@design-ai/cli 4.59.0 → 4.61.0

package/cli/sdk/index.d.ts

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

package/cli/sdk/index.mjs

@@ -1,19 +1,27 @@
-// design-ai Agent SDK — Phase A (read-only). See docs/AGENT-SDK.md and docs/SDK.md.
+// design-ai Agent SDK — Phase A (read-only) + Phase B (local writes). See
+// docs/AGENT-SDK.md and docs/SDK.md.
 //
 // A curated, semver-stable adapter over the same cli/lib functions the CLI and
 // MCP server call. Each verb validates its inputs, resolves the package root
 // the same way the CLI does, and returns a plain JSON-serializable object —
 // the same shape the CLI's --json mode emits. No network calls, no runtime
-// dependencies. Phase A performs no file writes: no learning-usage sidecar
-// writes, even from prompt/pack's withLearning option.
+// dependencies. The 8 Phase A verbs below perform no file writes: no
+// learning-usage sidecar writes, even from prompt/pack's withLearning option.
+//
+// Phase B adds a single `learn` namespace grouping the three explicit,
+// opt-in LOCAL-WRITE verbs (`learn.remember`, `learn.feedback`,
+// `learn.captureFromCheck`). This keeps the write boundary explicit: the 8
+// Phase A verbs stay read-only and unchanged; `learn` is the only place the
+// SDK writes files, and it only ever writes the local learning profile.
 //
 // Import path: `@design-ai/cli/sdk` (see the "exports" map in package.json).
 // `cli/lib/*` stays internal and unstable; this barrel is the only supported
 // public surface. Do not import `cli/lib/*.mjs` directly from outside this
-// package — only the 8 named exports below are covered by the semver
-// stability contract described in docs/SDK.md.
+// package — only the 8 named function exports plus the `learn` namespace
+// below are covered by the semver stability contract described in docs/SDK.md.
 
 export { check } from "./check-adapter.mjs";
+export { learn } from "./learn-adapter.mjs";
 export { pack } from "./pack-adapter.mjs";
 export { prompt } from "./prompt-adapter.mjs";
 export { recall } from "./recall-adapter.mjs";

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/docs/AGENT-SDK.md

@@ -75,9 +75,9 @@ Verification gates:
 - `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 — optional, explicit local writes
+### Phase B — explicit local writes (shipped)
 
-Only if demand appears: opt-in adapters that mirror the CLI's local-write commands (`learn.remember`, `learn.feedback`, `check` with capture), each requiring an explicit option and writing only the local learning profile, never the network. Deferred until an adopter needs it; Phase A is read-only.
+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
 

package/docs/AI-LEARNING-PHASE2.md

@@ -202,8 +202,8 @@ This review answers the five open questions against the shipped Phase A implemen
 
 - **FU-1 (Q4, before Phase B):** Add Hangul-aware tokenization (CJK bigramming or particle stripping) in `cli/lib/lexical.mjs` behind Korean `learn --eval` checkpoints; regression-test that `버튼`, `버튼을`, `버튼이` converge on the same button docs. _Done (2026-07-03): Hangul runs >= 2 chars now emit overlapping character bigrams alongside the surface form; the review's zero-hit queries recover (`버튼` 0 → 3 ranked hits, `접근성이` 0 → 3), with unit regression coverage in `lexical.test.mjs`._
 - **FU-2 (Q2, before Phase B index-as-source-of-truth):** Key the corpus index by corpus digest / record `designAiPath` in the payload so multiple checkouts do not overwrite each other once the index is read for content rather than staleness. _Done (2026-07-03): sidecar format bumped to version 2 (auto-invalidating v1 files); the corpus payload records resolved `designAiPath` and the learning payload the resolved `learningFile`, and `index --status` reports `sourceMatch` and treats identity mismatch as not fresh._
-- **FU-3 (Q1, gates default promotion):** Land a ranked-search eval checkpoint so any future `--ranked` default promotion is evidence-backed and announced.
-- **FU-4 (Q5, Phase B):** Specify and implement `~/.design-ai/config.json` as the Phase B provider config home with per-invocation `--embeddings` still required.
+- **FU-3 (Q1, gates default promotion):** Land a ranked-search eval checkpoint so any future `--ranked` default promotion is evidence-backed and announced. _Done (2026-07-05): `design-ai search --eval-template`/`--eval [--strict]` landed in `cli/lib/search-eval.mjs` and `cli/commands/search.mjs`, mirroring the route/prompt/pack/learn eval-checkpoint pattern; cases run through `rankedSearchCorpus` (the shipped ranked path), and the default template includes the three Korean particle-form regression cases from FU-1 (버튼/버튼을/접근성이) plus English cases, doubling as a retrieval-level Hangul-bigram regression check._
+- **FU-4 (Q5, Phase B):** Specify and implement `~/.design-ai/config.json` as the Phase B provider config home with per-invocation `--embeddings` still required. _Done (2026-07-03, Phase B): `cli/lib/local-config.mjs` reads `~/.design-ai/config.json` (or `DESIGN_AI_CONFIG_FILE`); the config only supplies the provider — every invocation still requires the explicit `--embeddings` flag to arm it._
 
 ### Phase B gate: cleared-with-conditions
 

package/docs/NEXT-SURFACE-DECISION.md

@@ -118,8 +118,17 @@ Cross-check any surface work against the release gate: `npm run audit` (8/8, lin
 
 ## Decision record
 
-- **Status:** proposed — awaiting maintainer sign-off
-- **Date:** 2026-07-03
+- **Status:** accepted and executed — both recommended surfaces shipped
+- **Date:** 2026-07-03 (proposed) / 2026-07-05 (executed)
 - **Deciders:** maintainer
 - **Supersedes:** none
 - **Related:** [`PRODUCT-READINESS.md`](PRODUCT-READINESS.md), [`external-status.md`](external-status.md), `AI-LEARNING-PHASE2.md`
+
+### Outcome (2026-07-05)
+
+The recommendation was executed in order and both surfaces are live:
+
+- **CLI deepening** shipped as v4.57.0 (local retrieval memory: `index`, `search --ranked`, `--with-recall`, `learn --recall`, opt-in embedding rerank) and v4.58.0 (`route --explain` related knowledge, recall quality, corpus depth). The dogfood friction this document identified — missing corpus and missing flags — is retired; retrieval spans every CLI/MCP surface.
+- **Agent SDK** followed exactly on the stated revisit trigger (recall interface stable across two releases): design doc [`AGENT-SDK.md`](AGENT-SDK.md), then v4.59.0 (Phase A — read-only `@design-ai/cli/sdk`, 8 verbs) and v4.60.0 (TypeScript declarations + the opt-in `learn.*` local-write namespace).
+
+The deferred surfaces (VS Code deepening, Web UI, Figma plugin) remain deferred with the same revisit triggers. The next-surface question is open again; re-evaluate against the criteria above when the next planning window opens, factoring in that the SDK now also serves programmatic adopters.