docs+tools: working-file policy, lane pruner, and a human MD explainer

Two pieces of work.

1. Keep milestones, not steps. Staged NN_*.py lanes were saving a full
   ~80 MB .blend per attempt, so Lena's lane reached 3.0 GB of which 2.2 GB
   was 30 .blend files -- five snapshots to land one crotch fix, five more
   for the bra. The .py recipes are the real history; the blends are cache.

   - .agents/rules/working-files.md: four-tier policy (KEEP / MASTER /
     SCRATCH / UNKNOWN) + how to work a lane.
   - tools/prune_lane.py: classifies a lane and prunes the scratch tier.
     Dry-run by default. Reads a per-lane .lanekeep manifest, flags
     binaries byte-identical to a registered original (canonical name
     always survives a duplicate pair), and never auto-deletes a .blend
     with no step script beside it -- those cannot be rebuilt.
   - .gitignore: scratch patterns can never be committed.

   Dry run on characters/female/lena_nude reports 2.3 GB reclaimable.
   Not applied -- that lane had a live Blender session at the time.

2. .humans/marvelous-designer.html: how we author garments in Marvelous
   Designer, written for people rather than agents -- the six-step process,
   what has been made, the traps that cost hours, and what is still
   unsolved. Matches the .humans/ HTML convention in ariki-game.

Also committing the docs the AGENTS.md knowledge map and the new page
reference, so they are not dangling: the clothing-lane architecture page,
the marvelous-designer skill, and the two screenshots the page embeds.

characters/ is deliberately untracked and stays that way -- it holds GBs of
blends and GLBs, and .gitattributes does not LFS-track .blend.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-06 12:05:46 -07:00
parent 854dbb5ce4
commit d1030def4e
13 changed files with 1729 additions and 6 deletions
+18 -1
View File
@@ -18,6 +18,9 @@ this file stays thin; the operational detail lives in `.claude/skills/` and
| Batch workflow, canonical retarget command, naming, loop QC, gotchas, repo etiquette | `.claude/skills/animation/SKILL.md` | always-on — read before any batch or clip work |
| Architecture (pipeline stages, canonical rig, tool provenance) | `.agents/wiki/ARCHITECTURE.md` | consult when touching the pipeline |
| Per-system architecture detail | `.agents/wiki/architecture/` | consult-when |
| **Clothing lane** — how a reference image becomes a worn in-game outfit (both halves, and where they meet) | `.agents/wiki/architecture/clothing-lane.md` | read before any garment/outfit work |
| Garment authoring in Marvelous Designer (bridge, drafting, draping, QC) | `.claude/skills/marvelous-designer/SKILL.md` | always-on for garment authoring |
| Garment mesh → game-ready skinned outfit GLB (headless Blender) | `clothing/README.md` | always-on for the game-ification half |
| In-flight work + recently shipped | `.agents/wiki/master-plan.md` | check before starting new work |
| Dance/clip naming registry (source of truth for names) | `.agents/wiki/dances/REGISTRY.md` | always-on when naming or shipping a clip |
| PC-lane routing stub | `.agents/wiki/iclone-bridge.md` | consult-when |
@@ -26,7 +29,9 @@ this file stays thin; the operational detail lives in `.claude/skills/` and
| Other operator playbooks (iClone/mocap, clip authoring, pose estimation) | `.claude/skills/` (index: `.agents/skills/README.md`) | consult-when |
| Loop-QC sub-agent | `.claude/agents/loop-qc.md` | consult-when |
| Repo-wide conventions | `.agents/rules/` | always-on |
| **Working files** — keep milestones, not steps: which `.blend`/render dirs survive a staged lane, and how to prune the rest | `.agents/rules/working-files.md` | read before running any staged `NN_*.py` lane |
| Exchange-folder operator guide (which folder, when files move/archive) | `exchange/GUIDE.md` | consult-when doing a batch |
| Human-facing explainer pages (HTML, for Jeremy/Özlem — not a source of truth) | `.humans/` | consult-when explaining the repo to a person |
## Layout
@@ -35,11 +40,23 @@ AGENTS.md ← you are here
.agents/ ← agent context: SOUL, wiki (architecture/master-plan/registry/
devops-reports), plans, rules, skills-pointer
.claude/ ← Claude-Code-native skills + agents (auto-discovered)
tools/ ← Blender-headless retargeters, loop tools, prop export
tools/ ← Blender-headless retargeters, loop tools, prop export,
md_bridge* (drive Marvelous Designer), tailor/ (garment
authoring: recipes, measurements, QC, screenshots)
characters/ ← character body models: originals/ (read-only Tripo sources) +
per-character working folders (male/mako, female/lena).
Naming law in characters/REGISTRY.md — applies to all new
derived models
clothing/ ← garment mesh → game-ready outfit GLB (staged Blender pipeline)
garments/ ← raw incoming garment sources + design advice notes
exchange/ ← files in flight between Mac and PC (see exchange/GUIDE.md)
archive/ ← retired takes — never deleted, never renumbered
```
Two lanes run through this repo: the **animation lane** (motion → clips) and the
**clothing lane** (garments → outfits). They converge on the same 65-bone
Quaternius skeleton.
## Git
- Branch is **`main`**. Sync via **`tinqs push`/`tinqs pull`** (not raw git —