From ec9a21cdeb7e434bcb0b80d595d6ac5be9c6b275 Mon Sep 17 00:00:00 2001
From: Penguin <say8425@gmail.com>
Date: Wed, 5 Aug 2026 13:19:07 +0900
Subject: [PATCH 1/5] =?UTF-8?q?docs:=20=EB=AC=B8=EC=84=9C-=EC=BD=94?=
 =?UTF-8?q?=EB=93=9C=20=EB=93=9C=EB=A6=AC=ED=94=84=ED=8A=B8=2017=EA=B1=B4?=
 =?UTF-8?q?=EC=9D=84=20=EA=B3=A0=EC=B9=98=EA=B3=A0=20=EA=B2=8C=EC=9D=B4?=
 =?UTF-8?q?=ED=8A=B8=EB=A1=9C=20=EB=AC=B6=EB=8A=94=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

전면 대조에서 나온 것들이다. 가장 아픈 건 CLI 플래그 파리티 테스트가
SKILL.md 하나만 봤다는 점이다 — 그 사이 `--fold-with-tree`가 npm README와
번역 4종에서 조용히 빠져 있었고(플래그를 만든 #14이 루트 README와 SKILL.md만
갱신했다), 게이트가 한 문서만 보는 한 나머지는 아무도 지키지 않는다.
그래서 테스트를 docs-flags-parity로 이름을 바꿔 일곱 문서 전부를 대조하게
했다. 이 테스트는 고치기 전 상태에서 정확히 그 다섯 문서를 빨간불로 잡는다.

틀린 설명: README 아키텍처가 agent skill을 apps/viewer 소속으로 적었지만
실제로는 레포 루트 skills/에 살고 build.ts가 dist/로 복사한다(번역 4종 동일).
trees "46 src"는 trees만 style.css를 포함해 센 값이라 45로 고치고, 무엇을
세는지 규칙과 재계산 명령을 함께 박았다. 엔진 규모 27k는 실측 29,482줄이다.
diff.ts:220-221은 221-222다.

모순: CLAUDE.md가 pr-check을 세 곳에서 다르게 열거했다(한 곳은 e2e 누락).
README의 커버리지 제외 목록은 여섯 중 셋만 적고 "의도적으로 제외된 것"이라
단정했다 — scripts/**와 스펙 자신이 빠져 있었다(번역 4종 동일).

누락: WHAT 트리에 skills/·docs/·.github/·플러그인 매니페스트·CHANGELOG.md·
bunfig.toml이 없었다. 125행이 "동기화 필수"라고 계약을 거는 대상과 83행이
"레포 루트에 있다"고 계약을 거는 파일이 지도에 없는 상태였다. prewarm.ts,
bunfig preload의 happy-dom 함정, 배포물이 deps 0인 전량 번들이라는 사실도
어디에도 없었다.

데드코드: isDiffViewerDisabled/DIFFDECK_DISABLE을 지웠다. 호출부가 한 번도
없었고 유일한 참조가 자기 테스트라 커버리지 100%가 그대로 유지됐다 —
게이트로는 원리적으로 안 드러나는 종류였다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G1vWAequwbToDppRceT6C1
---
 CLAUDE.md                                     | 30 ++++++----
 README.md                                     | 13 ++--
 apps/viewer/README.md                         | 31 +++++-----
 apps/viewer/__tests__/diff-config.test.ts     |  9 ---
 .../__tests__/docs-flags-parity.test.ts       | 59 +++++++++++++++++++
 .../__tests__/skill-flags-parity.test.ts      | 43 --------------
 apps/viewer/server/config.ts                  |  3 -
 docs/README.es.md                             |  9 ++-
 docs/README.ja.md                             |  9 ++-
 docs/README.ko.md                             |  9 ++-
 docs/README.zh.md                             |  9 ++-
 11 files changed, 127 insertions(+), 97 deletions(-)
 create mode 100644 apps/viewer/__tests__/docs-flags-parity.test.ts
 delete mode 100644 apps/viewer/__tests__/skill-flags-parity.test.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index f4901b0..62e5c86 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,20 +10,29 @@ diffdeck/
 │   ├── path-store/         # @diffdeck/path-store — 트리 순수 로직 (flatten·sort·projection·store), 18 src, deps 없음
 │   ├── theming/            # @diffdeck/theming — 테마 시스템 + 테마 데이터, 14 src + themes/*.json 10개
 │   ├── diffs/              # @diffdeck/diffs — CodeView diff 렌더 엔진, 144 src (CodeView.ts 3,563줄)
-│   └── trees/              # @diffdeck/trees — FileTree 엔진, 46 src (vanilla 렌더, de-preact 완료)
+│   └── trees/              # @diffdeck/trees — FileTree 엔진, 45 src (vanilla 렌더, de-preact 완료)
 ├── apps/
-│   └── viewer/             # @say8425/diffdeck — server/(데이터 API) + browser/(뷰어 프론트) + cli/(CLI 엔트리) + build.ts·cli.ts
+│   └── viewer/             # @say8425/diffdeck — server/(데이터 API) + browser/(뷰어 프론트) + cli/(CLI 엔트리) + build.ts·cli.ts·README.md(npm 페이지)
+├── skills/diffdeck/        # SKILL.md — 에이전트가 참조하는 유일한 구동 문서. build.ts가 dist/skills/로 복사한다
+├── docs/                   # README 번역 4종(ko·ja·zh·es) + demo.gif·screenshot.png·grab.png
+│                           #   (docs/superpowers/의 plan·spec은 .gitignore — 로컬 전용)
 ├── scripts/
 │   ├── extract-sources.ts       # 소스맵 sourcesContent → 원본 TS 복원 도구 (Foundation 일회성)
 │   ├── extract-sources.test.ts  # 합성 소스맵 fixture로 hermetic (외부 체크아웃 의존 없음)
 │   ├── css-inline-plugin.ts     # *.css?inline import용 Bun 플러그인 (런타임/번들러 2분리)
-│   └── parity/                  # 포크 렌더 패리티 하니스 (fixture·smoke test·main·build)
+│   └── parity/                  # 포크 렌더 패리티 하니스 (fixture·preload·smoke test·main·build)
+├── .github/workflows/      # pr-check.yml (5잡 게이트) + release.yml (release-please → npm)
+├── .claude-plugin/ .codex-plugin/  # 플러그인 매니페스트 — release-please extra-files가 버전을 bump
+├── CHANGELOG.md            # 레포 루트에 있다 (release-please changelog-path의 앞 슬래시 — CI 항목 참고)
+├── bunfig.toml             # 테스트 preload + 커버리지 게이트/제외 (테스트 3레인 항목 참고)
 ├── tsconfig.base.json      # 공유 base (jsxImportSource: preact, @diffdeck/* path alias)
 ├── .oxlintrc.json / .oxfmtrc.json
 ├── NOTICE                  # pierre (Apache-2.0) 유래 고지
 └── package.json            # Bun workspace 루트 (workspaces: packages/*, apps/*)
 ```
 
+**위 `N src` 숫자의 정의**: `src/` 아래 **테스트를 뺀 `.ts` 파일 수**다(`style.css`·`themes/*.json`은 제외 — 그래서 따로 적었다). 규칙을 박아두는 이유는 예전에 trees만 `style.css`를 포함해 세는 바람에 46으로 적혀 있었기 때문이다. 재계산: `find packages/<pkg>/src -name '*.ts' -not -path '*__tests__*' | wc -l`. 이 숫자들은 게이트가 없으므로 드리프트한다 — 규모의 감을 주는 값으로만 읽고, 정확한 값이 필요하면 위 명령이 답한다.
+
 **기술 스택**: Bun (런타임·번들·테스트·workspace), TypeScript 7 (Go 네이티브 컴파일러), oxlint/oxfmt
 
 **패키지 의존 그래프**:
@@ -48,7 +57,7 @@ cc-statusline에 포함됐던 로컬 diff 뷰어를 독립 제품으로 분리 +
 
 "Grab" 기능은 diff의 특정 구간을 프롬프트와 함께 클립보드로 복사해 AI 에이전트에게 바로 붙여넣을 수 있게 한다. 진입 경로는 둘: ① 엔진 거터의 GitHub식 라인 선택 + 상주 "+" 버튼(CodeView의 `enableLineSelection`/`enableGutterUtility` 옵션으로 활성화), ② 코드 텍스트 드래그 릴리스 시 즉시 열리는 프롬프트 팝오버. 둘 다 `#grab-popover` 프롬프트 입력창을 열고, Enter로 "참조(파일 경로·상태·base)+스니펫+프롬프트"를 한 텍스트로 인코딩해 클립보드에 복사한다. `enableLineSelection`/`enableGutterUtility`는 전역 활성화라 모든 라인 호버에 "+"가 뜨고 find 매치 라인에도 상주하는데, 이는 의도된 UX 변화다. 텍스트 경로는 pointerup에서 "실제 드래그였는지"부터 게이트한다 — pointerDown→pointerup 이동 거리가 `DRAG_THRESHOLD`(6px)를 넘어야 하며(헤더 폴드 토글과 동일한 `movedBeyondThreshold` 관례), 이 게이트가 없으면 더블/트리플클릭의 네이티브 단어·문단 선택(마우스 이동 없이도 비어있지 않은 Selection을 만든다)이 곧장 팝오버를 열어버린다. 통과하면 스냅샷 의미론: `pointerup` 시점(한 틱 뒤)에 선택·파일·스니펫을 전부 고정해 이후 워커 하이라이트 DOM 교체나 recycle이 선택을 죽여도 안전하고, 팝오버는 스크롤로는 닫히지 않으며 Esc·팝오버 바깥 pointerdown·`renderPatch`(파일 목록 갱신) 발생 시, 그리고 복사 성공 후 1.2초 뒤 자동으로 닫힌다. 선택 소유권: 팝오버가 엔진 라인 선택(`codeView.selectedLines` — `data-selected-line`을 낳는 슬롯)을 "소유"한 경우에만 — 즉 거터 "+" 경로(`onGutterUtilityClick`)로 열렸을 때만 — 닫히거나 복사가 성공할 때 `codeView.clearSelectedLines()`로 그 선택을 해제한다(`onGutterUtilityClick`이 세우는 `grabOwnsLineSelection` 플래그를 `onCopied`/`onClosed`가 공통으로 가드). 텍스트 드래그 경로는 네이티브 브라우저 Selection만 읽을 뿐 이 슬롯을 건드리지 않으므로 플래그를 세우지 않는다 — 무조건 해제했다면 find 바가 `revealMatch`/`selectMatch`로 같은 슬롯에 세워 둔 매치 하이라이트가 텍스트 경로 팝오버의 Esc나 복사 성공만으로 지워지고, 팝오버를 연 적 없는 "파킹된"(드래그만 하고 아직 "+"를 안 누른) 거터 선택도 `renderPatch`(팝오버가 열렸든 아니든 진입부에서 항상 `close()`를 호출)마다 지워지는 회귀가 생긴다. 거터 경로에서 스테일 선택이 남으면 안 되는 이유: 엔진의 `InteractionManager.placeUtility()`는 활성 선택이 있으면 호버를 무시하고 "+"를 선택 하단 행에 고정하며(그 행이 더 이상 렌더 대상이 아니면 아예 숨김) 이후 다른 행 호버에서도 "+"가 뜨지 않게 된다. 텍스트 경로 팝오버가 열리면(`input.focus()`) 네이티브 드래그 선택은 붕괴한다 — 포커스가 문서 선택을 팝오버 input으로 **옮기는** 것이라(실측: `getComposedRanges`가 `#grab-popover`의 자식을 가리킨다) 페인팅만 멈추는 게 아니고, 강제로 되돌려도 첫 타이핑에 다시 붕괴한다. 그래서 잡은 라인은 **grab 하이라이트**가 대신 보여준다: `unsafeCSS`로 넣은 `::highlight(diffdeck-grab)`(파랑) + `CSS.highlights` 레지스트리로 칠하는 독립 채널이다. 앱이 shadow root에 직접 `<style>`을 붙이면 안 된다 — `CodeView.cleanElement()`가 `data-unsafe-css` 등이 없는 style 노드를 첫 recycle에 떼어낸다. 하이라이트 범위는 진입 경로에 따라 다르다: **텍스트 드래그는 문자 단위**(드래그한 문자만), **거터 "+"는 라인 단위**다. `NormalizedRange`의 선택적 `chars`(`CharSpan`)가 그 차이를 나른다 — 없으면 줄 전체이고, 있으면 스니펫(`snippet.ts`의 `applyChars`)과 하이라이트(`highlight.ts`의 `withChars` → `setStart`/`setEnd`) **양쪽에 같은 값이 들어가** "보이는 범위 == 복사되는 범위"가 문자 수준에서 유지된다. `chars`는 양 끝점이 `[data-line]` 안에 직접 떨어졌고 클램프가 없었을 때만 세운다(거터 복구 끝점·크로스 파일·split 컬럼 클램프·비-라인 끝점·끝점이 텍스트 노드가 아닌 토큰 `<span>`인 경우는 생략 → 줄 전체). 가상화 주의: `rowsInRange`는 **그 순간 렌더된 행**만 받으므로, 보이는 첫/끝 행이 실제 선택 경계와 일치할 때만 그 경계에 오프셋을 적용한다(`startExact`/`endExact`) — 경계 행이 렌더 윈도우 밖이면 그 행은 통째로 칠한다. 행의 `textContent`가 파일 원본 라인과 정확히 일치하므로(탭 포함) 텍스트 노드 길이 누적이 원본 기준 오프셋을 준다. 어느 범위든 `lineFor`가 `data-alt-line`을 함께 읽어 행을 고르는 것은 그대로다: unified의 context 행은 엔진이 addition 요소 하나로만 렌더해 `data-line`이 new 번호이므로, 이 폴백이 없으면 old-side 범위에서 사이의 context 행이 하이라이트에서만 빠져(클립보드에는 들어간다 — `snippet.ts`가 `deletionLines`를 통째로 슬라이스한다) "보이는 범위 == 복사되는 범위"가 깨진다. split은 컬럼마다 context 행이 따로 있어 이 폴백을 unified로 한정한다. Range는 워커 DOM 교체·recycle에 죽으므로 `onPostRender`에서 재시딩하며, 대상 파일이 렌더 윈도우 밖일 때 하이라이트가 사라지는 것은 의도된 동작이다. 이 채널은 엔진 `selectedLines` 슬롯을 쓰지 않으므로 위 소유권 규칙(`grabOwnsLineSelection`)과 find 매치 하이라이트는 그대로다. 팝오버 위치는 드래그 **릴리스 좌표**(0크기 rect)를 앵커로 `computePlacement`에 넘긴다 — 예전엔 행 전체 rect라 커서와 무관하게 파일 왼쪽 끝에 떴다. Cmd+C로 이어지는 브라우저 기본 복사 흐름은 여전히 유지되지 않으며, 이는 수용된 트레이드오프다(팝오버 자체가 스니펫을 인코딩해 복사한다). 팝오버는 **컨텍스트 라벨 한 줄 + 입력 영역** 둘로 구성되고, 보내기 버튼은 입력 영역 **안**에 산다. 라벨은 `grabLabelParts()`가 만드는 조각 배열이고(`main.ts`가 그걸 넘긴다) 팝오버가 조각마다 span을 그린다 — 이어 붙이면 `popover.ts:53 · new side`이며 전체 경로는 `title`에 있다. `grabLabel()`은 그 조각을 join하는 것으로 남아 있다: 프로덕션 경로에서는 더 이상 호출되지 않지만, "조각을 이어 붙이면 예전 문자열과 같다"는 계약을 단언하는 테스트가 이 함수를 통해 색·텍스트 분기를 막는다. 테두리·배경·radius는 textarea가 아니라 래퍼 `.grab-field`가 갖는다 — 버튼이 같은 상자를 공유해야 하기 때문이고, textarea는 그 안에서 투명하게 눕는다(`field-sizing: content`로 `max-height` 90px(정확히 5줄)까지 자란 뒤 스크롤). **radius 8/6/4는 임의값이 아니라 앱에 이미 있는 세 값이다**: 8px = `#grab-popover`(떠 있는 패널, 앱에서 유일), 6px = `--vd-radius`(select·세그컨트롤·find바·오버플로메뉴와 같은 표준 컨트롤), 4px = 툴바 세그먼트 버튼과 같은 "컨테이너 안쪽 버튼". 앱에서 `999px`은 **토글 스위치 하나에만** 배정돼 있으므로 여기서 쓰면 그 어휘를 훔치게 된다(알약 시안을 버린 이유). `.grab-send`는 **배경색이 없는 게 계약이다** — 상태를 색으로만 말한다(회색 idle → 액센트 ready → 초록 ok → 빨강 fail, `data-state`). 아이콘 셋 3개를 전부 DOM에 두고 CSS가 하나만 보여준다(상태마다 innerHTML을 갈면 매번 파서를 태운다). 화살표는 **오른쪽**(보낸다)이지 위쪽(업로드)이 아니다. 빈 프롬프트로도 참조+스니펫은 복사되므로 버튼을 `disabled`로 만들지 않는다 — 강조만 바뀐다. `.grab-hint`(`role="status"`)는 **스크린리더 전용(sr-only)**이다: 시각적 상태는 버튼이 지고, 예전처럼 보이는 줄로 두면 복사할 때마다 창이 18px 자라(실측: 66 → 84) 커서 아래 코드가 밀렸다. `hidden`을 토글하지 않는 이유이기도 하다 — hidden 요소는 라이브 리전으로 알려지지 않으므로, "상태 없음"은 hidden이 아니라 **빈 텍스트**로 표현한다. 버튼 `mousedown`에 `preventDefault`를 걸어 클릭해도 입력 포커스를 잃지 않게 한다(포커스가 빠지면 IME 조합이 강제 확정돼 조합 중이던 글자가 누락된다). Enter는 제출, **Shift+Enter는 개행**(`preventDefault` 없이 빠져나가 textarea 기본 동작에 맡긴다 — 새 키 분기를 만들지 않아 IME 가드 3지점이 불변이다), Esc는 닫기다. `Enter ↵ · Esc` 상시 힌트 줄은 제거했다 — placeholder와 **같은 말을 두 번** 하는 중복이었고, 한 노드가 상시 안내와 상태를 겸용해 실패로 전이하면 조작 안내가 사라졌다. placeholder는 `"Prompt…"` 한 마디만 한다 — 한때 여기에 `"(⏎ copy · shift + ⏎ new line)"`까지 실었는데, 그게 창에서 가장 눈에 띄는 요소라 다른 걸 아무리 고쳐도 "안 바뀐 것처럼" 보였다(승인된 시안은 `Prompt…`였다). 단축키 고지는 **화면을 차지하지 않는** 두 채널이 맡는다: 버튼 hover(`title="Copy (⏎) · Shift+⏎ for new line"`)와 `aria-keyshortcuts`. 회귀망: `grab-highlight.e2e.ts` 9종(⑨는 복사 전후 창 높이 동일 — sr-only 힌트의 회귀망이고, happy-dom은 레이아웃이 없어 원리적으로 못 잡는다). 팝오버의 Enter/Esc 둘 다 IME 조합 가드(`isComposing`/`keyCode === 229`)를 걸어 한국어 등 조합 입력 중 키 이벤트가 오작동하지 않는다. 구현은 순수 로직 `apps/viewer/browser/grab/*`(range·snippet·encode·selectionAdapter·position·textSelection·popover·highlight, 100% 커버리지 게이트 안)와 `main.ts`의 배선으로 나뉘며, 배선 쪽은 `grab.e2e.ts` 12종이 회귀망이다.
 
-설계·조사 근거(요약): CodeView는 이미 프레임워크 무관 vanilla 27k줄 엔진(faithful 재작성 4~8개월, 이득 0 → 재작성 금지). trees의 preact 렌더 스킨도 Plan 3(de-preact)에서 vanilla로 포팅 완료 — 현재 리포에 preact/react 런타임 의존이 전혀 없다. 대체 라이브러리 조사 결과 pierre 품질 대체재 없음.
+설계·조사 근거(요약): CodeView는 이미 프레임워크 무관 vanilla 29.5k줄 엔진(`packages/diffs/src`의 테스트 제외 `.ts` 합계 29,482줄 — faithful 재작성 4~8개월, 이득 0 → 재작성 금지). trees의 preact 렌더 스킨도 Plan 3(de-preact)에서 vanilla로 포팅 완료 — 현재 리포에 preact/react 런타임 의존이 전혀 없다. 대체 라이브러리 조사 결과 pierre 품질 대체재 없음.
 
 ## HOW
 
@@ -68,10 +77,11 @@ bun run format
 - `bun run test:coverage` — 같은 스위트를 `--coverage`로 실행 + **diffdeck 소유 런타임 코드(`apps/viewer/{browser,cli,server}`) 100% 커버리지 게이트**(`bunfig.toml`의 `coverageThreshold`/`coveragePathIgnorePatterns`). 게이트 제외 대상: vendored `packages/*`, `scripts/**`, browser 엔트리 `main.ts`(in-process 유닛 테스트 대신 e2e로 커버), `build.ts`, 그리고 `*.test.ts`/`e2e/**` 자신.
 - `bun run test:e2e` — `apps/viewer/e2e/*.e2e.ts` Playwright 실브라우저 스위트. `playwright.config.ts`가 `channel:"chrome"`으로 시스템 Google Chrome을 구동(Chromium 별도 다운로드 없음), `globalSetup`이 `build.ts`를 1회 실행해 실제 `dist/cli.js`를 스폰. `main.ts`와 vendored 렌더 경로(fold·copy-path·find·flags-sync·image-diff 등)를 end-to-end로 커버. fixtures(`apps/viewer/e2e/fixtures/`: 임시 git repo 빌더 `repo.ts`, CLI 스폰 `launchViewer` `app.ts`, Node `child_process` 래퍼 `proc.ts`)는 **Node**로 동작 — Playwright Test는 항상 spec·fixture·globalSetup을 Node로 실행하므로(`bunx playwright test`로 띄워도) `Bun` 글로벌·`bun`의 `$` 셸을 못 쓰고 `spawn`으로 실제 `bun` 바이너리를 PATH에서 호출한다. `apps/viewer/e2e/tsconfig.json`이 루트 `typecheck` 스크립트에 배선되어 있다.
 - **`*.e2e.ts` 네이밍 규칙**: `bun test`는 `*.test.ts` 외에 `*.spec.ts`도 수집하므로, Playwright 스펙을 `*.e2e.ts`로 명명해 `bun test`가 절대 이를 실행하지 않도록 분리한다(Playwright 쪽은 `testMatch:"**/*.e2e.ts"`로 반대로 한정).
+- **`bunfig.toml`의 `preload`는 `scripts/parity/preload.ts` 하나뿐이고, happy-dom을 여기 넣으면 안 된다.** preload는 css-inline 플러그인을 등록해 포크 패키지의 `import styles from '../style.css?inline'`이 `bun test`에서 실제 스타일시트 텍스트로 풀리게 하는 용도다(빌드가 쓰는 것과 같은 플러그인). 반면 happy-dom 전역 등록(`packages/trees/src/__tests__/happydom.ts`)은 **의도적으로 preload에서 빠져 있다** — 전역 등록은 Node의 fetch/http를 테스트 런 **전체**에서 happy-dom 구현으로 갈아치우고, 그러면 실제 HTTP 서버를 띄우는 `apps/viewer` 테스트들이 무너진다(실측 21건 실패: diff-server·api/blob·built-serving). DOM이 필요한 테스트는 파일 맨 위에서 `import "../__tests__/happydom";`으로 **파일 단위로만** 켠다(`happydom-smoke.test.ts` 참고).
 
 ### 기여 워크플로 (PR 필수)
 
-- **`main`에 직접 push 금지 — 모든 변경은 브랜치 → PR로 진행한다.** (초기 extraction 시기의 main 직접 push 관례는 종료. 이미 배포·CI가 붙은 상태라 PR 리뷰를 거친다.) 브랜치를 파고 PR을 열면 `pr-check` CI(lint/format/typecheck/test/coverage)가 돌고, 사람이 리뷰·머지한다.
+- **`main`에 직접 push 금지 — 모든 변경은 브랜치 → PR로 진행한다.** (초기 extraction 시기의 main 직접 push 관례는 종료. 이미 배포·CI가 붙은 상태라 PR 리뷰를 거친다.) 브랜치를 파고 PR을 열면 `pr-check` CI(lint+format/typecheck/test/coverage/e2e — 다섯 잡, format은 lint 잡의 스텝)가 돌고, 사람이 리뷰·머지한다.
 - 커밋 메시지는 **Conventional Commits**(`feat:`/`fix:`/`docs:`/`chore:`/`refactor:`/`test:`/`ci:` …) — release-please가 이를 근거로 버전·CHANGELOG·릴리스를 관리하기 때문(`feat:`→minor, `fix:`→patch, `feat!:`/`BREAKING CHANGE:`→major; `docs`/`chore`/`test`/`ci` 등은 릴리스 미유발).
 
 ### CI / 릴리스
@@ -87,7 +97,7 @@ bun run format
 - **사용자 게이트(부트스트랩, 자동화 불가)**: npm은 신규 패키지 최초 버전을 OIDC로 못 올린다(설정 UI가 패키지 존재를 요구, npm/cli #8544). 따라서 순서: ① `0.1.0`을 **로컬에서 토큰/`npm login`으로 1회 수동 publish**(패키지 생성) → ② npmjs.com 패키지 Settings에서 trusted publisher 등록(org `say8425`, repo `diffdeck`, workflow `release.yml`, environment 없음) → ③ 이후 release-please가 낸 릴리스 PR을 사람이 머지하면 CI가 tokenless로 publish. provenance엔 public repo 필요(✅).
 - **CI는 아직 "신호"이고 "게이트"가 아니다 — required status checks가 비어 있다.** `main` 룰셋에는 `deletion`·`non_fast_forward`만 있고(`gh api repos/say8425/diffdeck/branches/main/protection` → 404 Branch not protected), 어떤 체크도 required로 지정돼 있지 않다. 그래서 **빨간 CI로도 머지 버튼이 열린다**(실측: e2e가 `IN_PROGRESS`인데 `mergeStateStatus: CLEAN`). e2e를 포함해 다섯 잡 전부에 해당하는 기존 상태다. 진짜 게이트로 만들려면 룰셋에 `required_status_checks`로 `lint`·`typecheck`·`test`·`coverage`·`e2e`를 등록해야 한다 — 워크플로 파일만으로는 안 된다. (같은 종류의 "코드가 아니라 저장소 설정" 항목이라 바로 아래 항목과 나란히 둔다.)
 - **저장소 설정 요구사항**: Settings → Actions → General → Workflow permissions의 **"Allow GitHub Actions to create and approve pull requests"** 가 켜져 있어야 한다(기본 OFF). 꺼져 있으면 release-please가 버전 계산·브랜치·커밋까지 다 만들어놓고 **PR 생성 단계에서만** `GitHub Actions is not permitted to create or approve pull requests` 로 실패한다. API로는 `gh api -X PUT repos/say8425/diffdeck/actions/permissions/workflow -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true`.
-- **배포 산출물**: `build.ts`가 `dist/cli.js`에 `#!/usr/bin/env bun` 셰뱅 + 실행권한을 부여해 `bunx`뿐 아니라 `npx`/직접 실행에서도 bun으로 구동된다(`// @bun` 마커는 셰뱅 다음 줄에 유지).
+- **배포 산출물**: `build.ts`가 `dist/cli.js`에 `#!/usr/bin/env bun` 셰뱅 + 실행권한을 부여해 `bunx`뿐 아니라 `npx`/직접 실행에서도 bun으로 구동된다(`// @bun` 마커는 셰뱅 다음 줄에 유지). **`apps/viewer/package.json`에는 `dependencies`가 하나도 없다 — 의도된 상태다**: 배포되는 건 `files` 필드대로 `dist` + `LICENSE` + `NOTICE`뿐이라 사용자는 `bunx` 시점에 아무것도 resolve하지 않는다. 두 축이 다른 이유로 그렇다 — `dist/cli.js`(26KB)는 **애초에 외부 deps를 안 쓴다**(서버·CLI가 Bun `$`와 node 빌트인만 쓴다: 번들에 남은 import가 `fs`·`os`·`path`뿐), 반면 `dist/viewer/main.js`(10.9MB)와 `dist/viewer/worker.js`(836KB)는 shiki와 문법 전량을 **번들 안에 품는다**. 뒤집으면 **새 런타임 import를 추가할 때 `dependencies`에 적을 곳이 없다** — 번들에 실제로 들어갔는지 `bun run build` 후 산출물에서 확인해야 하고, external로 남은 것은 설치 시점에 그냥 없다. 산출물은 `dist/cli.js` + `dist/viewer/{main.js,worker.js,index.html}` + `dist/skills/diffdeck/SKILL.md` 다섯이다.
 
 ### 렌더 패리티 하니스
 
@@ -104,7 +114,7 @@ cd scripts/parity && python3 -m http.server 8099 # http://127.0.0.1:8099/index.h
 
 ### 수정 시 주의사항
 
-- **CodeView(diffs) 재작성 금지** — 27k줄 vendored 엔진을 blackbox로 사용. 가상화·shiki 스트리밍·shadow DOM 등 상용급 난이도, 재작성 이득 없음.
+- **CodeView(diffs) 재작성 금지** — 29.5k줄 vendored 엔진을 blackbox로 사용. 가상화·shiki 스트리밍·shadow DOM 등 상용급 난이도, 재작성 이득 없음.
 - **CodeView 인스턴스 수명 — 재생성은 `!codeView`일 때만**: `renderPatch`가 CodeView를 새로 만드는 건 첫 렌더와 빈 상태 복귀뿐이다. unified↔split 전환은 살아 있는 인스턴스에 `setOptions(codeViewOptions())` → `setItems` → `render`로 태운다. 재생성하면 `diffMount.replaceChildren()`이 **스크롤 컨테이너 자신**(`#diff`가 곧 `diffMount`)을 비워 scrollHeight가 무너지고 브라우저가 scrollTop을 0으로 클램프해, 읽던 위치를 잃는다. 엔진은 `diffStyle`을 item-layout 옵션으로 취급하고(`hasItemLayoutOptionChanged`) `setOptions` 진입 즉시 `capturePendingLayoutAnchor()`로 앵커를 잡아 렌더 경로에서 `resolveAnchoredScrollTop()`으로 뷰포트를 붙든다(픽셀이 아니라 의미론적 앵커 — split은 scrollHeight가 대략 절반이라 픽셀 복원은 엉뚱한 파일에 착지한다). **호출 순서 자체가 계약이다**: `setOptions`가 `setItems`보다 먼저여야 앵커가 전환 전 레이아웃을 본다. `setOptions`가 건 인덱스 0 리셋이 뒤이은 `setItems`의 부분 리셋에 지워지지 않는 건 `markLayoutDirtyFromIndex()`가 기존 인덱스와 min을 취하기 때문이라, 순서를 뒤집으면 테스트가 못 잡는 채로 조용히 깨진다. `config.overscrollSize`를 생성 분기에서만 세팅해도 되는 이유도 여기 있다 — `setOptions`는 `config`를 건드리지 않아 이후 옵션 변경을 전부 살아남는다. 회귀망: `diffstyle-scroll.e2e.ts`(양방향 앵커 오프셋 + `data-diff-type`).
 - **평범한 데이터 갱신에도 픽셀 `scrollTo`를 얹지 말 것**: refresh·`--watch` 갱신 경로는 `setItems` → `render`만 부르고 스크롤 복원을 엔진에 맡긴다. `reconcileItems`가 `markLayoutDirtyFromIndex`를 세우면 렌더 경로가 `layoutDirtyIndex != null`을 보고 scroll correction을 무조건 재무장하고, 캐시된 앵커가 없으면 `getScrollAnchor`가 `renderState`에서 새로 만들어 보정한다 — 즉 이미 의미론적으로 보존된다. 여기에 `scrollTo({type:"position"})`를 얹으면 잉여가 아니라 **해롭다**: ① `position` 타깃은 애초에 항등 복원이 아니다 — `resolveScrollTargetTop`이 클램프되지 않은 값에서 `getStickyHeaderOffset()`(= `diffHeaderHeight` 44, 우리가 `stickyHeaders: true`를 주고 `disableFileHeader`를 안 주므로)을 빼므로, 모든 refresh·watch 폴링마다 뷰포트가 44px씩 위로 밀렸다, ② 뷰포트 *위쪽* 파일 길이가 변하면 아래 내용이 통째로 밀리는데 옛 픽셀로 되돌아가 읽던 줄이 어긋난다(실측: 60줄 증가에 1244px 드리프트), ③ `scrollTo`가 세우는 `pendingScrollTarget`을 프레임이 앵커보다 우선해 적용하므로, 스타일 전환의 렌더가 아직 큐에만 있는 1프레임 창에 갱신이 겹치면(그 창에선 `renderedDiffStyle`이 이미 갱신돼 이 갱신 분기로 들어온다) 전환 전 픽셀값이 앵커를 덮어써 split 기준 거의 바닥으로 착지한다. 보정이 항상 도는 건 아니고 그럴 필요도 없다: `setItems`엔 아무것도 dirty로 안 세우는 append 전용 경로가 있고(위쪽이 안 움직였으니 보정할 게 없다), 앵커 아이템이 사라지거나 목록이 렌더 윈도우보다 작아져 `renderState`가 리셋되면 앵커 해석이 비어 돌아온다 — 그 폴백은 클램프된 현재 위치라 옛 "값 −44"보다 낫다. 회귀망: `update-anchor.e2e.ts`(위쪽 파일 증가 + rAF 게이트로 결정화한 한 프레임 레이스).
 - **`#diff`에 innerHTML을 쓰기 전엔 살아 있는 CodeView가 없는지 확인**: 위와 같은 이유로 이 노드는 CodeView가 `setup()`에서 자기 컨테이너를 append한 스크롤 컨테이너라, 덮어쓰면 그 컨테이너가 문서에서 떨어져 나간다. `CodeView.setup()`은 이미 setup된 인스턴스의 재부착을 거부하므로(`already setup`) 인스턴스를 새로 만들기 전까지 패널이 영구히 빈 채로 남는다. 그래서 `load()`의 실패 카드는 `!codeView`로 가드한다 — `!lastFiles`가 아니다: 변경 없는 리포는 `lastFiles === []`(truthy)지만 `teardownViews()`로 이미 codeView가 비워진 뒤라 카드를 쓰는 게 안전하고, `!lastFiles`로 걸면 그 경우에 상태 라벨만 실패를 말하고 화면은 "No changes."를 계속 주장한다. 회귀망: `load-failure.e2e.ts`.
@@ -121,11 +131,11 @@ cd scripts/parity && python3 -m http.server 8099 # http://127.0.0.1:8099/index.h
 - **preact/react 런타임 의존 없음** — Plan 3(de-preact)에서 trees의 preact 렌더 스킨을 vanilla로 완전히 포팅했고, 어느 `packages/*/package.json`·`apps/viewer/package.json`에도 preact/react가 없다(devDep·peer 포함).
 - **라이선스**: 각 `packages/*/LICENSE`(Apache-2.0) + `packages/trees/NOTICE.md`(headless-tree MIT 유래) + 최상위 `NOTICE` 보존. 파일 수정 사실 고지 유지.
 - **`*.css?inline` ambient 선언**: 소비자(앱)의 tsconfig가 패키지 `src/**`를 glob include하지 않으면 안 보임 — Plan 2 앱 tsconfig에서 배선 필요.
-- **cc-statusline 잔재 데드코드 제거됨**: `server/ensure.ts`(spawn-if-not-running 데몬 ensure)와 `server.ts`의 `idleTimeoutMs` idle-shutdown을 제거했다. diffdeck의 CLI는 서버를 **foreground**로 띄워 Ctrl+C로 종료하는 모델이라(cc-statusline처럼 statusline이 백그라운드 데몬을 spawn-if-not-running으로 관리하는 구조가 아님) 두 기능 모두 미사용 상태였다.
-- **CLI 플래그 변경 시 `skills/diffdeck/SKILL.md` 동기화 필수**: `apps/viewer/cli/args.ts`(파싱)·`cli.ts`(`--help` 텍스트)에 플래그를 추가·변경·삭제하면 `skills/diffdeck/SKILL.md`의 `## Options` 섹션도 같은 커밋에서 갱신한다. 이 파일은 `install-skill`로 `~/.claude/skills/`에 배포되고(`--codex` 시 `~/.agents/skills/`에도) Claude Code 플러그인은 `skills/` 디렉터리를 자동 스캔해 로드하는, 에이전트가 diffdeck를 구동할 때 참조하는 유일한 문서라 — CLI 표면과 조용히 드리프트하면 에이전트가 존재하는 옵션(`--untracked`/`--watch`/`--split` 등)을 모른 채 구동하게 된다. `apps/viewer/__tests__/skill-flags-parity.test.ts`가 `cli.ts`의 `HELP` Options 블록과 SKILL.md를 비교해 드리프트를 자동으로 잡아낸다.
+- **cc-statusline 잔재 데드코드 제거됨**: `server/ensure.ts`(spawn-if-not-running 데몬 ensure)와 `server.ts`의 `idleTimeoutMs` idle-shutdown을 제거했고, 뒤늦게 `config.ts`의 `isDiffViewerDisabled`/`DIFFDECK_DISABLE`도 지웠다(diffdeck에선 **호출부가 한 번도 없었다** — 유일한 참조가 자기 테스트라 커버리지 100%가 그대로 유지돼 게이트로는 원리적으로 안 드러났다. 커버리지 초록은 "쓰인다"는 증거가 아니다). diffdeck의 CLI는 서버를 **foreground**로 띄워 Ctrl+C로 종료하는 모델이라(cc-statusline처럼 statusline이 백그라운드 데몬을 spawn-if-not-running으로 관리하는 구조가 아님) 이 기능들이 전부 미사용이었다. 참고로 `server.ts`의 `idleTimeout: 120`(Bun.serve 소켓 타임아웃)은 제거된 idle-shutdown과 **다른 것**이고 지금도 살아 있는 계약이다 — "Loading…" 항목의 45+45 예산이 이 값에 걸린다.
+- **CLI 플래그를 바꾸면 문서 일곱이 같은 커밋에서 함께 움직인다.** `apps/viewer/cli/args.ts`(파싱)와 `cli.ts`의 `HELP`(단일 진실)에 플래그를 추가·변경·삭제하면, 그 표면을 사람에게 되풀이해 말하는 문서가 전부 따라와야 한다: `skills/diffdeck/SKILL.md`, `README.md`(루트), `apps/viewer/README.md`(**npm 패키지 페이지** — 루트 README와 별개 파일이다), `docs/README.{ko,ja,zh,es}.md` 넷. SKILL.md가 특별한 이유는 따로 있다 — `install-skill`이 `~/.claude/skills/`에 배포하고(`--codex` 시 `~/.agents/skills/`에도) Claude Code 플러그인이 `skills/`를 자동 스캔하는, **에이전트가 diffdeck를 구동할 때 읽는 유일한 문서**라 드리프트하면 에이전트가 존재하는 옵션을 모른 채 구동한다. `apps/viewer/__tests__/docs-flags-parity.test.ts`가 `HELP`의 Options 블록과 **일곱 문서 전부**를 대조한다. **한 문서만 보는 게이트는 나머지를 지키지 않는다** — 예전엔 이 테스트가 SKILL.md만 봤고, 그 사이 `--fold-with-tree`가 npm README와 번역 4종에서 조용히 빠져 있었다(플래그를 만든 #14이 루트 README와 SKILL.md만 갱신했다). 문서를 새로 추가하면 그 테스트의 `DOCS` 배열에도 넣어야 같은 함정을 다시 파지 않는다.
 - **`hidden`으로 숨기는 노드에 author `display`를 선언하면 `[hidden]{display:none}`을 반드시 짝지어라.** author origin이 UA 규칙을 이겨 영구 노출된다. `#grab-popover[hidden]`이 `display:flex` 뒤에 명시된 이유이고, 과거 `.grab-hint`에서 두 번째로 밟았다(지금은 `.grab-hint`가 sr-only라 `hidden`을 토글하지 않아 이 함정에서 벗어났다 — 규칙 자체는 `#grab-popover`에 그대로 유효하다). **happy-dom은 `textContent`만 보므로 유닛이 못 잡고 실브라우저에서만 드러난다** — 이런 실패는 e2e에서만 잡힌다.
 - 워커 로드 실패 폴백은 엔진이 아니라 앱 워치독이 담당한다(회귀망: worker-highlight.e2e.ts의 폴백 테스트).
-- **프로세스 cwd가 삭제되면 diffdeck 전체가 죽는다 — 그래서 `cli.ts`가 기동 직후 `/`로 이탈한다.** cwd가 unlink된 프로세스는 **자식 프로세스를 하나도 생성할 수 없다**(자식이 상속할 cwd를 커널이 해석하지 못한다). 이건 Bun Shell의 동작이 아니라 OS 제약이라 `.cwd(repo)`를 명시해도, 셸을 안 거치는 `Bun.spawn`을 써도 `ENOENT: posix_spawn`으로 똑같이 죽는다(실측) — **호출부에서 고칠 수 있는 방법이 없다.** 증상은 `/api/diff`가 **repo와 무관하게** 400 `not a git repository`를 내는 것이고, `/api/ping`(204)과 정적 페이지(200)는 서브프로세스를 안 띄워서 멀쩡하므로 "서버는 살아있는데 diff만 안 된다"로 오진하기 쉽다. 감별: 403이면 토큰/포트 문제고, 400이면서 repo를 바꿔도 동일하면 이 문제다. 장수 데몬(cc-statusline이 띄운다 — `/api/ping`의 pid 헤더 주석 참고)이 기동 시점의 worktree를 물고 있다가 그 worktree가 삭제되면 발생한다. 예방은 `cli.ts`가 `repo`를 읽은 **직후** `toSafeCwd()`로 이탈하는 것이고(순서가 계약이다 — 먼저 이탈하면 `repo`가 `/`가 된다), 자가회복은 `server.ts` 핸들러 진입부가 `repairCwd`가 주입된 경우에만(단축평가 — 없으면 `isCwdAlive` 호출 자체를 건너뛴다, `repairCwd`를 안 넘긴 임베드 호스트에게 감지 자체가 순수 비용이 되면 안 되기 때문이다) `isCwdAlive`로 감지해 그 `repairCwd`를 부르는 것이다. **감지는 반드시 `existsSync(process.cwd())`여야 한다** — `existsSync(".")`·`statSync(".")`는 unlink된 inode를 살려두는 cwd 파일 디스크립터 때문에 항상 true라 원리적으로 못 잡는다. `process.chdir()`이 프로세스 전역 부작용이라 라이브러리인 `startDiffServer`는 감지만 하고 복구는 프로세스를 소유한 `cli.ts`에서 주입받는다. 회귀망: `daemon-cwd.e2e.ts`가 사용자에게 보이는 계약(기동 디렉토리가 삭제된 데몬이 다른 repo를 계속 서빙한다)을 종단 검증하는데, **예방과 자가회복을 구분하지는 못한다** — 둘 중 하나만 살아 있어도 통과하고 둘 다 없어야 400으로 빨간불이 된다(실측). 가드가 라우트 분기보다 먼저 돌아 첫 요청에서 git 호출 전에 cwd를 되살리기 때문이다. 기제별 격리는 유닛이 맡는다: `cli-run.test.ts`(예방 — 호출 순서와 주입), `diff-server.test.ts`(자가회복 4종 — 커버리지가 branch를 안 세므로 호출/미호출을 각각 찌르고, 나머지 둘은 단축평가로 감지가 건너뛰는 경로와 `cwdDeps` 생략 시 REAL_CWD_DEPS가 실제로 쓰이는 경로의 함수 커버리지를 찌른다), `diff-cwd.test.ts`(판정). 이후 git 호출 17곳 중 16곳은 `git -C ${repo}`로 repo를 조준하지만, 17번째인 `prBaseName`(`diff.ts:29-30`)은 `gh pr view`라 `-C`가 없고 `.cwd(repo)`로만 조준한다 — "전부 `-C`"로 읽으면 코드를 잘못 스캔하게 되지만, 결론(모두 repo를 명시적으로 조준하므로 cwd가 `/`여도 정상)은 그대로다. cwd 의존 지점이 하나 더 있다: `server.ts`의 `resolve(cfg.viewerDir)`는 chdir **이후**에 돌아 상대경로였다면 `/` 기준으로 풀리는데, 프로덕션 값(`${import.meta.dir}/viewer`)과 테스트(mkdtemp 절대경로)가 둘 다 절대경로라 현재 깨지는 건 없다. `/api/blob`의 경로 탈출 가드는 안전하다 — `getFileBytes`(`diff.ts:220-221`)가 `resolve(repo)`/`resolve(root, path)`로 가드를 세우고 실제 읽기는 `readFileSync(join(repo, path))`라 OS가 syscall 시점에 같은 cwd로 풀어 가드 기준과 읽기 기준이 함께 움직이므로 탈출 구멍이 열리지 않는다 — cwd가 조용히 바뀌며 보안 버그가 될 뻔했던 유일한 지점이라 기록해 둘 가치가 있다.
+- **프로세스 cwd가 삭제되면 diffdeck 전체가 죽는다 — 그래서 `cli.ts`가 기동 직후 `/`로 이탈한다.** cwd가 unlink된 프로세스는 **자식 프로세스를 하나도 생성할 수 없다**(자식이 상속할 cwd를 커널이 해석하지 못한다). 이건 Bun Shell의 동작이 아니라 OS 제약이라 `.cwd(repo)`를 명시해도, 셸을 안 거치는 `Bun.spawn`을 써도 `ENOENT: posix_spawn`으로 똑같이 죽는다(실측) — **호출부에서 고칠 수 있는 방법이 없다.** 증상은 `/api/diff`가 **repo와 무관하게** 400 `not a git repository`를 내는 것이고, `/api/ping`(204)과 정적 페이지(200)는 서브프로세스를 안 띄워서 멀쩡하므로 "서버는 살아있는데 diff만 안 된다"로 오진하기 쉽다. 감별: 403이면 토큰/포트 문제고, 400이면서 repo를 바꿔도 동일하면 이 문제다. 장수 데몬(cc-statusline이 띄운다 — `/api/ping`의 pid 헤더 주석 참고)이 기동 시점의 worktree를 물고 있다가 그 worktree가 삭제되면 발생한다. 예방은 `cli.ts`가 `repo`를 읽은 **직후** `toSafeCwd()`로 이탈하는 것이고(순서가 계약이다 — 먼저 이탈하면 `repo`가 `/`가 된다), 자가회복은 `server.ts` 핸들러 진입부가 `repairCwd`가 주입된 경우에만(단축평가 — 없으면 `isCwdAlive` 호출 자체를 건너뛴다, `repairCwd`를 안 넘긴 임베드 호스트에게 감지 자체가 순수 비용이 되면 안 되기 때문이다) `isCwdAlive`로 감지해 그 `repairCwd`를 부르는 것이다. **감지는 반드시 `existsSync(process.cwd())`여야 한다** — `existsSync(".")`·`statSync(".")`는 unlink된 inode를 살려두는 cwd 파일 디스크립터 때문에 항상 true라 원리적으로 못 잡는다. `process.chdir()`이 프로세스 전역 부작용이라 라이브러리인 `startDiffServer`는 감지만 하고 복구는 프로세스를 소유한 `cli.ts`에서 주입받는다. (`cli.ts`는 서버를 띄운 직후 `prewarmDiff`(`server/prewarm.ts`)로 자기 서버의 `/api/diff`를 `working`·`base` **순차로** 두 번 호출해 payload 캐시를 데운다 — 브라우저가 뜨는 동안 첫 diff 빌드를 선실행시키는 best-effort 경로다. 동시 호출이 아닌 이유는 `BUILD_CONCURRENCY=8`이 호출당이라 두 모드를 겹치면 기동 직후 git 서브프로세스 버스트가 배로 뛰기 때문이고, 이는 아래 "Loading…" 항목의 재시도 1회 제한과 같은 근거다. 실패해도 뷰어는 정상 동작한다.) 회귀망: `daemon-cwd.e2e.ts`가 사용자에게 보이는 계약(기동 디렉토리가 삭제된 데몬이 다른 repo를 계속 서빙한다)을 종단 검증하는데, **예방과 자가회복을 구분하지는 못한다** — 둘 중 하나만 살아 있어도 통과하고 둘 다 없어야 400으로 빨간불이 된다(실측). 가드가 라우트 분기보다 먼저 돌아 첫 요청에서 git 호출 전에 cwd를 되살리기 때문이다. 기제별 격리는 유닛이 맡는다: `cli-run.test.ts`(예방 — 호출 순서와 주입), `diff-server.test.ts`(자가회복 4종 — 커버리지가 branch를 안 세므로 호출/미호출을 각각 찌르고, 나머지 둘은 단축평가로 감지가 건너뛰는 경로와 `cwdDeps` 생략 시 REAL_CWD_DEPS가 실제로 쓰이는 경로의 함수 커버리지를 찌른다), `diff-cwd.test.ts`(판정). 이후 git 호출 17곳 중 16곳은 `git -C ${repo}`로 repo를 조준하지만, 17번째인 `prBaseName`(`diff.ts:29-30`)은 `gh pr view`라 `-C`가 없고 `.cwd(repo)`로만 조준한다 — "전부 `-C`"로 읽으면 코드를 잘못 스캔하게 되지만, 결론(모두 repo를 명시적으로 조준하므로 cwd가 `/`여도 정상)은 그대로다. cwd 의존 지점이 하나 더 있다: `server.ts`의 `resolve(cfg.viewerDir)`는 chdir **이후**에 돌아 상대경로였다면 `/` 기준으로 풀리는데, 프로덕션 값(`${import.meta.dir}/viewer`)과 테스트(mkdtemp 절대경로)가 둘 다 절대경로라 현재 깨지는 건 없다. `/api/blob`의 경로 탈출 가드는 안전하다 — `getFileBytes`(`diff.ts:221-222`)가 `resolve(repo)`/`resolve(root, path)`로 가드를 세우고 실제 읽기는 `readFileSync(join(repo, path))`라 OS가 syscall 시점에 같은 cwd로 풀어 가드 기준과 읽기 기준이 함께 움직이므로 탈출 구멍이 열리지 않는다 — cwd가 조용히 바뀌며 보안 버그가 될 뻔했던 유일한 지점이라 기록해 둘 가치가 있다.
 
 ### 로드맵 (각각 별도 sub-plan)
 
diff --git a/README.md b/README.md
index 161a7ff..a965736 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ A local diff viewer, built on a vendored fork of Pierre's [`@pierre/diffs`](http
 
 diffdeck is the local diff viewer originally embedded in [cc-statusline](https://github.com/say8425/cc-statusline), extracted into its own product. Instead of depending on the upstream Pierre packages — which move fast (`@pierre/diffs` churns heavily; `@pierre/trees` is pre-1.0 beta) and whose internal markup we had already coupled to heavily — diffdeck **recovers the original TypeScript from the packages' source maps and vendors it**, so we own the rendering engine outright.
 
-The result is a Bun-workspace monorepo where a commodity-hard, framework-agnostic diff engine (Pierre's `CodeView`, ~27k lines) is kept as-is, while the parts we customize live in our own code.
+The result is a Bun-workspace monorepo where a commodity-hard, framework-agnostic diff engine (Pierre's `CodeView`, ~29.5k lines) is kept as-is, while the parts we customize live in our own code.
 
 ## Features
 
@@ -165,8 +165,10 @@ packages/
   theming/      @diffdeck/theming      theme system + 10 vendored shiki theme JSONs
   diffs/        @diffdeck/diffs         CodeView diff-rendering engine
   trees/        @diffdeck/trees         FileTree engine (vanilla render)
-apps/viewer/    @say8425/diffdeck — CLI + diff-server (data API) + browser viewer + agent skill
+apps/viewer/    @say8425/diffdeck — CLI + diff-server (data API) + browser viewer
+skills/         the agent skill (SKILL.md), copied into the package at build time
 scripts/        source-map extraction tool, css-inline Bun plugin, render-parity harness
+docs/           README translations and screenshots
 ```
 
 Dependency graph: `path-store` (no deps) ← `trees`; `theming` (shiki) ← `diffs`, `trees`. Runtime externals: shiki + `@shikijs/*`, `diff`, `hast-util-to-html`, `lru_map`.
@@ -191,9 +193,10 @@ Three lanes:
   collection, so this never launches a browser.
 - `bun run test:coverage` — the same suite with a **100% coverage gate on
   diffdeck's owned runtime code** (`apps/viewer/{browser,cli,server}`).
-  Intentionally out of the gate: the vendored `packages/*`, the browser entry
-  `main.ts` (integration entry — exercised by the e2e suite instead, not
-  in-process), and `build.ts`.
+  Intentionally out of the gate: the vendored `packages/*`, the tooling under
+  `scripts/`, the browser entry `main.ts` (integration entry — exercised by the
+  e2e suite instead, not in-process), `build.ts`, and the specs themselves
+  (`*.test.ts`, `e2e/**`).
 - `bun run test:e2e` — the Playwright real-browser suite (`apps/viewer/e2e/`).
   Drives the system Google Chrome via `channel: "chrome"` (no Chromium
   download) and covers `main.ts` and the vendored render paths end-to-end.
diff --git a/apps/viewer/README.md b/apps/viewer/README.md
index d5b1637..41a7ab8 100644
--- a/apps/viewer/README.md
+++ b/apps/viewer/README.md
@@ -16,23 +16,24 @@ default browser.
 
 ## Options
 
-| Flag              | Description                                                  |
-| ----------------- | ------------------------------------------------------------ |
-| `--port <n>`      | Port to serve on (default: `$DIFFDECK_PORT` or `49573`)      |
-| `--no-open`       | Do not open a browser automatically (prints the URL instead) |
-| `--untracked`     | Start with untracked files included                          |
-| `--watch`         | Start with watch (auto-refresh) on                           |
-| `--no-flatten`    | Start with the file tree un-flattened (flatten is on)        |
-| `--tree-right`    | Start with the file tree on the right                        |
-| `--split`         | Start in split view (unified is the default)                 |
-| `--hide-tree`     | Start with the file tree hidden                              |
-| `-h`, `--help`    | Show help                                                    |
-| `-v`, `--version` | Show version                                                 |
+| Flag               | Description                                                  |
+| ------------------ | ------------------------------------------------------------ |
+| `--port <n>`       | Port to serve on (default: `$DIFFDECK_PORT` or `49573`)      |
+| `--no-open`        | Do not open a browser automatically (prints the URL instead) |
+| `--untracked`      | Start with untracked files included                          |
+| `--watch`          | Start with watch (auto-refresh) on                           |
+| `--no-flatten`     | Start with the file tree un-flattened (flatten is on)        |
+| `--tree-right`     | Start with the file tree on the right                        |
+| `--split`          | Start in split view (unified is the default)                 |
+| `--hide-tree`      | Start with the file tree hidden                              |
+| `--fold-with-tree` | Start with sidebar directory collapse synced to diff folds   |
+| `-h`, `--help`     | Show help                                                    |
+| `-v`, `--version`  | Show version                                                 |
 
 The view flags (`--untracked`, `--watch`, `--no-flatten`, `--tree-right`,
-`--split`, `--hide-tree`) set the initial state for this launch only — they
-don't change your saved preferences, and the in-app toggles reflect the
-launched state.
+`--split`, `--hide-tree`, `--fold-with-tree`) set the initial state for this
+launch only — they don't change your saved preferences, and the in-app toggles
+reflect the launched state.
 
 ## Environment
 
diff --git a/apps/viewer/__tests__/diff-config.test.ts b/apps/viewer/__tests__/diff-config.test.ts
index 5d9e6f7..151ef1f 100644
--- a/apps/viewer/__tests__/diff-config.test.ts
+++ b/apps/viewer/__tests__/diff-config.test.ts
@@ -2,7 +2,6 @@ import { describe, expect, test } from "bun:test";
 import {
 	DEFAULT_DIFF_PORT,
 	getCacheDir,
-	isDiffViewerDisabled,
 	resolveDiffPort,
 } from "../server/config.ts";
 
@@ -20,14 +19,6 @@ describe("resolveDiffPort", () => {
 	});
 });
 
-describe("isDiffViewerDisabled", () => {
-	test("true only when exactly '1'", () => {
-		expect(isDiffViewerDisabled({ DIFFDECK_DISABLE: "1" })).toBe(true);
-		expect(isDiffViewerDisabled({ DIFFDECK_DISABLE: "0" })).toBe(false);
-		expect(isDiffViewerDisabled({})).toBe(false);
-	});
-});
-
 describe("getCacheDir", () => {
 	test("respects XDG_CACHE_HOME", () => {
 		expect(getCacheDir({ XDG_CACHE_HOME: "/tmp/xdg" })).toBe(
diff --git a/apps/viewer/__tests__/docs-flags-parity.test.ts b/apps/viewer/__tests__/docs-flags-parity.test.ts
new file mode 100644
index 0000000..30b82e0
--- /dev/null
+++ b/apps/viewer/__tests__/docs-flags-parity.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { HELP } from "../cli.ts";
+
+const repoRoot = join(import.meta.dir, "..", "..", "..");
+
+// cli.ts의 HELP가 CLI 표면의 단일 진실이고, 아래 문서들은 전부 그 표면을
+// 사람에게 되풀이해 말한다. 예전엔 SKILL.md 하나만 대조했는데, 그 사이
+// `--fold-with-tree`가 npm README(apps/viewer/README.md)와 번역 4종에서
+// 조용히 빠져 있었다 — 플래그가 생긴 #14이 루트 README와 SKILL.md만
+// 갱신했기 때문이다. 게이트가 한 문서만 보면 나머지는 아무도 지키지 않는다.
+const DOCS = [
+	"skills/diffdeck/SKILL.md",
+	"README.md",
+	"apps/viewer/README.md",
+	"docs/README.ko.md",
+	"docs/README.ja.md",
+	"docs/README.zh.md",
+	"docs/README.es.md",
+] as const;
+
+const metaFlags = new Set(["--help", "--version"]);
+
+const extractOptionsFlags = (help: string): string[] => {
+	const optionsBlock = help.split("Options:")[1].split(/\n\s*\n/)[0];
+	const tokens = optionsBlock.match(/--[a-z][a-z-]*/g) ?? [];
+	return [...new Set(tokens)].filter((flag) => !metaFlags.has(flag));
+};
+
+/**
+ * 문서에서 플래그는 항상 코드 스팬으로 적힌다: `--split` 또는 `--port <n>`.
+ * 여는 백틱을 요구해 산문 속 우연한 일치를 막고, 뒤에 백틱이나 공백을 요구해
+ * `--tree-right`가 가상의 `--tree-right-foo`에 매칭되지 않게 한다.
+ */
+const documents = (content: string, flag: string): boolean =>
+	new RegExp(`\`${flag}[\`\\s]`).test(content);
+
+describe("CLI flag parity between cli.ts HELP and every doc that lists flags", () => {
+	const flags = extractOptionsFlags(HELP);
+
+	test("HELP's Options block has flags to check", () => {
+		expect(flags.length).toBeGreaterThan(0);
+	});
+
+	test("HELP's Options block excludes meta-flags --help/--version", () => {
+		expect(flags).not.toContain("--help");
+		expect(flags).not.toContain("--version");
+	});
+
+	for (const doc of DOCS) {
+		const content = readFileSync(join(repoRoot, doc), "utf8");
+		for (const flag of flags) {
+			test(`${doc} documents ${flag}`, () => {
+				expect(documents(content, flag)).toBe(true);
+			});
+		}
+	}
+});
diff --git a/apps/viewer/__tests__/skill-flags-parity.test.ts b/apps/viewer/__tests__/skill-flags-parity.test.ts
deleted file mode 100644
index 1b6a7be..0000000
--- a/apps/viewer/__tests__/skill-flags-parity.test.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { HELP } from "../cli.ts";
-
-const skillPath = join(
-	import.meta.dir,
-	"..",
-	"..",
-	"..",
-	"skills",
-	"diffdeck",
-	"SKILL.md",
-);
-
-const metaFlags = new Set(["--help", "--version"]);
-
-const extractOptionsFlags = (help: string): string[] => {
-	const optionsBlock = help.split("Options:")[1].split(/\n\s*\n/)[0];
-	const tokens = optionsBlock.match(/--[a-z][a-z-]*/g) ?? [];
-	return [...new Set(tokens)].filter((flag) => !metaFlags.has(flag));
-};
-
-describe("SKILL.md Options parity with cli.ts HELP", () => {
-	const flags = extractOptionsFlags(HELP);
-
-	test("HELP's Options block has flags to check", () => {
-		expect(flags.length).toBeGreaterThan(0);
-	});
-
-	test("HELP's Options block excludes meta-flags --help/--version", () => {
-		expect(flags).not.toContain("--help");
-		expect(flags).not.toContain("--version");
-	});
-
-	const skillContent = readFileSync(skillPath, "utf8");
-
-	for (const flag of extractOptionsFlags(HELP)) {
-		test(`SKILL.md documents ${flag}`, () => {
-			expect(skillContent).toContain(`\`${flag}`);
-		});
-	}
-});
diff --git a/apps/viewer/server/config.ts b/apps/viewer/server/config.ts
index 98bf6e8..73fd4ef 100644
--- a/apps/viewer/server/config.ts
+++ b/apps/viewer/server/config.ts
@@ -12,9 +12,6 @@ export const resolveDiffPort = (env: Env = process.env): number => {
 	return Number.isInteger(n) && n > 0 && n < 65536 ? n : DEFAULT_DIFF_PORT;
 };
 
-export const isDiffViewerDisabled = (env: Env = process.env): boolean =>
-	env.DIFFDECK_DISABLE === "1";
-
 export const getCacheDir = (env: Env = process.env): string => {
 	const base = env.XDG_CACHE_HOME || join(env.HOME || homedir(), ".cache");
 	return join(base, "diffdeck");
diff --git a/docs/README.es.md b/docs/README.es.md
index 6039182..3ed94fa 100644
--- a/docs/README.es.md
+++ b/docs/README.es.md
@@ -15,7 +15,7 @@ Un visor de diff local, construido sobre un fork vendorizado de los paquetes de
 
 diffdeck es el visor de diff local que originalmente estaba embebido en [cc-statusline](https://github.com/say8425/cc-statusline), ahora extraído como un producto propio. En lugar de depender de los paquetes originales de Pierre — que evolucionan rápido (`@pierre/diffs` cambia mucho; `@pierre/trees` está en beta pre-1.0) y cuyo markup interno ya estaba fuertemente acoplado a nuestro código —, diffdeck **recupera el TypeScript original a partir de los source maps de los paquetes y lo vendoriza**, de modo que somos dueños por completo del motor de renderizado.
 
-El resultado es un monorepo de workspaces de Bun donde un motor de diff sólido y agnóstico de framework (el `CodeView` de Pierre, ~27k líneas) se mantiene tal cual, mientras que las partes que personalizamos viven en nuestro propio código.
+El resultado es un monorepo de workspaces de Bun donde un motor de diff sólido y agnóstico de framework (el `CodeView` de Pierre, ~29.5k líneas) se mantiene tal cual, mientras que las partes que personalizamos viven en nuestro propio código.
 
 ## Características
 
@@ -93,6 +93,7 @@ Opciones:
 | `--tree-right`     | Iniciar con el árbol de archivos a la derecha                                     |
 | `--split`          | Iniciar en vista split (unified es el valor predeterminado)                       |
 | `--hide-tree`      | Iniciar con el árbol de archivos oculto                                            |
+| `--fold-with-tree` | Iniciar con el plegado de directorios de la barra lateral sincronizado con el diff |
 | `-h`, `--help`     | Mostrar ayuda                                                                      |
 | `-v`, `--version`  | Mostrar versión                                                                    |
 
@@ -154,8 +155,10 @@ packages/
   theming/      @diffdeck/theming      sistema de temas + 10 JSONs de temas shiki vendorizados
   diffs/        @diffdeck/diffs         motor de renderizado de diffs CodeView
   trees/        @diffdeck/trees         motor FileTree (render vanilla)
-apps/viewer/    @say8425/diffdeck — CLI + diff-server (API de datos) + visor de navegador + skill de agente
+apps/viewer/    @say8425/diffdeck — CLI + diff-server (API de datos) + visor de navegador
+skills/         el agent skill (SKILL.md), copiado al paquete durante el build
 scripts/        herramienta de extracción de source maps, plugin de Bun css-inline, arnés de paridad de renderizado
+docs/           traducciones del README y capturas de pantalla
 ```
 
 Grafo de dependencias: `path-store` (sin dependencias) ← `trees`; `theming` (shiki) ← `diffs`, `trees`. Externals en runtime: shiki + `@shikijs/*`, `diff`, `hast-util-to-html`, `lru_map`.
@@ -177,7 +180,7 @@ bun run format      # oxfmt
 Tres carriles:
 
 - `bun test` — tests unitarios/de integración, rápidos. Las specs `*.e2e.ts` quedan excluidas de la recolección, así que esto nunca lanza un navegador.
-- `bun run test:coverage` — la misma suite con una **puerta de cobertura del 100% sobre el código de runtime propio de diffdeck** (`apps/viewer/{browser,cli,server}`). Intencionalmente fuera de la puerta: los `packages/*` vendorizados, el punto de entrada del navegador `main.ts` (entry de integración — ejercitado por la suite e2e en su lugar, no in-process), y `build.ts`.
+- `bun run test:coverage` — la misma suite con una **puerta de cobertura del 100% sobre el código de runtime propio de diffdeck** (`apps/viewer/{browser,cli,server}`). Intencionalmente fuera de la puerta: los `packages/*` vendorizados, las herramientas bajo `scripts/`, el punto de entrada del navegador `main.ts` (entry de integración — ejercitado por la suite e2e en su lugar, no in-process), `build.ts`, y las propias specs (`*.test.ts`, `e2e/**`).
 - `bun run test:e2e` — la suite de Playwright con navegador real (`apps/viewer/e2e/`). Conduce el Google Chrome del sistema vía `channel: "chrome"` (sin descarga de Chromium) y cubre `main.ts` y las rutas de render vendorizadas de extremo a extremo.
 
 ### Arnés de paridad de renderizado
diff --git a/docs/README.ja.md b/docs/README.ja.md
index 2672eda..af305ad 100644
--- a/docs/README.ja.md
+++ b/docs/README.ja.md
@@ -15,7 +15,7 @@ Pierre の [`@pierre/diffs`](https://www.npmjs.com/package/@pierre/diffs) と [`
 
 diffdeck は、もともと [cc-statusline](https://github.com/say8425/cc-statusline) に組み込まれていたローカル diff ビューアを、独立した製品として切り出したものです。アップストリームの Pierre パッケージ — 変化が激しく(`@pierre/diffs` は頻繁に破壊的変更が入り、`@pierre/trees` はまだ 1.0 未満のベータ版)、しかも内部マークアップにすでに深く依存していた — にそのまま依存し続ける代わりに、diffdeck は **パッケージのソースマップから元の TypeScript を復元してベンダリングし**、レンダリングエンジンを完全に自前で保有しています。
 
-その結果、改変が難しい、フレームワークに依存しない diff エンジン(Pierre の `CodeView`、約 27,000 行)はそのまま維持しつつ、カスタマイズする部分だけを自前のコードに置く、という構成の Bun ワークスペースのモノレポになっています。
+その結果、改変が難しい、フレームワークに依存しない diff エンジン(Pierre の `CodeView`、約 29,500 行)はそのまま維持しつつ、カスタマイズする部分だけを自前のコードに置く、という構成の Bun ワークスペースのモノレポになっています。
 
 ## 機能
 
@@ -93,6 +93,7 @@ bunx @say8425/diffdeck        # or `diffdeck` if installed globally
 | `--tree-right` | ファイルツリーを右側に配置した状態で開始 |
 | `--split` | split ビューで開始(デフォルトは unified) |
 | `--hide-tree` | ファイルツリーを非表示にした状態で開始 |
+| `--fold-with-tree` | サイドバーのディレクトリ折りたたみを diff の折りたたみと同期した状態で開始 |
 | `-h`, `--help` | ヘルプを表示 |
 | `-v`, `--version` | バージョンを表示 |
 
@@ -154,8 +155,10 @@ packages/
   theming/      @diffdeck/theming      theme system + 10 vendored shiki theme JSONs
   diffs/        @diffdeck/diffs         CodeView diff-rendering engine
   trees/        @diffdeck/trees         FileTree engine (vanilla render)
-apps/viewer/    @say8425/diffdeck — CLI + diff-server (data API) + browser viewer + agent skill
+apps/viewer/    @say8425/diffdeck — CLI + diff-server (data API) + browser viewer
+skills/         エージェントスキル(SKILL.md) — ビルド時にパッケージへコピーされる
 scripts/        source-map extraction tool, css-inline Bun plugin, render-parity harness
+docs/           README の翻訳とスクリーンショット
 ```
 
 依存関係グラフ: `path-store`(依存なし)← `trees`、`theming`(shiki)← `diffs`, `trees`。ランタイムの外部依存: shiki + `@shikijs/*`、`diff`、`hast-util-to-html`、`lru_map`。
@@ -177,7 +180,7 @@ bun run format      # oxfmt
 3つのレーンがあります:
 
 - `bun test` — ユニット/統合テスト、高速。`*.e2e.ts` の spec は収集対象から除外されるため、ブラウザは起動しません。
-- `bun run test:coverage` — 同じテストスイートに、**diffdeck が所有するランタイムコード(`apps/viewer/{browser,cli,server}`)への 100% カバレッジゲート** を加えたもの。意図的にゲート対象外としているのは、ベンダリングされた `packages/*`、ブラウザエントリの `main.ts`(統合エントリ — インプロセスではなく e2e スイートで代わりに検証)、そして `build.ts` です。
+- `bun run test:coverage` — 同じテストスイートに、**diffdeck が所有するランタイムコード(`apps/viewer/{browser,cli,server}`)への 100% カバレッジゲート** を加えたもの。意図的にゲート対象外としているのは、ベンダリングされた `packages/*`、`scripts/` 配下のツール、ブラウザエントリの `main.ts`(統合エントリ — インプロセスではなく e2e スイートで代わりに検証)、`build.ts`、そしてスペック自身(`*.test.ts`、`e2e/**`)です。
 - `bun run test:e2e` — Playwright による実ブラウザスイート(`apps/viewer/e2e/`)。`channel: "chrome"` 経由でシステムの Google Chrome を操作し(Chromium のダウンロードは不要)、`main.ts` とベンダリングされたレンダリングパスをエンドツーエンドでカバーします。
 
 ### レンダーパリティハーネス
diff --git a/docs/README.ko.md b/docs/README.ko.md
index 4c1d731..4d59f42 100644
--- a/docs/README.ko.md
+++ b/docs/README.ko.md
@@ -15,7 +15,7 @@ Pierre의 [`@pierre/diffs`](https://www.npmjs.com/package/@pierre/diffs)와 [`@p
 
 diffdeck는 원래 [cc-statusline](https://github.com/say8425/cc-statusline)에 내장되어 있던 로컬 diff 뷰어를 별도 제품으로 분리한 것입니다. 빠르게 변화하는(`@pierre/diffs`는 변경이 잦고, `@pierre/trees`는 아직 1.0 이전 베타 단계입니다) 업스트림 Pierre 패키지에 의존하는 대신 — 게다가 내부 마크업에 이미 깊이 결합되어 있었기 때문에 — diffdeck는 **패키지의 소스맵에서 원본 TypeScript를 복원해 vendoring**해서, 렌더링 엔진을 완전히 직접 소유합니다.
 
-그 결과 구현하기 어려운, 프레임워크에 종속되지 않는 diff 엔진(Pierre의 `CodeView`, 약 27,000줄)은 그대로 유지하고, 우리가 커스터마이즈하는 부분만 자체 코드에 두는 Bun 워크스페이스 모노레포 구조가 되었습니다.
+그 결과 구현하기 어려운, 프레임워크에 종속되지 않는 diff 엔진(Pierre의 `CodeView`, 약 29,500줄)은 그대로 유지하고, 우리가 커스터마이즈하는 부분만 자체 코드에 두는 Bun 워크스페이스 모노레포 구조가 되었습니다.
 
 ## 기능
 
@@ -93,6 +93,7 @@ bunx @say8425/diffdeck        # or `diffdeck` if installed globally
 | `--tree-right`      | 파일 트리를 오른쪽에 둔 상태로 시작                                 |
 | `--split`           | split 뷰로 시작(unified가 기본값)                                  |
 | `--hide-tree`       | 파일 트리를 숨긴 상태로 시작                                       |
+| `--fold-with-tree`  | 사이드바 디렉토리 접기를 diff 접기와 동기화한 상태로 시작           |
 | `-h`, `--help`      | 도움말 표시                                                        |
 | `-v`, `--version`   | 버전 표시                                                          |
 
@@ -154,8 +155,10 @@ packages/
   theming/      @diffdeck/theming      theme system + 10 vendored shiki theme JSONs
   diffs/        @diffdeck/diffs         CodeView diff-rendering engine
   trees/        @diffdeck/trees         FileTree engine (vanilla render)
-apps/viewer/    @say8425/diffdeck — CLI + diff-server (data API) + browser viewer + agent skill
+apps/viewer/    @say8425/diffdeck — CLI + diff-server (data API) + browser viewer
+skills/         agent skill(SKILL.md) — 빌드 시 패키지로 복사됨
 scripts/        source-map extraction tool, css-inline Bun plugin, render-parity harness
+docs/           README 번역본과 스크린샷
 ```
 
 의존성 그래프: `path-store`(의존성 없음) ← `trees`; `theming`(shiki) ← `diffs`, `trees`. 런타임 외부 의존성: shiki + `@shikijs/*`, `diff`, `hast-util-to-html`, `lru_map`.
@@ -177,7 +180,7 @@ bun run format      # oxfmt
 세 가지 레인으로 구성됩니다:
 
 - `bun test` — 단위/통합 테스트, 빠릅니다. `*.e2e.ts` 스펙은 수집 대상에서 제외되므로 브라우저를 절대 띄우지 않습니다.
-- `bun run test:coverage` — 동일한 스위트를 실행하되 **diffdeck가 직접 소유한 런타임 코드**(`apps/viewer/{browser,cli,server}`)에 대해 **100% 커버리지 게이트**를 적용합니다. 게이트에서 의도적으로 제외된 것: vendoring된 `packages/*`, 브라우저 엔트리 `main.ts`(통합 엔트리 — in-process가 아니라 e2e 스위트로 검증됨), `build.ts`.
+- `bun run test:coverage` — 동일한 스위트를 실행하되 **diffdeck가 직접 소유한 런타임 코드**(`apps/viewer/{browser,cli,server}`)에 대해 **100% 커버리지 게이트**를 적용합니다. 게이트에서 의도적으로 제외된 것: vendoring된 `packages/*`, `scripts/` 아래의 도구, 브라우저 엔트리 `main.ts`(통합 엔트리 — in-process가 아니라 e2e 스위트로 검증됨), `build.ts`, 그리고 스펙 자신(`*.test.ts`, `e2e/**`).
 - `bun run test:e2e` — Playwright 실제 브라우저 스위트(`apps/viewer/e2e/`)입니다. `channel: "chrome"`로 시스템에 설치된 Google Chrome을 구동하며(Chromium 다운로드 없음), `main.ts`와 vendoring된 렌더링 경로를 엔드투엔드로 커버합니다.
 
 ### 렌더 패리티 하네스
diff --git a/docs/README.zh.md b/docs/README.zh.md
index 55a63fc..7e322d8 100644
--- a/docs/README.zh.md
+++ b/docs/README.zh.md
@@ -15,7 +15,7 @@
 
 diffdeck 最初是内置在 [cc-statusline](https://github.com/say8425/cc-statusline) 中的本地 diff 查看器，现已被拆分为独立产品。相比继续依赖上游的 Pierre 包——它们迭代很快（`@pierre/diffs` 变动频繁；`@pierre/trees` 仍处于 1.0 之前的 beta 阶段），而我们又已经深度耦合了它们的内部标记结构——diffdeck **从这些包的 source map 中还原出原始 TypeScript 并将其 vendor（内置）进来**，从而完全掌握渲染引擎的所有权。
 
-最终形成了一个 Bun workspace monorepo：与框架无关、已高度成熟稳定的 diff 引擎（Pierre 的 `CodeView`，约 27k 行代码）保持原样，而我们自定义的部分则保存在自己的代码中。
+最终形成了一个 Bun workspace monorepo：与框架无关、已高度成熟稳定的 diff 引擎（Pierre 的 `CodeView`，约 29.5k 行代码）保持原样，而我们自定义的部分则保存在自己的代码中。
 
 ## 功能
 
@@ -93,6 +93,7 @@ bunx @say8425/diffdeck        # or `diffdeck` if installed globally
 | `--tree-right`      | 启动时文件树显示在右侧                                      |
 | `--split`           | 以 split 视图启动（默认是 unified）                          |
 | `--hide-tree`       | 启动时隐藏文件树                                            |
+| `--fold-with-tree`  | 启动时将侧边栏目录折叠与 diff 折叠同步                       |
 | `-h`, `--help`      | 显示帮助                                                    |
 | `-v`, `--version`   | 显示版本号                                                  |
 
@@ -154,8 +155,10 @@ packages/
   theming/      @diffdeck/theming      theme system + 10 vendored shiki theme JSONs
   diffs/        @diffdeck/diffs         CodeView diff-rendering engine
   trees/        @diffdeck/trees         FileTree engine (vanilla render)
-apps/viewer/    @say8425/diffdeck — CLI + diff-server (data API) + browser viewer + agent skill
+apps/viewer/    @say8425/diffdeck — CLI + diff-server (data API) + browser viewer
+skills/         agent skill(SKILL.md)——构建时复制进包内
 scripts/        source-map extraction tool, css-inline Bun plugin, render-parity harness
+docs/           README 译文与截图
 ```
 
 依赖关系图：`path-store`（无依赖）← `trees`；`theming`（shiki）← `diffs`、`trees`。运行时外部依赖：shiki + `@shikijs/*`、`diff`、`hast-util-to-html`、`lru_map`。
@@ -177,7 +180,7 @@ bun run format      # oxfmt
 包含三条测试线：
 
 - `bun test` —— 单元/集成测试，速度快。`*.e2e.ts` 规格文件会被排除在收集范围之外，因此这一步永远不会启动浏览器。
-- `bun run test:coverage` —— 同一套测试，并对 **diffdeck 自有的运行时代码**（`apps/viewer/{browser,cli,server}`）施加 **100% 覆盖率门槛**。以下部分被有意排除在门槛之外：vendored 的 `packages/*`、浏览器入口 `main.ts`（属于集成入口——改为由 e2e 套件而非进程内测试来覆盖），以及 `build.ts`。
+- `bun run test:coverage` —— 同一套测试，并对 **diffdeck 自有的运行时代码**（`apps/viewer/{browser,cli,server}`）施加 **100% 覆盖率门槛**。以下部分被有意排除在门槛之外：vendored 的 `packages/*`、`scripts/` 下的工具、浏览器入口 `main.ts`（属于集成入口——改为由 e2e 套件而非进程内测试来覆盖）、`build.ts`，以及测试自身（`*.test.ts`、`e2e/**`）。
 - `bun run test:e2e` —— 基于 Playwright 的真实浏览器测试套件（`apps/viewer/e2e/`）。通过 `channel: "chrome"` 驱动系统自带的 Google Chrome（无需下载 Chromium），端到端覆盖 `main.ts` 及 vendored 的渲染路径。
 
 ### 渲染一致性验证工具

From 4a894a0f552b3fceefe1598f85aa35d8f1b8c442 Mon Sep 17 00:00:00 2001
From: Penguin <say8425@gmail.com>
Date: Wed, 5 Aug 2026 13:31:27 +0900
Subject: [PATCH 2/5] =?UTF-8?q?docs:=20=EA=B2=80=EC=A6=9D=EC=97=90?=
 =?UTF-8?q?=EC=84=9C=20=EB=93=9C=EB=9F=AC=EB=82=9C=20=EC=9E=90=EA=B8=B0=20?=
 =?UTF-8?q?=EC=98=A4=EB=A5=98=20=EB=8B=A4=EC=84=AF=EC=9D=84=20=EB=90=98?=
 =?UTF-8?q?=EB=8F=8C=EB=A6=B0=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

앞 커밋을 적대적으로 재검증한 결과다. 가장 나쁜 건 첫 번째 — 맞는 걸
틀리게 바꿔놨다.

- `diff.ts:220-221`을 221-222로 "고쳤"는데 원래가 맞았다. `resolve(repo)`가
  220, `resolve(root, path)`가 221이다. 되돌린다.
- `--fold-with-tree` 드리프트의 경로를 잘못 짚었다. #14은 루트 README와
  CLAUDE.md를 갱신했고 SKILL.md는 손대지 않았다 — SKILL.md는 파리티
  테스트를 만든 #24이 뒤늦게 채웠다. 사실관계가 오히려 논지를 강화한다:
  게이트가 감시하는 문서만 따라잡혔다.
- 배포 tarball을 "files 필드대로 셋뿐"이라 적었지만 `npm pack --dry-run`은
  9개다 — npm이 README.md와 package.json을 files와 무관하게 강제로 싣는다.
  같은 문서가 apps/viewer/README.md를 "npm 패키지 페이지"라 부르는 근거가
  바로 그 강제 포함이라, 앞 문장이 뒷 문장을 부정하고 있었다.
- WHAT 트리에 pr-check을 "5잡 게이트"라 적었는데, 같은 문서 아래쪽이
  required status checks가 비어 있다고 실측으로 말한다. 트리만 읽은
  사람은 정반대를 배운다.
- happy-dom preload 함정의 "21건"은 처음 밟았을 때 값이고 지금은 58건이다.
  개수는 스위트 크기의 함수라 상수로 박으면 안 된다 — bunfig.toml 주석도
  같이 고쳤다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G1vWAequwbToDppRceT6C1
---
 CLAUDE.md                                       | 10 +++++-----
 apps/viewer/__tests__/docs-flags-parity.test.ts |  5 +++--
 bunfig.toml                                     |  5 ++++-
 3 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 62e5c86..5ecf123 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,7 +21,7 @@ diffdeck/
 │   ├── extract-sources.test.ts  # 합성 소스맵 fixture로 hermetic (외부 체크아웃 의존 없음)
 │   ├── css-inline-plugin.ts     # *.css?inline import용 Bun 플러그인 (런타임/번들러 2분리)
 │   └── parity/                  # 포크 렌더 패리티 하니스 (fixture·preload·smoke test·main·build)
-├── .github/workflows/      # pr-check.yml (5잡 게이트) + release.yml (release-please → npm)
+├── .github/workflows/      # pr-check.yml (5잡 — 아직 required 아님, CI 항목 참고) + release.yml (release-please → npm)
 ├── .claude-plugin/ .codex-plugin/  # 플러그인 매니페스트 — release-please extra-files가 버전을 bump
 ├── CHANGELOG.md            # 레포 루트에 있다 (release-please changelog-path의 앞 슬래시 — CI 항목 참고)
 ├── bunfig.toml             # 테스트 preload + 커버리지 게이트/제외 (테스트 3레인 항목 참고)
@@ -77,7 +77,7 @@ bun run format
 - `bun run test:coverage` — 같은 스위트를 `--coverage`로 실행 + **diffdeck 소유 런타임 코드(`apps/viewer/{browser,cli,server}`) 100% 커버리지 게이트**(`bunfig.toml`의 `coverageThreshold`/`coveragePathIgnorePatterns`). 게이트 제외 대상: vendored `packages/*`, `scripts/**`, browser 엔트리 `main.ts`(in-process 유닛 테스트 대신 e2e로 커버), `build.ts`, 그리고 `*.test.ts`/`e2e/**` 자신.
 - `bun run test:e2e` — `apps/viewer/e2e/*.e2e.ts` Playwright 실브라우저 스위트. `playwright.config.ts`가 `channel:"chrome"`으로 시스템 Google Chrome을 구동(Chromium 별도 다운로드 없음), `globalSetup`이 `build.ts`를 1회 실행해 실제 `dist/cli.js`를 스폰. `main.ts`와 vendored 렌더 경로(fold·copy-path·find·flags-sync·image-diff 등)를 end-to-end로 커버. fixtures(`apps/viewer/e2e/fixtures/`: 임시 git repo 빌더 `repo.ts`, CLI 스폰 `launchViewer` `app.ts`, Node `child_process` 래퍼 `proc.ts`)는 **Node**로 동작 — Playwright Test는 항상 spec·fixture·globalSetup을 Node로 실행하므로(`bunx playwright test`로 띄워도) `Bun` 글로벌·`bun`의 `$` 셸을 못 쓰고 `spawn`으로 실제 `bun` 바이너리를 PATH에서 호출한다. `apps/viewer/e2e/tsconfig.json`이 루트 `typecheck` 스크립트에 배선되어 있다.
 - **`*.e2e.ts` 네이밍 규칙**: `bun test`는 `*.test.ts` 외에 `*.spec.ts`도 수집하므로, Playwright 스펙을 `*.e2e.ts`로 명명해 `bun test`가 절대 이를 실행하지 않도록 분리한다(Playwright 쪽은 `testMatch:"**/*.e2e.ts"`로 반대로 한정).
-- **`bunfig.toml`의 `preload`는 `scripts/parity/preload.ts` 하나뿐이고, happy-dom을 여기 넣으면 안 된다.** preload는 css-inline 플러그인을 등록해 포크 패키지의 `import styles from '../style.css?inline'`이 `bun test`에서 실제 스타일시트 텍스트로 풀리게 하는 용도다(빌드가 쓰는 것과 같은 플러그인). 반면 happy-dom 전역 등록(`packages/trees/src/__tests__/happydom.ts`)은 **의도적으로 preload에서 빠져 있다** — 전역 등록은 Node의 fetch/http를 테스트 런 **전체**에서 happy-dom 구현으로 갈아치우고, 그러면 실제 HTTP 서버를 띄우는 `apps/viewer` 테스트들이 무너진다(실측 21건 실패: diff-server·api/blob·built-serving). DOM이 필요한 테스트는 파일 맨 위에서 `import "../__tests__/happydom";`으로 **파일 단위로만** 켠다(`happydom-smoke.test.ts` 참고).
+- **`bunfig.toml`의 `preload`는 `scripts/parity/preload.ts` 하나뿐이고, happy-dom을 여기 넣으면 안 된다.** preload는 css-inline 플러그인을 등록해 포크 패키지의 `import styles from '../style.css?inline'`이 `bun test`에서 실제 스타일시트 텍스트로 풀리게 하는 용도다(빌드가 쓰는 것과 같은 플러그인). 반면 happy-dom 전역 등록(`packages/trees/src/__tests__/happydom.ts`)은 **의도적으로 preload에서 빠져 있다** — 전역 등록은 Node의 fetch/http를 테스트 런 **전체**에서 happy-dom 구현으로 갈아치우고, 그러면 실제 HTTP 서버를 띄우는 `apps/viewer` 테스트들이 무너진다(happy-dom의 `fetch`가 `NetworkError: Parse Error`로 죽는다 — diff-server·api/blob·built-serving 계열). **터지는 개수는 상수가 아니라 스위트 크기의 함수다**: bunfig 주석이 적은 21건은 이 함정을 처음 밟았을 때의 값이고, 2026-08-05에 다시 재현해보니 58건이었다. 숫자를 기준으로 삼지 말고 preload 목록 자체를 지켜라. DOM이 필요한 테스트는 파일 맨 위에서 `import "../__tests__/happydom";`으로 **파일 단위로만** 켠다(`happydom-smoke.test.ts` 참고).
 
 ### 기여 워크플로 (PR 필수)
 
@@ -97,7 +97,7 @@ bun run format
 - **사용자 게이트(부트스트랩, 자동화 불가)**: npm은 신규 패키지 최초 버전을 OIDC로 못 올린다(설정 UI가 패키지 존재를 요구, npm/cli #8544). 따라서 순서: ① `0.1.0`을 **로컬에서 토큰/`npm login`으로 1회 수동 publish**(패키지 생성) → ② npmjs.com 패키지 Settings에서 trusted publisher 등록(org `say8425`, repo `diffdeck`, workflow `release.yml`, environment 없음) → ③ 이후 release-please가 낸 릴리스 PR을 사람이 머지하면 CI가 tokenless로 publish. provenance엔 public repo 필요(✅).
 - **CI는 아직 "신호"이고 "게이트"가 아니다 — required status checks가 비어 있다.** `main` 룰셋에는 `deletion`·`non_fast_forward`만 있고(`gh api repos/say8425/diffdeck/branches/main/protection` → 404 Branch not protected), 어떤 체크도 required로 지정돼 있지 않다. 그래서 **빨간 CI로도 머지 버튼이 열린다**(실측: e2e가 `IN_PROGRESS`인데 `mergeStateStatus: CLEAN`). e2e를 포함해 다섯 잡 전부에 해당하는 기존 상태다. 진짜 게이트로 만들려면 룰셋에 `required_status_checks`로 `lint`·`typecheck`·`test`·`coverage`·`e2e`를 등록해야 한다 — 워크플로 파일만으로는 안 된다. (같은 종류의 "코드가 아니라 저장소 설정" 항목이라 바로 아래 항목과 나란히 둔다.)
 - **저장소 설정 요구사항**: Settings → Actions → General → Workflow permissions의 **"Allow GitHub Actions to create and approve pull requests"** 가 켜져 있어야 한다(기본 OFF). 꺼져 있으면 release-please가 버전 계산·브랜치·커밋까지 다 만들어놓고 **PR 생성 단계에서만** `GitHub Actions is not permitted to create or approve pull requests` 로 실패한다. API로는 `gh api -X PUT repos/say8425/diffdeck/actions/permissions/workflow -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true`.
-- **배포 산출물**: `build.ts`가 `dist/cli.js`에 `#!/usr/bin/env bun` 셰뱅 + 실행권한을 부여해 `bunx`뿐 아니라 `npx`/직접 실행에서도 bun으로 구동된다(`// @bun` 마커는 셰뱅 다음 줄에 유지). **`apps/viewer/package.json`에는 `dependencies`가 하나도 없다 — 의도된 상태다**: 배포되는 건 `files` 필드대로 `dist` + `LICENSE` + `NOTICE`뿐이라 사용자는 `bunx` 시점에 아무것도 resolve하지 않는다. 두 축이 다른 이유로 그렇다 — `dist/cli.js`(26KB)는 **애초에 외부 deps를 안 쓴다**(서버·CLI가 Bun `$`와 node 빌트인만 쓴다: 번들에 남은 import가 `fs`·`os`·`path`뿐), 반면 `dist/viewer/main.js`(10.9MB)와 `dist/viewer/worker.js`(836KB)는 shiki와 문법 전량을 **번들 안에 품는다**. 뒤집으면 **새 런타임 import를 추가할 때 `dependencies`에 적을 곳이 없다** — 번들에 실제로 들어갔는지 `bun run build` 후 산출물에서 확인해야 하고, external로 남은 것은 설치 시점에 그냥 없다. 산출물은 `dist/cli.js` + `dist/viewer/{main.js,worker.js,index.html}` + `dist/skills/diffdeck/SKILL.md` 다섯이다.
+- **배포 산출물**: `build.ts`가 `dist/cli.js`에 `#!/usr/bin/env bun` 셰뱅 + 실행권한을 부여해 `bunx`뿐 아니라 `npx`/직접 실행에서도 bun으로 구동된다(`// @bun` 마커는 셰뱅 다음 줄에 유지). **`apps/viewer/package.json`에는 `dependencies`가 하나도 없다 — 의도된 상태다**: tarball은 `files`에 적은 `dist`·`LICENSE`·`NOTICE`에 npm이 **`files`와 무관하게 항상 싣는** `README.md`·`package.json`을 더해 9개 파일이고(`npm pack --dry-run`으로 확인), 사용자는 `bunx` 시점에 아무것도 resolve하지 않는다. `apps/viewer/README.md`가 npm 패키지 페이지가 되는 것도 이 강제 포함 덕분이다 — `files`에 없다고 빼면 안 된다. 두 축이 다른 이유로 그렇다 — `dist/cli.js`(26KB)는 **애초에 외부 deps를 안 쓴다**(서버·CLI가 Bun `$`와 node 빌트인만 쓴다: 번들에 남은 import가 `fs`·`os`·`path`뿐), 반면 `dist/viewer/main.js`(10.9MB)와 `dist/viewer/worker.js`(836KB)는 shiki와 문법 전량을 **번들 안에 품는다**. 뒤집으면 **새 런타임 import를 추가할 때 `dependencies`에 적을 곳이 없다** — 번들에 실제로 들어갔는지 `bun run build` 후 산출물에서 확인해야 하고, external로 남은 것은 설치 시점에 그냥 없다. 산출물은 `dist/cli.js` + `dist/viewer/{main.js,worker.js,index.html}` + `dist/skills/diffdeck/SKILL.md` 다섯이다.
 
 ### 렌더 패리티 하니스
 
@@ -132,10 +132,10 @@ cd scripts/parity && python3 -m http.server 8099 # http://127.0.0.1:8099/index.h
 - **라이선스**: 각 `packages/*/LICENSE`(Apache-2.0) + `packages/trees/NOTICE.md`(headless-tree MIT 유래) + 최상위 `NOTICE` 보존. 파일 수정 사실 고지 유지.
 - **`*.css?inline` ambient 선언**: 소비자(앱)의 tsconfig가 패키지 `src/**`를 glob include하지 않으면 안 보임 — Plan 2 앱 tsconfig에서 배선 필요.
 - **cc-statusline 잔재 데드코드 제거됨**: `server/ensure.ts`(spawn-if-not-running 데몬 ensure)와 `server.ts`의 `idleTimeoutMs` idle-shutdown을 제거했고, 뒤늦게 `config.ts`의 `isDiffViewerDisabled`/`DIFFDECK_DISABLE`도 지웠다(diffdeck에선 **호출부가 한 번도 없었다** — 유일한 참조가 자기 테스트라 커버리지 100%가 그대로 유지돼 게이트로는 원리적으로 안 드러났다. 커버리지 초록은 "쓰인다"는 증거가 아니다). diffdeck의 CLI는 서버를 **foreground**로 띄워 Ctrl+C로 종료하는 모델이라(cc-statusline처럼 statusline이 백그라운드 데몬을 spawn-if-not-running으로 관리하는 구조가 아님) 이 기능들이 전부 미사용이었다. 참고로 `server.ts`의 `idleTimeout: 120`(Bun.serve 소켓 타임아웃)은 제거된 idle-shutdown과 **다른 것**이고 지금도 살아 있는 계약이다 — "Loading…" 항목의 45+45 예산이 이 값에 걸린다.
-- **CLI 플래그를 바꾸면 문서 일곱이 같은 커밋에서 함께 움직인다.** `apps/viewer/cli/args.ts`(파싱)와 `cli.ts`의 `HELP`(단일 진실)에 플래그를 추가·변경·삭제하면, 그 표면을 사람에게 되풀이해 말하는 문서가 전부 따라와야 한다: `skills/diffdeck/SKILL.md`, `README.md`(루트), `apps/viewer/README.md`(**npm 패키지 페이지** — 루트 README와 별개 파일이다), `docs/README.{ko,ja,zh,es}.md` 넷. SKILL.md가 특별한 이유는 따로 있다 — `install-skill`이 `~/.claude/skills/`에 배포하고(`--codex` 시 `~/.agents/skills/`에도) Claude Code 플러그인이 `skills/`를 자동 스캔하는, **에이전트가 diffdeck를 구동할 때 읽는 유일한 문서**라 드리프트하면 에이전트가 존재하는 옵션을 모른 채 구동한다. `apps/viewer/__tests__/docs-flags-parity.test.ts`가 `HELP`의 Options 블록과 **일곱 문서 전부**를 대조한다. **한 문서만 보는 게이트는 나머지를 지키지 않는다** — 예전엔 이 테스트가 SKILL.md만 봤고, 그 사이 `--fold-with-tree`가 npm README와 번역 4종에서 조용히 빠져 있었다(플래그를 만든 #14이 루트 README와 SKILL.md만 갱신했다). 문서를 새로 추가하면 그 테스트의 `DOCS` 배열에도 넣어야 같은 함정을 다시 파지 않는다.
+- **CLI 플래그를 바꾸면 문서 일곱이 같은 커밋에서 함께 움직인다.** `apps/viewer/cli/args.ts`(파싱)와 `cli.ts`의 `HELP`(단일 진실)에 플래그를 추가·변경·삭제하면, 그 표면을 사람에게 되풀이해 말하는 문서가 전부 따라와야 한다: `skills/diffdeck/SKILL.md`, `README.md`(루트), `apps/viewer/README.md`(**npm 패키지 페이지** — 루트 README와 별개 파일이다), `docs/README.{ko,ja,zh,es}.md` 넷. SKILL.md가 특별한 이유는 따로 있다 — `install-skill`이 `~/.claude/skills/`에 배포하고(`--codex` 시 `~/.agents/skills/`에도) Claude Code 플러그인이 `skills/`를 자동 스캔하는, **에이전트가 diffdeck를 구동할 때 읽는 유일한 문서**라 드리프트하면 에이전트가 존재하는 옵션을 모른 채 구동한다. `apps/viewer/__tests__/docs-flags-parity.test.ts`가 `HELP`의 Options 블록과 **일곱 문서 전부**를 대조한다. **한 문서만 보는 게이트는 나머지를 지키지 않는다** — 예전엔 이 테스트가 SKILL.md만 봤고, 그 사이 `--fold-with-tree`가 npm README와 번역 4종에서 조용히 빠져 있었다. 경로가 그걸 잘 보여준다: 플래그를 만든 #14은 루트 README와 CLAUDE.md만 갱신했고, SKILL.md는 뒤늦게 #24(파리티 테스트를 만든 그 커밋)이 채웠다 — 즉 **게이트가 감시하는 문서만 따라잡혔고 나머지 다섯은 그대로 남았다.** 문서를 새로 추가하면 그 테스트의 `DOCS` 배열에도 넣어야 같은 함정을 다시 파지 않는다.
 - **`hidden`으로 숨기는 노드에 author `display`를 선언하면 `[hidden]{display:none}`을 반드시 짝지어라.** author origin이 UA 규칙을 이겨 영구 노출된다. `#grab-popover[hidden]`이 `display:flex` 뒤에 명시된 이유이고, 과거 `.grab-hint`에서 두 번째로 밟았다(지금은 `.grab-hint`가 sr-only라 `hidden`을 토글하지 않아 이 함정에서 벗어났다 — 규칙 자체는 `#grab-popover`에 그대로 유효하다). **happy-dom은 `textContent`만 보므로 유닛이 못 잡고 실브라우저에서만 드러난다** — 이런 실패는 e2e에서만 잡힌다.
 - 워커 로드 실패 폴백은 엔진이 아니라 앱 워치독이 담당한다(회귀망: worker-highlight.e2e.ts의 폴백 테스트).
-- **프로세스 cwd가 삭제되면 diffdeck 전체가 죽는다 — 그래서 `cli.ts`가 기동 직후 `/`로 이탈한다.** cwd가 unlink된 프로세스는 **자식 프로세스를 하나도 생성할 수 없다**(자식이 상속할 cwd를 커널이 해석하지 못한다). 이건 Bun Shell의 동작이 아니라 OS 제약이라 `.cwd(repo)`를 명시해도, 셸을 안 거치는 `Bun.spawn`을 써도 `ENOENT: posix_spawn`으로 똑같이 죽는다(실측) — **호출부에서 고칠 수 있는 방법이 없다.** 증상은 `/api/diff`가 **repo와 무관하게** 400 `not a git repository`를 내는 것이고, `/api/ping`(204)과 정적 페이지(200)는 서브프로세스를 안 띄워서 멀쩡하므로 "서버는 살아있는데 diff만 안 된다"로 오진하기 쉽다. 감별: 403이면 토큰/포트 문제고, 400이면서 repo를 바꿔도 동일하면 이 문제다. 장수 데몬(cc-statusline이 띄운다 — `/api/ping`의 pid 헤더 주석 참고)이 기동 시점의 worktree를 물고 있다가 그 worktree가 삭제되면 발생한다. 예방은 `cli.ts`가 `repo`를 읽은 **직후** `toSafeCwd()`로 이탈하는 것이고(순서가 계약이다 — 먼저 이탈하면 `repo`가 `/`가 된다), 자가회복은 `server.ts` 핸들러 진입부가 `repairCwd`가 주입된 경우에만(단축평가 — 없으면 `isCwdAlive` 호출 자체를 건너뛴다, `repairCwd`를 안 넘긴 임베드 호스트에게 감지 자체가 순수 비용이 되면 안 되기 때문이다) `isCwdAlive`로 감지해 그 `repairCwd`를 부르는 것이다. **감지는 반드시 `existsSync(process.cwd())`여야 한다** — `existsSync(".")`·`statSync(".")`는 unlink된 inode를 살려두는 cwd 파일 디스크립터 때문에 항상 true라 원리적으로 못 잡는다. `process.chdir()`이 프로세스 전역 부작용이라 라이브러리인 `startDiffServer`는 감지만 하고 복구는 프로세스를 소유한 `cli.ts`에서 주입받는다. (`cli.ts`는 서버를 띄운 직후 `prewarmDiff`(`server/prewarm.ts`)로 자기 서버의 `/api/diff`를 `working`·`base` **순차로** 두 번 호출해 payload 캐시를 데운다 — 브라우저가 뜨는 동안 첫 diff 빌드를 선실행시키는 best-effort 경로다. 동시 호출이 아닌 이유는 `BUILD_CONCURRENCY=8`이 호출당이라 두 모드를 겹치면 기동 직후 git 서브프로세스 버스트가 배로 뛰기 때문이고, 이는 아래 "Loading…" 항목의 재시도 1회 제한과 같은 근거다. 실패해도 뷰어는 정상 동작한다.) 회귀망: `daemon-cwd.e2e.ts`가 사용자에게 보이는 계약(기동 디렉토리가 삭제된 데몬이 다른 repo를 계속 서빙한다)을 종단 검증하는데, **예방과 자가회복을 구분하지는 못한다** — 둘 중 하나만 살아 있어도 통과하고 둘 다 없어야 400으로 빨간불이 된다(실측). 가드가 라우트 분기보다 먼저 돌아 첫 요청에서 git 호출 전에 cwd를 되살리기 때문이다. 기제별 격리는 유닛이 맡는다: `cli-run.test.ts`(예방 — 호출 순서와 주입), `diff-server.test.ts`(자가회복 4종 — 커버리지가 branch를 안 세므로 호출/미호출을 각각 찌르고, 나머지 둘은 단축평가로 감지가 건너뛰는 경로와 `cwdDeps` 생략 시 REAL_CWD_DEPS가 실제로 쓰이는 경로의 함수 커버리지를 찌른다), `diff-cwd.test.ts`(판정). 이후 git 호출 17곳 중 16곳은 `git -C ${repo}`로 repo를 조준하지만, 17번째인 `prBaseName`(`diff.ts:29-30`)은 `gh pr view`라 `-C`가 없고 `.cwd(repo)`로만 조준한다 — "전부 `-C`"로 읽으면 코드를 잘못 스캔하게 되지만, 결론(모두 repo를 명시적으로 조준하므로 cwd가 `/`여도 정상)은 그대로다. cwd 의존 지점이 하나 더 있다: `server.ts`의 `resolve(cfg.viewerDir)`는 chdir **이후**에 돌아 상대경로였다면 `/` 기준으로 풀리는데, 프로덕션 값(`${import.meta.dir}/viewer`)과 테스트(mkdtemp 절대경로)가 둘 다 절대경로라 현재 깨지는 건 없다. `/api/blob`의 경로 탈출 가드는 안전하다 — `getFileBytes`(`diff.ts:221-222`)가 `resolve(repo)`/`resolve(root, path)`로 가드를 세우고 실제 읽기는 `readFileSync(join(repo, path))`라 OS가 syscall 시점에 같은 cwd로 풀어 가드 기준과 읽기 기준이 함께 움직이므로 탈출 구멍이 열리지 않는다 — cwd가 조용히 바뀌며 보안 버그가 될 뻔했던 유일한 지점이라 기록해 둘 가치가 있다.
+- **프로세스 cwd가 삭제되면 diffdeck 전체가 죽는다 — 그래서 `cli.ts`가 기동 직후 `/`로 이탈한다.** cwd가 unlink된 프로세스는 **자식 프로세스를 하나도 생성할 수 없다**(자식이 상속할 cwd를 커널이 해석하지 못한다). 이건 Bun Shell의 동작이 아니라 OS 제약이라 `.cwd(repo)`를 명시해도, 셸을 안 거치는 `Bun.spawn`을 써도 `ENOENT: posix_spawn`으로 똑같이 죽는다(실측) — **호출부에서 고칠 수 있는 방법이 없다.** 증상은 `/api/diff`가 **repo와 무관하게** 400 `not a git repository`를 내는 것이고, `/api/ping`(204)과 정적 페이지(200)는 서브프로세스를 안 띄워서 멀쩡하므로 "서버는 살아있는데 diff만 안 된다"로 오진하기 쉽다. 감별: 403이면 토큰/포트 문제고, 400이면서 repo를 바꿔도 동일하면 이 문제다. 장수 데몬(cc-statusline이 띄운다 — `/api/ping`의 pid 헤더 주석 참고)이 기동 시점의 worktree를 물고 있다가 그 worktree가 삭제되면 발생한다. 예방은 `cli.ts`가 `repo`를 읽은 **직후** `toSafeCwd()`로 이탈하는 것이고(순서가 계약이다 — 먼저 이탈하면 `repo`가 `/`가 된다), 자가회복은 `server.ts` 핸들러 진입부가 `repairCwd`가 주입된 경우에만(단축평가 — 없으면 `isCwdAlive` 호출 자체를 건너뛴다, `repairCwd`를 안 넘긴 임베드 호스트에게 감지 자체가 순수 비용이 되면 안 되기 때문이다) `isCwdAlive`로 감지해 그 `repairCwd`를 부르는 것이다. **감지는 반드시 `existsSync(process.cwd())`여야 한다** — `existsSync(".")`·`statSync(".")`는 unlink된 inode를 살려두는 cwd 파일 디스크립터 때문에 항상 true라 원리적으로 못 잡는다. `process.chdir()`이 프로세스 전역 부작용이라 라이브러리인 `startDiffServer`는 감지만 하고 복구는 프로세스를 소유한 `cli.ts`에서 주입받는다. (`cli.ts`는 서버를 띄운 직후 `prewarmDiff`(`server/prewarm.ts`)로 자기 서버의 `/api/diff`를 `working`·`base` **순차로** 두 번 호출해 payload 캐시를 데운다 — 브라우저가 뜨는 동안 첫 diff 빌드를 선실행시키는 best-effort 경로다. 동시 호출이 아닌 이유는 `BUILD_CONCURRENCY=8`이 호출당이라 두 모드를 겹치면 기동 직후 git 서브프로세스 버스트가 배로 뛰기 때문이고, 이는 아래 "Loading…" 항목의 재시도 1회 제한과 같은 근거다. 실패해도 뷰어는 정상 동작한다.) 회귀망: `daemon-cwd.e2e.ts`가 사용자에게 보이는 계약(기동 디렉토리가 삭제된 데몬이 다른 repo를 계속 서빙한다)을 종단 검증하는데, **예방과 자가회복을 구분하지는 못한다** — 둘 중 하나만 살아 있어도 통과하고 둘 다 없어야 400으로 빨간불이 된다(실측). 가드가 라우트 분기보다 먼저 돌아 첫 요청에서 git 호출 전에 cwd를 되살리기 때문이다. 기제별 격리는 유닛이 맡는다: `cli-run.test.ts`(예방 — 호출 순서와 주입), `diff-server.test.ts`(자가회복 4종 — 커버리지가 branch를 안 세므로 호출/미호출을 각각 찌르고, 나머지 둘은 단축평가로 감지가 건너뛰는 경로와 `cwdDeps` 생략 시 REAL_CWD_DEPS가 실제로 쓰이는 경로의 함수 커버리지를 찌른다), `diff-cwd.test.ts`(판정). 이후 git 호출 17곳 중 16곳은 `git -C ${repo}`로 repo를 조준하지만, 17번째인 `prBaseName`(`diff.ts:29-30`)은 `gh pr view`라 `-C`가 없고 `.cwd(repo)`로만 조준한다 — "전부 `-C`"로 읽으면 코드를 잘못 스캔하게 되지만, 결론(모두 repo를 명시적으로 조준하므로 cwd가 `/`여도 정상)은 그대로다. cwd 의존 지점이 하나 더 있다: `server.ts`의 `resolve(cfg.viewerDir)`는 chdir **이후**에 돌아 상대경로였다면 `/` 기준으로 풀리는데, 프로덕션 값(`${import.meta.dir}/viewer`)과 테스트(mkdtemp 절대경로)가 둘 다 절대경로라 현재 깨지는 건 없다. `/api/blob`의 경로 탈출 가드는 안전하다 — `getFileBytes`(`diff.ts:220-221`)가 `resolve(repo)`/`resolve(root, path)`로 가드를 세우고 실제 읽기는 `readFileSync(join(repo, path))`라 OS가 syscall 시점에 같은 cwd로 풀어 가드 기준과 읽기 기준이 함께 움직이므로 탈출 구멍이 열리지 않는다 — cwd가 조용히 바뀌며 보안 버그가 될 뻔했던 유일한 지점이라 기록해 둘 가치가 있다.
 
 ### 로드맵 (각각 별도 sub-plan)
 
diff --git a/apps/viewer/__tests__/docs-flags-parity.test.ts b/apps/viewer/__tests__/docs-flags-parity.test.ts
index 30b82e0..41a6c4b 100644
--- a/apps/viewer/__tests__/docs-flags-parity.test.ts
+++ b/apps/viewer/__tests__/docs-flags-parity.test.ts
@@ -8,8 +8,9 @@ const repoRoot = join(import.meta.dir, "..", "..", "..");
 // cli.ts의 HELP가 CLI 표면의 단일 진실이고, 아래 문서들은 전부 그 표면을
 // 사람에게 되풀이해 말한다. 예전엔 SKILL.md 하나만 대조했는데, 그 사이
 // `--fold-with-tree`가 npm README(apps/viewer/README.md)와 번역 4종에서
-// 조용히 빠져 있었다 — 플래그가 생긴 #14이 루트 README와 SKILL.md만
-// 갱신했기 때문이다. 게이트가 한 문서만 보면 나머지는 아무도 지키지 않는다.
+// 조용히 빠져 있었다 — 플래그를 만든 #14은 루트 README와 CLAUDE.md만
+// 갱신했고, SKILL.md는 이 테스트를 만든 #24이 뒤늦게 채웠기 때문이다.
+// 게이트가 감시하는 문서만 따라잡힌다. 그래서 목록을 전부로 넓혔다.
 const DOCS = [
 	"skills/diffdeck/SKILL.md",
 	"README.md",
diff --git a/bunfig.toml b/bunfig.toml
index 4044705..9a1f23c 100644
--- a/bunfig.toml
+++ b/bunfig.toml
@@ -8,7 +8,10 @@ root = "."
 # is intentionally NOT preloaded here. Registering happy-dom globally replaces
 # Node's fetch/http with happy-dom's implementations for the *entire* test run,
 # which broke apps/viewer's real HTTP server tests (diff-server, api/blob,
-# built-serving — 21 failures). Trees view/DOM tests must instead
+# built-serving) with `NetworkError: ... Parse Error` out of happy-dom's fetch.
+# The blast radius scales with the suite: 21 failures when first hit, 58 when
+# re-measured on 2026-08-05 — don't treat the count as a constant, just keep
+# happy-dom out of this list. Trees view/DOM tests must instead
 # `import "../__tests__/happydom";` at the top of each file that needs a DOM
 # (see happydom-smoke.test.ts).
 preload = ["./scripts/parity/preload.ts"]

From 9ac43ec84bbd54209ca41205cad7a337215e8b51 Mon Sep 17 00:00:00 2001
From: Penguin <say8425@gmail.com>
Date: Wed, 5 Aug 2026 13:42:38 +0900
Subject: [PATCH 3/5] =?UTF-8?q?docs:=20=EB=B2=88=EC=97=AD=20=EB=A6=AC?=
 =?UTF-8?q?=EB=B7=B0=20=EC=A7=80=EC=A0=81=EC=9D=84=20=EB=B0=98=EC=98=81?=
 =?UTF-8?q?=ED=95=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

원어민 관점 리뷰에서 나온 것들이다. 대부분 앞 커밋이 새로 만든 흠이다.

- 아키텍처 코드블록은 ko·ja·zh에서 원래 100% 영어인데 내가 현지어 두 줄을
  끼워 넣어 관례를 깼다. 영어로 되돌린다. es는 반대로 블록 전체가
  스페인어이므로 그대로 두되, `el agent skill … copiado`의 성·용어가 같은
  파일 106행의 `la skill de agente`와 어긋나 `la … copiada`로 고친다.
- 29.5k를 백틱 친 `CodeView`에 붙여 놓아, grep하면 3,563줄이 나오는 파일과
  8배 어긋났다. 다섯 README 전부에서 `packages/diffs`임을 밝힌다.
- ko 표가 네 행에서 "파일 트리"라 부르는 위젯을 새 행만 "사이드바"라 불렀다.
  용어를 맞추고, 동작도 단방향(트리를 접으면 diff가 따라 접힌다)으로 적는다.
- zh `将…同步`는 기동 시 1회 동작으로 읽힌다. 지속 모드이므로 `保持同步`.
- 무생물에 붙은 재귀대명사를 고친다: ko `스펙 자신` → `스펙 파일 자체`,
  zh `测试自身` → `测试文件本身`.
- es는 열거 마지막 `y` 앞의 쉼표를 뺀다(RAE). 소수점도 스페인어 관례상
  마침표가 아니라서 `~29.5k` → `~29 500`.
- es `--fold-with-tree` 설명이 "folds"를 흘려 "diff와 동기화"로 읽혔다.
  `el plegado del diff`로 무엇과 동기화되는지 밝힌다.

덤으로, npm README만 `XDG_CACHE_HOME`을 적고 나머지 다섯은 `~/.cache`만
말하고 있었다 — 이 PR이 고치는 것과 같은 종류의 드리프트라 함께 맞춘다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G1vWAequwbToDppRceT6C1
---
 README.md         |  4 ++--
 docs/README.es.md | 10 +++++-----
 docs/README.ja.md |  8 ++++----
 docs/README.ko.md | 12 ++++++------
 docs/README.zh.md | 12 ++++++------
 5 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index a965736..1b6e69f 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ A local diff viewer, built on a vendored fork of Pierre's [`@pierre/diffs`](http
 
 diffdeck is the local diff viewer originally embedded in [cc-statusline](https://github.com/say8425/cc-statusline), extracted into its own product. Instead of depending on the upstream Pierre packages — which move fast (`@pierre/diffs` churns heavily; `@pierre/trees` is pre-1.0 beta) and whose internal markup we had already coupled to heavily — diffdeck **recovers the original TypeScript from the packages' source maps and vendors it**, so we own the rendering engine outright.
 
-The result is a Bun-workspace monorepo where a commodity-hard, framework-agnostic diff engine (Pierre's `CodeView`, ~29.5k lines) is kept as-is, while the parts we customize live in our own code.
+The result is a Bun-workspace monorepo where a commodity-hard, framework-agnostic diff engine (Pierre's `CodeView`, the ~29.5k lines of `packages/diffs`) is kept as-is, while the parts we customize live in our own code.
 
 ## Features
 
@@ -102,7 +102,7 @@ These view flags set the initial state for this launch only — they don't chang
 your saved preferences, and the in-app toggles reflect the launched state.
 
 Environment: `DIFFDECK_PORT` sets the default port. The token is cached under
-`~/.cache/diffdeck/`.
+`$XDG_CACHE_HOME/diffdeck/`, or `~/.cache/diffdeck/` when that is unset.
 
 ## Skills
 
diff --git a/docs/README.es.md b/docs/README.es.md
index 3ed94fa..7610d7d 100644
--- a/docs/README.es.md
+++ b/docs/README.es.md
@@ -15,7 +15,7 @@ Un visor de diff local, construido sobre un fork vendorizado de los paquetes de
 
 diffdeck es el visor de diff local que originalmente estaba embebido en [cc-statusline](https://github.com/say8425/cc-statusline), ahora extraído como un producto propio. En lugar de depender de los paquetes originales de Pierre — que evolucionan rápido (`@pierre/diffs` cambia mucho; `@pierre/trees` está en beta pre-1.0) y cuyo markup interno ya estaba fuertemente acoplado a nuestro código —, diffdeck **recupera el TypeScript original a partir de los source maps de los paquetes y lo vendoriza**, de modo que somos dueños por completo del motor de renderizado.
 
-El resultado es un monorepo de workspaces de Bun donde un motor de diff sólido y agnóstico de framework (el `CodeView` de Pierre, ~29.5k líneas) se mantiene tal cual, mientras que las partes que personalizamos viven en nuestro propio código.
+El resultado es un monorepo de workspaces de Bun donde un motor de diff sólido y agnóstico de framework (el `CodeView` de Pierre — las ~29 500 líneas de `packages/diffs`) se mantiene tal cual, mientras que las partes que personalizamos viven en nuestro propio código.
 
 ## Características
 
@@ -93,13 +93,13 @@ Opciones:
 | `--tree-right`     | Iniciar con el árbol de archivos a la derecha                                     |
 | `--split`          | Iniciar en vista split (unified es el valor predeterminado)                       |
 | `--hide-tree`      | Iniciar con el árbol de archivos oculto                                            |
-| `--fold-with-tree` | Iniciar con el plegado de directorios de la barra lateral sincronizado con el diff |
+| `--fold-with-tree` | Iniciar con el plegado de directorios de la barra lateral sincronizado con el plegado del diff |
 | `-h`, `--help`     | Mostrar ayuda                                                                      |
 | `-v`, `--version`  | Mostrar versión                                                                    |
 
 Estos flags de vista establecen el estado inicial solo para este lanzamiento — no cambian tus preferencias guardadas, y los toggles dentro de la app reflejan el estado con el que se lanzó.
 
-Entorno: `DIFFDECK_PORT` establece el puerto predeterminado. El token se guarda en caché bajo `~/.cache/diffdeck/`.
+Entorno: `DIFFDECK_PORT` establece el puerto predeterminado. El token se guarda en caché bajo `$XDG_CACHE_HOME/diffdeck/`, o `~/.cache/diffdeck/` si esa variable no está definida.
 
 ## Skills
 
@@ -156,7 +156,7 @@ packages/
   diffs/        @diffdeck/diffs         motor de renderizado de diffs CodeView
   trees/        @diffdeck/trees         motor FileTree (render vanilla)
 apps/viewer/    @say8425/diffdeck — CLI + diff-server (API de datos) + visor de navegador
-skills/         el agent skill (SKILL.md), copiado al paquete durante el build
+skills/         la skill de agente (SKILL.md), copiada al paquete durante el build
 scripts/        herramienta de extracción de source maps, plugin de Bun css-inline, arnés de paridad de renderizado
 docs/           traducciones del README y capturas de pantalla
 ```
@@ -180,7 +180,7 @@ bun run format      # oxfmt
 Tres carriles:
 
 - `bun test` — tests unitarios/de integración, rápidos. Las specs `*.e2e.ts` quedan excluidas de la recolección, así que esto nunca lanza un navegador.
-- `bun run test:coverage` — la misma suite con una **puerta de cobertura del 100% sobre el código de runtime propio de diffdeck** (`apps/viewer/{browser,cli,server}`). Intencionalmente fuera de la puerta: los `packages/*` vendorizados, las herramientas bajo `scripts/`, el punto de entrada del navegador `main.ts` (entry de integración — ejercitado por la suite e2e en su lugar, no in-process), `build.ts`, y las propias specs (`*.test.ts`, `e2e/**`).
+- `bun run test:coverage` — la misma suite con una **puerta de cobertura del 100% sobre el código de runtime propio de diffdeck** (`apps/viewer/{browser,cli,server}`). Intencionalmente fuera de la puerta: los `packages/*` vendorizados, las herramientas bajo `scripts/`, el punto de entrada del navegador `main.ts` (entry de integración — ejercitado por la suite e2e en su lugar, no in-process), `build.ts` y las propias specs (`*.test.ts`, `e2e/**`).
 - `bun run test:e2e` — la suite de Playwright con navegador real (`apps/viewer/e2e/`). Conduce el Google Chrome del sistema vía `channel: "chrome"` (sin descarga de Chromium) y cubre `main.ts` y las rutas de render vendorizadas de extremo a extremo.
 
 ### Arnés de paridad de renderizado
diff --git a/docs/README.ja.md b/docs/README.ja.md
index af305ad..8f149ab 100644
--- a/docs/README.ja.md
+++ b/docs/README.ja.md
@@ -15,7 +15,7 @@ Pierre の [`@pierre/diffs`](https://www.npmjs.com/package/@pierre/diffs) と [`
 
 diffdeck は、もともと [cc-statusline](https://github.com/say8425/cc-statusline) に組み込まれていたローカル diff ビューアを、独立した製品として切り出したものです。アップストリームの Pierre パッケージ — 変化が激しく(`@pierre/diffs` は頻繁に破壊的変更が入り、`@pierre/trees` はまだ 1.0 未満のベータ版)、しかも内部マークアップにすでに深く依存していた — にそのまま依存し続ける代わりに、diffdeck は **パッケージのソースマップから元の TypeScript を復元してベンダリングし**、レンダリングエンジンを完全に自前で保有しています。
 
-その結果、改変が難しい、フレームワークに依存しない diff エンジン(Pierre の `CodeView`、約 29,500 行)はそのまま維持しつつ、カスタマイズする部分だけを自前のコードに置く、という構成の Bun ワークスペースのモノレポになっています。
+その結果、改変が難しい、フレームワークに依存しない diff エンジン(Pierre の `CodeView` — `packages/diffs` の約 29,500 行)はそのまま維持しつつ、カスタマイズする部分だけを自前のコードに置く、という構成の Bun ワークスペースのモノレポになっています。
 
 ## 機能
 
@@ -99,7 +99,7 @@ bunx @say8425/diffdeck        # or `diffdeck` if installed globally
 
 これらの表示フラグは、この起動時のみの初期状態を設定するものです — 保存済みの設定を変更するわけではなく、アプリ内のトグルは起動時の状態をそのまま反映します。
 
-環境変数: `DIFFDECK_PORT` でデフォルトポートを設定できます。トークンは `~/.cache/diffdeck/` にキャッシュされます。
+環境変数: `DIFFDECK_PORT` でデフォルトポートを設定できます。トークンは `$XDG_CACHE_HOME/diffdeck/` に、未設定なら `~/.cache/diffdeck/` にキャッシュされます。
 
 ## スキル
 
@@ -156,9 +156,9 @@ packages/
   diffs/        @diffdeck/diffs         CodeView diff-rendering engine
   trees/        @diffdeck/trees         FileTree engine (vanilla render)
 apps/viewer/    @say8425/diffdeck — CLI + diff-server (data API) + browser viewer
-skills/         エージェントスキル(SKILL.md) — ビルド時にパッケージへコピーされる
+skills/         the agent skill (SKILL.md), copied into the package at build time
 scripts/        source-map extraction tool, css-inline Bun plugin, render-parity harness
-docs/           README の翻訳とスクリーンショット
+docs/           README translations and screenshots
 ```
 
 依存関係グラフ: `path-store`(依存なし)← `trees`、`theming`(shiki)← `diffs`, `trees`。ランタイムの外部依存: shiki + `@shikijs/*`、`diff`、`hast-util-to-html`、`lru_map`。
diff --git a/docs/README.ko.md b/docs/README.ko.md
index 4d59f42..4c04042 100644
--- a/docs/README.ko.md
+++ b/docs/README.ko.md
@@ -15,7 +15,7 @@ Pierre의 [`@pierre/diffs`](https://www.npmjs.com/package/@pierre/diffs)와 [`@p
 
 diffdeck는 원래 [cc-statusline](https://github.com/say8425/cc-statusline)에 내장되어 있던 로컬 diff 뷰어를 별도 제품으로 분리한 것입니다. 빠르게 변화하는(`@pierre/diffs`는 변경이 잦고, `@pierre/trees`는 아직 1.0 이전 베타 단계입니다) 업스트림 Pierre 패키지에 의존하는 대신 — 게다가 내부 마크업에 이미 깊이 결합되어 있었기 때문에 — diffdeck는 **패키지의 소스맵에서 원본 TypeScript를 복원해 vendoring**해서, 렌더링 엔진을 완전히 직접 소유합니다.
 
-그 결과 구현하기 어려운, 프레임워크에 종속되지 않는 diff 엔진(Pierre의 `CodeView`, 약 29,500줄)은 그대로 유지하고, 우리가 커스터마이즈하는 부분만 자체 코드에 두는 Bun 워크스페이스 모노레포 구조가 되었습니다.
+그 결과 구현하기 어려운, 프레임워크에 종속되지 않는 diff 엔진(Pierre의 `CodeView` — `packages/diffs` 약 29,500줄)은 그대로 유지하고, 우리가 커스터마이즈하는 부분만 자체 코드에 두는 Bun 워크스페이스 모노레포 구조가 되었습니다.
 
 ## 기능
 
@@ -93,13 +93,13 @@ bunx @say8425/diffdeck        # or `diffdeck` if installed globally
 | `--tree-right`      | 파일 트리를 오른쪽에 둔 상태로 시작                                 |
 | `--split`           | split 뷰로 시작(unified가 기본값)                                  |
 | `--hide-tree`       | 파일 트리를 숨긴 상태로 시작                                       |
-| `--fold-with-tree`  | 사이드바 디렉토리 접기를 diff 접기와 동기화한 상태로 시작           |
+| `--fold-with-tree`  | 파일 트리에서 디렉토리를 접으면 diff도 함께 접히는 상태로 시작       |
 | `-h`, `--help`      | 도움말 표시                                                        |
 | `-v`, `--version`   | 버전 표시                                                          |
 
 이 뷰 플래그들은 이번 실행에서만 초기 상태를 설정합니다 — 저장된 설정을 바꾸지 않으며, 인앱 토글은 실행된 상태를 그대로 반영합니다.
 
-환경 변수: `DIFFDECK_PORT`로 기본 포트를 설정합니다. 토큰은 `~/.cache/diffdeck/`에 캐시됩니다.
+환경 변수: `DIFFDECK_PORT`로 기본 포트를 설정합니다. 토큰은 `$XDG_CACHE_HOME/diffdeck/`에, 그 값이 없으면 `~/.cache/diffdeck/`에 캐시됩니다.
 
 ## 스킬
 
@@ -156,9 +156,9 @@ packages/
   diffs/        @diffdeck/diffs         CodeView diff-rendering engine
   trees/        @diffdeck/trees         FileTree engine (vanilla render)
 apps/viewer/    @say8425/diffdeck — CLI + diff-server (data API) + browser viewer
-skills/         agent skill(SKILL.md) — 빌드 시 패키지로 복사됨
+skills/         the agent skill (SKILL.md), copied into the package at build time
 scripts/        source-map extraction tool, css-inline Bun plugin, render-parity harness
-docs/           README 번역본과 스크린샷
+docs/           README translations and screenshots
 ```
 
 의존성 그래프: `path-store`(의존성 없음) ← `trees`; `theming`(shiki) ← `diffs`, `trees`. 런타임 외부 의존성: shiki + `@shikijs/*`, `diff`, `hast-util-to-html`, `lru_map`.
@@ -180,7 +180,7 @@ bun run format      # oxfmt
 세 가지 레인으로 구성됩니다:
 
 - `bun test` — 단위/통합 테스트, 빠릅니다. `*.e2e.ts` 스펙은 수집 대상에서 제외되므로 브라우저를 절대 띄우지 않습니다.
-- `bun run test:coverage` — 동일한 스위트를 실행하되 **diffdeck가 직접 소유한 런타임 코드**(`apps/viewer/{browser,cli,server}`)에 대해 **100% 커버리지 게이트**를 적용합니다. 게이트에서 의도적으로 제외된 것: vendoring된 `packages/*`, `scripts/` 아래의 도구, 브라우저 엔트리 `main.ts`(통합 엔트리 — in-process가 아니라 e2e 스위트로 검증됨), `build.ts`, 그리고 스펙 자신(`*.test.ts`, `e2e/**`).
+- `bun run test:coverage` — 동일한 스위트를 실행하되 **diffdeck가 직접 소유한 런타임 코드**(`apps/viewer/{browser,cli,server}`)에 대해 **100% 커버리지 게이트**를 적용합니다. 게이트에서 의도적으로 제외된 것: vendoring된 `packages/*`, `scripts/` 아래의 도구, 브라우저 엔트리 `main.ts`(통합 엔트리 — in-process가 아니라 e2e 스위트로 검증됨), `build.ts`, 스펙 파일 자체(`*.test.ts`, `e2e/**`).
 - `bun run test:e2e` — Playwright 실제 브라우저 스위트(`apps/viewer/e2e/`)입니다. `channel: "chrome"`로 시스템에 설치된 Google Chrome을 구동하며(Chromium 다운로드 없음), `main.ts`와 vendoring된 렌더링 경로를 엔드투엔드로 커버합니다.
 
 ### 렌더 패리티 하네스
diff --git a/docs/README.zh.md b/docs/README.zh.md
index 7e322d8..d2b1cee 100644
--- a/docs/README.zh.md
+++ b/docs/README.zh.md
@@ -15,7 +15,7 @@
 
 diffdeck 最初是内置在 [cc-statusline](https://github.com/say8425/cc-statusline) 中的本地 diff 查看器，现已被拆分为独立产品。相比继续依赖上游的 Pierre 包——它们迭代很快（`@pierre/diffs` 变动频繁；`@pierre/trees` 仍处于 1.0 之前的 beta 阶段），而我们又已经深度耦合了它们的内部标记结构——diffdeck **从这些包的 source map 中还原出原始 TypeScript 并将其 vendor（内置）进来**，从而完全掌握渲染引擎的所有权。
 
-最终形成了一个 Bun workspace monorepo：与框架无关、已高度成熟稳定的 diff 引擎（Pierre 的 `CodeView`，约 29.5k 行代码）保持原样，而我们自定义的部分则保存在自己的代码中。
+最终形成了一个 Bun workspace monorepo：与框架无关、已高度成熟稳定的 diff 引擎（Pierre 的 `CodeView`，即 `packages/diffs` 的约 29.5k 行代码）保持原样，而我们自定义的部分则保存在自己的代码中。
 
 ## 功能
 
@@ -93,13 +93,13 @@ bunx @say8425/diffdeck        # or `diffdeck` if installed globally
 | `--tree-right`      | 启动时文件树显示在右侧                                      |
 | `--split`           | 以 split 视图启动（默认是 unified）                          |
 | `--hide-tree`       | 启动时隐藏文件树                                            |
-| `--fold-with-tree`  | 启动时将侧边栏目录折叠与 diff 折叠同步                       |
+| `--fold-with-tree`  | 启动时让侧边栏目录折叠与 diff 折叠保持同步                   |
 | `-h`, `--help`      | 显示帮助                                                    |
 | `-v`, `--version`   | 显示版本号                                                  |
 
 这些视图相关的参数只设置本次启动的初始状态——不会更改你已保存的偏好设置，应用内的开关会反映启动时的状态。
 
-环境变量：`DIFFDECK_PORT` 用于设置默认端口。令牌缓存在 `~/.cache/diffdeck/` 下。
+环境变量：`DIFFDECK_PORT` 用于设置默认端口。令牌缓存在 `$XDG_CACHE_HOME/diffdeck/` 下；该变量未设置时则为 `~/.cache/diffdeck/`。
 
 ## 技能
 
@@ -156,9 +156,9 @@ packages/
   diffs/        @diffdeck/diffs         CodeView diff-rendering engine
   trees/        @diffdeck/trees         FileTree engine (vanilla render)
 apps/viewer/    @say8425/diffdeck — CLI + diff-server (data API) + browser viewer
-skills/         agent skill(SKILL.md)——构建时复制进包内
+skills/         the agent skill (SKILL.md), copied into the package at build time
 scripts/        source-map extraction tool, css-inline Bun plugin, render-parity harness
-docs/           README 译文与截图
+docs/           README translations and screenshots
 ```
 
 依赖关系图：`path-store`（无依赖）← `trees`；`theming`（shiki）← `diffs`、`trees`。运行时外部依赖：shiki + `@shikijs/*`、`diff`、`hast-util-to-html`、`lru_map`。
@@ -180,7 +180,7 @@ bun run format      # oxfmt
 包含三条测试线：
 
 - `bun test` —— 单元/集成测试，速度快。`*.e2e.ts` 规格文件会被排除在收集范围之外，因此这一步永远不会启动浏览器。
-- `bun run test:coverage` —— 同一套测试，并对 **diffdeck 自有的运行时代码**（`apps/viewer/{browser,cli,server}`）施加 **100% 覆盖率门槛**。以下部分被有意排除在门槛之外：vendored 的 `packages/*`、`scripts/` 下的工具、浏览器入口 `main.ts`（属于集成入口——改为由 e2e 套件而非进程内测试来覆盖）、`build.ts`，以及测试自身（`*.test.ts`、`e2e/**`）。
+- `bun run test:coverage` —— 同一套测试，并对 **diffdeck 自有的运行时代码**（`apps/viewer/{browser,cli,server}`）施加 **100% 覆盖率门槛**。以下部分被有意排除在门槛之外：vendored 的 `packages/*`、`scripts/` 下的工具、浏览器入口 `main.ts`（属于集成入口——改为由 e2e 套件而非进程内测试来覆盖）、`build.ts`，以及测试文件本身（`*.test.ts`、`e2e/**`）。
 - `bun run test:e2e` —— 基于 Playwright 的真实浏览器测试套件（`apps/viewer/e2e/`）。通过 `channel: "chrome"` 驱动系统自带的 Google Chrome（无需下载 Chromium），端到端覆盖 `main.ts` 及 vendored 的渲染路径。
 
 ### 渲染一致性验证工具

From df88a237aa8c9bdb753a08f8bc8b087e9901ff58 Mon Sep 17 00:00:00 2001
From: Penguin <say8425@gmail.com>
Date: Wed, 5 Aug 2026 13:46:12 +0900
Subject: [PATCH 4/5] =?UTF-8?q?docs:=20=EC=99=84=EA=B2=B0=EC=84=B1=20?=
 =?UTF-8?q?=EB=B9=84=ED=8F=89=EC=9D=B4=20=EC=B0=BE=EC=9D=80=20=EB=8B=A4?=
 =?UTF-8?q?=EC=84=AF=EC=9D=84=20=EA=B3=A0=EC=B9=9C=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

게이트의 한계를 과장한 게 제일 나쁘다 — 이 PR이 고치는 병과 같은 종류다.

- 새 파리티 게이트를 "추가·변경·삭제를 잡는다"고 적었는데 단방향이다.
  HELP의 각 플래그가 문서에 있는지만 보므로 플래그를 지우면 문서에 남은
  유령 플래그가 그대로 통과한다. Options 블록만 읽어서 install-skill의
  --codex/--project도 게이트 밖이다. 무엇을 증명하지 않는지 명시한다.
- pr-check을 84행에서 "다섯 잡"으로 통일해놓고 정작 그걸 설명하는 89행은
  여섯 항목을 잡으로 나열한 채 뒀다. 같은 커밋이 만든 모순이다.
- e2e fixtures를 세 파일로 적었지만 넷이다. #43이 추가한 drag.ts가 빠져
  있었는데, 이건 grab 계열 두 스펙이 공유하는 실측 튜닝값의 단일 지점이라
  목록에 없으면 재튜닝할 곳을 못 찾는다.
- 파일 수 규칙에서 themes/*.json을 "제외"라 적었지만 src/ 밖이라 애초에
  세어지지 않는다. 규칙이 닿지도 않는 걸 제외라 부르면 규칙이 흐려진다.
- parity 하니스 열거에 index.html이 빠졌다 — 문서가 열라고 지시하는 파일이다.

덤: tsconfig.base.json의 include에 남은 bin/**/*.ts도 vestigial이라
JSX 항목에 함께 적는다. Plan 5가 CLI를 apps/viewer에 두면서 bin/은 끝내
만들어지지 않았고, tsc는 매칭 없는 glob을 조용히 넘긴다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G1vWAequwbToDppRceT6C1
---
 CLAUDE.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 5ecf123..db98d40 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,7 +20,7 @@ diffdeck/
 │   ├── extract-sources.ts       # 소스맵 sourcesContent → 원본 TS 복원 도구 (Foundation 일회성)
 │   ├── extract-sources.test.ts  # 합성 소스맵 fixture로 hermetic (외부 체크아웃 의존 없음)
 │   ├── css-inline-plugin.ts     # *.css?inline import용 Bun 플러그인 (런타임/번들러 2분리)
-│   └── parity/                  # 포크 렌더 패리티 하니스 (fixture·preload·smoke test·main·build)
+│   └── parity/                  # 포크 렌더 패리티 하니스 (fixture·preload·smoke test·main·build·index.html)
 ├── .github/workflows/      # pr-check.yml (5잡 — 아직 required 아님, CI 항목 참고) + release.yml (release-please → npm)
 ├── .claude-plugin/ .codex-plugin/  # 플러그인 매니페스트 — release-please extra-files가 버전을 bump
 ├── CHANGELOG.md            # 레포 루트에 있다 (release-please changelog-path의 앞 슬래시 — CI 항목 참고)
@@ -31,7 +31,7 @@ diffdeck/
 └── package.json            # Bun workspace 루트 (workspaces: packages/*, apps/*)
 ```
 
-**위 `N src` 숫자의 정의**: `src/` 아래 **테스트를 뺀 `.ts` 파일 수**다(`style.css`·`themes/*.json`은 제외 — 그래서 따로 적었다). 규칙을 박아두는 이유는 예전에 trees만 `style.css`를 포함해 세는 바람에 46으로 적혀 있었기 때문이다. 재계산: `find packages/<pkg>/src -name '*.ts' -not -path '*__tests__*' | wc -l`. 이 숫자들은 게이트가 없으므로 드리프트한다 — 규모의 감을 주는 값으로만 읽고, 정확한 값이 필요하면 위 명령이 답한다.
+**위 `N src` 숫자의 정의**: `src/` 아래 **테스트를 뺀 `.ts` 파일 수**다(`src/` 안의 `style.css`는 빠지고, `themes/*.json` 10개는 `src/` 밖이라 애초에 안 세어진다 — 그래서 따로 적었다). 규칙을 박아두는 이유는 예전에 trees만 `style.css`를 포함해 세는 바람에 46으로 적혀 있었기 때문이다. 재계산: `find packages/<pkg>/src -name '*.ts' -not -path '*__tests__*' | wc -l`. 이 숫자들은 게이트가 없으므로 드리프트한다 — 규모의 감을 주는 값으로만 읽고, 정확한 값이 필요하면 위 명령이 답한다.
 
 **기술 스택**: Bun (런타임·번들·테스트·workspace), TypeScript 7 (Go 네이티브 컴파일러), oxlint/oxfmt
 
@@ -75,7 +75,7 @@ bun run format
 
 - `bun test` — 유닛·통합, 빠름. `apps/viewer/e2e/*.e2e.ts`는 collection에서 제외되므로 이 커맨드로는 브라우저가 뜨지 않는다.
 - `bun run test:coverage` — 같은 스위트를 `--coverage`로 실행 + **diffdeck 소유 런타임 코드(`apps/viewer/{browser,cli,server}`) 100% 커버리지 게이트**(`bunfig.toml`의 `coverageThreshold`/`coveragePathIgnorePatterns`). 게이트 제외 대상: vendored `packages/*`, `scripts/**`, browser 엔트리 `main.ts`(in-process 유닛 테스트 대신 e2e로 커버), `build.ts`, 그리고 `*.test.ts`/`e2e/**` 자신.
-- `bun run test:e2e` — `apps/viewer/e2e/*.e2e.ts` Playwright 실브라우저 스위트. `playwright.config.ts`가 `channel:"chrome"`으로 시스템 Google Chrome을 구동(Chromium 별도 다운로드 없음), `globalSetup`이 `build.ts`를 1회 실행해 실제 `dist/cli.js`를 스폰. `main.ts`와 vendored 렌더 경로(fold·copy-path·find·flags-sync·image-diff 등)를 end-to-end로 커버. fixtures(`apps/viewer/e2e/fixtures/`: 임시 git repo 빌더 `repo.ts`, CLI 스폰 `launchViewer` `app.ts`, Node `child_process` 래퍼 `proc.ts`)는 **Node**로 동작 — Playwright Test는 항상 spec·fixture·globalSetup을 Node로 실행하므로(`bunx playwright test`로 띄워도) `Bun` 글로벌·`bun`의 `$` 셸을 못 쓰고 `spawn`으로 실제 `bun` 바이너리를 PATH에서 호출한다. `apps/viewer/e2e/tsconfig.json`이 루트 `typecheck` 스크립트에 배선되어 있다.
+- `bun run test:e2e` — `apps/viewer/e2e/*.e2e.ts` Playwright 실브라우저 스위트. `playwright.config.ts`가 `channel:"chrome"`으로 시스템 Google Chrome을 구동(Chromium 별도 다운로드 없음), `globalSetup`이 `build.ts`를 1회 실행해 실제 `dist/cli.js`를 스폰. `main.ts`와 vendored 렌더 경로(fold·copy-path·find·flags-sync·image-diff 등)를 end-to-end로 커버. fixtures(`apps/viewer/e2e/fixtures/`: 임시 git repo 빌더 `repo.ts`, CLI 스폰 `launchViewer` `app.ts`, Node `child_process` 래퍼 `proc.ts`, 합성 드래그 제스처 `drag.ts` — `grab.e2e.ts`·`grab-highlight.e2e.ts`가 공유하며 sleep 값과 40px 오프셋 같은 실측 튜닝값의 단일 지점이다)는 **Node**로 동작 — Playwright Test는 항상 spec·fixture·globalSetup을 Node로 실행하므로(`bunx playwright test`로 띄워도) `Bun` 글로벌·`bun`의 `$` 셸을 못 쓰고 `spawn`으로 실제 `bun` 바이너리를 PATH에서 호출한다. `apps/viewer/e2e/tsconfig.json`이 루트 `typecheck` 스크립트에 배선되어 있다.
 - **`*.e2e.ts` 네이밍 규칙**: `bun test`는 `*.test.ts` 외에 `*.spec.ts`도 수집하므로, Playwright 스펙을 `*.e2e.ts`로 명명해 `bun test`가 절대 이를 실행하지 않도록 분리한다(Playwright 쪽은 `testMatch:"**/*.e2e.ts"`로 반대로 한정).
 - **`bunfig.toml`의 `preload`는 `scripts/parity/preload.ts` 하나뿐이고, happy-dom을 여기 넣으면 안 된다.** preload는 css-inline 플러그인을 등록해 포크 패키지의 `import styles from '../style.css?inline'`이 `bun test`에서 실제 스타일시트 텍스트로 풀리게 하는 용도다(빌드가 쓰는 것과 같은 플러그인). 반면 happy-dom 전역 등록(`packages/trees/src/__tests__/happydom.ts`)은 **의도적으로 preload에서 빠져 있다** — 전역 등록은 Node의 fetch/http를 테스트 런 **전체**에서 happy-dom 구현으로 갈아치우고, 그러면 실제 HTTP 서버를 띄우는 `apps/viewer` 테스트들이 무너진다(happy-dom의 `fetch`가 `NetworkError: Parse Error`로 죽는다 — diff-server·api/blob·built-serving 계열). **터지는 개수는 상수가 아니라 스위트 크기의 함수다**: bunfig 주석이 적은 21건은 이 함정을 처음 밟았을 때의 값이고, 2026-08-05에 다시 재현해보니 58건이었다. 숫자를 기준으로 삼지 말고 preload 목록 자체를 지켜라. DOM이 필요한 테스트는 파일 맨 위에서 `import "../__tests__/happydom";`으로 **파일 단위로만** 켠다(`happydom-smoke.test.ts` 참고).
 
@@ -86,7 +86,7 @@ bun run format
 
 ### CI / 릴리스
 
-- **`.github/workflows/pr-check.yml`** — PR마다 lint(oxlint)·format:check(oxfmt)·typecheck·test·coverage(100% 게이트)·**e2e** 잡. `bun install --frozen-lockfile`. e2e 잡은 러너에 Node를 고정(Playwright는 spec·fixture·globalSetup을 항상 Node로 실행)하고 `playwright install --with-deps chrome`으로 **실제 Google Chrome**을 깐다(`playwright.config.ts`가 `channel:"chrome"`이라 번들 Chromium으로는 안 된다). 실패 시 `apps/viewer/test-results/`를 아티팩트로 올린다 — 없으면 CI 전용 실패를 로컬에서 재현할 단서가 없다. **e2e를 게이트에 둔 이유**: happy-dom에는 레이아웃이 없어 "창 크기가 상태 전환에도 변하지 않는가"·"버튼이 실제로 페인트되는가"·"클릭해도 포커스가 남는가" 같은 계약은 유닛이 원리적으로 못 잡는다. 일부만 고르지 않고 전부 돌리는 이유는 비용이 싸서가 아니라(실측상 e2e 잡이 다른 잡보다 수십 배 무겁다) **어느 계약이 깨질지 미리 알 수 없어서**다 — 골라 돌리면 고르는 사람이 이미 답을 안다고 전제하게 된다. `timeout-minutes: 15` 안에서 감당된다. 개수·소요시간을 문서에 박아두지 않는다(반드시 드리프트한다); 개수는 `bunx playwright test --list`가, 소요시간은 `gh run list --workflow=pr-check.yml --status=success` → `gh run view <id> --json jobs`가 답한다.
+- **`.github/workflows/pr-check.yml`** — PR마다 **다섯 잡**: lint(oxlint + format:check(oxfmt)가 같은 잡의 스텝)·typecheck·test·coverage(100% 게이트)·**e2e**. `bun install --frozen-lockfile`. e2e 잡은 러너에 Node를 고정(Playwright는 spec·fixture·globalSetup을 항상 Node로 실행)하고 `playwright install --with-deps chrome`으로 **실제 Google Chrome**을 깐다(`playwright.config.ts`가 `channel:"chrome"`이라 번들 Chromium으로는 안 된다). 실패 시 `apps/viewer/test-results/`를 아티팩트로 올린다 — 없으면 CI 전용 실패를 로컬에서 재현할 단서가 없다. **e2e를 게이트에 둔 이유**: happy-dom에는 레이아웃이 없어 "창 크기가 상태 전환에도 변하지 않는가"·"버튼이 실제로 페인트되는가"·"클릭해도 포커스가 남는가" 같은 계약은 유닛이 원리적으로 못 잡는다. 일부만 고르지 않고 전부 돌리는 이유는 비용이 싸서가 아니라(실측상 e2e 잡이 다른 잡보다 수십 배 무겁다) **어느 계약이 깨질지 미리 알 수 없어서**다 — 골라 돌리면 고르는 사람이 이미 답을 안다고 전제하게 된다. `timeout-minutes: 15` 안에서 감당된다. 개수·소요시간을 문서에 박아두지 않는다(반드시 드리프트한다); 개수는 `bunx playwright test --list`가, 소요시간은 `gh run list --workflow=pr-check.yml --status=success` → `gh run view <id> --json jobs`가 답한다.
 - **lint 스코프**: 스크립트는 `oxlint apps/`/`oxfmt apps/`로 **owned 코드만** 대상(vendored `packages/*`는 Pierre 원본 스타일이라 lint/format 게이트 제외). `.oxlintrc.json`의 `typeAware:true` 때문에 `oxlint-tsgolint`(devDep)가 있어야 lint가 돈다. 테스트/e2e override(`**/__tests__/**`·`**/e2e/**`)에서 unbound-method·no-empty-pattern·no-unassigned-import 등 완화.
 - **워커 하이라이트 경로 활성화됨**: `build.ts`가 `packages/diffs/src/worker/worker.ts`를 `dist/viewer/worker.js`로 번들하고, `main.ts`가 `getOrCreateWorkerPoolSingleton`(poolSize 2)으로 만든 풀을 CodeView에 주입한다. 렌더 옵션 5필드(theme·useTokenTransformer·tokenizeMaxLineLength·lineDiffType·maxLineDiffLength)는 풀이 자기 옵션을 init 메시지로 워커에 밀어넣어 자기일관적이다 — 진짜 계약은 반대 방향: 이 5필드를 CodeView 레벨에서 오버라이드해도 워커 경로는 무시하므로, 바꾸려면 반드시 `getOrCreateWorkerPoolSingleton`의 `highlighterOptions`에 넣어야 한다. 회귀망: `worker-highlight.e2e.ts`(첫 진입 무스파이크 + plain→색 전이 + 폴백).
 - **`.github/workflows/release.yml` + `release-please-config.json` + `.release-please-manifest.json`** — release-please(모노레포: 배포 패키지 `apps/viewer`, `package-name @say8425/diffdeck`)가 conventional commits로 **릴리스 PR을 생성**하고, **사람이 그 PR을 머지**하면 release-please가 릴리스·태그를 커팅 → `releases_created == 'true'` 일 때 publish 잡이 `apps/viewer`에서 `bun run build` + `npm publish --provenance --access public`.
@@ -126,13 +126,13 @@ cd scripts/parity && python3 -m http.server 8099 # http://127.0.0.1:8099/index.h
   2. 빈 렌더 윈도우(totalLines 0 = collapsed) 렌더를 plain-text + zero-range로 — 하이라이트 렌더가 범위를 무시하고 전체 파일을 동기 토크나이즈해 대형 lockfile 마운트가 수 초 프리징하던 것 완치. `renderDiff` sync/async 두 경로 + `RenderedDiffASTCache.emptyWindow` 표식(빈 풀을 확장 렌더가 재사용하면 processDiffResult가 throw — 표식이 확장 시 재렌더를 강제). 회귀망: `lockfile-freeze.e2e.ts` (30k줄 프리징 게이트 + 8k줄 sub-cutoff 펼침 무오류).
   3. `DiffHunksRenderer.recycle()`의 renderCache 조건부 보존 — 하이라이트 완료된(비-emptyWindow) 토크나이즈 AST를 언마운트 후에도 유지해, 오버스캔 재진입 때마다 파일 전체를 동기 재토크나이즈하던 100~360ms 프레임 스파이크(스크롤 끊김의 주범, 프로파일로 busy의 84~86% 확인)를 근절. 스테일은 renderDiff의 diff/options 동등성 검증이 자동 무효화. 회귀망: `retokenize-cache.e2e.ts` (재진입 프레임 상한 + watch 스테일 가드).
   4. 파일트리 flatten 경로의 GitHub식 말줄임 + full-path 툴팁 (`renderRowVanilla.ts` + `style.css`) — upstream은 flatten된 체인의 세그먼트마다 Truncate 위젯을 씌워 좁은 사이드바에서 `eng… / r… / … / p…`처럼 세그먼트별로 조각나던 것을, 세그먼트를 plain 텍스트로 렌더하고 래퍼(`[data-item-flattened-subitems]` — nowrap min-content가 행 flex 체인을 타고 행 폭을 부풀리지 않도록 `minmax(0, max-content)` 단일 컬럼 grid) 안의 clip 요소(`[data-item-flattened-clip]`)에서 CSS `text-overflow: ellipsis`로 끝에서 한 번만 자르게 변경(GitHub 트리와 동일). 아울러 모든 행 버튼에 `title`(full path — flatten 행은 종단 경로, `data-item-path`와 동일)을 주입해 hover 시 전체 경로 툴팁이 뜬다. 비-flatten 행의 확장자 보존 middle-truncate는 그대로다. 회귀망: `tree-path-tooltip.e2e.ts` + `renderRowVanilla.test.ts`.
-- **JSX 설정**: `tsconfig.base.json`은 `jsx: react-jsx` + `jsxImportSource: preact`를 여전히 선언하지만, Plan 3(de-preact) 완료 이후 리포 전체에 `.tsx` 파일이 하나도 없어 이 설정은 현재 미사용(vestigial) 상태다. `packages/diffs`·`packages/trees`의 tsconfig는 base를 extend만 하고 별도 JSX override가 없다. 루트 typecheck가 flat이 아니라 패키지별 루프인 건 JSX 때문이 아니라 TS project references가 안 걸려 있어서다.
+- **JSX 설정**: `tsconfig.base.json`은 `jsx: react-jsx` + `jsxImportSource: preact`를 여전히 선언하지만, Plan 3(de-preact) 완료 이후 리포 전체에 `.tsx` 파일이 하나도 없어 이 설정은 현재 미사용(vestigial) 상태다. 같은 파일의 `include`에 있는 `bin/**/*.ts`도 마찬가지다 — Plan 5가 CLI를 `bin/`이 아니라 `apps/viewer/cli.ts`에 두면서 그 디렉터리는 끝내 만들어지지 않았고(로드맵 Plan 5 항목 참고), tsc는 매칭 없는 glob을 조용히 넘기므로 아무것도 깨지지 않은 채 남아 있다. `packages/diffs`·`packages/trees`의 tsconfig는 base를 extend만 하고 별도 JSX override가 없다. 루트 typecheck가 flat이 아니라 패키지별 루프인 건 JSX 때문이 아니라 TS project references가 안 걸려 있어서다.
 - **외부 deps는 정확 버전 핀** (캐럿 금지). vendored 패키지는 workspace 내부.
 - **preact/react 런타임 의존 없음** — Plan 3(de-preact)에서 trees의 preact 렌더 스킨을 vanilla로 완전히 포팅했고, 어느 `packages/*/package.json`·`apps/viewer/package.json`에도 preact/react가 없다(devDep·peer 포함).
 - **라이선스**: 각 `packages/*/LICENSE`(Apache-2.0) + `packages/trees/NOTICE.md`(headless-tree MIT 유래) + 최상위 `NOTICE` 보존. 파일 수정 사실 고지 유지.
 - **`*.css?inline` ambient 선언**: 소비자(앱)의 tsconfig가 패키지 `src/**`를 glob include하지 않으면 안 보임 — Plan 2 앱 tsconfig에서 배선 필요.
 - **cc-statusline 잔재 데드코드 제거됨**: `server/ensure.ts`(spawn-if-not-running 데몬 ensure)와 `server.ts`의 `idleTimeoutMs` idle-shutdown을 제거했고, 뒤늦게 `config.ts`의 `isDiffViewerDisabled`/`DIFFDECK_DISABLE`도 지웠다(diffdeck에선 **호출부가 한 번도 없었다** — 유일한 참조가 자기 테스트라 커버리지 100%가 그대로 유지돼 게이트로는 원리적으로 안 드러났다. 커버리지 초록은 "쓰인다"는 증거가 아니다). diffdeck의 CLI는 서버를 **foreground**로 띄워 Ctrl+C로 종료하는 모델이라(cc-statusline처럼 statusline이 백그라운드 데몬을 spawn-if-not-running으로 관리하는 구조가 아님) 이 기능들이 전부 미사용이었다. 참고로 `server.ts`의 `idleTimeout: 120`(Bun.serve 소켓 타임아웃)은 제거된 idle-shutdown과 **다른 것**이고 지금도 살아 있는 계약이다 — "Loading…" 항목의 45+45 예산이 이 값에 걸린다.
-- **CLI 플래그를 바꾸면 문서 일곱이 같은 커밋에서 함께 움직인다.** `apps/viewer/cli/args.ts`(파싱)와 `cli.ts`의 `HELP`(단일 진실)에 플래그를 추가·변경·삭제하면, 그 표면을 사람에게 되풀이해 말하는 문서가 전부 따라와야 한다: `skills/diffdeck/SKILL.md`, `README.md`(루트), `apps/viewer/README.md`(**npm 패키지 페이지** — 루트 README와 별개 파일이다), `docs/README.{ko,ja,zh,es}.md` 넷. SKILL.md가 특별한 이유는 따로 있다 — `install-skill`이 `~/.claude/skills/`에 배포하고(`--codex` 시 `~/.agents/skills/`에도) Claude Code 플러그인이 `skills/`를 자동 스캔하는, **에이전트가 diffdeck를 구동할 때 읽는 유일한 문서**라 드리프트하면 에이전트가 존재하는 옵션을 모른 채 구동한다. `apps/viewer/__tests__/docs-flags-parity.test.ts`가 `HELP`의 Options 블록과 **일곱 문서 전부**를 대조한다. **한 문서만 보는 게이트는 나머지를 지키지 않는다** — 예전엔 이 테스트가 SKILL.md만 봤고, 그 사이 `--fold-with-tree`가 npm README와 번역 4종에서 조용히 빠져 있었다. 경로가 그걸 잘 보여준다: 플래그를 만든 #14은 루트 README와 CLAUDE.md만 갱신했고, SKILL.md는 뒤늦게 #24(파리티 테스트를 만든 그 커밋)이 채웠다 — 즉 **게이트가 감시하는 문서만 따라잡혔고 나머지 다섯은 그대로 남았다.** 문서를 새로 추가하면 그 테스트의 `DOCS` 배열에도 넣어야 같은 함정을 다시 파지 않는다.
+- **CLI 플래그를 바꾸면 문서 일곱이 같은 커밋에서 함께 움직인다.** `apps/viewer/cli/args.ts`(파싱)와 `cli.ts`의 `HELP`(단일 진실)에 플래그를 추가·변경·삭제하면, 그 표면을 사람에게 되풀이해 말하는 문서가 전부 따라와야 한다: `skills/diffdeck/SKILL.md`, `README.md`(루트), `apps/viewer/README.md`(**npm 패키지 페이지** — 루트 README와 별개 파일이다), `docs/README.{ko,ja,zh,es}.md` 넷. SKILL.md가 특별한 이유는 따로 있다 — `install-skill`이 `~/.claude/skills/`에 배포하고(`--codex` 시 `~/.agents/skills/`에도) Claude Code 플러그인이 `skills/`를 자동 스캔하는, **에이전트가 diffdeck를 구동할 때 읽는 유일한 문서**라 드리프트하면 에이전트가 존재하는 옵션을 모른 채 구동한다. `apps/viewer/__tests__/docs-flags-parity.test.ts`가 `HELP`의 Options 블록과 **일곱 문서 전부**를 대조한다. **이 게이트가 무엇을 증명하지 않는지 알 것**: 단방향이다 — `HELP`의 각 플래그가 문서에 있는지만 보므로 **플래그를 삭제하면 못 잡는다**(문서에 남은 유령 플래그는 통과한다). 그리고 `Options:` 블록만 읽으므로 `install-skill`의 `--codex`/`--project`는 아예 게이트 밖이다. 추가·변경만 자동으로 걸린다고 읽어라. **한 문서만 보는 게이트는 나머지를 지키지 않는다** — 예전엔 이 테스트가 SKILL.md만 봤고, 그 사이 `--fold-with-tree`가 npm README와 번역 4종에서 조용히 빠져 있었다. 경로가 그걸 잘 보여준다: 플래그를 만든 #14은 루트 README와 CLAUDE.md만 갱신했고, SKILL.md는 뒤늦게 #24(파리티 테스트를 만든 그 커밋)이 채웠다 — 즉 **게이트가 감시하는 문서만 따라잡혔고 나머지 다섯은 그대로 남았다.** 문서를 새로 추가하면 그 테스트의 `DOCS` 배열에도 넣어야 같은 함정을 다시 파지 않는다.
 - **`hidden`으로 숨기는 노드에 author `display`를 선언하면 `[hidden]{display:none}`을 반드시 짝지어라.** author origin이 UA 규칙을 이겨 영구 노출된다. `#grab-popover[hidden]`이 `display:flex` 뒤에 명시된 이유이고, 과거 `.grab-hint`에서 두 번째로 밟았다(지금은 `.grab-hint`가 sr-only라 `hidden`을 토글하지 않아 이 함정에서 벗어났다 — 규칙 자체는 `#grab-popover`에 그대로 유효하다). **happy-dom은 `textContent`만 보므로 유닛이 못 잡고 실브라우저에서만 드러난다** — 이런 실패는 e2e에서만 잡힌다.
 - 워커 로드 실패 폴백은 엔진이 아니라 앱 워치독이 담당한다(회귀망: worker-highlight.e2e.ts의 폴백 테스트).
 - **프로세스 cwd가 삭제되면 diffdeck 전체가 죽는다 — 그래서 `cli.ts`가 기동 직후 `/`로 이탈한다.** cwd가 unlink된 프로세스는 **자식 프로세스를 하나도 생성할 수 없다**(자식이 상속할 cwd를 커널이 해석하지 못한다). 이건 Bun Shell의 동작이 아니라 OS 제약이라 `.cwd(repo)`를 명시해도, 셸을 안 거치는 `Bun.spawn`을 써도 `ENOENT: posix_spawn`으로 똑같이 죽는다(실측) — **호출부에서 고칠 수 있는 방법이 없다.** 증상은 `/api/diff`가 **repo와 무관하게** 400 `not a git repository`를 내는 것이고, `/api/ping`(204)과 정적 페이지(200)는 서브프로세스를 안 띄워서 멀쩡하므로 "서버는 살아있는데 diff만 안 된다"로 오진하기 쉽다. 감별: 403이면 토큰/포트 문제고, 400이면서 repo를 바꿔도 동일하면 이 문제다. 장수 데몬(cc-statusline이 띄운다 — `/api/ping`의 pid 헤더 주석 참고)이 기동 시점의 worktree를 물고 있다가 그 worktree가 삭제되면 발생한다. 예방은 `cli.ts`가 `repo`를 읽은 **직후** `toSafeCwd()`로 이탈하는 것이고(순서가 계약이다 — 먼저 이탈하면 `repo`가 `/`가 된다), 자가회복은 `server.ts` 핸들러 진입부가 `repairCwd`가 주입된 경우에만(단축평가 — 없으면 `isCwdAlive` 호출 자체를 건너뛴다, `repairCwd`를 안 넘긴 임베드 호스트에게 감지 자체가 순수 비용이 되면 안 되기 때문이다) `isCwdAlive`로 감지해 그 `repairCwd`를 부르는 것이다. **감지는 반드시 `existsSync(process.cwd())`여야 한다** — `existsSync(".")`·`statSync(".")`는 unlink된 inode를 살려두는 cwd 파일 디스크립터 때문에 항상 true라 원리적으로 못 잡는다. `process.chdir()`이 프로세스 전역 부작용이라 라이브러리인 `startDiffServer`는 감지만 하고 복구는 프로세스를 소유한 `cli.ts`에서 주입받는다. (`cli.ts`는 서버를 띄운 직후 `prewarmDiff`(`server/prewarm.ts`)로 자기 서버의 `/api/diff`를 `working`·`base` **순차로** 두 번 호출해 payload 캐시를 데운다 — 브라우저가 뜨는 동안 첫 diff 빌드를 선실행시키는 best-effort 경로다. 동시 호출이 아닌 이유는 `BUILD_CONCURRENCY=8`이 호출당이라 두 모드를 겹치면 기동 직후 git 서브프로세스 버스트가 배로 뛰기 때문이고, 이는 아래 "Loading…" 항목의 재시도 1회 제한과 같은 근거다. 실패해도 뷰어는 정상 동작한다.) 회귀망: `daemon-cwd.e2e.ts`가 사용자에게 보이는 계약(기동 디렉토리가 삭제된 데몬이 다른 repo를 계속 서빙한다)을 종단 검증하는데, **예방과 자가회복을 구분하지는 못한다** — 둘 중 하나만 살아 있어도 통과하고 둘 다 없어야 400으로 빨간불이 된다(실측). 가드가 라우트 분기보다 먼저 돌아 첫 요청에서 git 호출 전에 cwd를 되살리기 때문이다. 기제별 격리는 유닛이 맡는다: `cli-run.test.ts`(예방 — 호출 순서와 주입), `diff-server.test.ts`(자가회복 4종 — 커버리지가 branch를 안 세므로 호출/미호출을 각각 찌르고, 나머지 둘은 단축평가로 감지가 건너뛰는 경로와 `cwdDeps` 생략 시 REAL_CWD_DEPS가 실제로 쓰이는 경로의 함수 커버리지를 찌른다), `diff-cwd.test.ts`(판정). 이후 git 호출 17곳 중 16곳은 `git -C ${repo}`로 repo를 조준하지만, 17번째인 `prBaseName`(`diff.ts:29-30`)은 `gh pr view`라 `-C`가 없고 `.cwd(repo)`로만 조준한다 — "전부 `-C`"로 읽으면 코드를 잘못 스캔하게 되지만, 결론(모두 repo를 명시적으로 조준하므로 cwd가 `/`여도 정상)은 그대로다. cwd 의존 지점이 하나 더 있다: `server.ts`의 `resolve(cfg.viewerDir)`는 chdir **이후**에 돌아 상대경로였다면 `/` 기준으로 풀리는데, 프로덕션 값(`${import.meta.dir}/viewer`)과 테스트(mkdtemp 절대경로)가 둘 다 절대경로라 현재 깨지는 건 없다. `/api/blob`의 경로 탈출 가드는 안전하다 — `getFileBytes`(`diff.ts:220-221`)가 `resolve(repo)`/`resolve(root, path)`로 가드를 세우고 실제 읽기는 `readFileSync(join(repo, path))`라 OS가 syscall 시점에 같은 cwd로 풀어 가드 기준과 읽기 기준이 함께 움직이므로 탈출 구멍이 열리지 않는다 — cwd가 조용히 바뀌며 보안 버그가 될 뻔했던 유일한 지점이라 기록해 둘 가치가 있다.

From f4ca253fc295f86b117120d5f9263aa5204826fe Mon Sep 17 00:00:00 2001
From: Penguin <say8425@gmail.com>
Date: Wed, 5 Aug 2026 13:50:44 +0900
Subject: [PATCH 5/5] =?UTF-8?q?docs:=20=EC=BD=94=EB=93=9C=20=EB=A6=AC?=
 =?UTF-8?q?=EB=B7=B0=EA=B0=80=20=EC=B0=BE=EC=9D=80=20worker.js=20=EC=98=A4?=
 =?UTF-8?q?=EB=A5=98=EC=99=80=20=EA=B2=8C=EC=9D=B4=ED=8A=B8=20=ED=95=9C?=
 =?UTF-8?q?=EA=B3=84=EB=A5=BC=20=EB=B0=94=EB=A1=9C=EC=9E=A1=EB=8A=94?=
 =?UTF-8?q?=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Critical 하나가 하필 "번들에 뭐가 들었는지 확인하는 법"을 가르치는 문단에
있었다. 그 문단을 믿고 grep한 사람이 정반대 결론을 내게 된다.

- worker.js가 "shiki와 문법 전량을 품는다"고 적었지만 문법은 0이다.
  worker.ts가 createHighlighterCore({themes:[], langs:[]})로 빈 채 뜨고
  문법은 WorkerPoolManager가 postMessage로 밀어넣는다. 실측으로
  main.js 298 : worker.js 0 (source.ts 기준). 10.9MB 대 836KB 격차가
  정확히 그 차이다. grep -c를 쓰지 말라는 주의도 함께 적는다 — 미니파이
  번들은 사실상 한 줄이라 298이 1로 보인다.
- 새 게이트가 "언급"을 증명하지 "위치"를 증명하지 않는다. 표의 행을 지우고
  같은 코드 스팬을 산문으로 옮겨도 통과한다(리뷰가 mutation으로 확인).
  표 문법에 앵커를 걸지 않는 이유까지 테스트 주석에 남긴다 — 번역 4종의
  컬럼 폭이 제각각이고 SKILL.md는 표가 아니라, 앵커를 걸면 게이트가 먼저
  부서진다.
- CLAUDE.md 자신이 여덟 번째 플래그 기술처인데 DOCS에 없다. --port·
  --no-open을 안 다뤄서 넣으면 빨간불이 나는 의도적 제외다. 다음 사람이
  "빠뜨렸다"고 판단해 추가하지 않도록 이유를 적는다.
- 파일 읽기를 describe 본문에서 test 콜백 안으로 옮긴다. 경로가 틀리면
  테스트 등록 전에 throw해서 "문서 X가 없다"가 아니라 수집 크래시로
  보였다 — 가드 두 개조차 안 돌았다.
- preload 플러그인을 "빌드와 같은 것"이라 적었지만 같은 모듈의 두 export다
  (runtime/bundler). WHAT 트리가 이미 "런타임/번들러 2분리"라 적고 있어
  두 줄이 서로 어긋났다.
- 21건 설명이 "bunfig 주석이 적은"이라는 옛 상태를 가리키고 있었다.

덤: 다섯 README의 "런타임 외부 의존성" 줄이 workspace 그래프를 말하는
건데, 이제 CLAUDE.md가 "설치 시 resolve되는 게 없다"고 못 박아 나란히
읽으면 어긋나 보인다. 한 구절로 둘을 잇는다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G1vWAequwbToDppRceT6C1
---
 CLAUDE.md                                       |  6 +++---
 README.md                                       |  2 +-
 apps/viewer/__tests__/docs-flags-parity.test.ts | 17 ++++++++++++++++-
 docs/README.es.md                               |  2 +-
 docs/README.ja.md                               |  2 +-
 docs/README.ko.md                               |  2 +-
 docs/README.zh.md                               |  2 +-
 7 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index db98d40..e25e16e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -77,7 +77,7 @@ bun run format
 - `bun run test:coverage` — 같은 스위트를 `--coverage`로 실행 + **diffdeck 소유 런타임 코드(`apps/viewer/{browser,cli,server}`) 100% 커버리지 게이트**(`bunfig.toml`의 `coverageThreshold`/`coveragePathIgnorePatterns`). 게이트 제외 대상: vendored `packages/*`, `scripts/**`, browser 엔트리 `main.ts`(in-process 유닛 테스트 대신 e2e로 커버), `build.ts`, 그리고 `*.test.ts`/`e2e/**` 자신.
 - `bun run test:e2e` — `apps/viewer/e2e/*.e2e.ts` Playwright 실브라우저 스위트. `playwright.config.ts`가 `channel:"chrome"`으로 시스템 Google Chrome을 구동(Chromium 별도 다운로드 없음), `globalSetup`이 `build.ts`를 1회 실행해 실제 `dist/cli.js`를 스폰. `main.ts`와 vendored 렌더 경로(fold·copy-path·find·flags-sync·image-diff 등)를 end-to-end로 커버. fixtures(`apps/viewer/e2e/fixtures/`: 임시 git repo 빌더 `repo.ts`, CLI 스폰 `launchViewer` `app.ts`, Node `child_process` 래퍼 `proc.ts`, 합성 드래그 제스처 `drag.ts` — `grab.e2e.ts`·`grab-highlight.e2e.ts`가 공유하며 sleep 값과 40px 오프셋 같은 실측 튜닝값의 단일 지점이다)는 **Node**로 동작 — Playwright Test는 항상 spec·fixture·globalSetup을 Node로 실행하므로(`bunx playwright test`로 띄워도) `Bun` 글로벌·`bun`의 `$` 셸을 못 쓰고 `spawn`으로 실제 `bun` 바이너리를 PATH에서 호출한다. `apps/viewer/e2e/tsconfig.json`이 루트 `typecheck` 스크립트에 배선되어 있다.
 - **`*.e2e.ts` 네이밍 규칙**: `bun test`는 `*.test.ts` 외에 `*.spec.ts`도 수집하므로, Playwright 스펙을 `*.e2e.ts`로 명명해 `bun test`가 절대 이를 실행하지 않도록 분리한다(Playwright 쪽은 `testMatch:"**/*.e2e.ts"`로 반대로 한정).
-- **`bunfig.toml`의 `preload`는 `scripts/parity/preload.ts` 하나뿐이고, happy-dom을 여기 넣으면 안 된다.** preload는 css-inline 플러그인을 등록해 포크 패키지의 `import styles from '../style.css?inline'`이 `bun test`에서 실제 스타일시트 텍스트로 풀리게 하는 용도다(빌드가 쓰는 것과 같은 플러그인). 반면 happy-dom 전역 등록(`packages/trees/src/__tests__/happydom.ts`)은 **의도적으로 preload에서 빠져 있다** — 전역 등록은 Node의 fetch/http를 테스트 런 **전체**에서 happy-dom 구현으로 갈아치우고, 그러면 실제 HTTP 서버를 띄우는 `apps/viewer` 테스트들이 무너진다(happy-dom의 `fetch`가 `NetworkError: Parse Error`로 죽는다 — diff-server·api/blob·built-serving 계열). **터지는 개수는 상수가 아니라 스위트 크기의 함수다**: bunfig 주석이 적은 21건은 이 함정을 처음 밟았을 때의 값이고, 2026-08-05에 다시 재현해보니 58건이었다. 숫자를 기준으로 삼지 말고 preload 목록 자체를 지켜라. DOM이 필요한 테스트는 파일 맨 위에서 `import "../__tests__/happydom";`으로 **파일 단위로만** 켠다(`happydom-smoke.test.ts` 참고).
+- **`bunfig.toml`의 `preload`는 `scripts/parity/preload.ts` 하나뿐이고, happy-dom을 여기 넣으면 안 된다.** preload는 css-inline 플러그인을 등록해 포크 패키지의 `import styles from '../style.css?inline'`이 `bun test`에서 실제 스타일시트 텍스트로 풀리게 하는 용도다(빌드와 **같은 모듈의 런타임 변형** — preload는 `cssInlineRuntimePlugin`, `build.ts`는 `cssInlineBundlerPlugin`이다). 반면 happy-dom 전역 등록(`packages/trees/src/__tests__/happydom.ts`)은 **의도적으로 preload에서 빠져 있다** — 전역 등록은 Node의 fetch/http를 테스트 런 **전체**에서 happy-dom 구현으로 갈아치우고, 그러면 실제 HTTP 서버를 띄우는 `apps/viewer` 테스트들이 무너진다(happy-dom의 `fetch`가 `NetworkError: Parse Error`로 죽는다 — diff-server·api/blob·built-serving 계열). **터지는 개수는 상수가 아니라 스위트 크기의 함수다**: 처음 밟았을 때는 21건이었고, 2026-08-05에 다시 재현해보니 58건이었다(bunfig 주석도 두 값을 함께 적어 둔다). 숫자를 기준으로 삼지 말고 preload 목록 자체를 지켜라. DOM이 필요한 테스트는 파일 맨 위에서 `import "../__tests__/happydom";`으로 **파일 단위로만** 켠다(`happydom-smoke.test.ts` 참고).
 
 ### 기여 워크플로 (PR 필수)
 
@@ -97,7 +97,7 @@ bun run format
 - **사용자 게이트(부트스트랩, 자동화 불가)**: npm은 신규 패키지 최초 버전을 OIDC로 못 올린다(설정 UI가 패키지 존재를 요구, npm/cli #8544). 따라서 순서: ① `0.1.0`을 **로컬에서 토큰/`npm login`으로 1회 수동 publish**(패키지 생성) → ② npmjs.com 패키지 Settings에서 trusted publisher 등록(org `say8425`, repo `diffdeck`, workflow `release.yml`, environment 없음) → ③ 이후 release-please가 낸 릴리스 PR을 사람이 머지하면 CI가 tokenless로 publish. provenance엔 public repo 필요(✅).
 - **CI는 아직 "신호"이고 "게이트"가 아니다 — required status checks가 비어 있다.** `main` 룰셋에는 `deletion`·`non_fast_forward`만 있고(`gh api repos/say8425/diffdeck/branches/main/protection` → 404 Branch not protected), 어떤 체크도 required로 지정돼 있지 않다. 그래서 **빨간 CI로도 머지 버튼이 열린다**(실측: e2e가 `IN_PROGRESS`인데 `mergeStateStatus: CLEAN`). e2e를 포함해 다섯 잡 전부에 해당하는 기존 상태다. 진짜 게이트로 만들려면 룰셋에 `required_status_checks`로 `lint`·`typecheck`·`test`·`coverage`·`e2e`를 등록해야 한다 — 워크플로 파일만으로는 안 된다. (같은 종류의 "코드가 아니라 저장소 설정" 항목이라 바로 아래 항목과 나란히 둔다.)
 - **저장소 설정 요구사항**: Settings → Actions → General → Workflow permissions의 **"Allow GitHub Actions to create and approve pull requests"** 가 켜져 있어야 한다(기본 OFF). 꺼져 있으면 release-please가 버전 계산·브랜치·커밋까지 다 만들어놓고 **PR 생성 단계에서만** `GitHub Actions is not permitted to create or approve pull requests` 로 실패한다. API로는 `gh api -X PUT repos/say8425/diffdeck/actions/permissions/workflow -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true`.
-- **배포 산출물**: `build.ts`가 `dist/cli.js`에 `#!/usr/bin/env bun` 셰뱅 + 실행권한을 부여해 `bunx`뿐 아니라 `npx`/직접 실행에서도 bun으로 구동된다(`// @bun` 마커는 셰뱅 다음 줄에 유지). **`apps/viewer/package.json`에는 `dependencies`가 하나도 없다 — 의도된 상태다**: tarball은 `files`에 적은 `dist`·`LICENSE`·`NOTICE`에 npm이 **`files`와 무관하게 항상 싣는** `README.md`·`package.json`을 더해 9개 파일이고(`npm pack --dry-run`으로 확인), 사용자는 `bunx` 시점에 아무것도 resolve하지 않는다. `apps/viewer/README.md`가 npm 패키지 페이지가 되는 것도 이 강제 포함 덕분이다 — `files`에 없다고 빼면 안 된다. 두 축이 다른 이유로 그렇다 — `dist/cli.js`(26KB)는 **애초에 외부 deps를 안 쓴다**(서버·CLI가 Bun `$`와 node 빌트인만 쓴다: 번들에 남은 import가 `fs`·`os`·`path`뿐), 반면 `dist/viewer/main.js`(10.9MB)와 `dist/viewer/worker.js`(836KB)는 shiki와 문법 전량을 **번들 안에 품는다**. 뒤집으면 **새 런타임 import를 추가할 때 `dependencies`에 적을 곳이 없다** — 번들에 실제로 들어갔는지 `bun run build` 후 산출물에서 확인해야 하고, external로 남은 것은 설치 시점에 그냥 없다. 산출물은 `dist/cli.js` + `dist/viewer/{main.js,worker.js,index.html}` + `dist/skills/diffdeck/SKILL.md` 다섯이다.
+- **배포 산출물**: `build.ts`가 `dist/cli.js`에 `#!/usr/bin/env bun` 셰뱅 + 실행권한을 부여해 `bunx`뿐 아니라 `npx`/직접 실행에서도 bun으로 구동된다(`// @bun` 마커는 셰뱅 다음 줄에 유지). **`apps/viewer/package.json`에는 `dependencies`가 하나도 없다 — 의도된 상태다**: tarball은 `files`에 적은 `dist`·`LICENSE`·`NOTICE`에 npm이 **`files`와 무관하게 항상 싣는** `README.md`·`package.json`을 더해 9개 파일이고(`npm pack --dry-run`으로 확인), 사용자는 `bunx` 시점에 아무것도 resolve하지 않는다. `apps/viewer/README.md`가 npm 패키지 페이지가 되는 것도 이 강제 포함 덕분이다 — `files`에 없다고 빼면 안 된다. 두 축이 다른 이유로 그렇다 — `dist/cli.js`(26KB)는 **애초에 외부 deps를 안 쓴다**(서버·CLI가 Bun `$`와 node 빌트인만 쓴다: 번들에 남은 import가 `fs`·`os`·`path`뿐), 반면 `dist/viewer/main.js`(10.9MB)는 shiki와 문법 전량을 **번들 안에 품는다**. `dist/viewer/worker.js`(836KB)는 다르다 — shiki **엔진만** 들었고 문법은 없다(`worker.ts`가 `createHighlighterCore({ themes: [], langs: [] })`로 빈 채 뜨고, 문법은 `WorkerPoolManager`가 postMessage로 밀어넣는다). 10.9MB 대 836KB의 격차가 정확히 그 차이다. 실측: `grep -o 'source\.ts' dist/viewer/main.js | wc -l` → 298, 같은 명령이 `worker.js`에선 0. **`grep -c`는 쓰지 마라** — 미니파이 번들은 사실상 한 줄이라 줄 수를 세면 298이 1로 보인다. 뒤집으면 **새 런타임 import를 추가할 때 `dependencies`에 적을 곳이 없다** — 번들에 실제로 들어갔는지 `bun run build` 후 산출물에서 확인해야 하고, external로 남은 것은 설치 시점에 그냥 없다. 산출물은 `dist/cli.js` + `dist/viewer/{main.js,worker.js,index.html}` + `dist/skills/diffdeck/SKILL.md` 다섯이다.
 
 ### 렌더 패리티 하니스
 
@@ -132,7 +132,7 @@ cd scripts/parity && python3 -m http.server 8099 # http://127.0.0.1:8099/index.h
 - **라이선스**: 각 `packages/*/LICENSE`(Apache-2.0) + `packages/trees/NOTICE.md`(headless-tree MIT 유래) + 최상위 `NOTICE` 보존. 파일 수정 사실 고지 유지.
 - **`*.css?inline` ambient 선언**: 소비자(앱)의 tsconfig가 패키지 `src/**`를 glob include하지 않으면 안 보임 — Plan 2 앱 tsconfig에서 배선 필요.
 - **cc-statusline 잔재 데드코드 제거됨**: `server/ensure.ts`(spawn-if-not-running 데몬 ensure)와 `server.ts`의 `idleTimeoutMs` idle-shutdown을 제거했고, 뒤늦게 `config.ts`의 `isDiffViewerDisabled`/`DIFFDECK_DISABLE`도 지웠다(diffdeck에선 **호출부가 한 번도 없었다** — 유일한 참조가 자기 테스트라 커버리지 100%가 그대로 유지돼 게이트로는 원리적으로 안 드러났다. 커버리지 초록은 "쓰인다"는 증거가 아니다). diffdeck의 CLI는 서버를 **foreground**로 띄워 Ctrl+C로 종료하는 모델이라(cc-statusline처럼 statusline이 백그라운드 데몬을 spawn-if-not-running으로 관리하는 구조가 아님) 이 기능들이 전부 미사용이었다. 참고로 `server.ts`의 `idleTimeout: 120`(Bun.serve 소켓 타임아웃)은 제거된 idle-shutdown과 **다른 것**이고 지금도 살아 있는 계약이다 — "Loading…" 항목의 45+45 예산이 이 값에 걸린다.
-- **CLI 플래그를 바꾸면 문서 일곱이 같은 커밋에서 함께 움직인다.** `apps/viewer/cli/args.ts`(파싱)와 `cli.ts`의 `HELP`(단일 진실)에 플래그를 추가·변경·삭제하면, 그 표면을 사람에게 되풀이해 말하는 문서가 전부 따라와야 한다: `skills/diffdeck/SKILL.md`, `README.md`(루트), `apps/viewer/README.md`(**npm 패키지 페이지** — 루트 README와 별개 파일이다), `docs/README.{ko,ja,zh,es}.md` 넷. SKILL.md가 특별한 이유는 따로 있다 — `install-skill`이 `~/.claude/skills/`에 배포하고(`--codex` 시 `~/.agents/skills/`에도) Claude Code 플러그인이 `skills/`를 자동 스캔하는, **에이전트가 diffdeck를 구동할 때 읽는 유일한 문서**라 드리프트하면 에이전트가 존재하는 옵션을 모른 채 구동한다. `apps/viewer/__tests__/docs-flags-parity.test.ts`가 `HELP`의 Options 블록과 **일곱 문서 전부**를 대조한다. **이 게이트가 무엇을 증명하지 않는지 알 것**: 단방향이다 — `HELP`의 각 플래그가 문서에 있는지만 보므로 **플래그를 삭제하면 못 잡는다**(문서에 남은 유령 플래그는 통과한다). 그리고 `Options:` 블록만 읽으므로 `install-skill`의 `--codex`/`--project`는 아예 게이트 밖이다. 추가·변경만 자동으로 걸린다고 읽어라. **한 문서만 보는 게이트는 나머지를 지키지 않는다** — 예전엔 이 테스트가 SKILL.md만 봤고, 그 사이 `--fold-with-tree`가 npm README와 번역 4종에서 조용히 빠져 있었다. 경로가 그걸 잘 보여준다: 플래그를 만든 #14은 루트 README와 CLAUDE.md만 갱신했고, SKILL.md는 뒤늦게 #24(파리티 테스트를 만든 그 커밋)이 채웠다 — 즉 **게이트가 감시하는 문서만 따라잡혔고 나머지 다섯은 그대로 남았다.** 문서를 새로 추가하면 그 테스트의 `DOCS` 배열에도 넣어야 같은 함정을 다시 파지 않는다.
+- **CLI 플래그를 바꾸면 문서 일곱이 같은 커밋에서 함께 움직인다.** `apps/viewer/cli/args.ts`(파싱)와 `cli.ts`의 `HELP`(단일 진실)에 플래그를 추가·변경·삭제하면, 그 표면을 사람에게 되풀이해 말하는 문서가 전부 따라와야 한다: `skills/diffdeck/SKILL.md`, `README.md`(루트), `apps/viewer/README.md`(**npm 패키지 페이지** — 루트 README와 별개 파일이다), `docs/README.{ko,ja,zh,es}.md` 넷. SKILL.md가 특별한 이유는 따로 있다 — `install-skill`이 `~/.claude/skills/`에 배포하고(`--codex` 시 `~/.agents/skills/`에도) Claude Code 플러그인이 `skills/`를 자동 스캔하는, **에이전트가 diffdeck를 구동할 때 읽는 유일한 문서**라 드리프트하면 에이전트가 존재하는 옵션을 모른 채 구동한다. `apps/viewer/__tests__/docs-flags-parity.test.ts`가 `HELP`의 Options 블록과 **일곱 문서 전부**를 대조한다. **이 게이트가 무엇을 증명하지 않는지 알 것**: 단방향이다 — `HELP`의 각 플래그가 문서에 있는지만 보므로 **플래그를 삭제하면 못 잡는다**(문서에 남은 유령 플래그는 통과한다). 그리고 `Options:` 블록만 읽으므로 `install-skill`의 `--codex`/`--project`는 아예 게이트 밖이다. 추가·변경만 자동으로 걸린다고 읽어라. 그리고 **이 문서(CLAUDE.md)가 여덟 번째 플래그 기술처**인데 `DOCS`에 없다 — WHY 절이 뷰 토글 플래그만 열거하고 `--port`·`--no-open`은 안 다루므로 넣으면 그 둘에서 빨간불이 난다. 의도적 제외이니 "빠뜨렸다"고 보고 추가하지 마라. 대신 뷰 토글을 건드릴 때는 손으로 챙겨야 한다. **한 문서만 보는 게이트는 나머지를 지키지 않는다** — 예전엔 이 테스트가 SKILL.md만 봤고, 그 사이 `--fold-with-tree`가 npm README와 번역 4종에서 조용히 빠져 있었다. 경로가 그걸 잘 보여준다: 플래그를 만든 #14은 루트 README와 CLAUDE.md만 갱신했고, SKILL.md는 뒤늦게 #24(파리티 테스트를 만든 그 커밋)이 채웠다 — 즉 **게이트가 감시하는 문서만 따라잡혔고 나머지 다섯은 그대로 남았다.** 문서를 새로 추가하면 그 테스트의 `DOCS` 배열에도 넣어야 같은 함정을 다시 파지 않는다.
 - **`hidden`으로 숨기는 노드에 author `display`를 선언하면 `[hidden]{display:none}`을 반드시 짝지어라.** author origin이 UA 규칙을 이겨 영구 노출된다. `#grab-popover[hidden]`이 `display:flex` 뒤에 명시된 이유이고, 과거 `.grab-hint`에서 두 번째로 밟았다(지금은 `.grab-hint`가 sr-only라 `hidden`을 토글하지 않아 이 함정에서 벗어났다 — 규칙 자체는 `#grab-popover`에 그대로 유효하다). **happy-dom은 `textContent`만 보므로 유닛이 못 잡고 실브라우저에서만 드러난다** — 이런 실패는 e2e에서만 잡힌다.
 - 워커 로드 실패 폴백은 엔진이 아니라 앱 워치독이 담당한다(회귀망: worker-highlight.e2e.ts의 폴백 테스트).
 - **프로세스 cwd가 삭제되면 diffdeck 전체가 죽는다 — 그래서 `cli.ts`가 기동 직후 `/`로 이탈한다.** cwd가 unlink된 프로세스는 **자식 프로세스를 하나도 생성할 수 없다**(자식이 상속할 cwd를 커널이 해석하지 못한다). 이건 Bun Shell의 동작이 아니라 OS 제약이라 `.cwd(repo)`를 명시해도, 셸을 안 거치는 `Bun.spawn`을 써도 `ENOENT: posix_spawn`으로 똑같이 죽는다(실측) — **호출부에서 고칠 수 있는 방법이 없다.** 증상은 `/api/diff`가 **repo와 무관하게** 400 `not a git repository`를 내는 것이고, `/api/ping`(204)과 정적 페이지(200)는 서브프로세스를 안 띄워서 멀쩡하므로 "서버는 살아있는데 diff만 안 된다"로 오진하기 쉽다. 감별: 403이면 토큰/포트 문제고, 400이면서 repo를 바꿔도 동일하면 이 문제다. 장수 데몬(cc-statusline이 띄운다 — `/api/ping`의 pid 헤더 주석 참고)이 기동 시점의 worktree를 물고 있다가 그 worktree가 삭제되면 발생한다. 예방은 `cli.ts`가 `repo`를 읽은 **직후** `toSafeCwd()`로 이탈하는 것이고(순서가 계약이다 — 먼저 이탈하면 `repo`가 `/`가 된다), 자가회복은 `server.ts` 핸들러 진입부가 `repairCwd`가 주입된 경우에만(단축평가 — 없으면 `isCwdAlive` 호출 자체를 건너뛴다, `repairCwd`를 안 넘긴 임베드 호스트에게 감지 자체가 순수 비용이 되면 안 되기 때문이다) `isCwdAlive`로 감지해 그 `repairCwd`를 부르는 것이다. **감지는 반드시 `existsSync(process.cwd())`여야 한다** — `existsSync(".")`·`statSync(".")`는 unlink된 inode를 살려두는 cwd 파일 디스크립터 때문에 항상 true라 원리적으로 못 잡는다. `process.chdir()`이 프로세스 전역 부작용이라 라이브러리인 `startDiffServer`는 감지만 하고 복구는 프로세스를 소유한 `cli.ts`에서 주입받는다. (`cli.ts`는 서버를 띄운 직후 `prewarmDiff`(`server/prewarm.ts`)로 자기 서버의 `/api/diff`를 `working`·`base` **순차로** 두 번 호출해 payload 캐시를 데운다 — 브라우저가 뜨는 동안 첫 diff 빌드를 선실행시키는 best-effort 경로다. 동시 호출이 아닌 이유는 `BUILD_CONCURRENCY=8`이 호출당이라 두 모드를 겹치면 기동 직후 git 서브프로세스 버스트가 배로 뛰기 때문이고, 이는 아래 "Loading…" 항목의 재시도 1회 제한과 같은 근거다. 실패해도 뷰어는 정상 동작한다.) 회귀망: `daemon-cwd.e2e.ts`가 사용자에게 보이는 계약(기동 디렉토리가 삭제된 데몬이 다른 repo를 계속 서빙한다)을 종단 검증하는데, **예방과 자가회복을 구분하지는 못한다** — 둘 중 하나만 살아 있어도 통과하고 둘 다 없어야 400으로 빨간불이 된다(실측). 가드가 라우트 분기보다 먼저 돌아 첫 요청에서 git 호출 전에 cwd를 되살리기 때문이다. 기제별 격리는 유닛이 맡는다: `cli-run.test.ts`(예방 — 호출 순서와 주입), `diff-server.test.ts`(자가회복 4종 — 커버리지가 branch를 안 세므로 호출/미호출을 각각 찌르고, 나머지 둘은 단축평가로 감지가 건너뛰는 경로와 `cwdDeps` 생략 시 REAL_CWD_DEPS가 실제로 쓰이는 경로의 함수 커버리지를 찌른다), `diff-cwd.test.ts`(판정). 이후 git 호출 17곳 중 16곳은 `git -C ${repo}`로 repo를 조준하지만, 17번째인 `prBaseName`(`diff.ts:29-30`)은 `gh pr view`라 `-C`가 없고 `.cwd(repo)`로만 조준한다 — "전부 `-C`"로 읽으면 코드를 잘못 스캔하게 되지만, 결론(모두 repo를 명시적으로 조준하므로 cwd가 `/`여도 정상)은 그대로다. cwd 의존 지점이 하나 더 있다: `server.ts`의 `resolve(cfg.viewerDir)`는 chdir **이후**에 돌아 상대경로였다면 `/` 기준으로 풀리는데, 프로덕션 값(`${import.meta.dir}/viewer`)과 테스트(mkdtemp 절대경로)가 둘 다 절대경로라 현재 깨지는 건 없다. `/api/blob`의 경로 탈출 가드는 안전하다 — `getFileBytes`(`diff.ts:220-221`)가 `resolve(repo)`/`resolve(root, path)`로 가드를 세우고 실제 읽기는 `readFileSync(join(repo, path))`라 OS가 syscall 시점에 같은 cwd로 풀어 가드 기준과 읽기 기준이 함께 움직이므로 탈출 구멍이 열리지 않는다 — cwd가 조용히 바뀌며 보안 버그가 될 뻔했던 유일한 지점이라 기록해 둘 가치가 있다.
diff --git a/README.md b/README.md
index 1b6e69f..5336145 100644
--- a/README.md
+++ b/README.md
@@ -171,7 +171,7 @@ scripts/        source-map extraction tool, css-inline Bun plugin, render-parity
 docs/           README translations and screenshots
 ```
 
-Dependency graph: `path-store` (no deps) ← `trees`; `theming` (shiki) ← `diffs`, `trees`. Runtime externals: shiki + `@shikijs/*`, `diff`, `hast-util-to-html`, `lru_map`.
+Dependency graph: `path-store` (no deps) ← `trees`; `theming` (shiki) ← `diffs`, `trees`. Runtime externals: shiki + `@shikijs/*`, `diff`, `hast-util-to-html`, `lru_map` — these are the packages' own dependencies; the published CLI bundles everything, so nothing is resolved at install time.
 
 ## Development
 
diff --git a/apps/viewer/__tests__/docs-flags-parity.test.ts b/apps/viewer/__tests__/docs-flags-parity.test.ts
index 41a6c4b..6633c07 100644
--- a/apps/viewer/__tests__/docs-flags-parity.test.ts
+++ b/apps/viewer/__tests__/docs-flags-parity.test.ts
@@ -33,6 +33,18 @@ const extractOptionsFlags = (help: string): string[] => {
  * 문서에서 플래그는 항상 코드 스팬으로 적힌다: `--split` 또는 `--port <n>`.
  * 여는 백틱을 요구해 산문 속 우연한 일치를 막고, 뒤에 백틱이나 공백을 요구해
  * `--tree-right`가 가상의 `--tree-right-foo`에 매칭되지 않게 한다.
+ *
+ * 이 게이트의 한계를 알고 쓸 것 — 셋 다 실측으로 확인했다:
+ * 1. **단방향**이다. HELP의 각 플래그가 문서에 있는지만 본다. 플래그를
+ *    삭제하면 문서에 남은 유령 플래그가 그대로 통과한다.
+ * 2. **언급**을 증명하지 실제 **위치**를 증명하지 않는다. 표의 행을 지우고
+ *    같은 코드 스팬을 산문 한 줄로 옮겨도 통과한다. 그래도 표 문법에
+ *    앵커를 걸지 않는 건, 번역 4종의 컬럼 폭이 제각각이고 SKILL.md는
+ *    애초에 표가 아니라서다 — 앵커를 걸면 게이트가 먼저 부서진다.
+ * 3. `Options:` 블록만 읽는다. `install-skill`의 `--codex`·`--project`는
+ *    Commands 섹션이라 이 게이트 밖이다.
+ * 무는 곳은 확실히 문다: 번역에서 행 하나를 지우면 그 문서만 빨간불이 되고,
+ * HELP에 새 플래그를 넣으면 일곱 문서가 한꺼번에 빨간불이 된다.
  */
 const documents = (content: string, flag: string): boolean =>
 	new RegExp(`\`${flag}[\`\\s]`).test(content);
@@ -49,10 +61,13 @@ describe("CLI flag parity between cli.ts HELP and every doc that lists flags", (
 		expect(flags).not.toContain("--version");
 	});
 
+	// 파일 읽기는 test 콜백 **안**에서 한다. describe 본문에서 읽으면 경로가
+	// 하나만 틀려도 테스트가 등록되기 전에 throw해서, "문서 X가 없다"가 아니라
+	// 정체불명의 수집 크래시로 보인다 — 위 가드 두 개조차 돌지 않는다.
 	for (const doc of DOCS) {
-		const content = readFileSync(join(repoRoot, doc), "utf8");
 		for (const flag of flags) {
 			test(`${doc} documents ${flag}`, () => {
+				const content = readFileSync(join(repoRoot, doc), "utf8");
 				expect(documents(content, flag)).toBe(true);
 			});
 		}
diff --git a/docs/README.es.md b/docs/README.es.md
index 7610d7d..b4ee03b 100644
--- a/docs/README.es.md
+++ b/docs/README.es.md
@@ -161,7 +161,7 @@ scripts/        herramienta de extracción de source maps, plugin de Bun css-inl
 docs/           traducciones del README y capturas de pantalla
 ```
 
-Grafo de dependencias: `path-store` (sin dependencias) ← `trees`; `theming` (shiki) ← `diffs`, `trees`. Externals en runtime: shiki + `@shikijs/*`, `diff`, `hast-util-to-html`, `lru_map`.
+Grafo de dependencias: `path-store` (sin dependencias) ← `trees`; `theming` (shiki) ← `diffs`, `trees`. Externals en runtime: shiki + `@shikijs/*`, `diff`, `hast-util-to-html`, `lru_map` — son dependencias de los propios paquetes; la CLI publicada lo empaqueta todo, así que no se resuelve nada al instalar.
 
 ## Desarrollo
 
diff --git a/docs/README.ja.md b/docs/README.ja.md
index 8f149ab..0f4c686 100644
--- a/docs/README.ja.md
+++ b/docs/README.ja.md
@@ -161,7 +161,7 @@ scripts/        source-map extraction tool, css-inline Bun plugin, render-parity
 docs/           README translations and screenshots
 ```
 
-依存関係グラフ: `path-store`(依存なし)← `trees`、`theming`(shiki)← `diffs`, `trees`。ランタイムの外部依存: shiki + `@shikijs/*`、`diff`、`hast-util-to-html`、`lru_map`。
+依存関係グラフ: `path-store`(依存なし)← `trees`、`theming`(shiki)← `diffs`, `trees`。ランタイムの外部依存: shiki + `@shikijs/*`、`diff`、`hast-util-to-html`、`lru_map` — これらはパッケージ自身の依存であり、配布される CLI はすべてバンドルするため、インストール時に解決されるものはありません。
 
 ## 開発
 
diff --git a/docs/README.ko.md b/docs/README.ko.md
index 4c04042..a667694 100644
--- a/docs/README.ko.md
+++ b/docs/README.ko.md
@@ -161,7 +161,7 @@ scripts/        source-map extraction tool, css-inline Bun plugin, render-parity
 docs/           README translations and screenshots
 ```
 
-의존성 그래프: `path-store`(의존성 없음) ← `trees`; `theming`(shiki) ← `diffs`, `trees`. 런타임 외부 의존성: shiki + `@shikijs/*`, `diff`, `hast-util-to-html`, `lru_map`.
+의존성 그래프: `path-store`(의존성 없음) ← `trees`; `theming`(shiki) ← `diffs`, `trees`. 런타임 외부 의존성: shiki + `@shikijs/*`, `diff`, `hast-util-to-html`, `lru_map` — 패키지들 자신의 의존성이며, 배포되는 CLI는 전부 번들하므로 설치 시점에 resolve되는 것은 없습니다.
 
 ## 개발
 
diff --git a/docs/README.zh.md b/docs/README.zh.md
index d2b1cee..90044f6 100644
--- a/docs/README.zh.md
+++ b/docs/README.zh.md
@@ -161,7 +161,7 @@ scripts/        source-map extraction tool, css-inline Bun plugin, render-parity
 docs/           README translations and screenshots
 ```
 
-依赖关系图：`path-store`（无依赖）← `trees`；`theming`（shiki）← `diffs`、`trees`。运行时外部依赖：shiki + `@shikijs/*`、`diff`、`hast-util-to-html`、`lru_map`。
+依赖关系图：`path-store`（无依赖）← `trees`；`theming`（shiki）← `diffs`、`trees`。运行时外部依赖：shiki + `@shikijs/*`、`diff`、`hast-util-to-html`、`lru_map`——这些是各包自身的依赖；发布的 CLI 会全部打包，因此安装时不会解析任何依赖。
 
 ## 开发