@design-ai/cli 4.57.0 → 4.59.0

package/knowledge/i18n/korean-density-conventions.md

@@ -0,0 +1,108 @@
+<!-- hand-written -->
+---
+title: Korean B2B density conventions
+applies_to: [web, mobile, all-ui, korean]
+version: 1.0.0
+last_updated: 2026-07
+stability: stable
+---
+
+# Korean B2B density conventions
+
+Korean enterprise software — ERP, HR, groupware, admin consoles, financial back-office — is visibly denser than its Western counterpart, and denser again than Korean *consumer* apps. A Western enterprise layout ported unchanged into a Korean B2B product reads as sparse, slow, and "not serious." This file is the density half of the Korean playbook; for consumer density and the broader Korean conventions, see [`knowledge/i18n/korean-product-conventions.md`](korean-product-conventions.md).
+
+## Why Korean B2B is denser
+
+- **Information-per-screen is a value, not a cost.** Power users (accountants, HR admins, operators) work the same screens all day and want everything in view — more rows, more columns, fewer clicks to the next field. Scrolling and pagination read as friction, not breathing room.
+- **The reference points are dense.** 더존, 영림원, SAP-Korea deployments, government e-gov portals, and bank back-office tools set the expectation. Naver Works / Kakao Work admin, Toss Business, and 뱅크샐러드 business consoles are the modern-but-still-dense benchmark.
+- **Hangul carries more meaning per character.** A Korean label is often shorter than its English equivalent for the same content, so the same row holds more without feeling cramped.
+
+This is a deliberate register, not clutter. The craft is being dense **and** legible — not dense **and** broken.
+
+## The density ladder
+
+Pick a mode per surface and hold it. Do not mix comfortable and compact rows in one table.
+
+| Mode | Row height (approx) | Use for |
+| --- | --- | --- |
+| **Comfortable** | 48–56px | Consumer-facing, onboarding, marketing-in-product, low-frequency admin |
+| **Cozy** (default KR B2B) | 36–44px | Most enterprise tables, forms, lists — the Korean B2B baseline |
+| **Compact** | 28–32px | Data grids for power users, financial ledgers, high-row-count monitoring |
+
+Western enterprise defaults to Comfortable; **Korean B2B defaults to Cozy.** Porting in usually means dropping one rung: reduce vertical padding ~15–25% and expect 30–50% more rows per fold. Offer a density toggle (Comfortable / Cozy / Compact) on heavy data surfaces so individual operators can go denser; persist the choice per user.
+
+## Tables are the center of gravity
+
+Korean B2B UIs are table-first. Most screens are a filter bar plus a table.
+
+- **Many columns are normal.** 8–15 columns is routine; horizontal scroll with a **frozen first column** (and often a frozen header row) beats hiding columns behind a menu.
+- **Compact rows, aligned numerals.** Right-align numbers and currency, use tabular figures, and keep row height in the Cozy/Compact band. See [`knowledge/patterns/money-and-amount.md`](../patterns/money-and-amount.md) for amount formatting.
+- **Inline row actions.** Put edit / delete / detail as compact icon buttons or a trailing action cell, not behind a per-row overflow menu that costs an extra click.
+- **Sticky context.** Freeze the header and the key identity column (사번, 거래처, 전표번호) so the operator never loses the row's identity while scrolling wide.
+- **Totals and subtotals in view.** A pinned footer row with sums/counts is expected on financial and inventory tables — operators reconcile against it constantly.
+- **Zebra or hairline rules, not heavy borders.** At Cozy/Compact density, 1px hairline separators or subtle zebra striping keep rows scannable without adding visual weight.
+
+## Forms at density
+
+- **Label-left (horizontal) layout** is the Korean B2B default for data-entry forms — it packs more fields per vertical space than label-top and matches the ledger-like mental model. Label-top is for consumer/onboarding.
+- **Multi-column forms.** Two or three field columns per row are normal for registration and master-data screens. Group by section with thin dividers, not big gaps.
+- **Tight field spacing.** Reduce inter-field vertical rhythm versus consumer forms; keep it consistent so the grid reads cleanly. See [`knowledge/patterns/form-design.md`](../patterns/form-design.md).
+- **Required/optional density.** Mark required with a compact indicator (asterisk or a small "필수" chip); don't spend a whole helper-text line per field unless the rule is non-obvious.
+- **Keyboard-first.** Power users tab through fields fast. Preserve a logical tab order, support Enter-to-next where appropriate, and don't trap focus in date/select popovers.
+
+## Lists, trees, and navigation
+
+- **Dense list rows** with secondary metadata inline (status chip, date, owner on one line) rather than stacked. See [`knowledge/patterns/list-and-feed.md`](../patterns/list-and-feed.md).
+- **Tree navigation** (조직도, 계정과목, 메뉴 권한) is common and should stay compact — small row height, clear expand affordances, many levels visible at once.
+- **Persistent side navigation** with dense, possibly two-level menus is expected over hamburger-hidden nav; enterprise users want the whole map visible. This is the opposite of the consumer preference noted in [`korean-product-conventions.md`](korean-product-conventions.md).
+
+## Typography at density
+
+- **Base size can drop, but not below legibility.** 13–14px body is common in KR B2B tables (vs 16px consumer). Do not go below ~12px for Hangul primary content — Hangul syllable blocks lose legibility faster than Latin at small sizes.
+- **Line-height stays generous relative to size.** Even dense Korean text needs ~1.4–1.5 line-height for the syllable blocks to breathe; do not crush leading to save space. See [`knowledge/i18n/korean-typography.md`](korean-typography.md).
+- **Numerals: tabular, aligned.** Financial density depends on figures lining up.
+- **Truncate with intent.** Ellipsize long values with a tooltip/title for the full string rather than wrapping and breaking row rhythm.
+
+## Density must not break accessibility
+
+Density is the constraint; accessibility is the floor. When they conflict, accessibility wins.
+
+- **Touch targets.** On touch/hybrid B2B (tablets on the floor, POS, hospital carts), keep interactive targets ≥ 44×44px *hit area* even when the visual row is compact — expand the clickable area beyond the visible cell rather than shrinking the target.
+- **Contrast holds at every density.** Hairline separators and secondary text must still meet WCAG contrast; dense does not mean low-contrast gray-on-gray. See [`knowledge/a11y/contrast.md`](../a11y/contrast.md).
+- **Focus visibility.** A visible focus ring is non-negotiable for keyboard-driven data entry; ensure it is not clipped by tight row borders. See [`knowledge/a11y/keyboard-and-focus.md`](../a11y/keyboard-and-focus.md).
+- **Density toggle as an a11y affordance.** Offering Comfortable mode is itself an accessibility accommodation for users who need larger targets and text.
+
+## Tokens consumed
+
+```
+--space-2xs, --space-xs      (dense row padding, inter-field gaps)
+--space-sm                   (section spacing at density)
+--row-height-compact         (or --space-based row sizing)
+--font-size-sm               (13–14px dense body)
+--line-height-normal         (~1.4–1.5 for Hangul)
+--color-border-subtle        (hairline separators)
+--color-bg-subtle            (zebra striping)
+--color-text-secondary       (inline metadata)
+--color-text-tabular         (aligned numerals)
+```
+
+Define a **density scale** as tokens (comfortable / cozy / compact row heights + padding) so the toggle flips a token set, not ad-hoc per-component values.
+
+## Don't
+
+- Don't ship Western enterprise comfortable-density defaults unchanged into a Korean B2B product — it reads as sparse and unserious.
+- Don't hide columns behind menus to avoid width — Korean power users prefer horizontal scroll with frozen columns.
+- Don't mix row-height modes within one table.
+- Don't crush Hangul below ~12px or crush line-height to gain rows — legibility breaks before the space saved is worth it.
+- Don't let density erode contrast, focus rings, or touch-target hit areas.
+- Don't bury per-row actions behind an overflow menu on high-frequency screens — inline them.
+- Don't apply consumer nav patterns (hamburger, hidden tabs) to enterprise — surface the full dense menu.
+
+## Cross-reference
+
+- [`knowledge/i18n/korean-product-conventions.md`](korean-product-conventions.md) — consumer density and the broader Korean conventions this file specializes from
+- [`knowledge/i18n/korean-typography.md`](korean-typography.md) — Hangul sizing and line-height at density
+- [`knowledge/patterns/form-design.md`](../patterns/form-design.md) — label-left, multi-column, dense forms
+- [`knowledge/patterns/list-and-feed.md`](../patterns/list-and-feed.md) — dense list rows and data grids
+- [`knowledge/patterns/money-and-amount.md`](../patterns/money-and-amount.md) — tabular numerals and aligned amounts
+- [`knowledge/a11y/contrast.md`](../a11y/contrast.md), [`knowledge/a11y/keyboard-and-focus.md`](../a11y/keyboard-and-focus.md) — the accessibility floor density must respect

package/knowledge/i18n/korean-product-conventions.md

@@ -58,6 +58,8 @@ This is not "cluttered design" — it matches reading pace and screen-time habit
 
 Reference: see how Coupang, Naver, KakaoTalk, Toss differ from Amazon, Google, WhatsApp, Robinhood.
 
+For enterprise / B2B density (denser again — ERP, HR, groupware, admin, financial back-office), see [`knowledge/i18n/korean-density-conventions.md`](korean-density-conventions.md).
+
 ## Color associations
 
 Different from Western color symbolism:

package/knowledge/patterns/async-control.md

@@ -0,0 +1,233 @@
+<!-- hand-written -->
+---
+title: Async control patterns
+applies_to: [web, mobile, all-ui]
+version: 1.0.0
+last_updated: 2026-07
+stability: stable
+---
+
+# Async control patterns
+
+Every action that talks to a server has an in-flight life. This file is about that life — the moment between the tap and the answer — not about the error screen at the end (see [`patterns/error-states.md`](error-states.md) for that). Get the in-flight state wrong and you get the two most common async bugs in product UIs: double submits and stuck spinners.
+
+## The async action lifecycle
+
+Every async action moves through the same four states. Model them explicitly; do not infer "loading" from the absence of data.
+
+```
+ idle ──trigger──▶ pending ──┬──▶ success ──▶ idle
+   ▲                         │
+   └─────────────────────────┴──▶ error ────▶ idle (retryable)
+```
+
+| State | The control shows | The user can |
+| --- | --- | --- |
+| **idle** | Its normal, enabled label | Trigger the action |
+| **pending** | Busy affordance + disabled | Wait, or cancel (if cancellable) |
+| **success** | Brief confirmation, then idle | Continue |
+| **error** | Recovery affordance | Retry or recover — see `error-states.md` |
+
+Rule: a control never sits in `pending` forever. Every request has a timeout that forces it to `error`.
+
+## Action controls during pending
+
+The trigger control (button, menu item, toggle) is where most async bugs live.
+
+| Do | Don't |
+| --- | --- |
+| Disable the control while its own action is in flight | Leave it clickable and hope |
+| Show a busy affordance **inside or beside** the control | Replace the whole screen with a spinner for a single button |
+| Keep the label readable — swap to a present-progressive verb | Blank the label to just a spinner (the user forgets what they clicked) |
+| Restore the control on success **and** error | Leave it disabled after a failed request |
+
+Label swap, Korean and English:
+
+| Idle | Pending | Done |
+| --- | --- | --- |
+| 저장 | 저장 중… | 저장됨 |
+| 불러오기 | 불러오는 중… | — |
+| 결제하기 | 결제 처리 중… | 결제 완료 |
+| 제출 | 제출 중… | — |
+
+```
+┌─────────────────┐      ┌─────────────────┐
+│     저장         │  →   │  ◌ 저장 중…      │   (disabled, spinner leads label)
+└─────────────────┘      └─────────────────┘
+```
+
+## Double-submit prevention
+
+The single most important async rule: **a control that started an action cannot start it again until that action resolves.** Disabling on `pending` handles the fast double-tap. Also guard the handler itself, because disabled is a UI state that a determined tap (or a slow render) can beat.
+
+```tsx
+function SubmitButton({ onSubmit }) {
+  const [status, setStatus] = useState("idle"); // idle | pending | error
+
+  async function handleClick() {
+    if (status === "pending") return;   // guard: not just the disabled attr
+    setStatus("pending");
+    try {
+      await onSubmit();
+      setStatus("idle");
+    } catch (err) {
+      setStatus("error");               // hand off to error-states.md
+    }
+  }
+
+  return (
+    <Button onClick={handleClick} disabled={status === "pending"} aria-busy={status === "pending"}>
+      {status === "pending" ? "저장 중…" : "저장"}
+    </Button>
+  );
+}
+```
+
+For money and irreversible actions (payment, transfer, delete), double-submit guarding is a correctness requirement, not a nicety. Pair the client guard with a server-side idempotency key — cite [`patterns/money-and-amount.md`](money-and-amount.md).
+
+## Choosing a loading affordance by duration
+
+Match the indicator to how long the wait actually is. Guessing wrong is worse than no indicator.
+
+| Expected wait | Affordance | Why |
+| --- | --- | --- |
+| < 100ms | **Nothing** | Faster than perception; a flashed spinner reads as a glitch |
+| 100ms – 1s | **In-place busy** (button spinner, subtle) | Confirms the tap registered |
+| 1s – 10s | **Skeleton** (for content) or **progress** (for known-length work) | Shows shape/position; feels faster than a spinner |
+| > 10s | **Progress + cancel + background option** | Let the user leave and be notified |
+| Unknown length | **Indeterminate spinner with a timeout** | Never an infinite bar |
+
+Spinner vs skeleton: a spinner says "something is happening"; a skeleton says "*this* is what's coming and where." Prefer skeletons for content regions (lists, cards, detail panes) — see [`patterns/list-and-feed.md`](list-and-feed.md). Reserve spinners for actions and small inline waits.
+
+Anti-flicker: if you show a delayed spinner (only after 100–300ms), also hold it for a minimum (~300ms) once shown, so a request that resolves at 310ms doesn't flash. Delay-in, min-hold-out.
+
+## Optimistic updates
+
+Apply the change in the UI immediately, before the server confirms, then reconcile.
+
+Use optimistic when: the action almost always succeeds, is cheap to reverse, and the wait would break flow — likes, toggles, reordering, adding a to-do, marking read.
+
+Do **not** use optimistic when: the action is money, irreversible, or the server is the source of truth for the result (payment, booking a seat, submitting an exam). There, show real `pending` and wait.
+
+```
+tap ─▶ update UI now ─▶ fire request ─┬─ ok:   keep, drop the "syncing" mark
+                                      └─ fail: roll back to prior value + show why
+```
+
+Rules:
+- Keep the pre-action value so you can roll back exactly.
+- Mark optimistic items as unconfirmed (subtle) until the server agrees, so a rollback isn't a jarring surprise.
+- On rollback, tell the user what reverted and why — a silent snap-back looks like a bug.
+
+## Debounce and throttle for async-triggering input
+
+Input that fires requests as the user types or drags must be rate-limited, or it floods the server and races itself.
+
+| Technique | Fires | Use for |
+| --- | --- | --- |
+| **Debounce** (wait for a pause) | Once, after input stops for N ms | Search-as-you-type (250–350ms), autosave (500ms–2s) |
+| **Throttle** (at most every N ms) | On a steady cadence | Drag/scroll-driven fetches, live position updates |
+| **Leading + trailing** | Immediately, then once more at the end | Feels responsive but still settles |
+
+Debounce is about *when to fire*; cancellation (next section) is about *what to do with requests already in flight*. You need both.
+
+## Cancellation and out-of-order responses
+
+Two requests fired in order can return out of order. Without cancellation, an older, slower response overwrites a newer one — the classic "I typed 서울, it shows 서" bug.
+
+- Cancel the previous in-flight request when a new one supersedes it (`AbortController` on the web).
+- Cancel in-flight requests when the component unmounts or the user navigates away.
+- If you cannot cancel, **guard on apply**: tag each request and ignore any response that isn't the latest.
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+  fetchResults(query, { signal: controller.signal })
+    .then(setResults)
+    .catch(ignoreAbort);
+  return () => controller.abort(); // supersede on new query / unmount
+}, [query]);
+```
+
+## Concurrency policy
+
+When the same action can be triggered while one is running, decide the policy on purpose:
+
+| Policy | Behavior | Use for |
+| --- | --- | --- |
+| **Block** | Ignore new triggers until the current resolves | Submits, payments (with double-submit guard) |
+| **Latest-wins** | Cancel the running one, keep only the newest | Search, filters, autosave |
+| **Queue** | Run in order, one at a time | Ordered writes that must all land |
+| **Parallel** | Let all run | Independent reads |
+
+Default to **block** for writes and **latest-wins** for reads unless you have a reason otherwise.
+
+## Timeouts and the stuck-spinner failure
+
+A spinner with no timeout is a trap: on a dropped connection it spins forever and the user is stuck.
+
+- Give every request a client timeout (e.g. 10–30s by operation).
+- On timeout, transition to `error` with a retry — hand off to [`patterns/error-states.md`](error-states.md) (network/server section, retry with backoff).
+- For genuinely long work (video processing, exports), don't hold a spinner — move to a **background job** pattern: acknowledge, let the user leave, notify on completion.
+
+## Perceived performance
+
+The felt speed of an async UI is mostly about what you show during the wait:
+
+- **Optimistic UI** — instant for reversible actions (above).
+- **Skeletons** — for content; show structure, not a void.
+- **Stale-while-revalidate** — show the last known data immediately, refresh in the background, swap in quietly. Mark it subtly as refreshing so a change isn't startling.
+- **Progressive reveal** — render what's ready (shell, then data) instead of blocking on the slowest piece.
+
+## Tokens consumed
+
+```
+--color-accent            (spinner, progress fill)
+--color-text-secondary    (pending label, "저장 중…")
+--color-text-tertiary     (unconfirmed / optimistic mark, "동기화 중")
+--color-bg-subtle         (skeleton base)
+--color-bg-elevated       (skeleton shimmer highlight)
+--radius-md
+--space-xs, --space-sm
+--duration-fast           (spinner delay-in / min-hold)
+--easing-standard
+```
+
+## Accessibility
+
+- Set `aria-busy="true"` on a control or region while its action is pending; clear it when resolved.
+- Announce state changes politely: a visually-hidden `role="status"` (`aria-live="polite"`) region saying "저장 중" then "저장됨". Do not use `assertive` for routine progress — reserve that for errors (see `error-states.md`).
+- Keep the control's accessible name stable and meaningful during pending — the label swap ("저장" → "저장 중…") is fine; an icon-only spinner with no name is not.
+- On success that removes the control (e.g. a submit that navigates), move focus deliberately to the next logical element; never drop focus to `<body>`.
+- Respect `prefers-reduced-motion`: swap spinners/shimmer for a static or fade indicator.
+- Disabled-while-pending must still be perceivable — don't rely on color alone; the busy affordance carries the meaning.
+
+## Korean considerations
+
+Per [`knowledge/i18n/korean-product-conventions.md`](../i18n/korean-product-conventions.md):
+- Progress labels use the present-progressive `~중…`: "저장 중…", "불러오는 중…", "처리 중…", "결제 처리 중…".
+- Keep pending labels short — Korean verbs + `중…` stay compact, so the button width rarely jumps.
+- For payment and transfer flows, show explicit real `pending` (never optimistic) and a clear "결제 처리 중…" state; cite [`knowledge/i18n/korean-payments.md`](../i18n/korean-payments.md) for the surrounding flow and failure messages.
+- Dense Korean B2B layouts favor in-place busy affordances (inline spinner, row-level skeleton) over full-page blocking overlays — cite [`knowledge/i18n/korean-product-conventions.md`](../i18n/korean-product-conventions.md) on density.
+
+## Don't
+
+- Don't leave a control clickable during its own async action — the double-submit bug.
+- Don't guard double-submit with the disabled attribute alone; guard the handler too.
+- Don't show a spinner for a sub-100ms wait — it reads as a flicker.
+- Don't show a spinner that can spin forever — every request has a timeout.
+- Don't blank a button to a bare spinner; keep a readable pending label.
+- Don't use optimistic updates for money, payments, or irreversible actions.
+- Don't let an older response overwrite a newer one — cancel or guard-on-apply.
+- Don't hold a full-screen spinner for long work — move it to a background job with notify.
+- Don't roll back an optimistic change silently — say what reverted and why.
+- Don't announce routine progress with `aria-live="assertive"` — that's for errors.
+
+## Cross-reference
+
+- [`knowledge/patterns/error-states.md`](error-states.md) — where the `error` state goes: recovery, retry-with-backoff, network/server messages
+- [`knowledge/patterns/form-design.md`](form-design.md) — submit buttons, validation-in-flight, form-level pending
+- [`knowledge/patterns/list-and-feed.md`](list-and-feed.md) — skeletons, pull-to-refresh, infinite scroll loading
+- [`knowledge/patterns/empty-states.md`](empty-states.md) — the resolved-but-no-data end state, distinct from loading
+- [`knowledge/patterns/money-and-amount.md`](money-and-amount.md) — why money actions use real pending + idempotency, never optimistic
+- [`knowledge/i18n/korean-payments.md`](../i18n/korean-payments.md) — payment in-flight and failure states

package/knowledge/patterns/error-states.md

@@ -312,6 +312,7 @@ function PageContent() {
 
 ## Cross-reference
 
+- [`knowledge/patterns/async-control.md`](async-control.md) — the in-flight state before the error: pending, retry-on-timeout, double-submit
 - [`knowledge/patterns/empty-states.md`](empty-states.md) — when there's no data, but it's not an error
 - [`knowledge/patterns/form-design.md`](form-design.md) — validation errors at the field level
 - [`knowledge/i18n/korean-payments.md`](../i18n/korean-payments.md) — payment-specific error messages

package/knowledge/patterns/form-design.md

@@ -232,6 +232,8 @@ Required affordances:
 
 ## Cross-reference
 
+- [`knowledge/patterns/async-control.md`](async-control.md) — submit-in-flight, double-submit prevention, pending button states
+
 - [knowledge/patterns/ux-guidelines.md](ux-guidelines.md) — broader UX rules
 - [knowledge/i18n/korean-product-conventions.md](../i18n/korean-product-conventions.md) — Korean form expectations (phone, address, terms)
 - [knowledge/a11y/keyboard-and-focus.md](../a11y/keyboard-and-focus.md) — keyboard navigation contract

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "@design-ai/cli",
-  "version": "4.57.0",
+  "version": "4.59.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": "./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,63 @@ 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
+# `@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.
+SDK_SMOKE_SCRIPT = """
+import { check, 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");
+
+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 +20296,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,
@@ -4785,7 +4785,7 @@ def assert_learning_query_human(raw: str, *, context: str, cmd: list[str]) -> No
         "Limit: 2",
         "Explain: selection score, matched tokens, and reason",
         "[accessibility] Prioritize keyboard accessibility details for Button component API specs",
-        "matched keyboard, accessibility",
+        "matched accessibility, keyboard",
         "reason brief-match",
     ):
         require_registry_smoke(
@@ -8378,7 +8378,7 @@ def run_self_test() -> None:
                 "",
                 "1. [accessibility] Prioritize keyboard accessibility details for Button component API specs",
                 "   learn-relevant · 2026-05-22T00:00:01.000Z",
-                "   score 4 · matched keyboard, accessibility · reason brief-match",
+                "   score 2.114533 · matched accessibility, keyboard · reason brief-match",
             ]),
             context="registry smoke self-test",
             cmd=learn_query_human_cmd,
@@ -8392,7 +8392,7 @@ def run_self_test() -> None:
                     "Limit: 2",
                     "Explain: selection score, matched tokens, and reason",
                     "[accessibility] Prioritize keyboard accessibility details for Button component API specs",
-                    "matched keyboard, accessibility",
+                    "matched accessibility, keyboard",
                 ]),
                 context="registry smoke self-test",
                 cmd=learn_query_human_cmd,

package/tools/audit/smoke_assertions.py

@@ -2246,6 +2246,7 @@ def passing_route_explain_human_output() -> str:
         f"   agent:   ✓ {EXPECTED_ROUTE_AGENT}",
         "   read:    ✓ knowledge/PRINCIPLES.md",
         f"   read:    ✓ {EXPECTED_ROUTE_KNOWLEDGE}",
+        "   related: knowledge/patterns/design-system-qa.md (score 10.13)",
         "",
     ])
 
@@ -3714,6 +3715,8 @@ def assert_route_explain_human_output(raw: str, *, context: str, cmd: list[str])
             f"agent:   ✓ {EXPECTED_ROUTE_AGENT}",
             "read:    ✓ knowledge/PRINCIPLES.md",
             f"read:    ✓ {EXPECTED_ROUTE_KNOWLEDGE}",
+            # Advisory related-knowledge recall is surfaced only under --explain.
+            "related: knowledge/",
         ),
         context=context,
         label="route explain human output",