@design-ai/cli 4.56.0 → 4.57.0

package/cli/commands/pack.mjs

@@ -14,12 +14,12 @@ import {
 import { writeOutputFile } from "../lib/output.mjs";
 
 function printHelp() {
-  console.log("Usage:  design-ai pack <brief> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N] [--json] [--out file] [--force]");
-  console.log("        design-ai pack --from-file brief.md [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N] [--json] [--out file] [--force]");
+  console.log("Usage:  design-ai pack <brief> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N] [--json] [--out file] [--force]");
+  console.log("        design-ai pack --from-file brief.md [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N] [--json] [--out file] [--force]");
   console.log("        design-ai pack --eval-template [--json] [--out file] [--force]");
   console.log("        design-ai pack --eval --from-file pack-eval.json [--strict] [--json] [--out file] [--force]");
   console.log("        cat pack-eval.json | design-ai pack --eval --stdin [--strict] [--json]");
-  console.log("        cat brief.md | design-ai pack --stdin [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--max-bytes N] [--json]\n");
+  console.log("        cat brief.md | design-ai pack --stdin [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--max-bytes N] [--json]\n");
   console.log("Generates a ready-to-use prompt plus bounded context file contents, summary, and warnings.");
   console.log("Pack eval is read-only and checks generated prompt-pack context contracts.\n");
   console.log("Options:");
@@ -29,6 +29,8 @@ function printHelp() {
   console.log("  --with-learning   Include brief-relevant local learning preferences and record local usage metadata");
   console.log("  --learning-category kind  Include only one learning category; requires --with-learning");
   console.log("  --learning-limit N        Limit included learning entries, 1-100; requires --with-learning");
+  console.log("  --with-recall     Include brief-relevant corpus knowledge files recalled from the shipped design corpus");
+  console.log("  --recall-limit N          Limit recalled corpus knowledge files, 1-20; requires --with-recall");
   console.log("  --max-bytes N     Maximum context bytes to include, 1000-1000000. Default: 120000");
   console.log("  --eval-template   Generate a runnable pack eval checkpoint JSON template");
   console.log("  --eval            Run deterministic prompt-pack checkpoint cases");
@@ -163,6 +165,8 @@ export async function runPack(args) {
     withLearning: parsed.withLearning,
     learningCategory: parsed.learningCategory,
     learningLimit: parsed.learningLimit,
+    withRecall: parsed.withRecall,
+    recallLimit: parsed.recallLimit,
   });
   const learningUsage = parsed.withLearning
     ? recordLearningUsage({

package/cli/commands/prompt.mjs

@@ -14,12 +14,12 @@ import {
 import { writeOutputFile } from "../lib/output.mjs";
 
 function printHelp() {
-  console.log("Usage:  design-ai prompt <brief> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--json] [--out file] [--force]");
-  console.log("        design-ai prompt --from-file brief.md [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--json] [--out file] [--force]");
+  console.log("Usage:  design-ai prompt <brief> [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--json] [--out file] [--force]");
+  console.log("        design-ai prompt --from-file brief.md [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--json] [--out file] [--force]");
   console.log("        design-ai prompt --eval-template [--json] [--out file] [--force]");
   console.log("        design-ai prompt --eval --from-file prompt-eval.json [--strict] [--json] [--out file] [--force]");
   console.log("        cat prompt-eval.json | design-ai prompt --eval --stdin [--strict] [--json]");
-  console.log("        cat brief.md | design-ai prompt --stdin [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--json]\n");
+  console.log("        cat brief.md | design-ai prompt --stdin [--route id] [--with-learning] [--learning-category kind] [--learning-limit N] [--with-recall] [--recall-limit N] [--json]\n");
   console.log("Builds a ready-to-use prompt from route recommendations and required design-ai files.");
   console.log("Prompt eval is read-only and checks generated prompt-plan contracts.\n");
   console.log("Options:");
@@ -29,6 +29,8 @@ function printHelp() {
   console.log("  --with-learning   Include brief-relevant local learning preferences and record local usage metadata");
   console.log("  --learning-category kind  Include only one learning category; requires --with-learning");
   console.log("  --learning-limit N        Limit included learning entries, 1-100; requires --with-learning");
+  console.log("  --with-recall     Include brief-relevant corpus knowledge files recalled from the shipped design corpus");
+  console.log("  --recall-limit N          Limit recalled corpus knowledge files, 1-20; requires --with-recall");
   console.log("  --eval-template   Generate a runnable prompt eval checkpoint JSON template");
   console.log("  --eval            Run deterministic prompt-plan checkpoint cases");
   console.log("  --strict          With --eval, exit non-zero on warning or failure");
@@ -161,6 +163,8 @@ export async function runPrompt(args) {
     withLearning: parsed.withLearning,
     learningCategory: parsed.learningCategory,
     learningLimit: parsed.learningLimit,
+    withRecall: parsed.withRecall,
+    recallLimit: parsed.recallLimit,
   });
   const learningUsage = parsed.withLearning
     ? recordLearningUsage({

package/cli/commands/search.mjs

@@ -2,18 +2,36 @@
 
 import { DESIGN_AI_HOME } from "../lib/paths.mjs";
 import { dim, header, info, warn } from "../lib/log.mjs";
+import { configuredEmbeddingProvider, defaultConfigFile } from "../lib/local-config.mjs";
+import { embeddingRerankSearch, rankedSearchCorpus } from "../lib/search-ranked.mjs";
 import { formatSearchJson, parseSearchArgs, searchCorpus } from "../lib/search.mjs";
 
 function printHelp() {
-  console.log("Usage:  design-ai search <query> [--limit N] [--dir kind] [--json]\n");
+  console.log("Usage:  design-ai search <query> [--limit N] [--dir kind] [--ranked] [--embeddings [--provider \"cmd args\"]] [--json]\n");
   console.log("Searches markdown files across knowledge, examples, skills, docs, agents, and commands.\n");
   console.log("Options:");
   console.log("  --limit N   Maximum hits to return, 1-500. Default: 20");
   console.log("  --dir kind  Restrict to one corpus directory. Repeatable.");
   console.log("              kind: knowledge, examples, skills, docs, agents, commands");
+  console.log("  --ranked    Rank results with the deterministic lexical (BM25-style) scorer");
+  console.log("  --embeddings          Rerank ranked results with the opt-in local embedding backend.");
+  console.log("                        Requires --ranked and a configured provider; falls back to the");
+  console.log("                        lexical ranking (with a notice) if no provider or sidecar is available");
+  console.log("  --provider \"cmd args\" Embedding provider command for this invocation (overrides config)");
   console.log("  --json      Emit machine-readable results");
 }
 
+function parseProviderFlag(value) {
+  const parts = String(value || "").trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return null;
+  return { command: parts[0], args: parts.slice(1) };
+}
+
+function resolveProvider({ flagProvider, configFile }) {
+  if (flagProvider) return parseProviderFlag(flagProvider);
+  return configuredEmbeddingProvider(configFile);
+}
+
 function printHits(hits) {
   for (const hit of hits) {
     console.log(`${hit.relPath}:${hit.lineNumber}`);
@@ -21,6 +39,12 @@ function printHits(hits) {
   }
 }
 
+function printRankedHits(query, hits, backend) {
+  header("design-ai search", `${query} (ranked, ${backend})`);
+  info(`Source: ${DESIGN_AI_HOME}`);
+  info(`Hits: ${hits.length}`);
+}
+
 export async function runSearch(args) {
   const parsed = parseSearchArgs(args);
   if (parsed.help) {
@@ -28,12 +52,81 @@ export async function runSearch(args) {
     return;
   }
 
+  if (parsed.embeddings && !parsed.ranked) {
+    throw new Error("--embeddings requires --ranked");
+  }
+
   if (!parsed.query) {
     printHelp();
     process.exitCode = 1;
     return;
   }
 
+  if (parsed.ranked) {
+    let backend = "lexical";
+    let notice = "";
+    let hits;
+
+    if (parsed.embeddings) {
+      const provider = resolveProvider({ flagProvider: parsed.provider, configFile: defaultConfigFile() });
+      const reranked = embeddingRerankSearch({
+        query: parsed.query,
+        provider,
+        designAiPath: DESIGN_AI_HOME,
+        dirs: parsed.dirs,
+        limit: parsed.limit,
+      });
+      if (reranked.fallback) {
+        notice = `embeddings unavailable, using lexical ranking: ${reranked.notice}`;
+        const lexical = rankedSearchCorpus({
+          query: parsed.query,
+          designAiPath: DESIGN_AI_HOME,
+          dirs: parsed.dirs,
+          limit: parsed.limit,
+        });
+        hits = lexical.hits;
+      } else {
+        backend = "embeddings";
+        hits = reranked.hits;
+      }
+    } else {
+      const lexical = rankedSearchCorpus({
+        query: parsed.query,
+        designAiPath: DESIGN_AI_HOME,
+        dirs: parsed.dirs,
+        limit: parsed.limit,
+      });
+      hits = lexical.hits;
+      notice = lexical.notice;
+    }
+
+    if (parsed.json) {
+      const payload = { query: parsed.query, ranked: true, notice, hits };
+      if (parsed.embeddings) payload.backend = backend;
+      console.log(formatSearchJson(payload));
+      return;
+    }
+
+    if (parsed.embeddings) {
+      printRankedHits(parsed.query, hits, backend);
+    } else {
+      header("design-ai search", `${parsed.query} (ranked)`);
+      info(`Source: ${DESIGN_AI_HOME}`);
+      info(`Hits: ${hits.length}`);
+    }
+    if (notice) info(notice);
+    console.log();
+    if (hits.length === 0) {
+      warn("No matches found.");
+      return;
+    }
+    for (const hit of hits) {
+      console.log(`${hit.relPath}  (score ${hit.score}, matched: ${hit.matchedTokens.join(", ")})`);
+      console.log(`  ${dim(hit.preview)}`);
+    }
+    return;
+  }
+
   const hits = searchCorpus({
     query: parsed.query,
     designAiPath: DESIGN_AI_HOME,

package/cli/lib/dispatch.mjs

@@ -20,6 +20,7 @@ import { runPrompt } from "../commands/prompt.mjs";
 import { runPack } from "../commands/pack.mjs";
 import { runVersion } from "../commands/version.mjs";
 import { runHelp } from "../commands/help.mjs";
+import { runIndex } from "../commands/index.mjs";
 import { hasHelpFlag } from "./help-flags.mjs";
 import { suggestNearest } from "./suggest.mjs";
 
@@ -52,6 +53,7 @@ const commands = {
   mcp: runMcp,
   search: runSearch,
   find: runSearch,
+  index: runIndex,
   show: runShow,
   cat: runShow,
   route: runRoute,
@@ -75,6 +77,7 @@ export const CANONICAL_COMMANDS = [
   "status",
   "list",
   "search",
+  "index",
   "show",
   "route",
   "routes",

package/cli/lib/embedding-index.mjs

@@ -0,0 +1,199 @@
+// Local embedding sidecar for Phase B (docs/AI-LEARNING-PHASE2.md).
+//
+// Sits next to the Phase A retrieval index under the same index directory. Never a
+// source of truth on its own: it records the same corpus/learning source identity as
+// the Phase A index (reusing retrieval-index.mjs helpers) so staleness/identity rules
+// stay identical (FU-2). Building requires a working provider (cli/lib/embedding-provider.mjs);
+// there is no network call anywhere in this module.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { embedDocuments } from "./embedding-provider.mjs";
+import { PACKAGE_ROOT } from "./paths.mjs";
+import {
+  collectCorpusDocuments,
+  computeCorpusDigest,
+  computeLearningDigest,
+  defaultIndexDir,
+  learningEntryDocuments,
+} from "./retrieval-index.mjs";
+import { auditLearningProfile, loadLearningProfile } from "./learn-profile.mjs";
+import { defaultLearningFile } from "./learn-shared.mjs";
+import { DEFAULT_SEARCH_DIRS } from "./search.mjs";
+
+export const EMBEDDING_INDEX_VERSION = 1;
+
+// Learning ids are prefixed in the embedding sidecar ONLY, so they can never collide
+// with corpus document ids (corpus ids are relative file paths and never contain ":").
+export const LEARNING_ID_PREFIX = "learning:";
+
+export function embeddingIndexFile(indexDir = defaultIndexDir()) {
+  return path.join(indexDir, "embedding-index.json");
+}
+
+function roundVector(vector) {
+  return vector.map((n) => Number(n.toFixed(6)));
+}
+
+// Builds the embedding sidecar by embedding both the corpus documents and the
+// learning entry documents (learning ids prefixed with "learning:" here only —
+// the Phase A learning index and learning.json itself are untouched).
+export function buildEmbeddingIndex({
+  provider,
+  designAiPath = PACKAGE_ROOT,
+  dirs = DEFAULT_SEARCH_DIRS,
+  learningFile = defaultLearningFile(),
+  now = new Date(),
+  spawnRunner,
+} = {}) {
+  if (!provider || typeof provider.command !== "string" || provider.command.trim() === "") {
+    return { ok: false, error: "no embedding provider configured (pass --provider or set embeddings.provider in ~/.design-ai/config.json)" };
+  }
+
+  const corpusDocuments = collectCorpusDocuments({ designAiPath, dirs });
+  const profile = loadLearningProfile(learningFile);
+  const learningDocuments = learningEntryDocuments(profile).map((doc) => ({
+    id: `${LEARNING_ID_PREFIX}${doc.id}`,
+    text: doc.text,
+  }));
+
+  const allDocuments = [...corpusDocuments, ...learningDocuments].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  const embedArgs = { provider, documents: allDocuments };
+  if (spawnRunner) embedArgs.spawnRunner = spawnRunner;
+  const embedded = embedDocuments(embedArgs);
+  if (!embedded.ok) return { ok: false, error: embedded.error };
+
+  const vectors = allDocuments
+    .map((doc) => ({ id: doc.id, v: roundVector(embedded.vectorsById.get(doc.id)) }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  const { digest: learningDigest } = computeLearningDigest(learningFile);
+  const audit = auditLearningProfile({ filePath: learningFile });
+
+  const payload = {
+    version: EMBEDDING_INDEX_VERSION,
+    kind: "embedding-index",
+    generatedAt: now.toISOString(),
+    provider: {
+      command: provider.command,
+      args: Array.isArray(provider.args) ? [...provider.args] : [],
+      modelLabel: provider.modelLabel || "",
+      dimensions: embedded.dimensions,
+    },
+    source: {
+      designAiPath: path.resolve(designAiPath),
+      corpusDirs: [...dirs],
+      corpusDigest: computeCorpusDigest(corpusDocuments),
+      learningFile: path.resolve(learningFile),
+      learningDigest,
+      auditStatus: audit.status || "unknown",
+    },
+    vectors,
+  };
+
+  return { ok: true, payload };
+}
+
+export function writeEmbeddingIndex({ indexDir = defaultIndexDir(), payload }) {
+  mkdirSync(indexDir, { recursive: true });
+  const file = embeddingIndexFile(indexDir);
+  writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  return { file };
+}
+
+// Mirrors loadIndexFile's validation shape/version contract from retrieval-index.mjs.
+export function loadEmbeddingIndexFile(file) {
+  if (!existsSync(file)) return { present: false, payload: null, error: "" };
+  try {
+    const payload = JSON.parse(readFileSync(file, "utf8"));
+    if (!payload || typeof payload !== "object" || payload.version !== EMBEDDING_INDEX_VERSION || payload.kind !== "embedding-index") {
+      return { present: true, payload: null, error: "unsupported embedding index payload shape or version" };
+    }
+    return { present: true, payload, error: "" };
+  } catch (error) {
+    return { present: true, payload: null, error: `unreadable embedding index file: ${error.message}` };
+  }
+}
+
+// Status mirrors retrieval-index.mjs's statusEntry rules: fresh requires both digests
+// to match AND both source identities (designAiPath, learningFile) to match — a
+// different checkout or a different learning file is "not my index" (same FU-2 rule).
+export function embeddingIndexStatus({
+  designAiPath = PACKAGE_ROOT,
+  dirs = DEFAULT_SEARCH_DIRS,
+  indexDir = defaultIndexDir(),
+  learningFile = defaultLearningFile(),
+} = {}) {
+  const file = embeddingIndexFile(indexDir);
+  const loaded = loadEmbeddingIndexFile(file);
+
+  if (!loaded.present) {
+    return {
+      file,
+      present: false,
+      fresh: false,
+      sourceMatch: false,
+      generatedAt: "",
+      documentCount: 0,
+      provider: null,
+      storedDigest: "",
+      currentDigest: "",
+      error: "",
+    };
+  }
+
+  const currentCorpusDigest = computeCorpusDigest(collectCorpusDocuments({ designAiPath, dirs }));
+  const currentLearningDigest = computeLearningDigest(learningFile).digest;
+
+  if (loaded.error) {
+    return {
+      file,
+      present: true,
+      fresh: false,
+      sourceMatch: false,
+      generatedAt: "",
+      documentCount: 0,
+      provider: null,
+      storedDigest: "",
+      currentDigest: currentCorpusDigest,
+      error: loaded.error,
+    };
+  }
+
+  const storedSource = loaded.payload.source || {};
+  const storedCorpusDigest = storedSource.corpusDigest || "";
+  const storedLearningDigest = storedSource.learningDigest || "";
+  const sourceMatch =
+    storedSource.designAiPath === path.resolve(designAiPath) &&
+    storedSource.learningFile === path.resolve(learningFile);
+  const digestMatch = storedCorpusDigest === currentCorpusDigest && storedLearningDigest === currentLearningDigest;
+  const fresh = sourceMatch && digestMatch;
+
+  const provider = loaded.payload.provider || null;
+
+  return {
+    file,
+    present: true,
+    fresh,
+    sourceMatch,
+    generatedAt: loaded.payload.generatedAt || "",
+    documentCount: Array.isArray(loaded.payload.vectors) ? loaded.payload.vectors.length : 0,
+    provider: provider ? { command: provider.command, modelLabel: provider.modelLabel || "", dimensions: provider.dimensions } : null,
+    // storedDigest/currentDigest track the corpus digest, matching the Phase A status
+    // entry shape; learning drift is folded into `fresh`/`sourceMatch` above since the
+    // embedding sidecar has two source digests (corpus + learning) but one file.
+    storedDigest: storedCorpusDigest,
+    currentDigest: currentCorpusDigest,
+    error: "",
+  };
+}
+
+export function vectorsById(payload) {
+  const map = new Map();
+  for (const entry of payload?.vectors || []) {
+    map.set(entry.id, entry.v);
+  }
+  return map;
+}

package/cli/lib/embedding-provider.mjs

@@ -0,0 +1,121 @@
+// Local embedding provider protocol for Phase B (docs/AI-LEARNING-PHASE2.md).
+//
+// Protocol: design-ai spawns the user-configured provider command as a local child
+// process (spawnSync, no shell — args are passed as an argv array, never interpolated
+// into a shell string). design-ai writes JSON Lines to the provider's stdin: one line
+// per input document, `{"id": string, "text": string}`, in sorted-id order. design-ai
+// reads JSON Lines from the provider's stdout: one line per input, `{"id": string,
+// "vector": number[]}`, in ANY order — outputs are matched back to inputs by id, not
+// position. The provider is expected to emit exactly one output line per input id.
+//
+// Failure handling: a non-zero exit code, unparseable stdout, a missing id, or vectors
+// with an empty or inconsistent dimension across the batch all collapse to a single
+// descriptive failure — `embedDocuments` never throws to its caller; it always returns
+// `{ ok: false, error }` so callers (index build, ranked search) can fall back to the
+// deterministic lexical path. No network access is made by this module; the provider
+// is a local executable chosen by the user, invoked exactly as configured.
+
+import { spawnSync } from "node:child_process";
+
+function toJsonLines(documents) {
+  return documents
+    .map((doc) => `${JSON.stringify({ id: doc.id, text: doc.text })}\n`)
+    .join("");
+}
+
+function parseOutputLines(stdout) {
+  const vectors = new Map();
+  const lines = stdout.split("\n").filter((line) => line.trim() !== "");
+  for (const line of lines) {
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (error) {
+      return { error: `provider emitted unparseable output line: ${error.message}` };
+    }
+    if (!parsed || typeof parsed !== "object" || typeof parsed.id !== "string") {
+      return { error: "provider output line is missing a string id" };
+    }
+    if (!Array.isArray(parsed.vector) || !parsed.vector.every((n) => typeof n === "number" && Number.isFinite(n))) {
+      return { error: `provider output for id "${parsed.id}" is missing a numeric vector` };
+    }
+    vectors.set(parsed.id, parsed.vector);
+  }
+  return { vectors };
+}
+
+// Default runner: spawns the provider as a local process only (no shell). Injectable
+// for tests, matching the mcp-server.mjs pattern of a default-parameter runner swap.
+function defaultSpawnRunner({ command, args, input }) {
+  const result = spawnSync(command, args, {
+    input,
+    encoding: "utf8",
+    shell: false,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    error: result.error || null,
+  };
+}
+
+// documents: [{ id, text }]. provider: { command, args }.
+// Returns { ok: true, vectorsById: Map<id, number[]>, dimensions } or { ok: false, error }.
+export function embedDocuments({ provider, documents, spawnRunner = defaultSpawnRunner }) {
+  if (!provider || typeof provider.command !== "string" || provider.command.trim() === "") {
+    return { ok: false, error: "no embedding provider command configured" };
+  }
+  const args = Array.isArray(provider.args) ? provider.args : [];
+  const sortedDocs = [...documents].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  if (sortedDocs.length === 0) {
+    return { ok: true, vectorsById: new Map(), dimensions: 0 };
+  }
+
+  let result;
+  try {
+    result = spawnRunner({ command: provider.command, args, input: toJsonLines(sortedDocs) });
+  } catch (error) {
+    return { ok: false, error: `failed to spawn embedding provider "${provider.command}": ${error.message}` };
+  }
+
+  if (result.error) {
+    return { ok: false, error: `failed to spawn embedding provider "${provider.command}": ${result.error.message}` };
+  }
+  if (result.status !== 0) {
+    const detail = (result.stderr || "").trim();
+    return {
+      ok: false,
+      error: `embedding provider "${provider.command}" exited with code ${result.status}${detail ? `: ${detail}` : ""}`,
+    };
+  }
+
+  const parsed = parseOutputLines(result.stdout);
+  if (parsed.error) return { ok: false, error: parsed.error };
+
+  const missing = sortedDocs.filter((doc) => !parsed.vectors.has(doc.id)).map((doc) => doc.id);
+  if (missing.length > 0) {
+    return { ok: false, error: `embedding provider did not return vectors for id(s): ${missing.slice(0, 5).join(", ")}` };
+  }
+
+  let dimensions = 0;
+  for (const doc of sortedDocs) {
+    const vector = parsed.vectors.get(doc.id);
+    if (vector.length === 0) {
+      return { ok: false, error: `embedding provider returned an empty vector for id "${doc.id}"` };
+    }
+    if (dimensions === 0) {
+      dimensions = vector.length;
+    } else if (vector.length !== dimensions) {
+      return {
+        ok: false,
+        error: `embedding provider returned inconsistent vector dimensions (expected ${dimensions}, got ${vector.length} for id "${doc.id}")`,
+      };
+    }
+  }
+
+  const vectorsById = new Map(sortedDocs.map((doc) => [doc.id, parsed.vectors.get(doc.id)]));
+  return { ok: true, vectorsById, dimensions };
+}

package/cli/lib/embedding-rerank.mjs

@@ -0,0 +1,52 @@
+// Deterministic cosine-similarity rerank for Phase B (docs/AI-LEARNING-PHASE2.md).
+//
+// design-ai's side of Phase B stays fully deterministic: candidate generation is the
+// existing Phase A lexical ranking, and this module only computes cosine similarity
+// against provider-supplied vectors and sorts with a fixed tie-break rule. Vector
+// values depend on the user's provider, but everything design-ai does with them here
+// is pure and order-stable.
+
+function dotProduct(a, b) {
+  let sum = 0;
+  for (let i = 0; i < a.length; i += 1) sum += a[i] * b[i];
+  return sum;
+}
+
+function magnitude(vector) {
+  return Math.sqrt(dotProduct(vector, vector));
+}
+
+export function cosineSimilarity(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || a.length === 0) return 0;
+  const magA = magnitude(a);
+  const magB = magnitude(b);
+  if (magA === 0 || magB === 0) return 0;
+  return dotProduct(a, b) / (magA * magB);
+}
+
+// candidates: [{ id, ... }] in Phase A lexical order (used as the tie-break/placement
+// order for anything without a vector). vectorsById: Map<id, number[]>. queryVector:
+// number[]. Candidates missing a vector are NOT scored — they keep their lexical
+// order and are placed AFTER every scored (embedded) candidate, deterministically.
+export function cosineRerank({ queryVector, candidates, vectorsById, limit }) {
+  const scored = [];
+  const unscored = [];
+
+  for (const candidate of candidates) {
+    const vector = vectorsById.get(candidate.id);
+    if (!vector) {
+      unscored.push(candidate);
+      continue;
+    }
+    const score = cosineSimilarity(queryVector, vector);
+    scored.push({ ...candidate, score: Number(score.toFixed(6)) });
+  }
+
+  scored.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  });
+
+  const ordered = [...scored, ...unscored];
+  return Number.isInteger(limit) ? ordered.slice(0, limit) : ordered;
+}