oh-my-design-cli 1.8.7 → 1.9.0

package/skills/omd-init/SKILL.md

@@ -7,7 +7,7 @@ description: "프로젝트 루트에 DESIGN.md를 부트스트랩 — 실제 기
 
 프로젝트에 DESIGN.md + AI 코딩 에이전트용 shim 3종을 한 번에 세팅. 레퍼런스 톤&매너는 **preserve**하고, 사용자 프로젝트 맥락은 controlled-vocabulary delta_set으로만 반영.
 
-**CLI 호출 없음** — Read/Write/Bash(파일 작업만) 툴로 직접 처리. (이전 버전은 `omd init recommend` 등 CLI subcommand를 호출했으나 현재 CLI binary는 `install-skills`만 노출. 이 skill은 self-contained하게 동작.)
+**런타임 CLI subcommand 호출 없음** — Read/Write/Bash(파일 작업만) 툴로 직접 처리한다. CLI의 사용자 표면은 bare `npx oh-my-design-cli`(대화형 installer)와 `npx oh-my-design-cli doctor`(설치 진단)이며, `omd init recommend` 같은 init subcommand는 제공하지 않는다. 이 skill은 설치 뒤 host agent 안에서 self-contained하게 동작한다.
 
 ## 전체 플로우
 
@@ -38,15 +38,19 @@ Phase 7: 요약 출력
 
 다음 파일을 Read 툴로 전체 로드 (있는 순서대로 fallback):
 
-1. `.claude/data/reference-fingerprints.json` (사용자 프로젝트에 설치된 카탈로그 — 표준 경로)
-2. `node_modules/oh-my-design-cli/data/reference-fingerprints.json` (npm 설치 직접 경로)
-3. `data/reference-fingerprints.json` (개발 환경)
+1. `.codex/data/reference-fingerprints.json` (Codex 설치 카탈로그)
+2. `.claude/data/reference-fingerprints.json` (Claude Code / Cursor 설치 카탈로그)
+3. `.opencode/data/reference-fingerprints.json` (OpenCode 설치 카탈로그)
+4. `node_modules/oh-my-design-cli/data/reference-fingerprints.json` (npm 설치 직접 경로)
+5. `data/reference-fingerprints.json` (개발 환경)
 
 스키마: `{ count, items: [{ id, primary_color_hex, category, visual_theme, voice_fingerprint, tone_keywords, antipatterns, signature_motion, has_personas, category_raw }] }`.
 
 추가 보조 파일 (있으면 같이 로드):
-- `.claude/data/vocabulary.json` — controlled vocab axes/keywords
-- `.claude/data/reference-tags.md` — human-readable keyword matrix
+- 위에서 실제 선택된 data dir의 `vocabulary.json` — controlled vocab axes/keywords
+- 같은 data dir의 `reference-tags.md` — human-readable keyword matrix
+
+채널을 알 수 있으면 해당 채널 data dir을 우선 사용하되, 파일이 없으면 위 1→5 순서로 fallback한다. 서로 다른 설치 채널의 fingerprint와 보조 파일을 섞지 말 것.
 
 ### 2.2 task 분석 (silent, in-head)
 
@@ -126,12 +130,14 @@ Phase 4.2~6은 건너뛴다.
 
 <!-- omd:catalog-resolution-order — omd-harness/omd-reference-capture SKILL.md + agents/omd-master.md 와 동일 순서 강제. drift guard: test/unit/core/catalog-resolution-order.test.ts -->
 
-1. `.claude/data/references/<id>/DESIGN.md` (installer가 복사 — npx 설치 기본 경로)
-2. `node_modules/oh-my-design-cli/web/references/<id>/DESIGN.md` (로컬 npm 설치 직접 경로)
-3. `web/references/<id>/DESIGN.md` (개발 레포)
-4. `https://oh-my-design.kr/<id>/design.md` 를 fetch (WebFetch 또는 `curl -fsSL`) — 1~3 로컬 경로가 전부 없을 때 (npx 설치가 기본 경로라 흔한 상황). 200이면 응답 본문이 곧 reference DESIGN.md다. 가져온 내용을 `.claude/data/references/<id>/DESIGN.md`로 저장해 다음 실행부터는 로컬 캐시(경로 1)로 잡히게 한다.
+1. `.codex/data/references/<id>/DESIGN.md` (Codex installer가 복사)
+2. `.claude/data/references/<id>/DESIGN.md` (Claude Code / Cursor installer가 복사)
+3. `.opencode/data/references/<id>/DESIGN.md` (OpenCode installer가 복사)
+4. `node_modules/oh-my-design-cli/web/references/<id>/DESIGN.md` (로컬 npm 설치 직접 경로)
+5. `web/references/<id>/DESIGN.md` (개발 레포)
+6. `https://oh-my-design.kr/<id>/design.md` 를 fetch (WebFetch 또는 `curl -fsSL`) — 1~5 로컬 경로가 전부 없을 때. 200이면 응답 본문이 곧 reference DESIGN.md다. 가져온 내용은 **활성 채널의 첫 writable data dir** (`.codex/data`, `.claude/data`, `.opencode/data`) 아래 `references/<id>/DESIGN.md`에 저장한다. 채널을 판별할 수 없으면 1→3 중 먼저 존재하고 쓸 수 있는 dir을 사용하고, 모두 없으면 활성 host 채널 dir을 생성한다.
 
-4까지 전부 실패하면 **절대 DESIGN.md를 임의로 지어내지 말 것.** 사용자에게
+6까지 전부 실패하면 **절대 DESIGN.md를 임의로 지어내지 말 것.** 사용자에게
 "레퍼런스 `<id>` 원문을 찾지 못했어요 (오프라인이거나 카탈로그 미배포).
 네트워크 연결 후 재시도하거나 다른 레퍼런스를 골라주세요"라고 보고하고 종료.
 
@@ -311,4 +317,4 @@ Next:
 - 레퍼런스에 없는 section/heading을 추가하지 말 것.
 - `.omd/init-context.json`을 직접 편집할 때 schema 어기지 말 것.
 - DESIGN.md가 이미 있는데 백업 없이 덮어쓰지 말 것 (Phase 4.2 rename 절차 준수).
-- **존재하지 않는 CLI subcommand (`omd init recommend`, `omd init prepare`, `omd sync`)를 호출하지 말 것** — 현 CLI binary는 `install-skills`만 제공.
+- **존재하지 않는 CLI subcommand (`omd init recommend`, `omd init prepare`, `omd sync`)를 호출하지 말 것** — CLI는 bare installer와 `install-skills`, `doctor`만 제공한다.

package/skills/omd-locale-adapter/SKILL.md

@@ -1,124 +1,91 @@
 ---
 name: omd:locale-adapter
-description: "한국어 본문을 EN/JP/ZH-TW로 **번역이 아닌 adaptation**. 문화 레퍼런스 swap, JP honorific 정합, ZH-TW 번체 idiom. KR은 항상 source of truth. '다국어 적용', 'EN 버전 만들어줘', 'JP로 옮겨줘' 류 트리거."
-user-invocable: true
+description: "한국어 canonical 문서·UX copy를 EN/JA/ZH-CN/ZH-TW로 번역이 아니라 locale adaptation한다. thesis·사실·명령어는 보존하되 문장 순서, 주어, register, 제품 용어와 호흡은 각 언어에서 다시 쓴다. '다국어 적용', '영문/일문/간체/대만어 버전', 'locale 문서 만들어줘' 요청에 사용한다."
 ---
 
 # omd:locale-adapter
 
-KR 본문을 받아 EN/JP/ZH-TW로 **adapt**한다. 직역이 아니라 각 문화의 디자인 블로그 voice로 다시 쓴다.
+한국어 canonical의 뜻과 사실을 다른 언어에서 **같이 이해되게** 만든다. 문장 단위 대응표를 만들지 않는다. EN, JA, ZH-CN, ZH-TW는 서로 독립된 원고다.
 
-참조: Frontitude brand-voice translation model, LINE localization playbook.
+## 0. Source contract
 
-## 0. Source of truth
+- KO가 canonical이다. 다른 locale은 `source_revision` 또는 canonical content hash를 가진다.
+- KO가 바뀌면 파생 locale을 stale로 표시하고 변경된 의미 단위를 다시 adapt한다.
+- 공유하는 것은 thesis, 사실, 정보 계층, 명령, URL, 제품 동작이다.
+- 공유하지 않는 것은 문장 순서, 비유, 인사, 주어, 문장 길이, 문장부호, 설명용 용어다.
+- canonical에 없는 사실은 어떤 locale에도 추가하지 않는다.
 
-**KR이 canonical**. EN/JP/ZH-TW는 derivative. KR이 갱신되면 다른 locale도 무효화.
+## 1. Target locale
 
-## 1. 대상 locale별 룰
+### EN (`en`)
 
-### 1.1 EN (en)
+- 행동과 관찰 가능한 결과를 먼저 쓴다.
+- repeated `not X, but Y`, 3단 슬로건, 추상 찬사를 원문의 구조 그대로 옮기지 않는다.
+- 제품이 이미 쓰는 US/UK spelling을 유지한다.
+- 한국 서비스는 첫 등장에만 독자에게 필요한 짧은 설명을 붙인다.
 
-- Voice baseline: Stripe Press / Linear changelog / Vercel blog
-- 문장 길이: 15~25 words (KR 35~50자 ≈ EN 15~25 words)
-- 1인칭: "we" or "I" 자연스럽게
-- 문화 swap:
-  - "토스" → "Toss (Korea's leading fintech)" (첫 출현만)
-  - "당근" → "Karrot (a hyperlocal Korean marketplace)"
-  - 김치/돌잔치 등 강한 KR-only ref → 영미권 equivalent or 짧은 gloss
-  - "안녕하세요" 인사 → "Hi, I'm [name]." 또는 informal opener
-- 분량: KR 자수의 0.45~0.55 (영어가 짧음)
-- 헤더: KR 짧은 헤더 → EN은 좀 더 descriptive OK ("토스 느낌의 시작" → "What gives Toss its 'feel'")
+### JA (`ja`)
 
-### 1.2 JP (ja)
+- 설명문은 です・ます調를 기본으로 하고 같은 섹션에서 register를 섞지 않는다.
+- 필요 없는 `私たちは / あなたは`는 생략한다.
+- 제목은 짧게 쓰고 마침표를 붙이지 않는다.
+- `正本 / 実ルート / 強いプロンプト` 같은 직역 대신 `唯一の基準 / 実際の製品画面 / 作業依頼`처럼 뜻이 통하는 제품 용어를 쓴다.
 
-- Voice baseline: note.com デザイン カテゴリ, クックパッド開発者ブログ
-- 종결: です・ます 일관 (敬体)
-- 격식 register: 영미보다 한 단계 더 정중
-- 문화 swap:
-  - "토스" → "Toss (韓国最大級のフィンテック)"
-  - 한국 특유의 이웃문화 ref → 일본식 「ご近所」 비유
-  - 존경어/겸양어 자연스럽게 ("저는 ~한다고 생각해요" → "私は〜と考えています")
-- 분량: KR 자수의 0.85~1.0
-- 헤더: 한국어 짧은 헤더와 비슷한 호흡 ("토스 느낌の始まり")
-- 한자: 常用漢字 위주. 어려운 한자는 仮名 병기.
+### ZH-CN (`zh-CN`)
 
-### 1.3 ZH-TW (zh-tw)
+- 사용자-facing AI는 `AI 编程助手`, 기술 역할은 문맥에 따라 `智能体角色`로 구분한다.
+- `赋能 / 无缝 / 全新升级 / 打造闭环` 같은 찬사를 기능 설명 대신 쓰지 않는다.
+- `项目唯一设计依据 / 实际产品页面 / 可重复执行的检查 / 空状态`처럼 간결한 제품 용어를 쓴다.
+- 행동과 결과를 먼저 쓰고 영어 정보 순서를 복제하지 않는다.
 
-- Voice baseline: 數位時代, INSIDE 硬塞網
-- **번체** (簡体 금지). 「設計」「顯示」「優化」.
-- 문화 swap:
-  - "토스" → "Toss (南韓金融科技龍頭)"
-  - "당근" → "Karrot (南韓地區型二手交易平台)"
-  - 한국 idiom → 中華圈 idiom (가능한 경우)
-- 분량: KR 자수의 0.6~0.75
-- 인용부호: 「」 사용
-- 헤더: KR 짧은 헤더와 비슷한 호흡 (「Toss 給人的感覺，從何而來」)
+### ZH-TW (`zh-TW`)
 
-## 2. Adaptation 7단계 절차
+- ZH-CN의 글자를 번체로 바꾸지 않고 대만 제품 문체로 다시 쓴다.
+- `軟體 / 資訊 / 使用者 / 影片 / 預設 / 介面 / 專案 / 儲存 / 設定 / 登入 / 資料`를 우선한다.
+- 사용자-facing AI는 `AI 程式助理`, 저장소는 `程式碼儲存庫` 또는 `專案儲存庫`로 쓴다.
+- 일반 UI QA는 `檢查`, 규정·공식 audit만 `稽核`을 쓴다.
 
-1. KR canonical 본문 + 출간된 frontmatter 읽기
-2. 글 전체 thesis 한 줄로 추출 (locale 다 동일해야 함)
-3. 각 H2 섹션을 1개씩 옮김 — **문장 단위 직역 금지**, 단락 단위 의역
-4. 문화 ref 발견 시 위 swap 룰 적용 + 첫 출현에 gloss
-5. 인용/코드/URL/figure src는 그대로 보존
-6. 헤더 number 일관성 유지 (KR=5 H2면 다른 locale도 5)
-7. frontmatter `title_<locale>`, `subtitle_<locale>` 채우기
+세부 후편집 규칙은 설치된 `omd-humanize/references/locale-playbooks.md`에서 대상 locale만 읽는다.
 
-## 3. 보존 (절대 변경 금지)
+## 2. Adaptation workflow
 
-- 코드 블록 내부 (변수명, 함수명, 주석 영문 유지)
-- URL, 파일 경로
-- 사람 이름 / 회사명 (단, 첫 출현에 gloss는 OK)
-- figure src
-- frontmatter slug
-- 수치 / 통계
+1. KO canonical, frontmatter, DESIGN.md §10, 승인된 제품 용어를 읽는다.
+2. 문서의 thesis 1–3개와 보호 구간(수치·명령·URL·ID·인용·제품 동작)을 적는다.
+3. 문서 구조를 의미 단위로 나눈다. H2 개수는 정보 parity를 확인하는 보조 지표일 뿐 강제로 맞추지 않는다.
+4. target locale에서 사용자가 읽을 순서로 문단을 새로 구성한다.
+5. 문화 맥락이 없으면 첫 등장에만 짧게 설명한다. 등가 비유가 없으면 억지로 새 비유를 만들지 않는다.
+6. code, command, URL, path, slug, skill/agent ID를 원문과 대조한다.
+7. `omd:humanize`의 target-locale audit으로 번역투, locale 혼입, 기계적 구조를 검증한다.
+8. UI copy면 실제 locale route에서 줄바꿈, overflow, CTA 동작, aria label을 확인한다.
 
-## 4. 비전형 케이스
+## 3. Output metadata
 
-| 원문 | 대응 |
-|---|---|
-| KR 특유의 이모지 사용 패턴 (`ㅎㅎ`, `^^`) | EN/JP/ZH-TW에서 제거. 톤은 다른 방식으로 표현. |
-| 한자어 농담 | locale 등가 농담 없으면 그냥 의미만 유지하고 농담 톤 표시 |
-| `안녕하세요` 같은 의례 인사 | EN은 informal greeting, JP는 「こんにちは」, ZH-TW는 「大家好」 |
-| Toss/당근 같은 회사명 인지도 차이 | 첫 등장에서 1줄 gloss, 이후 그대로 |
+문서 파일에는 가능한 경우 아래를 기록한다.
 
-## 5. 출력 형식
-
-```
-content/posts/<slug>/index.ko.md    ← source
-content/posts/<slug>/index.en.md    ← this skill 생성
-content/posts/<slug>/index.ja.md
-content/posts/<slug>/index.zh-tw.md
-```
-
-각 파일 frontmatter에:
 ```yaml
-locale: en
+locale: ja
 source_locale: ko
-source_revision: <git sha of ko at time of adaptation>
+source_revision: <ko content hash or git sha>
 adapted_at: <ISO date>
 ```
 
-## 6. 품질 체크 (self-audit)
-
-각 locale 생성 후 writer가 직접 검증:
-- H2 카운트가 KR과 일치
-- 인용 / 통계 누락 0건
-- figure src 경로 일치
-- 분량이 위 1.x의 비율 범위
-- 첫 출현 회사명 모두 gloss 처리됨
-- 코드 블록 변경 0건
+코드 dictionary처럼 frontmatter가 없으면 locale manifest 또는 테스트 fixture에 같은 revision을 기록한다.
 
-미달 시 동일 locale 재작성 (orchestrator round 카운터 증가).
+## 4. Quality gate
 
-## 7. KR 갱신 시 staleness
+- 보호 구간 변경 0
+- 다른 locale의 사용자-facing 용어 혼입 0
+- 제거된 기능·섹션을 소개하는 stale copy 0
+- target locale에서 반복되는 기계적 대조·추상 찬사 cluster 0
+- UI route의 horizontal overflow와 잘린 label 0
+- canonical이 바뀌었는데 revision이 그대로인 파생 원고 0
 
-KR이 수정되면 EN/JP/ZH-TW의 `source_revision`이 outdated. orchestrator가 다시 호출. 부분 갱신 가능 (수정된 H2 섹션만 re-adapt).
+미달 locale만 다시 작업한다. 영어 원고나 ZH-CN 원고를 fallback으로 노출하지 않는다.
 
-## 8. Anti-patterns
+## 금지
 
-- ❌ Google Translate 톤 — 직역 흔적
-- ❌ KR-only ref를 그대로 둠 (예: "강남에서 일하는데" → 영어판에 그대로)
-- ❌ 분량 mismatch (EN이 KR과 같은 자수)
-- ❌ 헤더 number 불일치
-- ❌ KR 없이 EN을 먼저 작성 (KR=canonical 원칙 위배)
+- 영어 문장을 모든 locale object의 prose fallback으로 사용
+- ZH-TW가 ZH-CN prose를 상속
+- 단락별 1:1 직역, 문장 순서 강제, 길이 비율을 품질 점수로 사용
+- 고유명사를 알리기 위해 원문에 없는 시장 지위·성과를 추가
+- `fallback`, `shim`, `truth source`, `strong prompt` 같은 설명용 영어를 그대로 노출

package/skills/omd-orchestrator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: omd:orchestrator
-description: "멀티 에이전트 디자인 워크플로우 supervisor. omd-kr-writer, omd-locale-adapter, omd-designer-review, omd-final-qa, omd-codex-image를 routing. 2-round revision cap 유지. 블로그/컴포넌트/아티클 등 multi-role 작업에 트리거 ('블로그 글 작성', 'KR+EN 동시 발행', '디자인 리뷰 받고 다듬어줘')."
+description: "멀티 에이전트 디자인 워크플로우 supervisor. writer, locale adaptation, humanize, UI slop audit, designer review, final QA, image materialization을 routing한다. 2-round revision cap을 유지하며 다국어 문서·UI 개선·출간 준비처럼 여러 역할이 필요한 요청에 사용한다."
 user-invocable: true
 ---
 
@@ -17,7 +17,9 @@ omd v0.2 agent layer의 **supervisor**. 한 글/한 컴포넌트가 여러 speci
 | 역할 | subagent | 용도 |
 |---|---|---|
 | Writer | `omd-kr-writer` | 한국어 본문 작성. `preset_id` 인자로 voice 결정. |
-| Localizer | `omd-locale-adapter` | KR → EN/JP/ZH-TW **adaptation** (번역 아님) |
+| Localizer | `omd-locale-adapter` | KR → EN/JA/ZH-CN/ZH-TW **adaptation** (번역 아님) |
+| Copy finalizer | `omd-humanizer` | locale별 번역투·기계적 구조를 국소 수정하고 보호 구간 대조 |
+| Slop auditor | `omd-slop-auditor` | 실제 route의 context-free UI/copy cluster를 품질·취향과 분리해 감사 |
 | Visual reviewer | `omd-designer-review` | DESIGN.md 대비 typo/색/spacing/state 검수 |
 | Critic | `omd-final-qa` | Read-only rubric verdict. 2-round cap 강제. |
 | Image materializer | `omd-codex-image` | `<!-- omd:gen-image -->` 블록을 채널별로 실체화 (Codex native gen / asset-curator fallback / OpenCode user-queue) |
@@ -34,7 +36,9 @@ omd v0.2 agent layer의 **supervisor**. 한 글/한 컴포넌트가 여러 speci
 ```
 사용자 요청 도착
 ├─ "글 작성" 키워드 → Stage 1: omd-kr-writer
-├─ 다국어 요청 ("EN", "영문", "JP") → Stage 3 추가
+├─ "AI 티/번역투/문장이 기계적" → omd-humanizer
+├─ 다국어 요청 ("EN", "영문", "JA", "간체", "대만어") → Stage 3 + locale별 humanize 추가
+├─ "AI slop/템플릿 같음" → omd-slop-auditor → 수정은 omd:apply
 ├─ artifact 첨부 + "리뷰" → Stage 2부터 진입
 └─ "출간 ready" → Stage 4 final-qa로 직행
 ```
@@ -43,9 +47,11 @@ omd v0.2 agent layer의 **supervisor**. 한 글/한 컴포넌트가 여러 speci
 
 ```
 Stage 1  WRITE       omd-kr-writer  (preset=toss-tech-design)
+Stage 1h HUMANIZE    omd-humanizer  (KO 보호 구간 + 자연스러움 검증)
 Stage 2  REVIEW      omd-designer-review  (artifact + brand DESIGN.md)
 Stage 2r REVISION    omd-kr-writer  (review feedback 반영)  ← max 2 round
-Stage 3  LOCALIZE    omd-locale-adapter  (KR → EN/JP)
+Stage 3  LOCALIZE    omd-locale-adapter  (KR → EN/JA/ZH-CN/ZH-TW)
+Stage 3h HUMANIZE    omd-humanizer  (각 locale 독립 검증)
 Stage 4  CRITIC      omd-final-qa  (rubric, read-only)
 Stage 4r REVISION    omd-kr-writer  (final-qa feedback)  ← max 2 round (Stage 2와 별도 카운트)
 Stage 4i IMAGES      omd-codex-image  (`<!-- omd:gen-image -->` 블록 처리, 채널별 분기)
@@ -114,7 +120,7 @@ prior_review: null  # 또는 review report 경로
 
 ## 9. 병렬화 허용 케이스
 
-- KR이 PASS된 뒤 EN/JP/ZH-TW **localization은 병렬** (각각 다른 파일이라 conflict 없음)
+- KR이 PASS된 뒤 EN/JA/ZH-CN/ZH-TW **adaptation은 병렬** (각각 다른 파일이라 conflict 없음). ZH-TW는 ZH-CN을 상속하지 않는다.
 - DESIGN.md re-read는 stage마다 강제 (Anthropic best practice — memory hallucination 방지)
 
 ## 10. 종료 조건

package/skills/omd-reference-capture/SKILL.md

@@ -95,7 +95,12 @@ Phase 7: 사용자 요약 + 다음 단계 안내
 ## Phase 1 — 입력 검증
 
 사용자 요청에서 brand id 추출:
-- 명시 brand 이름 (한글/영문) → `.claude/data/reference-fingerprints.json` `items[].id` 매칭
+- 명시 brand 이름 (한글/영문) → 아래 순서에서 찾은 첫 `reference-fingerprints.json`의 `items[].id` 매칭:
+  1. `.codex/data/reference-fingerprints.json`
+  2. `.claude/data/reference-fingerprints.json`
+  3. `.opencode/data/reference-fingerprints.json`
+  4. `node_modules/oh-my-design-cli/data/reference-fingerprints.json`
+  5. `data/reference-fingerprints.json` (개발 레포)
 - 없으면 사용자에게 묻기: "어느 reference brand 자료를 가져올까요? (예: banksalad, toss, socar)"
 
 id가 카탈로그에 없으면 종료 + "X는 reference 카탈로그에 없어요. omd:init으로 추가 가능합니다."
@@ -106,19 +111,21 @@ id가 카탈로그에 없으면 종료 + "X는 reference 카탈로그에 없어
 
 <!-- omd:catalog-resolution-order — omd-init/omd-harness SKILL.md + agents/omd-master.md 와 동일 순서 강제. drift guard: test/unit/core/catalog-resolution-order.test.ts -->
 
-1. `.claude/data/references/<id>/DESIGN.md` (installer가 복사 — npx 설치 기본 경로; 디렉토리에는 **DESIGN.md만** 보장)
-2. `node_modules/oh-my-design-cli/web/references/<id>/DESIGN.md` (로컬 npm 설치 직접 경로 — 디렉토리에 _promo.json/_research.md 포함)
-3. `web/references/<id>/DESIGN.md` (개발 레포)
-4. `https://oh-my-design.kr/<id>/design.md` 를 fetch (WebFetch 또는 `curl -fsSL`) — 1~3 로컬 경로가 전부 없을 때. 200이면 본문이 곧 reference DESIGN.md. 가져온 내용을 `.claude/data/references/<id>/DESIGN.md`로 캐시해 다음부터는 로컬 캐시(경로 1)로 잡히게 한다.
+1. `.codex/data/references/<id>/DESIGN.md` (Codex installer copy; 디렉토리에는 **DESIGN.md만** 보장)
+2. `.claude/data/references/<id>/DESIGN.md` (Claude Code / Cursor installer copy; 디렉토리에는 **DESIGN.md만** 보장)
+3. `.opencode/data/references/<id>/DESIGN.md` (OpenCode installer copy; 디렉토리에는 **DESIGN.md만** 보장)
+4. `node_modules/oh-my-design-cli/web/references/<id>/DESIGN.md` (로컬 npm 설치 직접 경로 — 디렉토리에 _promo.json/_research.md 포함)
+5. `web/references/<id>/DESIGN.md` (개발 레포)
+6. `https://oh-my-design.kr/<id>/design.md` 를 fetch (WebFetch 또는 `curl -fsSL`) — 1~5 로컬 경로가 전부 없을 때. 200이면 본문이 곧 reference DESIGN.md. 가져온 내용은 **활성 채널의 첫 writable data dir** (`.codex/data`, `.claude/data`, `.opencode/data`) 아래 `references/<id>/DESIGN.md`에 저장한다. 채널을 판별할 수 없으면 1→3 중 먼저 존재하고 쓸 수 있는 dir을 사용하고, 모두 없으면 활성 host 채널 dir을 생성한다.
 
-`<refdir>` = resolve된 DESIGN.md가 있는 디렉토리 (tier 4로 fetch한 경우 캐시 후 `.claude/data/references/<id>/`). `_promo.json`/`_research.md`는 (1)/(4)에 없을 수 있으니, 없으면 (2)/(3)로 폴백하고 그래도 없으면 fingerprints 기반 추론으로 진행.
+`<refdir>` = resolve된 DESIGN.md가 있는 디렉토리 (tier 6 fetch면 위 규칙으로 정한 활성 채널 cache dir). `_promo.json`/`_research.md`는 installer copy나 network cache에 없을 수 있으니, 없으면 (4)/(5)로 폴백하고 그래도 없으면 fingerprints 기반 추론으로 진행.
 
 다음을 순서대로 시도:
 
 1. **homepage URL**:
    - `<refdir>/_promo.json`의 `logo_url`이 brand site면 거기서 도메인 추출
    - 없으면 `<refdir>/_research.md`에서 Tier 1 source URL grep
-   - 둘 다 없으면 `.claude/data/reference-fingerprints.json`의 `items[].category_raw` 기반으로 추론 — 마지막 수단
+   - 둘 다 없으면 Phase 1에서 channel-aware하게 resolve한 `reference-fingerprints.json`의 `items[].category_raw` 기반으로 추론 — 마지막 수단
 
 2. **logo URL** (`_promo.json` 우선):
    - `_promo.json.logo_url` → 그대로 사용
@@ -254,15 +261,57 @@ canonical DESIGN.md가 "BM JUA를 landing/promo accent로"라고 적어뒀더라
 
 mode=clone이면 omd:init/omd:harness가 생성 HTML `<head>`에 fonts.json의 `live_observed: true` 항목 `html_link`를 **반드시** 박는다. mode=inspired면 폰트 로드는 사용자 선택.
 
-## Phase 3.9 — Browser harness 자동 선택 (v1.3.6 신설)
+## Phase 3.9 — MCP-free evidence collector (v2)
 
-라이브 캡쳐 도구는 두 가지 옵션. 환경 detect 후 빠른 쪽 사용:
+라이브 캡쳐의 정본은 버전된 `ReferenceEvidenceBundle`이다. 에이전트가 매번 다른 evaluate 스니펫을 만들지 않는다.
+
+### 기본 경로: packaged/local collector
+
+개발 저장소 안에서는:
+
+```bash
+npm --prefix web run capture:reference -- <id-or-url> \
+  --max-routes 3 \
+  --out "$PWD/assets/_reference/<id>/evidence.json"
+```
+
+npm으로 설치된 스킬에서는:
+
+```bash
+# 현재 읽고 있는 SKILL.md와 같은 디렉토리의 bundled collector를 사용한다.
+# 예: .agents/skills/omd-reference-capture/scripts/capture-reference-evidence.mjs
+SKILL_DIR="<directory-containing-this-SKILL.md>"
+COLLECTOR="$SKILL_DIR/scripts/capture-reference-evidence.mjs"
+node "$COLLECTOR" "<homepage-url>" --id "<id>" \
+  --max-routes 3 \
+  --out "$PWD/assets/_reference/<id>/evidence.json"
+```
+
+설치된 collector는 Node 18에서 실행되는 단일 ESM 파일이며 `playwright-core`까지 내부에 포함한다. 따라서 프로젝트 `node_modules`, npm cache, TypeScript runtime에 의존하지 않고 system Chrome을 직접 사용한다. Chrome 경로가 표준 위치가 아니면 `OMD_CHROME_PATH`만 지정한다. MCP server, MCP SDK, 별도 API key는 필요 없다. 설치형 collector에는 항상 Phase 2에서 확정한 homepage URL과 `--id`를 함께 전달한다. 이 방식은 npm package가 일회성 `npx` cache에서 사라진 뒤에도 동작한다.
+
+현재 SKILL.md의 위치를 직접 알 수 없는 shell 환경에서는 아래 순서에서 첫 실행 파일을 찾는다:
+
+```bash
+for candidate in \
+  "$PWD/.claude/skills/omd-reference-capture/scripts/capture-reference-evidence.mjs" \
+  "$PWD/.agents/skills/omd-reference-capture/scripts/capture-reference-evidence.mjs" \
+  "$PWD/.opencode/skills/omd-reference-capture/scripts/capture-reference-evidence.mjs" \
+  "$HOME/.claude/skills/omd-reference-capture/scripts/capture-reference-evidence.mjs" \
+  "$HOME/.agents/skills/omd-reference-capture/scripts/capture-reference-evidence.mjs" \
+  "$HOME/.config/opencode/skills/omd-reference-capture/scripts/capture-reference-evidence.mjs"
+do
+  if [ -f "$candidate" ]; then COLLECTOR="$candidate"; break; fi
+done
+test -n "${COLLECTOR:-}" || { echo "capture_blocked: bundled collector not found"; exit 1; }
+```
+
+필수 산출물은 `evidence.json` 하나이며 schema version, surface URL, selector, computed style, FontFaceSet, `@font-face` source, interaction state, component fingerprint와 coverage를 포함한다. hover/focus/pressed는 state-specific computed snapshot으로 남고, 안전하게 열 수 있는 menu/dialog/form-error/tab/toast는 `interactions[]`의 trigger/target/state로 남는다. `tokens.json`, `.live-inspect-proof.json`, `structure.json`은 이 bundle의 하위 projection으로만 만든다.
 
 ### Fast-path: browser-harness (있으면 우선)
 
 `shutil.which("browser-harness")` 또는 `command -v browser-harness`로 detect. 있고 `browser-harness --doctor` 가 `[ok ] chrome running` 띄우면 fast-path:
 
-- **장점**: heredoc 단일 호출 + Chrome remote-debugging CDP 직접 → playwright MCP 대비 3-5x 빠름 (실측 3.5s/페이지). sub-agent의 "did live inspect" 거짓 보고 불가능 (heredoc 실행 자체가 evidence).
+- **용도**: 이미 로그인된 surface나 collector가 열지 못한 메뉴/모달을 보충한다. sub-agent의 "did live inspect" 보고 대신 실제 raw evidence를 남긴다.
 - **prerequisite**: Python 3.11+, uv 또는 pip, Chrome with `--remote-debugging-port=9222` 또는 `chrome://inspect#remote-debugging` 활성.
 - **호출 패턴**:
   ```bash
@@ -293,43 +342,47 @@ mode=clone이면 omd:init/omd:harness가 생성 HTML `<head>`에 fonts.json의 `
   capture_screenshot(path="<assets_dir>/screenshots/hero-desktop.png", full=False)
   PY
   ```
-- 결과를 `tokens.json#live_overrides` + `.live-inspect-proof.json` raw_samples에 그대로 박음.
+- 결과를 임의 JSON으로 끝내지 말고 `evidence.json`의 surface/state evidence와 동일한 필드로 reconcile한다. screenshot은 보조 자료이며 토큰 근거를 대신하지 않는다.
 
-### Fallback: playwright MCP (default)
+### Fallback: browser-harness only
 
-browser-harness 미설치면 `mcp__playwright__browser_navigate` + `browser_evaluate` + `browser_take_screenshot` 사용 (이전 버전 동작 그대로).
+packaged collector가 없고 browser-harness만 있으면 위 fast-path를 사용한다. 둘 다 없으면 live 검증을 했다고 주장하지 말고 `capture_blocked`를 기록한다. Playwright MCP로 fallback하지 않는다.
 
 ### 자동 선택 logic
 
 ```bash
-if command -v browser-harness >/dev/null && browser-harness --doctor 2>&1 | grep -q "ok.*chrome running"; then
-  echo "MODE=harness"
+if [ -f "web/scripts/capture-reference-evidence.ts" ]; then
+  echo "MODE=local-collector"
+elif [ -n "${COLLECTOR:-}" ] && [ -f "$COLLECTOR" ]; then
+  echo "MODE=packaged-collector"
+elif command -v browser-harness >/dev/null && browser-harness --doctor 2>&1 | grep -q "ok.*chrome running"; then
+  echo "MODE=harness-supplement"
 else
-  echo "MODE=playwright"
+  echo "MODE=capture-blocked"
 fi
 ```
 
 ### 사용자 안내 (선택)
 
 skill 진입 시 사용자에게 한 줄로 알림:
-> "browser-harness 감지됨 — fast-path 사용 (3.5s/page)" 또는 "playwright MCP 사용 — browser-harness 설치하면 3x 빠름: github.com/browser-use/browser-harness"
+> "MCP 없이 evidence collector로 N개 surface를 캡쳐합니다." 또는 "collector가 없어 live capture가 막혔습니다."
 
 이 안내는 informational only, 사용자 action 요구 X.
 
 ## Phase 4 — 토큰 캡쳐 (facts)
 
-**Proof gate (위반 = regression)**: 이 Phase는 실제 playwright navigate + computed style 추출이 일어났음을 후속 generator에게 증명하는 artifact를 남겨야 함. 이전 버전(v1.3.3)에서 sub-agent가 "라이브 inspect 했다"고 보고하지만 실제로는 canonical 값만 복사하는 결함이 관측됨. proof gate가 이를 차단:
+**Proof gate (위반 = regression)**: 이 Phase는 실제 navigation + computed style 추출이 일어났음을 `evidence.json`으로 증명해야 한다. 사람이 쓴 "라이브 inspect 했다" 문장은 증거가 아니다.
 
 ### 4.0 — `.live-inspect-proof.json` 작성 (REQUIRED, 이 파일 없으면 후속 generator는 live_overrides 무시)
 
-playwright `browser_navigate` 직후 `browser_evaluate`로 raw computed style 5개 이상 추출하고 결과를 `assets/_reference/<id>/.live-inspect-proof.json`에 저장:
+collector의 `evidence.json`에서 raw computed style 5개 이상을 projection해 `assets/_reference/<id>/.live-inspect-proof.json`에 저장한다:
 
 ```json
 {
   "navigated_at": "<ISO-8601 with seconds>",
   "source_url": "https://www.banksalad.com",
   "viewport": "1280x800",
-  "tool_used": "playwright_mcp_browser_evaluate",
+  "tool_used": "reference_evidence_collector_v1",
   "raw_samples": [
     { "element_selector": "body", "font-family": "Pretendard, ...", "color": "rgb(0, 0, 0)", "background": "rgba(0, 0, 0, 0)" },
     { "element_selector": "header nav a:first-child", "font-size": "14px", "font-weight": "500" },
@@ -337,19 +390,20 @@ playwright `browser_navigate` 직후 `browser_evaluate`로 raw computed style 5
     { "element_selector": ".hero-section section", "background-color": "rgba(0, 0, 0, 0)" },
     { "element_selector": "footer", "background-color": "rgb(255, 255, 255)" }
   ],
-  "playwright_response_hash": "<5+ char of returned evaluate result>"
+  "evidence_schema_version": 1,
+  "evidence_bundle": "./evidence.json"
 }
 ```
 
-후속 generator (omd:init / omd:harness)는 이 파일이 **존재하고 raw_samples 길이 ≥5** 이어야만 `tokens.json#live_overrides`를 신뢰. 파일 없거나 비어있으면 canonical만 사용.
+후속 generator (omd:init / omd:harness)는 `evidence.json`의 `schemaVersion === 1`, `surfaces.length >= 1`, raw element ≥5를 먼저 확인한다. legacy proof 파일만 있고 bundle이 없으면 canonical만 사용한다.
 
 ### 4.1 — drift detection (proof와 tokens.json#live_overrides 일관성)
 
-tokens.json의 `live_overrides` 값이 캡쳐된 canonical 값과 **byte-for-byte 동일**하면 live inspect가 실제로는 안 돈 것 → live_overrides 블록을 통째로 삭제하고 사용자에게 "live inspect 결과가 canonical과 동일 — 차이 없거나 inspect 실패. tokens.json#live_overrides 미사용."이라고 알림. metadata note만 적고 실제 hex override 없는 거짓 live_overrides 금지.
+`tokens.json#live_overrides`의 각 값은 bundle의 `surfaceId + selector + style property`로 역추적 가능해야 한다. canonical과 값이 같다는 이유만으로 실패 처리하지는 않지만, provenance가 없으면 override를 삭제한다.
 
 ### 4.2 — token 캡쳐 본문
 
-playwright MCP를 사용해 homepage에 navigate한 뒤 computed styles를 추출. 결과는 `assets/_reference/<id>/tokens.json`:
+`evidence.json`의 aggregate와 representative raw element를 reconcile한다. 결과는 `assets/_reference/<id>/tokens.json`:
 
 ```json
 {
@@ -385,7 +439,7 @@ playwright MCP를 사용해 homepage에 navigate한 뒤 computed styles를 추
 }
 ```
 
-inspect 패턴: 5-10 elements 샘플링 (`body` / `header nav` / hero CTA / card / `footer` 류 대표 element의 getComputedStyle 추출 — Phase 3.9의 JS 패턴과 동일한 방식). 캡쳐하려는 brand가 카탈로그에 없으면 웹 카탈로그(`oh-my-design.kr/design-systems`)에서 먼저 찾아보고, 카탈로그에 새 brand를 직접 추가하는 워크플로우(omd-add-reference)는 dev 레포(github.com/kwakseongjae/oh-my-design)에만 존재 — 배포본(npx 설치)에는 포함되지 않는다.
+최소 샘플은 `body` / heading / hero CTA / card 또는 form / footer이며, 각 샘플은 bundle selector를 보존한다. 캡쳐하려는 brand가 카탈로그에 없으면 URL을 직접 collector에 전달한다. 카탈로그에 신규 brand를 추가하는 워크플로우(omd-add-reference)는 dev 레포에만 존재한다.
 
 ## Phase 4.5 — 구조 cue 캡쳐 (structure.json)
 
@@ -505,7 +559,7 @@ structure.json에는 텍스트·이미지·copy·brand statement 일체 X. 오
 
 ### 5.2 Hero screenshot
 
-playwright `mcp__playwright__browser_take_screenshot`로 homepage 위 fold만 캡쳐:
+evidence collector와 같은 로컬 Playwright context 또는 browser-harness로 homepage 위 fold만 캡쳐(MCP 불필요):
 
 - viewport: 1280×800 (데스크탑 기본)
 - fullPage: **false** — 위 fold만