@design-ai/cli 4.55.0 → 4.57.0

package/README.md

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

package/cli/bin/design-ai.mjs

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

package/cli/commands/help.mjs

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

package/cli/commands/index.mjs

@@ -0,0 +1,292 @@
+// `design-ai index` — build, inspect, and verify the local retrieval index.
+// Explicit-only: nothing here runs in the background or on behalf of other commands.
+
+import { DESIGN_AI_HOME } from "../lib/paths.mjs";
+import { dim, header, info, success, warn } from "../lib/log.mjs";
+import {
+  buildEmbeddingIndex,
+  embeddingIndexStatus,
+  loadEmbeddingIndexFile,
+  writeEmbeddingIndex,
+} from "../lib/embedding-index.mjs";
+import { configuredEmbeddingProvider, defaultConfigFile } from "../lib/local-config.mjs";
+import {
+  buildCorpusIndex,
+  buildLearningIndex,
+  defaultIndexDir,
+  retrievalIndexStatus,
+  verifyRetrievalIndexes,
+  writeRetrievalIndexes,
+} from "../lib/retrieval-index.mjs";
+import { defaultLearningFile } from "../lib/learn-shared.mjs";
+import { unknownOptionMessage } from "../lib/suggest.mjs";
+
+const INDEX_OPTIONS = ["-h", "--help", "--build", "--status", "--verify", "--json", "--embeddings", "--provider"];
+
+// A bare --provider command string is split on spaces (documented here and in
+// printHelp): "python3 embed.py --quiet" -> command "python3", args ["embed.py",
+// "--quiet"]. Providers whose command or args need spaces/quoting should be
+// configured via ~/.design-ai/config.json embeddings.provider.args instead — that
+// is the robust path; --provider is the quick one-shot override.
+function parseProviderFlag(value) {
+  const parts = String(value || "").trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return null;
+  return { command: parts[0], args: parts.slice(1) };
+}
+
+export function parseIndexArgs(args) {
+  const out = { action: "status", json: false, help: false, embeddings: false, provider: "" };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "-h" || arg === "--help") {
+      out.help = true;
+    } else if (arg === "--json") {
+      out.json = true;
+    } else if (arg === "--build") {
+      out.action = "build";
+    } else if (arg === "--status") {
+      out.action = "status";
+    } else if (arg === "--verify") {
+      out.action = "verify";
+    } else if (arg === "--embeddings") {
+      out.embeddings = true;
+    } else if (arg === "--provider") {
+      out.provider = args[i + 1] || "";
+      i += 1;
+    } else {
+      throw new Error(unknownOptionMessage("index", arg, INDEX_OPTIONS));
+    }
+  }
+  return out;
+}
+
+function printHelp() {
+  console.log("Usage:  design-ai index [--build|--status|--verify] [--json] [--embeddings [--provider \"cmd args\"]]\n");
+  console.log("Manages the local retrieval index (derived, rebuildable cache files).");
+  console.log("Index files stay on this machine and are safe to delete at any time.\n");
+  console.log("Options:");
+  console.log("  --build     Build/refresh the corpus + learning retrieval index (explicit, never background)");
+  console.log("  --status    Report index paths, digests, staleness, and document counts. Default action");
+  console.log("  --verify    Rebuild in memory and compare against the stored index; read-only");
+  console.log("  --json      Emit machine-readable output");
+  console.log("  --embeddings          Also build the opt-in local embedding sidecar (requires a provider)");
+  console.log("  --provider \"cmd args\" Embedding provider command for this invocation (overrides config).");
+  console.log("                        Split on spaces; for commands needing quoting, use the config file's");
+  console.log("                        embeddings.provider.args array instead (~/.design-ai/config.json)");
+  console.log("\nEmbeddings are never built by default: --embeddings requires a provider from --provider or");
+  console.log("~/.design-ai/config.json (embeddings.provider), and both a config AND the --embeddings flag");
+  console.log("are required — config alone never silently enables it.");
+}
+
+function statusLine(label, entry) {
+  if (!entry.present) return `${label}: missing (run design-ai index --build)`;
+  if (entry.error) return `${label}: unreadable — ${entry.error}`;
+  const freshness = entry.fresh ? "fresh" : "stale (run design-ai index --build)";
+  return `${label}: ${freshness} — ${entry.documentCount} documents, generated ${entry.generatedAt}`;
+}
+
+function embeddingsStatusLine(embeddings) {
+  if (!embeddings) return "Embeddings: not built (opt-in; design-ai index --build --embeddings --provider ...)";
+  if (embeddings.error) return `Embeddings: unreadable — ${embeddings.error}`;
+  const freshness = embeddings.fresh ? "fresh" : "stale (run design-ai index --build --embeddings)";
+  const providerLabel = embeddings.provider ? ` (provider: ${embeddings.provider.command})` : "";
+  return `Embeddings: ${freshness} — ${embeddings.documentCount} vectors, generated ${embeddings.generatedAt}${providerLabel}`;
+}
+
+function printStatus(status) {
+  header("design-ai index", "status");
+  info(`Index dir: ${status.indexDir}`);
+  info(statusLine("Corpus index", status.corpus));
+  info(statusLine("Learning index", status.learning));
+  info(embeddingsStatusLine(status.embeddings));
+  if (status.fresh) {
+    success("Index is fresh.");
+  } else {
+    warn(`Index is not fresh. Rebuild with: ${status.buildCommand}`);
+  }
+}
+
+function resolveProvider({ flagProvider, configFile }) {
+  if (flagProvider) return { provider: parseProviderFlag(flagProvider), source: "flag" };
+  const configured = configuredEmbeddingProvider(configFile);
+  if (configured) return { provider: configured, source: "config" };
+  return { provider: null, source: "" };
+}
+
+function embeddingsUnavailableError({ configFile }) {
+  return [
+    "--embeddings requires a provider: pass --provider \"command args\" for this invocation,",
+    `or configure embeddings.provider in ${configFile} (see docs/AI-LEARNING-PHASE2.md, Phase B).`,
+  ].join("\n");
+}
+
+// index --status embeddings section shape (nullable, present only when the sidecar
+// file exists): { file, present, fresh, sourceMatch, generatedAt, documentCount,
+// provider, storedDigest, currentDigest, error }. Positioned after "learning" and
+// before top-level "fresh" in the JSON payload (documented contract).
+function embeddingsStatusSection(context) {
+  const raw = embeddingIndexStatus(context);
+  if (!raw.present) return null;
+  return raw;
+}
+
+export async function runIndex(args) {
+  const parsed = parseIndexArgs(args);
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  const context = {
+    designAiPath: DESIGN_AI_HOME,
+    indexDir: defaultIndexDir(),
+    learningFile: defaultLearningFile(),
+  };
+  const configFile = defaultConfigFile();
+
+  if (parsed.action === "build") {
+    const corpus = buildCorpusIndex({ designAiPath: context.designAiPath });
+    const learning = buildLearningIndex({ filePath: context.learningFile });
+    const written = writeRetrievalIndexes({ indexDir: context.indexDir, corpus, learning });
+
+    let embeddingsResult = null;
+    if (parsed.embeddings) {
+      const { provider } = resolveProvider({ flagProvider: parsed.provider, configFile });
+      if (!provider) {
+        embeddingsResult = { ok: false, error: embeddingsUnavailableError({ configFile }) };
+      } else {
+        const built = buildEmbeddingIndex({
+          provider,
+          designAiPath: context.designAiPath,
+          learningFile: context.learningFile,
+        });
+        if (built.ok) {
+          const writtenEmbeddings = writeEmbeddingIndex({ indexDir: context.indexDir, payload: built.payload });
+          embeddingsResult = {
+            ok: true,
+            file: writtenEmbeddings.file,
+            documentCount: built.payload.vectors.length,
+            provider: { command: built.payload.provider.command, modelLabel: built.payload.provider.modelLabel, dimensions: built.payload.provider.dimensions },
+          };
+        } else {
+          embeddingsResult = { ok: false, error: built.error };
+        }
+      }
+    }
+
+    if (parsed.json) {
+      const payload = {
+        action: "build",
+        indexDir: context.indexDir,
+        corpus: { file: written.corpusFile, documentCount: corpus.stats.documentCount, digest: corpus.source.corpusDigest },
+        learning: { file: written.learningFile, documentCount: learning.stats.documentCount, digest: learning.source.learningDigest },
+      };
+      if (embeddingsResult) payload.embeddings = embeddingsResult;
+      console.log(JSON.stringify(payload, null, 2));
+      if (embeddingsResult && !embeddingsResult.ok) process.exitCode = 1;
+      return;
+    }
+
+    header("design-ai index", "build");
+    info(`Corpus index: ${written.corpusFile} (${corpus.stats.documentCount} documents)`);
+    info(`Learning index: ${written.learningFile} (${learning.stats.documentCount} entries)`);
+    success("Index built.");
+    if (embeddingsResult) {
+      if (embeddingsResult.ok) {
+        success(`Embedding index built: ${embeddingsResult.file} (${embeddingsResult.documentCount} vectors)`);
+      } else {
+        warn(`Embedding index not built: ${embeddingsResult.error}`);
+        process.exitCode = 1;
+      }
+    }
+    return;
+  }
+
+  if (parsed.action === "verify") {
+    const verify = verifyRetrievalIndexes(context);
+    const embeddings = embeddingsStatusSection(context);
+    let embeddingsCheck = null;
+    if (embeddings) {
+      if (embeddings.error) {
+        embeddingsCheck = { name: "embeddings", file: embeddings.file, matches: false, reason: embeddings.error };
+      } else {
+        const { provider } = resolveProvider({ flagProvider: parsed.provider, configFile });
+        if (!provider) {
+          embeddingsCheck = {
+            name: "embeddings",
+            file: embeddings.file,
+            matches: true,
+            skipped: true,
+            reason: "skipped: provider unavailable (pass --provider or configure ~/.design-ai/config.json to verify embedding content)",
+          };
+        } else {
+          const rebuilt = buildEmbeddingIndex({
+            provider,
+            designAiPath: context.designAiPath,
+            learningFile: context.learningFile,
+          });
+          if (!rebuilt.ok) {
+            embeddingsCheck = {
+              name: "embeddings",
+              file: embeddings.file,
+              matches: true,
+              skipped: true,
+              reason: `skipped: provider unavailable (${rebuilt.error})`,
+            };
+          } else {
+            const stored = loadEmbeddingIndexFile(embeddings.file);
+            const normalize = (payload) => {
+              const { generatedAt, ...rest } = payload || {};
+              return JSON.stringify(rest);
+            };
+            const matches = normalize(stored.payload) === normalize(rebuilt.payload);
+            embeddingsCheck = {
+              name: "embeddings",
+              file: embeddings.file,
+              matches,
+              reason: matches ? "" : "stored embedding index differs from an in-memory rebuild of its sources",
+            };
+          }
+        }
+      }
+      verify.checks.push(embeddingsCheck);
+      verify.ok = verify.ok && (embeddingsCheck.matches !== false);
+    }
+
+    if (parsed.json) {
+      console.log(JSON.stringify({ action: "verify", ...verify }, null, 2));
+    } else {
+      header("design-ai index", "verify");
+      for (const check of verify.checks) {
+        if (check.matches) {
+          info(check.skipped ? `${check.name}: ${check.reason}` : `${check.name}: matches an in-memory rebuild`);
+        } else {
+          warn(`${check.name}: ${check.reason}`);
+          console.log(`  ${dim(check.file)}`);
+        }
+      }
+      if (verify.ok) success("Stored index matches its sources.");
+    }
+    if (!verify.ok) process.exitCode = 1;
+    return;
+  }
+
+  const status = retrievalIndexStatus(context);
+  const embeddings = embeddingsStatusSection(context);
+  const fresh = embeddings ? status.fresh && embeddings.fresh : status.fresh;
+  // Key order is a documented contract (embeddings sits after learning, before
+  // fresh) — build the object explicitly rather than relying on spread order.
+  const fullStatus = {
+    indexDir: status.indexDir,
+    corpus: status.corpus,
+    learning: status.learning,
+    embeddings,
+    fresh,
+    buildCommand: status.buildCommand,
+  };
+  if (parsed.json) {
+    console.log(JSON.stringify({ action: "status", ...fullStatus }, null, 2));
+    return;
+  }
+  printStatus(fullStatus);
+}