docs: published team credits + archive context index

README gains "The team" -- the published VWE BattleTech credits roster (scan supplied July 2026) cross-referenced against the 1994-96 source in this tree; HISTORY.md links the podbay developer-script names to the credited team members. context/ adds the archive index README and its generator script. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-24 12:02:49 -05:00
parent bd082d8c4a
commit c26d7baf8d
4 changed files with 345 additions and 1 deletions
@@ -30,7 +30,9 @@ Geographic League, VWE's fiction). Pods booted via `BOOTPOD.BAT`, pulled
 game builds from the server share **`\\vgl_code\podbay`**, and each developer
 had a named update script: Chris, Gabe, Edo, Joanna, Jordan, Milo, Kiwi,
 Shroom, Splotch, Bernoulli, and Golden (the golden/release build, default
-game BT). The boot configuration documents the pod peripherals: Thrustmaster
+game BT). Several match the published team credits (see "The team" in
+[README.md](README.md)): Chris Brewer, Gabe Underwood, Joanna Mason, and
+Jordan Weisman. The boot configuration documents the pod peripherals: Thrustmaster
 controls, a 640x480x16 gauge display, a plasma display on COM2, intercom,
 and SVGA-or-NTSC main video output.

@@ -133,6 +133,51 @@ INI-style calibration files (`.XST/.CAM/.BAK`) defining viewing extents and
 camera offsets ("head offset") for the cockpit's main display, including a
 `[LAB_ONLY]` configuration.

+## The team
+
+From a published VWE BattleTech credits page (scan supplied to this archive,
+July 2026). The roster matches the 1994–1996 source in this tree — see the
+cross-references below the table.
+
+| Role | Name(s) |
+|------|---------|
+| Producer and Designer | Jordan Weisman |
+| Art Director | David McCoy |
+| Technical Director | J.M. Albertson |
+| Audio Director | Eric Huffman |
+| Corporate Director of Technology | Bill Redmann |
+| **Software Engineers** | |
+| — Framework and Simulation Design | J.M. Albertson |
+| — Secondary/Auxiliary Screens and Low Level I/O | Chris Brewer |
+| — Low Level I/O Design and Programming | Marek Ciolek |
+| — Framework and 3D Video Rendering | Greg Corson |
+| — Animation Simulations and Tools | Jerry Edsall |
+| — Macintosh Design and Programming | Garth Hermanson |
+| — Framework and 3D Audio System | Eric Huffman |
+| — Simulation Code and Cameras | Joanna Mason |
+| — Graphics Research and Art Tools | Ken Olsen |
+| — Simulation Code and 'Mech Internal Systems | Gabe Underwood |
+| **Artists & Animators** | |
+| — 3D Art and Animations | Tom Burlington, Duane Molitor, David McCoy, Lex Story |
+| — Allen Workshop 2D Art | Victor Bonilla, Tom Peters |
+| Software Tools Group Leader | Ken Olsen |
+| Sound Samples/Designs | Bing McCoy, Tom Effinger, Eric Huffman |
+
+Cross-references to this tree:
+
+- `// Author:` headers in `CODE/` name four of the credited engineers:
+  **J.M. Albertson** (MUNGA math/debug bricks — `LINE`, `SPHERE`, `DEBUG*`),
+  **Jerry Edsall** (`TOOL`, `FILEUTIL`, the BT/RP `*TOOL` modules),
+  **Ken Olsen** (`NAMELIST`, `NOTATION` template containers), and
+  **Eric Huffman** (`CSTR`, `MEMREG`, `SCHAIN`).
+- The pod-lab per-developer update scripts on the recovered developer drive
+  (see [HISTORY.md](HISTORY.md)) are named Chris, Gabe, Joanna, and Jordan —
+  matching **Chris Brewer**, **Gabe Underwood**, **Joanna Mason**, and
+  **Jordan Weisman**.
+- **Garth Hermanson**'s "Macintosh Design and Programming" credit fits the
+  venue side: the operator console the pods connect to was a Macintosh
+  application.
+
 ## Provenance

 - Copyright (C) 1994–1996 Virtual World Entertainment, Inc. All rights
@@ -0,0 +1,125 @@
+# Context index — all project documentation
+
+A single map of every hand-written `.md` in this repo, grouped by area with a
+one-line description and a link. Use it to find the right note without grepping.
+
+> **Scope:** project-authored docs only. ~70 vendored/third-party READMEs (the
+> DOSBox-X fork under [`emulator/src/`](../emulator/src/), SDL2, libpng,
+> libpdcurses, freetype) are intentionally omitted — they document upstream
+> libraries, not this project.
+
+> **Keeping this current:** the linked list below is generated. Run
+> `context/gen-index.sh` to check for drift (new/removed docs) and
+> `context/gen-index.sh --write` to regenerate it. Hand-written descriptions are
+> preserved across regenerations; only the block between the AUTOGEN markers is
+> touched, so edit descriptions freely — just keep them inside that block.
+
+---
+<!-- BEGIN AUTOGEN (context/gen-index.sh) -->
+
+## Orientation
+
+- [HISTORY.md](../HISTORY.md) — provenance of the recovered developer drive ("Glaze"/`sda4`) that sits alongside the release tree.
+- [README.md](../README.md) — repo overview: source + content for Tesla:BattleTech and Tesla:Red Planet (Release 4.10).
+
+## Emulator — plan, phases & operations
+
+- [emulator/ENV-VARS.md](../emulator/ENV-VARS.md) — environment variables for both the pod (game) and host (emulator).
+- [emulator/LAUNCH.md](../emulator/LAUNCH.md) — pod launch cheat-sheet (all commands, non-elevated PowerShell).
+- [emulator/PHASE0-RESULTS.md](../emulator/PHASE0-RESULTS.md) — Phase 0: baseline DOS boot test (complete).
+- [emulator/PHASE1-RESULTS.md](../emulator/PHASE1-RESULTS.md) — Phase 1: interface discovery via a VPX link-adapter logging build (complete).
+- [emulator/PHASE2-PROGRESS.md](../emulator/PHASE2-PROGRESS.md) — Phase 2: boot-protocol emulation — handshake, i860 download, FIFO transport.
+- [emulator/PHASE3-PROGRESS.md](../emulator/PHASE3-PROGRESS.md) — Phase 3: render backend (3a/3b/3c command decode + bridge).
+- [emulator/PLAN.md](../emulator/PLAN.md) — master implementation plan for running unported DOS BattleTech/Red Planet under VPX emulation.
+
+## Emulator — subsystems
+
+- [emulator/CAMERA-REVIEW-NOTES.md](../emulator/CAMERA-REVIEW-NOTES.md) — how the games did Live Cam & Mission Review (spool replay, host roles).
+- [emulator/GAUGE-NOTES.md](../emulator/GAUGE-NOTES.md) — the cockpit gauge / secondary-display path (5 mono MFDs + color radar).
+- [emulator/NET-NOTES.md](../emulator/NET-NOTES.md) — networking subsystem recon & bring-up plan for pod boot/mesh.
+- [emulator/RENDER-HARNESS.md](../emulator/RENDER-HARNESS.md) — FLYK + the VWETEST diagnostic suite as a render harness.
+- [emulator/RENDERER-COLLAB.md](../emulator/RENDERER-COLLAB.md) — shared working log for the two renderer efforts (VPX/Division backend).
+- [emulator/RIO-NOTES.md](../emulator/RIO-NOTES.md) — RIO cockpit-controls passthrough tuning (COM1 input board).
+- [emulator/SOUND-NOTES.md](../emulator/SOUND-NOTES.md) — audio subsystem recon & plan (AWE32/SOS clock, faithful bring-up).
+- [emulator/VDB-NOTES.md](../emulator/VDB-NOTES.md) — the VWE Video Distribution Board: one framebuffer → six cockpit displays.
+
+## Emulator — deployment & ports
+
+- [emulator/DEPLOYMENT-PLAN.md](../emulator/DEPLOYMENT-PLAN.md) — network-agnostic pod-bay deployment (pcap bridge, two-IP design, mesh).
+- [emulator/EGRESS-HOLD-FIX-PLAN.md](../emulator/EGRESS-HOLD-FIX-PLAN.md) — egress-hold / floor-lighting investigation (CLOSED, won't-fix; findings kept).
+- [emulator/XP-PORT-PLAN.md](../emulator/XP-PORT-PLAN.md) — one archive from Windows XP → Windows 11 (back-burnered fleet plan).
+
+## Emulator — devices & support files
+
+- [emulator/deploy/README.md](../emulator/deploy/README.md) — install-side artifacts for the self-contained, air-gapped pod install.
+- [emulator/net-boot/README.md](../emulator/net-boot/README.md) — files the pod mounts as `D:` when booting the networked path.
+- [emulator/pod-launch/README.md](../emulator/pod-launch/README.md) — the supervising launch entry-point for both DOSBox titles.
+- [emulator/rio-firmware/README.md](../emulator/rio-firmware/README.md) — RIO cockpit I/O board firmware dump (v4.2).
+- [emulator/rio-firmware/RIOv4_2-ANALYSIS.md](../emulator/rio-firmware/RIOv4_2-ANALYSIS.md) — RIO v4.2 firmware RE: the protocol-wedge analysis.
+- [emulator/roms/README.md](../emulator/roms/README.md) — card ROM dumps (AWE32 1MGM sample ROM, etc.).
+- [emulator/vpx-device/README.md](../emulator/vpx-device/README.md) — VPX + AWE32 emulated-hardware sources for the DOSBox-X integration.
+- [emulator/vpx-device/serialport/README.md](../emulator/vpx-device/serialport/README.md) — modified DOSBox-X serial passthrough (RIO latency options).
+
+## Emulator — VelociRender firmware decompilation
+
+- [emulator/firmware-decomp/FPGA-RECONSTRUCTION.md](../emulator/firmware-decomp/FPGA-RECONSTRUCTION.md) — reconstructing the VelociRender in hardware (FPGA design note).
+- [emulator/firmware-decomp/GPU-RETARGET.md](../emulator/firmware-decomp/GPU-RETARGET.md) — GPU-compute retarget: the DOSBox-renderer shipping path.
+- [emulator/firmware-decomp/HARDWARE-ARCHITECTURE.md](../emulator/firmware-decomp/HARDWARE-ARCHITECTURE.md) — the card's hardware architecture, reconstructed for emulation (+ photo inventory).
+- [emulator/firmware-decomp/IG-SHADING-MODEL.md](../emulator/firmware-decomp/IG-SHADING-MODEL.md) — the IG-board shading model, ground truth distilled from shipped libDPL.
+- [emulator/firmware-decomp/IGC-ENCODING-DERIVATION.md](../emulator/firmware-decomp/IGC-ENCODING-DERIVATION.md) — IGC instruction-word encoding derived from EOF.C ↔ EOF.S (Tier-1 decoder).
+- [emulator/firmware-decomp/M4-LIVE-SEAM.md](../emulator/firmware-decomp/M4-LIVE-SEAM.md) — M4: the live DOSBox seam design note.
+- [emulator/firmware-decomp/M4B-RESULTS.md](../emulator/firmware-decomp/M4B-RESULTS.md) — M4b: offline end-to-end renderer-chain results.
+- [emulator/firmware-decomp/M5-TEXTURING.md](../emulator/firmware-decomp/M5-TEXTURING.md) — M5: faithful texturing, the last mile to recognizable frames.
+- [emulator/firmware-decomp/MICROCODE-DECODE-NOTES.md](../emulator/firmware-decomp/MICROCODE-DECODE-NOTES.md) — PXPL5 IGC micro-code decode working notes (ground/sky path).
+- [emulator/firmware-decomp/PVISION-IMPLEMENTATION-GUIDE.md](../emulator/firmware-decomp/PVISION-IMPLEMENTATION-GUIDE.md) — implementing IR / "Predator" vision in a VelociRender renderer.
+- [emulator/firmware-decomp/README.md](../emulator/firmware-decomp/README.md) — decompilation reference hub (make this the authoritative VelociRender answer).
+- [emulator/firmware-decomp/i860-encoding.md](../emulator/firmware-decomp/i860-encoding.md) — i860 instruction encoding, validated against our own object files.
+
+## Emulator — render bridge
+
+- [emulator/render-bridge/COCKPIT-CAGE-NOTES.md](../emulator/render-bridge/COCKPIT-CAGE-NOTES.md) — cockpit cage, glances, and the "black rear view" (canopy/twist forensics).
+- [emulator/render-bridge/DEATH-SEQUENCE-NOTES.md](../emulator/render-bridge/DEATH-SEQUENCE-NOTES.md) — death-sequence camera findings.
+
+## dpl3-revive — DPL3 renderer port & format specs
+
+- [dpl3-revive/README.md](../dpl3-revive/README.md) — porting the VWE DPL3 renderer (BattleTech / Red Planet).
+- [dpl3-revive/patha/CAPTURE.md](../dpl3-revive/patha/CAPTURE.md) — capturing real FLYK.EXE link traffic (Path A validation).
+- [dpl3-revive/spec/B2Z_FORMAT.md](../dpl3-revive/spec/B2Z_FORMAT.md) — the DIV-BIZ2 (`.B2Z`/`.V2Z`) binary geometry format.
+- [dpl3-revive/spec/MAP_FORMAT.md](../dpl3-revive/spec/MAP_FORMAT.md) — `.MAP` game maps and `.MOD` game objects (playable worlds).
+- [dpl3-revive/spec/SCN_FORMAT.md](../dpl3-revive/spec/SCN_FORMAT.md) — `.SCN` scene format (from FLYK.C).
+- [dpl3-revive/spec/SPL_FORMAT.md](../dpl3-revive/spec/SPL_FORMAT.md) — `.SPL` camera-path spline format (from SPLINE.C).
+- [dpl3-revive/spec/SVT_FORMAT.md](../dpl3-revive/spec/SVT_FORMAT.md) — `.SVT` texture format (from DPL_LOAD.C `load_svt()`).
+- [dpl3-revive/spec/VELOCIRENDER_PROTOCOL.md](../dpl3-revive/spec/VELOCIRENDER_PROTOCOL.md) — the VelociRender wire protocol (run the original binary unmodified).
+
+## restoration — scene re-renders
+
+- [restoration/README.md](../restoration/README.md) — modern re-renderings of the Division dVS scenes recovered from the Glaze drive.
+
+## restoration — RIO firmware & hardware
+
+- [restoration/rio-firmware/README.md](../restoration/rio-firmware/README.md) — RIO board firmware (owner-facing entry point).
+- [restoration/rio-firmware/RIOv4_2-ANALYSIS.md](../restoration/rio-firmware/RIOv4_2-ANALYSIS.md) — RIO v4.2 firmware RE: protocol-wedge analysis.
+- [restoration/rio-firmware/wedge-explained.md](../restoration/rio-firmware/wedge-explained.md) — plain-language "why the stick died mid-battle" for pod owners.
+- [restoration/rio-hardware/README.md](../restoration/rio-hardware/README.md) — RIO cockpit hardware: boards, schematics, GAL dump.
+- [restoration/rio-hardware/display-board-1408.md](../restoration/rio-hardware/display-board-1408.md) — Display Board 1408 outputs and what the RIO shows on it.
+- [restoration/rio-hardware/gal/README.md](../restoration/rio-hardware/gal/README.md) — U7 GAL20V8A decode: the recovered RIO memory map.
+
+## restoration — source410 reconstruction
+
+- [restoration/source410/BT/BTCNSL.NOTES.md](../restoration/source410/BT/BTCNSL.NOTES.md) — BTCNSL reconstruction notes.
+- [restoration/source410/BT/BTPLAYER.NOTES.md](../restoration/source410/BT/BTPLAYER.NOTES.md) — BTPLAYER reconstruction notes (ctor/Make/experience level).
+- [restoration/source410/BT/BTSCNRL.NOTES.md](../restoration/source410/BT/BTSCNRL.NOTES.md) — BTSCNRL reconstruction notes.
+- [restoration/source410/BT/MECH-LAYOUT.md](../restoration/source410/BT/MECH-LAYOUT.md) — MECH.HPP staging worksheet (the mech-family working ledger).
+- [restoration/source410/BT/MECH.NOTES.md](../restoration/source410/BT/MECH.NOTES.md) — MECH.CPP/.HPP reconstruction notes.
+- [restoration/source410/BT/MECHSUB.NOTES.md](../restoration/source410/BT/MECHSUB.NOTES.md) — MECHSUB reconstruction notes.
+- [restoration/source410/BT/NAMEFILT.NOTES.md](../restoration/source410/BT/NAMEFILT.NOTES.md) — NAMEFILT reconstruction notes.
+- [restoration/source410/BT/SENSOR.NOTES.md](../restoration/source410/BT/SENSOR.NOTES.md) — SENSOR reconstruction notes.
+- [restoration/source410/BT/SEQCTL.NOTES.md](../restoration/source410/BT/SEQCTL.NOTES.md) — SEQCTL reconstruction notes.
+- [restoration/source410/BT/STAGED-HEADERS.NOTES.md](../restoration/source410/BT/STAGED-HEADERS.NOTES.md) — the 13 headers that closed the tree's compile (shared notes).
+- [restoration/source410/BT_L4/BTL4.NOTES.md](../restoration/source410/BT_L4/BTL4.NOTES.md) — BTL4.CPP reconstruction notes (launch path).
+- [restoration/source410/BT_L4/BTL4APP.NOTES.md](../restoration/source410/BT_L4/BTL4APP.NOTES.md) — BTL4APP.CPP reconstruction notes (12/12 functions).
+- [restoration/source410/MUNGA/ALARM.NOTES.md](../restoration/source410/MUNGA/ALARM.NOTES.md) — ALARM.HPP reconstruction notes.
+- [restoration/source410/MUNGA/BACKFILLS.NOTES.md](../restoration/source410/MUNGA/BACKFILLS.NOTES.md) — engine header backfills, shared per-file evidence.
+- [restoration/source410/MUNGA/VDATA.NOTES.md](../restoration/source410/MUNGA/VDATA.NOTES.md) — VDATA.HPP: the first engine-side header backfill.
+- [restoration/source410/README.md](../restoration/source410/README.md) — overview of the missing-source reconstruction effort.
+<!-- END AUTOGEN -->
@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+#
+# gen-index.sh — keep context/README.md's documentation index in sync with the repo.
+#
+#   context/gen-index.sh            # CHECK: report drift, exit 1 if the index is stale
+#   context/gen-index.sh --write    # rewrite the AUTOGEN block in context/README.md
+#   context/gen-index.sh --help
+#
+# Only the region between the AUTOGEN markers in context/README.md is touched;
+# the hand-written header/scope note above it is left alone. Descriptions that
+# already exist in the index are PRESERVED (matched by path); files that are new
+# to the tree get a stub description pulled from their first heading/lead line,
+# ready for you to polish. Vendored/third-party trees are excluded, matching the
+# index's stated scope.
+#
+# Run it from anywhere; it locates the repo via this script's own path.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+INDEX="context/README.md"
+BEGIN='<!-- BEGIN AUTOGEN (context/gen-index.sh) -->'
+END='<!-- END AUTOGEN -->'
+
+MODE="check"
+case "${1:-}" in
+  --write) MODE="write" ;;
+  ""|--check) MODE="check" ;;
+  -h|--help) sed -n '3,17p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  *) echo "unknown option: $1 (try --help)" >&2; exit 2 ;;
+esac
+
+# --- ordered sections: a path lands in the FIRST section whose regex matches ---
+TITLES=(
+  "Orientation"
+  "Emulator — plan, phases & operations"
+  "Emulator — subsystems"
+  "Emulator — deployment & ports"
+  "Emulator — devices & support files"
+  "Emulator — VelociRender firmware decompilation"
+  "Emulator — render bridge"
+  "dpl3-revive — DPL3 renderer port & format specs"
+  "restoration — scene re-renders"
+  "restoration — RIO firmware & hardware"
+  "restoration — source410 reconstruction"
+)
+REGEX=(
+  '^(README|HISTORY)\.md$'
+  '^emulator/(PLAN|PHASE[0-9].*|LAUNCH|ENV-VARS)\.md$'
+  '^emulator/(VDB-NOTES|GAUGE-NOTES|SOUND-NOTES|NET-NOTES|RIO-NOTES|CAMERA-REVIEW-NOTES|RENDER-HARNESS|RENDERER-COLLAB)\.md$'
+  '^emulator/(DEPLOYMENT-PLAN|XP-PORT-PLAN|EGRESS-HOLD-FIX-PLAN)\.md$'
+  '^emulator/(vpx-device|pod-launch|net-boot|deploy|roms|rio-firmware)/'
+  '^emulator/firmware-decomp/'
+  '^emulator/render-bridge/'
+  '^dpl3-revive/'
+  '^restoration/README\.md$'
+  '^restoration/rio-'
+  '^restoration/source410/'
+)
+
+# --- the doc set (same filter as the index scope) ---
+list_docs() {
+  git ls-files '*.md' '*.MD' \
+    | grep -viE '/(vs|libpng|libpdcurses|sdl2|sdl2net|freetype)/' \
+    | grep -viE '^emulator/src/(NOTES|\.github)/' \
+    | grep -vxF "$INDEX" \
+    | sort
+}
+
+# --- preserved descriptions: parse the current AUTOGEN block, path -> desc ---
+declare -A DESC
+if [ -f "$INDEX" ]; then
+  in_block=0
+  while IFS= read -r line; do
+    [ "$line" = "$BEGIN" ] && { in_block=1; continue; }
+    [ "$line" = "$END" ] && { in_block=0; continue; }
+    [ "$in_block" = 1 ] || continue
+    case "$line" in
+      "- ["*"](../"*")"*)
+        rest="${line#*](../}"; path="${rest%%)*}"; after="${rest#*)}"
+        after="${after#"${after%%[![:space:]]*}"}"   # ltrim
+        after="${after#—}"; after="${after#-}"        # drop leading em/hyphen dash
+        after="${after#"${after%%[![:space:]]*}"}"    # ltrim again
+        [ -n "$after" ] && DESC["$path"]="$after"
+        ;;
+    esac
+  done < "$INDEX"
+fi
+
+# --- stub description for a file new to the index ---
+extract_desc() {
+  local f="$1" raw
+  raw="$(awk 'NR>1 && $0 !~ /^#/ && $0 !~ /^---/ && $0 !~ /^>/ && $0 !~ /^[[:space:]]*$/ {print; exit}' "$f")"
+  raw="$(printf '%s' "$raw" | sed -E 's/[`*]//g; s/[[:space:]]+/ /g; s/^ +//; s/ +$//')"
+  [ "${#raw}" -gt 140 ] && raw="${raw:0:137}..."
+  [ -n "$raw" ] && printf '%s' "$raw" || printf '(no description — add one)'
+}
+
+# --- build the block body on stdout ---
+gen_body() {
+  local docs; docs="$(list_docs)"
+  local -a remaining; mapfile -t remaining <<< "$docs"
+
+  emit_section() {
+    local title="$1" re="$2"; shift 2
+    local -a kept=() matched=()
+    local p
+    for p in "${remaining[@]}"; do
+      [ -z "$p" ] && continue
+      if [[ "$p" =~ $re ]]; then matched+=("$p"); else kept+=("$p"); fi
+    done
+    remaining=("${kept[@]}")
+    [ "${#matched[@]}" -eq 0 ] && return 0
+    printf '\n## %s\n\n' "$title"
+    for p in "${matched[@]}"; do
+      local d="${DESC[$p]:-}"; [ -z "$d" ] && d="$(extract_desc "$p")"
+      printf -- '- [%s](../%s) — %s\n' "$p" "$p" "$d"
+    done
+  }
+
+  local i
+  for i in "${!TITLES[@]}"; do
+    emit_section "${TITLES[$i]}" "${REGEX[$i]}"
+  done
+
+  # anything unmatched still shows up — never silently dropped
+  local -a leftover=()
+  local p
+  for p in "${remaining[@]}"; do [ -n "$p" ] && leftover+=("$p"); done
+  if [ "${#leftover[@]}" -gt 0 ]; then
+    printf '\n## Uncategorized\n\n'
+    printf '%s\n' '> New locations the section rules do not cover yet — assign them in gen-index.sh.'
+    printf '\n'
+    for p in "${leftover[@]}"; do
+      local d="${DESC[$p]:-}"; [ -z "$d" ] && d="$(extract_desc "$p")"
+      printf -- '- [%s](../%s) — %s\n' "$p" "$p" "$d"
+    done
+  fi
+}
+
+# --- current block body (between the markers) on stdout ---
+current_body() {
+  awk -v b="$BEGIN" -v e="$END" '
+    $0==b {inb=1; next} $0==e {inb=0} inb==1 {print}
+  ' "$INDEX"
+}
+
+grep -qF "$BEGIN" "$INDEX" && grep -qF "$END" "$INDEX" || {
+  echo "error: AUTOGEN markers not found in $INDEX" >&2; exit 2; }
+
+NEW="$(gen_body)"
+
+if [ "$MODE" = "check" ]; then
+  if diff <(current_body) <(printf '%s\n' "$NEW") >/dev/null; then
+    echo "context index is current ($(list_docs | grep -c . ) docs)."
+    exit 0
+  fi
+  echo "context index is STALE — run: context/gen-index.sh --write" >&2
+  echo "--- diff (current -> generated) ---" >&2
+  diff <(current_body) <(printf '%s\n' "$NEW") >&2 || true
+  exit 1
+fi
+
+# MODE=write: splice NEW between the markers, leave everything else intact
+tmp="$(mktemp)"
+awk -v b="$BEGIN" -v e="$END" -v body="$NEW" '
+  $0==b {print; print body; skip=1; next}
+  $0==e {skip=0; print; next}
+  skip!=1 {print}
+' "$INDEX" > "$tmp"
+mv "$tmp" "$INDEX"
+echo "wrote $INDEX ($(list_docs | grep -c . ) docs)."