@design-ai/cli 4.57.0 → 4.59.0

package/cli/sdk/route-adapter.mjs

@@ -0,0 +1,45 @@
+// SDK adapter: route(brief, opts) and routes(). See docs/AGENT-SDK.md.
+
+import { DESIGN_AI_HOME } from "../lib/paths.mjs";
+import { readRouteManifestVersion, routeBrief, routeCatalog } from "../lib/route.mjs";
+import {
+  optionalBoolean,
+  optionalInteger,
+  requireNonEmptyString,
+  requireOptions,
+} from "./validate.mjs";
+
+/**
+ * Recommend the best design-ai route(s), commands, skills, and knowledge files
+ * for a task brief. Pure, read-only adapter over `routeBrief` from cli/lib/route.mjs.
+ *
+ * @param {string} brief - Task brief text.
+ * @param {{limit?: number, explain?: boolean}} [opts]
+ * @returns {Array<object>} RouteResult[] — the same shape as `design-ai route --json`'s `routes` array.
+ */
+export function route(brief, opts = {}) {
+  requireNonEmptyString(brief, "brief");
+  const options = requireOptions(opts, "route");
+  const limit = optionalInteger(options.limit, "limit", { fallback: 3, min: 1, max: 10 });
+  const explain = optionalBoolean(options.explain, "explain", false);
+
+  return routeBrief({
+    brief,
+    sourceRoot: DESIGN_AI_HOME,
+    limit,
+    explain,
+  });
+}
+
+/**
+ * List the full route catalog (all route ids with their static metadata),
+ * independent of any brief. Pure, read-only adapter over `routeCatalog`.
+ *
+ * @returns {{version: string, routes: Array<object>}} RouteCatalog
+ */
+export function routes() {
+  return {
+    version: readRouteManifestVersion(DESIGN_AI_HOME),
+    routes: routeCatalog({ sourceRoot: DESIGN_AI_HOME }),
+  };
+}

package/cli/sdk/search-adapter.mjs

@@ -0,0 +1,55 @@
+// SDK adapter: search(query, opts). See docs/AGENT-SDK.md.
+
+import { DESIGN_AI_HOME } from "../lib/paths.mjs";
+import { rankedSearchCorpus } from "../lib/search-ranked.mjs";
+import { DEFAULT_SEARCH_DIRS, searchCorpus } from "../lib/search.mjs";
+import {
+  optionalBoolean,
+  optionalInteger,
+  optionalString,
+  requireNonEmptyString,
+  requireOptions,
+} from "./validate.mjs";
+
+function resolveDirs(dirName) {
+  if (!dirName) return DEFAULT_SEARCH_DIRS;
+  if (!DEFAULT_SEARCH_DIRS.includes(dirName)) {
+    throw new Error(`dir must be one of: ${DEFAULT_SEARCH_DIRS.join(", ")}`);
+  }
+  return [dirName];
+}
+
+/**
+ * Search the local design-ai markdown corpus. Pure, read-only adapter over
+ * `searchCorpus` / `rankedSearchCorpus` from cli/lib/search.mjs and
+ * cli/lib/search-ranked.mjs.
+ *
+ * @param {string} query - Search query text.
+ * @param {{dir?: string, limit?: number, ranked?: boolean}} [opts]
+ * @returns {Array<object>} SearchHit[] — line hits by default, ranked (score + matchedTokens) hits when `ranked: true`.
+ */
+export function search(query, opts = {}) {
+  requireNonEmptyString(query, "query");
+  const options = requireOptions(opts, "search");
+
+  const dirName = optionalString(options.dir, "dir");
+  const dirs = resolveDirs(dirName);
+  const limit = optionalInteger(options.limit, "limit", { fallback: 20, min: 1, max: 500 });
+  const ranked = optionalBoolean(options.ranked, "ranked", false);
+
+  if (ranked) {
+    return rankedSearchCorpus({
+      query,
+      designAiPath: DESIGN_AI_HOME,
+      dirs,
+      limit,
+    }).hits;
+  }
+
+  return searchCorpus({
+    query,
+    designAiPath: DESIGN_AI_HOME,
+    dirs,
+    limit,
+  });
+}

package/cli/sdk/validate.mjs

@@ -0,0 +1,48 @@
+// Input validation helpers shared by the SDK adapters (cli/sdk/*.mjs).
+// Fail fast with a clear Error on bad input, per docs/AGENT-SDK.md Phase A.
+
+export function requireNonEmptyString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+export function optionalString(value, label, fallback = "") {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "string") {
+    throw new Error(`${label} must be a string`);
+  }
+  return value;
+}
+
+export function optionalBoolean(value, label, fallback = false) {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "boolean") {
+    throw new Error(`${label} must be a boolean`);
+  }
+  return value;
+}
+
+// `zeroMeansUnset: true` is for options where the underlying cli/lib function
+// treats 0 itself as "not set, use the library default" (e.g. learningLimit,
+// recallLimit in prompt.mjs/pack.mjs use `learningLimit || 12`). In that case
+// an explicit 0 is accepted and passed through unchecked against min/max,
+// exactly like omitting the option.
+export function optionalInteger(value, label, { fallback = 0, min = -Infinity, max = Infinity, zeroMeansUnset = false } = {}) {
+  if (value === undefined || value === null) return fallback;
+  if (zeroMeansUnset && value === 0) return 0;
+  const num = Number(value);
+  if (!Number.isInteger(num) || num < min || num > max) {
+    throw new Error(`${label} must be an integer from ${min} to ${max}`);
+  }
+  return num;
+}
+
+export function requireOptions(opts, label) {
+  if (opts === undefined || opts === null) return {};
+  if (typeof opts !== "object" || Array.isArray(opts)) {
+    throw new Error(`${label} options must be a plain object`);
+  }
+  return opts;
+}

package/cli/sdk/version-adapter.mjs

@@ -0,0 +1,17 @@
+// SDK adapter: version(). See docs/AGENT-SDK.md.
+
+import { collectVersionReport } from "../commands/version.mjs";
+
+/**
+ * Report the CLI package version and the plugin/corpus version. Pure,
+ * read-only adapter over `collectVersionReport` from cli/commands/version.mjs.
+ *
+ * @returns {{cli: string, corpus: string}} version summary.
+ */
+export function version() {
+  const report = collectVersionReport();
+  return {
+    cli: report.versions.cli,
+    corpus: report.versions.plugin,
+  };
+}

package/docs/AGENT-SDK.md

@@ -0,0 +1,98 @@
+# Agent SDK design
+
+> Status: draft / planning — 2026-07-04
+
+This document opens the Agent SDK phase — the fast-follow chosen in [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md), now unblocked because the CLI recall interface has been stable across two releases (`--with-recall` / `learn --recall` shipped in v4.57.0 and stayed stable through v4.58.0's `route --explain` enrichment).
+
+Nothing here is shipped until a phase below is implemented and release-gated. Until then, the only supported programmatic entry to design-ai is the CLI and the MCP server.
+
+## Goal
+
+Let an external Node.js program — an agent runtime, a build script, a custom tool — use design-ai's deterministic design capabilities **as importable functions**, without shelling out to the CLI or spawning the MCP server. The SDK is a thin, documented, semver-stable adapter over the same `cli/lib` functions the CLI and MCP already call, so a capability that ships in the CLI is instantly available to an SDK consumer.
+
+The decision record scored this surface highest on leverage and learning synergy precisely because it reuses the shared library verbatim: `route`, `prompt`, `pack`, `search --ranked`, `recall`, and `check` are already pure functions in `cli/lib`.
+
+## Non-goals
+
+- No new capabilities. The SDK exposes existing CLI/MCP behavior; it does not add design logic.
+- No runtime dependencies, no network calls, no telemetry — same posture as the CLI.
+- No exposure of the entire `cli/lib` internal surface. The SDK is a curated, stable subset; `cli/lib/*` stays internal and free to refactor.
+- No new process model — the SDK runs in the caller's process, deterministic and synchronous where the underlying functions are.
+- No model inference or fine-tuning (unchanged product stance).
+
+## The stable surface
+
+A single curated entry (`cli/sdk/index.mjs`) re-exports a small set of adapter functions with **their own stable signatures**, independent of the internal `cli/lib` shapes. Internal functions may be renamed or refactored; the SDK adapter absorbs that so the public API stays put.
+
+Proposed surface (Phase A — read-only verbs):
+
+```js
+import { route, prompt, pack, search, recall, check, routes, version } from "@design-ai/cli/sdk";
+
+route(brief, { limit = 3, explain = false })            // → RouteResult[]
+prompt(brief, { routeId, withLearning, learningCategory, learningLimit, withRecall, recallLimit })  // → PromptPlan
+pack(brief, { routeId, maxBytes, withLearning, learningCategory, learningLimit, withRecall, recallLimit })  // → Pack
+search(query, { dir, limit = 20, ranked = false })      // → SearchHit[]  (ranked: BM25 hits with scores)
+recall(query, { limit = 5, category = "" })             // → { corpus, learning }  (combined recall view)
+check(artifact, { routeId = "", strict = false })       // → CheckReport
+routes()                                                // → RouteCatalog
+version()                                               // → { cli, corpus }
+```
+
+Every function is a pure adapter: it validates its inputs, calls the corresponding `cli/lib` function with the resolved package root, and returns a plain JSON-serializable object — the same shape the CLI's `--json` mode emits, which is already a contract covered by smoke tests. No function writes files or reads the network in Phase A. `recall` and the `withRecall`/`withLearning` options read the local corpus and the user's local `learning.json` (via `DESIGN_AI_LEARNING_FILE`) exactly as the CLI does; nothing else is read.
+
+## Packaging
+
+Add an `exports` map to `package.json`:
+
+```json
+"exports": {
+  "./sdk": "./cli/sdk/index.mjs",
+  "./package.json": "./package.json"
+}
+```
+
+- `@design-ai/cli/sdk` is the one public import path. The bare package (`.`) intentionally stays unexported so `import "@design-ai/cli"` does not accidentally couple callers to internals; the CLI is invoked as a bin, the SDK via the explicit subpath.
+- `cli/` is already in `files`, so `cli/sdk/` ships with the package with no `files` change.
+- The `package-contents` audit and `package:smoke` must cover the new entry: a packed-tarball smoke that `import`s `@design-ai/cli/sdk` and calls `route`/`search --ranked`/`recall` and asserts deterministic output.
+
+## Stability contract
+
+- The `@design-ai/cli/sdk` surface is **semver-stable**: additive changes are minor, signature/return changes are major. This is stated in the SDK reference doc and enforced by SDK contract tests that pin the exported names and return-shape keys.
+- `cli/lib/*` remains **internal and unstable** — importing `@design-ai/cli/cli/lib/...` is unsupported. The adapter layer is the seam that lets internals refactor (as they did repeatedly during the retrieval work) without breaking SDK consumers.
+- Determinism: same inputs → same outputs, matching the CLI. The SDK adds no randomness or time-dependence.
+
+## Phased plan
+
+### Phase A — read-only SDK core
+
+The verbs above (`route`, `prompt`, `pack`, `search`, `recall`, `check`, `routes`, `version`) as pure adapters over existing `cli/lib` functions. Read-only: no file writes, no network, no learning-usage sidecar writes (the SDK's `prompt`/`pack` default to not recording usage, unlike the CLI's opt-in `--with-learning` sidecar write — an SDK caller opts in explicitly if that is added later).
+
+Verification gates:
+- `node --test` unit coverage for each adapter: signature, option defaults, return-shape keys, determinism, and parity with the CLI `--json` output for a fixed brief.
+- SDK contract test pinning the exported names and the return-shape key sets (the semver anchor).
+- `npm run audit` 8/8 (the SDK reference doc's links resolve; frontmatter valid).
+- `npm run release:check` additions: packed-tarball smoke that imports `@design-ai/cli/sdk` from the installed package and exercises `route`/`search`(ranked)/`recall`, plus a registry-smoke parity check after publish.
+- `npm run release:metadata` unchanged (README stance preserved).
+
+### Phase B — optional, explicit local writes
+
+Only if demand appears: opt-in adapters that mirror the CLI's local-write commands (`learn.remember`, `learn.feedback`, `check` with capture), each requiring an explicit option and writing only the local learning profile, never the network. Deferred until an adopter needs it; Phase A is read-only.
+
+## Integration points
+
+- **MCP server** already wraps the same `cli/lib` functions; the SDK and MCP stay in lockstep because both are thin layers over one core. No MCP change is required for Phase A.
+- **Retrieval** (`search` ranked, `recall`, `withRecall`) flows into the SDK for free — the shared lexical scorer and the generated-index exclusion apply identically.
+- **Docs**: a `docs/SDK.md` (or this file, promoted from draft) becomes the public SDK reference; the README install table gains an "SDK" row pointing to it.
+
+## Risks and open questions
+
+Risks:
+- **Semver commitment.** Once published, the SDK surface is a promise. Mitigation: keep Phase A small (8 verbs), pin names/shapes in a contract test, and treat the adapter as the only stable seam.
+- **Return-shape coupling.** SDK returns mirror the CLI `--json` shapes; if those change, the SDK breaks. Mitigation: the same smoke/parity tests that already guard the CLI JSON guard the SDK, and shape changes are already major-version events.
+
+Open questions (answer during Phase A implementation review):
+1. Export the bare package root (`.`) as an alias for `./sdk`, or keep `./sdk` the only path? (Leaning: `./sdk` only, to avoid implying the whole package is the SDK.)
+2. Ship TypeScript types (`.d.ts`) hand-written for the 8 verbs, or JSDoc-only for the zero-toolchain stance? (Leaning: JSDoc + a hand-written `sdk/index.d.ts` with no build step.)
+3. Does `prompt`/`pack` via the SDK ever write the learning-usage sidecar, or is that strictly a Phase B explicit opt-in? (Leaning: never in Phase A; read-only.)
+4. Is `check` in Phase A (read-only quality check) or deferred with the other write-adjacent verbs? (Leaning: Phase A — `check` is read-only when capture is off.)

package/docs/ROADMAP.md

@@ -1,5 +1,73 @@
 # Roadmap
 
+## Phase 758 — Agent SDK Phase A Release (v4.59.0) ✓ ready
+
+Ships the Agent SDK Phase A work (Phase 757) as an npm version: the curated, semver-stable `@design-ai/cli/sdk` surface — eight read-only adapter verbs (`route`, `prompt`, `pack`, `search`, `recall`, `check`, `routes`, `version`) over the same `cli/lib` functions the CLI and MCP already call. No new capabilities, no runtime dependencies, no network, no telemetry; read-only, deterministic, backward-compatible.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check` (unit tests incl. 61 SDK tests, strict audits, whitespace, package contents, release metadata, release self-tests, packed-tarball smoke that imports `@design-ai/cli/sdk`).
+- `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
+- design-ai's routing, prompt/pack generation, ranked search, recall, and artifact checks become plain importable functions for agent runtimes, build scripts, and custom tools — deterministic, in-process, zero-dependency — behind a semver-stable contract that insulates callers from internal `cli/lib` refactors.
+
+### What's still ahead
+- Optional `cli/sdk/index.d.ts` hand-written type declarations (zero-build), and Phase B explicit local-write adapters — both deferred until an adopter needs them.
+
+## Phase 757 — Agent SDK (Phase A implemented, unreleased)
+
+Opens the Agent SDK phase — the fast-follow chosen in [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md), unblocked now that the recall interface has been stable across two releases (v4.57.0/v4.58.0). Scope, the stable surface, packaging, and the stability contract are defined in [AGENT-SDK.md](AGENT-SDK.md). No new capabilities, no runtime dependencies, no network, no telemetry; the SDK is a thin, semver-stable adapter over the same `cli/lib` functions the CLI and MCP already call.
+
+Phase A landed in `main` (commit `326ed0a`) as `cli/sdk/`; it is code-complete and gated but **not yet released as an npm version** — shipping it is the next release decision.
+
+### Delivered (Phase A)
+- [x] Read-only SDK core at `@design-ai/cli/sdk` — `route`, `prompt`, `pack`, `search` (incl. ranked), `recall`, `check`, `routes`, `version` as pure adapters with stable signatures; `exports` map added; no file writes / no network. `check` operates on artifact content (not a path), so it reads and writes nothing.
+- [x] Unit coverage per adapter (signature, defaults, return-shape keys, determinism, CLI `--json` parity) plus an SDK contract test (`cli/sdk/index.test.mjs`) pinning exported names and return-shape keys — the semver anchor. 61 new tests, 540/540 total.
+- [x] Packed-tarball smoke (`package-smoke.py`) that imports `@design-ai/cli/sdk` from the installed package and exercises `route`/`search` ranked/`recall`/`version`/`routes`/`prompt`/`pack`/`check`, asserting determinism and the Phase A no-`learningUsage` guarantee.
+- [x] `docs/SDK.md` public reference + README/README.ko "Node.js / Agent SDK" install-table row + mkdocs nav.
+- [x] Open questions from [AGENT-SDK.md](AGENT-SDK.md) resolved: bare root `.` not exported (only `./sdk`); usage sidecar never written in Phase A; `check` is in Phase A (read-only). TS `.d.ts` deferred — adapters carry JSDoc; a hand-written `sdk/index.d.ts` remains an optional follow-up.
+
+### Remaining
+- [ ] Release decision: bundle Phase A into the next npm version (e.g. v4.59.0) — version bump, CHANGELOG, registry-smoke parity after publish.
+- [ ] Optional follow-up: hand-written `cli/sdk/index.d.ts` type declarations for the 8 verbs (zero-build stance preserved).
+- [ ] Phase B (optional, deferred until an adopter needs it): explicit local-write adapters (`learn.remember`/`feedback`, capture).
+
+## Phase 756 — Retrieval Across Surfaces and Corpus Depth Release (v4.58.0) ✓ ready
+
+Groups the post-v4.57.0 retrieval completion and corpus work into one release: `route --explain` related-knowledge enrichment (retrieval now spans every surface), recall exclusion of generated index/meta files, the async-control and Korean B2B density knowledge files, and the registry-smoke assertion fix that realigns the live post-publish smoke with the shared scorer. Defaults are unchanged; the release is additive and backward-compatible.
+
+### Changed
+- `route --explain` gains an advisory related-knowledge section (routing unchanged), completing retrieval across `search`/`prompt`/`pack`/`learn`/`route`; carried to MCP via the existing `design_ai_route` `explain` parameter.
+- Recall injection excludes generated index/meta files so injected context is real design knowledge; raw `search --ranked` is unchanged.
+- Added `knowledge/patterns/async-control.md` and `knowledge/i18n/korean-density-conventions.md` (corpus now 94 files), closing the remaining dogfood-named gaps.
+- Fixed the stale `registry-smoke.py` learn-relevance token-order assertion so the live post-publish registry smoke matches the published package.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check` (unit tests, strict audits, whitespace, package contents, release metadata, release self-tests, packed-tarball smoke).
+- `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
+- Retrieval is uniform across every design-ai surface and injects real design knowledge, not index tables; the Korean corpus gains async-control and B2B density depth.
+- Publishing v4.58.0 realigns `main` with the published package so the live registry smoke verifies cleanly.
+
+### What's still ahead
+- Push the v4.58.0 tag, then verify npm publish (provenance), GitHub Release, public `npm run registry:smoke` (now skew-free), and docs deployment.
+- Refresh the Homebrew formula SHA-256 and the [external-status.md](external-status.md) / README distribution status from published `4.57.0` to `4.58.0` after the tag tarball exists.
+
 ## Phase 755 — Local Retrieval Memory Release (v4.57.0) ✓ ready
 
 Groups the Phase 754 A+B retrieval work, the MCP ranked-search parameter, the `refs/` reference-page migration, and the docs-deploy retry hardening into one public package release. Scope and data boundaries are defined in [AI-LEARNING-PHASE2.md](AI-LEARNING-PHASE2.md); defaults are unchanged, so the release is additive and backward-compatible.

package/docs/SDK.md

@@ -0,0 +1,162 @@
+# Agent SDK reference
+
+> Status: shipped (Phase A) — read-only verbs, semver-stable surface
+
+`@design-ai/cli/sdk` lets an external Node.js program — an agent runtime, a build script, a custom tool — use design-ai's deterministic design capabilities as importable functions, without shelling out to the CLI or spawning the MCP server. It is a thin, curated adapter over the same `cli/lib` functions the CLI and MCP server already call, so a capability that ships in the CLI is instantly available to an SDK consumer.
+
+See [`AGENT-SDK.md`](AGENT-SDK.md) for the full design rationale, phased plan, and open questions. This page is the public reference for the shipped Phase A surface.
+
+## Install and import
+
+The SDK ships inside the `@design-ai/cli` package (no separate install):
+
+```bash
+npm install @design-ai/cli
+```
+
+```js
+import { route, prompt, pack, search, recall, check, routes, version } from "@design-ai/cli/sdk";
+```
+
+Only the `./sdk` subpath is exported — `import "@design-ai/cli"` (the bare package root) is intentionally not exported, so importing the SDK is always an explicit `@design-ai/cli/sdk` import. `cli/lib/*` is internal and unstable; do not import it directly.
+
+## Phase A: read-only
+
+Every verb below is a pure, read-only adapter:
+
+- It validates its inputs and throws a plain `Error` with a clear message on bad input (e.g. a non-string brief).
+- It resolves the package root the same way the CLI does.
+- It calls the corresponding `cli/lib` function and returns a plain JSON-serializable object — the same shape the CLI's `--json` mode emits.
+- It performs no file writes, no network calls, and no learning-usage sidecar writes. This is a deliberate difference from the CLI: `prompt`/`pack`'s `withLearning` option in the SDK only **reads** the local learning profile to build context — it never records a usage event, unlike the CLI's `--with-learning` flag. There is no SDK equivalent of `check --learn` (capture) in Phase A.
+- Given the same inputs, it returns the same outputs (determinism), matching the CLI.
+
+## Verbs
+
+### `route(brief, opts)`
+
+Recommend the best design-ai route(s), commands, skills, and knowledge files for a task brief.
+
+```js
+route(brief: string, opts?: { limit?: number, explain?: boolean }): RouteResult[]
+```
+
+- `limit` — maximum route recommendations, 1-10. Default: `3`.
+- `explain` — include route scoring, reference coverage, and related-knowledge detail. Default: `false`.
+
+Returns an array of `RouteResult` objects (`id`, `label`, `score`, `confidence`, `matchedKeywords`, `command`, `skills`, `agents`, `knowledge`, `keywords`, `explanation`, plus `relatedKnowledge` when `explain: true`) — the same shape as the `routes` array in `design-ai route --json`.
+
+### `prompt(brief, opts)`
+
+Build a ready-to-use agent prompt plan from a task brief.
+
+```js
+prompt(brief: string, opts?: {
+  routeId?: string,
+  withLearning?: boolean,
+  learningCategory?: string,
+  learningLimit?: number,
+  withRecall?: boolean,
+  recallLimit?: number,
+}): PromptPlan | null
+```
+
+- `routeId` — force a route id instead of scoring the brief.
+- `withLearning` — include brief-relevant local learning preferences (reads `DESIGN_AI_LEARNING_FILE`; **never** records usage, unlike the CLI's `--with-learning`).
+- `learningCategory`, `learningLimit` (1-100) — scope/limit the learning context; require `withLearning`.
+- `withRecall` — include brief-relevant shipped corpus knowledge.
+- `recallLimit` (1-20) — limit recalled corpus files; requires `withRecall`.
+
+Returns a `PromptPlan` object (`brief`, `version`, `route`, `slashCommand`, `referenceExamples`, `filesToRead`, `checklist`, `qualityCommand`, `prompt`, plus `learningContext`/`recall` when requested) — the same shape as `design-ai prompt --json`, minus `learningUsage` (Phase A never writes it).
+
+### `pack(brief, opts)`
+
+Build a ready-to-use prompt plus a bounded context-file bundle from a task brief.
+
+```js
+pack(brief: string, opts?: {
+  routeId?: string,
+  maxBytes?: number,
+  withLearning?: boolean,
+  learningCategory?: string,
+  learningLimit?: number,
+  withRecall?: boolean,
+  recallLimit?: number,
+}): Pack
+```
+
+- `maxBytes` — maximum context bytes to include, 1000-1,000,000. Default: `120000`.
+- The remaining options mirror `prompt`'s learning/recall options.
+
+Returns a `Pack` object (`brief`, `version`, `maxBytes`, `usedBytes`, `summary`, `warnings`, `plan`, `files`, `markdown`) — the same shape as `design-ai pack --json`, minus `learningUsage`.
+
+### `search(query, opts)`
+
+Search the local design-ai markdown corpus.
+
+```js
+search(query: string, opts?: { dir?: string, limit?: number, ranked?: boolean }): SearchHit[]
+```
+
+- `dir` — restrict to one corpus directory: `knowledge`, `examples`, `skills`, `docs`, `agents`, or `commands`.
+- `limit` — maximum hits, 1-500. Default: `20`.
+- `ranked` — rank results with the deterministic lexical (BM25-style) scorer instead of returning raw line hits. Default: `false`.
+
+Returns `SearchHit[]`. Unranked hits: `{ file, relPath, lineNumber, preview }`. Ranked hits: `{ file, relPath, score, matchedTokens, preview }` — the same shapes as `design-ai search --json` and `design-ai search --ranked --json`.
+
+### `recall(query, opts)`
+
+Recall brief-relevant shipped corpus knowledge and local learning-profile entries for a query — a combined read-only view.
+
+```js
+recall(query: string, opts?: { limit?: number, category?: string }): { corpus: object, learning: object }
+```
+
+- `limit` — applies to both the corpus and learning lists, 1-20. Default: `5`.
+- `category` — scopes only the learning list.
+
+Returns `{ corpus: { candidateCount, selectedCount, selected }, learning: { mode, candidateCount, selectedCount, selected } }` — the same shape as `design-ai learn --recall --json`.
+
+### `check(artifact, opts)`
+
+Check a generated design Markdown artifact for grounding, accessibility, responsive, unresolved-marker, and route-specific requirements.
+
+```js
+check(artifact: string, opts?: { routeId?: string, strict?: boolean }): CheckReport
+```
+
+- `routeId` — add route-specific checks (e.g. `component-spec`, `palette-from-brand`). Must be a known route id.
+- `strict` — accepted for CLI-flag parity but has no effect on the returned report; the SDK never sets a process exit code. Inspect `report.status` yourself.
+
+Returns a `CheckReport` object (`filePath`, `status`, `passes`, `warnings`, `failures`, `total`, `score`, `results`, plus `routeId` when passed) — the same shape as `design-ai check --json` (minus any `--learn` capture, which Phase A does not support).
+
+### `routes()`
+
+List the full route catalog (every route id with its static metadata), independent of any brief.
+
+```js
+routes(): { version: string, routes: RouteResult[] }
+```
+
+Returns the same shape as `design-ai route --list --json`.
+
+### `version()`
+
+Report the CLI package version and the plugin/corpus version.
+
+```js
+version(): { cli: string, corpus: string }
+```
+
+## Stability contract
+
+`@design-ai/cli/sdk` is **semver-stable**:
+
+- Additive changes (new optional fields, new opt-in options) are minor version bumps.
+- Signature or return-shape changes are major version bumps.
+- The 8 exported names (`route`, `prompt`, `pack`, `search`, `recall`, `check`, `routes`, `version`) and their return-shape key sets are pinned by an SDK contract test (`cli/sdk/index.test.mjs`) — this is the semver anchor. If a name or a top-level key drifts unintentionally, that test fails.
+- `cli/lib/*` remains internal and unstable. Only `@design-ai/cli/sdk` is a supported import path.
+- Determinism: the same inputs always produce the same outputs, with no randomness or time-dependence added by the adapter layer.
+
+## Phase B (not yet shipped)
+
+Phase A is read-only by design. A future Phase B may add opt-in, explicit local-write adapters mirroring the CLI's local-write commands (`learn.remember`, `learn.feedback`, `check` with capture) — deferred until an adopter needs it. See [`AGENT-SDK.md`](AGENT-SDK.md#phase-b-optional-explicit-local-writes) for the current plan.

package/docs/external-status.md

@@ -1,22 +1,22 @@
 # External Publication Status
 
-> Checked: 2026-07-02
+> Checked: 2026-07-04
 > Scope: npm registry, GitHub Pages, Homebrew tap, VS Code Marketplace, Claude/Codex MCP
 
 ## Summary
 
-Local release readiness is verified, GitHub Pages docs are publicly reachable, GitHub Release `v4.56.0` is published, and the Homebrew tap formula points at the `v4.56.0` release source tarball with a verified SHA-256. npm is publicly published at `@design-ai/cli@4.56.0`; publish run `28569283984` succeeded with provenance and the public registry smoke passed. The VS Code extension `sungjin.design-ai-vscode` is published to the VS Code Marketplace at version `0.4.1`; the Gallery API is reachable. The public npm MCP entrypoint and the local Claude Code / Codex MCP client registrations were rechecked on 2026-07-02.
+npm is publicly published at `@design-ai/cli@4.58.0` (npm dist-tag `latest` = `4.58.0`); publish run from tag `v4.58.0` succeeded with provenance and all pre-publish gates green. After fixing the remaining stale learn-relevance score-type assertions in `tools/audit/registry-smoke.py` (`16e97aa`), the live `npm run registry:smoke` passes cleanly against published `@design-ai/cli@4.58.0` ("Registry smoke passed"), covering the retrieval surfaces (index/ranked/embeddings/recall) and route enrichment. GitHub Release `v4.58.0` is published, and the Homebrew tap formula points at the `v4.58.0` release source tarball with a verified SHA-256. The VS Code extension `sungjin.design-ai-vscode` remains published at `0.4.1`. GitHub Pages docs are publicly reachable.
 
 ## Results
 
 | Surface | Checked target | Result | Evidence |
 |---|---|---|---|
-| npm registry | `@design-ai/cli` | Published latest is `4.56.0`; publish run `28569283984` succeeded and public registry smoke passed for `@design-ai/cli@4.56.0`. | `evidence/cli-logs/npm-registry-status.log`, `evidence/cli-logs/npm-registry-smoke.log`, `evidence/cli-logs/npm-publish-v4.56.0-success.log` |
+| npm registry | `@design-ai/cli` | Published latest is `4.58.0` (tag `v4.58.0`, provenance). Pre-publish packed-tarball smoke and post-fix live `npm run registry:smoke` both pass for `@design-ai/cli@4.58.0`. | `npm view @design-ai/cli version` → `4.58.0`; live registry smoke "Registry smoke passed" |
 | GitHub Pages | `https://sungjin9288.github.io/design-ai/` | Published and reachable: HTTP `200`, design-ai MkDocs page rendered | `evidence/cli-logs/github-pages-status.log` |
-| Homebrew tap | `Formula/design-ai.rb` | Formula pinned to `v4.56.0` release source tarball with SHA-256 `507d2519296497defcd486c0ffc2b5164967a0bc540ddc31bc89502350688212`; Ruby syntax and `brew style` passed | `evidence/cli-logs/homebrew-formula-status.log` |
+| Homebrew tap | `Formula/design-ai.rb` | Formula pinned to `v4.58.0` release source tarball with SHA-256 `45ec7fa4e82e7af38cdf948e1ad056a3758be848e5541013144e8d93d4c9da37` (recomputed from the published tag tarball) | `Formula/design-ai.rb` |
 | VS Code Marketplace | `sungjin.design-ai-vscode` | Published: run `28431571256` published `v0.4.1`, and the Marketplace Gallery API returned visible version `0.4.1` on 2026-07-02. | `evidence/cli-logs/vscode-marketplace-status.log`, `evidence/cli-logs/vscode-marketplace-secret-status.log`, `evidence/cli-logs/vscode-extension-vsce-package.log`, `evidence/cli-logs/vscode-publish-workflow-status.log` |
-| GitHub Release | `v4.56.0` | Published with release tarball asset `design-ai-cli-4.56.0.tgz` | `evidence/cli-logs/github-release-v4.56.0.log` |
-| MCP server | `@design-ai/cli@4.56.0` / local clone | Public npm `design-ai-mcp` responds to initialize and tools/list with 10 tools; local Codex and Claude Code both report `design-ai` MCP as configured and connected. | `evidence/cli-logs/npm-registry-smoke.log`, `evidence/cli-logs/design-ai-mcp-client-status.log` |
+| GitHub Release | `v4.58.0` | Published for tag `v4.58.0` at commit `22dc8a9` | `gh release view v4.58.0` |
+| MCP server | `@design-ai/cli@4.58.0` / local clone | Public npm `design-ai-mcp` responds to initialize and tools/list with 10 tools; local Codex and Claude Code both report `design-ai` MCP as configured and connected. | `evidence/cli-logs/npm-registry-smoke.log`, `evidence/cli-logs/design-ai-mcp-client-status.log` |
 
 ## Interpretation
 

package/knowledge/COVERAGE.md

@@ -12,7 +12,7 @@ generated_at: 2026-07-03
 
 | Layer | Count | Detail |
 | --- | --- | --- |
-| Knowledge files | 92 | 77 hand-written + 15 generated |
+| Knowledge files | 94 | 79 hand-written + 15 generated |
 | Skills (PLAYBOOK + SKILL) | 20 | 20 with verification phase |
 | Worked examples | 221 | |
 | Extractors | 12 | |
@@ -30,12 +30,12 @@ generated_at: 2026-07-03
 | `conversational` | 5 | 5 | 0 |
 | `design-tokens` | 4 | 3 | 1 |
 | `game-ui` | 5 | 5 | 0 |
-| `i18n` | 6 | 6 | 0 |
+| `i18n` | 7 | 7 | 0 |
 | `icons` | 1 | 0 | 1 |
 | `illustration` | 5 | 5 | 0 |
 | `layout` | 1 | 1 | 0 |
 | `motion` | 6 | 6 | 0 |
-| `patterns` | 30 | 24 | 6 |
+| `patterns` | 31 | 25 | 6 |
 | `platforms` | 1 | 1 | 0 |
 | `print` | 6 | 6 | 0 |
 | `spatial` | 5 | 5 | 0 |
@@ -49,7 +49,7 @@ generated_at: 2026-07-03
 
 | File | Lines | Type | Title |
 | --- | --- | --- | --- |
-| [knowledge/COVERAGE.md](../knowledge/COVERAGE.md) | 741 | generated | Coverage report |
+| [knowledge/COVERAGE.md](../knowledge/COVERAGE.md) | 743 | generated | Coverage report |
 | [knowledge/PRINCIPLES.md](../knowledge/PRINCIPLES.md) | 108 | hand-written | Design-AI principles |
 
 #### a11y
@@ -108,9 +108,10 @@ generated_at: 2026-07-03
 | File | Lines | Type | Title |
 | --- | --- | --- | --- |
 | [knowledge/i18n/korean-app-store-visual.md](../knowledge/i18n/korean-app-store-visual.md) | 223 | hand-written | Korean app store visual design |
+| [knowledge/i18n/korean-density-conventions.md](../knowledge/i18n/korean-density-conventions.md) | 108 | hand-written | Korean B2B density conventions |
 | [knowledge/i18n/korean-document-style.md](../knowledge/i18n/korean-document-style.md) | 301 | hand-written | Korean document style |
 | [knowledge/i18n/korean-payments.md](../knowledge/i18n/korean-payments.md) | 211 | hand-written | Korean payments |
-| [knowledge/i18n/korean-product-conventions.md](../knowledge/i18n/korean-product-conventions.md) | 96 | hand-written | Korean product UX conventions |
+| [knowledge/i18n/korean-product-conventions.md](../knowledge/i18n/korean-product-conventions.md) | 98 | hand-written | Korean product UX conventions |
 | [knowledge/i18n/korean-publishing.md](../knowledge/i18n/korean-publishing.md) | 139 | hand-written | Korean app store & publishing requirements |
 | [knowledge/i18n/korean-typography.md](../knowledge/i18n/korean-typography.md) | 123 | hand-written | Korean (Hangul) typography for product UI |
 
@@ -151,6 +152,7 @@ generated_at: 2026-07-03
 
 | File | Lines | Type | Title |
 | --- | --- | --- | --- |
+| [knowledge/patterns/async-control.md](../knowledge/patterns/async-control.md) | 233 | hand-written | Async control patterns |
 | [knowledge/patterns/auth-flow-design.md](../knowledge/patterns/auth-flow-design.md) | 316 | hand-written | Authentication flow design |
 | [knowledge/patterns/b2b-onboarding-flows.md](../knowledge/patterns/b2b-onboarding-flows.md) | 182 | hand-written | B2B onboarding flows |
 | [knowledge/patterns/brand-identity.md](../knowledge/patterns/brand-identity.md) | 238 | hand-written | Brand identity |
@@ -162,8 +164,8 @@ generated_at: 2026-07-03
 | [knowledge/patterns/document-typography.md](../knowledge/patterns/document-typography.md) | 248 | hand-written | Document typography |
 | [knowledge/patterns/email-design.md](../knowledge/patterns/email-design.md) | 338 | hand-written | Email design |
 | [knowledge/patterns/empty-states.md](../knowledge/patterns/empty-states.md) | 263 | hand-written | Empty states |
-| [knowledge/patterns/error-states.md](../knowledge/patterns/error-states.md) | 318 | hand-written | Error states |
-| [knowledge/patterns/form-design.md](../knowledge/patterns/form-design.md) | 237 | hand-written | Form design patterns |
+| [knowledge/patterns/error-states.md](../knowledge/patterns/error-states.md) | 319 | hand-written | Error states |
+| [knowledge/patterns/form-design.md](../knowledge/patterns/form-design.md) | 239 | hand-written | Form design patterns |
 | [knowledge/patterns/information-architecture.md](../knowledge/patterns/information-architecture.md) | 341 | hand-written | Information architecture |
 | [knowledge/patterns/landing-hero-design.md](../knowledge/patterns/landing-hero-design.md) | 283 | hand-written | Landing hero design |
 | [knowledge/patterns/landing-page-patterns.md](../knowledge/patterns/landing-page-patterns.md) | 681 | generated | Landing page patterns |