docs+build: hygiene pass — close leak risk, de-drift docs, fix build prereqs

Repo hygiene round following a full review. No shim behaviour changes.

Leak risk:
- .gitignore: ignore CLAUDE.md (personal assistant-lane config, was one
  `git add -A` away from a public commit) and scratch_obj/.

Docs vs. reality:
- shim/README.md: rewritten. It described a pre-implementation skeleton with
  "core fns are TODO stubs returning -1005", three mutually inconsistent stub
  counts, and four completed milestones listed as open. Now carries the verified
  breakdown: 438/438 exports = 371 generated stubs + 46 core + 7 layers + 2
  Vulkan queries + 12 passthru trampolines.
- TESTING.md: dropped the self-contradicting "NOT yet" block (5 of 6 items were
  done or misstated, and contradicted the same file 45 lines above). Path B now
  points at tools/desktop-harness, which exists, instead of the orphaned
  shim/tests/harness.c. Path A prereqs marked as the record they are.
- HOST.md: corrected the runtime assumption. The OpenXR runtime inside Lepton is
  SteamVR (vendor/etc/openxr/1/active_runtime.json -> vrclient.so), not Monado.
  Favourable: SteamVR emulates Oculus Touch by default and advertises the
  XR_FB_foveation family, so the existing input and foveation paths should carry
  over. The old "remaining unknowns" are resolved by Lepton's published source
  and replaced with the items to check before a first Frame boot.
- README.md: same runtime correction.
- docs/research/RECON.md: the four passages prescribing an entitlement
  NOP/stub/bypass are corrected in place rather than merely disclaimed by the
  top banner, which they contradicted.

Build correctness:
- shim/build_android.sh: missing patchelf is now fatal. It warned and exited 0,
  producing a .so that cannot resolve the OpenXR loader at runtime.
- scripts/fetch_deps.sh + packaging/build_openxr_loader.sh: pin the OpenXR and
  Vulkan header versions (were tracking `main`), overridable via OPENXR_TAG /
  VULKAN_HEADERS_TAG; require cmake for the loader build.
- packaging/steamframe_patches.sh: use the apktool.jar that fetch_deps.sh
  downloads. Its prereq check demanded an `apktool` binary on PATH that the
  documented setup never provides, so it could not run after a clean setup.
- shim/gen_stubs.sh: it reads all_exports.txt, not shim_surface.txt; comment and
  emitted banner corrected. stubs.c regenerated (banner line only).
- shim/src/core.c: split seven `if (out) ...; return ...;` one-liners. Host
  build now compiles with zero warnings, down from seven.

Verified: host build 0 warnings; gen_stubs.sh output identical on regeneration;
bash -n clean on all edited scripts; pinned header/tarball URLs return 200 and
the tag tarball extracts to the expected directory name.

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

packaging/steamframe_patches.sh

@@ -16,12 +16,22 @@
 #     in.apk  : shim-repacked APK            (default: out/re4vr-shim.apk)
 #     out.apk : patched output               (default: out/re4vr-steamframe.apk)
 #
-# Prereqs: apktool (https://apktool.org), plus the Android build-tools used by repack.sh.
+# Prereqs: tools/apktool.jar (scripts/fetch_deps.sh) or apktool on PATH, plus a JDK and
+# the Android build-tools used by repack.sh.
 # NOTE: prepared for the non-Quest bring-up; not yet validated on Steam Frame hardware.
 set -euo pipefail
 source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/_env.sh"
 [ -n "${BT:-}" ] && [ -d "$BT" ] || { echo "Android build-tools not found. Run scripts/fetch_deps.sh"; exit 1; }
-command -v apktool >/dev/null || { echo "apktool not found — install it (https://apktool.org) to run the smali/manifest patches"; exit 1; }
+# Prefer the apktool.jar that scripts/fetch_deps.sh downloads (same as inspect_manifest.sh);
+# fall back to an `apktool` wrapper on PATH.
+if [ -f "${APKTOOL_JAR:-}" ]; then
+  APKTOOL=("${JAVA_HOME:+$JAVA_HOME/bin/}java" -jar "$APKTOOL_JAR")
+elif command -v apktool >/dev/null; then
+  APKTOOL=(apktool)
+else
+  echo "apktool not found — run scripts/fetch_deps.sh (fetches tools/apktool.jar) or install"
+  echo "apktool on PATH (https://apktool.org) to run the smali/manifest patches"; exit 1
+fi
 
 IN="${1:-$PKG/out/re4vr-shim.apk}"
 OUT="${2:-$PKG/out/re4vr-steamframe.apk}"
@@ -54,7 +64,7 @@ rm -rf "$WORK"; mkdir -p "$WORK"
 DEC="$WORK/dec"
 
 echo "== apktool decode =="
-apktool d -f -o "$DEC" "$IN" >/dev/null
+"${APKTOOL[@]}" d -f -o "$DEC" "$IN" >/dev/null
 
 # Locate UE's GameActivity smali (ue4 or unreal namespace, across smali_classesN dirs).
 mapfile -t GA < <(find "$DEC" -path '*/com/epicgames/ue4/GameActivity.smali' \
@@ -90,7 +100,7 @@ if [ -f "$MAN" ]; then
 fi
 
 echo "== apktool build =="
-apktool b -o "$WORK/unsigned.apk" "$DEC" >/dev/null
+"${APKTOOL[@]}" b -o "$WORK/unsigned.apk" "$DEC" >/dev/null
 
 echo "== align + sign =="
 "$BT/zipalign" -f -p 4 "$WORK/unsigned.apk" "$WORK/aligned.apk"