Extract complete owned game content and prepare HUDs and customisation during setup

docs/setup-content.md

@@ -0,0 +1,63 @@
+# Setup content ownership
+
+Setup owns extraction and preparation. Features must read installed asset paths;
+private development launchers and environment overrides are not installation steps.
+
+The selected owned game tree is extracted into `assets/private/original` before
+runtime conversion. All EB BIG v3 and BIG4/BIGF banks are decoded, including nested
+audio banks, and loose files are copied. Each bank has its own namespace so two
+archives with the same member name cannot overwrite each other. The private
+`original/manifest.json` records source archive hashes, member names, output sizes
+and decoded hashes. Repeating this extraction verifies and reuses matching files.
+Unsafe paths, ambiguous names and unsupported archive formats fail explicitly.
+The installation retains this source cache; temporary map conversion files are
+still removed after successful preparation.
+
+| Runtime content | Setup owner |
+| --- | --- |
+| Stock animation banks, action/motion/camera graphs, gestures, input and recipes | Stock BIG and loose animation extraction |
+| Physics, difficulty, scoring and other VLT tuning; skeleton metadata | VLT and physics-skeleton converters |
+| Skater mesh, textures and authored character lighting | Character and lighting converters |
+| Resident character choices, original textures, tattoos and native presets | `prepare_customisation.py` using existing CAC converters |
+| Original trickdisplay actions, shapes and bitmap fonts | `prepare_hud.py` |
+| Original session-marker geometry, labels and Xbox button images | `extract_session_marker.py` using the vendored toolkit |
+| Retail skies, render/exposure settings, travel destinations and foliage | Existing environment converters |
+| Authored movable-object models and placement | DMO catalog and per-map conversion |
+| Every disc district map, textures, collision and retained extensions | Existing map jobs |
+
+The final `runtime_content` check verifies manifests and referenced files,
+including HUD RGBA lengths, character scene/texture dependencies, lighting,
+per-map skies and movable objects. It writes `private/content-manifest.json`.
+Only after this check and the existing runtime asset checks pass does setup
+publish `installation.json` and report success. CAC conversion errors now stop
+setup rather than publishing an incomplete library.
+
+Extraction is not a claim of full engine support for every original format.
+Unported audio/frontend data remains in the indexed source cache. The ocean PCA
+table is executable-resident: its existing converter accepts a hash-verified
+mapped TU3 image, which ordinary disc setup does not produce. The owned XEX is
+preserved, but that optional table still needs the mapped-image converter; the
+renderer retains its documented fallback when absent. User-authored animations
+and third-party mods are not disc assets and are not generated by extraction.
+
+Existing installations can add the original HUDs using the targeted
+[cache repair](hud-installation.md), or prepare only missing feature caches with
+the respective tools. Updating source code does not automatically rerun setup
+or replace an already installed package.
+
+## Offline validation
+
+The 2026-09-09 setup integration was checked without running the game, recomp,
+Steam or gameplay tests. Archive tests cover BIG4 RefPack payloads, nested banks,
+duplicate names, unsafe paths, reuse and repair. The owned source inventory reads
+51 top-level banks and identifies 28 nested EB banks. HUD installation tests cover
+missing/corrupt files and byte preservation; the vendored marker compiler produces
+the same 15 meshes and seven texture payloads as the prepared native overlay.
+The data-only original movie audit passes 1,800 frames. The existing owned CAC
+audit validates 480 models, 2,427 materials and 170 tattoos.
+The dependency validator also passes against 3,435 prepared runtime files assembled
+from the existing caches with a University map. The packaged setup worker passes
+data-only archive extraction and HUD installation checks; no setup GUI is launched.
+
+Full installation and GPU/gameplay behavior still require manual validation;
+prepared maps and dependencies were reused rather than rebuilding the installation.