Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

docs: documentation index with the four pipelines; static-pose recipe merged into breathing

Soohong Kim05fd151bb7b5
diff --git a/SKILL.md b/SKILL.md
index 144e41d..5fa70b3 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -126,7 +126,7 @@ One job each, all under `scripts/` (wrappers) ↔ `sprite_gen/<domain>/` (impl).
| `unpack_atlas_run.py` (`unpack-atlas`) · `export_curated_pngs.py` (`export-pngs`) | finished sheet / PNG folder → curator-ready run · curated frames → named PNGs (`curated/`) | [`docs/curation.md`](docs/curation.md) |
| `cutout` · `slice_sheet_cells.py` (`slice-sheet`) · `dev/check_visible_magenta.py` | imported-image background removal (white matte / chroma engine) · multi-figure sheet → per-cell cuts · screenshot chroma-leak guard | [`docs/sheet-slicing.md`](docs/sheet-slicing.md) |
-Breathing (idle) and static-pose rows are a **post-process layer** declared in `curation.json` (`states.<state>.breathe`) and baked by compose — never a script step; the contract (anatomy detection, editor, rigid boundary, `migrate-breathe`) is [`docs/breathing.md`](docs/breathing.md) and [`docs/static-pose-recipe.md`](docs/static-pose-recipe.md).
+Breathing (idle) and static-pose rows are a **post-process layer** declared in `curation.json` (`states.<state>.breathe`) and baked by compose — never a script step; the contract (anatomy detection, editor, rigid boundary, `migrate-breathe`) is [`docs/breathing.md`](docs/breathing.md) and [`docs/breathing.md`](docs/breathing.md) "정지 자세 행 레시피".
## Workflow (atlas route)
@@ -229,7 +229,7 @@ Leaf docs are one link deep. Walk the branch that matches your task; each doc ow
CONTRACT & STRUCTURE docs/run-contract.md · docs/architecture.md
REQUEST AUTHORING docs/states-and-frames.md · docs/subject-profiles.md · docs/pixel-unfake.md · docs/chroma-alpha.md
GENERATION docs/gen.md · docs/video.md · docs/video-pipeline.md · docs/frame-interpolation.md · docs/seamless-video-loop.md
-CURATION docs/curation.md · docs/breathing.md · docs/static-pose-recipe.md
+CURATION docs/curation.md · docs/breathing.md
COLOURWAYS docs/recolor.md
LAYER TRACKS docs/layer-tracks.md
ENGINE EXPORT docs/engine-export.md
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..9a9eee2
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,99 @@
+# sprite-gen documentation index
+
+One tool, four pipelines, one taxonomy. Every verb works alone or as a pipeline stage;
+every doc below owns exactly one concern and the others point at it. Start with the
+pipeline you are running, then follow its contract doc.
+
+```mermaid
+flowchart LR
+ subgraph A["A · atlas rows"]
+ direction LR
+ a1[prepare] --> a2["gen · gen-set"] --> a3[extract] --> a4[curation] --> a5[compose-atlas]
+ end
+ subgraph B["B · video → loop"]
+ direction LR
+ b1[video-canvas] --> b2[video] --> b3[video-frames] --> b4[video-loop]
+ b5[video-set] -.runs all four.-> b1
+ end
+ subgraph C["C · utilities"]
+ direction LR
+ c1[cutout] ~~~ c2[slice-sheet] ~~~ c3[unpack-atlas]
+ end
+ subgraph D["D · post-processing"]
+ direction LR
+ d1[recolor] ~~~ d2[compose-layers] ~~~ d3["breathe (compose)"] ~~~ d4[export-*]
+ end
+```
+
+| Pipeline | Entry doc | Verbs |
+|---|---|---|
+| **A · atlas rows** — one still becomes a runtime sprite sheet | [run-contract.md](run-contract.md) | `prepare` → `gen` / `gen-set` → `extract` → `curation` → `compose-atlas` |
+| **B · video → loop** — one still becomes transparent motion loops | [video-pipeline.md](video-pipeline.md) | `video-canvas` → `video` → `video-frames` → `video-loop`, `video-set` |
+| **C · utilities** — imported images in, clean cuts out | [sheet-slicing.md](sheet-slicing.md) | `cutout`, `slice-sheet`, `unpack-atlas` |
+| **D · post-processing** — finished sheets, refined | [recolor.md](recolor.md) | `recolor`, `compose-layers`, breathing (compose), `export-pngs`, `export-aseprite` |
+
+`sprite-gen --help` prints the same four pipelines and every verb grouped by domain; the
+grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.
+
+## Contract & structure
+
+| Doc | Owns |
+|---|---|
+| [run-contract.md](run-contract.md) | The atlas pipeline's normative contract: stages, the run-dir folder tree, curation-view display, atomic extract, concurrency scope |
+| [architecture.md](architecture.md) | How the code is laid out: domains, stage ownership, the numeric SSoT, the cell model, extraction internals, runtime manifest |
+
+## Request authoring (pipeline A inputs)
+
+| Doc | Owns |
+|---|---|
+| [states-and-frames.md](states-and-frames.md) | Which states to request and how many frames each |
+| [subject-profiles.md](subject-profiles.md) | `character` vs `effect` subjects and the sparse-frame floor they set |
+| [pixel-unfake.md](pixel-unfake.md) | The `fit` / `pixel_unfake` path for pixel-art targets and jitter-free locomotion |
+| [chroma-alpha.md](chroma-alpha.md) | Choosing the chroma key and diagnosing alpha cleanup after extraction |
+
+## Generation (the AI steps)
+
+| Doc | Owns |
+|---|---|
+| [gen.md](gen.md) | `sprite-gen gen` / `gen-set`: providers, default resolution, transparency strategy per provider, row usage |
+| [video.md](video.md) | `sprite-gen video`: image to mp4 through Grok Imagine with the user's own credential |
+| [video-pipeline.md](video-pipeline.md) | Pipeline B engine contract: state canvas, keyed frames, true-period and one-shot cycles, strip/GIF/WebP, the batch |
+| [frame-interpolation.md](frame-interpolation.md) | Generative in-betweens for sprite frames, recorded as a take |
+| [seamless-video-loop.md](seamless-video-loop.md) | Making a non-looping ambient clip loop forever (RIFE seam bridge) — a different job from pipeline B |
+
+## Curation
+
+| Doc | Owns |
+|---|---|
+| [curation.md](curation.md) | The webview, standalone candidate view, finished-sheet editing and every `curation.json` field |
+| [breathing.md](breathing.md) | The idle-breathing post-process layer and the static-pose row recipe |
+| [locomotion-curation.md](locomotion-curation.md) | Motion-phase experiments, manual selected cycles, clean GIF export |
+
+## Post-processing (pipeline D)
+
+| Doc | Owns |
+|---|---|
+| [recolor.md](recolor.md) | Deterministic palette-swap bake, colourway pick, `variants/` and its report |
+| [layer-tracks.md](layer-tracks.md) | Rig runs: `rig` / `track` / `layers` contract and `compose-layers` |
+| [engine-export.md](engine-export.md) | Aseprite-compatible export for Phaser and Flame |
+
+## Specialized inputs (pipeline C and direction runs)
+
+| Doc | Owns |
+|---|---|
+| [directional-anchor-workflow.md](directional-anchor-workflow.md) | Directional / 45° rows: base → direction anchors → rows, the left-right gate |
+| [sheet-slicing.md](sheet-slicing.md) | Multi-figure grid sheets to per-cell standing cuts; the `cutout` routes |
+
+## QA
+
+| Doc | Owns |
+|---|---|
+| [qa-motion.md](qa-motion.md) | Motion Continuity — the blocking judgement of a row as motion |
+
+## Runtime & process
+
+| Doc | Owns |
+|---|---|
+| [interpreter.md](interpreter.md) | Why the project venv is the only interpreter (no global `python3`, no NumPy fallback) |
+| [rename-gate.md](rename-gate.md) | What must move together when a vocabulary word or key is renamed |
+| [troubleshooting.md](troubleshooting.md) | Symptoms of a pipeline that is "quietly wrong", with causes and fixes |
diff --git a/docs/breathing.md b/docs/breathing.md
index fa7cb86..0d9eaaa 100644
--- a/docs/breathing.md
+++ b/docs/breathing.md
@@ -1,11 +1,69 @@
# 호흡(idle breathing) · 정지 자세 행 — 후처리 레이어 계약
-> SKILL.md Script Map 에서 옮겨온 본문(2026-09-09, 허브 슬림화). `compose_sprite_gif.py` / `compose_sprite_atlas.py` 가 굽는 호흡 레이어, 정지 자세 행 레시피, 큐레이션 뷰의 호흡 편집기 계약을 소유한다. 실측 근거·프레임 게이트는 [static-pose-recipe.md](static-pose-recipe.md).
+> SKILL.md Script Map 에서 옮겨온 본문(2026-09-09, 허브 슬림화). `compose_sprite_gif.py` / `compose_sprite_atlas.py` 가 굽는 호흡 레이어, 정지 자세 행 레시피, 큐레이션 뷰의 호흡 편집기 계약을 소유한다. 실측 근거·프레임 게이트는 아래 "정지 자세(Static-Pose) 행 레시피" 절.
-- **에이전트 주도 호흡** (사용자가 "숨쉬기 적용해서 뽑아줘" 라고만 해도 됨): 호흡은 사이드카 필드라 뷰 없이도 켤 수 있다 — (1) `states.<state>.breathe = {"depth": 0.06, "breaths": 1, "lag": 0.1}` 만 쓰면 된다. **경계는 선언하지 않는다** — `sprite_gen/anatomy.py` 가 검출한다. 큐레이터를 거치면 그 결과가 사이드카 `anatomy` 에 얼려지고(`GET /api/breathe-anatomy`), 뷰 없이 에이전트가 `breathe` 만 쓴 런은 `anatomy` 가 비어 있어 **굽기가 매번 다시 잰다** — 굽기는 사이드카에 쓰지 않는다. 어느 쪽이든 동작한다. **굽기는 얼린 값을 신뢰하지 않는다 — 언제나 자기 기준 프레임에서 다시 잰다** (얼린 값은 큐레이터 프리뷰용 캐시다). 사이드카와 어긋나면 manifest 의 `sidecar_drift` 로 값을 실어 보고한다. 그 캐시가 아직 유효한지는 기준 프레임의 **입력** 지문(원본 파일 스탬프·픽셀편집·변형·변종)으로 판정하고, 어긋나면 큐레이터가 프리뷰·영상 내보내기를 **거부하며 갱신하라고 알린다** — 조용히 낡은 숫자로 그리지 않는다. 사람이 특정 행에 고정하고 싶을 때만 `rigid_row` 를 준다. (에이전트 직접 쓰기는 `load_curation`→`stamp_curation` 도장 경로 필수, 열린 탭은 새로고침 안내 — 함정 상세: [`docs/troubleshooting.md`](docs/troubleshooting.md)), (2) `compose_sprite_gif.py`/`compose_sprite_atlas.py` 가 자동으로 굽는다. 검증: gif-manifest 의 `breathe.phases`. **구 `splits`/`amplitude`/`subpixel` 은 요란하게 거부된다** — 옮기려면 `sprite-gen migrate-breathe <run-dir> --apply`.
-- **정지 자세(sit/lie/carry_idle 등) 행 레시피** — 정지 1컷 + 링크 복제 @ 4fps + 허리선 호흡(breaths 3) + 눈 보이는 방향만 깜빡임. **복제 수 = `recommended_breathe_frames(breathe) − 1`** (호흡당 `SMOOTH_CYCLE_FRAMES`=6 프레임 확보; breaths 3 → 총 18컷) — 짧은 루프(옛 11컷)에 다수 호흡을 우겨넣으면 1px 위상이 매 프레임 토글해 진동으로 읽히던 걸 막는다 (maintainer 2026-07-24). 깜빡임은 **시퀀스 끝 근처**(맨 끝 아님, 뒤에 눈뜬 rest ≥2)에 배치해 루프 이음새 전에 다시 떠 스냅을 없앤다. 실측 도출 근거·자동 적용 절차·프레임 게이트: [`docs/static-pose-recipe.md`](docs/static-pose-recipe.md) (maintainer 확정 2026-07-19, 이징 게이트 2026-07-24).
+- **에이전트 주도 호흡** (사용자가 "숨쉬기 적용해서 뽑아줘" 라고만 해도 됨): 호흡은 사이드카 필드라 뷰 없이도 켤 수 있다 — (1) `states.<state>.breathe = {"depth": 0.06, "breaths": 1, "lag": 0.1}` 만 쓰면 된다. **경계는 선언하지 않는다** — `sprite_gen/anatomy.py` 가 검출한다. 큐레이터를 거치면 그 결과가 사이드카 `anatomy` 에 얼려지고(`GET /api/breathe-anatomy`), 뷰 없이 에이전트가 `breathe` 만 쓴 런은 `anatomy` 가 비어 있어 **굽기가 매번 다시 잰다** — 굽기는 사이드카에 쓰지 않는다. 어느 쪽이든 동작한다. **굽기는 얼린 값을 신뢰하지 않는다 — 언제나 자기 기준 프레임에서 다시 잰다** (얼린 값은 큐레이터 프리뷰용 캐시다). 사이드카와 어긋나면 manifest 의 `sidecar_drift` 로 값을 실어 보고한다. 그 캐시가 아직 유효한지는 기준 프레임의 **입력** 지문(원본 파일 스탬프·픽셀편집·변형·변종)으로 판정하고, 어긋나면 큐레이터가 프리뷰·영상 내보내기를 **거부하며 갱신하라고 알린다** — 조용히 낡은 숫자로 그리지 않는다. 사람이 특정 행에 고정하고 싶을 때만 `rigid_row` 를 준다. (에이전트 직접 쓰기는 `load_curation`→`stamp_curation` 도장 경로 필수, 열린 탭은 새로고침 안내 — 함정 상세: [`troubleshooting.md`](troubleshooting.md)), (2) `compose_sprite_gif.py`/`compose_sprite_atlas.py` 가 자동으로 굽는다. 검증: gif-manifest 의 `breathe.phases`. **구 `splits`/`amplitude`/`subpixel` 은 요란하게 거부된다** — 옮기려면 `sprite-gen migrate-breathe <run-dir> --apply`.
+- **정지 자세(sit/lie/carry_idle 등) 행 레시피** — 정지 1컷 + 링크 복제 @ 4fps + 허리선 호흡(breaths 3) + 눈 보이는 방향만 깜빡임. **복제 수 = `recommended_breathe_frames(breathe) − 1`** (호흡당 `SMOOTH_CYCLE_FRAMES`=6 프레임 확보; breaths 3 → 총 18컷) — 짧은 루프(옛 11컷)에 다수 호흡을 우겨넣으면 1px 위상이 매 프레임 토글해 진동으로 읽히던 걸 막는다 (maintainer 2026-07-24). 깜빡임은 **시퀀스 끝 근처**(맨 끝 아님, 뒤에 눈뜬 rest ≥2)에 배치해 루프 이음새 전에 다시 떠 스냅을 없앤다. 실측 도출 근거·자동 적용 절차·프레임 게이트: 아래 "정지 자세(Static-Pose) 행 레시피" 절 (maintainer 확정 2026-07-19, 이징 게이트 2026-07-24).
- 호흡(idle breathing)은 **후처리 레이어**다 (maintainer 확정 2026-07-18) — 스크립트가 아니라 curation.json 사이드카 `states.<state>.breathe = {depth, depth_x?, breaths, lag, rigid_row?, anatomy}` 로 선언하고, compose/GIF 가 재생 시퀀스 위에 결정론(봉투 워프, `sprite_gen/breathe.py`)으로 굽는다. 깜빡임 프레임도 그대로 숨쉰다 (프레임 선택과 직교).
- **변형은 자르지 않고 강도를 떨군다** (2026-07-25 교체): 스프라이트 전체에 연속 변형장을 걸고 그 강도를 강체 경계에서 0 으로 테이퍼한다. `env=0` 인 행은 가로 사상이 항등이고 세로 누적이 정확히 1씩 늘어 **그 구간이 프레임 간 비트 동일**하다 — 눈·입이 몇 도트뿐이라 근사로는 표정이 뭉갠다. 가로는 행 안에서 밀도를 적분하므로 사상이 단조라 접힘이 없고, 날개 같은 부속은 밀리기만 하고 안 늘어난다.
- **강체 경계는 가슴이 아니라 목이다.** 가슴은 해부학 개념이라 몬스터마다 다르지만 목은 기하학적 병목이라 안정적으로 잡힌다. 얼굴이 몸통에 있으면(버섯·슬라임) 대칭 눈쌍을 찾아 얼굴 아래로 내린다. 병목도 얼굴도 없으면 어깨-기울기로 떨어지고 그 사실이 `anatomy.warnings` 에 남는다.
- 큐레이션 뷰: 줄 헤더 호흡 체크박스(즉시 on/off) + 라벨 클릭 편집기(실재생 위 **강체 경계 1개 드래그** · 세로 진폭 `depth` · 가로 진폭 `depth_x`(기본 "=세로", 0 = 가로 끄기 — maintainer 요청 2026-07-30 가로/세로 분리) · 루프당 호흡 횟수 · `auto` 되돌리기 — 즉시 반영, Esc 복원, 최종 굽기 필름스트립). 루프 길이는 시퀀스 그대로 불변이고 위상이 연속값이라 breaths 는 요청 그대로 적용된다 (범위 1~8이고 **정수여야 한다**; 밖이거나 비정수면 조용히 깎지 않고 요란하게 거부한다 — `depth` 0.005~0.20, `depth_x` null|0~0.20, `lag` 0~0.45 도 같다). 재추출/굽기 대기 없음.
- 세로선(몸통 밴드)을 **사람이 조정하면** 보호 램프가 밴드 자체에 앵커된다 — 밴드 밖 열은 늘어나지 않고 밀리기만 한다. 자동 검출 밴드는 부속(날개·긴 팔)이 실재할 때만 켜지는 기존 계약 그대로다 (블롭에서 밴드 조정이 무력했던 버그 수리, 2026-07-30).
+
+## 정지 자세(Static-Pose) 행 레시피
+
+> `docs/static-pose-recipe.md` 에서 병합(2026-09-09, 본문 verbatim). 호흡 레이어와 정지 자세 레시피는 한 계약이라 한 문서가 소유한다.
+
+합성 정지 자세 회귀에서 도출한 결정론적 레시피다.
+
+### 적용 대상
+
+이동/액션이 아닌 모든 "가만히 있는" 상태: `idle`, `sit`, `sit_chair`, `lie`,
+`carry_idle` 등. 로코모션(walk/run/jump)과 action 행에는 적용하지 않는다.
+
+### 레시피
+
+1. **정지 1컷 + 링크 복제**: 추출 프레임 중 최적 정지 포즈 1장을 고르고
+ (사람 검수 대상; 기본 후보 frame 0), 나머지 시퀀스는 전부 그 프레임의
+ **링크 복제**로 채운다 — 편집 truth 1곳, 아틀라스 셀 공유(무비용).
+2. **길이 = 호흡당 최소 프레임 확보** @ 4fps. 시퀀스 길이는
+ `sprite_gen/effects/breathe.py` `recommended_breathe_frames(breathe)` 로 정한다
+ (호흡당 `SMOOTH_CYCLE_FRAMES`=6 프레임): 기본 `breaths: 3` → **18컷**
+ (~4.5s 루프, 호흡당 1.5s). **옛 11컷은 사이클당 ~3.7프레임이라 1px 위상이
+ 거의 매 프레임 토글해 호흡이 아니라 진동으로 읽힌다**. 이 게이트가 그 원인을 막는다. 깜빡임 프레임은 이 길이에
+ 포함되며 별도로 +하지 않는다 (아래 4).
+3. **호흡 레이어**: `breathe = {depth: 0.06, breaths: 3, lag: 0.1}` 만 쓴다.
+ **강체 경계는 선언하지 않는다** — `sprite_gen/effects/anatomy.py` 가 목 병목(없으면 대칭
+ 눈쌍 아래, 그것도 없으면 어깨-기울기)으로 검출해 사이드카 `anatomy` 에 채운다.
+ **굽기는 그 값을 캐시로만 본다** — 매번 자기 기준 프레임에서 다시 재고, 사이드카와
+ 어긋나면 manifest 의 `sidecar_drift` 로 값을 실어 보고한다. 사이드카의 `anatomy` 는
+ 큐레이터 미리보기가 굽기와 같은 경계로 그리려고 들고 있는 것이고, 그게 아직 유효한지는
+ `fingerprint`(기준 프레임의 **입력** 키 — `breathe.reference_key`)로 판정한다.
+ 특정 행에 고정해야 할 때만 `rigid_row`.
+ 위상이 연속값이라 이징을 위한 별도 옵션이 없다 — 부드러움은 프레임 수(위 2)로 얻는다.
+4. **깜빡임은 눈이 보이는 방향만**: 시퀀스 **끝 근처**(맨 끝 아님)에 배치하고
+ 뒤에 눈-뜬 rest 프레임을 **최소 2장** 남긴다 — 그래야 감았다가 루프 이음새
+ 전에 다시 뜨며 이어진다 (맨 끝 1프레임이면 감은 채로 끝나 다음 루프 첫
+ 프레임에서 확 떠 스냅난다). 감은-눈은 rest 위상 프레임에
+ 얹어 몸통은 그대로 두고 눈만 바뀌게 한다.
+ - 정면(down): 독립(unlink) 복제 2장에 감은-눈 픽셀 ops (open→closed→open
+ 읽히게), 뒤에 rest 프레임 ≥2.
+ - 옆(side): 동일 (독립 복제 감은-눈 + 뒤 rest ≥2).
+ - 뒤(up): 깜빡임 없음.
+ 감은-눈 픽셀은 **사람이 깎는다** — 자세마다 눈 위치가 달라 자동 이식
+ 금지 (포즈별 눈 좌표가 다르면 눈이 엉뚱한 데 감긴다).
+5. **변형/픽셀 편집은 정지 원본 프레임에만** — 복제는 링크 동기화로 따라온다.
+
+### 자동 적용 절차 (에이전트)
+
+새 정지 자세 행이 추출되면 (큐레이션 없음 전제):
+
+1. `curation.json` `states.<state>` 에: `selected=[still]`,
+ `order=[still]+클론N`, `clones={새 idx: still}` (링크 기본 — 편집 복사 금지),
+ breathe 위 레시피. **N = `recommended_breathe_frames(breathe) − 1`** (정지
+ 원본 1장 제외; 기본 breaths 3 → 17 클론 → 총 18컷). 링크 복제라 아틀라스
+ 셀은 안 늘어난다 — 호흡 위상당 유니크 셀만 굽는다. 18컷 `breaths: 3` 이면 유니크 칸 6개(위상이 6종만 반복).
+2. fps 4 를 `sprite-request.json` 해당 상태에 기록.
+3. 깜빡임(정면/옆)은 자동 생성하지 않는다 — "깜빡임 추가 대기" 로 보고하고
+ 사람이 정지 프레임 확정 후 눈을 깎는다.
+4. 열린 큐레이션 탭이 있으면 두-작성자 충돌 방지를 위해 새로고침을 안내한다.
diff --git a/docs/static-pose-recipe.md b/docs/static-pose-recipe.md
deleted file mode 100644
index e9d2a1e..0000000
--- a/docs/static-pose-recipe.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# 정지 자세(Static-Pose) 행 레시피
-
-합성 정지 자세 회귀에서 도출한 결정론적 레시피다.
-
-## 적용 대상
-
-이동/액션이 아닌 모든 "가만히 있는" 상태: `idle`, `sit`, `sit_chair`, `lie`,
-`carry_idle` 등. 로코모션(walk/run/jump)과 action 행에는 적용하지 않는다.
-
-## 레시피
-
-1. **정지 1컷 + 링크 복제**: 추출 프레임 중 최적 정지 포즈 1장을 고르고
- (사람 검수 대상; 기본 후보 frame 0), 나머지 시퀀스는 전부 그 프레임의
- **링크 복제**로 채운다 — 편집 truth 1곳, 아틀라스 셀 공유(무비용).
-2. **길이 = 호흡당 최소 프레임 확보** @ 4fps. 시퀀스 길이는
- `sprite_gen/effects/breathe.py` `recommended_breathe_frames(breathe)` 로 정한다
- (호흡당 `SMOOTH_CYCLE_FRAMES`=6 프레임): 기본 `breaths: 3` → **18컷**
- (~4.5s 루프, 호흡당 1.5s). **옛 11컷은 사이클당 ~3.7프레임이라 1px 위상이
- 거의 매 프레임 토글해 호흡이 아니라 진동으로 읽힌다**. 이 게이트가 그 원인을 막는다. 깜빡임 프레임은 이 길이에
- 포함되며 별도로 +하지 않는다 (아래 4).
-3. **호흡 레이어**: `breathe = {depth: 0.06, breaths: 3, lag: 0.1}` 만 쓴다.
- **강체 경계는 선언하지 않는다** — `sprite_gen/effects/anatomy.py` 가 목 병목(없으면 대칭
- 눈쌍 아래, 그것도 없으면 어깨-기울기)으로 검출해 사이드카 `anatomy` 에 채운다.
- **굽기는 그 값을 캐시로만 본다** — 매번 자기 기준 프레임에서 다시 재고, 사이드카와
- 어긋나면 manifest 의 `sidecar_drift` 로 값을 실어 보고한다. 사이드카의 `anatomy` 는
- 큐레이터 미리보기가 굽기와 같은 경계로 그리려고 들고 있는 것이고, 그게 아직 유효한지는
- `fingerprint`(기준 프레임의 **입력** 키 — `breathe.reference_key`)로 판정한다.
- 특정 행에 고정해야 할 때만 `rigid_row`.
- 위상이 연속값이라 이징을 위한 별도 옵션이 없다 — 부드러움은 프레임 수(위 2)로 얻는다.
-4. **깜빡임은 눈이 보이는 방향만**: 시퀀스 **끝 근처**(맨 끝 아님)에 배치하고
- 뒤에 눈-뜬 rest 프레임을 **최소 2장** 남긴다 — 그래야 감았다가 루프 이음새
- 전에 다시 뜨며 이어진다 (맨 끝 1프레임이면 감은 채로 끝나 다음 루프 첫
- 프레임에서 확 떠 스냅난다). 감은-눈은 rest 위상 프레임에
- 얹어 몸통은 그대로 두고 눈만 바뀌게 한다.
- - 정면(down): 독립(unlink) 복제 2장에 감은-눈 픽셀 ops (open→closed→open
- 읽히게), 뒤에 rest 프레임 ≥2.
- - 옆(side): 동일 (독립 복제 감은-눈 + 뒤 rest ≥2).
- - 뒤(up): 깜빡임 없음.
- 감은-눈 픽셀은 **사람이 깎는다** — 자세마다 눈 위치가 달라 자동 이식
- 금지 (포즈별 눈 좌표가 다르면 눈이 엉뚱한 데 감긴다).
-5. **변형/픽셀 편집은 정지 원본 프레임에만** — 복제는 링크 동기화로 따라온다.
-
-## 자동 적용 절차 (에이전트)
-
-새 정지 자세 행이 추출되면 (큐레이션 없음 전제):
-
-1. `curation.json` `states.<state>` 에: `selected=[still]`,
- `order=[still]+클론N`, `clones={새 idx: still}` (링크 기본 — 편집 복사 금지),
- breathe 위 레시피. **N = `recommended_breathe_frames(breathe) − 1`** (정지
- 원본 1장 제외; 기본 breaths 3 → 17 클론 → 총 18컷). 링크 복제라 아틀라스
- 셀은 안 늘어난다 — 호흡 위상당 유니크 셀만 굽는다. 18컷 `breaths: 3` 이면 유니크 칸 6개(위상이 6종만 반복).
-2. fps 4 를 `sprite-request.json` 해당 상태에 기록.
-3. 깜빡임(정면/옆)은 자동 생성하지 않는다 — "깜빡임 추가 대기" 로 보고하고
- 사람이 정지 프레임 확정 후 눈을 깎는다.
-4. 열린 큐레이션 탭이 있으면 두-작성자 충돌 방지를 위해 새로고침을 안내한다.
diff --git a/tests/docs/test_docs_index.py b/tests/docs/test_docs_index.py
new file mode 100644
index 0000000..15033d1
--- /dev/null
+++ b/tests/docs/test_docs_index.py
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: Apache-2.0
+"""docs/README.md is the documentation index: every leaf doc appears there exactly once,
+grouped under the taxonomy, and no markdown link in the repo's docs points at a file that
+does not exist. A doc added without an index line — or a link left behind by a rename —
+fails here instead of surfacing as a dead link for a reader."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+DOCS = ROOT / "docs"
+LINK = re.compile(r"\[[^\]]*\]\(([^)\s#]+)(?:#[^)]*)?\)")
+
+
+def _leaf_docs() -> set[str]:
+ return {p.name for p in DOCS.glob("*.md") if p.name != "README.md"}
+
+
+def test_docs_index_lists_every_leaf_doc_exactly_once() -> None:
+ index = (DOCS / "README.md").read_text(encoding="utf-8")
+ linked = re.findall(r"\]\(([a-z0-9-]+\.md)\)", index)
+ # the taxonomy sections start at the first "## " heading; the pipeline table above them
+ # may name an entry doc a second time, the sections list each doc exactly once
+ sections = index[index.index("\n## "):]
+ per_section = re.findall(r"\]\(([a-z0-9-]+\.md)\)", sections)
+ counts = {name: per_section.count(name) for name in set(per_section)}
+ missing = sorted(_leaf_docs() - set(per_section))
+ extra = sorted(set(linked) - _leaf_docs())
+ dupes = sorted(n for n, c in counts.items() if c > 1)
+ assert not missing, f"docs without an index line: {missing}"
+ assert not extra, f"index lines for docs that do not exist: {extra}"
+ assert not dupes, f"docs indexed more than once: {dupes}"
+
+
+def _markdown_files() -> list[Path]:
+ files = [ROOT / "README.md", ROOT / "SKILL.md", ROOT / "CHANGELOG.md", *DOCS.glob("*.md"), ROOT / "scripts" / "dev" / "README.md"]
+ return [f for f in files if f.is_file()]
+
+
+def test_relative_markdown_links_resolve() -> None:
+ broken: list[str] = []
+ for md in _markdown_files():
+ text = md.read_text(encoding="utf-8")
+ for target in LINK.findall(text):
+ if re.match(r"^[a-z]+:", target) or target.startswith("/"):
+ continue # URLs, mailto, absolute paths are not repo links
+ resolved = (md.parent / target).resolve()
+ if not resolved.exists():
+ broken.append(f"{md.relative_to(ROOT)} -> {target}")
+ assert not broken, "broken relative links:\n" + "\n".join(broken)
diff --git a/tests/effects/test_breathe_off_state.py b/tests/effects/test_breathe_off_state.py
index a680591..f02e43a 100644
--- a/tests/effects/test_breathe_off_state.py
+++ b/tests/effects/test_breathe_off_state.py
@@ -900,7 +900,7 @@ RETIRED_DOC_CLAIMS = [
("a mismatch re-detects", "굽기는 지문을 안 보고 **매번** 재검출한다"),
]
DOC_FILES = ["CHANGELOG.md", "SKILL.md", "README.md",
- "docs/static-pose-recipe.md", "docs/run-contract.md", "docs/curation.md"]
+ "docs/breathing.md", "docs/run-contract.md", "docs/curation.md"]
def test_no_doc_still_describes_the_retired_fingerprint_design():