@design-ai/cli 4.59.0 → 4.61.0

package/docs/ROADMAP.md

@@ -1,5 +1,100 @@
 # Roadmap
 
+## Phase 763 — Ranked-search Eval Checkpoint Release (v4.61.0) ✓ ready
+
+Ships the FU-3 ranked-search eval checkpoint (Phase 762) as an npm version: `search --eval-template` / `search --eval [--strict]` over the shipped BM25 path, with the Korean particle-form regression cases in the default template. Additive and backward-compatible; default `search` behavior is unchanged. With this release the AI-learning Phase A follow-ups (FU-1–FU-4) are all closed and published.
+
+### Verified
+- All 8 audits passed.
+- `npm run release:check` (unit tests incl. search-eval and search-command suites, 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.60.0 → 4.61.0.
+- `vscode-extension/package.json`: remains 0.4.1.
+
+### What this enables
+- The `--ranked` default-promotion decision becomes evidence-backed for npm users too: the published CLI carries the checkpoint tooling, so the eval can be re-run against any installed version — including Korean agglutinative-query regressions — before and after such a change.
+
+### What's still ahead
+- The `--ranked` default-promotion decision itself (separate, evidence-backed call).
+- Next-surface re-evaluation per the updated decision record in [NEXT-SURFACE-DECISION.md](NEXT-SURFACE-DECISION.md).
+
+## Phase 762 — Ranked-search eval checkpoint (FU-3, implemented, unreleased)
+
+Closes the last open follow-up from the AI-learning Phase A review ([AI-LEARNING-PHASE2.md](AI-LEARNING-PHASE2.md), FU-3): `design-ai search` gains `--eval-template` / `--eval [--strict]` checkpoint modes mirroring the route/prompt/pack/learn eval pattern, run through the shipped ranked (BM25) search path. This is the standing evidence artifact for any future decision to promote `--ranked` to the default; with FU-1/FU-2/FU-4 already annotated done, all four Phase A follow-ups are now closed.
+
+### Delivered
+- [x] `cli/lib/search-eval.mjs` — `SEARCH_EVAL_VERSION = 1`, `buildSearchEvalTemplate()`, `searchEvalReport()` over `rankedSearchCorpus`; route-style payload normalization and error messages. Case schema: `id`, `query`, optional `dirs`/`limit`, assertions `expectRelPathIn` / `minHits` / `matchedTokenIncludes`.
+- [x] Default template includes the FU-1 Korean particle-form regression cases (`버튼`, `버튼을`, `접근성이`) plus three English cases — so the eval doubles as the retrieval-level Hangul-bigram regression. All six verified passing against the shipped corpus (`--strict` exit 0).
+- [x] CLI wiring in `cli/lib/search.mjs` / `cli/commands/search.mjs` (`--eval-template`, `--eval`, `--strict`, `--from-file`, `--stdin`, mutual-exclusivity validation), help topic usage line, and the shared `smoke_assertions.py` pins (4 spots — shared constants, so both package and registry smokes stay aligned).
+- [x] Tests: `search-eval.test.mjs` (template, pass/warn/fail reports, malformed payloads) and `search-command.test.mjs` (CLI-level, strict exit semantics). 578/578 total.
+- [x] `docs/AI-LEARNING-PHASE2.md` FU-3 and FU-4 done annotations.
+
+### Remaining
+- [ ] Release: bundle into the next npm version.
+- [ ] The `--ranked` default-promotion decision itself — a future, separate call that this checkpoint now makes evidence-backed.
+
+## 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.
@@ -19,7 +114,8 @@ Ships the Agent SDK Phase A work (Phase 757) as an npm version: the curated, sem
 - 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 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)
 

package/docs/SDK.md

@@ -1,10 +1,10 @@
 # Agent SDK reference
 
-> Status: shipped (Phase A) — read-only verbs, semver-stable surface
+> Status: shipped (Phase A + Phase B) — 8 read-only verbs plus the opt-in `learn.*` local-write namespace, 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.
+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 (read-only) and Phase B (local-write) surface.
 
 ## Install and import
 
@@ -20,6 +20,16 @@ import { route, prompt, pack, search, recall, check, routes, version } from "@de
 
 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.
 
+### TypeScript
+
+Hand-written type declarations ship with the package at `cli/sdk/index.d.ts` and are wired through the `exports` `types` condition, so TypeScript and editors resolve them automatically for `@design-ai/cli/sdk` — no `@types` install, and no build step on our side (the declarations are maintained by hand to preserve the zero-toolchain stance). Use `moduleResolution: node16`/`nodenext` (or `bundler`) so the subpath `types` condition is honored. All exported types (`RouteResult`, `PromptPlan`, `Pack`, `SearchHit`, `RankedSearchHit`, `RecallResult`, `CheckReport`, option interfaces, …) are importable:
+
+```ts
+import { route, type RouteResult, type SearchOptions } from "@design-ai/cli/sdk";
+```
+
+A `node --test` guard (`cli/sdk/types.test.mjs`) asserts the declaration file stays in exact sync with the runtime exports.
+
 ## Phase A: read-only
 
 Every verb below is a pure, read-only adapter:
@@ -57,7 +67,7 @@ prompt(brief: string, opts?: {
   learningLimit?: number,
   withRecall?: boolean,
   recallLimit?: number,
-}): PromptPlan | null
+}): PromptPlan
 ```
 
 - `routeId` — force a route id instead of scoring the brief.
@@ -153,10 +163,87 @@ version(): { cli: string, corpus: string }
 
 - 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.
+- The 8 read-only function exports (`route`, `prompt`, `pack`, `search`, `recall`, `check`, `routes`, `version`) plus the frozen `learn` namespace object (`learn.remember`, `learn.feedback`, `learn.captureFromCheck`) 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 B — local writes
+
+Phase A (above) is read-only by design: the 8 verbs never write a file. Phase B adds a single namespace export, `learn`, grouping the three explicit, opt-in **LOCAL-WRITE** verbs. This is the only place the SDK writes files — every Phase A verb stays read-only and unchanged.
+
+```js
+import { learn } from "@design-ai/cli/sdk";
+
+learn.remember(text, opts?)               // opts: { category?: string }
+learn.feedback(text, opts?)                // opts: { outcome?: string, category?: string }
+learn.captureFromCheck(artifact, opts?)    // opts: { routeId?: string }
+```
+
+**Write boundary rationale:** an SDK consumer should never be surprised by a file write. Phase A's 8 verbs are safe to call from any context — a build script, a read path, a CI check — with zero side effects. `learn.*` is the deliberate, narrow exception: three verbs, one destination, no ambiguity about what gets written or where.
+
+All three verbs write **only** the local learning profile — `DESIGN_AI_LEARNING_FILE` if set, otherwise the CLI's `defaultLearningFile()` default path — and never touch the network. There is no `filePath` option and no `now`/timestamp option on any of them: target a specific profile the same way the CLI does, by setting the `DESIGN_AI_LEARNING_FILE` environment variable before calling. The underlying library functions supply their own defaults (the env var and `new Date()`).
+
+### `learn.remember(text, opts)`
+
+Record a local learning-profile preference. Adapter over `rememberLearning` from `cli/lib/learn-profile.mjs`.
+
+```js
+learn.remember(text: string, opts?: { category?: string }): RememberResult
+```
+
+- `text` — required, non-empty string.
+- `category` — one of the learning-profile categories (e.g. `preference`, `brand`, `workflow`, `constraint`, `accessibility`, `korean`, `other`); the library normalizes and validates it. Default: `"preference"`.
+
+Returns a `RememberResult`: `{ file, entry, profile }`, where `entry` is `{ id, category, text, source, createdAt }` (`source` is always `"sdk"`) and `profile` is the full updated learning profile `{ version, updatedAt, entries }`.
+
+### `learn.feedback(text, opts)`
+
+Record feedback (keep/avoid/improve) as a local learning-profile entry. Adapter over `recordLearningFeedback` from `cli/lib/learn-profile.mjs`.
+
+```js
+learn.feedback(text: string, opts?: { outcome?: string, category?: string }): RememberResult
+```
+
+- `text` — required, non-empty string.
+- `outcome` — any string; the library normalizes it (`normalizeFeedbackOutcome`) to one of `keep` / `avoid` / `improve` and folds it into both the stored entry's `text` (e.g. `"Avoid in future outputs: …"`) and its `source` (e.g. `"feedback:avoid"`). Default: `"improve"`.
+- `category` — same category enum as `remember`. Default: `"workflow"`.
+
+Returns the same `RememberResult` shape as `learn.remember`.
+
+### `learn.captureFromCheck(artifact, opts)`
+
+Check a Markdown artifact, then capture its non-pass results as local learning-profile entries — the SDK equivalent of the CLI's `check --learn --yes`. Adapter over `checkArtifactContent` + `buildCheckLearningCapture` from `cli/lib/check.mjs`.
+
+```js
+learn.captureFromCheck(artifact: string, opts?: { routeId?: string }): CaptureResult
+```
+
+- `artifact` — required, non-empty Markdown string.
+- `routeId` — add route-specific check requirements before capturing; must be a known route id (validated with the same `assertKnownRouteId` helper the read-only `check` adapter uses).
+
+Returns a `CaptureResult` — the `captureLearningEntries` return shape:
+
+```
+{
+  file: string,           // the learning profile file written to
+  dryRun: false,           // always false; captureFromCheck always applies
+  applied: true,           // always true when dryRun is false
+  source: string,          // "check:<routeId>" or "check:artifact"
+  candidateCount: number,  // non-pass check results considered
+  addedCount: number,      // entries newly written
+  skippedCount: number,    // entries skipped as duplicates of existing entries
+  count: number,           // total entries in the profile after this call
+  entries: LearningProfileEntry[],  // the entries that were added
+  skipped: Array<{ category, text, source, reason }>,  // reason is "duplicate-entry-text"
+}
+```
+
+Calling `captureFromCheck` twice with the same artifact adds nothing the second time — every candidate is skipped with `reason: "duplicate-entry-text"`.
+
+### Validation
+
+All three verbs use the same `cli/sdk/validate.mjs` helpers as Phase A: `requireNonEmptyString` for `text`/`artifact`, `requireOptions` for the options bag, and `optionalString` for string options. `routeId` is validated with `assertKnownRouteId`, exactly like the read-only `check` adapter. Bad input throws a plain `Error` with a clear message — no process exit code, no silent fallback.
+
+### What stays unchanged
 
-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.
+`check()` (the Phase A read-only verb) is untouched: it still never writes, and it has no capture option. Capture is exclusively reached through `learn.captureFromCheck`, which is a separate, explicitly-named write verb — this keeps the read/write boundary visible at the call site rather than hidden behind an option flag on a read-only function.

package/docs/external-status.md

@@ -1,22 +1,22 @@
 # External Publication Status
 
-> Checked: 2026-07-04
+> Checked: 2026-07-05
 > Scope: npm registry, GitHub Pages, Homebrew tap, VS Code Marketplace, Claude/Codex MCP
 
 ## Summary
 
-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.
+npm is publicly published at `@design-ai/cli@4.60.0` (npm dist-tag `latest` = `4.60.0`); publish run from tag `v4.60.0` succeeded with provenance and all pre-publish gates green. This release extends the Agent SDK (`@design-ai/cli/sdk`) with shipped TypeScript declarations (via an `exports` `types` condition) and the opt-in `learn.*` local-write namespace; the eight read-only verbs are unchanged, so CLI output is unchanged. The live `npm run registry:smoke` passes cleanly against published `@design-ai/cli@4.60.0` ("Registry smoke passed"), covering the retrieval surfaces (index/ranked/embeddings/recall) and route enrichment. GitHub Release `v4.60.0` is published, and the Homebrew tap formula points at the `v4.60.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.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" |
+| npm registry | `@design-ai/cli` | Published latest is `4.60.0` (tag `v4.60.0`, provenance). Pre-publish packed-tarball smoke (incl. SDK import + `learn.remember` write) and live `npm run registry:smoke` both pass for `@design-ai/cli@4.60.0`. | `npm view @design-ai/cli version` → `4.60.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.58.0` release source tarball with SHA-256 `45ec7fa4e82e7af38cdf948e1ad056a3758be848e5541013144e8d93d4c9da37` (recomputed from the published tag tarball) | `Formula/design-ai.rb` |
+| Homebrew tap | `Formula/design-ai.rb` | Formula pinned to `v4.60.0` release source tarball with SHA-256 `fa34af51c32d8e59dba4c1d293746688820e85ae03efa3b0bae4f3b3b2a34583` (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.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` |
+| GitHub Release | `v4.60.0` | Published for tag `v4.60.0` at commit `2d73c42` | `gh release view v4.60.0` |
+| MCP server | `@design-ai/cli@4.60.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-ai/cli",
-  "version": "4.59.0",
+  "version": "4.61.0",
   "description": "Senior product designer for any AI coding agent. Installs design-ai (20 skills, 17 commands, 4 agents) into Claude Code globally. Korean market depth plus website improvement control tower.",
   "bin": {
     "design-ai": "cli/bin/design-ai.mjs",
@@ -8,7 +8,10 @@
   },
   "type": "module",
   "exports": {
-    "./sdk": "./cli/sdk/index.mjs",
+    "./sdk": {
+      "types": "./cli/sdk/index.d.ts",
+      "default": "./cli/sdk/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "engines": {

package/tools/audit/package-smoke.py

@@ -763,15 +763,20 @@ def assert_version_json_smoke(cmd: list[str], *, env: dict[str, str], cwd: Path
     assert_version_json(result.stdout, context=context, cmd=cmd)
 
 
-# Phase A Agent SDK packed-tarball smoke (docs/AGENT-SDK.md, docs/SDK.md): imports
+# Agent SDK packed-tarball smoke (docs/AGENT-SDK.md, docs/SDK.md): imports
 # `@design-ai/cli/sdk` from the installed package (proving the package.json
 # "exports" map resolves) and exercises route/search(ranked)/recall, asserting
 # each call is deterministic (same input -> same JSON-serialized output) and
 # that Phase A's read-only contract holds (prompt/pack never include
-# learningUsage). This is a Node script, not a design-ai CLI invocation, so it
-# is run directly rather than through npm_exec_cmd/design-ai bin helpers.
+# learningUsage). Also exercises Phase B's `learn.remember` against a temp
+# DESIGN_AI_LEARNING_FILE and asserts it actually wrote the profile. This is a
+# Node script, not a design-ai CLI invocation, so it is run directly rather
+# than through npm_exec_cmd/design-ai bin helpers.
 SDK_SMOKE_SCRIPT = """
-import { check, pack, prompt, recall, route, routes, search, version } from "@design-ai/cli/sdk";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { check, learn, pack, prompt, recall, route, routes, search, version } from "@design-ai/cli/sdk";
 
 const brief = "Spec a Button component API with variants, props, and keyboard accessibility";
 
@@ -808,6 +813,23 @@ const ck = check(
 );
 if (typeof ck.status !== "string") throw new Error("check() bad shape");
 
+// Phase B: learn.remember must write only DESIGN_AI_LEARNING_FILE.
+const smokeDir = mkdtempSync(path.join(tmpdir(), "design-ai-sdk-learn-smoke-"));
+const learningFile = path.join(smokeDir, "learning.json");
+process.env.DESIGN_AI_LEARNING_FILE = learningFile;
+try {
+  const result = learn.remember("Package smoke: prefer 8px spacing grid.", { category: "preference" });
+  if (result.entry.source !== "sdk") throw new Error("learn.remember() entry.source must be 'sdk'");
+  if (!existsSync(learningFile)) throw new Error("learn.remember() did not write DESIGN_AI_LEARNING_FILE");
+  const onDisk = JSON.parse(readFileSync(learningFile, "utf8"));
+  if (!Array.isArray(onDisk.entries) || onDisk.entries.length !== 1) {
+    throw new Error("learn.remember() did not persist exactly one entry");
+  }
+} finally {
+  rmSync(smokeDir, { recursive: true, force: true });
+  delete process.env.DESIGN_AI_LEARNING_FILE;
+}
+
 console.log("design-ai sdk smoke passed");
 """.strip()
 

package/tools/audit/smoke_assertions.py

@@ -160,7 +160,7 @@ EXPECTED_HELP_TOPIC_USAGES = {
     "uninstall": "design-ai uninstall [--json]",
     "status": "design-ai status [--json]",
     "list": "design-ai list [skills|commands|agents] [--json]",
-    "search": "design-ai search <query> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]",
+    "search": "design-ai search <query|--eval-template|--eval> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider \"cmd args\"]] [--strict] [--json]",
     "index": "design-ai index [--build|--status|--verify] [--json] [--embeddings [--provider \"cmd args\"]]",
     "show": "design-ai show <file[:line]> [--lines N:M] [--context N] [--json]",
     "route": "design-ai route <brief|--from-file file|--stdin|--list|--eval-template|--eval> [--limit N]",
@@ -184,7 +184,12 @@ EXPECTED_HELP_TOPIC_FRAGMENTS = {
     "uninstall": ("Usage:", "design-ai uninstall [--json]"),
     "status": ("Usage:", "design-ai status [--json]"),
     "list": ("Usage:", "design-ai list [skills|commands|agents]"),
-    "search": ("Usage:", "design-ai search <query> [--limit N] [--dir kind] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]"),
+    "search": (
+        "Usage:",
+        "design-ai search <query> [--limit N] [--dir kind] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]",
+        "design-ai search --eval-template [--json]",
+        "design-ai search --eval --from-file search-eval.json [--strict] [--json]",
+    ),
     "index": ("Usage:", "design-ai index [--build|--status|--verify] [--json] [--embeddings [--provider \"cmd args\"]]"),
     "show": ("Usage:", "design-ai show <file[:line|start-end]> [--lines N:M] [--context N] [--json]"),
     "route": ("Usage:", "design-ai route <brief>", "design-ai route --list [--json]", "design-ai route --eval-template [--json]"),
@@ -364,7 +369,7 @@ EXPECTED_MAIN_HELP_FRAGMENTS = (
     "Usage:  design-ai <command> [args]",
     "design-ai help [command|--json]",
     "install",
-    "search <query>",
+    "search <query|--eval-template|--eval>",
     "show <file[:line]>",
     "route <brief|--from-file file|--stdin|--list|--eval-template|--eval>",
     "improve homepage conversion and SEO",
@@ -4669,8 +4674,8 @@ def passing_main_help_output() -> str:
         "        design-ai help [command|--json]",
         "",
         "  install                                                                Symlink design-ai into Claude Code (~/.claude)",
-        "  search <query> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]",
-        "    Search the local markdown corpus",
+        "  search <query|--eval-template|--eval> [--dir kind] [--limit N] [--ranked] [--embeddings [--provider \"cmd args\"]] [--strict] [--json]",
+        "    Search the local markdown corpus and ranked-search eval checkpoints",
         "  index [--build|--status|--verify] [--json] [--embeddings [--provider \"cmd args\"]]",
         "    Build, inspect, and verify the local retrieval index",
         "  show <file[:line]> [--lines N:M] [--context N] [--json]                Print a corpus file or line range",