@design-ai/cli 4.56.0 → 4.57.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "design-ai",
-  "version": "4.56.0",
+  "version": "4.57.0",
   "description": "Senior product designer for any AI coding agent. 20 skills, 17 commands, 4 review agents covering UI/UX, website improvement, design systems, motion, illustration, print, video, game UI, conversational, and spatial design. Korean market depth.",
   "author": {
     "name": "Sungjin Park",
@@ -90,7 +90,7 @@
     {
       "name": "document-author",
       "path": "skills/document-author/SKILL.md",
-      "description": "Write technical / product documentation. Diátaxis-aware. Korean-aware."
+      "description": "Write technical / product documentation. Di\u00e1taxis-aware. Korean-aware."
     },
     {
       "name": "slide-deck-author",
@@ -120,12 +120,12 @@
     {
       "name": "game-ui-designer",
       "path": "skills/game-ui-designer/SKILL.md",
-      "description": "Spec game UI — HUD, menus, inventory, store. Korean conventions (확률 표시, 본인인증, PC bang)."
+      "description": "Spec game UI \u2014 HUD, menus, inventory, store. Korean conventions (\ud655\ub960 \ud45c\uc2dc, \ubcf8\uc778\uc778\uc99d, PC bang)."
     },
     {
       "name": "conversational-ui-designer",
       "path": "skills/conversational-ui-designer/SKILL.md",
-      "description": "Spec a conversational UI — voice, chatbot, AI chat. Korean conventions (해요체 / 합쇼체)."
+      "description": "Spec a conversational UI \u2014 voice, chatbot, AI chat. Korean conventions (\ud574\uc694\uccb4 / \ud569\uc1fc\uccb4)."
     },
     {
       "name": "spatial-designer",
@@ -134,29 +134,113 @@
     }
   ],
   "commands": [
-    { "name": "design-from-brief", "path": "commands/design-from-brief.md", "description": "Generate a complete design system from a one-paragraph product brief." },
-    { "name": "iterate", "path": "commands/iterate.md", "description": "Apply a critique to an existing artifact, produce a revision + changelog." },
-    { "name": "document-from-brief", "path": "commands/document-from-brief.md", "description": "Generate documentation from a brief." },
-    { "name": "slide-deck", "path": "commands/slide-deck.md", "description": "Generate a slide deck outline from a brief." },
-    { "name": "design-review", "path": "commands/design-review.md", "description": "Run UX audit + a11y review + design critique in parallel and combine." },
-    { "name": "website-improvement", "path": "commands/website-improvement.md", "description": "Plan a website improvement project with profile, audits, MCP readiness, prompts, and handoff." },
-    { "name": "palette-from-brand", "path": "commands/palette-from-brand.md", "description": "Generate a full palette from a brand input." },
-    { "name": "component-spec", "path": "commands/component-spec.md", "description": "Spec a single component using the component-spec-writer skill." },
-    { "name": "extract-tokens", "path": "commands/extract-tokens.md", "description": "Run the token extractor pipeline." },
-    { "name": "motion-design", "path": "commands/motion-design.md", "description": "Spec motion for a screen / component / page." },
-    { "name": "illustration", "path": "commands/illustration.md", "description": "Design or spec an illustration system or piece." },
-    { "name": "print", "path": "commands/print.md", "description": "Spec a print piece." },
-    { "name": "video", "path": "commands/video.md", "description": "Spec video for marketing, social, or in-product." },
-    { "name": "game-ui", "path": "commands/game-ui.md", "description": "Spec game UI." },
-    { "name": "conversational", "path": "commands/conversational.md", "description": "Spec a chatbot / voice / AI chat / live agent." },
-    { "name": "spatial", "path": "commands/spatial.md", "description": "Spec a VR / AR / MR / WebXR experience." },
-    { "name": "stability-review", "path": "commands/stability-review.md", "description": "Run the quarterly stability review report. Surfaces promotion candidates + stale files." }
+    {
+      "name": "design-from-brief",
+      "path": "commands/design-from-brief.md",
+      "description": "Generate a complete design system from a one-paragraph product brief."
+    },
+    {
+      "name": "iterate",
+      "path": "commands/iterate.md",
+      "description": "Apply a critique to an existing artifact, produce a revision + changelog."
+    },
+    {
+      "name": "document-from-brief",
+      "path": "commands/document-from-brief.md",
+      "description": "Generate documentation from a brief."
+    },
+    {
+      "name": "slide-deck",
+      "path": "commands/slide-deck.md",
+      "description": "Generate a slide deck outline from a brief."
+    },
+    {
+      "name": "design-review",
+      "path": "commands/design-review.md",
+      "description": "Run UX audit + a11y review + design critique in parallel and combine."
+    },
+    {
+      "name": "website-improvement",
+      "path": "commands/website-improvement.md",
+      "description": "Plan a website improvement project with profile, audits, MCP readiness, prompts, and handoff."
+    },
+    {
+      "name": "palette-from-brand",
+      "path": "commands/palette-from-brand.md",
+      "description": "Generate a full palette from a brand input."
+    },
+    {
+      "name": "component-spec",
+      "path": "commands/component-spec.md",
+      "description": "Spec a single component using the component-spec-writer skill."
+    },
+    {
+      "name": "extract-tokens",
+      "path": "commands/extract-tokens.md",
+      "description": "Run the token extractor pipeline."
+    },
+    {
+      "name": "motion-design",
+      "path": "commands/motion-design.md",
+      "description": "Spec motion for a screen / component / page."
+    },
+    {
+      "name": "illustration",
+      "path": "commands/illustration.md",
+      "description": "Design or spec an illustration system or piece."
+    },
+    {
+      "name": "print",
+      "path": "commands/print.md",
+      "description": "Spec a print piece."
+    },
+    {
+      "name": "video",
+      "path": "commands/video.md",
+      "description": "Spec video for marketing, social, or in-product."
+    },
+    {
+      "name": "game-ui",
+      "path": "commands/game-ui.md",
+      "description": "Spec game UI."
+    },
+    {
+      "name": "conversational",
+      "path": "commands/conversational.md",
+      "description": "Spec a chatbot / voice / AI chat / live agent."
+    },
+    {
+      "name": "spatial",
+      "path": "commands/spatial.md",
+      "description": "Spec a VR / AR / MR / WebXR experience."
+    },
+    {
+      "name": "stability-review",
+      "path": "commands/stability-review.md",
+      "description": "Run the quarterly stability review report. Surfaces promotion candidates + stale files."
+    }
   ],
   "agents": [
-    { "name": "design-critic", "path": "agents/design-critic.md", "description": "Senior-designer critique with focus on hierarchy, craft, decisions." },
-    { "name": "a11y-reviewer", "path": "agents/a11y-reviewer.md", "description": "WCAG 2.1/2.2 AA accessibility review." },
-    { "name": "component-architect", "path": "agents/component-architect.md", "description": "Component anatomy + API design review." },
-    { "name": "token-extractor", "path": "agents/token-extractor.md", "description": "Extract design tokens from raw source files." }
+    {
+      "name": "design-critic",
+      "path": "agents/design-critic.md",
+      "description": "Senior-designer critique with focus on hierarchy, craft, decisions."
+    },
+    {
+      "name": "a11y-reviewer",
+      "path": "agents/a11y-reviewer.md",
+      "description": "WCAG 2.1/2.2 AA accessibility review."
+    },
+    {
+      "name": "component-architect",
+      "path": "agents/component-architect.md",
+      "description": "Component anatomy + API design review."
+    },
+    {
+      "name": "token-extractor",
+      "path": "agents/token-extractor.md",
+      "description": "Extract design tokens from raw source files."
+    }
   ],
   "supports": {
     "claude-code": ">=1.0.0"

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 User-facing release notes for design-ai. Versions follow semver.
 
+## v4.57.0 — Local Retrieval Memory: Ranked Search and Optional Embeddings (2026-07)
+
+Ships the Phase 754 AI-learning retrieval work: a deterministic, zero-dependency local retrieval layer over the knowledge corpus and the local learning profile, plus an opt-in local embedding rerank backend. Defaults are unchanged — `search`, `route`, `prompt`, and `pack` behave exactly as before unless a new flag is passed — so this release is additive and backward-compatible. It also moves `refs/` source links behind generated reference pages and hardens the docs deploy against intermittent GitHub Pages failures.
+
+### Added
+- `design-ai index --build/--status/--verify`: an explicit-only local retrieval index (`~/.design-ai/index/`, `DESIGN_AI_INDEX_DIR` override) over `knowledge/`, `examples/`, `skills/`, `docs/`, `agents/`, `commands/`, and `learning.json`. The index files are derived, rebuildable cache artifacts that are never committed, packaged, or sent anywhere.
+- `design-ai search --ranked`: deterministic BM25-style ranked corpus search with fully ordered output. The default substring `search` is unchanged.
+- A shared lexical scorer behind `prompt --with-learning` / `pack --with-learning`, so learning-entry selection and ranked search rank with one auditable algorithm; `learn --eval` checkpoints now record a `ranker` field.
+- `prompt --with-recall` / `pack --with-recall`: retrieval-augment a prompt or pack with the most relevant shipped corpus knowledge files for the brief, ranked by the same deterministic lexical scorer (opt-in, `--recall-limit N` from 1 to 20, default 5). Default `prompt`/`pack` output is unchanged.
+- `design-ai learn --recall <query>`: a read-only view of what design-ai recalls for a query — the top corpus knowledge files and the top local learning entries, ranked by the same shared scorer, in one command. Mutates nothing.
+- Hangul-aware tokenization: Korean surface forms emit character bigrams alongside the whole token so stem and particle-attached queries converge (`버튼` now matches documents containing only `버튼을`).
+- `design-ai search --ranked --embeddings` and `index --build --embeddings [--provider …]`: an opt-in, local-only embedding rerank backend configured through `~/.design-ai/config.json`. It never runs by default, makes no network calls, ships no model, and degrades visibly to the lexical path on any absence, staleness, or provider failure (exit 0).
+- MCP `design_ai_search` gains the same opt-in `ranked` parameter as the CLI, and `design_ai_prompt` / `design_ai_pack` gain the same opt-in `withRecall` / `recallLimit` parameters — no new tools and no implicit index builds.
+- `design-ai workspace` reports retrieval-index readiness (unused / fresh / stale) alongside its existing learning-usage and eval-checkpoint freshness.
+
+### Changed
+- `refs/` source links in the corpus now resolve to generated reference pages under `docs/reference/` instead of the gitignored upstream mirror; the MkDocs refs-only warning baseline is now 0.
+- The retrieval index sidecar format is version 2, recording the resolved checkout path and learning-file identity so a different checkout that shares the per-machine index directory is treated as stale rather than silently trusted.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check`.
+- `npm run release:metadata`.
+- `npm run audit:strict`.
+- `git diff --check`.
+- Main-branch GitHub Actions (`Design-AI audit`, `Deploy doc site`) passed for the constituent Phase 754 commits.
+
+### Versions
+- `package.json` + `.claude-plugin/plugin.json`: 4.56.0 → 4.57.0.
+- `vscode-extension/package.json`: remains 0.4.1.
+
+### What this enables
+- Users get sharper, deterministic corpus and learning-context retrieval — including for Korean queries — with zero new dependencies and no behavior change unless they opt in with `--ranked`.
+- Teams that want semantic rerank can wire a local embedding provider without design-ai ever making a network call or shipping a model.
+- Maintainers can publish a retrieval-capable release whose new surfaces are covered by both packed-tarball and public-registry smoke.
+
 ## v4.56.0 — MCP Protocol Hardening and Published Client Evidence (2026-07)
 
 Hardened the local stdio MCP server that Claude Code, Codex, and other MCP clients use to call design-ai. This release turns malformed JSON-RPC envelopes, request ids, notifications, initialize params, and tool arguments into deterministic protocol errors before CLI execution, then refreshes evidence that the published npm MCP entrypoint and local Claude/Codex registrations work.

package/README.ko.md

@@ -12,7 +12,7 @@
 
 > **모델이 아니에요. 파인튜닝도 아니에요.** 디자인 전문 지식을 구조화한 코퍼스 + 에이전트가 바로 실행할 수 있는 지시문이에요. 범용 LLM을 이번 세션에서만큼은 시니어 디자이너로 바꿔주는 셈이에요.
 
-> **배포 상태, 2026-06-30 확인:** 로컬 `npm run release:check`는 통과했고 GitHub Pages 문서는 공개 URL에서 확인됐으며, GitHub Release `v4.55.0`, npm `@design-ai/cli@4.55.0`, VS Code Marketplace `sungjin.design-ai-vscode` publish가 확인됐어요. 자세한 내용은 [`docs/external-status.md`](docs/external-status.md)를 확인하세요.
+> **배포 상태, 2026-07-02 확인:** 로컬 `npm run release:check`는 통과했고, GitHub Pages 문서는 live 상태이며, GitHub Release `v4.56.0`과 npm `@design-ai/cli@4.56.0` publish 및 registry smoke가 확인됐어요. Homebrew formula는 `v4.56.0`에 pinning되어 있고, VS Code Marketplace에는 `sungjin.design-ai-vscode@0.4.1`이 공개되어 있어요. 자세한 내용은 [`docs/external-status.md`](docs/external-status.md)를 확인하세요.
 
 ## 한눈에 보는 커버리지
 
@@ -75,7 +75,7 @@ design-ai install
 /design-from-brief 프리랜서를 위한 한국 핀테크
 ```
 
-CLI 명령어: `design-ai install [--json]`, `update [--dry-run] [--json]`, `uninstall [--json]`, `status [--json]`, `list [skills|commands|agents] [--json]`, `route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N] [--explain] [--strict] [--json]`, `routes [--json]`, `prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--strict] [--json]`, `pack <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N] [--strict] [--json]`, `learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--backup|--redact|--verify|--diff|--restore|--restore-backups [--prune]|--import|--audit [--fix]|--curate|--stats|--usage|--signals [--strict]|--agent-backlog [--strict]|--propose-skills [--min-evidence N] [--review-file path] [--review-check|--apply-plan] [--strict]|--eval-template|--eval [--strict]|--forget id|--clear] [--json|--report|--patch|--review-template] [--out file]`, `check <artifact.md|--stdin|--examples> [--route id|--all-routes] [--issues-only] [--strict] [--learn [--yes] [--learning-file path]] [--json]`, `workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]`, `site <workspace.json|--stdin> [--strict] [--json|--mcp-check [--probes]|--mcp-plan [--probes] [--json]|--next-actions [--json]|--graph|--tasks|--bundle|--report|--prompts|--prompt id [--task id]] [--out file] | site <bundle-dir> --bundle-check [--json] | site <bundle-dir> --bundle-compare other-bundle-dir [--json] | site <bundle-dir> --bundle-handoff [--task id] [--json] | site <bundle-dir> --bundle-repair [--yes] [--json] [--out file] | site --init --name name --live-url url [--next-actions] [--out file] | site --init --name name --live-url url --bundle --out dir | site --from-intake file.md|--stdin [--json|--next-actions [--json]|--tasks|--bundle [--tasks] --out dir] [--out file] | site --intake-template [--language en|ko] [--json] [--out file] | site --sample [--out file] | site --prompt-list [--json]`, `examples [query|--route id] [--limit N] [--json]`, `search <query> [--dir kind] [--limit N] [--json]`, `show <file[:line]> [--lines N:M] [--context N] [--json]`, `audit [--strict] [--quiet] [--json]`, `doctor [--strict] [--json] [--fix]`, `mcp`, `version [--json]`, `help [command|--json]`.
+CLI 명령어: `design-ai install [--json]`, `update [--dry-run] [--json]`, `uninstall [--json]`, `status [--json]`, `list [skills|commands|agents] [--json]`, `route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N] [--explain] [--strict] [--json]`, `routes [--json]`, `prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--strict] [--json]`, `pack <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N] [--strict] [--json]`, `learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--recall query|--backup|--redact|--verify|--diff|--restore|--restore-backups [--prune]|--import|--audit [--fix]|--curate|--stats|--usage|--signals [--strict]|--agent-backlog [--strict]|--propose-skills [--min-evidence N] [--review-file path] [--review-check|--apply-plan] [--strict]|--eval-template|--eval [--strict]|--forget id|--clear] [--json|--report|--patch|--review-template] [--out file]`, `check <artifact.md|--stdin|--examples> [--route id|--all-routes] [--issues-only] [--strict] [--learn [--yes] [--learning-file path]] [--json]`, `workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]`, `site <workspace.json|--stdin> [--strict] [--json|--mcp-check [--probes]|--mcp-plan [--probes] [--json]|--next-actions [--json]|--graph|--tasks|--bundle|--report|--prompts|--prompt id [--task id]] [--out file] | site <bundle-dir> --bundle-check [--json] | site <bundle-dir> --bundle-compare other-bundle-dir [--json] | site <bundle-dir> --bundle-handoff [--task id] [--json] | site <bundle-dir> --bundle-repair [--yes] [--json] [--out file] | site --init --name name --live-url url [--next-actions] [--out file] | site --init --name name --live-url url --bundle --out dir | site --from-intake file.md|--stdin [--json|--next-actions [--json]|--tasks|--bundle [--tasks] --out dir] [--out file] | site --intake-template [--language en|ko] [--json] [--out file] | site --sample [--out file] | site --prompt-list [--json]`, `examples [query|--route id] [--limit N] [--json]`, `search <query> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider "cmd args"]] [--json]`, `index [--build|--status|--verify] [--json] [--embeddings [--provider "cmd args"]]`, `show <file[:line]> [--lines N:M] [--context N] [--json]`, `audit [--strict] [--quiet] [--json]`, `doctor [--strict] [--json] [--fix]`, `mcp`, `version [--json]`, `help [command|--json]`.
 
 자세한 내용은 [`docs/DISTRIBUTION.ko.md`](docs/DISTRIBUTION.ko.md)를 확인하세요.
 
@@ -171,13 +171,11 @@ design-ai는 한국 시장을 1순위로 만들어졌고, 글로벌 시장 패
 
 ## 상태
 
-전체 단계 로그는 [`docs/ROADMAP.md`](docs/ROADMAP.md), 현재 완료 범위는 [`docs/PRODUCT-READINESS.md`](docs/PRODUCT-READINESS.md)에서 확인하세요. 현재 **v4.55.0** (public registry Website Console smoke + public registry workspace restore-backups readiness + workspace learning restore-backups readiness + public registry learning restore/prune smoke + learning restore rollback backup pruning + learning restore rollback backup inventory + learning restore rollback backup + learning profile restore + learning profile diff + workspace curation report next actions + learning curation Markdown reports + workspace learning curation next actions + learning usage curation review + workspace learning usage readiness + workspace learning eval freshness guard + workspace sibling learning eval checkpoint auto-detection + shell-safe workspace learning eval commands + workspace learning eval-template hints + public registry learning eval template smoke + learning eval template generation + public registry workspace learning eval smoke + workspace learning eval readiness + local learning eval strict gate + local learning eval checkpoints + local learning usage report + usage sidecar + archive-first curation + website improvement target-repo handoff prompt + handoff bundle compare + fingerprint verification + bundle export + MCP action plan JSON export + MCP action plan export + readiness check + prompt template listing + task-selected prompt export + control tower + 90% component coverage).
+전체 단계 로그는 [`docs/ROADMAP.md`](docs/ROADMAP.md), 현재 완료 범위는 [`docs/PRODUCT-READINESS.md`](docs/PRODUCT-READINESS.md)에서 확인하세요. 현재 **v4.56.0**: public npm publish, provenance-backed GitHub Actions release, public registry smoke, Website Console MCP readiness, workspace learning restore/eval coverage, handoff bundle verification, 90%+ component coverage가 완료됐어요.
 
-핵심 디자인 컨설팅 워크플로우는 로컬 릴리스 기준으로 준비되어 있어요. 웹사이트 개선 컨트롤 타워는 [`docs/website-console/index.html`](docs/website-console/index.html) zero-dependency static Web App과 `website-improvement` route/skill/command로 제공되며, Site Profile, audit checklist, MCP readiness, refactor prompt, browser-local handoff evidence tracking, verified bundle evidence metadata, generated bundle contract verification, repair report `--out file` output-file persistence가 붙은 bundle repair preview/apply와 packed-tarball evidence preservation smoke coverage가 붙은 CLI/bundle evidence export, handoff report를 관리해요. 로컬 학습 선호도는 `design-ai learn`, preview-first starter profile bootstrap인 `learn --init`, 명시적 `learn --feedback` keep/improve/avoid guidance, local QA warn/fail 결과를 저장하는 명시적 `check --learn --yes` capture, `learning.json`과 skill 파일을 수정하지 않는 focused `learn --agent-backlog --report --out agent-backlog.md` agent backlog artifact와 반복 check-capture 신호를 후보 skill instruction delta로 바꾸고 `--report --out skill-proposals.md` Markdown review artifact, read-only `--review-file` decision join, `--patch --out skill-proposals.patch` unified diff handoff를 저장할 수 있는 preview-only `learn --propose-skills`, git / canonical repository remote와 metadata alignment / learning / 선택형 또는 sibling `--learning-usage` sidecar summary와 stale selected id 및 profile mismatch readiness warning / 선택형 `--learning-eval` checkpoint summary와 freshness metadata / sibling `learning-eval.json` checkpoint 자동 인식 / active learning profile이 checkpoint 생성 뒤 바뀌었거나 checkpoint metadata와 맞지 않을 때 freshness warning / learning usage/eval path가 들어가는 next-action command의 shell-safe quoting / learning profile audit 또는 usage sidecar drift가 있을 때 usage-aware `learn --curate --usage-file`로 이어지는 next-action / archive cleanup 전에 `learn --curate --report --out learning-curation-report.md`를 저장하도록 안내하는 workspace report next-action / 학습 profile에 entry가 있지만 checkpoint가 없을 때 `learn --eval-template` bootstrap next-action hint / release-script 상태를 한 번에 보고 `--strict` readiness gate로 실패 처리할 수 있는 read-only `design-ai workspace` dogfood readiness snapshot, Website Console JSON export에서 sample workspace 생성, `design-ai site --init` Website Console project init workspace coverage in installed-bin and one-shot paths, `design-ai site --init --bundle --out <dir>` Website Console init handoff bundle도 설치된 binary와 one-shot 경로에서 확인, prompt template listing, `--mcp-check` 기반 deterministic MCP readiness check와 `--mcp-check --probes` 기반 read-only MCP probe check, `--mcp-plan` 및 `--mcp-plan --probes` 기반 Markdown or JSON MCP action plan export, `--graph --json` 기반 portable workflow graph export, `--bundle --out` 기반 전체 handoff bundle export, `--bundle-check --strict --json` 기반 handoff bundle checksum 검증, bundle digest 검증, generated bundle contract 검증, `--bundle-compare --strict --json` 기반 handoff bundle 비교, `--bundle-handoff --strict --json` 기반 검증된 bundle digest에서 대상 repo handoff prompt 생성, `--bundle-repair --yes --json` 기반 local handoff bundle repair, refactor task generation, task 선택이 가능한 단일 prompt template export, Markdown report/prompt bundle 변환을 처리하는 `design-ai site`, 안전한 `--out` file output과 `--force` overwrite control을 지원하는 전체 portable `learn --backup --json` profile export, local profile 또는 portable JSON을 `--from-file` / `--stdin`으로 받아 공유 전 민감정보를 가리는 redacted `learn --redact --json` profile export, 비파괴 `learn --verify` import validation, 읽기 전용 `learn --diff` portable JSON profile comparison, portable backup에서 active profile을 교체하고 자동 rollback backup과 선택형 `--backup-file` path를 제공하는 preview-first `learn --restore`, sibling rollback backup inventory를 보여주는 읽기 전용 `learn --restore-backups`, 오래된 rollback backup을 preview-first로 정리하는 `learn --restore-backups --prune --keep N`, portable `learn --import` dry-run/confirmed profile merge, recency fallback 없이 matching preference와 selection reason을 확인하는 query-filtered `learn --list --explain` / `learn --export`, cleanup suggestion을 포함하는 읽기 전용 `learn --audit` / `learn --stats`, 로컬 prompt/pack usage sidecar 활동을 요약하는 읽기 전용 `learn --usage`, active profile에서 runnable checkpoint JSON을 만드는 `learn --eval-template`, deterministic local learning selection QA와 `--strict` failure gate 및 sanitized checkpoint metadata를 위한 읽기 전용 `learn --eval` checkpoint report, 안전한 `learn --audit --fix --dry-run` preview와 확인형 `--fix --yes` cleanup, duplicate/sensitive entry를 sibling archive JSON으로 보존하고 `learn --curate --report --out` Markdown audit trail과 profile mismatch, stale selected id, unused active entry advisory usage review를 제공하는 archive-first `learn --curate` preview/apply flow, brief-relevance ranking, category/limit 범위 지정, selection scoring metadata, audit summary가 붙고 raw brief 대신 selected entry id와 짧은 brief hash만 `learning.usage.json` sidecar에 남기는 선택형 `prompt`/`pack --with-learning`으로 사용할 수 있고, AI 모델 학습이나 fine-tuning은 여전히 현재 배포 범위 밖이에요.
+핵심 디자인 컨설팅 워크플로우는 로컬 릴리스 기준으로 준비되어 있어요. 웹사이트 개선 컨트롤 타워는 zero-dependency static Web App과 `website-improvement` route/skill/command로 제공되고, Site Profile, audit checklist, MCP readiness, refactor prompt, handoff evidence tracking, bundle export/verify/repair를 한 번에 다뤄요. 로컬 학습 선호도는 `design-ai learn`으로 관리해요 — profile bootstrap, feedback 캡처, 읽기 전용 signal registry, 반복 QA 신호에서 만드는 skill 제안, 그리고 backup/restore/curate/audit까지 전부 로컬에서만 동작하는 opt-in 기능이에요. AI 모델 학습이나 fine-tuning은 여전히 현재 배포 범위 밖이에요.
 
-`learn --signals`는 local learning audit, usage sidecar, route/prompt/pack/learning eval signal, check learning capture, deterministic agent development backlog, workspace readiness를 하나로 묶어 보여주는 읽기 전용 registry예요. `learn --agent-backlog --report --out agent-backlog.md`는 같은 deterministic backlog만 분리해서 JSON/Markdown artifact와 strict gate로 확인하는 focused read-only surface예요. `learn --signals --report --out learning-signals.md`는 같은 registry를 공유 가능한 Markdown handoff artifact로 저장하고, `learn --signals --strict`는 signal registry나 agent backlog가 warn/fail이면 non-zero로 종료하므로 내부 에이전트와 AI 디밸롭 상태를 로컬 gate로 확인할 수 있고, `learning.json` 수정이나 외부 AI API 호출은 하지 않아요.
-
-`learn --propose-skills`는 반복된 `check --learn --yes` 신호를 후보 skill, evidence sources, proposed instruction delta, verification command, risk level로 정리하는 preview-only 리포트예요. `--min-evidence N`으로 proposal 기준을 높이거나 낮출 수 있고, `--report --out skill-proposals.md`를 쓰면 실제 skill 편집 전에 reviewer-friendly Markdown artifact로 저장할 수 있어요. `--review-file skill-proposals.review.json`은 applied/rejected proposal decision을 읽기 전용으로 합쳐 strict proposal gate를 정리하고, `--review-file skill-proposals.review.json --review-check`은 현재 proposal이 review file로 닫히는지 read-only readiness check로 검증하며, `--review-file skill-proposals.review.json --apply-plan`은 accepted proposal을 수동 skill 편집 계획으로 바꾸지만 파일은 수정하지 않아요. `--review-template --out skill-proposals.review.json`은 현재 pending proposal id를 JSON review scaffold로 저장하며, `--patch --out skill-proposals.patch`는 unresolved proposal을 unified diff preview로 저장하지만 skill 파일은 수정하지 않아요. `--strict`를 붙이면 pending proposal 또는 upstream signal readiness 경고가 있을 때 non-zero로 종료하지만, 실제 skill 수정은 이 명령에서 수행하지 않아요.
+위 모든 기능이 정확히 어떤 명령과 플래그를 검증하는지 — `learn`, `site`, `workspace`의 모든 옵션 단위 상세 — 는 [`docs/RELEASE-GATES.ko.md`](docs/RELEASE-GATES.ko.md)에 정리되어 있어요.
 
 코퍼스는 v1.7부터 CI 검사를 통과해 왔고, 현재 8개 audit으로 운영돼요:
 - 프론트매터 유효성
@@ -194,31 +192,16 @@ main 브랜치의 모든 커밋에서 8개 모두 통과해요.
 ## 기여하기
 
 [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md)를 참고하세요. 기준:
-- 릴리스 PR 또는 태그 전에는 `npm run release:check`를 core gate로 실행해요. `npm test` CLI unit test, `npm run audit:strict` 8개 audit, `git diff --check` whitespace check, `npm run package:check` package contents check, `npm run release:metadata` release metadata check 및 release metadata JSON `product_readiness_checked: true` Product Readiness guard coverage, `npm run release:self-test` release self-test 검증, installed-bin과 one-shot `npm exec --package <tarball>` 경로를 포함한 `npm run package:smoke` packed-tarball smoke, `design-ai workspace --strict --json` workspace strict 실패/성공 readiness checks와 workspace `--learning-usage` sidecar summary와 workspace `--learning-eval` checkpoint summary와 freshness metadata와 `design-ai workspace` workspace learning restore-backups readiness 및 restore rollback backup inventory, `design-ai site --stdin --json` Website Console export validation, `design-ai site --stdin --next-actions --json --out file --force` Website Console next-action operator checklist `--out` file 저장 확인, `design-ai site --stdin --next-actions --out file --force` Website Console next-action human checklist `--out` file 저장 확인, `design-ai site --sample` Website Console sample workspace coverage, `design-ai site --intake-template` Website Console intake template coverage for JSON stdout, Markdown stdout, Markdown `--out`, JSON `--out`, and `--language ko` Korean JSON/Markdown plus Korean Markdown `--out` in installed-bin and one-shot paths, `design-ai site --from-intake` Website Console from-intake filled Markdown intake import coverage for workspace JSON stdout, stdin workspace JSON stdout, stdin next-actions JSON stdout, stdin next-actions JSON `--out` file output-file persistence, stdin next-actions human `--out` file output-file persistence, stdin workspace JSON `--out` file output-file persistence, workspace JSON `--out` file output-file persistence, from-intake task generation, stdin from-intake task JSON `--out` output-file persistence, from-intake task handoff bundle generation, stdin from-intake task handoff bundle generation, stdin handoff bundle generation, and from-intake handoff bundle generation in installed-bin과 one-shot paths, `design-ai site --init` Website Console project init workspace coverage in installed-bin and one-shot paths, `design-ai site --init --bundle --out <dir>` Website Console init handoff bundle도 설치된 binary와 one-shot 경로에서 확인, `design-ai site --prompt-list --json` Website Console prompt template listing, `design-ai site --stdin --mcp-check --json` Website Console MCP readiness 검증, `design-ai site --stdin --mcp-check --probes --json` Website Console MCP readiness probe JSON with `--out` file-write confirmation, shared MCP probe output-file smoke assertions, MCP check 내장 probe next-step commands, MCP check 내장 command 실행 smoke coverage 검증, `design-ai site --stdin --mcp-plan` Website Console MCP action plan 생성, `design-ai site --stdin --mcp-plan --probes` Website Console MCP probe action plan 생성, `design-ai site --stdin --mcp-plan --probes --json` Website Console MCP probe action plan JSON with `--out` file-write confirmation plus embedded MCP action plan probe output-file commands plus MCP action plan human report output command parity plus MCP action plan emitted human report command smoke coverage plus MCP action plan emitted check JSON command smoke coverage plus MCP action plan emitted self-archive command smoke coverage plus shared MCP action plan command mapping self-test coverage 생성, `design-ai site --stdin --graph --json` Website Console workflow graph 생성, `design-ai site --stdin --bundle --out <dir>` Website Console handoff bundle 생성, `design-ai site <bundle-dir> --bundle-check --strict --json` Website Console handoff bundle checksum 검증, bundle digest 검증, generated bundle contract 검증, `design-ai site <bundle-dir> --bundle-compare <other-bundle-dir> --strict --json` Website Console handoff bundle 비교와 bundle digest 비교 및 packed-tarball과 public-registry smoke에서 warning-state Website Console bundle-compare strict 경고 실패가 동일 warning bundle의 sameBundle true 유지와 strict에서 non-zero 종료를 보존하는지도 확인, `design-ai site <bundle-dir> --bundle-handoff --strict --json` Website Console 대상 repo handoff prompt와 검증된 handoff bundle digest, `design-ai site <bundle-dir> --bundle-repair --yes --json` Website Console bundle repair preview/apply drift recovery와 repair report `--out file` output-file persistence, 공용 repair guidance smoke helper, 공용 repair report assertion helper, `design-ai site --stdin --tasks` Website Console refactor task generation, `design-ai site --stdin --prompt codex-implementation --task task-homepage-cta` Website Console task-selected single prompt generation, human `design-ai version`과 JSON `design-ai version --json` machine-readable version metadata, `design-ai help` top-level help, `design-ai help --json` topic catalog with probe-capable Website Console site help usage, command alias help와 functional alias 출력, command-specific help topic 출력 및 shared Website Console site help topic example smoke assertions 및 `design-ai site website-workspace.json --next-actions --out website-next-actions.md` next-actions Markdown 도움말 예시 plus from-intake stdin help examples (`cat company-website-intake.ko.md | design-ai site --from-intake --stdin --out website-workspace.json --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --next-actions --out website-next-actions.md --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --tasks --out website-workspace.tasks.json --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --bundle --tasks --out website-handoff-bundle`) 검증, 세 가지 `list` catalog domain의 human/JSON 출력, human / JSON corpus discovery 출력, route JSON 출력, route catalog 출력, route stdin 입력, 명시적 `show --lines` 출력과 `route --explain` 출력 검증, unknown command failure, unknown help-topic failure, unknown list-domain failure, unknown search-dir failure, unknown route-id suggestion, unknown option suggestion, unknown value suggestion, numeric range failure 검증, prompt JSON 출력, prompt markdown 출력, prompt from-file 출력, prompt stdin 출력, pack JSON 출력, pack markdown 출력, pack from-file 출력, pack stdin 출력, prompt/pack 강제 `--out` overwrite 및 prompt/pack file-write confirmation, check examples 출력, check artifact 출력, check stdin 출력, check all-routes 출력, check learning capture output, human `design-ai audit --strict --quiet` 출력과 JSON `design-ai audit --strict --quiet --json` machine-readable repository-audit output, JSON `design-ai learn --feedback` output plus learn feedback `--out` file-write confirmation, JSON `design-ai learn --init` output, JSON `design-ai learn --backup` output, JSON `design-ai learn --redact` output, `design-ai learn --redact --from-file` output, `design-ai learn --redact --stdin` output, learn JSON `--out` file-write confirmation과 forced overwrite coverage, JSON `design-ai learn --verify` output과 learn verify `--out` file-write confirmation, JSON `design-ai learn --restore` preview/apply output과 learn restore `--out` file-write confirmation, learn restore rollback backup verification, learn restore `--backup-file` path coverage, design-ai learn --restore-backups restore rollback backup inventory coverage, design-ai learn --restore-backups --prune restore rollback backup pruning coverage, JSON `design-ai learn --import` dry-run/apply output과 learn import `--out` file-write confirmation, human / JSON `design-ai learn --stats` profile summary output과 learn stats `--out` file-write confirmation, query-filtered human learn list explanation and export JSON output, brief-relevant prompt/pack learning selection, prompt/pack learning usage sidecar recording, human / JSON `design-ai learn --usage` usage sidecar report plus learn usage `--out` file-write confirmation, human / JSON `design-ai learn --signals` learning signal registry plus `design-ai learn --signals --strict --json` strict gate plus learn signals `--out` file-write confirmation, human / JSON `design-ai learn --eval-template` checkpoint generation plus generated checkpoint strict validation, human / JSON `design-ai learn --eval` checkpoint report plus learn eval `--out` file-write confirmation plus learn eval `--strict` failure gate, human / JSON `design-ai learn --audit` cleanup suggestion output과 learn audit `--out` file-write confirmation, human `design-ai update --dry-run` output, `design-ai update --dry-run --json` machine-readable update plan, `design-ai doctor --strict` human diagnostics 출력, `design-ai doctor --json` machine-readable diagnostics 출력, human `design-ai install` 출력과 `design-ai install --json` machine-readable install lifecycle output, human `design-ai status` 출력과 JSON status, `design-ai status --json` machine-readable install-state output, human `design-ai uninstall` 출력과 `design-ai uninstall --json` machine-readable uninstall lifecycle output 검증을 한 번에 확인해요.
-- 같은 `npm run release:check` gate는 Website Console bundle `mcp-probes.json` saved-payload guard 단계를 package contents, release self-tests, packed-tarball smoke로 함께 보존해요.
-- 같은 `npm run release:check` gate는 Website Console bundle boundary metadata guard 단계도 bundle-check JSON/human and bundle-handoff JSON/prompt boundary metadata plus full `release:self-test` evidence recording through unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke와 함께 보존해요.
-- 같은 `npm run release:check` gate는 Product Readiness release policy full gate guard for Website Console bundle boundary metadata full `release:check` evidence도 unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, packed-tarball smoke와 함께 보존해요.
-- 같은 `npm run release:check` gate는 Product Readiness release policy full gate evidence guard도 unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, packed-tarball smoke와 함께 보존해요.
-- Packed-tarball smoke는 installed-bin과 one-shot `npm exec --package <tarball>` 경로에서 route eval, prompt eval, pack eval checkpoint output도 확인해요.
-- Packed-tarball smoke는 installed-bin과 one-shot `npm exec --package <tarball>` 경로에서 `design-ai learn --signals --report --out learning-signals.md` Markdown signal report, learn signals JSON `--out` file-write confirmation, `design-ai learn --agent-backlog --report --out agent-backlog.md` focused agent backlog Markdown report와 agent backlog JSON `--out` file-write confirmation, `design-ai learn --agent-backlog --strict --json` agent backlog strict gate, focused agent backlog readiness summaries, `optionalGapDetails` JSON field coverage, check index JSON field coverage, Markdown check index section coverage, check-capture optional-gap semantics도 확인해요. 이 smoke coverage는 optional refresh-only runbook selection reason도 보존해서 no-command agent backlog output이 refresh를 executable handoff command가 아닌 status metadata로 다루는지 확인해요.
-- Packed-tarball smoke는 installed-bin과 one-shot `npm exec --package <tarball>` 경로에서 `design-ai learn --propose-skills --min-evidence 3 --json` threshold skipping, learn skill proposals JSON `--out` file-write confirmation, `design-ai learn --propose-skills --report --out skill-proposals.md` Markdown review artifact, `design-ai learn --propose-skills --review-file skill-proposals.review.json --json` read-only review decision join, `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --json` read-only review-file readiness check, `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --report --out skill-proposal-review-check.md` read-only review-check Markdown report, `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --json` read-only accepted proposal apply plan, `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan` human apply-plan command contract summary와 `Command contract` section, `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --report --out skill-proposal-apply-plan.md` read-only apply-plan Markdown report, `design-ai learn --propose-skills --review-template --out skill-proposals.review.json` JSON review template, `design-ai learn --propose-skills --patch --out skill-proposals.patch` unified diff handoff, `design-ai learn --propose-skills --strict --json` expected-failure skill proposal readiness gate도 확인해요.
-- npm publish가 끝난 뒤에는 `npm run registry:smoke`로 공개 `npm exec --package` 설치 경로, human `design-ai version`과 JSON `design-ai version --json` machine-readable version metadata, `design-ai help` top-level help, `design-ai help --json` topic catalog with probe-capable Website Console site help usage, functional alias 출력, 세 가지 `list` catalog domain의 human/JSON 출력, human / JSON corpus discovery 출력, route JSON 출력, route catalog 출력, route stdin 입력, 명시적 `show --lines` 출력과 `route --explain` 출력 검증, unknown command failure, unknown help-topic failure, unknown list-domain failure, unknown search-dir failure, unknown route-id suggestion, unknown option suggestion, unknown value suggestion, numeric range failure 검증, prompt JSON 출력, prompt markdown 출력, prompt from-file 출력, prompt stdin 출력, pack JSON 출력, pack markdown 출력, pack from-file 출력, pack stdin 출력, prompt/pack 강제 `--out` overwrite 및 prompt/pack file-write confirmation, check examples 출력, check artifact 출력, check stdin 출력, check all-routes 출력, check learning capture output, human `design-ai audit --strict --quiet` 출력과 JSON `design-ai audit --strict --quiet --json` machine-readable repository-audit output, public registry JSON `design-ai learn --verify` output과 public registry learn verify `--out` file-write confirmation, public registry JSON `design-ai learn --backup` output과 public registry learn backup `--out` file-write confirmation, public registry human / JSON `design-ai learn --stats` profile summary output과 public registry learn stats `--out` file-write confirmation, human `design-ai update --dry-run` output, `design-ai update --dry-run --json` machine-readable update plan, `design-ai doctor --strict` human diagnostics 출력, `design-ai doctor --json` machine-readable diagnostics 출력, human `design-ai install` 출력과 `design-ai install --json` machine-readable install lifecycle output, human `design-ai status` 출력과 JSON status, `design-ai status --json` machine-readable install-state output, human `design-ai uninstall` 출력과 `design-ai uninstall --json` machine-readable uninstall lifecycle output을 확인해요.
-- Registry smoke는 공개 npm registry `design-ai workspace --strict --json` strict 실패/성공 readiness checks도 published package path에서 확인해요.
-- Registry smoke는 공개 npm registry `design-ai workspace --learning-eval learning-eval.json --strict --json` checkpoint summary와 freshness metadata, auto-detected learning usage sidecar summary도 published package path에서 확인해요.
-- Registry smoke는 공개 npm registry `design-ai workspace` workspace restore-backups readiness와 restore rollback backup inventory도 published package path에서 확인해요.
-- Registry smoke는 공개 npm registry `design-ai site` Website Console export validation, 공개 npm registry `design-ai site --stdin --next-actions --json` next-action operator checklist 계약 및 `mcpProbeCounts` probe count telemetry와 shared smoke assertion self-test coverage for Website Console next-actions MCP probe counts 및 공개 npm registry `design-ai site --stdin --next-actions --json --out file --force` next-action operator checklist `--out` file 저장 확인 및 공개 npm registry `design-ai site --stdin --next-actions --out file --force` next-action human checklist `--out` file 저장 확인, sample workspace, prompt template 목록, MCP readiness, MCP readiness probe, MCP readiness probe JSON with `--out` file-write confirmation plus shared MCP probe output-file smoke assertions plus embedded MCP check probe next-step commands plus executable embedded MCP check probe command smoke coverage plus human MCP check probe command guidance and output-file smoke coverage plus embedded MCP check probe human report output command, MCP action plan, MCP probe action plan, MCP probe action plan JSON with `--out` file-write confirmation plus embedded MCP action plan probe output-file commands plus MCP action plan human report output command parity plus MCP action plan emitted human report command smoke coverage plus MCP action plan emitted check JSON command smoke coverage plus MCP action plan emitted self-archive command smoke coverage plus shared MCP action plan command mapping self-test coverage, handoff bundle, bundle-check JSON/human and bundle-handoff JSON/prompt boundary metadata for deterministic-local, no-external-call, and no-target-repo-mutation handoff validation, bundle-check/compare/handoff `mcpProbeCounts` probe count telemetry plus package smoke self-test coverage for Website Console bundle MCP probe counts plus bundled Website Console `mcp-probes.json` saved probe evidence payload assertion instead of the full `site --mcp-check --probes --json` response, bundle-repair, refactor task 생성, task-selected prompt 생성도 published package path에서 확인해요.
-- Registry smoke는 public registry JSON `design-ai learn --feedback` output plus public registry learn feedback `--out` file-write confirmation, public registry `design-ai learn --feedback --from-file`, public registry `design-ai learn --feedback --stdin`, public registry JSON `design-ai learn --init` preview/apply output, public registry learn init duplicate-skip output도 확인해요.
-- Registry smoke는 public registry JSON `design-ai learn --restore` preview/apply output, public registry learn restore `--out` file-write confirmation, public registry learn restore rollback backup verification, public registry learn restore `--backup-file` path coverage, public registry `design-ai learn --restore-backups` restore rollback backup inventory coverage, public registry `design-ai learn --restore-backups --prune` restore rollback backup pruning coverage도 확인해요.
-- Registry smoke는 public registry JSON `design-ai learn --import` dry-run/apply output과 public registry learn import `--out` file-write confirmation과 public registry JSON `design-ai learn --redact` output, public registry `design-ai learn --redact --from-file`, public registry `design-ai learn --redact --stdin`, public registry learn redact `--out` file-write confirmation도 확인해요.
-- Registry smoke는 public registry human / JSON `design-ai learn --audit` cleanup suggestion output과 public registry learn audit `--out` file-write confirmation과 public registry `design-ai learn --audit --fix --dry-run` cleanup preview 및 confirmed apply output도 확인해요.
-- Registry smoke는 public registry query-filtered learn list explanation/export JSON output, public registry brief-relevant prompt/pack learning selection, prompt/pack learning usage sidecar recording, public registry prompt/pack --with-learning, public registry `design-ai learn --eval-template` checkpoint generation, public registry generated checkpoint strict validation도 확인해요.
-- Registry smoke는 public registry learning readiness Markdown report coverage도 확인해서 `design-ai learn --signals --report --out learning-signals.md`와 `design-ai learn --agent-backlog --report --out agent-backlog.md`가 published package path에서 `Readiness check index` section을 보존하는지 검증해요.
+- 릴리스 PR 또는 태그 전에는 `npm run release:check`를 core gate로 실행해요. 이 명령은 `npm test`(CLI unit test), `npm run audit:strict`(8개 audit 전부), `git diff --check`(whitespace 검사), `npm run package:check`(package contents 검사), `npm run release:metadata`(release metadata + Product Readiness guard), `npm run release:self-test`(release 자체 검증), `npm run package:smoke`(packed-tarball smoke — install, `site`, `workspace`, `learn`, help/version/audit 표면 전체를 installed-bin과 one-shot `npm exec --package <tarball>` 두 경로에서 확인)를 하나로 묶어요.
+- npm publish가 끝난 뒤에는 `npm run registry:smoke`로 같은 표면을 공개 `npm exec --package` 설치 경로에서 다시 확인해요.
 - 손으로 쓴 지식 파일은 `<!-- hand-written -->` 마커 사용.
 - 스킬 PLAYBOOK은 verification phase 체크리스트 포함.
 - 한국어 문자열은 한국어로 직접 작성 (기계 번역 금지).
 - 모든 검사 통과.
 - CI에 올리기 전 GitHub workflow와 가까운 로컬 검증이 필요하면 `npm run ci:local`을 실행하세요. `release:check`, Python syntax check, knowledge size budget, VS Code extension compile/unit test, MkDocs build, docs deployment workflow와 같은 MkDocs warning policy를 한 번에 확인해요. 이 정책은 non-`refs/` warning을 막고, refs-only warning도 승인된 baseline 이상 늘어나지 않게 제한해요.
 
+`release:check`, packed-tarball smoke, registry smoke가 정확히 어떤 명령과 플래그를 검증하는지 전체 목록은 [`docs/RELEASE-GATES.ko.md`](docs/RELEASE-GATES.ko.md)에 남겨뒀어요.
+
 ## 라이선스
 
 MIT. [LICENSE](https://github.com/sungjin9288/design-ai/blob/main/LICENSE) 참조.

package/README.md

@@ -12,7 +12,7 @@ A model-agnostic design knowledge base + skill system. Drop it in front of any A
 
 > **Not a model. Not a fine-tune.** A structured corpus of design expertise + agent-ready instructions that turn a general-purpose LLM into an expert.
 
-> **Distribution status, checked 2026-06-30:** local `npm run release:check` passes, GitHub Pages docs are live, GitHub Release `v4.55.0` is published, `@design-ai/cli@4.55.0` is public on npm with registry smoke coverage, and `sungjin.design-ai-vscode` is public on the VS Code Marketplace. See [`docs/external-status.md`](docs/external-status.md).
+> **Distribution status, checked 2026-07-02:** local `npm run release:check` passes, GitHub Pages docs are live, GitHub Release `v4.56.0` is published, `@design-ai/cli@4.56.0` is public on npm with registry smoke coverage, the Homebrew formula is pinned to `v4.56.0`, and `sungjin.design-ai-vscode@0.4.1` is public on the VS Code Marketplace. See [`docs/external-status.md`](docs/external-status.md).
 
 ## Coverage at a glance
 
@@ -75,7 +75,7 @@ Any available path installs all 20 skills, 17 commands, and 4 agents under `~/.c
 /design-from-brief Korean fintech for freelancers
 ```
 
-CLI commands: `design-ai install [--json]`, `update [--dry-run] [--json]`, `uninstall [--json]`, `status [--json]`, `list [skills|commands|agents] [--json]`, `route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N] [--explain] [--strict] [--json]`, `routes [--json]`, `prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--strict] [--json]`, `pack <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N] [--strict] [--json]`, `learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--backup|--redact|--verify|--diff|--restore|--restore-backups [--prune]|--import|--audit [--fix]|--curate|--stats|--usage|--signals [--strict]|--agent-backlog [--strict]|--propose-skills [--min-evidence N] [--review-file path] [--review-check|--apply-plan] [--strict]|--eval-template|--eval [--strict]|--forget id|--clear] [--json|--report|--patch|--review-template] [--out file]`, `check <artifact.md|--stdin|--examples> [--route id|--all-routes] [--issues-only] [--strict] [--learn [--yes] [--learning-file path]] [--json]`, `workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]`, `site <workspace.json|--stdin> [--strict] [--json|--mcp-check [--probes]|--mcp-plan [--probes] [--json]|--next-actions [--json]|--graph|--tasks|--bundle|--report|--prompts|--prompt id [--task id]] [--out file] | site <bundle-dir> --bundle-check [--json] | site <bundle-dir> --bundle-compare other-bundle-dir [--json] | site <bundle-dir> --bundle-handoff [--task id] [--json] | site <bundle-dir> --bundle-repair [--yes] [--json] [--out file] | site --init --name name --live-url url [--next-actions] [--out file] | site --init --name name --live-url url --bundle --out dir | site --from-intake file.md|--stdin [--json|--next-actions [--json]|--tasks|--bundle [--tasks] --out dir] [--out file] | site --intake-template [--language en|ko] [--json] [--out file] | site --sample [--out file] | site --prompt-list [--json]`, `examples [query|--route id] [--limit N] [--json]`, `search <query> [--dir kind] [--limit N] [--json]`, `show <file[:line]> [--lines N:M] [--context N] [--json]`, `audit [--strict] [--quiet] [--json]`, `doctor [--strict] [--json] [--fix]`, `mcp`, `version [--json]`, `help [command|--json]`.
+CLI commands: `design-ai install [--json]`, `update [--dry-run] [--json]`, `uninstall [--json]`, `status [--json]`, `list [skills|commands|agents] [--json]`, `route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N] [--explain] [--strict] [--json]`, `routes [--json]`, `prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--strict] [--json]`, `pack <brief|--from-file file|--stdin|--eval-template|--eval> [--out file] [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N] [--strict] [--json]`, `learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--recall query|--backup|--redact|--verify|--diff|--restore|--restore-backups [--prune]|--import|--audit [--fix]|--curate|--stats|--usage|--signals [--strict]|--agent-backlog [--strict]|--propose-skills [--min-evidence N] [--review-file path] [--review-check|--apply-plan] [--strict]|--eval-template|--eval [--strict]|--forget id|--clear] [--json|--report|--patch|--review-template] [--out file]`, `check <artifact.md|--stdin|--examples> [--route id|--all-routes] [--issues-only] [--strict] [--learn [--yes] [--learning-file path]] [--json]`, `workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]`, `site <workspace.json|--stdin> [--strict] [--json|--mcp-check [--probes]|--mcp-plan [--probes] [--json]|--next-actions [--json]|--graph|--tasks|--bundle|--report|--prompts|--prompt id [--task id]] [--out file] | site <bundle-dir> --bundle-check [--json] | site <bundle-dir> --bundle-compare other-bundle-dir [--json] | site <bundle-dir> --bundle-handoff [--task id] [--json] | site <bundle-dir> --bundle-repair [--yes] [--json] [--out file] | site --init --name name --live-url url [--next-actions] [--out file] | site --init --name name --live-url url --bundle --out dir | site --from-intake file.md|--stdin [--json|--next-actions [--json]|--tasks|--bundle [--tasks] --out dir] [--out file] | site --intake-template [--language en|ko] [--json] [--out file] | site --sample [--out file] | site --prompt-list [--json]`, `examples [query|--route id] [--limit N] [--json]`, `search <query> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider "cmd args"]] [--json]`, `index [--build|--status|--verify] [--json] [--embeddings [--provider "cmd args"]]`, `show <file[:line]> [--lines N:M] [--context N] [--json]`, `audit [--strict] [--quiet] [--json]`, `doctor [--strict] [--json] [--fix]`, `mcp`, `version [--json]`, `help [command|--json]`.
 
 See [`docs/DISTRIBUTION.md`](docs/DISTRIBUTION.md) for the full distribution guide.
 
@@ -213,9 +213,11 @@ Refresh refs/ on demand: `./tools/extractors/run-all.sh`.
 
 ## Status
 
-See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full phase log and [`docs/PRODUCT-READINESS.md`](docs/PRODUCT-READINESS.md) for the current completion boundary. Currently at **v4.55.0** (public registry Website Console smoke + public registry workspace restore-backups readiness + workspace learning restore-backups readiness + public registry learning restore/prune smoke + learning restore rollback backup pruning + learning restore rollback backup inventory + learning restore rollback backup + learning profile restore + learning profile diff + workspace curation report next actions + learning curation Markdown reports + workspace learning curation next actions + learning usage curation review + workspace learning usage readiness + workspace learning eval freshness guard + workspace sibling learning eval checkpoint auto-detection + shell-safe workspace learning eval commands + workspace learning eval-template hints + public registry learning eval template smoke + learning eval template generation + public registry workspace learning eval smoke + workspace learning eval readiness + local learning eval strict gate + local learning eval checkpoints + local learning usage report + usage sidecar + archive-first curation + website improvement target-repo handoff prompt + handoff bundle compare + fingerprint verification + bundle export + MCP action plan JSON export + MCP action plan export + readiness check + prompt template listing + task-selected prompt export + control tower + 90% component coverage).
+See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full phase log and [`docs/PRODUCT-READINESS.md`](docs/PRODUCT-READINESS.md) for the current completion boundary. Currently at **v4.56.0**: public npm publish, provenance-backed GitHub Actions release, public registry smoke, Website Console MCP readiness, workspace learning restore/eval coverage, handoff bundle verification, and 90%+ component coverage are complete.
 
-Core design consulting workflows are locally release-ready. The website improvement control tower is available as a zero-dependency static Web App at [`docs/website-console/index.html`](docs/website-console/index.html), plus a `website-improvement` route/skill/command for Site Profiles, audit checklists, MCP readiness, refactor prompts, browser-local handoff evidence tracking, CLI/bundle evidence export with verified bundle evidence metadata, generated bundle contract verification, bundle repair preview/apply with repair report `--out file` output-file persistence, and packed-tarball evidence preservation smoke coverage, and handoff reports. Local learning preferences are available through `design-ai learn`, starter profile bootstrap via preview-first `learn --init`, explicit `learn --feedback` keep/improve/avoid guidance, explicit `check --learn --yes` capture for local QA warning/failure results, read-only `learn --signals` registry reports that join learning audit, usage sidecar, eval signal files, check capture entries, deterministic agent development backlog actions, and workspace readiness without mutating `learning.json`, focused read-only `learn --agent-backlog` reports that expose only the local AI/agent next-action queue with JSON/Markdown output and strict gating, `learn --signals --report --out learning-signals.md` Markdown handoff artifacts, `learn --signals --strict` gating for warning/failing signal registry or backlog status, preview-only `learn --propose-skills` reports that convert repeated check-capture signals into candidate skill instruction deltas without editing skill files, adjustable `learn --propose-skills --min-evidence N` thresholds for stricter or faster local proposal review, read-only `learn --propose-skills --review-file skill-proposals.review.json` decision joins for applied/rejected proposal state, read-only `learn --propose-skills --review-file skill-proposals.review.json --review-check` review-file readiness checks for current proposals, read-only `learn --propose-skills --review-file skill-proposals.review.json --apply-plan` accepted proposal apply plans for manual skill edits, `--review-template --out skill-proposals.review.json` JSON decision scaffolds, `--report --out skill-proposals.md` Markdown review artifacts, preview-only `--patch --out skill-proposals.patch` unified diff handoffs for manual review, `learn --propose-skills --strict` gating when proposal review or upstream signal readiness is pending, read-only `design-ai workspace` dogfood readiness snapshots for git, canonical repository remote/metadata alignment, learning, optional or sibling `--learning-usage` sidecar summaries with stale selected-id/profile-mismatch readiness warnings, optional `--learning-eval` checkpoint summaries with freshness metadata, automatic sibling `learning-eval.json` checkpoint detection, checkpoint freshness warnings when the active learning profile changed after checkpoint generation or no longer matches checkpoint metadata, shell-safe learning usage/eval next-action commands for local paths, usage-aware `learn --curate --usage-file` next actions when learning profile audit or usage sidecar drift needs review, companion `learn --curate --report --out learning-curation-report.md` workspace report next actions before archive cleanup, eval-template bootstrap next-action hints when a clean learning profile has entries but no checkpoint, and release-script state with `--strict` readiness gating, `design-ai site` sample workspace generation, prompt template listing, deterministic MCP readiness checks through `--mcp-check`, opt-in read-only MCP probe checks through `--mcp-check --probes`, Markdown or JSON MCP action plan export through `--mcp-plan`, `--mcp-plan --probes`, and `--mcp-plan --probes --json`, portable workflow graph export through `--graph --json`, complete handoff bundle export through `--bundle --out`, handoff bundle checksum/fingerprint and generated contract verification through `--bundle-check --strict --json`, handoff bundle comparison through `--bundle-compare --strict --json`, target-repo handoff prompt generation from a verified bundle through `--bundle-handoff --strict --json`, local handoff bundle repair through `--bundle-repair --yes --json`, refactor task generation, single prompt template export with task selection, and validation/report/prompt generation from Website Console JSON exports, full portable `learn --backup --json` profile export with safe `--out` file output and `--force` overwrite control, redacted portable `learn --redact --json` profile export for sharing from the local profile or portable JSON via `--from-file` / `--stdin`, non-mutating `learn --verify` import validation, read-only `learn --diff` profile comparison against portable JSON, preview-first full-profile `learn --restore` replacement from portable backups with automatic rollback backup and optional `--backup-file` path, read-only `learn --restore-backups` inventory for sibling rollback backups, preview-first `learn --restore-backups --prune --keep N` cleanup for older sibling rollback backups, portable `learn --import` dry-run/confirmed profile merge, query-filtered `learn --list --explain` / `learn --export` inspection without recency fallback, read-only `learn --audit` cleanup suggestions / `learn --stats`, read-only `learn --usage` reports for local prompt/pack usage sidecar activity, runnable `learn --eval-template` checkpoint generation from the active profile, read-only `learn --eval` checkpoint reports for deterministic local learning selection QA with `--strict` failure gating and sanitized checkpoint metadata, safe `learn --audit --fix --dry-run` previews plus confirmed `--fix --yes` cleanup, archive-first `learn --curate` preview/apply flow for duplicate and sensitive learning entries plus `learn --curate --report --out` Markdown audit trails and advisory usage review hints for profile mismatch, stale selected ids, and unused active entries, and opt-in `prompt`/`pack --with-learning` with brief-relevance ranking, category/limit scoping, selection scoring metadata, learned-context audit summaries, and local `learning.usage.json` sidecar events that store selected entry ids plus a short brief hash instead of raw brief text; AI model training or fine-tuning remains outside the shipped scope.
+Core design consulting workflows are locally release-ready. The website improvement control tower ships as a zero-dependency static Web App plus a `website-improvement` route/skill/command, covering Site Profiles, audit checklists, MCP readiness, refactor prompts, handoff evidence tracking, and bundle export/verify/repair. Local learning preferences are available through `design-ai learn` — profile bootstrap, feedback capture, a read-only signals registry, skill-proposal generation from repeated QA signals, and full backup/restore/curate/audit tooling, all local-only and opt-in. AI model training or fine-tuning remains outside the shipped scope.
+
+Full assertion-level detail for every one of the surfaces above — including every `learn`, `site`, and `workspace` flag and what it verifies — lives in [`docs/RELEASE-GATES.md`](docs/RELEASE-GATES.md).
 
 The corpus has been audited under CI checks since v1.7. It currently runs 8 audits:
 - Frontmatter validity
@@ -232,31 +234,16 @@ All 8 pass on every commit to `main`.
 ## Contributing
 
 See [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md). The bar:
-- Run `npm run release:check` as the core gate before release PRs or tags. It covers `npm test` CLI unit tests, `npm run audit:strict` all 8 audits, `git diff --check` whitespace checks, `npm run package:check` package contents checks, `npm run release:metadata` release metadata checks with release metadata JSON `product_readiness_checked: true` Product Readiness guard coverage, `npm run release:self-test` release assertion self-tests (including audit runner exit-code and coverage timestamp preservation fixtures), and `npm run package:smoke` packed-tarball smoke for installed-bin plus one-shot `npm exec --package <tarball>` paths including `design-ai workspace --strict --json` workspace strict failure/success readiness checks plus workspace `--learning-usage` sidecar summaries and workspace `--learning-eval` checkpoint summaries with freshness metadata plus `design-ai workspace` workspace learning restore-backups readiness with restore rollback backup inventory, `design-ai site --stdin --json` Website Console export validation, `design-ai site --stdin --next-actions --json --out file --force` Website Console next-action operator checklist output-file persistence, `design-ai site --stdin --next-actions --out file --force` Website Console next-action human checklist output-file persistence, `design-ai site --sample` Website Console sample workspace coverage, `design-ai site --intake-template` Website Console intake template coverage for JSON stdout, Markdown stdout, Markdown `--out`, JSON `--out`, and `--language ko` Korean JSON/Markdown plus Korean Markdown `--out` in installed-bin and one-shot paths, `design-ai site --from-intake` Website Console from-intake filled Markdown intake import coverage for workspace JSON stdout, stdin workspace JSON stdout, stdin next-actions JSON stdout, stdin next-actions JSON `--out` file output-file persistence, stdin next-actions human `--out` file output-file persistence, stdin workspace JSON `--out` file output-file persistence, workspace JSON `--out` file output-file persistence, from-intake task generation, stdin from-intake task JSON `--out` output-file persistence, from-intake task handoff bundle generation, stdin from-intake task handoff bundle generation, stdin handoff bundle generation, and from-intake handoff bundle generation in installed-bin and one-shot paths, `design-ai site --init` Website Console project init workspace coverage in installed-bin and one-shot paths, `design-ai site --init --bundle --out <dir>` Website Console init handoff bundle coverage in package bin path and one-shot paths, `design-ai site --prompt-list --json` Website Console prompt template listing, `design-ai site --stdin --mcp-check --json` Website Console MCP readiness check, `design-ai site --stdin --mcp-check --probes --json` Website Console MCP readiness probe JSON with `--out` file-write confirmation plus shared MCP probe output-file smoke assertions plus embedded MCP check probe next-step commands plus executable embedded MCP check probe command smoke coverage plus human MCP check probe command guidance and output-file smoke coverage plus embedded MCP check probe human report output command, `design-ai site --stdin --mcp-plan` Website Console MCP action plan, `design-ai site --stdin --mcp-plan --probes` Website Console MCP probe action plan, `design-ai site --stdin --mcp-plan --probes --json` Website Console MCP probe action plan JSON with `--out` file-write confirmation plus embedded MCP action plan probe output-file commands plus MCP action plan human report output command parity plus MCP action plan emitted human report command smoke coverage plus MCP action plan emitted check JSON command smoke coverage plus MCP action plan emitted self-archive command smoke coverage plus shared MCP action plan command mapping self-test coverage, `design-ai site --stdin --graph --json` Website Console workflow graph export, `design-ai site --stdin --bundle --out <dir>` Website Console handoff bundle, `design-ai site <bundle-dir> --bundle-check --strict --json` Website Console handoff bundle check with SHA-256 checksum verification, bundle digest/fingerprint verification, and generated bundle contract verification, `design-ai site <bundle-dir> --bundle-compare <other-bundle-dir> --strict --json` Website Console handoff bundle compare with bundle digest comparison plus packed-tarball and public-registry smoke for warning-state Website Console bundle-compare strict failures where identical warning bundles keep `sameBundle: true` while exiting non-zero under `--strict`, `design-ai site <bundle-dir> --bundle-handoff --strict --json` Website Console target-repo handoff prompt from a verified bundle digest plus `--bundle-handoff --task task-content-quality --strict --json` task-selected bundle handoff, `design-ai site <bundle-dir> --bundle-repair --yes --json` Website Console bundle repair preview/apply drift recovery with repair report `--out file` output-file persistence, shared repair guidance smoke helpers, and shared repair report assertion helpers, `design-ai site --stdin --tasks` Website Console refactor task generation, `design-ai site --stdin --prompt codex-implementation --task task-homepage-cta` Website Console task-selected single prompt generation, human `design-ai version` and machine-readable version metadata from JSON `design-ai version --json`, `design-ai help` top-level help, the `design-ai help --json` topic catalog with probe-capable Website Console site help usage, command alias help and functional alias output, command-specific help topic output, shared Website Console site help topic example smoke assertions including the `design-ai site website-workspace.json --next-actions --out website-next-actions.md` next-actions Markdown help example plus from-intake stdin help examples (`cat company-website-intake.ko.md | design-ai site --from-intake --stdin --out website-workspace.json --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --next-actions --out website-next-actions.md --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --tasks --out website-workspace.tasks.json --force`, `cat company-website-intake.ko.md | design-ai site --from-intake --stdin --bundle --tasks --out website-handoff-bundle`), all three `list` catalog domains in human and JSON mode, human / JSON corpus discovery output, route JSON output, route catalog output, and route stdin input, explicit `show --lines` output and `route --explain` output, unknown command failure, unknown help-topic failure, unknown list-domain failure, and unknown search-dir failure, unknown route-id suggestion, unknown option suggestion, unknown value suggestion, and numeric range failure, prompt JSON output, prompt markdown output, prompt from-file output, prompt stdin output, pack JSON output, pack markdown output, pack from-file output, and pack stdin output, prompt/pack forced `--out` overwrite and prompt/pack file-write confirmations, check examples output, check artifact output, check stdin output, check all-routes output, and check learning capture output, human `design-ai audit --strict --quiet` output and JSON `design-ai audit --strict --quiet --json` machine-readable repository-audit output, JSON `design-ai learn --feedback` output plus learn feedback `--out` file-write confirmation, JSON `design-ai learn --init` output, JSON `design-ai learn --backup` output, JSON `design-ai learn --redact` output, `design-ai learn --redact --from-file` output, `design-ai learn --redact --stdin` output, learn JSON `--out` file-write confirmation and forced overwrite coverage, JSON `design-ai learn --verify` output plus learn verify `--out` file-write confirmation, JSON `design-ai learn --restore` preview/apply output plus learn restore `--out` file-write confirmation plus learn restore rollback backup verification plus learn restore `--backup-file` path coverage plus design-ai learn --restore-backups restore rollback backup inventory coverage plus design-ai learn --restore-backups --prune restore rollback backup pruning coverage, JSON `design-ai learn --import` dry-run/apply output plus learn import `--out` file-write confirmation, human / JSON `design-ai learn --stats` profile summary output plus learn stats `--out` file-write confirmation, query-filtered human learn list explanation and export JSON output, brief-relevant prompt/pack learning selection, prompt/pack learning usage sidecar recording, human / JSON `design-ai learn --usage` usage sidecar report plus learn usage `--out` file-write confirmation, human / JSON `design-ai learn --signals` learning signal registry plus `design-ai learn --signals --strict --json` strict gate plus learn signals `--out` file-write confirmation, human / JSON `design-ai learn --eval-template` checkpoint generation plus generated checkpoint strict validation, human / JSON `design-ai learn --eval` checkpoint report plus learn eval `--out` file-write confirmation plus learn eval `--strict` failure gate, human / JSON `design-ai learn --audit` cleanup suggestion output plus learn audit `--out` file-write confirmation, human / JSON `design-ai learn --curate` archive-first curation output plus usage-aware curation JSON review, human `design-ai update --dry-run` output, `design-ai update --dry-run --json` machine-readable update plan, human diagnostics output from `design-ai doctor --strict`, machine-readable diagnostics output from `design-ai doctor --json`, human `design-ai install` output plus `design-ai install --json` machine-readable install lifecycle output, human `design-ai status` output plus JSON status including `design-ai status --json` machine-readable install-state output, and human `design-ai uninstall` output plus `design-ai uninstall --json` machine-readable uninstall lifecycle output.
-- The same `npm run release:check` gate preserves Website Console bundle `mcp-probes.json` saved-payload guard phases through package contents, release self-tests, and packed-tarball smoke.
-- The same `npm run release:check` gate also preserves Website Console bundle boundary metadata guard phases for bundle-check JSON/human and bundle-handoff JSON/prompt boundary metadata plus full `release:self-test` evidence recording through unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke.
-- The same `npm run release:check` gate now also preserves the Product Readiness release policy full gate guard for Website Console bundle boundary metadata full `release:check` evidence through unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke.
-- The same `npm run release:check` gate now also preserves the Product Readiness release policy full gate evidence guard through unit tests, strict audits, whitespace checks, package contents, release metadata, release self-tests, and packed-tarball smoke.
-- Packed-tarball smoke also verifies route eval, prompt eval, and pack eval checkpoint output for installed-bin and one-shot `npm exec --package <tarball>` paths.
-- Packed-tarball smoke also verifies `design-ai learn --signals --report --out learning-signals.md` Markdown signal reports, learn signals JSON `--out` file-write confirmations, and `design-ai learn --agent-backlog --report --out agent-backlog.md` focused agent backlog Markdown reports plus agent backlog JSON `--out` file-write confirmations and `design-ai learn --agent-backlog --strict --json` agent backlog strict gates, focused agent backlog readiness summaries, `optionalGapDetails` JSON field coverage, check index JSON field coverage, Markdown check index section coverage, and check-capture optional-gap semantics for installed-bin and one-shot `npm exec --package <tarball>` paths. That smoke coverage also preserves the optional refresh-only runbook selection reason so no-command agent backlog output treats refresh as status metadata, not an executable handoff command.
-- Packed-tarball smoke also verifies `design-ai learn --propose-skills --min-evidence 3 --json` threshold skipping, learn skill proposals JSON `--out` file-write confirmations, `design-ai learn --propose-skills --report --out skill-proposals.md` Markdown review artifacts, `design-ai learn --propose-skills --review-file skill-proposals.review.json --json` read-only review decision joins, `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --json` read-only review-file readiness checks, `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --report --out skill-proposal-review-check.md` read-only review-check Markdown reports, `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --json` read-only accepted proposal apply plans, human apply-plan command contract summaries via `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan` with the `Command contract` section, `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --report --out skill-proposal-apply-plan.md` read-only apply-plan Markdown reports, `design-ai learn --propose-skills --review-template --out skill-proposals.review.json` JSON review templates, `design-ai learn --propose-skills --patch --out skill-proposals.patch` unified diff handoffs, and `design-ai learn --propose-skills --strict --json` as an expected-failure skill proposal readiness gate for installed-bin and one-shot `npm exec --package <tarball>` paths.
-- After npm publish completes, run `npm run registry:smoke` to verify the public `npm exec --package` install path, including human `design-ai version` and machine-readable version metadata from JSON `design-ai version --json`, `design-ai help` top-level help, the `design-ai help --json` topic catalog with probe-capable Website Console site help usage, functional aliases, all three `list` catalog domains in human and JSON mode, human / JSON corpus discovery output, route JSON output, route catalog output, and route stdin input, explicit `show --lines` output and `route --explain` output, unknown command failure, unknown help-topic failure, unknown list-domain failure, and unknown search-dir failure, unknown route-id suggestion, unknown option suggestion, unknown value suggestion, and numeric range failure, prompt JSON output, prompt markdown output, prompt from-file output, prompt stdin output, pack JSON output, pack markdown output, pack from-file output, and pack stdin output, prompt/pack forced `--out` overwrite and prompt/pack file-write confirmations, check examples output, check artifact output, check stdin output, check all-routes output, and check learning capture output, human `design-ai audit --strict --quiet` output and JSON `design-ai audit --strict --quiet --json` machine-readable repository-audit output, public registry JSON `design-ai learn --verify` output plus public registry learn verify `--out` file-write confirmation, public registry JSON `design-ai learn --backup` output plus public registry learn backup `--out` file-write confirmation, public registry human / JSON `design-ai learn --stats` profile summary output plus public registry learn stats `--out` file-write confirmation, human `design-ai update --dry-run` output, `design-ai update --dry-run --json` machine-readable update plan, human diagnostics output from `design-ai doctor --strict`, machine-readable diagnostics output from `design-ai doctor --json`, and human `design-ai install` output plus `design-ai install --json` machine-readable install lifecycle output, human `design-ai status` output plus JSON status including `design-ai status --json` machine-readable install-state output, and human `design-ai uninstall` output plus `design-ai uninstall --json` machine-readable uninstall lifecycle output.
-- Registry smoke also verifies public registry `design-ai workspace --strict --json` workspace strict failure/success readiness checks from the published package path.
-- Registry smoke also verifies public registry `design-ai workspace --learning-eval learning-eval.json --strict --json` checkpoint summaries with freshness metadata plus auto-detected learning usage sidecar summaries from the published package path.
-- Registry smoke also verifies public registry `design-ai workspace` workspace restore-backups readiness with restore rollback backup inventory from the published package path.
-- Registry smoke also verifies public registry `design-ai site` Website Console export validation, including public registry `design-ai site --stdin --next-actions --json` next-action operator checklist contract with `mcpProbeCounts` probe count telemetry plus shared smoke assertion self-test coverage for Website Console next-actions MCP probe counts plus public registry `design-ai site --stdin --next-actions --json --out file --force` next-action operator checklist output-file persistence plus public registry `design-ai site --stdin --next-actions --out file --force` next-action human checklist output-file persistence, sample workspace coverage, prompt template listing, MCP readiness, MCP readiness probes, MCP readiness probe JSON with `--out` file-write confirmation plus shared MCP probe output-file smoke assertions plus embedded MCP check probe next-step commands plus executable embedded MCP check probe command smoke coverage plus human MCP check probe command guidance and output-file smoke coverage plus embedded MCP check probe human report output command, MCP action plan, MCP probe action plan, MCP probe action plan JSON with `--out` file-write confirmation plus embedded MCP action plan probe output-file commands plus MCP action plan human report output command parity plus MCP action plan emitted human report command smoke coverage plus MCP action plan emitted check JSON command smoke coverage plus MCP action plan emitted self-archive command smoke coverage plus shared MCP action plan command mapping self-test coverage, handoff bundle, bundle-check JSON/human and bundle-handoff JSON/prompt boundary metadata for deterministic-local, no-external-call, and no-target-repo-mutation handoff validation, bundle-check/compare/handoff `mcpProbeCounts` probe count telemetry plus package smoke self-test coverage for Website Console bundle MCP probe counts plus bundled Website Console `mcp-probes.json` saved probe evidence payload assertion instead of the full `site --mcp-check --probes --json` response, bundle-repair, refactor task generation, and task-selected prompt generation from the published package path.
-- Registry smoke also verifies public registry JSON `design-ai learn --feedback` output plus public registry learn feedback `--out` file-write confirmation, public registry `design-ai learn --feedback --from-file`, public registry `design-ai learn --feedback --stdin`, public registry JSON `design-ai learn --init` preview/apply output, and public registry learn init duplicate-skip output.
-- Registry smoke also verifies public registry JSON `design-ai learn --restore` preview/apply output plus public registry learn restore `--out` file-write confirmation, public registry learn restore rollback backup verification, public registry learn restore `--backup-file` path coverage, public registry `design-ai learn --restore-backups` restore rollback backup inventory coverage, and public registry `design-ai learn --restore-backups --prune` restore rollback backup pruning coverage.
-- Registry smoke also verifies public registry JSON `design-ai learn --import` dry-run/apply output plus public registry learn import `--out` file-write confirmation plus public registry JSON `design-ai learn --redact` output, public registry `design-ai learn --redact --from-file`, public registry `design-ai learn --redact --stdin`, and public registry learn redact `--out` file-write confirmation.
-- Registry smoke also verifies public registry human / JSON `design-ai learn --audit` cleanup suggestion output plus public registry learn audit `--out` file-write confirmation and public registry `design-ai learn --audit --fix --dry-run` cleanup preview and confirmed apply output.
-- Registry smoke also verifies public registry query-filtered learn list explanation/export JSON output, public registry brief-relevant prompt/pack learning selection and prompt/pack learning usage sidecar recording with public registry prompt/pack --with-learning, and public registry `design-ai learn --eval-template` checkpoint generation plus public registry generated checkpoint strict validation.
-- Registry smoke also verifies public registry learning readiness Markdown report coverage so `design-ai learn --signals --report --out learning-signals.md` and `design-ai learn --agent-backlog --report --out agent-backlog.md` preserve the `Readiness check index` section from the published package path.
+- Run `npm run release:check` as the core gate before release PRs or tags. It wraps `npm test` (CLI unit tests), `npm run audit:strict` (all 8 audits), `git diff --check` (whitespace), `npm run package:check` (package contents), `npm run release:metadata` (release metadata + Product Readiness guard), `npm run release:self-test` (release assertion self-tests), and `npm run package:smoke` (packed-tarball smoke covering install, `site`, `workspace`, `learn`, and help/version/audit surfaces for both installed-bin and one-shot `npm exec --package <tarball>` paths).
+- After npm publish completes, run `npm run registry:smoke` to verify the same surfaces against the public `npm exec --package` install path.
 - Knowledge files use `<!-- hand-written -->` marker if hand-authored.
 - Skill PLAYBOOKs include a verification phase checklist.
 - Korean strings spelled out in Korean (no machine translation passing through).
 - All audits pass.
 - Before pushing for CI, run `npm run ci:local` when you need local parity with the non-publishing GitHub workflows. It wraps `release:check`, Python syntax checks, knowledge size budget, VS Code extension compile/unit tests, the MkDocs build, and the MkDocs warning policy used by the docs deployment workflow: no non-`refs/` warnings, with refs-only warnings capped at the accepted baseline.
 
+The exhaustive list of every command and flag that `release:check`, packed-tarball smoke, and registry smoke assert on is preserved in [`docs/RELEASE-GATES.md`](docs/RELEASE-GATES.md).
+
 ## License
 
 MIT. See [LICENSE](https://github.com/sungjin9288/design-ai/blob/main/LICENSE).

package/cli/bin/design-ai.mjs

@@ -8,6 +8,7 @@
 //   status               Show what's installed
 //   list [domain]        List skills / commands / knowledge (optionally filtered)
 //   search               Search the local design-ai markdown corpus
+//   index                Build, inspect, and verify the local retrieval index
 //   show                 Print a corpus file or line range
 //   route                Recommend and explain commands, skills, and knowledge for a brief
 //   routes               List available route ids

package/cli/commands/help.mjs

@@ -17,6 +17,7 @@ import { runMcp } from "./mcp.mjs";
 import { runPack } from "./pack.mjs";
 import { runPrompt } from "./prompt.mjs";
 import { runRoute } from "./route.mjs";
+import { runIndex } from "./index.mjs";
 import { runSearch } from "./search.mjs";
 import { runShow } from "./show.mjs";
 import { runSite } from "./site.mjs";
@@ -32,17 +33,18 @@ export const HELP_COMMANDS = [
   { topic: "uninstall", usage: "uninstall [--json]", description: "Remove symlinks (keeps source files)" },
   { topic: "status", usage: "status [--json]", description: "Show what's installed (use VERBOSE=1 for full list)" },
   { topic: "list", usage: "list [skills|commands|agents] [--json]", description: "List catalog from the plugin manifest" },
-  { topic: "search", usage: "search <query> [--dir kind] [--limit N] [--json]", description: "Search the local markdown corpus" },
+  { topic: "search", usage: "search <query> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]", description: "Search the local markdown corpus" },
+  { topic: "index", usage: "index [--build|--status|--verify] [--json] [--embeddings [--provider \"cmd args\"]]", description: "Build, inspect, and verify the local retrieval index" },
   { topic: "show", usage: "show <file[:line]> [--lines N:M] [--context N] [--json]", description: "Print a corpus file or line range" },
   { topic: "route", usage: "route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N]", description: "Recommend commands, skills, knowledge, and route eval checkpoints" },
   { topic: "routes", usage: "routes [--json]", description: "List available route ids" },
-  { topic: "prompt", usage: "prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--out file]", description: "Generate a ready-to-use agent prompt and prompt-plan eval checkpoints" },
-  { topic: "pack", usage: "pack <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N]", description: "Generate prompt plus bounded context and prompt-pack eval checkpoints" },
+  { topic: "prompt", usage: "prompt <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--out file]", description: "Generate a ready-to-use agent prompt and prompt-plan eval checkpoints" },
+  { topic: "pack", usage: "pack <brief|--from-file file|--stdin|--eval-template|--eval> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N]", description: "Generate prompt plus bounded context and prompt-pack eval checkpoints" },
   { topic: "check", usage: "check <artifact.md|--stdin|--examples> [--route id|--all-routes] [--learn]", description: "Check generated Markdown artifact quality; add --issues-only or --learn" },
   { topic: "audit", usage: "audit [--strict] [--quiet] [--json]", description: "Run repository quality checks" },
   { topic: "doctor", usage: "doctor [--strict] [--json] [--fix]", description: "Diagnose source, runtime, and install state" },
   { topic: "examples", usage: "examples [query] [--route id] [--limit N] [--json]", description: "Find worked examples for a route or query" },
-  { topic: "learn", usage: "learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--backup|--redact|--verify|--diff|--restore|--restore-backups [--prune]|--import|--audit [--fix]|--curate|--stats|--usage|--signals [--strict]|--agent-backlog [--strict]|--propose-skills [--min-evidence N] [--review-file path] [--review-check|--apply-plan] [--strict]|--eval-template|--eval [--strict]|--forget id|--clear] [--json|--report|--patch|--review-template] [--out file]", description: "Manage local learning preferences, usage reports, signal registry, agent backlog, skill proposals, and eval checkpoints for prompt personalization" },
+  { topic: "learn", usage: "learn [--init|--remember text|--feedback text|--list|--export|--query text|--explain|--recall query|--backup|--redact|--verify|--diff|--restore|--restore-backups [--prune]|--import|--audit [--fix]|--curate|--stats|--usage|--signals [--strict]|--agent-backlog [--strict]|--propose-skills [--min-evidence N] [--review-file path] [--review-check|--apply-plan] [--strict]|--eval-template|--eval [--strict]|--forget id|--clear] [--json|--report|--patch|--review-template] [--out file]", description: "Manage local learning preferences, usage reports, signal registry, agent backlog, skill proposals, and eval checkpoints for prompt personalization" },
   { topic: "workspace", usage: "workspace [--root path] [--learning-file path] [--learning-usage path] [--learning-eval path] [--strict] [--json]", description: "Show read-only local dogfood readiness: git, repository, learning usage, eval checkpoints, and release scripts" },
   { topic: "site", usage: "site <workspace.json|--stdin> [--strict] [--json|--mcp-check [--probes]|--mcp-plan [--probes] [--json]|--next-actions [--json]|--graph|--tasks|--bundle|--report|--prompts|--prompt id [--task id]] [--out file] | site <bundle-dir> --bundle-check [--json] | site <bundle-dir> --bundle-compare other-bundle-dir [--json] | site <bundle-dir> --bundle-handoff [--task id] [--json] | site <bundle-dir> --bundle-repair [--yes] [--json] [--out file] | site --init --name name --live-url url [--next-actions] [--out file] | site --init --name name --live-url url --bundle --out dir | site --from-intake file.md|--stdin [--json|--next-actions [--json]|--tasks|--bundle [--tasks] --out dir] [--out file] | site --intake-template [--language en|ko] [--json] [--out file] | site --sample [--out file] | site --prompt-list [--json]", description: "Validate Website Improvement Console exports and generate handoff artifacts" },
   { topic: "mcp", usage: "mcp", description: "Start the stdio MCP server for Claude Code, Codex, and other MCP clients" },
@@ -79,6 +81,7 @@ const HELP_RUNNERS = {
   status: () => runStatus(["--help"]),
   list: () => runList(["--help"]),
   search: () => runSearch(["--help"]),
+  index: () => runIndex(["--help"]),
   show: () => runShow(["--help"]),
   route: () => runRoute(["--help"]),
   routes: printRoutesHelp,