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.mdindex 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 owCONTRACT & STRUCTURE docs/run-contract.md · docs/architecture.mdREQUEST AUTHORING docs/states-and-frames.md · docs/subject-profiles.md · docs/pixel-unfake.md · docs/chroma-alpha.mdGENERATION 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.mdCOLOURWAYS docs/recolor.mdLAYER TRACKS docs/layer-tracks.mdENGINE EXPORT docs/engine-export.mddiff --git a/docs/README.md b/docs/README.mdnew file mode 100644index 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.mdindex 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.mddeleted file mode 100644index 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.pynew file mode 100644index 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.pyindex 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():