Document append bootstrap sequence

docs/asset-resolution-re.md

@@ -222,6 +222,28 @@ scene-local numeric addressing mode.
    the earlier pointer in the native loop; no base/append name replacement occurs. Native extracts the
    selector with arithmetic `SAR 24`; the port rejects sign-bit selectors rather than guessing behavior for
    ids that would index before AGE's mount table.
+
+   **Append bootstrap/data sequence (static content verified 2026-07-24; native launch boundary open).**
+   Installed `APPEND01` contains 81 records, including 39 SYS4 scripts. Record zero is
+   `$1$AUTORUN.BIN` (`0x01000000`), a clean 43-instruction script. Its first 22 instructions call packed
+   records `0x01000001..0x01000016` in exact order: append fragments for EBINIT, CNINIT, ITINIT, SKINIT,
+   ILINIT, AFINIT, TRINIT, MAINIT, ALINIT, CDINIT2, MPINIT, LAINIT, OBINIT, STINIT2, RTINIT, CGINIT,
+   SPINIT, CTINIT, CVINIT, CIINIT, VIINIT, and SCINIT. It then marks append state and installs
+   `$1$CCINIT.BIN` at `0x01000017`, `$1$SCJUMP.BIN` at `0x01000018`, and the packed
+   READY/CLOSE/ROUND and message handlers through `0x01000029` into existing dispatch globals. The
+   called INIT fragments populate references to the append graphics and six append scenario scripts.
+
+   These INIT fragments are additive bytecode, not same-name catalog overlays. In particular,
+   `$1$EBINIT.BIN` (`0x01000001`) writes directly into the established EBINIT global arrays and adds
+   sparse unit-definition rows 81 and 900..905; `$1$CNINIT.BIN` adds their display names and voice-family
+   mappings. Mounting an AAI therefore only makes its packed records addressable. Executing its AUTORUN
+   is the separate operation that materializes append data and registers append control flow.
+
+   The base/loose script corpus contains no reference to packed id `0x01000000`. The shipped game must
+   therefore enter the append AUTORUN outside the visible base script call graph, but the exact native
+   launcher and its ordering relative to SYSTEM4/INIT2 have not yet been reversed. The current port can
+   resolve and execute append scripts when given their packed ids, but natural SYSTEM4 boot does not yet
+   launch mounted AUTORUNs. Do not treat VFS-B mount completion as append gameplay/bootstrap completion.
 3. **AGF decoder (VFS-C DONE).** `Age.Engine/Sys4/AgfDecoder.cs` decodes an opened AGF payload directly
    to a tightly packed, top-down width/height + RGBA8 surface. The MIT-licensed GARbro
    `ArcFormats/Eushully/ImageAGF.cs` provides a compact reference: `ACGF` (or zero) signature, type 1/2,

docs/engine-re.md

@@ -2172,6 +2172,16 @@ The callers pass their operands unchanged: `script_frame_load_resource@0x40e980`
 fetches operand 1 and immediately forwards it to that helper. Thus scene-local and raw-fallback are not
 native modes: ordinary resource operands are already universal packed SYS4INI/AAI ids.
 
+**Unresolved append execution boundary (2026-07-24).** Static inspection now separates catalog mount
+from append initialization. Installed selector 1 record zero is `$1$AUTORUN.BIN` at packed id
+`0x01000000`; it calls the 22 append INIT fragments at `0x01000001..0x01000016`, then installs append
+dispatch scripts/resources. No base or loose script contains a call to `0x01000000`, so append startup is
+owned outside the visible base-script graph. The native function that chooses and launches mounted
+AUTORUN records, and its exact ordering relative to SYSTEM4/INIT2, remain unnamed/unproven. A follow-up
+should trace script-frame creation for packed id `0x01000000` during cold boot, then rename/comment and
+save the responsible `/v2` function. Until then, “AAI mounted” must not be used as evidence that append
+INIT deltas ran.
+
 SC0010 supplies a clean corpus proof outside SC0000's base-zero coincidence. Its `set-texture 0x21` must
 open raw entry `0x21` (`SO013A.AGF`); adding SC0010's catalog position `0x11e` instead selects unrelated
 `COL0023.OGG`. Its `play-voice 0x120/0x121/0x122` operands directly select

docs/name-resolution.md

@@ -724,6 +724,16 @@ The v1 map labels *shapes and tables*; the next increments add *meaning*, cheape
    known value in-game (take damage, gain XP), watch which global moves → definitive
    `field@X = "HP"`. Reserve for the fields that matter; this is the last mile.
 
+**Append semantic-coverage caveat (2026-07-24).** The current `paths.scripts()` corpus and
+`extract_init.py` resolution path include DATA1 plus loose root overrides, but not selector-keyed AAI
+records. Consequently generated `build/data/EBINIT.json` describes the base/loose EBINIT only. Installed
+`$1$AUTORUN.BIN` calls additive append INIT fragments; `$1$EBINIT.BIN` adds unit rows 81 and 900..905 to
+the same global schema, and `$1$CNINIT.BIN` supplies the companion names/voice families. A future append
+semantic pass should enumerate packed scripts from the runtime catalog, preserve `(pack selector, raw
+index)` provenance, extract each INIT fragment with the existing schemas, and merge base/append assignments
+only after the native AUTORUN ordering is proven. The AAI format and verified internal call sequence are
+canonical in `docs/asset-resolution-re.md`.
+
 Re-run `tools/global_map.py` after each increment; `sys4load` picks up the new labels
 automatically (it reads `build/global-var-map.json` at load).
 

docs/phase-b-framework.md

@@ -90,6 +90,14 @@ coverage is 100% for all 23 data initializers, CALCARR, and TUNE; the remaining
 SYSTEM4-rooted path visible and interactive in Godot, then investigate only the gaps actually reached on
 that route instead of treating every static gap as a prerequisite.
 
+**Append boot caveat (2026-07-24).** The sequence and coverage above describe only the base/loose script
+graph. Mounted `APPEND01` has a separate `$1$AUTORUN.BIN` at packed id `0x01000000`; that script calls 22
+append INIT deltas and registers the append's class-change, SCJUMP, message, stage, and scenario resources.
+The base corpus never references that packed id, and natural port boot currently mounts the catalog without
+executing AUTORUN. Stage B2 is therefore not append-complete until native RE identifies the engine-owned
+launch boundary and the port reproduces its ordering. The verified append-internal sequence and remaining
+native question are canonical in `docs/asset-resolution-re.md` and `docs/engine-re.md`.
+
 **Godot root landing (2026-07-20).** The no-argument Godot/run-godot path now starts SYSTEM4 directly and
 does not apply the direct-SC0000 layout/surface bootstrap or the diagnostic `--boot` prefix. A windowed run
 reaches and renders TITLE using SYSTEM4-owned retained state. A real-script integration test drives TITLE's
@@ -316,6 +324,9 @@ The boot path must cover two existing categories:
 - System/session initialization currently approximated by `INITCONFIG`, `INIT2`, and `INIT`, including
   host-visible side effects that `CaptureHost` discards.
 - Game-data initialization represented by the `*INIT` family used by the headless boot/session tools.
+- Mounted append initialization: execute each native-selected packed AUTORUN at the proven boot boundary,
+  preserving base-versus-append order and provenance rather than treating same-suffix INIT fragments as
+  filename replacements.
 
 Completion evidence: