Rewrite NPC plans around the Quaternius base

docs/3d-model-review.md

@@ -85,10 +85,12 @@ Readings:
 
 ## Baseline inventory (2026-11-04)
 
-Recorded for the Blender NPC model overhaul track: the exact starting point before the local
-part pipeline is built. `npc_base.blend` is the frozen fallback; the 12 characters are assembled
-procedurally by `tools/blender_assets.py`; the MakeHuman prototypes live under `tmp/npc-research/`
-and are not the shipped path.
+Recorded for the character baseline before the Quaternius migration. `npc_base.blend` is the
+frozen fallback; the 12 characters are currently assembled procedurally by
+`tools/blender_assets.py`. The active plan is now the CC0 Quaternius base bake
+([ADR-0017](adr/0017-quaternius-npc-base.md)); this section and the MakeHuman notes below are the
+pre-migration record. The MPFB/MakeHuman development files were removed from `tmp/` after the
+2026-11-05 pivot.
 
 ### `assets/models/npc/npc_base.blend` (frozen fallback)
 
@@ -143,7 +145,7 @@ width scale.
   287–440 px/m via the 4× repeat; runtime tint carries the look. This is a recorded note until a
   portrait shows texture starvation.
 
-### MakeHuman prototypes (not shipped; `tmp/npc-research/makehuman/`)
+### MakeHuman prototypes (historical, not shipped; research files removed from `tmp/`)
 
 | File | Verts / tris | Bones | Slots | Note |
 | --- | ---: | ---: | --- | --- |
@@ -242,7 +244,7 @@ nose/lip/chin relief cleanly.
 
 The judge then compared the displacement head against the **decimated MakeHuman head**
 (extracted from `makehuman_retargeted.glb`, 2,009 verts / 1,573 tris, saved as
-`tmp/npc-parts/makehuman_head.glb`) and returned a decisive result: **ship the MakeHuman head** —
+the local `makehuman_head.glb`) and returned a decisive result: **ship the MakeHuman head** —
 it keeps the nose/chin/jaw landmarks at a fraction of the cost, while the procedural head's
 "clean ellipse outline instantly screams procedural sphere".
 

docs/README.md

@@ -4,8 +4,8 @@ This folder holds the project documentation, visual references and generated QA
 
 ## Current priorities
 
-1. [Blender NPC model overhaul](../TODO.md#blender-npc-model-overhaul-top-priority) — part-based head/face/hands pipeline and 24,000-budget contract.
-2. [MakeHuman and 3D model/map improvements](../TODO.md#makehuman-character-pipeline) — body intake, asset re-evaluation and local map reconstruction.
+1. [Quaternius NPC base migration](../TODO.md#quaternius-npc-base-migration-top-priority) — CC0 Quaternius mesh/animation source baked to the 24,000-budget runtime contract.
+2. [3D model and local map improvements](../TODO.md#3d-model-and-local-map-re-evaluation) — asset re-evaluation and local map reconstruction.
 3. [0.10.0 release candidate](../TODO.md#milestone-0100--3d-model-and-map-improvements-minor) — versioned release hardening after the unversioned development tracks.
 
 ## Start here
@@ -13,7 +13,7 @@ This folder holds the project documentation, visual references and generated QA
 - [`../PLAN.md`](../PLAN.md) — product, design intent and development priorities
 - [`../TODO.md`](../TODO.md) — priority-ordered active tasks and roadmap
 - [`npc-model-sourcing.md`](npc-model-sourcing.md) — character-source evaluation, licence rules and the character-development plan
-- [`makehuman-head-review.md`](makehuman-head-review.md) — local MakeHuman head prototype, provenance and review verdict
+- [`makehuman-head-review.md`](makehuman-head-review.md) — retained MakeHuman fallback head, provenance and review verdict
 - [`architecture.md`](architecture.md) — arc42 system architecture
 - [`getting-started.md`](getting-started.md) — setup, run/test commands and controls
 - [`asset-tooling.md`](asset-tooling.md) — image/model pipelines and screenshot gates

docs/adr/0015-npc-model-variety-sourcing.md

@@ -1,8 +1,14 @@
 # ADR-0015: NPC model variety sourcing
 
-- **Status:** Accepted (planning)
+- **Status:** Superseded by [ADR-0017](0017-quaternius-npc-base.md) (2026-11-05)
 - **Date:** 2026-11-03
 
+## Superseded
+
+ADR-0017 replaces the generator-first decision below: Quaternius is now the
+primary NPC base. The evaluation, licence rules and consequences remain as the
+record of the 2026-11-03 decision.
+
 ## Context
 
 The library has eight skinned characters, and role/seed selection reuses them

docs/adr/0017-quaternius-npc-base.md

@@ -0,0 +1,69 @@
+# ADR-0017: Quaternius NPC base
+
+- **Status:** Accepted
+- **Date:** 2026-11-05
+- **Supersedes:** ADR-0015 (generator-first character sourcing)
+
+## Context
+
+The current NPC library is built by the project-owned procedural generator. It
+keeps the contract and ships, but the body, neck, hands and shoes need a
+bespoke part pipeline to read as human. The MakeHuman head and MPFB body
+prototypes improved detail but added a second authoring path, a 19,747-triangle
+prototype and unresolved neck/shoulder seams.
+
+The CC0 **Quaternius Ultimate Modular Characters** pack already provides a
+coherent low-poly human silhouette, 21 modular outfits and 24 animation clips.
+The researched GLBs (`Casual`, `Casual_Hoodie`, `Worker`) measure 4 meshes, 62
+joints and 24 clips each. The owner directed that Quaternius become the NPC
+base. The full evaluation is in [`docs/npc-model-sourcing.md`](../npc-model-sourcing.md).
+
+## Decision
+
+1. **Quaternius is the primary NPC mesh and animation source.** Keep the
+   licence and SHA-256 provenance for the three researched GLBs.
+2. **Stage 1 keeps the runtime contract.** Bake a canonical Quaternius base onto
+   the existing 13-core contract, five tint slots, 24,000/24,000 budget,
+   grounded −Y front and one `npc_base` skinned mesh. Retarget Idle and Walk;
+   discard the combat/gun/sword clips. `NpcAvatar`, gear attach points and the
+   pose composition remain the runtime interface.
+3. **The 62-joint rig is an authoring source, not a runtime dependency.** It is
+   not shipped and Quaternius is not loaded by CI, build or runtime.
+4. **Stage 2 needs its own ADR.** If the proportion warp fails the silhouette,
+   deformation or gear gate, stop and decide whether to adopt the 62-joint rig
+   at runtime. Do not ship a hybrid rig or a second gear offset system.
+5. **Close the MakeHuman/MPFB body work.** The accepted MakeHuman head and the
+   procedural `npc_base` stay as tested fallbacks until the Quaternius rollout
+   ships. No new MPFB development.
+6. **Commit baked assets only.** The release consumes committed GLBs, maps and
+   the manifest; Quaternius and Blender remain development tools.
+
+## Consequences
+
+### Positive
+
+- A human base, modular outfits and a coherent animation set are already
+  authored and CC0.
+- The bespoke neck, hand and shoe pipelines are no longer on the critical path.
+- The runtime contract and gear stay stable during the mesh migration.
+
+### Negative
+
+- A 62-joint T-pose does not share the arm-down 13-core rest pose or
+  proportions; the proportion warp is the main risk.
+- Quaternius' animation quality is only available after retargeting, unless
+  Stage 2 is accepted.
+- The migration touches all 12 variants, their AO maps, manifest entries and
+  baseline captures at once.
+
+## Alternatives
+
+- **Keep the procedural generator as the primary path.** Rejected by the owner:
+  the human silhouette remains the weak point and the bespoke part pipeline is
+  larger than the Quaternius bake.
+- **Adopt the 62-joint rig immediately.** Deferred to Stage 2 because it changes
+  `NpcAvatar`, pose composition and gear offsets at the same time as the mesh.
+- **Continue the MPFB body.** Rejected: it needs a separate head/neck/hand
+  pipeline and still has unresolved surface seams.
+- **Use a service character generator (Mixamo, Ready Player Me).** Rejected:
+  redistribution and runtime terms are not a CC0 basis.

docs/adr/README.md

@@ -20,3 +20,4 @@ Each ADR records the context, decision, consequences and alternatives for a dura
 - [0014-runtime-image-root](0014-runtime-image-root.md)
 - [0015-npc-model-variety-sourcing](0015-npc-model-variety-sourcing.md)
 - [0016-npc-character-budget-24k](0016-npc-character-budget-24k.md)
+- [0017-quaternius-npc-base](0017-quaternius-npc-base.md)

docs/architecture.md

@@ -81,7 +81,7 @@ The player interacts with NPCs, venue entrances, access artifacts, equipment, st
 - `WorldBuilder` assembles the procedural venue from a per-venue `VENUE_SPECS` table (facade, windows, stairs, street, nav bounds, guard spawn, feature flags and prop placements), prefers the Blender prop library in `assets/models/blender/props/`, and falls back to `assets/models/generated/` or primitives. `GameManager` rebuilds only the `World` container when the venue changes, so the guard/UI and their state survive. It also wires the phase-driven library emissives and street dressing.
 - `src/game/ui/art.gd` loads runtime UI/scene art from `assets/images/ui/` and `assets/images/scenes/`, with null fallbacks so panels keep their procedural layouts.
 - `tools/model_pipeline.py` builds and audits the street-prop `.glb` models and packs their colour atlases.
-- `tools/npc_pipeline.py` builds and audits the skinned NPC base model (`assets/models/generated/npc_base.glb`) and its per-slot material maps, with an optional AI fabric override (ADR-0013).
+- `tools/npc_pipeline.py` builds and audits the skinned NPC base model (`assets/models/generated/npc_base.glb`) and its per-slot material maps, with an optional AI fabric override (ADR-0013). The active character migration bakes the CC0 Quaternius base onto the same contract (ADR-0017); the procedural base remains the fallback.
 - `tools/blender_assets.py` builds, renders and audits the Blender asset library (`assets/models/blender/{npc,npc_gear,props}/` + `manifest.json`): NPC character variants that are drop-in for `npc_base`, attach-point gear, and street/venue props. `NpcAvatar` selects variants/gear by role/seed and `WorldBuilder` loads the prop replacements and new street dressing, with procedural fallbacks (see `docs/blender-assets.md`).
 - `tools/scene_concepts.py` generates realism-pass references (`docs/screens/concepts/`), skyline backdrops and surface tiles (raw `assets/textures/ai/v2/raw/` → candidates `assets/textures/ai/game_ready/v2/`), promotes the validated ones to the tracked `v2/picks/` that `SurfaceMaterials`/`WorldBuilder` preload, audits them, and scores `src/test/capture_realism.gd` A/B captures (six stages, runtime texture swaps) against the concepts (`docs/screens/realism/<run>/`).
 - `tools/asset_pipeline.py` generates and audits role-aware textures; `tools/screen_designs.py` generates screen references and judges captures; `tools/check_screenshots.sh` renders the staged gallery and runs the compare gate.
@@ -206,14 +206,14 @@ transient input state.
 
 ### Character development tooling
 
-Characters have two authored sources and one procedural fallback. The eight-variant
-Blender library (`assets/models/blender/npc/`) is the normal presentation path; the
-older skinned `npc_base` (`assets/models/generated/npc_base.glb`) remains a frozen
-contract and fallback; `NpcAvatar`'s procedural rig is the offline last resort.
-Four crowd-variety prototypes have been built and audited locally but are not yet in
-the shipped catalogue; generator-first expansion is the active character track
-(ADR-0015). Blender is a developer tool only — runtime, tests and CI consume committed
-GLBs and maps.
+Characters have one active migration, two committed fallbacks and one procedural last
+resort. The Quaternius base migration (ADR-0017) bakes the CC0 Quaternius mesh and
+Idle/Walk clips onto the existing 13-core contract and produces the next 12-variant
+library. Until that ships, the 12-variant Blender library
+(`assets/models/blender/npc/`) is the normal presentation path, the older skinned
+`npc_base` (`assets/models/generated/npc_base.glb`) is the frozen contract fallback,
+and `NpcAvatar`'s procedural rig is the offline last resort. Blender and Quaternius are
+developer tools only — runtime, tests and CI consume committed GLBs and maps.
 
 | Tool | Role | Committed artifact | Verification gate |
 | --- | --- | --- | --- |
@@ -388,6 +388,7 @@ Architecture decisions are recorded as ADRs:
 - [ADR-0008: Cone focus and focus circle](adr/0008-cone-focus-and-head-ring.md)
 - [ADR-0009: Radial action menu](adr/0009-radial-action-menu.md)
 - [ADR-0010: Procedural NPC presentation](adr/0010-procedural-npc-presentation.md)
+- [ADR-0017: Quaternius NPC base](adr/0017-quaternius-npc-base.md)
 - [ADR-0011: Aim-free selection and precision walk](adr/0011-aim-free-selection-and-precision-walk.md)
 - [ADR-0012: Surface materials and generated props](adr/0012-surface-materials-and-generated-props.md)
 - [ADR-0013: Blender-authored NPC characters and baked materials](adr/0013-blender-authored-npc-characters.md)

docs/asset-tooling.md

@@ -82,6 +82,8 @@ tonemapping, glow, fog, colour grading) that the phase lighting applies.
 
 NPCs are moving from the procedural capsule rig to a skinned, UV-mapped base
 character authored in Blender ([ADR-0013](adr/0013-blender-authored-npc-characters.md)).
+The active base is the CC0 Quaternius modular character, baked to the runtime contract
+([ADR-0017](adr/0017-quaternius-npc-base.md)).
 `tools/npc_pipeline.py` builds `assets/models/generated/npc_base.glb` plus the
 per-slot material maps. `NpcAvatar` instantiates that skinned model, tints its
 five material slots from the seed-driven outfit, and drives the bones from the
@@ -129,10 +131,10 @@ with colliders/avoidance and drives their emissive parts from the day/night
 cycle. The single `npc_base.glb` and primitive props remain offline fallbacks.
 Contract and integration notes: [`blender-assets.md`](blender-assets.md).
 
-Sourcing and expansion research (no external model is shipped yet):
-[`npc-model-sourcing.md`](npc-model-sourcing.md) compares Quaternius, Kenney, Khronos and
-MakeHuman sources against the character contract and records the 2026-11-03 direction
-(procedural generator first, Quaternius reference, MakeHuman deferred).
+Sourcing and migration plan: [`npc-model-sourcing.md`](npc-model-sourcing.md) records the
+2026-11-05 direction (ADR-0017). Quaternius Ultimate Modular (CC0) is the primary NPC mesh
+and animation source, baked to the existing 13-core contract; the procedural generator is
+the fallback. Kenney/Khronos/MakeHuman remain evaluated references, not active bases.
 
 | Characters | Props |
 | --- | --- |
@@ -146,7 +148,7 @@ python3 tools/blender_assets.py sheet   # docs/blender_previews/sheet_*.jpg
 python3 tools/blender_assets.py audit   # no Blender needed
 python3 tools/blender_assets.py fit     # gear-vs-body fit report
 python3 tools/blender_assets.py texels  # per-slot texel density (px/m) of the characters
-# `build --head mh` selects the MakeHuman head; the default stays `face` until rollout.
+# `build --head mh` selects the retained MakeHuman fallback head; the default is still `face`.
 godot --headless --path . --import
 ```
 
@@ -188,9 +190,9 @@ Caveats:
 
 ### Intake adaptation (`adapt`)
 
-`adapt` is the mechanical first half of an external-mesh intake (MakeHuman,
-MPFB, downloaded GLB): import, apply transforms, ground the feet, weld seam
-splits, decimate to the character budget, and export a GLB. It does **not** map
+`adapt` is the mechanical first half of an external-mesh intake (Quaternius,
+MakeHuman fallback, downloaded GLB): import, apply transforms, ground the feet,
+weld seam splits, decimate to the character budget, and export a GLB. It does **not** map
 the five tint slots or rebuild the 13-core-bone `npc_base` armature (optional extra bones are allowed) — those stay a
 manual `retopology`/`rigging` step with a recorded second-rig contract if the
 source rig cannot be retargeted:
@@ -198,14 +200,14 @@ source rig cannot be retargeted:
 ```bash
 flatpak run org.blender.Blender --background \
   --python "$PWD/tools/blender_assets.py" -- adapt \
-  --file "$PWD/tmp/npc-research/makehuman_base.glb" \
-  --out "$PWD/tmp/npc-research/makehuman_adapted.glb" \
+  --file "$PWD/tmp/npc-research/quaternius/Casual.glb" \
+  --out "$PWD/tmp/npc-research/quaternius_adapted.glb" \
   --target-tris 24000
-# prints: adapted makehuman_adapted.glb: 36972 -> 24000 tris (bones=N, meshes=1)
+# prints: adapted quaternius_adapted.glb: <source> -> 24000 tris (bones=N, meshes=1)
 ```
 
 Run `inspect` on the adapted GLB before and after, and keep the procedural
-generator as the fallback until a MakeHuman variant passes `audit`/`fit` and the
+generator as the fallback until a Quaternius variant passes `audit`/`fit` and the
 24-NPC budget.
 - Numbers are Blender-side measurements. Triangles match `audit` on project assets; the seam-split
   vertex count can differ by ±1 because the importer rounds normals. `audit` stays the single final

docs/blender-assets.md

@@ -3,7 +3,10 @@
 Architecture context: the asset contracts and fallback path are summarized in
 [`architecture.md`](architecture.md#content-and-asset-pipeline-architecture).
 
-Status: built, audited, and integrated (2026-11-01). `NpcAvatar` selects the
+Status: built, audited, and integrated (2026-11-01). The active character migration
+replaces the procedural body with a baked CC0 Quaternius base
+([ADR-0017](adr/0017-quaternius-npc-base.md)); the current library remains the shipped
+fallback until the Quaternius 12-variant baseline passes review. `NpcAvatar` selects the
 character variants and attaches the gear; `WorldBuilder` loads the prop library
 with colliders and phase-driven emissives. The 0.9.4 neutral baseline and its
 acceptance criteria are in [`npc-visual-review.md`](npc-visual-review.md);
@@ -63,7 +66,7 @@ flatpak run org.blender.Blender --background \
 flatpak run org.blender.Blender --background \
   --python "$PWD/tools/npc_parts.py" -- extract --part hand_l --variant npc_casual \
   --out "$PWD/tmp/npc-parts/npc_casual/hand_l.glb"
-# Assemble a variant (currently rebuilds the procedural character)
+# Assemble a variant (current fallback path; Quaternius migration in progress)
 flatpak run org.blender.Blender --background \
   --python "$PWD/tools/npc_parts.py" -- assemble --variant npc_casual \
   --out "$PWD/tmp/npc-parts/npc_casual/assembled.glb"
@@ -139,7 +142,8 @@ render about 2.5 min.
 
 ## Characters
 
-All library variants share the [character and gear asset contract](architecture.md#character-and-gear-asset-contract):
+All library variants, including the incoming Quaternius-derived base, 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:

docs/development-status.md

@@ -34,8 +34,9 @@ and the active order/gaps in [`TODO.md`](../TODO.md).
 ## Known gaps
 
 - External first-time-player sessions and balance sweeps are not completed.
-- The NPC head/face/hand overhaul and MakeHuman body pipeline are planned, not
-  shipped.
+- The Quaternius NPC base migration is planned, not shipped. The current 12-character
+  procedural library and the MakeHuman head remain fallbacks until the Quaternius
+  12-variant baseline passes review.
 - 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/makehuman-head-review.md

@@ -1,19 +1,19 @@
 # MakeHuman head prototype
 
-Status: **owner-accepted head, assembled prototype, not yet shipped.**
-The owner accepted the basic human head on 2026-11-04. The automated vision gate
+Status: **retained fallback; superseded as the active NPC head by the Quaternius
+base (ADR-0017).** The owner accepted the basic human head on 2026-11-04. The automated vision gate
 still records REJECT on the eye/lid region as deferred polish. The asset is a
-standalone head/neck extracted from the CC0 MakeHuman base in
-`tmp/npc-research/makehuman/base.obj`; the assembled path now adds hair, a hidden
-scalp trim and the procedural body. The 12 shipped GLBs have not been rebuilt
-with it yet.
+standalone head/neck extracted from the CC0 MakeHuman base. The assembled path
+adds hair, a hidden scalp trim and the procedural body. The 12 shipped GLBs have
+not been rebuilt with it, and the Quaternius migration replaces it as the active
+base. The development source files were removed from `tmp/` on 2026-11-05.
 
 ## Asset
 
 - GLB: [`assets/models/blender_src/makehuman_head.glb`](../assets/models/blender_src/makehuman_head.glb)
 - Review sheet: [`blender_previews/sheet_makehuman_head.jpg`](blender_previews/sheet_makehuman_head.jpg)
-- Source workflow (development-only): `tmp/npc-research/build_makehuman_head.py`
-  — extracts the MakeHuman head, cuts it at the neck, keeps the head/eye/mouth
+- Source workflow (development-only, files removed after the Quaternius pivot;
+  retained here as the historical method) — extracts the MakeHuman head, cuts it at the neck, keeps the head/eye/mouth
   components, cuts an almond aperture through a skin eyelid mask, adds recessed
   eyeballs with flat iris/pupil discs, anchors brows to the face surface, renders
   front/three-quarter/profile and exports the standalone GLB.
@@ -53,10 +53,11 @@ with it yet.
 ## Provenance
 
 - Base mesh: MakeHuman / MPFB base, CC0, from the local research set
-  `tmp/npc-research/makehuman/`; see [`CREDITS.md`](../CREDITS.md).
+  (development source files removed after the 2026-11-05 Quaternius pivot); see
+  [`CREDITS.md`](../CREDITS.md).
 - The head is a **derived prototype**, not a shipped NPC. It does not enter
   `assets/models/blender/npc/`, `npc_base`, the runtime `NpcAvatar` path, CI, or
-  a release package until the NPC overhaul plan accepts it.
+  a release package. It is retained as a fallback, not the active NPC base.
 - Source photographs/proportions are not used as textures here; this is a
   geometry-only head built from the researched model data.
 
@@ -123,8 +124,8 @@ than a body-welded seam.
 - The procedural body was narrowed at the neck and shoulders (chest 0.158,
   neck base 0.060, neck top 0.054, shoulder root z 1.345) and its skin decimate
   dropped to 0.21 so all 12 variants fit the 16,000 cap.
-- Local review renders: `tmp/npc-parts/prototype_mh/renders/` (portrait
-  front/three-quarter/profile and full-body front/three-quarter).
+- Local review renders were removed with the 2026-11-05 `tmp/` cleanup; the
+  committed review sheet above is the retained evidence.
 
 ## Deferred polish
 

docs/npc-model-sourcing.md

@@ -1,93 +1,114 @@
 # NPC Model Sourcing
 
-This page records the source evaluation behind [ADR-0015](adr/0015-npc-model-variety-sourcing.md).
-The shipped path is the project-owned Blender/procedural library; external sources
-remain references or local prototypes unless a later ADR accepts them.
+This page records the source evaluation and the active character plan. The
+decision is [ADR-0017](adr/0017-quaternius-npc-base.md), which supersedes the
+generator-first sourcing decision in [ADR-0015](adr/0015-npc-model-variety-sourcing.md).
 
-## Evaluation
+## Active direction
 
-The library needs variety beyond the original eight silhouettes while preserving
-the `npc_base` contract: mesh node, 13 required core bones (optional extras
-allowed), five tint slots, −Y/+Z front, grounded feet and the 24,000/24,000
-character budget.
+**Quaternius Ultimate Modular Characters (CC0) is the primary NPC mesh and
+animation source.** The project-owned procedural library remains the shipped
+fallback until the Quaternius migration passes the silhouette and gear gates.
 
-| Source | Licence | Result |
+The migration keeps the runtime contract that Godot, gear and tests already
+consume:
+
+- one `npc_base` skinned mesh under the 13 required core bones (optional extras
+  allowed);
+- five tint slots: `skin`, `cloth`, `pants`, `accessory`, `hair`;
+- front on Blender −Y / Godot +Z, feet grounded, height about 1.81 m;
+- 24,000 triangles / 24,000 glTF vertices per character;
+- gear stays at 1,500 triangles and props at 4,000;
+- committed GLBs and maps only; no Quaternius, Blender or network dependency in
+  CI, build or runtime.
+
+### Stage 1 (default)
+
+1. Import the researched Quaternius GLBs and choose a canonical base.
+2. Map the 62 source joints to the 13-core contract and bake a proportion warp.
+3. Skin the mesh, retarget Idle and Walk, and verify seated/arm-down poses.
+4. Map the five slots, unwrap and bake 256² maps.
+5. Fit the existing gear and render the silhouette gate.
+6. Build the 12 variants, audit, and capture the 12 × 6 baseline.
+
+The Quaternius 62-joint rig and its 24 animation clips are an **authoring
+source**. They are not loaded at runtime.
+
+### Stage 2 gate
+
+The 62-joint T-pose source does not share the project's arm-down rest pose or
+proportions. If the Stage 1 proportion warp cannot preserve the Quaternius
+silhouette and deformation, stop the rollout and write a new ADR for adopting
+the 62-joint rig at runtime. Do not ship a hybrid rig, a second gear offset
+system or a silent `NpcAvatar` change.
+
+## Research findings
+
+The researched files are the three converted Quaternius outfits used by the
+Ducz Character Creator: `Casual`, `Casual_Hoodie` and `Worker`. They are kept
+locally in `tmp/npc-research/quaternius/` with the licence and mirror notes.
+
+| File | SHA-256 | Structure |
 | --- | --- | --- |
-| Quaternius Ultimate Modular | CC0 | Good silhouette/decimation material, but a 62-bone T-pose realistic rig and different proportions; not a drop-in. Kept as a reference/prototype. |
-| Kenney Blocky Characters | CC0 | No matching rig; style is much blockier than the project look. |
-| Khronos CesiumMan / RiggedFigure | CC BY 4.0 | Different bone names/rest pose and no five-slot materials; not a drop-in. |
-| MakeHuman / MPFB base | CC0 | Useful body-shape base, but requires retopology, a custom rig, clothing and part integration. Active local pipeline, not the shipped path. |
+| `Casual.glb` | `bc2d84fba249ebaa0629cb9d133ad37234196e4b8004aa205a6397abed04e05c` | 4 meshes, 62 joints, 24 clips, 7 materials |
+| `Casual_Hoodie.glb` | `f5b722199f7628b24550989af4230f65d5230727df9c326fd2b3e360effe5249` | 4 meshes, 62 joints, 24 clips, 7 materials |
+| `Worker.glb` | `8d0f454336c2effc5c08f63a177af3a82d1a7af025ca9588b40e4c90c4703534` | 4 meshes, 62 joints, 24 clips, 11 materials |
 
-The contract mismatch is the expensive part, not decimation: retargeting a
-different rig or rebuilding slots/weights can distort the body and invalidate
-gear placement. Any future second-rig path needs its own ADR and animation/gear
-offsets.
+Source: [Quaternius Ultimate Modular Characters](https://quaternius.com/packs/ultimatemodularcharacters.html)
+and [Ultimate Modular Women](https://quaternius.com/packs/ultimatemodularwomen.html),
+CC0 1.0. The Ducz mirror is a browser builder over the same packs; it adds 21
+outfits and a shared skeleton. The three full GLBs are the initial scope; the
+21-part builder is a fallback for role coverage, not the default.
 
-## Decision and outcome
+The first prototype measured 12,518 imported vertices, 3,199 after welding and
+2,423 vertices / 4,654 triangles after a 0.75 decimate. Idle and Walk read well.
+The source is a T-pose with a 62-joint realistic rig, roughly 0.96 m hip,
+1.68 m arm span and 0.153 m shoulder offset, so a contract bake is required.
 
-- Extend the project-owned procedural generator as the primary shipped path
-  (12-character library, crowd variants, role pools).
-- Keep Quaternius as a studied reference, not a shipped base.
-- MakeHuman is a local development pipeline for body-shape diversity; it must
-  consume the same head/hand parts as the procedural library and never become a
-  CI/build dependency.
-- Record CC0/CC-BY provenance; CC-BY previews require attribution in
+The 24,000 cap leaves room to stay much closer to the source LOD than the
+prototype's 4,654 triangles. Do not decimate to the old 7,000-triangle target
+before the silhouette gate.
+
+## Contract mismatch
+
+The expensive part is the rig and proportions, not the mesh. The source has a
+T-pose and a realistic skeleton; the runtime expects an arm-down 13-core rig,
+fixed gear attach points and the existing pose composition. The Stage 1 bake
+must therefore:
+
+- rotate the arms down and match the contract wrist positions;
+- warp the hips, knees, shoulders and head without collapsing the deltoid,
+  shortening the arms or changing the silhouette;
+- keep one skinned `npc_base` mesh and the five slots;
+- verify gear against the new shoulder, hip and head positions.
+
+If those constraints distort the model, Stage 2 is the correct next decision,
+not a local workaround.
+
+## Licence and provenance
+
+- CC0 preferred. CC-BY is allowed only with attribution in
   [`CREDITS.md`](../CREDITS.md).
+- No service asset whose terms restrict redistribution may be shipped.
+- Keep the source URL, author, licence, download date and SHA-256 in this page
+  and in `CREDITS.md`.
+- Research files and generated previews stay in `tmp/` (gitignored). Only final
+  audited assets and committed review sheets enter the repository.
+- Quaternius models and animations are CC0; the existing credits entry already
+  names Quaternius. Keep it accurate if the shipped source set changes.
 
-## MakeHuman prototype notes
+## Closed tracks
 
-The local prototype (`tmp/npc-research/`, never committed) scaled the base to
-1.82 m, grounded it, triangulated/decimated it and retargeted it to the 13-core
-armature. The first retarget measured **6,444 / 16,000 tris and**
-**7,726 / 16,000 verts**, 14 bones, skinned, arm-down, five slots. It exposed
-the expected issues: a 1.63× arm-scale warp at the deltoid/shoulder, blocky
-decimated hands, rough slot boundaries and a head/neck shadow gap. The later
-project head/hands swap reduced this to **6,407 / 16,000 tris and**
-**6,651 / 16,000 verts**, but manual shoulder/neck retopology and part cleanup
-remain before it can be considered shippable.
+The MakeHuman/MPFB body pipeline is closed for the NPC base. The accepted
+MakeHuman head and the procedural `npc_base` remain tested fallbacks until the
+Quaternius rollout is complete. Their research scripts and renders were removed
+from `tmp/` after the pivot; the measurements and decisions remain in
+[`DONE.md`](../DONE.md), [`MEMORY.md`](../MEMORY.md) and the review docs.
 
-A standalone MakeHuman head is recorded in
-[`makehuman-head-review.md`](makehuman-head-review.md). The owner accepted the basic
-human head on 2026-11-04; the assembled path (`build_character(head="mh")`) adds a
-skull-conforming hair cap and hides the scalp under it. The 12 shipped GLBs still use
-the procedural head until the hair/body review and rollout in [`TODO.md`](../TODO.md).
-The MakeHuman body should reuse the approved local head/hand parts rather than forking
-a second face implementation.
+## Related documents
 
-The current local MPFB full-body prototype (`tmp/npc-research/build_mpfb_npc.py`) assembles the
-accepted head on an MPFB 2.0.18 body at **19,747 / 24,000 tris**, 1.810 m, 14 bones and 10
-materials, with project hands, bevelled shoe shells with inset soles and tongues, pant cuffs,
-cloth sleeve cuffs and flat slot colours. The torso is radially inflated by 12% through z 0.72–1.40
-to loosen the shirt. It is a review candidate, not a shipped asset. The neck is a boolean-cut
-circular bore bridged by a smooth lathe; the accepted head is trimmed at the narrow neck (z 1.55)
-so its wide flat cut brim is discarded, and the lathe flares to cover the bore, then tucks inside
-the jaw. This removed the square collar, dark notches and wide brim; a thin jaw crease and a hard
-shirt-shoulder point in three-quarter view remain. The ankles are hidden by 0.11 m shoe shells and
-0.08 m pant cuffs, and a light smoothing pass softens the closed thigh/hip region. The neck skin
-test is guarded to z > 1.35 so it cannot paint the crotch. Remaining polish: the crotch hollow still reads as a V under
-the shirt hem, a partly loosened shirt and angular thigh facets; a separate loose shirt shell is
-the fix. Lowering the hem to z 0.80, tilting it up at the front and a 13% hem flare were rejected
-as a unitard, high-cut swimwear and a peplum respectively. A quick open, flared solidified tube
-(0.150→0.196 m, z 1.05→0.80, 24 segments) read as a hanging apron/tabard; the shell needs a shaped
-torso, armholes and a curved hem.
-A torus collar, cloth cylinder collar, skin neck-blend sphere, destructive vertex-smoothing pass
-and untucked shirt-hem band were tried and removed because they read as a brace, shelf, donut or
-hanging flap, or tore a hole at the collar. Protruding flat sole plates read as skates or bricks,
-so the shoe detail is an inset sole and tongue under a rounded shell; laces were dropped for
-triangle budget. The production integration decision (bake a committed source GLB or keep the
-procedural body) and the owner review are tracked in `TODO.md`; MPFB itself must not become a
-CI/build dependency.
-
-## Provenance rules
-
-- CC0 preferred; CC-BY only with attribution in `CREDITS.md`; no service asset
-  whose terms restrict redistribution.
-- Downloaded research and generated previews stay in `tmp/`/gitignored folders;
-  only final audited assets and committed review sheets enter the repository.
-- Record source URL, licence, author, date and what decision the reference
-  informed. Never treat a generated concept as licensed map/model data.
-
-Measurements, visual decisions and accepted limits are in
-[`3d-model-review.md`](3d-model-review.md) and
-[`npc-visual-review.md`](npc-visual-review.md). Commands are in
-[`asset-tooling.md`](asset-tooling.md).
+- [ADR-0017: Quaternius NPC base](adr/0017-quaternius-npc-base.md)
+- [ADR-0016: 24,000-triangle character budget](adr/0016-npc-character-budget-24k.md)
+- [Blender asset contract](architecture.md#character-and-gear-asset-contract)
+- [`3d-model-review.md`](3d-model-review.md), [`npc-visual-review.md`](npc-visual-review.md)
+- [`asset-tooling.md`](asset-tooling.md)