Document MPFB full-body NPC prototype status and seams

MEMORY.md

@@ -27,6 +27,18 @@ canonical implemented-features list in `docs/development-status.md`.
   neck/shoulders (shoulder root z 1.345, chest 0.158, neck 0.060/0.054) and its skin
   decimate dropped to 0.21. The local renders are in
   `tmp/npc-parts/prototype_mh/renders/`.
+- **MPFB full-body prototype (2026-11-04):** the current body candidate is the local MPFB 2.0.18
+  pipeline at `tmp/npc-research/build_mpfb_npc.py` (dev-only; no `.mhclo` clothing installed).
+  It creates a macro-driven human, bakes targets, adds the `game_engine` rig, captures arm
+  points/weights, removes the rig, applies the helper MASK, scales to 1.81 m, retargets the A-pose
+  arms to the contract wrist, cuts the neck at 1.505, decimates, bisects the clothing boundaries,
+  paints the five slots, adds a short neck flare, project hands, rounded shoes and cuffs, the
+  accepted head and the 14-bone contract armature. Current output: **15,917 tris / 9,543 raw verts /
+  1.811 m / 14 bones / 10 materials**; `inspect` clean and feet grounded. **Not accepted yet:** the
+  neckline reads as a short collar, the 2k-tri body budget leaves boxy/finned outer thighs, the
+  shoes are blocky, and torso/hip/arm seam gaps appear when the body target is raised. The prototype
+  uses flat slot colours because the one-shot MPFB UV unwrap does not match the per-slot NPC
+  atlases. Renders: `tmp/npc-parts/mpfb_proto/renders/`; body-only: `body_only.glb`.
 - **Project agent skills (2026-11-03):** two tracked skills live in `.agents/skills/`:
   `gig-line-blender-asset-contract` and `gig-line-release-qa`. They are guidance only,
   add no runtime dependency and are referenced from `tools/README.md`. The third-party
@@ -128,6 +140,14 @@ canonical implemented-features list in `docs/development-status.md`.
   (dark tangent patches) — hair skips the normal map. Generate the cap before deleting
   the hidden scalp, or the cap inherits the hole. The flatpak sandbox cannot read `/tmp`;
   helper scripts must live under `$PWD`.
+- MPFB gotchas: call `TargetService.bake_targets(body)` before any decimate (shape-key
+  modifier error); add the built-in rig and capture arm weights before applying the MASK
+  modifier, or `build_basemesh_position_info` divides by zero on an emptied bone group;
+  decimate before bisecting the clothing loops, or the decimator collapses the bisect
+  into a sawtooth. Clear custom split normals after joining (imported MPFB normals leave
+  flat-shaded thigh facets). Imported GLBs may include helper `Cube`/`Icosphere` meshes at
+  ±1.0, so select `npc_base` explicitly. Delete the MPFB hands by hand/finger vertex-group
+  weights, not only by `|x|`, or leftover fingers become pants-coloured fins.
 - Image models have per-model size floors/caps (Seedream needs 1920+; `GEN_SIZE=2048`, do not
   lower; gpt-5-image-mini caps lower). `generate_image` applies model-specific sizing; concept
   generation defaults to `--request-size 1536`.

TODO.md

@@ -167,6 +167,8 @@ the rest of §C remains the broad review checklist.
       the hair cap, keep boundary faces as a safety band, and trim the hidden neck plug to 12
       segments. This saves ~950 tris on every variant.
 - [ ] Owner approves the hair cap and full-body silhouette on the local `npc_casual` prototype.
+      **Status (2026-11-04):** the current body candidate is the MPFB full-body prototype below,
+      not the narrowed procedural body; the 12-variant rebuild is blocked on that review.
 - [ ] Rebuild the 12 committed character GLBs with `--head mh`, in asset-family batches, then
       regenerate their AO maps and manifest entries. Never run a no-op full-library rebuild.
 - [ ] Run `blender_assets.py audit`, `fit`, `inspect` and `texels`, plus
@@ -184,11 +186,41 @@ the rest of §C remains the broad review checklist.
       no second rig, no material-slot rename.
 - [ ] Keep the MakeHuman body prototype consumable with the same approved head/hands; do not let it
       grow a second face/hand implementation while the part pipeline is being proven.
+
 - [ ] Rebuild only the changed character GLBs, AO maps and manifest entries; never run a no-op full
       library rebuild. Commit one asset family per change.
 - [ ] Re-run `blender_assets.py audit`/`fit`/`inspect`, `npc_proportions.py`, the 24-NPC budget,
       Godot and Python tests, the 48-frame baseline and the 96-frame final-context review.
 
+### Full-body MPFB prototype
+
+Goal: assemble the accepted MakeHuman head onto a CC0 MPFB body with project hands, shoes and
+14-bone contract rig, inside the 16,000/16,000 character budget. Local development only until the
+owner reviews the silhouette and a production integration decision is recorded.
+
+- [x] Build the dev pipeline at `tmp/npc-research/build_mpfb_npc.py`: create a macro-driven MPFB
+      human, bake targets, add the `game_engine` rig, capture arm points/weights, remove the rig,
+      apply the helper MASK, scale to 1.81 m, retarget the A-pose arms to the contract wrist
+      (`x=±0.27`, `z=0.78`), cut the neck at 1.505, decimate, bisect the clothing boundaries, paint
+      the five slots, add a short neck flare, project hands, rounded shoe shells, cuffs, the
+      accepted head and the 14-bone armature. Current output: **15,917 tris / 9,543 raw verts /
+      1.811 m / 14 bones / 10 materials**; `inspect` clean, feet grounded.
+- [x] Replace the spiky decimated MPFB hands with the project palm/finger primitives, straighten the
+      splayed MPFB feet so the shoes point forward, and use rounded shoe shells + cuffs instead of
+      flat blocks. Use flat slot colours in the prototype because the one-shot MPFB UV unwrap does
+      not match the per-slot NPC atlases.
+- [ ] Owner reviews the MPFB body renders (`tmp/npc-parts/mpfb_proto/renders/`): neck reads as a
+      short collar, boxy/finned outer thighs at the 2k body budget, blocky shoe silhouette, and
+      seam gaps that grow when the body target is raised above ~2k tris.
+- [ ] Fix the low-budget seams before any rollout: weld the torso/hip/arm components after the
+      bisects, protect the hip/knee loops during decimation (or rebalance head/body triangles), and
+      rebuild the neckline so the accepted head does not sit on a flared collar.
+- [ ] Record the production integration decision: either bake the approved MPFB body to a committed
+      source GLB (CI and fresh checkouts stay MPFB-free) or keep the procedural body as the shipped
+      path. Do not add the MPFB extension as a build/CI dependency.
+- [ ] If approved, roll the MPFB body into the 12 variants and regenerate AO maps, manifest entries,
+      `inspect`/`fit`/`audit`/`texels`, the proportion report and the 12 × 6 baseline.
+
 ### 6. QA, docs and exit
 
 - [ ] Capture front/three-quarter/profile head comparisons and open/grip hand comparisons; add

docs/npc-model-sourcing.md

@@ -54,6 +54,14 @@ the procedural head until the hair/body review and rollout in [`TODO.md`](../TOD
 The MakeHuman body should reuse the approved local head/hand parts rather than forking
 a second face implementation.
 
+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 **15,917 / 16,000 tris**, 1.811 m, 14 bones and 10
+materials, with project hands, rounded shoe shells, cuffs and flat slot colours. It is a review
+candidate, not a shipped asset: the neckline reads as a short collar, the 2k-tri body budget
+leaves boxy outer thighs, and torso/hip/arm seam gaps appear when the budget is raised. 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