chore(agents): migrate to agents.md protocol — .agents/ wiki/plans/rules/skills

Root AGENTS.md is now a thin entry point + knowledge map; the batch-workflow
detail it duplicated already lived in .claude/skills/animation/SKILL.md.
Folded docs/ (dances registry + iclone-bridge stub), root plans/, and
devops-reports/ into .agents/wiki/ and .agents/plans/ per the per-repo .agents/
convention. Added .agents/SOUL.md, .agents/AGENTS.md, wiki/ARCHITECTURE.md,
wiki/architecture/, and wiki/master-plan.md (derived from the closed plans +
the dance registry's live ceremony-slot table). Fixed doc-path references in
exchange/GUIDE.md, the animation skill, and the iclone-bridge stub. All moves
via mv (git detected as renames) — no content deleted.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.agents/AGENTS.md

@@ -0,0 +1,11 @@
+# .agents/AGENTS.md — registry + delegation
+
+Detailed layer behind root `AGENTS.md`. This repo has no repo-specific
+multi-agent registry beyond:
+
+- **`loop-qc`** (`.claude/agents/loop-qc.md`) — sub-agent for the loop-QC pass
+  on converted GLBs; use it instead of hand-running `tools/loop_qc.py` when
+  checking a batch of clips.
+
+For cross-repo agent roster, MCP services, and delegation rules, see the hub:
+`tinqs-ltd/docs/.agents/AGENTS.md`.

.agents/SOUL.md

@@ -0,0 +1,26 @@
+# SOUL.md — animation repo identity
+
+Inherits the shared identity, values, and confidentiality rules from the hub:
+`tinqs-ltd/docs/.agents/SOUL.md`. Read that first if this is your first session
+on any Tinqs repo.
+
+## What this repo is
+
+The animation-pipeline hub and Mac↔PC bridge for Ariki. iClone 8 + Video Mocap
+run on Jeremy's Windows PC; Blender 5, the retarget tools, and `ariki-game` live
+on both machines. This repo carries the skills, tools, and files-in-flight that
+turn PC-side motion capture (iClone renders, video mocap) into game-ready
+Quaternius-rig GLB clips consumed by `ariki-game`.
+
+## Scope
+
+- **In scope:** FBX→GLB retargeting (Blender headless), loop QC and loop-fixing,
+  dance/clip naming and the registry, boat/prop export, the exchange-folder
+  bridge protocol, and the skills that encode iClone/mocap operator knowledge.
+- **Out of scope:** game-side rendering, ClipCatalog code, dance ceremony
+  design (owned by `ariki-game`) — this repo only produces and ships the assets.
+
+## Confidentiality
+
+Same as the hub: this repo is private/internal. No special classified material
+lives here (Cosmos-related confidentiality does not apply to animation tooling).

.agents/rules/README.md

@@ -0,0 +1,7 @@
+# rules/ — always-on conventions for this repo
+
+No repo-specific rules beyond what's already always-on in root `AGENTS.md`
+(git via `tinqs push`/`tinqs pull`, stage-by-explicit-path, naming law) and the
+shared hub rules at `tinqs-ltd/docs/.agents/rules/`. Add a file here when a
+convention needs to be enforced repo-wide and doesn't fit in `AGENTS.md`'s
+thin-entry budget.

.agents/skills/README.md

@@ -0,0 +1,18 @@
+# skills/ — playbooks
+
+This repo's operator playbooks are Claude-Code-native skills and live at
+`.claude/skills/` (auto-discovered by Claude Code), not duplicated here:
+
+| Skill | Covers |
+|---|---|
+| `animation` | Operator playbook — the batch workflow, naming, loop QC, gotchas |
+| `animation-creation` | Authoring new clips on the shared Quaternius skeleton |
+| `iclone-video-mocap` | iClone 8 + Video Mocap: filming, cleanup, FBX export |
+| `pose-estimation` | Video→pose-landmark extraction (MediaPipe) |
+| `retarget-animations` | Deprecated early retarget notes, kept for history |
+
+An agent-level playbook (`loop-qc`) lives at `.claude/agents/loop-qc.md`. Follow
+the per-repo convention (`.agents/skills/` as the canonical location) once this
+repo's skills are ported off `.claude/`; until then this file is the pointer so
+there's a single place agents look, per the SoT rule (no second source of
+truth).

.agents/wiki/ARCHITECTURE.md

@@ -0,0 +1,90 @@
+# Architecture — animation pipeline
+
+Entry point to architecture law for this repo. Per-system detail lives in
+`.agents/wiki/architecture/`.
+
+## The one-sentence shape
+
+PC-side motion capture (iClone 8 + Video Mocap) → this repo (Mac↔PC bridge,
+Blender-headless retargeting, loop QC) → `ariki-game` (Quaternius-rig GLB
+consumption via ClipCatalog).
+
+## Machines and where things live
+
+| Machine | Owns |
+|---|---|
+| PC (Windows) | iClone 8 + Video Mocap plugin — authors motion, exports FBX |
+| Mac (and PC) | Blender 5.1.2, this repo's retarget tools, `ariki-game` checkout |
+
+Files move machine-to-machine only through `exchange/` in this repo, synced
+with `tinqs push`/`tinqs pull` (Git LFS for `.fbx/.glb/.mp4/.task` — see
+`.gitattributes`). Raw `git pull` hangs on LFS in tinqs.com repos.
+
+## Pipeline stages
+
+1. **Capture (PC)** — iClone export, Blender preset, Range=All, Preserve Bone
+   Names ON → `exchange/incoming-fbx/`.
+2. **Retarget (either machine)** — Blender-headless, source-specific retargeter
+   in `tools/`, all bake onto the shared Quaternius rig and export a
+   mesh-stripped GLB with one NLA track per clip:
+   - `cc_retarget.py` — Reallusion CC/iClone `CC_Base_*` FBX (60fps; rejects
+     2-frame `_TempMotion` exports as a guard against motion-less takes)
+   - `mixamo_retarget.py` — Mixamo FBX (prefix auto-detect)
+   - `kevin_retarget.py` — Kevin Iglesias Unity FBX (`B-*` rig; hardcoded
+     target path, non-portable)
+   - `mocap_retarget.py` — MediaPipe pose JSON → GLB (rotation solving, no
+     source armature)
+   → `exchange/converted-glb/`.
+3. **Loop QC** — `tools/loop_qc.py` (pre-commit gate: pose/velocity/root-drift
+   continuity across the seam, exit 0 = smooth). Fixers when it fails:
+   `tools/loop_fix.py` (de-drift/trim/seam-blend → `exchange/looped-glb/`) and
+   `tools/pingpong_bake.py` (palindrome bake, seam-perfect but motion reverses
+   at the turn → `exchange/pingpong-glb/`, clip suffix `PP`). Every adopted
+   dance ships as a base clip + `_pp` pair.
+4. **Ship** — commit + `tinqs push` the GLBs in this repo, then copy into
+   `ariki-game/assets/quaternius/dancegen/` (auto-discovered by ClipCatalog as
+   `<pack>/<ClipName>` — also watches `kevin/`, `mixamo/`), write one dance JSON
+   per clip in `ariki-game/assets/dances/`, `game.sh import`, verify clip names
+   match GLB `animations[].name` exactly, commit in ariki-game (push only when
+   Jeremy asks).
+5. **Post-ingest QC (game side, out of this repo)** — `ariki-game/tools/anim_qc.py`
+   re-checks world-space seam continuity + renders a seam-cross video for eye
+   review. Two QC tools by design: this repo's gate is pre-commit/local-space,
+   the game's is post-ingest/world-space.
+
+## Naming law
+
+Full detail: `.agents/wiki/dances/REGISTRY.md` (source of truth — do not
+duplicate its content elsewhere). Summary: new takes get a provisional `nd_##`
+id (never a content-derived name); a take is renamed to its ceremony code
+(snake_case of the sim's `DanceType` enum + index) only once Jeremy assigns it
+to a specific ceremony, via `tools/rename_clip.py`. Rejected/superseded takes
+are archived (`archive/`), never deleted; numbers are never reused.
+
+## Canonical target rig
+
+All retargeters bake onto ariki-game's
+`assets/quaternius/base-characters/.../Godot - UE/Superhero_Male_FullBody.gltf`.
+Run from this repo, `--target` must be passed explicitly (the tool's default
+path is ariki-relative and won't resolve here). The rig/pack standard itself
+(65-bone Quaternius UE-named skeleton, hero body `Ariki_Female_QuatSkin.glb`) is
+governed by `ariki-game/.humans/animation-bone-sources.html` and
+`ariki-game/.agents/wiki/quaternius-ual-packs.md` — this repo's iClone/mocap
+lane is explicitly a separate clip source (not UAL1/UAL2/Kevin/Mixamo), landing
+in `dancegen/` only.
+
+## Tool provenance / mirroring
+
+`tools/cc_retarget.py`, `mixamo_retarget.py`, `kevin_retarget.py`,
+`mocap_retarget.py` are **mirrors of `ariki-game/tools/`** — the game copies are
+authoritative; re-copy from ariki-game when they change (they have silently
+diverged before). `.claude/skills/` here mirror a subset of `ariki-game/.claude/skills/`
+plus `~/.claude/skills/pose-estimation` — see `README.md` Provenance section.
+
+## See also
+
+- `.agents/wiki/architecture/` — per-system detail (currently: this file covers
+  the whole pipeline; split out if a subsystem grows its own doc).
+- `.agents/wiki/dances/REGISTRY.md` — naming/registry source of truth.
+- `.agents/wiki/iclone-bridge.md` — PC-lane routing stub.
+- `.agents/wiki/devops-reports/` — point-in-time audits and convergence reports.

.agents/wiki/architecture/README.md

@@ -0,0 +1,12 @@
+# architecture/ — per-system detail
+
+This repo's pipeline is small enough that `.agents/wiki/ARCHITECTURE.md` covers
+it end to end today; nothing has grown large enough yet to need its own
+per-system doc here. Split a topic out into this folder (and link it from
+`ARCHITECTURE.md`) when it does — likely candidates as the repo grows:
+
+- Retarget-tool internals (per-source rig mapping, bone-name conventions).
+- Loop QC/fix algorithms (pose-gap, velocity-gap, root-drift math).
+- The exchange-folder state machine (`exchange/GUIDE.md` currently owns this —
+  promote here if it needs architecture-level treatment beyond an operator
+  guide).

.agents/wiki/iclone-bridge.md

@@ -10,7 +10,7 @@ GLBs.
 | Need | Go to |
 |---|---|
 | Which exchange/ folder to use, when files move/archive | `exchange/GUIDE.md` |
-| Naming (nd_## → ceremony codes), loop-pair rule, registry | `docs/dances/REGISTRY.md` |
+| Naming (nd_## → ceremony codes), loop-pair rule, registry | `.agents/wiki/dances/REGISTRY.md` |
 | Filming rules, iClone/AccuFACE settings, mocap cleanup, FBX export | `iclone-video-mocap` skill (`.claude/skills/` here and in ariki-game) |
 | CC FBX → Quaternius GLB conversion | `tools/cc_retarget.py` (mirror of ariki-game — game copy is authoritative) |
 | Looping (`_pp`) + QC gates | `tools/pingpong_bake.py` + `tools/loop_qc.py`; game-side `anim_qc.py` (split documented in REGISTRY.md) |

.agents/wiki/master-plan.md

@@ -0,0 +1,56 @@
+# Master plan — animation repo
+
+What's in flight and recently shipped. See `.agents/plans/` for the closed-out
+plan/results docs behind these items; see `.agents/wiki/dances/REGISTRY.md` for
+the live per-clip status table (source of truth, not duplicated here).
+
+## Recently shipped (closed plans, folded into wiki)
+
+- **Animation-gen pipeline** (2026-07-13) — the FBX→Blender-retarget→GLB→dance-JSON
+  bridge itself; core of `.agents/wiki/ARCHITECTURE.md` today.
+- **Animation skills adoption** (2026-07-13) — `.claude/skills/animation*`,
+  `iclone-video-mocap`, `pose-estimation` brought in as repo skills.
+- **Loop fix** (2026-07-16, plan + results) — `tools/loop_fix.py` (de-drift/trim/
+  seam-blend) and `tools/pingpong_bake.py` shipped; every adopted dance now ships
+  as a base clip + `_pp` pair, gated by `tools/loop_qc.py`.
+- **Boat prop export** (2026-07-17, plan + fixes + results) — `tools/export_boat_prop.py`
+  staging pipeline for the boat action-clip set (see "Boat actions" below).
+- **Animation-standard convergence** (2026-07-23/24, `.agents/wiki/devops-reports/`) —
+  full audit against ariki-game's animation-standardization contract. Result:
+  pipeline core already conformant (100% of runtime clip GLBs on the 65-bone
+  Quaternius rig, all `_pp` pairs present, dance JSONs clean). Fixes landed:
+  registry corrections (`tide_dance_01` has no sim enum entry — flag before
+  filming; `rain_dance_01` confirmed in-enum), `iclone-bridge.md` written
+  (previously a dead reference), QC-tool split documented (`loop_qc.py` here =
+  pre-commit gate, `ariki-game/tools/anim_qc.py` = post-ingest gate).
+- **agents.md migration** (2026-07-24, this change) — repo restructured onto the
+  open agent protocol: root `AGENTS.md` (thin) + `.agents/` (SOUL, wiki, plans,
+  skills-pointer). `docs/` and root `plans/`/`devops-reports/` folded into
+  `.agents/wiki/`.
+
+## In flight — ceremony dance slots awaiting a take
+
+Per `.agents/wiki/dances/REGISTRY.md`, adopted so far: `fertility_dance_01`
+(hula), `taming_dance_01`, `war_dance_01` (haka) — each shipped with its `_pp`
+loop. One provisional take (`nd_01`, baraka1) is filmed and QC-passed but not
+yet assigned to a ceremony. Still **awaiting a take**: `water_dance_01`,
+`fire_dance_01`, `food_dance_01`, `sailing_dance_01`, `building_dance_01`,
+`colony_shield_dance_01`, `age_progression_dance_01`, `star_watching_dance_01`,
+`rain_dance_01`. `tide_dance_01` has no confirmed sim `DanceType` entry — resolve
+with Ozan before filming.
+
+## In flight — boat action clips
+
+Staging tooling (`tools/export_boat_prop.py`) is built and the boat prop rig
+verified; the action-clip set itself is **awaiting takes**: `boat_dive`,
+`boat_climb`, `boat_collect`, `boat_row_loop`, `boat_fish_loop`,
+`boat_sail_idle`. Two boat-adjacent clips are already live in-game
+(`CanoeDismount`/`CanoeSitIdle`, `run_to_dive`) but predate this registry and
+need a `boat_*` code assigned at the next adoption pass.
+
+## Open threads
+
+- `tools/kevin_retarget.py` has a hardcoded, non-portable target path — fine for
+  now, flagged in `AGENTS.md` gotchas.
+- `.claude/skills/retarget-animations/` is kept only for history (deprecated,
+  superseded by the per-source retargeters in `tools/`).

.claude/skills/animation/SKILL.md

@@ -33,7 +33,7 @@ This skill is the accumulated **do-it-this-way** knowledge from real runs.
 ```
 Blender here is **5.1.2**. When running from this repo the `--target` is **required** — the tool's default target path is ariki-relative and won't resolve.
 
-## Naming system (registry: `docs/dances/REGISTRY.md` — read it, it is the source of truth)
+## Naming system (registry: `.agents/wiki/dances/REGISTRY.md` — read it, it is the source of truth)
 Two-stage names, following the **game's item-id convention (lowercase snake_case)**.
 **New dances get a provisional id, never a content name**: at conversion, assign the
 next free `nd_##` from the registry — pack `nd_08`, clip `ND08`, JSON `nd_08.json`,

AGENTS.md

@@ -1,112 +1,56 @@
 # AGENTS.md — animation repo
 
-Guidance for AI agents working in `local.repo/animation`. This repo is Jeremy's
+Entry point for AI agents working in `local.repo/animation` (all tools: pi,
-animation-pipeline hub **and** the Mac↔PC bridge that carries iClone exports into
+Claude Code, Cursor). This repo is Jeremy's animation-pipeline hub **and** the
-`ariki-game`. iClone 8 + Video Mocap live on the PC; Blender 5, the retarget tools,
+Mac↔PC bridge that carries iClone/mocap exports into `ariki-game`. iClone 8 +
-and the game repo live on both machines.
+Video Mocap live on the PC; Blender 5, the retarget tools, and the game repo
+live on both machines.
 
-Deeper knowledge lives in the repo skills (`.claude/skills/`): use **`animation`**
+Read `.agents/SOUL.md` at session start, then use the knowledge map below —
-for the operator's playbook and hard-won lessons, **`animation-creation`** for
+this file stays thin; the operational detail lives in `.claude/skills/` and
-authoring new clips, **`iclone-video-mocap`** for iClone-side "how do I X", and
+`.agents/`.
-**`pose-estimation`** for video→pose extraction. `docs/dances/REGISTRY.md` is the
-source of truth for clip names. This file is the fast orientation; the skills and
-registry are authoritative.
 
-## The batch workflow ("process the incoming animations")
+## Knowledge map
 
-1. **Pull first** — `tinqs pull` (raw `git pull` hangs on LFS in tinqs.com repos).
+| Category | Path | When |
-   Incoming FBX + textures + JSON land in `exchange/incoming-fbx/`.
+|---|---|---|
-2. **Retarget each FBX** → GLB in `exchange/converted-glb/` (command below).
+| Identity | `.agents/SOUL.md` | always-on |
-   Every dance ships as a **pair**: also bake its loop variant with
+| 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 |
-   `tools/pingpong_bake.py` → `exchange/pingpong-glb/<id>_pp.glb` (clip `<Clip>PP`).
+| Architecture (pipeline stages, canonical rig, tool provenance) | `.agents/wiki/ARCHITECTURE.md` | consult when touching the pipeline |
-3. **Commit + push the GLBs in this repo** with `tinqs push` (self-heals auth,
+| Per-system architecture detail | `.agents/wiki/architecture/` | consult-when |
-   uploads LFS direct-to-S3). Report the commit hash.
+| In-flight work + recently shipped | `.agents/wiki/master-plan.md` | check before starting new work |
-4. **Copy GLBs into ariki-game** `assets/quaternius/dancegen/`, write one dance
+| Dance/clip naming registry (source of truth for names) | `.agents/wiki/dances/REGISTRY.md` | always-on when naming or shipping a clip |
-   JSON per clip in `ariki-game/assets/dances/`.
+| PC-lane routing stub | `.agents/wiki/iclone-bridge.md` | consult-when |
-5. **Loop QC gate** — run `loop_qc.py` on each GLB; flag anything not smooth
+| Point-in-time audits / convergence reports | `.agents/wiki/devops-reports/` | consult-when |
-   *before* it ships.
+| Open/executing plans | `.agents/plans/` | consult-when |
-6. **Import** so Godot generates sidecars: `bash tools/game.sh import` (ariki root).
+| Other operator playbooks (iClone/mocap, clip authoring, pose estimation) | `.claude/skills/` (index: `.agents/skills/README.md`) | consult-when |
-7. **Verify** clip names, then commit in ariki-game.
+| Loop-QC sub-agent | `.claude/agents/loop-qc.md` | consult-when |
-8. **Launch the test bed only after asking Jeremy.**
+| Repo-wide conventions | `.agents/rules/` | always-on |
-9. Leave `exchange/` cleanup until Jeremy confirms the batch looks right in-game.
+| Exchange-folder operator guide (which folder, when files move/archive) | `exchange/GUIDE.md` | consult-when doing a batch |
-
-### Canonical retarget command
-```bash
-/Applications/Blender.app/Contents/MacOS/Blender --background --python tools/cc_retarget.py -- \
-  --src exchange/incoming-fbx/<take>.fbx \
-  --out exchange/converted-glb/<pack>.glb --name <ClipName> \
-  --target "/Users/jeremykashkett/Tinqs/local.repo/ariki-game/assets/quaternius/base-characters/Universal Base Characters[Standard]/Base Characters/Godot - UE/Superhero_Male_FullBody.gltf"
-```
-Blender is **5.1.2**. `--target` is **required** when running from this repo (the
-tool's default target path is ariki-relative and won't resolve here). Other
-retargeters: `mixamo_retarget.py` (Mixamo), `kevin_retarget.py` (Kevin Iglesias
-`B-*` rig, hardcoded target), `mocap_retarget.py` (MediaPipe pose JSON).
-
-## Naming (see `docs/dances/REGISTRY.md`)
-
-Lowercase snake_case, matching the game's item-id convention. **New takes get a
-provisional `nd_##` id, never a content name** — pack `nd_08`, clip `ND08`, JSON
-`nd_08.json`, variants `nd_08_pp` / `ND08PP`. Only when Jeremy **adopts** a take
-for a ceremony is it renamed to its dance code (snake_case of the sim's `DanceType`
-enum + index, e.g. `war_dance_01` / `WarDance01`). Never guess the ceremony —
-Jeremy assigns it. Rename via `tools/rename_clip.py` + JSON + registry update.
-Rejected takes are **archived, never deleted**; numbers are never reused. Update
-the registry row on every convert/adopt/archive.
-
-- Pack name = GLB basename (lowercase); clip name = `--name` baked into the GLB.
-- Clip ref in JSON = `<pack>/<ClipName>` (e.g. `nd08/ND08`).
-- ClipCatalog auto-discovers anything in `dancegen/` (also `kevin/`, `mixamo/`) —
-  no code change needed.
-
-## Loop QC
-
-The game loops with Godot `LoopMode.Linear` (last keyframe → frame 0). A clip only
-looks right if pose, motion velocity, and root position are continuous across the
-seam — raw takes rarely are. QC every clip:
-```bash
-/Applications/Blender.app/Contents/MacOS/Blender --background --python tools/loop_qc.py -- \
-  --src exchange/converted-glb/<pack>.glb   # exit 0 = SMOOTH, 1 = NOT SMOOTH, 2 = error
-```
-Fixers (no iClone round-trip): `tools/loop_fix.py` (de-drift + trim + seam blend →
-`exchange/looped-glb/`) and `tools/pingpong_bake.py` (palindrome bake, seam-perfect
-but motion reverses at the turn — prefer for sway-heavy dances). Re-run `loop_qc.py`
-to confirm exit 0. Or use the `loop-qc` agent.
-
-## Gotchas that have actually bitten
-
-- **2-frame `_TempMotion` FBX = no motion.** The tool rejects by frame count, not
-  name; that's the guard working. Re-export from iClone with Include/Export Motion.
-- **A-pose arms.** CC/iClone bind in A-pose. Eyeball arm orientation in the test
-  bed on the first clip of any new source; re-export with *Use T-Pose As Bind Pose*
-  if wrong.
-- **Verify GLB `animations[].name` == JSON clip ref** before shipping — a mismatch
-  is a silent no-play.
-- **Commit the `.glb.import` sidecar with the GLB** (Godot embeds `uid://` there;
-  no separate `.uid`). GLB + `.import` + JSON go together.
-- **`game.sh import` warnings are pre-existing noise** — only `errors` matter.
-- **Green verify ≠ correct.** An agent-authored gate once passed an upside-down
-  boat export. Always render and eyeball a new visual asset before shipping.
-
-## Repo etiquette
-
-- **Don't touch unrelated uncommitted work.** ariki-game often has in-flight files;
-  stage only this batch's files **by explicit path**, never `git add -A`.
-- Use **`tinqs push` / `tinqs pull`**, not raw git — this repo uses Git LFS for
-  `.fbx/.glb/.mp4/.task`. Report the commit hash after pushing.
-- Commit co-author line: `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
-- **ariki-game commits stay local until Jeremy asks to push** — pushing the game
-  repo is not part of the bridge steps.
-- **Ask before launching the game.** `SCENE=dance_test_bed bash tools/game.sh spawn`
-  (from ariki root); `animation_showcase` pages every clip. Never use `*RM` /
-  `*RootMotion` variants — everything is in-place. If you pipe spawn through `tail`,
-  the log stays 0 bytes until exit — confirm via the lease file + `pgrep`, don't
-  assume it failed.
 
 ## Layout
 
-- `.claude/skills/` — repo skills (see intro); `.claude/agents/loop-qc.md`.
+```
-- `tools/` — Blender-headless retargeters, loop tools, prop export, `rename_clip.py`.
+AGENTS.md          ← you are here
-- `exchange/` — files in flight: `incoming-fbx/`, `converted-glb/`, `looped-glb/`,
+.agents/           ← agent context: SOUL, wiki (architecture/master-plan/registry/
-  `pingpong-glb/`, `outgoing-props/`, `reference-video/`, `INBOX/`.
+                     devops-reports), plans, rules, skills-pointer
-- `docs/` — `dances/REGISTRY.md`, `iclone-bridge.md`.
+.claude/           ← Claude-Code-native skills + agents (auto-discovered)
-- `plans/` — pipeline design docs. `archive/` — retired takes. `devops-reports/`.
+tools/             ← Blender-headless retargeters, loop tools, prop export
+exchange/          ← files in flight between Mac and PC (see exchange/GUIDE.md)
+archive/           ← retired takes — never deleted, never renumbered
+```
+
+## Git
+
+- Branch is **`main`**. Sync via **`tinqs push`/`tinqs pull`** (not raw git —
+  this repo uses Git LFS for `.fbx/.glb/.mp4/.task`; a plain `git pull` hangs).
+  Report the commit hash after pushing.
+- **Stage explicit paths, never `git add -A`** — ariki-game and this repo often
+  carry unrelated in-flight files.
+- Never commit secrets.
+
+## The rule that bites most often
+
+**Green verify ≠ correct.** An agent-authored gate once passed an upside-down
+boat export. Always render and eyeball a new visual asset before shipping —
+full gotcha list in `.claude/skills/animation/SKILL.md`.

README.md

@@ -41,7 +41,7 @@ into the game repo.
   - `kevin_retarget.py` — Kevin Iglesias Unity FBX (`B-*` rig; hardcoded target path — non-portable)
   - `mocap_retarget.py` — MediaPipe pose JSON → GLB (rotation solving, no source armature)
   - `bake_run_punch.mjs` — composite upper/lower clip baking reference
-- `plans/` — pipeline design docs (animation generation pipeline, skills adoption)
+- `AGENTS.md` / `.agents/` — agent context (identity, wiki, plans, rules); see `AGENTS.md` for the knowledge map
 
 ## Canonical target rig
 

exchange/GUIDE.md

@@ -6,8 +6,8 @@ below. If you are an agent dropping files into this repo, or processing a batch,
 this file tells you which folder to use, when a file moves to the next stage, and
 when the previous version gets archived.
 
-Related docs: `docs/dances/REGISTRY.md` (naming — the source of truth),
+Related docs: `.agents/wiki/dances/REGISTRY.md` (naming — the source of truth),
-`docs/iclone-bridge.md` (PC-lane overview), and the `animation` skill (batch workflow details).
+`.agents/wiki/iclone-bridge.md` (PC-lane overview), and the `animation` skill (batch workflow details).
 
 **Tool mirroring rule (audit 2026-07-23):** the retargeters in `tools/`
 (`cc_retarget.py`, `mixamo_retarget.py`, `kevin_retarget.py`, `mocap_retarget.py`) are
@@ -79,7 +79,7 @@ always.
 | `PINGPONG_GLB` / `LOOPED_GLB` | The loop variant (`<pack>_pp` / seam-fixed). **Every shipped dance is a pair: base + loop.** Must pass `tools/loop_qc.py` (exit 0) | Copied into `GAME_DANCEGEN` alongside the base clip |
 
 Rules on this track:
-- **Naming:** new takes get the next free `nd_##` from `docs/dances/REGISTRY.md`
+- **Naming:** new takes get the next free `nd_##` from `.agents/wiki/dances/REGISTRY.md`
   at conversion — never a content name. Update the registry row at every
   conversion/adoption/archive.
 - **FBX stays in `INCOMING_FBX` after conversion** (it's the re-export source)
@@ -151,7 +151,7 @@ These are big (100 MB+) LFS blobs.
    `ARCHIVE` is ever renamed or reused.
 3. **Registry numbers are never reused.** An archived `nd_03` retires the number
    forever.
-4. Every archive action gets a **registry update** (`docs/dances/REGISTRY.md`)
+4. Every archive action gets a **registry update** (`.agents/wiki/dances/REGISTRY.md`)
    when it involves a tracked dance.
 5. Game-side counterparts (GLBs/JSON already copied into ariki-game) archive to
    `<ariki-game>/archive/dances/` (which is `.gdignore`d), in the same commit