@design-ai/cli 4.55.0 → 4.57.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "design-ai",
-  "version": "4.55.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,11 +2,86 @@
 
 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.
+
+### Added
+- MCP tool argument validation now rejects unsupported fields, wrong JSON types, non-integer integer fields, out-of-range values, and blank required strings before invoking CLI commands.
+- Public npm `design-ai-mcp` evidence now records initialize and tools/list protocol smoke from a clean one-shot `npm exec --package @design-ai/cli@4.55.0 -- design-ai-mcp` path.
+- Local Claude Code and Codex client evidence now records the clone-backed `design-ai` MCP server as configured and connected.
+
+### Changed
+- Website Improvement runbook helpers were split into clearer, smaller modules and named predicates while preserving the existing handoff JSON and Markdown contracts.
+- MCP subprocess tests now use a shared stdio response helper, making negative protocol scenarios easier to read and extend.
+- MCP setup docs now explain why one-shot public npm verification should run outside the source checkout.
+
+### Fixed
+- MCP initialize now rejects malformed `protocolVersion` values, including non-string and blank-only protocol versions.
+- MCP notifications now reject request ids across the whole `notifications/` namespace while preserving silent handling for valid id-less notifications.
+- MCP response-producing methods now require ids, and malformed JSON-RPC request ids, methods, params, and tool-call containers return deterministic JSON-RPC errors.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check`.
+- `npm run release:metadata`.
+- `npm run audit:strict`.
+- `git diff --check`.
+- Public npm MCP protocol smoke returned server version `4.55.0` and 10 tools before the release bump.
+- Main-branch GitHub Actions passed for `Design-AI audit` and `Deploy doc site` after the MCP client evidence refresh.
+
+### Versions
+- `package.json` + `.claude-plugin/plugin.json`: 4.55.0 → 4.56.0.
+- `vscode-extension/package.json`: remains 0.4.1.
+
+### What this enables
+- Claude Code and Codex users get stricter, more predictable MCP error behavior without changing the design-ai tool surface.
+- Maintainers can verify the published MCP entrypoint and local client registrations from concrete evidence before and after publishing.
+
 ## Unreleased — Agent Eval, Learning Signals, Skill Proposals, MCP Probes, Workflow Graphs, and Handoff Evidence
 
 Added deterministic route, prompt-plan, prompt-pack eval surfaces, a read-only learning signal registry with deterministic agent development backlog actions and structured readiness summaries, focused backlog readiness pass-through for local AI/agent handoffs with packed-tarball smoke coverage and release metadata guard coverage, preview-only skill evolution proposals, optional Website Console MCP probes with output-file smoke persistence and executable embedded follow-up commands, shared MCP probe output-file smoke assertions, release metadata guard coverage for shared MCP probe output-file smoke assertions, embedded MCP check probe next-step commands, executable embedded MCP check probe command smoke coverage, human-readable MCP check probe command guidance, packed/public smoke coverage for that human guidance, human report output-file persistence smoke coverage, embedded human report output commands, release metadata guard coverage for embedded human report output commands, MCP action plan JSON parity for embedded human report output commands, release metadata guard coverage for that action-plan parity, and packed/public smoke execution for action-plan emitted human report commands, structured Website Console MCP action plan JSON export with output-file persistence and embedded probe output-file commands, release metadata guard coverage for embedded MCP action plan probe output-file commands, next-action operator checklist output-file smoke persistence, portable Website Console workflow graph export, static Website Console graph rendering, browser-local Website Console handoff evidence tracking, CLI/bundle handoff evidence export, verified bundle evidence metadata, generated bundle contract verification with per-file diagnostics, repair guidance, repair preview/apply, repair report output-file persistence, repair report command guidance, executable repair guidance smoke coverage, shared repair guidance smoke helpers, shared repair report assertion helpers, release metadata guard coverage for shared repair guidance smoke helpers and shared repair report assertion helpers, public registry Website Console MCP probe smoke coverage, MCP probe action plan smoke coverage, shared Website Console site help topic example smoke assertions, release metadata guard coverage for shared Website Console site help topic example smoke assertions, release metadata guard coverage and packed-tarball smoke coverage for optional refresh-only agent backlog runbook selection semantics, post-commit release evidence for that refresh-only backlog smoke contract, full `release:check` evidence after the refresh-only backlog closeout, and packed-tarball evidence preservation smoke coverage for local AI/agent development drift review.
 
 ### Added
+- Added MCP tool argument validation, so Claude Code and Codex receive clear typed errors for malformed tool calls before `design-ai` invokes any CLI command.
+- Added packed-tarball smoke coverage for the standalone `design-ai-mcp` binary, covering both installed `node_modules/.bin/design-ai-mcp` and one-shot `npm exec --package <tarball> -- design-ai-mcp` setup paths.
+- Added public registry smoke coverage for `npm exec --package @design-ai/cli@<version> -- design-ai-mcp`, so post-publish verification checks the same MCP stdio entrypoint that users install from npm.
 - Improved Website Console revalidation gate action labels, so compact gate copy/export buttons identify their JSON artifact type directly.
 - Improved Website Console Source Bundle action labels, so Markdown and provenance JSON copy/export buttons identify their artifact type directly.
 - Added Website Console Source Bundle detail source copy action, so operators can copy the current runbook source marker directly from the provenance table.

package/README.ko.md

@@ -3,7 +3,7 @@
 [![Audit](https://img.shields.io/badge/audit-passing-brightgreen)](https://github.com/sungjin9288/design-ai/actions/workflows/audit.yml)
 [![Docs](https://img.shields.io/badge/docs-live-indigo)](https://sungjin9288.github.io/design-ai/ko/)
 [![Knowledge files](https://img.shields.io/badge/knowledge-92-blue)](knowledge/PRINCIPLES.md)
-[![Examples](https://img.shields.io/badge/examples-223-blue)](examples/README.md)
+[![Examples](https://img.shields.io/badge/examples-221-blue)](examples/README.md)
 [![Skills](https://img.shields.io/badge/skills-20-blue)](skills/README.md)
 
 > 🇰🇷 한국어 / [🇺🇸 English](https://github.com/sungjin9288/design-ai/blob/main/README.md)
@@ -12,14 +12,14 @@
 
 > **모델이 아니에요. 파인튜닝도 아니에요.** 디자인 전문 지식을 구조화한 코퍼스 + 에이전트가 바로 실행할 수 있는 지시문이에요. 범용 LLM을 이번 세션에서만큼은 시니어 디자이너로 바꿔주는 셈이에요.
 
-> **배포 상태, 2026-06-23 확인:** 로컬 `npm run release:check`는 통과했고 GitHub Pages 문서는 공개 URL에서 확인됐어요. public npm과 VS Code Marketplace 배포는 아직 확인되지 않았으므로 package publish가 끝나기 전까지는 Git clone/local install 경로를 사용하세요. 자세한 내용은 [`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)를 확인하세요.
 
 ## 한눈에 보는 커버리지
 
 | 영역 | 지식 | 워크드 예제 | 스킬 |
 |---|---|---|---|
 | 디자인 토큰 (W3C DTCG, OKLCH) | ✓ | ✓ | `color-palette` |
-| 컴포넌트 (Ant + MUI + shadcn 합성) | ✓ | 72 specs | `component-spec-writer` |
+| 컴포넌트 (Ant + MUI + shadcn 합성) | ✓ | 210 component specs | `component-spec-writer` |
 | UX 패턴 (인증, 가격, 히어로, 폼 등) | ✓ | ✓ | `ux-audit`, `design-critique` |
 | 웹사이트 개선 컨트롤 타워 | ✓ | ✓ | `website-improvement` |
 | 한국어 i18n (한글, 결제, 앱스토어, 핀테크) | ✓ | ✓ | (전 영역 적용) |
@@ -34,7 +34,7 @@
 
 ## 설치 (Claude Code)
 
-### A. Git clone / local install (현재 추천)
+### A. Git clone / local install
 
 ```bash
 git clone https://github.com/sungjin9288/design-ai.git
@@ -42,9 +42,9 @@ cd design-ai
 ./install.sh
 ```
 
-### B. NPM (public publish 이후)
+### B. NPM
 
-`@design-ai/cli`가 publish되고 `npm run registry:smoke`가 통과한 뒤에만 이 경로를 사용하세요.
+public npm package 설치 경로예요.
 
 ```bash
 npx @design-ai/cli install
@@ -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)를 확인하세요.
 
@@ -120,7 +120,7 @@ design-ai/
 │   ├── spatial/             # VR / AR / 패널 / 편안함
 │   └── i18n/                # 한국어 타이포그래피, 결제, 앱스토어 등
 │
-├── examples/                # 223개 워크드 예제 ("good"이 어떻게 생겼는지)
+├── examples/                # 221개 워크드 예제 ("good"이 어떻게 생겼는지)
 │
 ├── skills/                  # 20개 재사용 가능한 플레이북 (작업 중심)
 ├── agents/                  # 4개 서브 에이전트 (병렬 리뷰)
@@ -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) 참조.