@design-ai/cli 4.55.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,11 +2,11 @@
 
 design-ai를 이 레포에서 어댑터의 Claude Code 환경으로 가져오는 방법.
 
-> 배포 상태, 2026-06-23 확인: 로컬 `npm run release:check`는 통과했고 GitHub Pages 문서는 공개 URL에서 확인됐어요. public npm과 VS Code Marketplace 배포는 아직 확인되지 않았으므로 package publish가 끝나기 전까지는 Git clone/local install 경로를 사용하세요. 자세한 내용은 [`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)를 확인하세요.
 
 ## 설치 경로
 
-### A. Git clone / local install (현재 추천)
+### A. Git clone / local install
 
 ```bash
 git clone https://github.com/sungjin9288/design-ai.git
@@ -17,14 +17,13 @@ cd design-ai
 소스가 작업 클론에 있어요. 업데이트는 `git pull && ./install.sh`.
 
 이 경로를 사용할 때:
-- public package publish 전에 design-ai를 사용할 때
 - upstream에 기여할 때
 - knowledge / skills를 로컬에서 수정할 때
 - publish된 release보다 최신 `main`을 추적할 때
 
-### B. NPM (public publish 이후)
+### B. NPM
 
-`@design-ai/cli`가 publish되고 `npm run registry:smoke`가 통과한 뒤에만 이 경로를 사용하세요.
+public package 설치 경로예요. `@design-ai/cli@4.56.0` publish와 public registry smoke 통과가 확인됐어요.
 
 ```bash
 # npx로 일회성 (글로벌 설치 없음)
@@ -49,6 +48,35 @@ design-ai install
 
 검증된 tap release 이후에는 코퍼스가 Homebrew의 `libexec`에 설치되고 `design-ai` 바이너리가 PATH에 추가돼요.
 
+### D. VS Code Marketplace
+
+VS Code 확장은 `vscode-extension/`에 있어요. 공개 Marketplace publish는 수동 `Publish VS Code extension` GitHub Actions workflow로 처리해요.
+
+현재 공개 package:
+
+```text
+sungjin.design-ai-vscode@0.4.1
+```
+
+2026-06-30에 `0.4.1` listing copy correction publish run이 성공했고, propagation 이후 public Gallery API도 visible version `0.4.1`을 반환했어요.
+
+이 workflow의 기본값은 `dry_run=true`예요. 이 모드에서는 extension compile, unit test, `.vsix` packaging, workflow artifact 업로드까지만 실행하고 Marketplace publish는 하지 않아요.
+
+공개 publish 절차:
+
+1. `vscode-extension/package.json`의 Marketplace publisher id를 확인해요.
+2. Marketplace publish용 Azure DevOps Personal Access Token을 만들어요.
+   - Organization: **All accessible organizations**
+   - Scopes: **Marketplace → Manage**
+   - Expiration: 이번 release에 필요한 가장 짧은 기간
+3. 이 token을 repository secret `VSCE_PAT`로 추가해요.
+4. **Actions → Publish VS Code extension → Run workflow**에서 `dry_run=false`로 실행해요.
+5. `sungjin.design-ai-vscode` Marketplace listing이 검색되는지 확인해요.
+
+Microsoft의 현재 Marketplace publish 안내에 따르면 Azure DevOps global PAT는 2026-12-01에 retired 돼요. 이번 release handoff에는 `VSCE_PAT`를 사용하되, 그 전까지 Entra ID 기반 publish로 전환하는 계획을 잡아야 해요.
+
+2026-06-30 publish run은 `dry_run=false`로 성공했고 Marketplace Gallery API가 `sungjin.design-ai-vscode` listing 1개를 반환했으며 browser item URL도 HTTP `200`으로 확인됐어요.
+
 ## CLI 명령어
 
 ```
@@ -114,6 +142,8 @@ design-ai help [cmd|--json] 전체 또는 command별 도움말; --json으로 top
 - Packed-tarball smoke는 installed-bin과 one-shot `npm exec --package <tarball>` 경로에서 `design-ai learn --signals` learning signal registry, Markdown signal report `design-ai learn --signals --report --out learning-signals.md`, learn signals JSON `--out` file-write confirmation, `design-ai learn --signals --strict --json` strict gate, `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, optional refresh-only runbook selection reason이 no-command refresh output을 executable handoff command가 아닌 status metadata로 다루는지도 확인하고, `design-ai learn --propose-skills` skill proposal의 human, JSON, Markdown `--report --out`, read-only review `--review-file`, read-only review-check Markdown report `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --report --out skill-proposal-review-check.md`, read-only accepted proposal apply plan `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --json`, `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan` human apply-plan command contract summary와 `Command contract` section, read-only apply-plan Markdown report `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --report --out skill-proposal-apply-plan.md`, JSON review template `--review-template --out`, unified diff `--patch --out`, JSON `--out` output, `design-ai learn --propose-skills --min-evidence 3 --json` threshold skipping, 그리고 `design-ai learn --propose-skills --strict --json` expected-failure gate도 확인해요.
 - push 준비 시 `npm run ci:local`로 Real-CI parity를 먼저 확인하고, 의도된 `refs/` source-link warning만 허용하며 refs-only warning도 승인된 baseline을 넘지 않는지 함께 검증.
 - 패킹된 tarball을 임시 프로젝트에 설치해 packed-tarball installed-bin 경로를 smoke test하고 같은 public CLI surface를 one-shot `npm exec --package <tarball>` 경로로 다시 검증하며, human `design-ai version`과 `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를 읽어 expected public topic/alias set을 확인하고, 모든 `design-ai help <command>` topic-specific usage 출력 및 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`), 문서화된 help/command alias 출력, `find`, `cat`, `recommend`, `example`, `ex`, `ls`, `lint` functional alias 출력, 세 가지 `list` catalog domain의 human/JSON 출력, human/JSON `search` / `show` / `examples` 출력, 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 `Wrote <path>` 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 Markdown `design-ai learn --signals --report --out learning-signals.md` signal report plus `design-ai learn --signals --strict --json` strict gate plus learn signals `--out` file-write confirmation, human / JSON `design-ai learn --propose-skills` preview-only skill proposal report plus Markdown `--report --out skill-proposals.md` review artifact plus read-only review `--review-file skill-proposals.review.json` decision join plus read-only review-file readiness check `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --json` plus read-only review-check Markdown report `design-ai learn --propose-skills --review-file skill-proposals.review.json --review-check --report --out skill-proposal-review-check.md` plus read-only accepted proposal apply plan `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --json` plus read-only apply-plan Markdown report `design-ai learn --propose-skills --review-file skill-proposals.review.json --apply-plan --report --out skill-proposal-apply-plan.md` plus JSON review template `--review-template --out skill-proposals.review.json` plus unified diff `--patch --out skill-proposals.patch` handoff plus learn skill proposals JSON `--out` file-write confirmation plus `design-ai learn --propose-skills --min-evidence 3 --json` threshold skipping plus `design-ai learn --propose-skills --strict --json` expected-failure gate, 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 / JSON `design-ai learn --curate` archive-first curation output plus usage-aware curation JSON review, human `design-ai update --dry-run` output과 `design-ai update --dry-run --json` machine-readable update plan, fake `CLAUDE_HOME` 기반 human `design-ai install` 출력, `design-ai install --json` machine-readable install lifecycle output, `design-ai doctor --strict` human diagnostics 출력, `design-ai doctor --json` machine-readable diagnostics 출력, 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까지 검증.
+- 긴 package smoke를 실행하기 전에 `NPM_TOKEN` 인증을 확인해요. package-scoped granular token은 더 넓은 scope 목록 조회를 거부할 수 있어서 package-list 확인은 advisory로만 다뤄요.
+- token 기반 CI publish는 npm 정책상 interactive 2FA 또는 Bypass 2FA가 켜진 granular access token이 필요해요. 장기적으로는 package와 workflow가 지원할 때 Trusted Publishing이 더 나은 경로예요.
 - `--provenance`로 publish (npm provenance attestation).
 - publish 후 공개 npm registry package를 `npm exec --package @design-ai/cli@<version>` 경로로 smoke test하고, human version과 `design-ai version --json` machine-readable version metadata, `design-ai help` top-level help 출력, expected `design-ai help --json` catalog with probe-capable Website Console site help usage, 발견된 help topic usage 출력 및 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`), 문서화된 help/command alias 출력, `find`, `cat`, `recommend`, `example`, `ex`, `ls`, `lint` 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 강제 output-file과 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, human `design-ai install` 출력과 `design-ai install --json` machine-readable install lifecycle output, `design-ai doctor --strict` human diagnostics 출력, `design-ai doctor --json` machine-readable diagnostics 출력, 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도 함께 검증.
 - Public registry workspace readiness coverage는 공개 npm registry `design-ai workspace --strict --json` strict 실패/성공 readiness checks를 published package path에서 확인해요.
@@ -237,7 +267,6 @@ chown -R $USER ~/.claude
 
 - **Homebrew tap → homebrew-core** — 코퍼스가 안정화되면 정식 등록.
 - **Claude Code 플러그인 마켓플레이스** — 그 생태계가 성숙하면.
-- **VS Code Marketplace publish** — 로컬 확장을 public install surface로 전환.
 - **Docker 이미지** — CI / 샌드박스 환경용.
 
 ## 교차 참조

package/docs/DISTRIBUTION.md

@@ -2,11 +2,11 @@
 
 How design-ai gets from this repo into adopters' Claude Code installations.
 
-> Distribution status, checked 2026-06-23: local `npm run release:check` passes and GitHub Pages docs are live. Public npm and VS Code Marketplace distribution are not currently confirmed, so use the Git clone/local install path until package publishing is completed. 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
 
-### A. Git clone / local install (currently recommended)
+### A. Git clone / local install
 
 ```bash
 git clone https://github.com/sungjin9288/design-ai.git
@@ -17,14 +17,13 @@ cd design-ai
 The source is your working clone. Pull updates with `git pull && ./install.sh`.
 
 Use this path if you want to:
-- Use design-ai before public package publish.
 - Contribute back upstream.
 - Modify knowledge / skills locally.
 - Track latest `main` rather than published releases.
 
-### B. NPM (after public publish)
+### B. NPM
 
-Use this path only after `@design-ai/cli` is published and `npm run registry:smoke` passes.
+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)
@@ -43,6 +42,35 @@ After install, the CLI symlinks the bundled corpus into `~/.claude/skills/`, `~/
 
 For environments where neither npm nor bash works the way you expect. See [PLUGIN-PACKAGING.md](PLUGIN-PACKAGING.md) for the manual symlink loop.
 
+### D. VS Code Marketplace
+
+The VS Code extension lives in `vscode-extension/`. Public Marketplace publish is handled by the manual `Publish VS Code extension` GitHub Actions workflow.
+
+Current public package:
+
+```text
+sungjin.design-ai-vscode@0.4.1
+```
+
+The `0.4.1` listing-copy correction publish run succeeded on 2026-06-30, and the public Gallery API returned visible version `0.4.1` after propagation.
+
+The workflow defaults to `dry_run=true`, which compiles the extension, runs unit tests, packages a `.vsix`, and uploads the VSIX as a workflow artifact without publishing.
+
+To publish publicly:
+
+1. Confirm the Marketplace publisher id in `vscode-extension/package.json`.
+2. Create an Azure DevOps Personal Access Token for Marketplace publishing:
+   - Organization: **All accessible organizations**
+   - Scopes: **Marketplace → Manage**
+   - Expiration: shortest practical lifetime for this release
+3. Add that token as a repository secret named `VSCE_PAT`.
+4. Run **Actions → Publish VS Code extension → Run workflow** with `dry_run=false`.
+5. Verify the Marketplace listing for `sungjin.design-ai-vscode`.
+
+Microsoft's current Marketplace publishing guidance warns that Azure DevOps global PATs retire on 2026-12-01. Use `VSCE_PAT` for the current release handoff, then plan a migration to Entra ID based publishing before that date.
+
+The 2026-06-30 publish run completed successfully with `dry_run=false`, the Marketplace Gallery API returned one listing for `sungjin.design-ai-vscode`, and the browser item URL returned HTTP `200`.
+
 ## CLI commands
 
 ```
@@ -98,6 +126,8 @@ For releases, both must match. The publish workflow enforces this:
 The workflow:
 - Verifies tag matches `package.json` version.
 - Verifies `package.json` and `plugin.json` versions match.
+- Verifies `NPM_TOKEN` can authenticate before the long package smoke runs; package-list access is advisory because package-scoped granular tokens can refuse broader scope listing.
+- For token-based CI publish, npm requires either an interactive 2FA flow or a granular access token with Bypass 2FA enabled. Trusted Publishing is the preferred long-term path when it is available for the package/workflow.
 - Runs `npm run audit:strict` for all 8 audits (frontmatter / link / Korean copy / raw hex / integration / stale / coverage / example QA).
 - Runs `npm test` CLI unit tests before publishing or attaching release assets.
 - Runs whitespace checks with `git diff --check` before packaging.
@@ -209,11 +239,8 @@ Adopters can download the tarball, extract it, and run `./install.sh` directly.
 
 Possibilities (not yet implemented):
 
-- **Homebrew tap** — `brew install design-ai`
 - **Claude Code plugin marketplace** — once that ecosystem matures, list there
-- **VS Code Marketplace publish** — move the local extension wrapper to a public install surface
 - **Docker image** — for CI / sandboxed environments
-- **Public doc site** (mkdocs / docusaurus) — for browsing knowledge without install
 
 ## Troubleshooting
 

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-CHECKLIST.md

@@ -191,6 +191,7 @@ After the tag is live:
 - [ ] Verify public install path: `npm run registry:smoke`
 - [ ] Verify doc site updated: visit deployed URL
 - [ ] If breaking change in major version: update Homebrew formula sha256 + version.
+- [ ] If publishing the VS Code extension: run `Publish VS Code extension` with `dry_run=true`, then re-run with `dry_run=false` after `VSCE_PAT` is configured.
 - [ ] Optional: GitHub release notes (auto-generated from CHANGELOG.md section).
 
 ## For major versions (vN.0.0)
@@ -229,11 +230,27 @@ Walk through all knowledge files with `stability: experimental` or `stability: b
 
 Separate from npm:
 
+1. Confirm `vscode-extension/package.json` has the correct `publisher` and `version`.
+2. Create an Azure DevOps Personal Access Token for Marketplace publishing:
+   - Organization: **All accessible organizations**
+   - Scopes: **Marketplace → Manage**
+   - Expiration: shortest practical lifetime for this release
+3. Add that token as repository secret `VSCE_PAT`.
+4. Run **Actions → Publish VS Code extension → Run workflow** with `dry_run=true`.
+5. Inspect the uploaded VSIX artifact.
+6. Re-run the same workflow with `dry_run=false` to publish.
+7. Verify the `sungjin.design-ai-vscode` Marketplace listing.
+
+If `vsce publish` returns 401/403, first check that the token was created with **All accessible organizations** and **Marketplace → Manage**. Microsoft's current guidance also warns that Azure DevOps global PATs retire on 2026-12-01, so migrate this workflow to Entra ID based publishing before that date.
+
+Local equivalent for package-only validation:
+
 ```bash
 cd vscode-extension
-npm install
-npx @vscode/vsce package        # produces .vsix
-npx @vscode/vsce publish        # requires Azure DevOps PAT + publisher account
+npm ci --no-audit --no-fund
+npm run compile
+npm test
+npx --yes @vscode/vsce@latest package --out /tmp/design-ai-vscode-$(node -p "require('./package.json').version").vsix
 ```
 
 Publisher account setup: <https://code.visualstudio.com/api/working-with-extensions/publishing-extension>