@design-ai/cli 4.57.0 → 4.59.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "design-ai",
-  "version": "4.57.0",
+  "version": "4.59.0",
   "description": "Senior product designer for any AI coding agent. 20 skills, 17 commands, 4 review agents covering UI/UX, website improvement, design systems, motion, illustration, print, video, game UI, conversational, and spatial design. Korean market depth.",
   "author": {
     "name": "Sungjin Park",

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 User-facing release notes for design-ai. Versions follow semver.
 
+## v4.59.0 — Agent SDK Phase A (2026-07)
+
+Adds a curated, semver-stable programmatic surface — `@design-ai/cli/sdk` — so an external Node.js program can call design-ai's deterministic design verbs as importable functions, without shelling out to the CLI or spawning the MCP server. The SDK is a thin adapter over the same `cli/lib` functions the CLI and MCP already call, so no design behavior changes. Phase A is read-only: no file writes, no network, no runtime dependencies. All additions are additive and backward-compatible.
+
+### Added
+- `@design-ai/cli/sdk` — eight read-only adapter verbs with their own stable signatures: `route(brief, opts)`, `prompt(brief, opts)`, `pack(brief, opts)`, `search(query, opts)`, `recall(query, opts)`, `check(artifact, opts)`, `routes()`, and `version()`. Each validates its inputs, resolves the package root the same way the CLI does, and returns the same JSON-serializable shape the CLI's `--json` mode emits. `check` operates on artifact content (not a path), so it reads and writes nothing.
+- `package.json` `exports` map exposing `./sdk` (and `./package.json`) as the only public import paths; `cli/lib/*` stays internal and unstable, refactorable behind the adapter seam.
+- `docs/SDK.md` — the public SDK reference (surface, return shapes, semver stability contract) — plus a "Node.js / Agent SDK" row in the README install tables and an Agent SDK mkdocs nav section.
+
+### Changed
+- `npm test` now also runs `cli/sdk/*.test.mjs` (61 new SDK tests, 540 total), including a contract test (`cli/sdk/index.test.mjs`) that pins the eight exported names and their return-shape keys — the semver anchor — and asserts Phase A writes no `learningUsage` sidecar.
+- `tools/audit/package-smoke.py` now imports `@design-ai/cli/sdk` from the installed tarball and exercises the eight verbs, asserting determinism and the read-only guarantee.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check`.
+- `npm run release:metadata`.
+- `git diff --check`.
+- Main-branch GitHub Actions (`Design-AI audit`, `Deploy doc site`) passed for the constituent commits.
+
+### Versions
+- `package.json` + `.claude-plugin/plugin.json`: 4.58.0 → 4.59.0.
+- `vscode-extension/package.json`: remains 0.4.1.
+
+### What this enables
+- Agent runtimes, build scripts, and custom tools can consume design-ai's routing, prompt/pack generation, ranked search, recall, and artifact checks as plain functions — deterministic, in-process, zero-dependency — with a semver-stable contract independent of the internal `cli/lib` shapes.
+
+## v4.58.0 — Retrieval Across Surfaces and Corpus Depth (2026-07)
+
+Completes the retrieval integration started in v4.57.0 by bringing it to the last untouched surface (`route --explain`), refines recall quality so injected knowledge is real design guidance rather than index files, and closes the remaining dogfood-named corpus gaps. All additions are additive and backward-compatible; default output is unchanged unless a flag is passed.
+
+### Added
+- `route --explain` now includes an advisory "Related knowledge" section — brief-relevant corpus knowledge recalled by the shared lexical scorer, excluding what the route already curates. This is advisory only: route ids, scores, and curated knowledge are unchanged, and default `route` output is byte-unchanged. `design_ai_route`'s existing `explain` parameter carries it to MCP automatically. Retrieval now spans every surface: `search --ranked`, `prompt`/`pack --with-recall`, `learn --recall`, and `route --explain`.
+- `knowledge/patterns/async-control.md` — the async action in-flight lifecycle: pending states, double-submit prevention, duration-matched loading affordances, optimistic updates with rollback, debounce/throttle, cancellation and out-of-order handling, concurrency policy, timeouts, and the accessibility floor.
+- `knowledge/i18n/korean-density-conventions.md` — Korean B2B/enterprise density: the density ladder, table-first layouts, label-left multi-column forms, dense navigation, typography at density, and where density must yield to accessibility.
+
+### Changed
+- Recall injection surfaces (`prompt`/`pack --with-recall`, `learn --recall`, `route --explain`) now exclude generated index/meta files (`COVERAGE.md`, `INDEX.md`, `docs/reference/*`) so injected context is real design knowledge; raw `search --ranked` still returns those files when explicitly searched.
+- Knowledge corpus is now 94 files (from 92).
+
+### Fixed
+- `tools/audit/registry-smoke.py`'s learn-relevance assertion expected a stale token order (`keyboard, accessibility`) after the v4.57 shared-scorer change sorted matched tokens; aligned it with `package-smoke.py` and the real CLI output so the live post-publish registry smoke matches the published package.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check`.
+- `npm run release:metadata`.
+- `git diff --check`.
+- Main-branch GitHub Actions (`Design-AI audit`, `Deploy doc site`) passed for the constituent commits.
+
+### Versions
+- `package.json` + `.claude-plugin/plugin.json`: 4.57.0 → 4.58.0.
+- `vscode-extension/package.json`: remains 0.4.1.
+
+### What this enables
+- Agents routing a brief now see additional relevant knowledge beyond the route's curated set, and every retrieval surface injects real design guidance rather than index tables.
+- The Korean-market corpus gains async-control and B2B density coverage that dogfood runs specifically named as missing.
+- Publishing v4.58.0 realigns `main` with the published package so the live registry smoke verifies cleanly again.
+
 ## v4.57.0 — Local Retrieval Memory: Ranked Search and Optional Embeddings (2026-07)
 
 Ships the Phase 754 AI-learning retrieval work: a deterministic, zero-dependency local retrieval layer over the knowledge corpus and the local learning profile, plus an opt-in local embedding rerank backend. Defaults are unchanged — `search`, `route`, `prompt`, and `pack` behave exactly as before unless a new flag is passed — so this release is additive and backward-compatible. It also moves `refs/` source links behind generated reference pages and hardens the docs deploy against intermittent GitHub Pages failures.

package/README.ko.md

@@ -2,7 +2,7 @@
 
 [![Audit](https://img.shields.io/badge/audit-passing-brightgreen)](https://github.com/sungjin9288/design-ai/actions/workflows/audit.yml)
 [![Docs](https://img.shields.io/badge/docs-live-indigo)](https://sungjin9288.github.io/design-ai/ko/)
-[![Knowledge files](https://img.shields.io/badge/knowledge-92-blue)](knowledge/PRINCIPLES.md)
+[![Knowledge files](https://img.shields.io/badge/knowledge-94-blue)](knowledge/PRINCIPLES.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)
 
@@ -12,7 +12,7 @@
 
 > **모델이 아니에요. 파인튜닝도 아니에요.** 디자인 전문 지식을 구조화한 코퍼스 + 에이전트가 바로 실행할 수 있는 지시문이에요. 범용 LLM을 이번 세션에서만큼은 시니어 디자이너로 바꿔주는 셈이에요.
 
-> **배포 상태, 2026-07-02 확인:** 로컬 `npm run release:check`는 통과했고, GitHub Pages 문서는 live 상태이며, GitHub Release `v4.56.0`과 npm `@design-ai/cli@4.56.0` publish 및 registry smoke가 확인됐어요. Homebrew formula는 `v4.56.0`에 pinning되어 있고, VS Code Marketplace에는 `sungjin.design-ai-vscode@0.4.1`이 공개되어 있어요. 자세한 내용은 [`docs/external-status.md`](docs/external-status.md)를 확인하세요.
+> **배포 상태, 2026-07-04 확인:** 로컬 `npm run release:check`는 통과했고, GitHub Pages 문서는 live 상태이며, GitHub Release `v4.58.0`과 npm `@design-ai/cli@4.58.0`(`latest`) publish가 provenance와 함께 확인됐어요. 수정 후 live `npm run registry:smoke`가 published `@design-ai/cli@4.58.0`에 대해 깨끗이 통과했어요(retrieval 표면과 route enrichment 포함). Homebrew formula는 `v4.58.0`에 pinning되어 있고, VS Code Marketplace에는 `sungjin.design-ai-vscode@0.4.1`이 공개되어 있어요. 자세한 내용은 [`docs/external-status.md`](docs/external-status.md)를 확인하세요.
 
 ## 한눈에 보는 커버리지
 
@@ -88,6 +88,7 @@ CLI 명령어: `design-ai install [--json]`, `update [--dry-run] [--json]`, `uni
 | **Cursor** | 이 폴더를 열고 `AGENTS.md`를 `.cursorrules`로 심볼릭 링크하거나 복사해요. [워크스루](docs/integrations/cursor-walkthrough.md). |
 | **Aider** | `AGENTS.md`를 시스템 프롬프트로 전달해요. [워크스루](docs/integrations/aider-walkthrough.md). |
 | **Anthropic / OpenAI SDK** | 관련 스킬 `PLAYBOOK.md` 파일을 프롬프트에 포함시켜요. [워크스루](docs/integrations/sdk-walkthrough.md). |
+| **Node.js / Agent SDK** | `import { route, prompt, pack, search, recall, check, routes, version } from "@design-ai/cli/sdk"` — CLI 셸 실행이나 MCP 서버 없이 design-ai의 결정적 기능을 함수로 바로 호출해요. 읽기 전용(Phase A). [SDK 레퍼런스](docs/SDK.md). |
 | **일반 프롬프트** | 어떤 `skills/*/PLAYBOOK.md` 본문이든 붙여넣으세요 — 각각 자기 완결적이에요. |
 
 에이전트별 설치 방법은 [`docs/USING.md`](docs/USING.md)를, 구체적인 사용 예시는 위 워크스루 링크를 참고하세요.
@@ -107,7 +108,7 @@ design-ai/
 │
 ├── refs/                    # Sparse-clone된 업스트림 소스 (gitignored)
 │
-├── knowledge/               # 92개 손으로 쓴 + 추출된 지식 파일
+├── knowledge/               # 94개 손으로 쓴 + 추출된 지식 파일
 │   ├── design-tokens/       # W3C DTCG, OKLCH, HCT
 │   ├── components/          # Ant + MUI + shadcn 합성
 │   ├── patterns/            # 인증, 가격, 랜딩 히어로, 브랜드, 이메일 등
@@ -171,7 +172,7 @@ design-ai는 한국 시장을 1순위로 만들어졌고, 글로벌 시장 패
 
 ## 상태
 
-전체 단계 로그는 [`docs/ROADMAP.md`](docs/ROADMAP.md), 현재 완료 범위는 [`docs/PRODUCT-READINESS.md`](docs/PRODUCT-READINESS.md)에서 확인하세요. 현재 **v4.56.0**: public npm publish, provenance-backed GitHub Actions release, public registry smoke, Website Console MCP readiness, workspace learning restore/eval coverage, handoff bundle verification, 90%+ component coverage가 완료됐어요.
+전체 단계 로그는 [`docs/ROADMAP.md`](docs/ROADMAP.md), 현재 완료 범위는 [`docs/PRODUCT-READINESS.md`](docs/PRODUCT-READINESS.md)에서 확인하세요. 현재 **v4.58.0**: public npm publish, provenance-backed GitHub Actions release, public registry smoke, Website Console MCP readiness, workspace learning restore/eval coverage, handoff bundle verification, 90%+ component coverage가 완료됐어요.
 
 핵심 디자인 컨설팅 워크플로우는 로컬 릴리스 기준으로 준비되어 있어요. 웹사이트 개선 컨트롤 타워는 zero-dependency static Web App과 `website-improvement` route/skill/command로 제공되고, Site Profile, audit checklist, MCP readiness, refactor prompt, handoff evidence tracking, bundle export/verify/repair를 한 번에 다뤄요. 로컬 학습 선호도는 `design-ai learn`으로 관리해요 — profile bootstrap, feedback 캡처, 읽기 전용 signal registry, 반복 QA 신호에서 만드는 skill 제안, 그리고 backup/restore/curate/audit까지 전부 로컬에서만 동작하는 opt-in 기능이에요. AI 모델 학습이나 fine-tuning은 여전히 현재 배포 범위 밖이에요.
 

package/README.md

@@ -2,7 +2,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)
+[![Knowledge files](https://img.shields.io/badge/knowledge-94-blue)](knowledge/PRINCIPLES.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)
 
@@ -12,7 +12,7 @@ A model-agnostic design knowledge base + skill system. Drop it in front of any A
 
 > **Not a model. Not a fine-tune.** A structured corpus of design expertise + agent-ready instructions that turn a general-purpose LLM into an expert.
 
-> **Distribution status, checked 2026-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).
+> **Distribution status, checked 2026-07-04:** local `npm run release:check` passes, GitHub Pages docs are live, GitHub Release `v4.58.0` is published, `@design-ai/cli@4.58.0` is public on npm (`latest`) with provenance, and the live `npm run registry:smoke` passes cleanly against `@design-ai/cli@4.58.0`. The Homebrew formula is pinned to `v4.58.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
 
@@ -89,6 +89,7 @@ See [`docs/DISTRIBUTION.md`](docs/DISTRIBUTION.md) for the full distribution gui
 | **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** | Install the public Marketplace extension for sidebar trees + quick-pick commands. [Walkthrough](docs/integrations/vscode-walkthrough.md). |
+| **Node.js / Agent SDK** | `import { route, prompt, pack, search, recall, check, routes, version } from "@design-ai/cli/sdk"` — call design-ai's deterministic verbs as functions, no CLI shell-out or MCP server needed. Read-only (Phase A). [SDK reference](docs/SDK.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.
@@ -107,7 +108,7 @@ design-ai/
 │
 ├── refs/                    # Sparse-cloned upstream sources (gitignored)
 │
-├── knowledge/               # 92 hand-written + extracted knowledge files
+├── knowledge/               # 94 hand-written + extracted knowledge files
 │   ├── design-tokens/       # Token systems (W3C DTCG, OKLCH, HCT)
 │   ├── components/          # Component synthesis (Ant + MUI + shadcn)
 │   ├── patterns/            # Auth, pricing, landing hero, brand, email, ...
@@ -213,7 +214,7 @@ 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.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.
+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.58.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 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.
 

package/cli/commands/route.mjs

@@ -28,7 +28,7 @@ function printHelp() {
   console.log("  --stdin           Read the task brief, or route eval JSON with --eval, from standard input");
   console.log("  --list            List route ids without scoring a brief");
   console.log("  --limit N         Maximum route recommendations to return, 1-10. Default: 3");
-  console.log("  --explain         Include route scoring and reference coverage details");
+  console.log("  --explain         Include route scoring, reference coverage, and related knowledge");
   console.log("  --eval-template   Generate a runnable route eval checkpoint JSON template");
   console.log("  --eval            Run deterministic route-selection checkpoint cases");
   console.log("  --strict          With --eval, exit non-zero on warning or failure");
@@ -78,6 +78,17 @@ function printRoute(route, index, explain = false) {
   for (const knowledge of route.knowledge) {
     console.log(`   read:    ${formatPath(knowledge)}`);
   }
+
+  if (explain) {
+    const related = route.relatedKnowledge || [];
+    if (related.length === 0) {
+      console.log("   related: (none)");
+    } else {
+      for (const item of related) {
+        console.log(`   related: ${item.id} ${dim(`(score ${item.score.toFixed(2)})`)}`);
+      }
+    }
+  }
 }
 
 function printCatalogRoute(route, index) {
@@ -211,6 +222,7 @@ export async function runRoute(args) {
     brief,
     sourceRoot: DESIGN_AI_HOME,
     limit: parsed.limit,
+    explain: parsed.explain,
   });
 
   const payload = {

package/cli/lib/recall.mjs

@@ -109,7 +109,7 @@ export function buildRecallContext({
   const candidateCount = collectCorpusDocuments({ designAiPath, dirs }).length;
 
   const hits = query
-    ? rankedSearchCorpus({ query, designAiPath, dirs, limit: recallLimit }).hits
+    ? rankedSearchCorpus({ query, designAiPath, dirs, limit: recallLimit, excludeGeneratedIndex: true }).hits
     : [];
 
   const selected = hits.map((hit) => ({
@@ -150,7 +150,7 @@ export function buildLearnRecall({
 
   const corpusCandidateCount = collectCorpusDocuments({ designAiPath, dirs }).length;
   const corpusHits = normalizedQuery
-    ? rankedSearchCorpus({ query: normalizedQuery, designAiPath, dirs, limit }).hits
+    ? rankedSearchCorpus({ query: normalizedQuery, designAiPath, dirs, limit, excludeGeneratedIndex: true }).hits
     : [];
   const corpusSelected = corpusHits.map((hit) => ({
     id: hit.relPath,

package/cli/lib/route.mjs

@@ -7,6 +7,7 @@ import {
 import path from "node:path";
 
 import { parseBriefSourceFlag } from "./brief.mjs";
+import { rankedSearchCorpus } from "./search-ranked.mjs";
 import { suggestNearest, unknownOptionMessage } from "./suggest.mjs";
 
 function exists(p) {
@@ -35,6 +36,17 @@ const ROUTE_OPTIONS = [
 ];
 const ROUTE_EVAL_VERSION = 1;
 const ROUTE_EVAL_DEFAULT_LIMIT = 3;
+// Advisory "Related knowledge" recall (docs/AI-LEARNING-PHASE2.md, "Phase A
+// implementation review" Q3): under `--explain` only, surface the top corpus
+// knowledge/ files recalled by the shipped deterministic lexical scorer that the
+// route's curated `knowledge` list does NOT already point to. Purely additive —
+// it never changes route selection, ids, scores, or the curated list. Restricted
+// to knowledge/ so it surfaces design knowledge, not docs/QUICKSTART. The recall
+// pulls RELATED_KNOWLEDGE_RECALL_LIMIT candidates then keeps the top
+// RELATED_KNOWLEDGE_KEEP after excluding the curated set.
+const RELATED_KNOWLEDGE_DIRS = ["knowledge"];
+const RELATED_KNOWLEDGE_RECALL_LIMIT = 10;
+const RELATED_KNOWLEDGE_KEEP = 3;
 const CONFIDENCE_ORDER = {
   low: 1,
   medium: 2,
@@ -456,6 +468,35 @@ function routeExplanation({ hits, command, skills, agents, knowledge, forced = f
   };
 }
 
+// Advisory related-knowledge recall for a single route. REUSES rankedSearchCorpus
+// (the shipped deterministic lexical scorer — score desc, id asc) scoped to
+// knowledge/, excludes the route's curated knowledge relPaths, and keeps the top
+// RELATED_KNOWLEDGE_KEEP remaining. Returns [] on empty brief or no hits.
+function relatedKnowledgeFor({ brief, sourceRoot, curatedRelPaths }) {
+  const query = String(brief || "").trim();
+  if (!query) return [];
+
+  const curated = new Set(curatedRelPaths);
+  const { hits } = rankedSearchCorpus({
+    query,
+    dirs: RELATED_KNOWLEDGE_DIRS,
+    limit: RELATED_KNOWLEDGE_RECALL_LIMIT,
+    designAiPath: sourceRoot,
+    // Recall/injection surface: keep generated index/meta docs (COVERAGE.md,
+    // INDEX.md, docs/reference/*) out of the advisory related-knowledge list.
+    excludeGeneratedIndex: true,
+  });
+
+  return hits
+    .filter((hit) => !curated.has(hit.relPath))
+    .slice(0, RELATED_KNOWLEDGE_KEEP)
+    .map((hit) => ({
+      id: hit.relPath,
+      score: hit.score,
+      matchedTokens: hit.matchedTokens,
+    }));
+}
+
 function routeToResult(route, sourceRoot, hits, options = {}) {
   const command = route.command
     ? { path: route.command, exists: exists(path.join(sourceRoot, route.command)) }
@@ -467,6 +508,17 @@ function routeToResult(route, sourceRoot, hits, options = {}) {
   const fallback = Boolean(options.fallback);
   const catalog = Boolean(options.catalog);
 
+  // Advisory related-knowledge is attached ONLY when explain is requested, so the
+  // default `route` JSON stays byte-unchanged. `knowledge` already merges
+  // COMMON_KNOWLEDGE + route.knowledge, so its relPaths are the dedupe set.
+  const relatedKnowledge = options.explain
+    ? relatedKnowledgeFor({
+      brief: options.brief || "",
+      sourceRoot,
+      curatedRelPaths: knowledge.map((entry) => entry.path),
+    })
+    : null;
+
   return {
     id: route.id,
     label: route.label,
@@ -479,6 +531,7 @@ function routeToResult(route, sourceRoot, hits, options = {}) {
     knowledge,
     keywords: route.keywords,
     explanation: routeExplanation({ hits, command, skills, agents, knowledge, forced, fallback, catalog }),
+    ...(relatedKnowledge ? { relatedKnowledge } : {}),
     ...(forced ? { forced: true } : {}),
     ...(fallback ? { fallback: true } : {}),
   };
@@ -501,18 +554,22 @@ export function routeById({ routeId, sourceRoot }) {
   };
 }
 
-function fallbackResult(sourceRoot) {
+function fallbackResult(sourceRoot, options = {}) {
   const route = ROUTES.find((item) => item.id === "design-from-brief");
   return {
-    ...routeToResult(route, sourceRoot, [], { fallback: true }),
+    ...routeToResult(route, sourceRoot, [], { fallback: true, ...options }),
     confidence: "low",
   };
 }
 
-export function routeBrief({ brief, sourceRoot, limit = 3 }) {
+export function routeBrief({ brief, sourceRoot, limit = 3, explain = false }) {
   const normalized = brief.trim();
   if (!normalized) return [];
 
+  // Only compute advisory related-knowledge under --explain; keep the default
+  // routing (keyword scoring, ordering, selection) completely unchanged.
+  const resultOptions = explain ? { explain: true, brief: normalized } : {};
+
   const scored = ROUTES
     .map((route) => ({ route, hits: keywordHits(normalized, route.keywords) }))
     .filter((item) => item.hits.length > 0)
@@ -521,10 +578,10 @@ export function routeBrief({ brief, sourceRoot, limit = 3 }) {
       return a.route.label.localeCompare(b.route.label);
     })
     .slice(0, limit)
-    .map((item) => routeToResult(item.route, sourceRoot, item.hits));
+    .map((item) => routeToResult(item.route, sourceRoot, item.hits, resultOptions));
 
   if (scored.length > 0) return scored;
-  return [fallbackResult(sourceRoot)];
+  return [fallbackResult(sourceRoot, resultOptions)];
 }
 
 function isoTimestamp(now = new Date()) {

package/cli/lib/search-ranked.mjs

@@ -24,6 +24,22 @@ import { DEFAULT_SEARCH_DIRS } from "./search.mjs";
 
 const RANKED_PREVIEW_LEN = 120;
 
+// Predicate for GENERATED index/meta docs that must be kept out of the RECALL /
+// context-injection layer (pack/prompt --with-recall, learn --recall corpus side,
+// route --explain related knowledge). These files rank on keyword density but are
+// meta/index tables, not design knowledge worth injecting into an agent's context.
+// Rule: true when the basename is `COVERAGE.md` or `INDEX.md` (generated coverage
+// table / component index), OR the forward-slash-normalized path starts with
+// `docs/reference/` (generated upstream-reference pages). Raw `search --ranked`
+// does NOT apply this — a user explicitly searching may legitimately want an index.
+export function isGeneratedIndexDoc(relPath) {
+  const normalized = String(relPath || "").replace(/\\/g, "/");
+  const basename = normalized.slice(normalized.lastIndexOf("/") + 1);
+  return basename === "COVERAGE.md"
+    || basename === "INDEX.md"
+    || normalized.startsWith("docs/reference/");
+}
+
 // N = max(limit*5, 25): the number of top lexical candidates handed to the embedding
 // reranker. Documented constant (docs/AI-LEARNING-PHASE2.md, Phase B CLI wiring).
 export function embeddingCandidateCount(limit) {
@@ -66,12 +82,28 @@ export function rankedSearchCorpus({
   dirs = DEFAULT_SEARCH_DIRS,
   limit = 20,
   indexDir = defaultIndexDir(),
+  // Opt-in RECALL filter: when true, drop generated index/meta docs
+  // (isGeneratedIndexDoc) BEFORE applying `limit`, so the limit fills with real
+  // knowledge instead of index files. Default false keeps raw `search --ranked`
+  // byte-unchanged. Filtering before the limit preserves determinism (score desc,
+  // id asc) — the rank pass already orders fully, we only remove excluded ids.
+  excludeGeneratedIndex = false,
 } = {}) {
   const documents = collectCorpusDocuments({ designAiPath, dirs });
   const stats = buildLexicalStats(documents.map(({ id, text }) => ({ id, text })));
   const textById = new Map(documents.map((doc) => [doc.id, doc.text]));
 
-  const hits = rankLexical(query, stats, { limit }).map((hit) => ({
+  // When excluding, rank the FULL candidate pool first (limit = documents.length)
+  // so that filtering out index docs cannot let a real-knowledge hit fall off the
+  // pre-limit cutoff; then re-apply `limit`. Ordering is unchanged (score desc, id asc).
+  const ranked = rankLexical(query, stats, {
+    limit: excludeGeneratedIndex ? documents.length : limit,
+  });
+  const filtered = excludeGeneratedIndex
+    ? ranked.filter((hit) => !isGeneratedIndexDoc(hit.id)).slice(0, limit)
+    : ranked;
+
+  const hits = filtered.map((hit) => ({
     relPath: hit.id,
     file: path.join(designAiPath, hit.id),
     score: hit.score,

package/cli/sdk/check-adapter.mjs

@@ -0,0 +1,36 @@
+// SDK adapter: check(artifact, opts). See docs/AGENT-SDK.md.
+//
+// Read-only: capture is never enabled from the SDK in Phase A (the CLI's
+// `--learn` writes a local learning-profile capture; there is no equivalent
+// opt-in here, consistent with "no file writes" for Phase A).
+
+import { checkArtifactContent } from "../lib/check.mjs";
+import { assertKnownRouteId } from "../lib/route.mjs";
+import { optionalBoolean, optionalString, requireNonEmptyString, requireOptions } from "./validate.mjs";
+
+/**
+ * Check a generated design Markdown artifact for grounding, accessibility,
+ * responsive, unresolved-marker, and route-specific requirements. Pure,
+ * read-only adapter over `checkArtifactContent` from cli/lib/check.mjs.
+ *
+ * @param {string} artifact - Markdown artifact content to check.
+ * @param {{routeId?: string, strict?: boolean}} [opts]
+ * @returns {object} CheckReport — the same shape as `design-ai check --json`.
+ */
+export function check(artifact, opts = {}) {
+  requireNonEmptyString(artifact, "artifact");
+  const options = requireOptions(opts, "check");
+
+  const routeId = optionalString(options.routeId, "routeId");
+  if (routeId) assertKnownRouteId(routeId, { allowEmpty: false });
+  // `strict` only affects CLI exit-code behavior; validated for type safety,
+  // but the SDK returns the report as-is and lets the caller decide what to
+  // do with report.status — there is no process exit code to influence here.
+  optionalBoolean(options.strict, "strict", false);
+
+  return checkArtifactContent({
+    content: artifact,
+    filePath: "sdk",
+    routeId,
+  });
+}

package/cli/sdk/index.mjs

@@ -0,0 +1,22 @@
+// design-ai Agent SDK — Phase A (read-only). See docs/AGENT-SDK.md and docs/SDK.md.
+//
+// A curated, semver-stable adapter over the same cli/lib functions the CLI and
+// MCP server call. Each verb validates its inputs, resolves the package root
+// the same way the CLI does, and returns a plain JSON-serializable object —
+// the same shape the CLI's --json mode emits. No network calls, no runtime
+// dependencies. Phase A performs no file writes: no learning-usage sidecar
+// writes, even from prompt/pack's withLearning option.
+//
+// Import path: `@design-ai/cli/sdk` (see the "exports" map in package.json).
+// `cli/lib/*` stays internal and unstable; this barrel is the only supported
+// public surface. Do not import `cli/lib/*.mjs` directly from outside this
+// package — only the 8 named exports below are covered by the semver
+// stability contract described in docs/SDK.md.
+
+export { check } from "./check-adapter.mjs";
+export { pack } from "./pack-adapter.mjs";
+export { prompt } from "./prompt-adapter.mjs";
+export { recall } from "./recall-adapter.mjs";
+export { route, routes } from "./route-adapter.mjs";
+export { search } from "./search-adapter.mjs";
+export { version } from "./version-adapter.mjs";

package/cli/sdk/pack-adapter.mjs

@@ -0,0 +1,55 @@
+// SDK adapter: pack(brief, opts). See docs/AGENT-SDK.md.
+//
+// Phase A is read-only: like the prompt adapter, this never records the
+// learning-usage sidecar, even when withLearning is requested.
+
+import { DESIGN_AI_HOME, SYMLINK_PREFIX } from "../lib/paths.mjs";
+import { buildPromptPack } from "../lib/pack.mjs";
+import {
+  optionalBoolean,
+  optionalInteger,
+  optionalString,
+  requireNonEmptyString,
+  requireOptions,
+} from "./validate.mjs";
+
+const DEFAULT_MAX_BYTES = 120_000;
+
+/**
+ * Build a ready-to-use prompt plus bounded context-file bundle from a task
+ * brief. Pure, read-only adapter over `buildPromptPack` from cli/lib/pack.mjs.
+ * Never records learning-usage, even with withLearning: true.
+ *
+ * @param {string} brief - Task brief text.
+ * @param {{routeId?: string, maxBytes?: number, withLearning?: boolean, learningCategory?: string, learningLimit?: number, withRecall?: boolean, recallLimit?: number}} [opts]
+ * @returns {object} Pack — the same shape as `design-ai pack --json` (minus learningUsage).
+ */
+export function pack(brief, opts = {}) {
+  requireNonEmptyString(brief, "brief");
+  const options = requireOptions(opts, "pack");
+
+  const routeId = optionalString(options.routeId, "routeId");
+  const maxBytes = optionalInteger(options.maxBytes, "maxBytes", {
+    fallback: DEFAULT_MAX_BYTES,
+    min: 1000,
+    max: 1_000_000,
+  });
+  const withLearning = optionalBoolean(options.withLearning, "withLearning", false);
+  const learningCategory = optionalString(options.learningCategory, "learningCategory");
+  const learningLimit = optionalInteger(options.learningLimit, "learningLimit", { fallback: 0, min: 1, max: 100, zeroMeansUnset: true });
+  const withRecall = optionalBoolean(options.withRecall, "withRecall", false);
+  const recallLimit = optionalInteger(options.recallLimit, "recallLimit", { fallback: 0, min: 1, max: 20, zeroMeansUnset: true });
+
+  return buildPromptPack({
+    brief,
+    sourceRoot: DESIGN_AI_HOME,
+    prefix: SYMLINK_PREFIX,
+    maxBytes,
+    routeId,
+    withLearning,
+    learningCategory,
+    learningLimit,
+    withRecall,
+    recallLimit,
+  });
+}

package/cli/sdk/prompt-adapter.mjs

@@ -0,0 +1,49 @@
+// SDK adapter: prompt(brief, opts). See docs/AGENT-SDK.md.
+//
+// Phase A is read-only: unlike the CLI's `--with-learning` (which records a
+// local usage sidecar entry via recordLearningUsage), the SDK adapter never
+// writes the learning-usage sidecar, even when withLearning is requested. It
+// only reads the local learning profile to build the learning context.
+
+import { DESIGN_AI_HOME, SYMLINK_PREFIX } from "../lib/paths.mjs";
+import { buildPromptPlan } from "../lib/prompt.mjs";
+import {
+  optionalBoolean,
+  optionalInteger,
+  optionalString,
+  requireNonEmptyString,
+  requireOptions,
+} from "./validate.mjs";
+
+/**
+ * Build a ready-to-use agent prompt plan from a task brief. Pure, read-only
+ * adapter over `buildPromptPlan` from cli/lib/prompt.mjs. Never records
+ * learning-usage, even with withLearning: true (Phase A is read-only).
+ *
+ * @param {string} brief - Task brief text.
+ * @param {{routeId?: string, withLearning?: boolean, learningCategory?: string, learningLimit?: number, withRecall?: boolean, recallLimit?: number}} [opts]
+ * @returns {object|null} PromptPlan — the same shape as `design-ai prompt --json` (minus learningUsage).
+ */
+export function prompt(brief, opts = {}) {
+  requireNonEmptyString(brief, "brief");
+  const options = requireOptions(opts, "prompt");
+
+  const routeId = optionalString(options.routeId, "routeId");
+  const withLearning = optionalBoolean(options.withLearning, "withLearning", false);
+  const learningCategory = optionalString(options.learningCategory, "learningCategory");
+  const learningLimit = optionalInteger(options.learningLimit, "learningLimit", { fallback: 0, min: 1, max: 100, zeroMeansUnset: true });
+  const withRecall = optionalBoolean(options.withRecall, "withRecall", false);
+  const recallLimit = optionalInteger(options.recallLimit, "recallLimit", { fallback: 0, min: 1, max: 20, zeroMeansUnset: true });
+
+  return buildPromptPlan({
+    brief,
+    sourceRoot: DESIGN_AI_HOME,
+    prefix: SYMLINK_PREFIX,
+    routeId,
+    withLearning,
+    learningCategory,
+    learningLimit,
+    withRecall,
+    recallLimit,
+  });
+}

package/cli/sdk/recall-adapter.mjs

@@ -0,0 +1,39 @@
+// SDK adapter: recall(query, opts). See docs/AGENT-SDK.md.
+//
+// Combined recall view: brief-relevant shipped corpus knowledge (`corpus`) plus
+// brief-relevant local learning-profile entries (`learning`), both ranked by the
+// same shipped deterministic lexical scorer used by `search --ranked`. Read-only:
+// reads the local corpus and `DESIGN_AI_LEARNING_FILE` learning profile, exactly
+// as `design-ai learn --recall` does, and never writes either.
+
+import { DESIGN_AI_HOME } from "../lib/paths.mjs";
+import { buildLearnRecall, DEFAULT_RECALL_LIMIT } from "../lib/recall.mjs";
+import { optionalInteger, optionalString, requireNonEmptyString, requireOptions } from "./validate.mjs";
+
+/**
+ * Recall brief-relevant corpus knowledge and local learning-profile entries for
+ * a query. Pure, read-only adapter over `buildLearnRecall` from cli/lib/recall.mjs.
+ *
+ * @param {string} query - Recall query text.
+ * @param {{limit?: number, category?: string}} [opts]
+ * @returns {{corpus: object, learning: object}} combined recall view.
+ */
+export function recall(query, opts = {}) {
+  requireNonEmptyString(query, "query");
+  const options = requireOptions(opts, "recall");
+
+  const limit = optionalInteger(options.limit, "limit", { fallback: DEFAULT_RECALL_LIMIT, min: 1, max: 20 });
+  const category = optionalString(options.category, "category");
+
+  const result = buildLearnRecall({
+    query,
+    limit,
+    category,
+    designAiPath: DESIGN_AI_HOME,
+  });
+
+  return {
+    corpus: result.corpus,
+    learning: result.learning,
+  };
+}