@design-ai/cli 4.56.0 → 4.57.0

package/docs/AI-LEARNING-PHASE2.md

@@ -0,0 +1,215 @@
+# AI learning phase 2: local retrieval memory
+
+This document opens the deeper AI-learning phase selected in [PRODUCT-READINESS.md](PRODUCT-READINESS.md) ("Recommended next decision", option 2). It defines the scope, data boundaries, and phased plan for local retrieval memory on top of the shipped learning system described in [AI-LEARNING.md](AI-LEARNING.md).
+
+Status: **Phase A implemented and release-gated** (see the Phase 754 checklist in [ROADMAP.md](ROADMAP.md)); **Phase B remains planning**. Everything Phase A shipped is local, derived, opt-in retrieval — the shipped learning scope otherwise remains what [AI-LEARNING.md](AI-LEARNING.md) documents, and the README stance is unchanged.
+
+## Goal
+
+Improve how design-ai selects context — corpus files for `search` and `route`, learning entries for `prompt --with-learning` and `pack --with-learning` — by adding a deterministic local retrieval layer, and optionally a local-only embedding backend, without changing the product's honesty stance: design-ai is not a model and does not train one.
+
+Concretely:
+
+- Replace first-substring-match corpus search with ranked lexical retrieval (tokenized TF-IDF/BM25-style scoring) that stays zero-dependency and reproducible.
+- Upgrade learning-entry selection from token-containment scoring (`cli/lib/learn-select.mjs`) to the same shared lexical scorer, so prompt/pack learning injection and corpus search rank with one auditable algorithm.
+- Allow an explicitly opt-in, user-supplied local embedding backend for reranking, degrading gracefully to the lexical path when absent.
+
+## Non-goals
+
+These stay out of scope for this phase and must not be introduced by its implementation:
+
+- Model fine-tuning, in any form.
+- Training a private model on user artifacts.
+- External embedding APIs, or any network call made by retrieval code paths.
+- Background learning or background indexing without an explicit CLI command.
+- Telemetry of any kind.
+
+This preserves the standing repo constraint ("Do not add external AI APIs, embeddings, telemetry, or fine-tuning behavior without explicit approval") — the maintainer approval that opens this phase covers local-only, opt-in mechanisms only.
+
+## Data boundaries and privacy constraints
+
+### What may be indexed
+
+1. **The shipped knowledge corpus**: `knowledge/`, `examples/`, `skills/`, `docs/`, `agents/`, `commands/` — the same directory set `design-ai search` already reads (`DEFAULT_SEARCH_DIRS` in `cli/lib/search.mjs`).
+2. **The user's local learning profile**: entries in `learning.json` (or the `DESIGN_AI_LEARNING_FILE` override), which the user already stores explicitly through `learn --remember`, `learn --feedback`, and `check --learn --yes`.
+
+Nothing else. Briefs, prompt text, artifacts under review, target-repo contents, and usage sidecar events are not index inputs.
+
+### What may never leave the machine
+
+- Index files, embedding vectors, and every retrieval artifact are local files. They are never synced, uploaded, or sent to any provider, matching the existing `learning.json` / `learning.usage.json` boundary in [AI-LEARNING.md](AI-LEARNING.md).
+- Retrieval code paths make no HTTP requests. Phase B providers are local executables chosen by the user; design-ai never selects or downloads one.
+- Query privacy follows the usage-sidecar convention: any retrieval logging stores selected ids and short brief hashes, never raw brief or query text.
+
+### How redaction composes
+
+- Index artifacts are **derived and rebuildable**. They are not part of the profile, so `learn --backup`, `learn --redact`, `learn --restore`, and `learn --import` do not include them, and their contracts do not change.
+- Because the learning index is derived from `learning.json`, redacting or curating the profile and rebuilding the index removes the corresponding text from retrieval. The index build records a content digest of its source profile; a mismatch marks the index stale so post-redaction state cannot keep serving pre-redaction text silently.
+- `learn --audit` warnings propagate: an index built from a profile with audit warnings carries the same audit summary metadata that `learn --export` and `--with-learning` already attach.
+- Restore and rollback (`learn --restore`, `--restore-backups`) invalidate the learning index by digest mismatch; the CLI reports the stale index and the rebuild command instead of rebuilding implicitly.
+
+## Phased plan
+
+### Phase A — deterministic local retrieval memory
+
+A zero-dependency lexical index over the knowledge corpus and local learning entries. No new runtime dependencies; plain Node.js like the rest of `cli/`.
+
+Scoring: shared tokenizer (the Unicode letter/number tokenizer already used by `learn-select.mjs`), document frequency statistics, and a BM25-style score with fixed constants. All math is integer/float-deterministic on the same inputs; no randomness, no time-dependent scoring.
+
+Consumers:
+
+- `design-ai search --ranked`: ranked results across the corpus instead of first-substring-match per file. The default `search` behavior is unchanged until the ranked mode has eval coverage.
+- `design-ai route`: unchanged routing table; the index may power an advisory "related knowledge" section in `--explain` output only. Route ids stay keyword-table-driven and deterministic.
+- `prompt --with-learning` / `pack --with-learning`: learning-entry selection moves to the shared scorer behind the existing selection-metadata contract (`selection.selected[]` with `id`, `score`, `matchedTokens`, `reason`). Recency fallback and category/limit scoping keep their current semantics.
+
+CLI surface sketch:
+
+```bash
+design-ai index --build            # build/refresh corpus + learning index (explicit, never background)
+design-ai index --status --json    # paths, digests, staleness, entry/doc counts
+design-ai index --verify           # rebuild in memory and compare digests; read-only
+design-ai search "query" --ranked  # BM25-style ranked corpus search
+design-ai prompt "brief" --with-learning   # same flag; shared scorer underneath
+```
+
+Storage format sketch (sidecar JSON, following `learning.json` conventions — versioned, sorted keys, stable ids):
+
+```json
+{
+  "version": 2,
+  "kind": "retrieval-index",
+  "generatedAt": "2026-07-03T00:00:00.000Z",
+  "source": {
+    "designAiPath": "/absolute/path/to/this/checkout",
+    "corpusDirs": ["knowledge", "examples", "skills", "docs", "agents", "commands"],
+    "corpusDigest": "sha256:...",
+    "learningFile": "~/.design-ai/learning.json",
+    "learningDigest": "sha256:..."
+  },
+  "stats": { "documentCount": 0, "termCount": 0, "avgDocLength": 0 },
+  "documents": [{ "id": "knowledge/a11y/contrast.md", "length": 0, "terms": {} }]
+}
+```
+
+Default locations: `~/.design-ai/index/corpus-index.json` and `~/.design-ai/index/learning-index.json`, with `DESIGN_AI_INDEX_DIR` as the override. Index files are cache artifacts: never committed, never packaged, safe to delete.
+
+Determinism and reproducibility: the same corpus bytes and profile bytes produce a byte-identical index apart from `generatedAt`, which is excluded from the digest. `index --verify` proves this by rebuilding and comparing. Ranked results are fully ordered (score, then stable path/id tiebreak), so `search --ranked` output is reproducible across runs and machines with the same inputs.
+
+Verification gates:
+
+- `node --test` unit coverage for tokenizer, scoring, tie-breaking, digest staleness, and `--build/--status/--verify` flows (`npm test`).
+- `npm run audit` stays 8/8 — docs links, frontmatter, and integration checks must pass with the new surfaces documented.
+- `npm run release:check` additions: packed-tarball smoke for `index --build` + `index --verify` round-trip and for `search --ranked` determinism (two runs, identical output); `learn --eval --strict` checkpoints re-run against the shared scorer to catch selection regressions.
+- `npm run release:metadata` stays green; README scope language ("Not a model. Not a fine-tune."; training/fine-tuning outside shipped scope) is unchanged by this phase.
+
+Rollback/compat: default `search`, `route`, `prompt`, and `pack` behavior is preserved until eval evidence supports switching defaults; `--ranked` is additive. If the learning-selection scorer changes selection output for existing profiles, the change ships behind updated `learn --eval-template` checkpoints and is called out in [ROADMAP.md](ROADMAP.md). Deleting the index directory restores pre-index behavior with zero data loss, because every index artifact is derived.
+
+### Phase B — optional local embedding backend
+
+An opt-in reranking layer on top of Phase A. Never a default, never external HTTP.
+
+- Pluggable local provider: the user supplies a local executable (for example an ONNX or llama.cpp embedding runner) via explicit configuration. design-ai shells out to it with document/query text on stdin and reads vectors from stdout. design-ai ships no model weights and adds no dependency.
+- Explicit opt-in per profile/config **and** per invocation; no flag, no embeddings. Absent, failing, or misbehaving providers degrade gracefully and visibly to the Phase A lexical path — output metadata reports which backend actually ranked the results.
+
+CLI surface sketch:
+
+```bash
+design-ai index --build --embeddings --provider ./bin/local-embed   # explicit provider, explicit build
+design-ai search "query" --ranked --embeddings                       # rerank lexical candidates; lexical fallback if unavailable
+design-ai index --status --json                                      # reports embedding backend presence, digests, staleness
+```
+
+Storage format (sidecar next to the Phase A index, `embedding-index.json`; as shipped):
+
+```json
+{
+  "version": 1,
+  "kind": "embedding-index",
+  "generatedAt": "2026-07-03T00:00:00.000Z",
+  "provider": { "command": "./bin/local-embed", "args": [], "modelLabel": "user-supplied", "dimensions": 384 },
+  "source": {
+    "designAiPath": "/absolute/path/to/this/checkout",
+    "corpusDirs": ["knowledge", "examples", "skills", "docs", "agents", "commands"],
+    "corpusDigest": "sha256:...",
+    "learningFile": "~/.design-ai/learning.json",
+    "learningDigest": "sha256:...",
+    "auditStatus": "ok"
+  },
+  "vectors": [{ "id": "knowledge/a11y/contrast.md", "v": [0.0] }]
+}
+```
+
+Same source-identity fields as the Phase A corpus/learning index (`designAiPath`, `learningFile`, both digests) so freshness and "not my index" rules are identical (FU-2). Learning entry documents are embedded alongside the corpus, with their id prefixed `learning:` in this sidecar only (never in `learning.json` or the Phase A learning index) so ids never collide with corpus paths. Configuration home: `~/.design-ai/config.json` (`{ "version": 1, "embeddings": { "provider": { "command": "...", "args": [...] }, "modelLabel": "..." } }`, user-authored, design-ai never writes it) supplies the durable per-machine provider; `--provider "cmd args"` overrides it for one invocation; either way the explicit `--embeddings` flag is still required per invocation (config alone never enables it).
+
+Determinism and reproducibility: design-ai's side is deterministic — candidate generation (Phase A), provider invocation order, cosine similarity, and tie-breaking are all fixed. Vector values depend on the user's provider; the index therefore records the provider command and source digests so results are reproducible for a given provider, and `index --status` surfaces any digest drift. Eval checkpoints for embedding-assisted selection are only valid against the same recorded provider.
+
+Verification gates:
+
+- `npm test` coverage using a deterministic stub provider (fixed fake vectors) for build, rerank, fallback, and provider-failure paths; no real model in CI.
+- `npm run audit` 8/8 with Phase B surfaces documented; `npm run release:metadata` green.
+- `npm run release:check` additions: packed-tarball smoke proving (1) embeddings are off by default, (2) a missing provider degrades to Phase A with a clear notice and exit code 0, (3) no network access is attempted (provider invocation is a local process spawn only).
+
+Rollback/compat: removing the provider configuration or deleting the embedding sidecar reverts to Phase A everywhere. Phase A never depends on Phase B artifacts. Lexical index format changes required by Phase B bump the sidecar `version` field with a documented migration note.
+
+## Integration points with existing surfaces
+
+- **learn**: `learn --eval` / `--eval-template` remain the regression gate for selection behavior; checkpoints gain an optional `ranker` field (`lexical` default) so Phase A/B changes are eval-visible. `learn --curate`, `--redact`, `--restore` interact with the index only through digest staleness, as described above.
+- **signals**: `learn --signals --report` adds a retrieval-readiness section (index presence, staleness, backend) next to the existing usage/eval signal files, keeping the same read-only and privacy rules.
+- **workspace**: `design-ai workspace` reports index staleness the same way it reports usage-sidecar and eval-checkpoint freshness — a warning plus a shell-quoted `design-ai index --build` next action; `--strict` treats a stale index as a readiness warning only when retrieval features are in use.
+- **eval**: route eval (`route --eval`) and learning eval stay the deterministic QA harness; new ranked surfaces do not ship as defaults before checkpoints cover them.
+- **MCP server tools**: `design_ai_search` gains the same opt-in ranked mode as the CLI; `design_ai_prompt` / `design_ai_pack` inherit the shared scorer transparently. A read-only `design_ai_index_status` tool may expose `index --status`. MCP tools never trigger index builds implicitly; building stays an explicit operator action, consistent with the current read-only-by-default MCP posture in [MCP-INTEGRATION.md](MCP-INTEGRATION.md).
+
+## Risks and open questions
+
+Risks:
+
+- **Scope creep toward "AI product" claims.** Mitigation: README status language is a release gate; this document and [PRODUCT-READINESS.md](PRODUCT-READINESS.md) keep retrieval memory listed as planning until shipped.
+- **Selection-behavior drift** for existing users when the shared scorer replaces containment scoring. Mitigation: eval checkpoints before/after, selection metadata unchanged in shape, roadmap callout.
+- **Stale-index confusion** if users edit the profile and see old retrieval behavior. Mitigation: digest staleness is checked on every consumer read and reported, never silently ignored.
+- **Phase B provider quality and safety** are outside design-ai's control. Mitigation: provider results are rerank-only over lexical candidates, provenance is recorded, and the lexical path remains the contract.
+
+Open questions:
+
+1. Should `search --ranked` become the default once eval evidence exists, or stay opt-in permanently to preserve byte-stable output for existing scripts? — answered in the [Phase A implementation review](#phase-a-implementation-review-2026-07-03).
+2. Does the corpus index live per-checkout (keyed by corpus digest) or per-machine? Per-checkout is safer for multiple clones; per-machine is simpler. — answered in the [Phase A implementation review](#phase-a-implementation-review-2026-07-03).
+3. Should `route` ever consume the index for routing decisions, or is advisory `--explain` enrichment the permanent boundary? — answered in the [Phase A implementation review](#phase-a-implementation-review-2026-07-03).
+4. Minimum useful BM25 constants and tokenizer treatment for Korean text — does the current Unicode tokenizer rank Korean briefs well enough, or does Phase A need explicit bigram handling for Hangul? — answered in the [Phase A implementation review](#phase-a-implementation-review-2026-07-03).
+5. Phase B configuration home: a new `~/.design-ai/config.json`, or flags-only to keep zero persistent configuration? — answered in the [Phase A implementation review](#phase-a-implementation-review-2026-07-03).
+
+These questions should be answered during Phase A implementation review before Phase B is scheduled.
+
+## Phase A implementation review (2026-07-03)
+
+This review answers the five open questions against the shipped Phase A implementation (`cli/lib/lexical.mjs`, `cli/lib/retrieval-index.mjs`, `cli/lib/search-ranked.mjs`, `cli/lib/learn-select.mjs`) with all Phase 754 Phase A checklist items landed in [ROADMAP.md](ROADMAP.md).
+
+### Decisions
+
+1. **`search --ranked` stays opt-in; it does not become the default.** The default `search` emits byte-stable first-substring-match output that existing scripts and the packed-tarball determinism smoke depend on, and ranked output is a different contract (scores, ordering, previews). The right long-term move is not flipping the default but adding a ranked-mode eval checkpoint so ranked quality is measured; until such a checkpoint exists there is no evidence basis to switch, and even with it the safer path is a documented opt-in plus a possible future `--ranked` alias rather than silently changing default output. Decision: **opt-in permanently**, with promotion to default deferred behind a concrete trigger (a landed ranked-search eval checkpoint showing ranked ≥ substring on the QA set) — and even then only via an announced major-version default change, never a silent one.
+
+2. **Corpus index stays per-machine, but must be keyed by corpus digest within the shared directory.** Today `buildCorpusIndex` writes a single `corpus-index.json` under `~/.design-ai/index/`, so two checkouts with different corpora overwrite each other's index. This is currently harmless because `search --ranked` live-scans the corpus and uses the index file only for a staleness notice (`corpusIndexNotice`) — a wrong-checkout index produces a "stale" notice, never wrong results. It becomes load-bearing the moment Phase B reads vectors from the sidecar instead of live-scanning. Decision: **keep per-machine storage** (simpler, matches the `learning.json` boundary) but add a follow-up to namespace the index file by corpus digest (or record the `designAiPath` in the payload and treat a path/digest mismatch as "not my index") before Phase B consumes the index as a source of truth.
+
+3. **`route` keeps the advisory boundary; the index never drives routing decisions.** Verified in the shipped build: `route --explain` scores against its own deterministic keyword table (observed `matched: 접근성, 개선` with integer scores and `why:` keyword lists), fully independent of the BM25 index, and no "related knowledge" section is wired in yet. Route ids must stay keyword-table-driven and reproducible so routing is auditable and stable across machines regardless of index presence. Decision: **advisory `--explain` enrichment is the permanent boundary** — the index may later populate an advisory "related knowledge" block in `--explain` output only, and must never change which route ids are selected or their order.
+
+4. **The current Unicode tokenizer is NOT adequate for Korean briefs; Phase A needs Hangul handling, tracked as a follow-up rather than a Phase B blocker.** Empirical finding: the tokenizer treats each whitespace-delimited Hangul surface form as one atomic token with no stemming, so agglutinative (particle-attached) forms only match documents containing that exact form. Observed via `search "<q>" --ranked --json`:
+   - `버튼을` → 2 hits (matches only literal `버튼을`); bare stem `버튼` → **0 hits**, `버튼이` → **0 hits**. Corpus grep confirms `버튼` appears *only* as `버튼을`/`버튼은`, never bare — so the stem query silently misses every button doc.
+   - `접근성이` → **0 hits**, but bare `접근성` → 12 hits (corpus has `접근성` bare 17×).
+   - `결제하기` → 2 hits (exact form only); `저장하기` → 3 hits vs `저장` → 20 hits; `삭제` → 13 hits.
+   The match/miss outcome is pure coincidence of which surface form happens to occur in the corpus, not linguistic relevance — the same query concept scores 0 or high depending on an accidental particle. English is unaffected because its tokenizer already splits on the space between word and particle. This is a real Korean-brief retrieval gap given the product's Korean-market focus ([NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md)). Mitigation is a Phase A follow-up (Hangul-aware handling: character bigrams for CJK runs, or a small particle-stripping pass), gated by new Korean eval checkpoints so the tokenizer change is eval-visible. BM25 constants (`k1=1.2`, `b=0.75`) are standard and fine; the gap is tokenization, not scoring.
+
+5. **Phase B configuration home: introduce `~/.design-ai/config.json`, not flags-only.** A local embedding provider is a durable per-machine setting (a provider command path plus opt-in state) that a user should set once, not re-pass on every invocation; flags-only would force the provider path into every `search`/`index` call and into MCP tool wiring, which is fragile and undiscoverable. `config.json` also composes with the existing `~/.design-ai/` sidecar convention and stays local-only. Decision: **add `~/.design-ai/config.json`** (versioned, sorted keys, local-only, honoring `DESIGN_AI_INDEX_DIR`-style overrides), still requiring the per-invocation `--embeddings` opt-in from the design so config presence alone never silently enables reranking — config supplies the provider, the flag arms it.
+
+### Follow-up work items
+
+- **FU-1 (Q4, before Phase B):** Add Hangul-aware tokenization (CJK bigramming or particle stripping) in `cli/lib/lexical.mjs` behind Korean `learn --eval` checkpoints; regression-test that `버튼`, `버튼을`, `버튼이` converge on the same button docs. _Done (2026-07-03): Hangul runs >= 2 chars now emit overlapping character bigrams alongside the surface form; the review's zero-hit queries recover (`버튼` 0 → 3 ranked hits, `접근성이` 0 → 3), with unit regression coverage in `lexical.test.mjs`._
+- **FU-2 (Q2, before Phase B index-as-source-of-truth):** Key the corpus index by corpus digest / record `designAiPath` in the payload so multiple checkouts do not overwrite each other once the index is read for content rather than staleness. _Done (2026-07-03): sidecar format bumped to version 2 (auto-invalidating v1 files); the corpus payload records resolved `designAiPath` and the learning payload the resolved `learningFile`, and `index --status` reports `sourceMatch` and treats identity mismatch as not fresh._
+- **FU-3 (Q1, gates default promotion):** Land a ranked-search eval checkpoint so any future `--ranked` default promotion is evidence-backed and announced.
+- **FU-4 (Q5, Phase B):** Specify and implement `~/.design-ai/config.json` as the Phase B provider config home with per-invocation `--embeddings` still required.
+
+### Phase B gate: cleared-with-conditions
+
+Phase B may be scheduled. Conditions that must be met before or during Phase B:
+
+- **FU-2 is a hard precondition** if Phase B reads the corpus/embedding sidecar as a source of truth rather than live-scanning: the per-machine single-file index must be digest/path-keyed first, or multiple checkouts will serve each other's vectors.
+- **FU-1 should land in Phase A** (or explicitly early in Phase B) so embedding rerank is not layered on top of a Korean lexical candidate set that already silently drops particle-attached queries — otherwise Phase B inherits and masks the tokenization gap.
+- **FU-4 (`config.json`)** is the accepted Phase B configuration home and must keep the per-invocation opt-in.
+- Non-goals and Data boundaries above are unchanged; Phase B remains local-only, opt-in, no external HTTP, graceful degradation to the Phase A lexical path.

package/docs/DISTRIBUTION.ko.md

@@ -2,7 +2,7 @@
 
 design-ai를 이 레포에서 어댑터의 Claude Code 환경으로 가져오는 방법.
 
-> 배포 상태, 2026-07-02 확인: 로컬 `npm run release:check`는 통과했고 GitHub Pages 문서는 공개 URL에서 확인됐으며, GitHub Release `v4.56.0`과 Homebrew formula `v4.56.0` pinning이 확인됐어요. npm은 아직 `@design-ai/cli@4.55.0`이 최신 public package이고 public registry smoke도 이 버전 기준으로 통과했어요. `v4.56.0` npm publish workflow는 `NPM_TOKEN` 인증과 package smoke까지 통과하지만, npm publish 단계에서 granular token의 Bypass 2FA가 필요하다는 `E403`으로 막혀 있어요. Bypass 2FA가 켜진 granular token으로 GitHub Secret을 교체하거나 Trusted Publishing으로 전환한 뒤 다시 실행해야 해요. `sungjin.design-ai-vscode@0.4.1`도 VS Code Marketplace Gallery API 기준으로 publish가 확인됐어요. 자세한 내용은 [`external-status.md`](external-status.md)를 확인하세요.
+> 배포 상태, 2026-07-02 확인: 로컬 `npm run release:check`는 통과했고 GitHub Pages 문서는 공개 URL에서 확인됐으며, GitHub Release `v4.56.0`과 Homebrew formula `v4.56.0` pinning이 확인됐어요. npm은 `@design-ai/cli@4.56.0`이 최신 public package이고 public registry smoke도 이 버전 기준으로 통과했어요. `sungjin.design-ai-vscode@0.4.1`도 VS Code Marketplace Gallery API 기준으로 publish가 확인됐어요. 자세한 내용은 [`external-status.md`](external-status.md)를 확인하세요.
 
 ## 설치 경로
 
@@ -23,7 +23,7 @@ cd design-ai
 
 ### B. NPM
 
-public package 설치 경로예요. `@design-ai/cli@4.55.0` publish와 public registry smoke 통과가 확인됐어요. `v4.56.0`은 GitHub Release로는 공개됐지만, npm에는 publish token 교체와 workflow 재실행이 끝난 뒤 올라가요.
+public package 설치 경로예요. `@design-ai/cli@4.56.0` publish와 public registry smoke 통과가 확인됐어요.
 
 ```bash
 # npx로 일회성 (글로벌 설치 없음)

package/docs/DISTRIBUTION.md

@@ -2,7 +2,7 @@
 
 How design-ai gets from this repo into adopters' Claude Code installations.
 
-> Distribution status, checked 2026-07-02: local `npm run release:check` passes, GitHub Pages docs are live, GitHub Release `v4.56.0` is published, the Homebrew formula is pinned to `v4.56.0`, `@design-ai/cli@4.55.0` remains the latest public npm package with registry smoke coverage, and `sungjin.design-ai-vscode@0.4.1` is published to the VS Code Marketplace by Gallery API evidence. The `v4.56.0` npm publish workflow now authenticates `NPM_TOKEN` and passes package smoke, but npm rejects publish unless the granular token has Bypass 2FA enabled or the workflow uses Trusted Publishing. See [`external-status.md`](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, the Homebrew formula is pinned to `v4.56.0`, `@design-ai/cli@4.56.0` is the latest public npm package with registry smoke coverage, and `sungjin.design-ai-vscode@0.4.1` is published to the VS Code Marketplace by Gallery API evidence. See [`external-status.md`](external-status.md).
 
 ## Install paths
 
@@ -23,7 +23,7 @@ Use this path if you want to:
 
 ### B. NPM
 
-Use this path for the public package. `@design-ai/cli@4.55.0` is published and public registry smoke has passed. `v4.56.0` is available as a GitHub Release, but it is not on npm until the publish token is replaced and the workflow is rerun successfully.
+Use this path for the public package. `@design-ai/cli@4.56.0` is published and public registry smoke has passed.
 
 ```bash
 # One-shot via npx (no global install)

package/docs/NEXT-SURFACE-DECISION.md

@@ -0,0 +1,125 @@
+# Next surface decision
+
+> Status: proposed — awaiting maintainer sign-off
+> Date: 2026-07-03
+
+This record answers option 3 of the "Recommended next decision" in [`PRODUCT-READINESS.md`](PRODUCT-READINESS.md): if the goal is "best design tool" as a broader product, which surface do we deepen next — CLI, VS Code extension, web UI, Figma plugin, or agent SDK?
+
+## Context and decision drivers
+
+### Who uses design-ai today
+
+design-ai is a model-agnostic design knowledge corpus plus a deterministic, zero-dependency Node.js CLI. Its primary consumer is an **AI coding agent** (Claude Code, Codex, Cursor, Aider) that picks up the repo and behaves like a senior product designer for a session. The human is present but works *through* the agent — routing briefs, packing prompts, checking artifacts, running the Website Improvement handoff flow. Secondary consumers are maintainers who run the CLI directly and adopters who install via npm/Homebrew.
+
+### What is already shipped
+
+Per [`external-status.md`](external-status.md) (checked 2026-07-02):
+
+- **CLI** — `@design-ai/cli@4.56.0` on npm, GitHub Release `v4.56.0`, Homebrew tap. This is the mature surface: route/prompt/pack/check/search/show/examples, plus `site` (Website Console), `learn`, and `workspace`.
+- **MCP server** — public `design-ai-mcp` entrypoint, 10 tools, connected to Claude Code and Codex. This is the agent-facing distribution channel and it already works.
+- **VS Code extension** — `sungjin.design-ai-vscode@0.4.1` on the Marketplace: sidebar trees + quick-pick commands over the corpus.
+- **Web console** — the zero-dependency static web console under [`website-console/`](website-console/) for the website-improvement workflow (workflow graph, browser-local handoff evidence tracking).
+- **Docs** — GitHub Pages (MkDocs).
+
+The important framing: none of the five candidates is greenfield. Each is a *deepening* of something that already ships in thin form.
+
+### Maintenance constraints
+
+- **Single maintainer.** Build cost and ongoing maintenance cost dominate. A surface that needs continuous platform-review babysitting (store submissions, plugin re-approvals) is expensive out of proportion to its code.
+- **Zero-dependency stance.** The CLI and web console ship with no runtime dependencies. Any surface that forces a framework/toolchain (React build, Figma plugin bundler) breaks that stance and adds supply-chain surface.
+- **Deterministic architecture.** The product is deterministic corpus routing, prompt packing, and quality checking — not model inference. Surfaces that imply "smart UI" set an expectation the architecture deliberately does not meet.
+- **Korean-market focus.** Load-bearing value in the dogfood runs came from Korean i18n knowledge (see [`DOGFOOD-FINDINGS.md`](DOGFOOD-FINDINGS.md), [`DOGFOOD-V4-FINDINGS.md`](DOGFOOD-V4-FINDINGS.md)). Any surface should keep that differentiator front and center, not dilute it into a generic tool.
+
+### Synergy driver
+
+A sibling doc, `AI-LEARNING-PHASE2.md`, is being authored in parallel to open an AI-learning retrieval phase (retrieval memory over the corpus and local learning signals). Whichever surface we deepen should compound with that phase rather than fork effort away from it.
+
+## Evaluation criteria
+
+Each surface is scored 1–5 on:
+
+- **Leverage** — reuse of existing assets (corpus, CLI lib, MCP tools, web console).
+- **Reach** — user value and how many of today's users it serves.
+- **Build cost** — 1 = expensive, 5 = cheap (higher is better).
+- **Maintenance** — ongoing burden for one maintainer; 1 = heavy, 5 = light.
+- **Distribution** — discovery and install friction; 5 = frictionless.
+- **Risk** — platform dependency and review-process exposure; 5 = low risk.
+- **Learning synergy** — compounding with the AI-learning retrieval phase.
+
+## Scoring table
+
+| Criterion | CLI deepening | VS Code deepening | Web UI | Figma plugin | Agent SDK |
+|---|---|---|---|---|---|
+| Leverage | 5 | 4 | 4 | 2 | 5 |
+| Reach | 4 | 3 | 3 | 2 | 4 |
+| Build cost | 5 | 3 | 3 | 2 | 4 |
+| Maintenance | 5 | 3 | 4 | 1 | 4 |
+| Distribution | 5 | 4 | 3 | 3 | 4 |
+| Risk | 5 | 3 | 4 | 1 | 4 |
+| Learning synergy | 5 | 3 | 3 | 2 | 5 |
+| **Total** | **34** | **23** | **24** | **13** | **30** |
+
+## Per-surface analysis
+
+### 1. CLI deepening
+
+**Scores.** Leverage 5: every command already routes through the shared `cli/lib` surface and the MCP server wraps the same functions, so a CLI capability is instantly an MCP capability. Reach 4: serves the primary agent user and the maintainer directly. Build cost 5 and maintenance 5: no toolchain, no store, `npm run audit` (8/8) plus the packed-tarball and registry smokes already gate every change. Distribution 5: publish is a solved, provenance-signed path. Risk 5: no platform dependency. Learning synergy 5: retrieval memory is naturally exposed as new `learn`/`route`/`pack` flags and reused verbatim by MCP.
+
+**90-day slice.** Land the AI-learning retrieval flow as CLI verbs (`learn --recall`, `pack --with-recall`), close the concrete corpus gaps the dogfoods named — money-aware patterns, mobile navigation, list/feed, React Native, Korean payments (from [`DOGFOOD-FINDINGS.md`](DOGFOOD-FINDINGS.md)) — and add the async-control and Korean-density knowledge from [`DOGFOOD-V4-FINDINGS.md`](DOGFOOD-V4-FINDINGS.md). Each ships behind existing gates and flows to MCP for free.
+
+**Evidence.** The v4 dogfood explicitly credits the single `npm run audit` runner and the CLI corpus for a 3–5x speedup on Form/Dialog/List work; the friction it surfaced was *missing corpus and flags*, not a missing surface.
+
+### 2. VS Code extension deepening
+
+**Scores.** Leverage 4: reuses the corpus and search logic but the `vscode` API layer is its own code. Reach 3: serves humans who browse the corpus, not the agent that is the primary consumer. Build cost 3 and maintenance 3: TypeScript toolchain, and [`DOGFOOD-V4-VSCODE-FINDINGS.md`](DOGFOOD-V4-VSCODE-FINDINGS.md) shows the untested `vscode` API surface (quick-pick rendering, config propagation, tree refresh) still needs `@vscode/test-electron` plus a CI matrix. Distribution 4: Marketplace publish already works at 0.4.1. Risk 3: Marketplace review and API churn. Learning synergy 3: a webview could show recall results but that is net-new UI.
+
+**90-day slice.** Add a webview that renders the Website Console workflow graph inside the editor and surfaces `check` results inline; add the deferred headless integration tests. Real value, but it targets the human-browsing path while the agent path (MCP) is where the product is consumed.
+
+**Evidence.** The VS Code dogfood is honest that pure logic is 100% extracted and tested, but "actual UI rendering inside VS Code" and "config change handling under real load" are explicitly *not* validated — deepening here means first paying down that test debt.
+
+### 3. Web UI (expand the website console)
+
+**Scores.** Leverage 4: the static console already exists and is zero-dependency. Reach 3: good for the website-improvement workflow specifically, narrower for the rest of the corpus. Build cost 3 and maintenance 4: staying zero-dependency keeps it cheap, but broadening beyond the console's single workflow is real design work. Distribution 3: a static site needs hosting and discovery it doesn't have yet. Risk 4: low platform risk if it stays static. Learning synergy 3: could visualize recall, but as new UI.
+
+**90-day slice.** Generalize [`website-console/`](website-console/) from one workflow into a small corpus browser + prompt-pack builder that runs fully client-side against exported JSON. Attractive, but it risks re-implementing the CLI's routing/packing in a second language and diverging from it.
+
+**Evidence.** The console is the one shipped web asset and it is deliberately scoped to website-improvement; there is no dogfood evidence of demand for a broader web surface, whereas corpus and flag gaps are documented repeatedly.
+
+### 4. Figma plugin
+
+**Scores.** Leverage 2: the [`FIGMA-INTEGRATION.md`](FIGMA-INTEGRATION.md) bridge is token export/import, not a live plugin, so most plugin code is new. Reach 2: serves designers who are not today's primary agent user. Build cost 2, maintenance 1, risk 1: a Figma plugin means a bundler (breaking the zero-dependency stance), the Figma plugin-review process, and API churn maintained by one person. Distribution 3 and synergy 2 do not offset that.
+
+**90-day slice.** A plugin that pushes generated tokens into Figma Variables and pulls selection context back. High desirability, but the worst fit for the constraints: new toolchain, external review gate, and a maintenance tail that competes directly with the learning phase.
+
+**Evidence.** Nothing in the dogfood record points to Figma-plugin friction; the shipped Figma story is file-based token sync, which the CLI already serves.
+
+### 5. Agent SDK (programmatic library surface)
+
+**Scores.** Leverage 5: an SDK is a thin, documented wrapper over the exact `cli/lib` functions the MCP server already calls — near-zero new logic. Reach 4: lets other tools and agents embed design-ai's routing/packing/checking without shelling out to the CLI, extending the primary agent-consumer story. Build cost 4 and maintenance 4: mostly surface stabilization and typing over existing code, gated by the same smokes; the ongoing cost is API stability, not a platform. Distribution 4: ships in the same npm package. Risk 4: the only real risk is committing to a public API contract. Learning synergy 5: the retrieval phase is consumed programmatically day one.
+
+**90-day slice.** Extract and document a stable `@design-ai/cli` programmatic entry (`route()`, `pack()`, `check()`, `recall()`) mirroring the MCP tool set, with typed inputs/outputs and smoke coverage. This is the second-best fit and a natural follow-on to CLI deepening — but committing to a public API contract before the retrieval phase settles risks freezing an interface we will want to change.
+
+**Evidence.** The MCP server already proves these functions are cleanly separable from I/O; an SDK formalizes what MCP consumes internally.
+
+## Recommendation
+
+**Deepen the CLI (option 1), and treat the Agent SDK (option 5) as the fast follow once the AI-learning retrieval phase stabilizes.**
+
+Rationale: the CLI is the one surface where every constraint points the same direction — highest leverage (it is also the MCP surface, so one change serves both the human and the agent consumer), lowest build and maintenance cost, no platform-review risk, and the cleanest synergy with `AI-LEARNING-PHASE2.md`, whose retrieval verbs land as CLI flags and flow to MCP for free. The dogfood record is consistent that the friction today is *missing corpus and missing flags*, not a missing GUI. Deepening the CLI directly retires that friction while keeping the zero-dependency, deterministic, Korean-focused posture intact.
+
+## What we defer, and when to revisit
+
+- **Agent SDK** — deferred only until the retrieval API stabilizes (target: after the first `AI-LEARNING-PHASE2.md` milestone lands in the CLI). Revisit trigger: the CLI recall interface has been stable across two releases, or an external adopter asks to embed design-ai programmatically.
+- **VS Code deepening** — deferred pending demand and test-debt paydown. Revisit trigger: adopter reports of the extension being the primary entry point, or the headless `@vscode/test-electron` suite is in place.
+- **Web UI** — deferred beyond the current website-console scope. Revisit trigger: repeated requests for a no-install, browser-only corpus experience, or a non-agent audience becomes a real segment.
+- **Figma plugin** — deferred longest. Revisit trigger: file-based token sync is demonstrably insufficient and a designer audience (not the agent) becomes a primary user, justifying the toolchain and review-process cost.
+
+Cross-check any surface work against the release gate: `npm run audit` (8/8, link resolution included) and `npm run release:metadata` before touching README/DISTRIBUTION-class docs.
+
+## Decision record
+
+- **Status:** proposed — awaiting maintainer sign-off
+- **Date:** 2026-07-03
+- **Deciders:** maintainer
+- **Supersedes:** none
+- **Related:** [`PRODUCT-READINESS.md`](PRODUCT-READINESS.md), [`external-status.md`](external-status.md), `AI-LEARNING-PHASE2.md`

package/docs/PRODUCT-READINESS.md

@@ -53,9 +53,9 @@ These are valid future product ideas, but they are different from the current ar
 
 Only launch-readiness items remain in the active roadmap:
 
-- Real-CI verification: push the branch and observe GitHub Actions green.
-- External launch: publish/announce after CI and registry smoke are proven.
-- Reference-link policy: decide whether `refs/` source links remain visible or move behind generated reference pages.
+- Real-CI verification: complete — main-branch pushes run green on GitHub Actions (audit + docs deploy), and npm publish run `28569283984` succeeded with provenance (verified 2026-07-03).
+- External launch: publishing is complete (npm `@design-ai/cli@4.56.0`, GitHub Release `v4.56.0`, Homebrew tap, VS Code Marketplace `sungjin.design-ai-vscode` v0.4.1, GitHub Pages docs); the public announcement itself remains a maintainer decision.
+- Reference-link policy: decided — `refs/` source links moved behind generated reference pages. `tools/extractors/reference_pages.py` emits `docs/reference/{ant-design,mui,shadcn-ui,awesome-design-md}.md`, and corpus pages (`knowledge/components/INDEX.md`, `knowledge/patterns/brand-references.md`, `examples/*.md`) link to those pages instead of the gitignored `refs/` mirror. Plain-text `refs/` provenance mentions (frontmatter `source:`/`sources:`, link text) stay as-is, and the MkDocs refs-only warning baseline in `tools/audit/local-ci.py` is now 0.
 
 ## Recommended next decision
 

package/docs/RELEASE-GATES.ko.md

@@ -0,0 +1,35 @@
+# 릴리스 게이트 상세 (v4.56.0)
+
+> `README.ko.md`의 상태·기여하기 요약을 뒷받침하는 전체 증빙 문구 모음이에요.
+> 영어판 전체 증빙은 [RELEASE-GATES.md](RELEASE-GATES.md)를 참고하세요.
+> 릴리스 정책 가드(`npm run release:metadata`)는 README.ko.md와 이 문서를 함께 검사해요.
+
+## 상태 상세
+
+핵심 디자인 컨설팅 워크플로우는 로컬 릴리스 기준으로 준비되어 있어요. 웹사이트 개선 컨트롤 타워는 [`docs/website-console/index.html`](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은 여전히 현재 배포 범위 밖이에요.
+
+`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 수정은 이 명령에서 수행하지 않아요.
+
+## 기여하기 게이트 상세
+
+- 릴리스 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을 보존하는지 검증해요.