@design-ai/cli 4.58.0 → 4.60.0

package/docs/SDK.md

@@ -0,0 +1,249 @@
+# Agent SDK reference
+
+> 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 (read-only) and Phase B (local-write) surface.
+
+## Install and import
+
+The SDK ships inside the `@design-ai/cli` package (no separate install):
+
+```bash
+npm install @design-ai/cli
+```
+
+```js
+import { route, prompt, pack, search, recall, check, routes, version } from "@design-ai/cli/sdk";
+```
+
+Only the `./sdk` subpath is exported — `import "@design-ai/cli"` (the bare package root) is intentionally not exported, so importing the SDK is always an explicit `@design-ai/cli/sdk` import. `cli/lib/*` is internal and unstable; do not import it directly.
+
+### 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:
+
+- It validates its inputs and throws a plain `Error` with a clear message on bad input (e.g. a non-string brief).
+- It resolves the package root the same way the CLI does.
+- It calls the corresponding `cli/lib` function and returns a plain JSON-serializable object — the same shape the CLI's `--json` mode emits.
+- It performs no file writes, no network calls, and no learning-usage sidecar writes. This is a deliberate difference from the CLI: `prompt`/`pack`'s `withLearning` option in the SDK only **reads** the local learning profile to build context — it never records a usage event, unlike the CLI's `--with-learning` flag. There is no SDK equivalent of `check --learn` (capture) in Phase A.
+- Given the same inputs, it returns the same outputs (determinism), matching the CLI.
+
+## Verbs
+
+### `route(brief, opts)`
+
+Recommend the best design-ai route(s), commands, skills, and knowledge files for a task brief.
+
+```js
+route(brief: string, opts?: { limit?: number, explain?: boolean }): RouteResult[]
+```
+
+- `limit` — maximum route recommendations, 1-10. Default: `3`.
+- `explain` — include route scoring, reference coverage, and related-knowledge detail. Default: `false`.
+
+Returns an array of `RouteResult` objects (`id`, `label`, `score`, `confidence`, `matchedKeywords`, `command`, `skills`, `agents`, `knowledge`, `keywords`, `explanation`, plus `relatedKnowledge` when `explain: true`) — the same shape as the `routes` array in `design-ai route --json`.
+
+### `prompt(brief, opts)`
+
+Build a ready-to-use agent prompt plan from a task brief.
+
+```js
+prompt(brief: string, opts?: {
+  routeId?: string,
+  withLearning?: boolean,
+  learningCategory?: string,
+  learningLimit?: number,
+  withRecall?: boolean,
+  recallLimit?: number,
+}): PromptPlan
+```
+
+- `routeId` — force a route id instead of scoring the brief.
+- `withLearning` — include brief-relevant local learning preferences (reads `DESIGN_AI_LEARNING_FILE`; **never** records usage, unlike the CLI's `--with-learning`).
+- `learningCategory`, `learningLimit` (1-100) — scope/limit the learning context; require `withLearning`.
+- `withRecall` — include brief-relevant shipped corpus knowledge.
+- `recallLimit` (1-20) — limit recalled corpus files; requires `withRecall`.
+
+Returns a `PromptPlan` object (`brief`, `version`, `route`, `slashCommand`, `referenceExamples`, `filesToRead`, `checklist`, `qualityCommand`, `prompt`, plus `learningContext`/`recall` when requested) — the same shape as `design-ai prompt --json`, minus `learningUsage` (Phase A never writes it).
+
+### `pack(brief, opts)`
+
+Build a ready-to-use prompt plus a bounded context-file bundle from a task brief.
+
+```js
+pack(brief: string, opts?: {
+  routeId?: string,
+  maxBytes?: number,
+  withLearning?: boolean,
+  learningCategory?: string,
+  learningLimit?: number,
+  withRecall?: boolean,
+  recallLimit?: number,
+}): Pack
+```
+
+- `maxBytes` — maximum context bytes to include, 1000-1,000,000. Default: `120000`.
+- The remaining options mirror `prompt`'s learning/recall options.
+
+Returns a `Pack` object (`brief`, `version`, `maxBytes`, `usedBytes`, `summary`, `warnings`, `plan`, `files`, `markdown`) — the same shape as `design-ai pack --json`, minus `learningUsage`.
+
+### `search(query, opts)`
+
+Search the local design-ai markdown corpus.
+
+```js
+search(query: string, opts?: { dir?: string, limit?: number, ranked?: boolean }): SearchHit[]
+```
+
+- `dir` — restrict to one corpus directory: `knowledge`, `examples`, `skills`, `docs`, `agents`, or `commands`.
+- `limit` — maximum hits, 1-500. Default: `20`.
+- `ranked` — rank results with the deterministic lexical (BM25-style) scorer instead of returning raw line hits. Default: `false`.
+
+Returns `SearchHit[]`. Unranked hits: `{ file, relPath, lineNumber, preview }`. Ranked hits: `{ file, relPath, score, matchedTokens, preview }` — the same shapes as `design-ai search --json` and `design-ai search --ranked --json`.
+
+### `recall(query, opts)`
+
+Recall brief-relevant shipped corpus knowledge and local learning-profile entries for a query — a combined read-only view.
+
+```js
+recall(query: string, opts?: { limit?: number, category?: string }): { corpus: object, learning: object }
+```
+
+- `limit` — applies to both the corpus and learning lists, 1-20. Default: `5`.
+- `category` — scopes only the learning list.
+
+Returns `{ corpus: { candidateCount, selectedCount, selected }, learning: { mode, candidateCount, selectedCount, selected } }` — the same shape as `design-ai learn --recall --json`.
+
+### `check(artifact, opts)`
+
+Check a generated design Markdown artifact for grounding, accessibility, responsive, unresolved-marker, and route-specific requirements.
+
+```js
+check(artifact: string, opts?: { routeId?: string, strict?: boolean }): CheckReport
+```
+
+- `routeId` — add route-specific checks (e.g. `component-spec`, `palette-from-brand`). Must be a known route id.
+- `strict` — accepted for CLI-flag parity but has no effect on the returned report; the SDK never sets a process exit code. Inspect `report.status` yourself.
+
+Returns a `CheckReport` object (`filePath`, `status`, `passes`, `warnings`, `failures`, `total`, `score`, `results`, plus `routeId` when passed) — the same shape as `design-ai check --json` (minus any `--learn` capture, which Phase A does not support).
+
+### `routes()`
+
+List the full route catalog (every route id with its static metadata), independent of any brief.
+
+```js
+routes(): { version: string, routes: RouteResult[] }
+```
+
+Returns the same shape as `design-ai route --list --json`.
+
+### `version()`
+
+Report the CLI package version and the plugin/corpus version.
+
+```js
+version(): { cli: string, corpus: string }
+```
+
+## Stability contract
+
+`@design-ai/cli/sdk` is **semver-stable**:
+
+- Additive changes (new optional fields, new opt-in options) are minor version bumps.
+- Signature or return-shape changes are major version bumps.
+- The 8 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 — 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
+
+`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-03
+> Checked: 2026-07-04
 > Scope: npm registry, GitHub Pages, Homebrew tap, VS Code Marketplace, Claude/Codex MCP
 
 ## Summary
 
-npm is publicly published at `@design-ai/cli@4.57.0` (npm dist-tag `latest` = `4.57.0`); publish run `28663430171` from tag `v4.57.0` succeeded with provenance and all pre-publish gates green (8 audits, CLI unit tests, release self-tests, package contents, and the packed-tarball installed-package smoke on the 4.57.0 tarball). The automated post-publish live registry smoke step failed on a stale learn-relevance token-order assertion in `tools/audit/registry-smoke.py` — a verification-tool bug fixed on `main` in `710656a`, not a package defect; the published package is validated by the pre-publish packed-tarball smoke. GitHub Release `v4.57.0` is published, and the Homebrew tap formula points at the `v4.57.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.59.0` (npm dist-tag `latest` = `4.59.0`); publish run from tag `v4.59.0` succeeded with provenance and all pre-publish gates green. This release adds the read-only Agent SDK surface (`@design-ai/cli/sdk`, eight adapter verbs) — additive only, so CLI output is unchanged. The live `npm run registry:smoke` passes cleanly against published `@design-ai/cli@4.59.0` ("Registry smoke passed"), covering the retrieval surfaces (index/ranked/embeddings/recall) and route enrichment. GitHub Release `v4.59.0` is published, and the Homebrew tap formula points at the `v4.59.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.57.0`; publish run `28663430171` (tag `v4.57.0`) succeeded with provenance. Pre-publish packed-tarball smoke passed on the 4.57.0 tarball; the post-publish live registry smoke failed on a stale assertion (fixed on `main` `710656a`). | publish run `28663430171`; `npm view @design-ai/cli version` → `4.57.0` |
+| npm registry | `@design-ai/cli` | Published latest is `4.59.0` (tag `v4.59.0`, provenance). Pre-publish packed-tarball smoke (incl. SDK import) and live `npm run registry:smoke` both pass for `@design-ai/cli@4.59.0`. | `npm view @design-ai/cli version` → `4.59.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.57.0` release source tarball with SHA-256 `c1fed279ed7bc2daf42473bd9a68cf3fa6df6823fe3390b2f2ccee8625407559` (recomputed from the published tag tarball) | `Formula/design-ai.rb` |
+| Homebrew tap | `Formula/design-ai.rb` | Formula pinned to `v4.59.0` release source tarball with SHA-256 `e711203fb96fee5f6e7f25d809bc42108553bc8108ddf3e8cd181f0a76f6e0f5` (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.57.0` | Published (not draft/prerelease) for tag `v4.57.0` at commit `4be46d7` | `gh release view v4.57.0` |
-| MCP server | `@design-ai/cli@4.57.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.59.0` | Published for tag `v4.59.0` at commit `9f53345` | `gh release view v4.59.0` |
+| MCP server | `@design-ai/cli@4.59.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,17 +1,24 @@
 {
   "name": "@design-ai/cli",
-  "version": "4.58.0",
+  "version": "4.60.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",
     "design-ai-mcp": "cli/bin/design-ai-mcp.mjs"
   },
   "type": "module",
+  "exports": {
+    "./sdk": {
+      "types": "./cli/sdk/index.d.ts",
+      "default": "./cli/sdk/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "engines": {
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test cli/lib/*.test.mjs",
+    "test": "node --test cli/lib/*.test.mjs cli/sdk/*.test.mjs",
     "audit": "python3 -B tools/audit/run-all.py",
     "audit:strict": "python3 -B tools/audit/run-all.py --strict",
     "audit:runner:self-test": "python3 -B tools/audit/run-all.py --self-test",

package/tools/audit/package-smoke.py

@@ -763,6 +763,85 @@ def assert_version_json_smoke(cmd: list[str], *, env: dict[str, str], cwd: Path
     assert_version_json(result.stdout, context=context, cmd=cmd)
 
 
+# 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). 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 { 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";
+
+const r1 = route(brief, { limit: 1 });
+const r2 = route(brief, { limit: 1 });
+if (JSON.stringify(r1) !== JSON.stringify(r2)) throw new Error("route() not deterministic");
+if (r1[0].id !== "component-spec") throw new Error(`unexpected route id: ${r1[0].id}`);
+
+const s1 = search("accessibility", { ranked: true, limit: 3 });
+const s2 = search("accessibility", { ranked: true, limit: 3 });
+if (JSON.stringify(s1) !== JSON.stringify(s2)) throw new Error("search() not deterministic");
+if (s1.length === 0) throw new Error("search() returned no hits");
+
+const rec1 = recall("keyboard accessibility button", { limit: 2 });
+const rec2 = recall("keyboard accessibility button", { limit: 2 });
+if (JSON.stringify(rec1) !== JSON.stringify(rec2)) throw new Error("recall() not deterministic");
+if (!rec1.corpus || !rec1.learning) throw new Error("recall() missing corpus/learning");
+
+const v = version();
+if (typeof v.cli !== "string" || typeof v.corpus !== "string") throw new Error("version() bad shape");
+
+const rc = routes();
+if (!Array.isArray(rc.routes) || rc.routes.length === 0) throw new Error("routes() bad shape");
+
+const p = prompt(brief, { routeId: "component-spec" });
+if (Object.hasOwn(p, "learningUsage")) throw new Error("prompt() must not include learningUsage in Phase A");
+
+const pk = pack(brief, { routeId: "component-spec", maxBytes: 20000 });
+if (Object.hasOwn(pk, "learningUsage")) throw new Error("pack() must not include learningUsage in Phase A");
+
+const ck = check(
+  "# T\\n\\nAnatomy variants API contrast 4.5:1 keyboard focus screen reader aria- responsive mobile desktop.",
+  { routeId: "component-spec" },
+);
+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()
+
+
+def assert_sdk_smoke(*, cwd: Path, env: dict[str, str], context: str) -> None:
+    result = run_plain(["node", "--input-type=module", "-e", SDK_SMOKE_SCRIPT], cwd=cwd, env=env)
+    if result.returncode != 0:
+        raise SystemExit(f"{context} failed (exit {result.returncode})")
+    if "design-ai sdk smoke passed" not in result.stdout:
+        raise SystemExit(f"{context}: expected success marker missing from output")
+
+
 def assert_workspace_json_smoke(cmd: list[str], *, env: dict[str, str], cwd: Path | None = None, context: str) -> None:
     result = run_plain(cmd, cwd=cwd, env=env)
     assert_workspace_json(result.stdout, context=context, cmd=cmd)
@@ -20239,6 +20318,11 @@ def smoke_tarball(tarball: Path) -> None:
             env=smoke_env,
             context="package smoke installed bin version JSON",
         )
+        assert_sdk_smoke(
+            cwd=install_root,
+            env=smoke_env,
+            context="package smoke installed Agent SDK (@design-ai/cli/sdk)",
+        )
         assert_design_ai_mcp_protocol_smoke(
             [str(mcp_bin_path)],
             cwd=install_root,

package/tools/audit/registry-smoke.py

@@ -4637,7 +4637,7 @@ def assert_learning_relevance_context(payload: dict[str, object], *, context: st
         message="learning selection explanation should mark the relevant entry as a brief match",
     )
     require_registry_smoke(
-        isinstance(selected_entry.get("score"), int) and selected_entry.get("score") > 0,
+        type(selected_entry.get("score")) in (int, float) and selected_entry.get("score") > 0,
         context=context,
         cmd=cmd,
         message="learning selection explanation should include a positive relevance score",
@@ -4759,7 +4759,7 @@ def assert_learning_query_json(
     require_registry_smoke(
         selected[0].get("id") == "learn-relevant"
         and selected[0].get("reason") == "brief-match"
-        and isinstance(selected[0].get("score"), int)
+        and type(selected[0].get("score")) in (int, float)
         and selected[0].get("score") > 0,
         context=context,
         cmd=cmd,