animation/dev/glm-task-kapahaka-outfit.md

# TASK: put the approved kapa haka outfit through the clothing pipeline into the game

You are working in `C:/Users/Jeremy/tinqs/animation` (Git Bash, Windows). Blender is:

    BLENDER="/c/Program Files/Blender Foundation/Blender 5.1/blender.exe"

## Goal

Two Marvelous-Designer-authored garments have been approved. Turn them into
game-ready outfit parts on the shared 65-bone Quaternius skeleton, using the
existing staged Blender pipeline `clothing/garment_pipeline.py`.

| Garment | Source file (already exported, do not re-author) | Outfit slot |
|---|---|---|
| Tāniko bodice ("pari") | `tools/tailor/lena_pari_v3_garment.fbx` | Body |
| Flax skirt ("piupiu") | `tools/tailor/lena_piupiu_v2_garment.fbx` | Legs |

Target body / rig (the fit target and weight donor):
`C:/Users/Jeremy/tinqs/ariki-game/assets/quaternius/derived-bodies/Ariki_Female_QuatSkin.glb`

Export destination:
`C:/Users/Jeremy/tinqs/ariki-game/assets/quaternius/outfits/kapahaka/`
Set id `Kapahaka`, gender `Female`, so the pipeline should produce
`Female_Kapahaka_Body.gltf` and `Female_Kapahaka_Legs.gltf` (+ .bin), matching
the naming pattern of the earlier pilot in `../outfits/mddress/`.

## Read these first (they are the source of truth — do not guess)

1. `clothing/README.md` — the pipeline's stages, design rationale, usage, and
   the config schema explanation. Read it fully before writing any config.
2. `clothing/configs/dress.json` — a working config to model yours on.
3. `.claude/skills/marvelous-designer/SKILL.md` — how these garments were made
   (section "Handing off downstream" is the relevant part).

## What is DIFFERENT about these garments (important — the pilot config misleads)

The pilot config (`dress.json`) was written for a *downloaded* MD dress of
**2.49 million verts** with 12 materials, where aggressive reduction was the hard
problem. **These garments are nothing like that:**

- They are tiny: pari ≈ 1.9k verts / 3.6k faces; piupiu ≈ 3.7k verts / 7.1k faces.
  They are ALREADY at game budget. Do not fight to decimate them. Set generous
  tri budgets; only reduce if something is genuinely over budget.
- They were draped directly on this exact body in Marvelous Designer, so they
  are ALREADY fitted and correctly scaled/positioned. Expect alignment to be
  near-identity (scale 1.0, no nudge) — verify rather than assuming the pilot's
  `scale_xy: 1.18 / scale_z: 0.95` values, which were corrections for a
  foreign garment.
- The `fit` stage is still worth running for its +4mm clearance shell
  (poke-through defence), but it should barely move anything.
- Each garment is one simple part — no junk materials, no topstitch soup, no
  multi-island jacket. Expect a small number of islands.

## Already-established facts (verified — do not spend steps re-deriving)

- The body/rig imports clean: **65 bones**, Quaternius names, body z-range
  `-0.011 .. 1.766` m, `pelvis` z = 0.932, `neck_01` z = 1.413.
- **The MD garment FBX exports are 10× oversized and offset in Z.** Measured
  pari z-range is `10.546 .. 14.613` against a body of `0 .. 1.77`. This is the
  mirror of how they were authored (the avatar was imported into Marvelous
  Designer at `scale=10` to work in MD's millimetre space, so garments come back
  in that same space). Expect to need roughly **0.1 uniform scale**, then a Z
  placement correction — derive the exact numbers from the measured bounds
  rather than trusting this estimate. Sanity check after aligning: the pari
  should span roughly z 1.05–1.40 m (waist to shoulder) and the piupiu roughly
  z 0.45–1.05 m (below knee to waist).

## CRITICAL: placement. A previous run exported a garment 10 cm too low.

**You cannot see the QA renders.** Confirming a PNG exists proves nothing about
whether the garment is in the right place. Placement must be verified
**numerically**, and it is the single most likely thing to go wrong.

### Why the pipeline mis-places these garments

`stage_prepare` auto-aligns by moving the garment so its **top** meets the
`align.top_bone` head: `dz = (b_top - garment_top_after_scale) + z_nudge`.
That is correct for a *foreign* garment of unknown position. It is **wrong for
these garments**, which were draped on this exact body and are therefore already
in the correct world position — only 10× too large. Any bone-align drags them
off their authored placement. On the last run this applied `dz = -0.0970` and
pushed the pari's straps below the shoulder and its hem down to the hip.

### The rule

**A garment's correct final world position is exactly its raw census z-range
divided by 10.** Nothing else. Use `z_nudge` purely to cancel the pipeline's
auto-align so the net placement lands there.

### The procedure (repeat per garment)

1. From the `census` log, note the raw island z-range `[z0, z1]`.
   Target world range is **`[z0/10, z1/10]`**.
   (pari measured `[10.546, 14.613]` → target **`[1.055, 1.461]`**.)
2. Run `prepare`, then measure what you actually got — load the checkpoint and
   print the garment's world-space Z bounds, e.g.

   ```
   "$BLENDER" --background clothing/work/<name>/10_prepare.blend --python-expr "import bpy; o=[x for x in bpy.data.objects if x.name.startswith('GARM_')][0]; zs=[(o.matrix_world@v.co).z for v in o.data.vertices]; print('ZRANGE', min(zs), max(zs))"
   ```
3. If the measured top differs from the target top by more than **0.02 m**,
   adjust: `z_nudge += (target_top - measured_top)`, re-run `prepare`, measure
   again. Two iterations should converge.
4. Only proceed to `fit` once the measured range is within 2 cm of target at
   both ends. State the final measured range in your DONE report.

Cross-check against the body (a gross error should be obvious): pari ≈ waist to
just above shoulder; piupiu ≈ below-knee to waist. Body landmarks: hem/ankle
0.11, knee 0.52, hip 0.95, waist 1.09, bust 1.26, shoulder 1.40, neck 1.41.

**The pari currently in the export folder is WRONG and must be redone** — delete
`Female_Kapahaka_Body.*` and rebuild it with correct placement before moving on.

## Method

Work one garment at a time; get the pari (Body) fully through first, then the
piupiu (Legs). Suggested sequence per garment:

1. `census` stage — see what islands/materials actually exist. Read the printed
   stats and `clothing/work/<name>/census.json`. Let the data drive the config.
2. Write/adjust `clothing/configs/<name>.json` accordingly.
3. Run `prepare` → `fit` → `reduce` → `skin` → `export`. Skip `bake` (it is
   optional, Cycles-slow, and these have no high-poly detail worth baking).
4. After each stage, verify **numerically** (you cannot see the QA renders —
   their existence proves nothing). Print vert/tri counts and world-space
   bounds from the checkpoint .blend and check them against expectations. If a
   stage errors, read the traceback and adapt the config.

The pipeline is data-driven: **prefer fixing the config over editing
`garment_pipeline.py`.** If you find a genuine bug or a missing capability in the
pipeline, you may make a small, surgical, well-commented edit — but say so
clearly in your DONE summary.

The skirt (`piupiu`, Legs slot) is the harder one: read the README's notes on
skirt handling (`weights: dress` pelvis-gradient, cone proxy, why skirts are not
decimated) and apply what fits. It is a straight A-line skirt, not pleated.

## Success criteria (all must hold)

1. `Female_Kapahaka_Body.gltf` and `Female_Kapahaka_Legs.gltf` exist in the
   export dir above (with their `.bin` companions).
2. Each exported file contains a mesh skinned to a **65-bone** armature with
   Quaternius bone names (the pipeline prints verification info — capture it).
3. Vert/tri counts are sane (roughly the input magnitudes, not zero, not
   millions).
4. The QA renders show a garment that still looks like a garment (not shredded,
   not collapsed, not inside-out).

Verify claims with commands; do not assert success you have not checked.

## Rules

- **Do not** run git commit/push, do not install packages, do not touch `.env`.
- **Do not** modify anything under `tools/tailor/` — those are approved source
  assets. Read them only.
- Do not re-run Marvelous Designer; it is not scriptable from here and its UI is
  not available to you.
- Work in small verifiable steps. One command per turn.
- Blender runs are slow (a stage can take minutes). That is normal — run them
  with a single command and wait for the output.
- If you get truly blocked, emit `DONE:` with a precise description of the
  blocker, what you tried, and what you recommend. A clear failure report is far
  more useful than silent thrashing.

## Report

When finished, emit `DONE:` with:
- which files were produced and where,
- the final config(s) you settled on and any notable parameter choices,
- verification output proving the bone count / vert counts,
- anything that looks wrong or needs a human eye,
- any edit you made to `garment_pipeline.py`.