@design-ai/cli 4.58.0 → 4.60.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "design-ai",
-  "version": "4.58.0",
+  "version": "4.60.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,59 @@
 
 User-facing release notes for design-ai. Versions follow semver.
 
+## v4.60.0 — Agent SDK types and local-write namespace (2026-07)
+
+Extends the Agent SDK (`@design-ai/cli/sdk`) two ways, both additive and backward-compatible. First, hand-written TypeScript declarations now ship with the package, so TypeScript and editors resolve `@design-ai/cli/sdk` with full types — no `@types` install and no build step. Second, an opt-in `learn.*` namespace adds the SDK's first local-write verbs, keeping the eight Phase A verbs read-only and unchanged.
+
+### Added
+- `cli/sdk/index.d.ts` — hand-written type declarations for all eight read-only verbs (precise signatures and return interfaces, including `search` ranked/plain overloads, the `RouteConfidence` union, and optional `learningContext`/`recall`/`relatedKnowledge` fields) plus the `learn` namespace. Wired through an `exports` `types` condition, so `moduleResolution: node16`/`nodenext`/`bundler` consumers get types automatically. A `node --test` guard (`cli/sdk/types.test.mjs`) keeps the declarations in exact sync with the runtime exports; the declarations are verified to compile under `tsc --strict`.
+- `learn` — a frozen namespace grouping the SDK's only writing verbs (Phase B): `learn.remember(text, { category })`, `learn.feedback(text, { outcome, category })`, and `learn.captureFromCheck(artifact, { routeId })`. Each writes only the local learning profile (`DESIGN_AI_LEARNING_FILE`), never the network, mirroring the CLI's `learn remember` / `learn feedback` / `check --learn` write paths. There is no `filePath` or timestamp option — consumers target a profile via the env var, exactly like the CLI.
+
+### Changed
+- The eight Phase A verbs (`route`, `prompt`, `pack`, `search`, `recall`, `check`, `routes`, `version`) remain read-only and unchanged. `check` in particular stays read-only: capture lives in `learn.captureFromCheck`, never as a `check` option. The SDK contract test (`cli/sdk/index.test.mjs`) now pins both the eight read-only function verbs and the frozen `learn` namespace with its three verbs and their return-shape keys.
+- `tools/audit/package-smoke.py` now also exercises `learn.remember` from the installed tarball against a temp `DESIGN_AI_LEARNING_FILE`, asserting the write.
+
+### 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.59.0 → 4.60.0.
+- `vscode-extension/package.json`: remains 0.4.1.
+
+### What this enables
+- TypeScript consumers get first-class types for the whole SDK with zero toolchain cost on either side, and agents can now record design preferences, feedback, and check-derived learnings through a single explicit, opt-in write namespace — while every read-only verb keeps its no-write guarantee.
+
+## 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.

package/README.ko.md

@@ -12,7 +12,7 @@
 
 > **모델이 아니에요. 파인튜닝도 아니에요.** 디자인 전문 지식을 구조화한 코퍼스 + 에이전트가 바로 실행할 수 있는 지시문이에요. 범용 LLM을 이번 세션에서만큼은 시니어 디자이너로 바꿔주는 셈이에요.
 
-> **배포 상태, 2026-07-03 확인:** 로컬 `npm run release:check`는 통과했고, GitHub Pages 문서는 live 상태이며, GitHub Release `v4.57.0`과 npm `@design-ai/cli@4.57.0`(`latest`) publish가 provenance와 함께 확인됐어요. Homebrew formula는 `v4.57.0`에 pinning되어 있고, VS Code Marketplace에는 `sungjin.design-ai-vscode@0.4.1`이 공개되어 있어요. v4.57.0 post-publish live registry smoke는 stale 어서션에 걸렸고(`main`에서 수정됨), 패키지는 pre-publish packed-tarball smoke로 검증됐어요. 자세한 내용은 [`docs/external-status.md`](docs/external-status.md)를 확인하세요.
+> **배포 상태, 2026-07-04 확인:** 로컬 `npm run release:check`는 통과했고, GitHub Pages 문서는 live 상태이며, GitHub Release `v4.59.0`과 npm `@design-ai/cli@4.59.0`(`latest`) publish가 provenance와 함께 확인됐어요. 이번 릴리스는 읽기 전용 Agent SDK 표면(`@design-ai/cli/sdk`, 8개 어댑터 verb)을 추가했고 additive라 CLI 출력은 그대로예요. live `npm run registry:smoke`가 published `@design-ai/cli@4.59.0`에 대해 깨끗이 통과했어요(retrieval 표면과 route enrichment 포함). Homebrew formula는 `v4.59.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)를, 구체적인 사용 예시는 위 워크스루 링크를 참고하세요.
@@ -171,7 +172,7 @@ design-ai는 한국 시장을 1순위로 만들어졌고, 글로벌 시장 패
 
 ## 상태
 
-전체 단계 로그는 [`docs/ROADMAP.md`](docs/ROADMAP.md), 현재 완료 범위는 [`docs/PRODUCT-READINESS.md`](docs/PRODUCT-READINESS.md)에서 확인하세요. 현재 **v4.57.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.59.0**: 읽기 전용 Agent SDK(`@design-ai/cli/sdk`), 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

@@ -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-03:** local `npm run release:check` passes, GitHub Pages docs are live, GitHub Release `v4.57.0` is published, `@design-ai/cli@4.57.0` is public on npm (`latest`) with provenance and registry smoke coverage, the Homebrew formula is pinned to `v4.57.0`, and `sungjin.design-ai-vscode@0.4.1` is public on the VS Code Marketplace. The v4.57.0 post-publish live registry smoke hit a stale assertion (fixed on `main`); the package is validated by the pre-publish packed-tarball smoke. 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.59.0` is published, `@design-ai/cli@4.59.0` is public on npm (`latest`) with provenance, and the live `npm run registry:smoke` passes cleanly against `@design-ai/cli@4.59.0`. The Homebrew formula is pinned to `v4.59.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.
@@ -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.57.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.59.0**: the read-only Agent SDK (`@design-ai/cli/sdk`), 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/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.d.ts

@@ -0,0 +1,435 @@
+// Type declarations for the design-ai Agent SDK — Phase A (read-only).
+// Hand-written, zero-build: no TypeScript toolchain is required to produce or
+// ship these. They mirror the runtime shapes exercised by cli/sdk/index.test.mjs
+// (the semver anchor). The eight exported names and their return-shape top-level
+// keys are the stable, semver-covered surface; deeper nested shapes follow the
+// same JSON the CLI's `--json` mode emits.
+//
+// Import: `import { route, search } from "@design-ai/cli/sdk";`
+
+// ── Shared building blocks ────────────────────────────────────────────────
+
+/** A curated reference (skill/agent/knowledge/command) and whether it exists on disk. */
+export interface RouteReference {
+  path: string;
+  exists: boolean;
+}
+
+/** One reference-coverage tally (available vs total) within a route explanation. */
+export interface CoverageCount {
+  available: number;
+  total: number;
+}
+
+export interface ReferenceCoverage {
+  command: CoverageCount;
+  skills: CoverageCount;
+  agents: CoverageCount;
+  knowledge: CoverageCount;
+  total: CoverageCount;
+}
+
+export interface ScoreBreakdownEntry {
+  label: string;
+  value: number;
+}
+
+export interface RouteExplanation {
+  summary: string;
+  scoreBreakdown: ScoreBreakdownEntry[];
+  referenceCoverage: ReferenceCoverage;
+  missingReferences: string[];
+}
+
+/** Advisory brief-relevant knowledge recalled by the shared lexical scorer. */
+export interface RelatedKnowledge {
+  id: string;
+  score: number;
+  matchedTokens: string[];
+}
+
+export type RouteConfidence = "high" | "medium" | "low" | "catalog" | "forced";
+
+export interface RouteResult {
+  id: string;
+  label: string;
+  score: number;
+  confidence: RouteConfidence;
+  matchedKeywords: string[];
+  command: RouteReference | null;
+  skills: RouteReference[];
+  agents: RouteReference[];
+  knowledge: RouteReference[];
+  keywords: string[];
+  explanation: RouteExplanation;
+  /** Present only when `route(brief, { explain: true })` is requested. */
+  relatedKnowledge?: RelatedKnowledge[];
+  /** Present only when a route was forced via `routeId`. */
+  forced?: boolean;
+  /** Present only when the fallback route was used. */
+  fallback?: boolean;
+}
+
+export interface RouteCatalog {
+  version: string;
+  routes: RouteResult[];
+}
+
+// ── prompt / pack ─────────────────────────────────────────────────────────
+
+export interface ReferenceExample {
+  relPath: string;
+  title: string;
+  category: string;
+  score: number;
+  preview: string;
+}
+
+/** A single recalled learning-profile entry. */
+export interface LearningRecallEntry {
+  id: string;
+  category: string;
+  score: number;
+  matchedTokens: string[];
+  text: string;
+}
+
+/** A single recalled shipped-corpus knowledge entry. */
+export interface CorpusRecallEntry {
+  id: string;
+  score: number;
+  matchedTokens: string[];
+}
+
+/** Recall block embedded in a prompt plan when `withRecall: true`. */
+export interface PromptRecall {
+  query: string;
+  mode: string;
+  candidateCount: number;
+  selectedCount: number;
+  selected: CorpusRecallEntry[];
+  markdown: string;
+}
+
+/** A stored learning-profile entry, as surfaced in a prompt plan's learning context. */
+export interface LearningEntry {
+  id: string;
+  category: string;
+  text: string;
+  source: string;
+  createdAt: string;
+}
+
+export interface LearningSelection {
+  mode: string;
+  query: string;
+  candidateCount: number;
+  matchedCount: number;
+  queryTokenCount: number;
+  fallbackEnabled: boolean;
+  selectedCount: number;
+  fallbackCount: number;
+  selected: LearningRecallEntry[];
+}
+
+export interface LearningAuditSummary {
+  status: string;
+  failures: number;
+  warnings: number;
+}
+
+/** Learning context embedded in a prompt plan when `withLearning: true`. */
+export interface LearningContext {
+  file: string;
+  category: string;
+  limit: number;
+  query: string;
+  selection: LearningSelection;
+  entries: LearningEntry[];
+  empty: boolean;
+  auditSummary: LearningAuditSummary;
+  markdown: string;
+}
+
+export interface PromptPlan {
+  brief: string;
+  version: string;
+  route: RouteResult;
+  slashCommand: string;
+  referenceExamples: ReferenceExample[];
+  filesToRead: string[];
+  checklist: string[];
+  qualityCommand: string;
+  prompt: string;
+  /** Present only when `prompt(brief, { withLearning: true })` is requested. */
+  learningContext?: LearningContext;
+  /** Present only when `prompt(brief, { withRecall: true })` is requested. */
+  recall?: PromptRecall;
+}
+
+export interface PackSummary {
+  totalFiles: number;
+  includedFiles: number;
+  truncatedFiles: number;
+  missingFiles: number;
+  usedBytes: number;
+  maxBytes: number;
+  remainingBytes: number;
+  usedRatio: number;
+  status: string;
+}
+
+export interface PackFile {
+  path: string;
+  bytes: number;
+  includedBytes: number;
+  included: boolean;
+  truncated: boolean;
+  content: string;
+}
+
+export interface Pack {
+  brief: string;
+  version: string;
+  maxBytes: number;
+  usedBytes: number;
+  summary: PackSummary;
+  warnings: string[];
+  plan: PromptPlan;
+  files: PackFile[];
+  markdown: string;
+}
+
+// ── search ────────────────────────────────────────────────────────────────
+
+/** A plain line hit (default `search`). */
+export interface SearchHit {
+  file: string;
+  lineNumber: number;
+  relPath: string;
+  preview: string;
+}
+
+/** A ranked hit (`search(query, { ranked: true })`) with a BM25 score. */
+export interface RankedSearchHit {
+  relPath: string;
+  file: string;
+  score: number;
+  matchedTokens: string[];
+  preview: string;
+}
+
+// ── recall ────────────────────────────────────────────────────────────────
+
+export interface RecallCorpus {
+  candidateCount: number;
+  selectedCount: number;
+  selected: CorpusRecallEntry[];
+}
+
+export interface RecallLearning {
+  mode: string;
+  candidateCount: number;
+  selectedCount: number;
+  selected: LearningRecallEntry[];
+}
+
+export interface RecallResult {
+  corpus: RecallCorpus;
+  learning: RecallLearning;
+}
+
+// ── check ─────────────────────────────────────────────────────────────────
+
+export type CheckLevel = "pass" | "warn" | "fail";
+
+export interface CheckResult {
+  id: string;
+  title: string;
+  level: CheckLevel;
+  passed: boolean;
+  message: string;
+  /** Present only when the check has supporting evidence. */
+  evidence?: string;
+}
+
+export interface CheckReport {
+  filePath: string;
+  /** Present only when a `routeId` was supplied. */
+  routeId?: string;
+  status: CheckLevel;
+  passes: number;
+  warnings: number;
+  failures: number;
+  total: number;
+  /** Human-readable ratio, e.g. "6/8". */
+  score: string;
+  results: CheckResult[];
+}
+
+export interface VersionReport {
+  cli: string;
+  corpus: string;
+}
+
+// ── Option objects ────────────────────────────────────────────────────────
+
+export interface RouteOptions {
+  /** Max routes to return. Default 3, range 1–10. */
+  limit?: number;
+  /** Include the advisory explanation + related-knowledge section. Default false. */
+  explain?: boolean;
+}
+
+export interface PromptOptions {
+  /** Force a specific route id instead of scoring the brief. */
+  routeId?: string;
+  /** Include local learning-profile guidance (read-only; never recorded). Default false. */
+  withLearning?: boolean;
+  /** Restrict learning guidance to a category. */
+  learningCategory?: string;
+  /** Max learning entries. Range 1–100. */
+  learningLimit?: number;
+  /** Include a brief-relevant corpus recall block. Default false. */
+  withRecall?: boolean;
+  /** Max recall entries. Range 1–20. */
+  recallLimit?: number;
+}
+
+export interface PackOptions extends PromptOptions {
+  /** Byte budget for the bundled context files. Default 120000, range 1000–1000000. */
+  maxBytes?: number;
+}
+
+export interface SearchOptions {
+  /** Restrict to one corpus directory (must be a known search dir). */
+  dir?: string;
+  /** Max hits. Default 20, range 1–500. */
+  limit?: number;
+  /** Return ranked BM25 hits (score + matchedTokens) instead of plain line hits. */
+  ranked?: boolean;
+}
+
+export interface RecallOptions {
+  /** Max entries per side (corpus/learning). Range 1–20. */
+  limit?: number;
+  /** Restrict learning recall to a category. */
+  category?: string;
+}
+
+export interface CheckOptions {
+  /** Apply route-specific requirements for this route id. */
+  routeId?: string;
+  /** Validated for parity with the CLI; has no effect in-process (no exit code). */
+  strict?: boolean;
+}
+
+// ── The eight Phase A verbs ─────────────────────────────────────────────────
+
+/** Recommend the best route(s), commands, skills, and knowledge for a brief. */
+export function route(brief: string, opts?: RouteOptions): RouteResult[];
+
+/** List the full route catalog independent of any brief. */
+export function routes(): RouteCatalog;
+
+/** Build a ready-to-use agent prompt plan from a brief. */
+export function prompt(brief: string, opts?: PromptOptions): PromptPlan;
+
+/** Build a prompt plan plus a bounded context-file bundle from a brief. */
+export function pack(brief: string, opts?: PackOptions): Pack;
+
+/** Search the local corpus. Returns ranked hits when `ranked: true`, else plain line hits. */
+export function search(query: string, opts: SearchOptions & { ranked: true }): RankedSearchHit[];
+export function search(query: string, opts?: SearchOptions): SearchHit[];
+
+/** Recall brief-relevant corpus knowledge and local learning-profile entries. */
+export function recall(query: string, opts?: RecallOptions): RecallResult;
+
+/** Check a Markdown artifact's content for grounding, accessibility, and route requirements. */
+export function check(artifact: string, opts?: CheckOptions): CheckReport;
+
+/** Report the CLI package version and the plugin/corpus version. */
+export function version(): VersionReport;
+
+// ── learn.* (Phase B — local writes) ─────────────────────────────────────
+//
+// The ONLY writing verbs in the SDK. Each writes exclusively to the local
+// learning profile (`DESIGN_AI_LEARNING_FILE` / defaultLearningFile()), never
+// the network. There is no `filePath` or `now`/timestamp option on any of
+// these — target a specific profile via the `DESIGN_AI_LEARNING_FILE` env
+// var, exactly like the CLI. See docs/SDK.md "Phase B — local writes".
+
+export interface LearnRememberOptions {
+  /** Learning-profile category. Default "preference". */
+  category?: string;
+}
+
+export interface LearnFeedbackOptions {
+  /** Feedback outcome; normalized by the underlying lib (e.g. "keep" | "avoid" | "improve"). Default "improve". */
+  outcome?: string;
+  /** Learning-profile category. Default "workflow". */
+  category?: string;
+}
+
+export interface LearnCaptureOptions {
+  /** Add route-specific check requirements for this route id before capturing. */
+  routeId?: string;
+}
+
+/** A single stored learning-profile entry, as written by learn.remember/feedback/captureFromCheck. */
+export interface LearningProfileEntry {
+  id: string;
+  category: string;
+  text: string;
+  source: string;
+  createdAt: string;
+}
+
+export interface LearningProfile {
+  version: number;
+  updatedAt: string;
+  entries: LearningProfileEntry[];
+}
+
+/** Return shape of learn.remember() and learn.feedback(). */
+export interface RememberResult {
+  file: string;
+  entry: LearningProfileEntry;
+  profile: LearningProfile;
+}
+
+/** An entry skipped by learn.captureFromCheck() because it duplicates an existing profile entry. */
+export interface CaptureSkippedEntry {
+  category: string;
+  text: string;
+  source: string;
+  reason: string;
+}
+
+/** Return shape of learn.captureFromCheck() — the `captureLearningEntries` result. */
+export interface CaptureResult {
+  file: string;
+  dryRun: boolean;
+  applied: boolean;
+  source: string;
+  candidateCount: number;
+  addedCount: number;
+  skippedCount: number;
+  count: number;
+  entries: LearningProfileEntry[];
+  skipped: CaptureSkippedEntry[];
+}
+
+/**
+ * Phase B: the explicit, opt-in LOCAL-WRITE namespace. `learn.remember`,
+ * `learn.feedback`, and `learn.captureFromCheck` are the only SDK verbs that
+ * write files — each writes only the local learning profile.
+ */
+export declare const learn: {
+  /** Record a local learning-profile preference. */
+  remember(text: string, opts?: LearnRememberOptions): RememberResult;
+  /** Record feedback (keep/avoid/improve) as a local learning-profile entry. */
+  feedback(text: string, opts?: LearnFeedbackOptions): RememberResult;
+  /** Check a Markdown artifact and capture its non-pass results as local learning-profile entries. */
+  captureFromCheck(artifact: string, opts?: LearnCaptureOptions): CaptureResult;
+};

package/cli/sdk/index.mjs

@@ -0,0 +1,30 @@
+// design-ai Agent SDK — Phase A (read-only) + Phase B (local writes). 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. The 8 Phase A verbs below perform no file writes: no
+// learning-usage sidecar writes, even from prompt/pack's withLearning option.
+//
+// Phase B adds a single `learn` namespace grouping the three explicit,
+// opt-in LOCAL-WRITE verbs (`learn.remember`, `learn.feedback`,
+// `learn.captureFromCheck`). This keeps the write boundary explicit: the 8
+// Phase A verbs stay read-only and unchanged; `learn` is the only place the
+// SDK writes files, and it only ever writes the local learning profile.
+//
+// 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 function exports plus the `learn` namespace
+// below are covered by the semver stability contract described in docs/SDK.md.
+
+export { check } from "./check-adapter.mjs";
+export { learn } from "./learn-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";