docs: fix runtime claim, stale header notes and dangling doc references

- ovrplugin_shim.h: runtime on Steam Frame is SteamVR (HOST.md), not Monado;
  drop the "Status: scaffold" line and the note that SetupLayer /
  GetLayerTexture2 await a 128-byte desc (implemented against the 108-byte
  ovrpLayerDesc); point RE-NOTES/SHIM-SCOPE at docs/research/.
- lever2-detect-skip-black-handoff.md lives in docs/research/, not analysis/.
- References to unpublished RE notes now say so instead of naming files that
  are not in the repo.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/handoffs/HANDOFF-2026-06-26-reproject.md

@@ -58,7 +58,7 @@ now a SAFETY NET for render-ahead's old instability (detect+hide any black inste
 
 ## Game perf RE (done this session) — one new lever, several myths busted
 Static RE of the GAME binary `dump/apk_libs/lib/arm64-v8a/libUE4.so` via capstone. Full report:
-`analysis/game-perf-RE.md`; memory `game-perf-RE-findings`. This REPLACES the behavioral
+private RE notes (not published); memory `game-perf-RE-findings`. This REPLACES the behavioral
 inferences in `game-doesnt-drive-dynamic-perf-from-feed` with code proof:
 - **No game-side dynamic-FFR loop exists** — `SetTiledMultiRes{Level,Dynamic}` args are config
   bytes (`SetTiledMultiResDynamic(Settings.byte[0x11d])`), never compared to GPU time/metrics. So

docs/handoffs/HANDOFF-2026-06-26-skipblack.md

@@ -3,7 +3,7 @@
 Continuation of `HANDOFF-2026-06-26.md` (morning). Branch `latency-perffix-copyring`.
 This session built + ran **Lever 2 step 1 (instrument-only black-frame detector)** and
 validated the signal is real but coarse. Detailed finding in auto-memory
-`skipblack-posthitch-signal-validated`. Design: `analysis/lever2-detect-skip-black-handoff.md`.
+`skipblack-posthitch-signal-validated`. Design: `docs/research/lever2-detect-skip-black-handoff.md`.
 
 ## TL;DR — the post-hitch black signal is REAL but needs a tighter gate + frame-accurate proof
 Added `debug.re4vr.skipblack 1` (instrument-only): after a HITCH (dt>20ms), flag the next

docs/handoffs/HANDOFF-2026-06-26.md

@@ -19,7 +19,7 @@ frame-drop under load**, NOT a shim bug:
 - Load-gated: bridge (sparse) never blacks; house/dense geometry blacks; worse while casting.
 
 ## NEXT TASK — Lever 2: detect the bad frame + reproject
-Full design in `analysis/lever2-detect-skip-black-handoff.md`. Idea: when UE hands us a
+Full design in `docs/research/lever2-detect-skip-black-handoff.md`. Idea: when UE hands us a
 truncated/black frame, DON'T present it — re-present the last-good eye image with the
 current pose so the OpenXR compositor reprojects (timewarp) instead of showing black.
 - **Bad-frame signal:** start with the **post-hitch heuristic** (the truncated frame is the

docs/research/render-submit-sync-design.md

@@ -1,6 +1,6 @@
 # Render-submit race — fix design (#2)
 
-Pairs with `render-submit-sync-RE.md` (subagent RE of UE/OVRPlugin submit timing).
+Pairs with private RE notes on UE/OVRPlugin submit timing (not published).
 Status: design draft; final approach (A vs B) gated on the RE findings.
 
 ## Confirmed mechanism
@@ -52,7 +52,7 @@ the submit without a hook), adds latency/stalls. Not recommended.
 **D. Use an ovrp call UE makes around submit as the sync point** — only viable if the RE
 finds UE invokes an OVRPlugin entry point right after the render submit. Unlikely; → RE.
 
-## RE outcome (`render-submit-sync-RE.md`) → Option A is feasible
+## RE outcome (private RE notes, not published) → Option A is feasible
 - **Original = zero Vulkan sync, definitively:** libOVRPlugin imports *no* `vk*` (only
   `vrapi_*`); libvrapi imports no `vk*` either. The compositor is a separate system
   process; swapchains are cross-process system-owned (`vrapi_CreateTextureSwapChainCrossProcess`).

shim/include/ovrplugin_shim.h

@@ -2,18 +2,19 @@
  *
  * Goal: a drop-in replacement libOVRPlugin.so that re-exports the ovrp_* symbols
  * RE4 VR (com.Armature.VR4, OVRPlugin 1.51 / pkg 19.0.0.449.531) calls, backed by
- * OpenXR (Monado) on Steam Frame instead of Meta's libvrapi.so.
+ * OpenXR (SteamVR on Steam Frame — see HOST.md) instead of Meta's libvrapi.so.
  *
  * Provenance of each declaration:
  *   [VERIFIED]   struct size / arg shape confirmed from Ghidra decompilation of the
- *                actual binary (see analysis/ovrp_decomp.txt, RE-NOTES.md).
+ *                actual binary (decomp output is private, not published;
+ *                findings summarized in docs/research/RE-NOTES.md).
  *   [HEADER]     taken from public OVRPlugin.cs @ v1.51; layout trusted because the
  *                VERIFIED structs matched it byte-for-byte, but not independently
  *                re-confirmed against this binary yet.
  *   [TODO]       signature not yet finalized — placeholder, do not trust arg list.
  *
- * Status: scaffold. Base types + the fully-confirmed functions are real; the rest
- * of the ~239-function surface (analysis/shim_surface.txt) is still to be filled.
+ * This header declares the base types and the functions the shim implements by hand;
+ * the rest of the export surface (analysis/shim_surface.txt) is generated stubs.
  */
 #ifndef OVRPLUGIN_SHIM_H
 #define OVRPLUGIN_SHIM_H
@@ -277,12 +278,11 @@ OVRP_EXPORT ovrpResult ovrp_IsPerfMetricsSupported(ovrpPerfMetrics metric, ovrpB
 OVRP_EXPORT ovrpResult ovrp_GetPerfMetricsFloat(ovrpPerfMetrics metric, float *outValue);
 OVRP_EXPORT ovrpResult ovrp_GetPerfMetricsInt(ovrpPerfMetrics metric, int *outValue);
 
-/* TODO: remaining ~225 of the 239-function surface; see analysis/shim_surface.txt.
- * Buckets (per SHIM-SCOPE.md): ~150 stub-to-constant (Media_, camera, perf,
- * boundary, handtracking, system-getters), ~45 mechanical (rest of tracking,
- * input, eye params), and the hard layer/swapchain set (SetupLayer,
- * CalculateEyeLayerDesc2, GetLayerTexture2) which need the 128-byte
- * ovrpLayerDesc reversed first. */
+/* The rest of the surface (analysis/shim_surface.txt; buckets per
+ * docs/research/SHIM-SCOPE.md) is stub-to-constant or declared alongside its
+ * implementation. The layer/swapchain set (SetupLayer, CalculateEyeLayerDesc2,
+ * GetLayerTexture2) is implemented in layers.c against the 108-byte ovrpLayerDesc
+ * above. */
 
 #ifdef __cplusplus
 }

shim/src/core.c

@@ -361,7 +361,8 @@ OVRP_EXPORT ovrpResult ovrp_GetGPUFrameTime(float *outGpuTimeMs) {
 
 /* Lever A — dynamic resolution. Previously stubbed Unsupported, leaving the game's preset
  * scale=1.0 (full res always). We return scale<1 under GPU pressure; the game self-downscales
- * its eye buffer (resolution = baseDensity * sqrt(scale)). See xr_runtime.c / game-perf-RE.md. */
+ * its eye buffer (resolution = baseDensity * sqrt(scale)). See xr_runtime.c; the game-side
+ * RE notes behind this are private (not published). */
 OVRP_EXPORT ovrpResult ovrp_GetAdaptiveGpuPerformanceScale2(float *outScale) {
     PT_FWD(ovrp_GetAdaptiveGpuPerformanceScale2, outScale);
     if (!outScale) return ovrpFailure_InvalidParameter;

shim/src/xr_runtime.c

@@ -260,7 +260,7 @@ static int submithook_level(void) {
  *   2 = (future) reproject: re-present the last-good eye image on a flagged frame.
  * Root cause is settled: UE renders a truncated (~28 vs ~198 draws) black frame under load;
  * the truncated frame is the RECOVERY frame following a stall, which we already detect as a
- * dt>20ms HITCH. See analysis/lever2-detect-skip-black-handoff.md. */
+ * dt>20ms HITCH. See docs/research/lever2-detect-skip-black-handoff.md. */
 static int skipblack_level(void) {
     int v = 0;
 #ifdef __ANDROID__