@design-ai/cli 4.58.0 → 4.60.0

package/cli/sdk/learn-adapter.mjs

@@ -0,0 +1,100 @@
+// SDK namespace: learn.*. See docs/AGENT-SDK.md (Phase B) and docs/SDK.md.
+//
+// The ONLY writing verbs in the SDK. Phase A (route, prompt, pack, search,
+// recall, check, routes, version) stays read-only and unchanged — this
+// namespace is the explicit, opt-in write boundary: every verb here writes
+// only the local learning profile (`DESIGN_AI_LEARNING_FILE` /
+// `defaultLearningFile()`), never the network. Consumers target a specific
+// profile file via the `DESIGN_AI_LEARNING_FILE` env var, exactly like the
+// CLI — there is no `filePath` option and no `now`/timestamp option; the
+// underlying cli/lib functions use their own defaults (the env var and
+// `new Date()`).
+
+import { checkArtifactContent, buildCheckLearningCapture } from "../lib/check.mjs";
+import { rememberLearning, recordLearningFeedback } from "../lib/learn-profile.mjs";
+import { assertKnownRouteId } from "../lib/route.mjs";
+import { optionalString, requireNonEmptyString, requireOptions } from "./validate.mjs";
+
+/**
+ * Record a local learning-profile preference. Writes only the local learning
+ * profile (`DESIGN_AI_LEARNING_FILE` / `defaultLearningFile()`); never the
+ * network. Pure adapter over `rememberLearning` from cli/lib/learn-profile.mjs.
+ *
+ * @param {string} text - Preference text to remember.
+ * @param {{category?: string}} [opts]
+ * @returns {{file: string, entry: object, profile: object}} RememberResult.
+ */
+function remember(text, opts = {}) {
+  requireNonEmptyString(text, "text");
+  const options = requireOptions(opts, "learn.remember");
+  const category = optionalString(options.category, "category", "preference");
+
+  return rememberLearning({
+    text,
+    category,
+    source: "sdk",
+  });
+}
+
+/**
+ * Record feedback (keep/avoid/improve) as a local learning-profile entry.
+ * Writes only the local learning profile; never the network. Pure adapter
+ * over `recordLearningFeedback` from cli/lib/learn-profile.mjs.
+ *
+ * @param {string} text - Feedback text.
+ * @param {{outcome?: string, category?: string}} [opts]
+ * @returns {{file: string, entry: object, profile: object}} RememberResult.
+ */
+function feedback(text, opts = {}) {
+  requireNonEmptyString(text, "text");
+  const options = requireOptions(opts, "learn.feedback");
+  // The lib normalizes the outcome itself (normalizeFeedbackOutcome); the SDK
+  // only validates that, if given, it is a string.
+  const outcome = optionalString(options.outcome, "outcome", "improve");
+  const category = optionalString(options.category, "category", "workflow");
+
+  return recordLearningFeedback({
+    text,
+    outcome,
+    category,
+  });
+}
+
+/**
+ * Check a Markdown artifact, then capture its non-pass results as local
+ * learning-profile entries. Writes only the local learning profile; never the
+ * network. Pure adapter over `checkArtifactContent` + `buildCheckLearningCapture`
+ * from cli/lib/check.mjs (the same path as the CLI's `check --learn --yes`).
+ *
+ * @param {string} artifact - Markdown artifact content to check and capture.
+ * @param {{routeId?: string}} [opts]
+ * @returns {object} CaptureResult — the `captureLearningEntries` return shape:
+ *   { file, dryRun, applied, source, candidateCount, addedCount, skippedCount,
+ *     count, entries, skipped }.
+ */
+function captureFromCheck(artifact, opts = {}) {
+  requireNonEmptyString(artifact, "artifact");
+  const options = requireOptions(opts, "learn.captureFromCheck");
+
+  const routeId = optionalString(options.routeId, "routeId");
+  if (routeId) assertKnownRouteId(routeId, { allowEmpty: false });
+
+  const report = checkArtifactContent({
+    content: artifact,
+    filePath: "sdk",
+    routeId,
+  });
+
+  return buildCheckLearningCapture(report, { dryRun: false });
+}
+
+/**
+ * The Phase B local-write namespace. `learn.remember`, `learn.feedback`, and
+ * `learn.captureFromCheck` are the only SDK verbs that write files; all three
+ * write exclusively to the local learning profile. See docs/SDK.md.
+ */
+export const learn = Object.freeze({
+  remember,
+  feedback,
+  captureFromCheck,
+});

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,
+  };
+}

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 — explicit local writes (shipped)
+
+Implemented as a single `learn` namespace export grouping three opt-in adapters that mirror the CLI's local-write commands: `learn.remember`, `learn.feedback`, and `learn.captureFromCheck` (capture from a `check()` report). Each writes only the local learning profile (`DESIGN_AI_LEARNING_FILE` / `defaultLearningFile()`), never the network — no `filePath` or `now`/timestamp option; consumers target a profile via the env var, exactly like the CLI. The 8 Phase A verbs are unchanged and stay read-only; `check()` in particular gets no capture option — capture is reached only through the separate, explicitly-named `learn.captureFromCheck`, keeping the write boundary visible at the call site. See [`SDK.md`](SDK.md#phase-b--local-writes) for the full reference.
+
+## 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,103 @@
 # Roadmap
 
+## Phase 761 — Agent SDK types + Phase B Release (v4.60.0) ✓ ready
+
+Ships the Agent SDK TypeScript declarations (Phase 759) and the `learn.*` local-write namespace (Phase 760) together as one npm version. Both are additive and backward-compatible: the eight Phase A verbs stay read-only and unchanged, and TypeScript types resolve automatically for `@design-ai/cli/sdk` with no build step on either side.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check` (unit tests incl. SDK type-sync guard and `learn.*` write tests, strict audits, whitespace, package contents, release metadata, release self-tests, packed-tarball smoke that imports `@design-ai/cli/sdk` and exercises `learn.remember`).
+- `npm run release:metadata`.
+- `git diff --check`.
+- The declarations compile under `tsc --strict` against a real consumer (transient check; TypeScript is not a package dependency).
+- 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/editor tooling resolves the full SDK surface (verbs, option interfaces, return types) with zero `@types` install and zero build step, and agents gain an explicit, opt-in `learn.*` write namespace for recording preferences, feedback, and check-derived learnings — while every read-only verb keeps its no-write guarantee.
+
+### What's still ahead
+- SDK surface is feature-complete for the planned phases; further verbs are demand-driven. Remaining roadmap work returns to other surfaces (see later phases).
+
+## Phase 760 — Agent SDK Phase B (local writes, implemented, unreleased)
+
+Adds the Phase B local-write surface described in [AGENT-SDK.md](AGENT-SDK.md#phase-b--explicit-local-writes-shipped): a single `learn` namespace export grouping three explicit, opt-in local-write verbs (`learn.remember`, `learn.feedback`, `learn.captureFromCheck`). This is the only place the SDK writes files; the 8 Phase A verbs are unchanged and stay read-only — `check()` in particular gets no capture option, so its read-only contract test still holds. Landed in `main` as `cli/sdk/learn-adapter.mjs`; code-complete and gated but not yet released as an npm version.
+
+### Delivered
+- [x] `learn.remember(text, opts?)` — records a local learning-profile preference. Adapter over `rememberLearning` from `cli/lib/learn-profile.mjs`; always writes `source: "sdk"`.
+- [x] `learn.feedback(text, opts?)` — records keep/avoid/improve feedback as a learning-profile entry. Adapter over `recordLearningFeedback`; the library normalizes `outcome` and folds it into the stored entry's `text` and `source`.
+- [x] `learn.captureFromCheck(artifact, opts?)` — checks a Markdown artifact, then captures its non-pass results as learning-profile entries. Adapter over `checkArtifactContent` + `buildCheckLearningCapture` from `cli/lib/check.mjs` — the SDK equivalent of the CLI's `check --learn --yes`. Duplicate captures are skipped (`reason: "duplicate-entry-text"`).
+- [x] All three write **only** the local learning profile (`DESIGN_AI_LEARNING_FILE` / `defaultLearningFile()`), never the network; no `filePath` or `now`/timestamp option on any of them — consumers target a profile via the env var, exactly like the CLI.
+- [x] `learn` is a frozen object (`Object.freeze`); `cli/sdk/index.mjs` re-exports it alongside the 8 unchanged Phase A verbs.
+- [x] Input validation reused from `cli/sdk/validate.mjs` (`requireNonEmptyString`, `requireOptions`, `optionalString`); `routeId` validated with the same `assertKnownRouteId` helper the read-only `check` adapter uses.
+- [x] `cli/sdk/learn-adapter.test.mjs` — per-verb coverage: persistence (re-reading the written profile), `remember`'s `source: "sdk"`, `feedback`'s outcome-to-text/source mapping, `captureFromCheck`'s added/skipped results and duplicate-capture skip, and bad-input rejection. 16 new tests.
+- [x] `cli/sdk/index.test.mjs` contract test updated: the 8 read-only function verbs are pinned unchanged; `learn` is pinned as a frozen object export with exactly `["captureFromCheck", "feedback", "remember"]`, plus return-shape keys for each verb (including the full `captureLearningEntries` result shape: `file, dryRun, applied, source, candidateCount, addedCount, skippedCount, count, entries, skipped`).
+- [x] `cli/sdk/types.test.mjs` unchanged and passing (it filters to `typeof === "function"`, so the `learn` object export is naturally excluded); a new assertion added confirming `index.d.ts` declares `export declare const learn:`.
+- [x] `cli/sdk/index.d.ts` — hand-written types for `LearnRememberOptions`, `LearnFeedbackOptions`, `LearnCaptureOptions`, `LearningProfileEntry`, `LearningProfile`, `RememberResult`, `CaptureSkippedEntry`, `CaptureResult`, and the `learn` const declaration. Verified to compile under `tsc --strict` against a transient consumer (zero-toolchain stance preserved — TypeScript is not added to `package.json`).
+- [x] `docs/SDK.md` — "Phase B — local writes" section replaces the "not yet shipped" placeholder: full reference for all three verbs, options, return shapes, the `DESIGN_AI_LEARNING_FILE` target, and the write-boundary rationale.
+- [x] `docs/AGENT-SDK.md` Phase B section updated from "only if demand" to shipped.
+- [x] `npm test` (563/563), `npm run audit` (8/8), `npm run release:metadata` all pass.
+
+### Remaining
+- [ ] Release decision: bundle Phase B into the next npm version alongside or after Phase 759's TypeScript declarations.
+- [ ] Optional follow-up: extend the packed-tarball SDK smoke (`tools/audit/package-smoke.py`) to exercise `learn.remember` against a temp `DESIGN_AI_LEARNING_FILE`.
+
+## Phase 759 — Agent SDK TypeScript declarations (implemented, unreleased)
+
+Ships hand-written type declarations for the eight SDK verbs so TypeScript and editor tooling resolve `@design-ai/cli/sdk` with full types — no `@types` package, no build step (the `.d.ts` is maintained by hand to preserve the zero-toolchain stance). Landed in `main` as `cli/sdk/index.d.ts`; additive (types only), pending bundling into the next npm version.
+
+### Delivered
+- [x] `cli/sdk/index.d.ts` — precise signatures + return interfaces for all eight verbs (incl. `search` ranked/plain overloads, the `RouteConfidence` union, and optional `learningContext`/`recall`/`relatedKnowledge` fields), derived from the runtime shapes the contract test pins.
+- [x] `exports` `types` condition (`"./sdk": { "types": …, "default": … }`) so the subpath resolves declarations under `moduleResolution: node16`/`nodenext`/`bundler`.
+- [x] `cli/sdk/types.test.mjs` — zero-dependency guard asserting the `.d.ts` declares exactly the runtime-exported verbs (drift anchor). Declarations independently verified to compile under `tsc --strict` against a real consumer.
+- [x] `docs/SDK.md` TypeScript section.
+
+### Remaining
+- [ ] Release: bundle into the next npm version (with Phase B, or standalone).
+
+## 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
+- Phase B explicit local-write adapters (`learn.remember`/`feedback`, capture) — implemented and landed in `main` (see Phase 760); pending release.
+- Hand-written `cli/sdk/index.d.ts` TypeScript declarations shipped after this release (see Phase 759).
+
+## 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.