Release 0.9.9: full Quaternius roster, docs, changelog, version, slimmer export filters and checksums

docs/blender-assets.md

@@ -142,11 +142,22 @@ render about 2.5 min.
 
 ## Characters
 
-All library variants, including the incoming Quaternius-derived base, share the
+All library variants share the
 [character and gear asset contract](architecture.md#character-and-gear-asset-contract):
-`npc_base` mesh node, required 13 core bones (optional extras allowed), five
-tint slots, +Z visual front, 24,000/24,000 character budget and the same 256²
-slot-map/AO rules. Role selection and look notes:
+`npc_base` mesh node, five tint slots, +Z visual front, 24,000/24,000 character budget and the
+same 256² slot-map/AO rules. The shipped roster is on the 62-joint Quaternius skeleton
+(ADR-0018); the procedural fallback built by `build --source procedural` keeps the 13 core bones.
+Both are accepted by `audit`, `inspect`, the runtime bone map and the tests.
+
+The three Quaternius sources (`casual`, `hoodie`, `worker`) live in
+`assets/models/blender_src/quaternius/` as build inputs. `build` (default
+`--source quaternius`) does a two-pass bake per character: a cached T-pose round trip that joins
+without welding, maps the upstream materials onto the five slots and unwraps the degenerate
+source UVs, then an arm-down rest bake exported with `export_apply=False`. The per-character slot
+map, triangle counts and measurements are in
+[`npc-model-sourcing.md#shipped-roster-099-owner-chose-the-full-swap`](npc-model-sourcing.md#shipped-roster-099-owner-chose-the-full-swap).
+
+Role selection and look notes (tint + gear now carry the role, not the mesh):
 
 | Character | `layer_for()` / look | Suggested roles | Preview gear |
 | --- | --- | --- | --- |
@@ -165,6 +176,11 @@ colour texture. The current `_apply_outfit_materials()` sets
 `albedo_color = WHITE` on any slot it does not recognise, and these keep their
 colour through that. When integrating, tint only the five contract slots.
 
+**Head gear fit.** Head gear is authored for the shipped Quaternius head:
+`HEAD_GEAR_SCALE = 0.64` (0.201 m base head against the 0.315 m procedural one) and
+`HEAD_GEAR_LIFT = 0.07` (its centre sits higher). The procedural fallback therefore wears slightly
+undersized caps — cosmetic and fallback-only.
+
 **Runtime tint notes (implemented).** Only the five contract slots are tinted;
 fixed detail materials keep their authored colour. On `npc_vest` the vest is the
 fixed `hivis` material and `cloth` is the undershirt, so the yellow override is

docs/development-status.md

@@ -34,11 +34,14 @@ and the active order/gaps in [`TODO.md`](../TODO.md).
 ## Known gaps
 
 - External first-time-player sessions and balance sweeps are not completed.
-- The Quaternius NPC base is wired for one character (`npc_casual`): arm-down rest, five tint
-  slots, unwrapped UVs, 62-joint rig at source proportions, Idle/Walk/Sit pose code, 6,206 tris.
-  The remaining `0.9.9` blocker is the owner face/silhouette decision
-  (`docs/screens/npc-face-gate/`); the full 12-role roster rollout is `0.9.10`. The other eleven
-  characters stay procedural with the MakeHuman head until that decision lands.
+- The Quaternius roster is shipped (`0.9.9`): all twelve characters are baked from the three CC0
+  sources (casual tee, hoodie, work clothes), 4,458–6,424 triangles each, 62-joint rig at source
+  proportions, arm-down rest, five tint slots, unwrapped UVs and baked 256² AO. The procedural
+  library and the MakeHuman head remain the tested fallback.
+- Roster silhouette variety is narrower than the procedural library (three meshes for twelve
+  roles, differentiated by tint and gear) until the modular part library is added.
+- Head gear is authored for the shipped Quaternius head; the procedural fallback therefore wears
+  slightly undersized caps. Cosmetic, fallback-only.
 - Accessibility/localization acceptance, target-hardware profiling, macOS
   signing/notarization and AI/storefront legal approval remain open.
 - Live 3D replay, recorded VO/music, more venues and seasonal content are future

docs/npc-model-sourcing.md

@@ -238,6 +238,47 @@ Two source quirks shaped the bake:
 
 The face and silhouette gate sheet is in [`screens/npc-face-gate/`](screens/npc-face-gate/README.md).
 
+## Shipped roster (0.9.9, owner chose the full swap)
+
+Every public character name is baked from one of the three CC0 sources. The build is
+`tools/blender_assets.py build` (default `--source quaternius`); the sources live in
+`assets/models/blender_src/quaternius/` and the geometry pipeline is two passes:
+
+1. `_quaternius_tpose_glb()` — import, drop the Icosphere helper, join **without welding**,
+   repoint the upstream materials onto the five tint slots, Smart-UV-unwrap + repack, export an
+   intermediate T-pose GLB. The round trip also normalises the mirrored upstream bone rolls,
+   which is what makes the next pass symmetric.
+2. `_bake_quaternius_rest()` — pose `UpperArm.L/R` -90° local X, read the posed matrices, apply
+   the Armature modifier, reset the pose, write the rest matrices, re-add the modifier, export
+   with `export_apply=False`.
+
+Then `tools/bake_ao.py --only <name>`.
+
+| Character | Source | Tris | Material slots |
+| --- | --- | --- | --- |
+| `npc_casual` | hoodie | 6,206 | skin, cloth, pants, hair, accessory + Eye, Eyebrows |
+| `npc_jacket` | casual | 6,424 | five slots + eyes/brows |
+| `npc_coat` | hoodie | 6,206 | five slots + eyes/brows |
+| `npc_vest` | worker | 5,240 | five slots + hivis vest/hat, eyes, moustache |
+| `npc_dress` | casual | 6,424 | five slots + eyes/brows |
+| `npc_hoodie` | hoodie | 6,206 | five slots + eyes/brows |
+| `npc_firefighter` | worker (vest + hat dropped) | 4,458 | five slots + eyes, moustache |
+| `npc_guard` | worker (vest + hat dropped) | 4,458 | five slots + eyes, moustache |
+| `npc_crowd_a` | casual | 6,424 | five slots + eyes/brows |
+| `npc_crowd_b` | casual | 6,424 | five slots + eyes/brows |
+| `npc_crowd_c` | hoodie | 6,206 | five slots + eyes/brows |
+| `npc_crowd_d` | worker (vest + hat dropped) | 4,458 | five slots + eyes, moustache |
+
+Source slot maps (`QUATERNIUS_SOURCES`): the `casual` tee is `Skin`/`White`/`Orange`/`Grey`/
+`Hair_Blond`; the hoodie is `Skin`/`Purple`/`LightBlue`/`Hair`/`White`; the worker is `Skin`/
+`LightBrown`/`Brown`+`Brown2`/`Grey`+`Black`/`Eyebrows`. Everything not in the map keeps its
+authored colour (eyes, brows, moustache, hivis vest and hard hat), so the contract still holds if
+upstream adds a material — it shows up as an extra fixed-colour slot instead of vanishing.
+
+Head gear is authored for this head: `HEAD_GEAR_SCALE = 0.64` and `HEAD_GEAR_LIFT = 0.07` map the
+0.315 m procedural head onto the 0.201–0.214 m Quaternius head. The procedural fallback therefore
+wears slightly small hats.
+
 ## Contract mismatch
 
 The expensive part is the rig and proportions, not the mesh. The source has a