codetrap 0.1.7 → 0.1.9

package/src/lib/codex-setup.ts

@@ -0,0 +1,247 @@
+import {
+  appendFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findProjectRoot } from "./scope";
+import agentsTemplateAsset from "../../plugins/codetrap-agent/templates/AGENTS.codetrap.md" with { type: "text" };
+import codetrapAddSkill from "../../plugins/codetrap-agent/skills/codetrap-add/SKILL.md" with { type: "text" };
+import codetrapCaptureSkill from "../../plugins/codetrap-agent/skills/codetrap-capture/SKILL.md" with { type: "text" };
+import codetrapCaptureExternalSkill from "../../plugins/codetrap-agent/skills/codetrap-capture-external/SKILL.md" with { type: "text" };
+import codetrapCheckSkill from "../../plugins/codetrap-agent/skills/codetrap-check/SKILL.md" with { type: "text" };
+import codetrapSearchSkill from "../../plugins/codetrap-agent/skills/codetrap-search/SKILL.md" with { type: "text" };
+
+export type CodexSetupOptions = {
+  cwd: string;
+  codexHome?: string;
+  agentsFile?: string;
+  installMcp?: boolean;
+  skipAgents?: boolean;
+  dryRun?: boolean;
+};
+
+export type CodexSetupStatus =
+  | "already_present"
+  | "created"
+  | "appended"
+  | "installed"
+  | "updated"
+  | "unchanged"
+  | "skipped"
+  | "would_create"
+  | "would_append"
+  | "would_install"
+  | "would_update"
+  | "would_run"
+  | "failed";
+
+export type CodexSetupResult = {
+  success: boolean;
+  project_root: string;
+  codex_home: string;
+  plugin_root: string;
+  dry_run: boolean;
+  project: {
+    codetrap_dir: string;
+    status: CodexSetupStatus;
+  };
+  skills: Array<{
+    name: string;
+    source: string;
+    destination: string;
+    status: CodexSetupStatus;
+  }>;
+  agents: {
+    path: string | null;
+    status: CodexSetupStatus;
+  };
+  mcp: {
+    requested: boolean;
+    command: string;
+    status: CodexSetupStatus;
+    exit_code?: number | null;
+    error?: string;
+  };
+};
+
+const AGENTS_TEMPLATE_PATH = "templates/AGENTS.codetrap.md";
+const CODEX_MARKER = "codetrap search \"<keywords>\" --mode hybrid --json";
+const MCP_COMMAND = ["codex", "mcp", "add", "codetrap", "--", "codetrap", "serve"];
+const EMBEDDED_PLUGIN_ROOT = "embedded://plugins/codetrap-agent";
+const EMBEDDED_SKILLS = [
+  { name: "codetrap-add", skill: codetrapAddSkill },
+  { name: "codetrap-capture", skill: codetrapCaptureSkill },
+  { name: "codetrap-capture-external", skill: codetrapCaptureExternalSkill },
+  { name: "codetrap-check", skill: codetrapCheckSkill },
+  { name: "codetrap-search", skill: codetrapSearchSkill },
+];
+
+export function runCodexSetup(options: CodexSetupOptions): CodexSetupResult {
+  const cwd = resolve(options.cwd);
+  const projectRoot = findProjectRoot(cwd) ?? cwd;
+  const codexHome = resolveCodexHome(options.codexHome);
+  const pluginRoot = bundledPluginRoot();
+  const useEmbeddedAssets = !existsSync(pluginRoot);
+
+  const dryRun = options.dryRun === true;
+  const project = ensureProjectCodetrap(projectRoot, dryRun);
+  const skills = useEmbeddedAssets
+    ? installEmbeddedSkills(codexHome, dryRun)
+    : installSkills(pluginRoot, codexHome, dryRun);
+  const agents = options.skipAgents
+    ? { path: null, status: "skipped" as const }
+    : installAgentsTemplate(projectRoot, useEmbeddedAssets ? null : pluginRoot, options.agentsFile ?? "AGENTS.md", dryRun);
+  const mcp = setupMcp(options.installMcp === true, dryRun);
+  const success = mcp.status !== "failed";
+
+  return {
+    success,
+    project_root: projectRoot,
+    codex_home: codexHome,
+    plugin_root: useEmbeddedAssets ? EMBEDDED_PLUGIN_ROOT : pluginRoot,
+    dry_run: dryRun,
+    project,
+    skills,
+    agents,
+    mcp,
+  };
+}
+
+export function formatCodexSetupText(result: CodexSetupResult): string {
+  const installed = result.skills.filter((skill) =>
+    ["installed", "updated", "would_install", "would_update"].includes(skill.status)
+  ).length;
+  const unchanged = result.skills.filter((skill) => skill.status === "unchanged").length;
+  const lines = [
+    result.success ? "Codex setup complete." : "Codex setup completed with errors.",
+    `Project: ${result.project.status} (${result.project.codetrap_dir})`,
+    `Skills: ${installed} changed, ${unchanged} unchanged (${join(result.codex_home, "skills")})`,
+    `AGENTS: ${result.agents.status}${result.agents.path ? ` (${result.agents.path})` : ""}`,
+  ];
+  if (result.mcp.requested) {
+    lines.push(`MCP: ${result.mcp.status} (${result.mcp.command})`);
+    if (result.mcp.error) lines.push(`MCP error: ${result.mcp.error}`);
+  } else {
+    lines.push(`MCP: skipped; pass --mcp to run '${result.mcp.command}'.`);
+  }
+  if (result.dry_run) lines.unshift("Dry run; no files or Codex config were changed.");
+  return lines.join("\n");
+}
+
+function ensureProjectCodetrap(projectRoot: string, dryRun: boolean): CodexSetupResult["project"] {
+  const codetrapDir = join(projectRoot, ".codetrap");
+  if (existsSync(codetrapDir)) {
+    return { codetrap_dir: codetrapDir, status: "already_present" };
+  }
+  if (!dryRun) mkdirSync(codetrapDir, { recursive: true });
+  return { codetrap_dir: codetrapDir, status: dryRun ? "would_create" : "created" };
+}
+
+function installSkills(pluginRoot: string, codexHome: string, dryRun: boolean): CodexSetupResult["skills"] {
+  const sourceSkillsDir = join(pluginRoot, "skills");
+  const targetSkillsDir = join(codexHome, "skills");
+  if (!dryRun) mkdirSync(targetSkillsDir, { recursive: true });
+
+  return readdirSync(sourceSkillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((entry) => {
+      const source = join(sourceSkillsDir, entry.name);
+      const destination = join(targetSkillsDir, entry.name);
+      const sourceSkill = readFileSync(join(source, "SKILL.md"), "utf-8");
+      const destinationSkillPath = join(destination, "SKILL.md");
+      const exists = existsSync(destinationSkillPath);
+      const unchanged = exists && readFileSync(destinationSkillPath, "utf-8") === sourceSkill;
+      let status: CodexSetupStatus = unchanged ? "unchanged" : exists ? "updated" : "installed";
+      if (dryRun && status === "installed") status = "would_install";
+      if (dryRun && status === "updated") status = "would_update";
+      if (!dryRun && !unchanged) cpSync(source, destination, { recursive: true, force: true });
+      return { name: entry.name, source, destination, status };
+    });
+}
+
+function installEmbeddedSkills(codexHome: string, dryRun: boolean): CodexSetupResult["skills"] {
+  const targetSkillsDir = join(codexHome, "skills");
+  if (!dryRun) mkdirSync(targetSkillsDir, { recursive: true });
+
+  return EMBEDDED_SKILLS.map((entry) => {
+    const destination = join(targetSkillsDir, entry.name);
+    const destinationSkillPath = join(destination, "SKILL.md");
+    const exists = existsSync(destinationSkillPath);
+    const unchanged = exists && readFileSync(destinationSkillPath, "utf-8") === entry.skill;
+    let status: CodexSetupStatus = unchanged ? "unchanged" : exists ? "updated" : "installed";
+    if (dryRun && status === "installed") status = "would_install";
+    if (dryRun && status === "updated") status = "would_update";
+    if (!dryRun && !unchanged) {
+      mkdirSync(destination, { recursive: true });
+      writeFileSync(destinationSkillPath, entry.skill);
+    }
+    return {
+      name: entry.name,
+      source: `${EMBEDDED_PLUGIN_ROOT}/skills/${entry.name}`,
+      destination,
+      status,
+    };
+  });
+}
+
+function installAgentsTemplate(
+  projectRoot: string,
+  pluginRoot: string | null,
+  agentsFile: string,
+  dryRun: boolean
+): CodexSetupResult["agents"] {
+  const target = resolve(projectRoot, agentsFile);
+  const template = (pluginRoot
+    ? readFileSync(join(pluginRoot, AGENTS_TEMPLATE_PATH), "utf-8")
+    : agentsTemplateAsset
+  ).trimEnd();
+  if (existsSync(target)) {
+    const current = readFileSync(target, "utf-8");
+    if (current.includes(CODEX_MARKER)) {
+      return { path: target, status: "already_present" };
+    }
+    if (!dryRun) appendFileSync(target, `${current.endsWith("\n") ? "\n" : "\n\n"}${template}\n`);
+    return { path: target, status: dryRun ? "would_append" : "appended" };
+  }
+  if (!dryRun) writeFileSync(target, `${template}\n`);
+  return { path: target, status: dryRun ? "would_create" : "created" };
+}
+
+function setupMcp(requested: boolean, dryRun: boolean): CodexSetupResult["mcp"] {
+  const command = MCP_COMMAND.join(" ");
+  if (!requested) return { requested, command, status: "skipped" };
+  if (dryRun) return { requested, command, status: "would_run" };
+
+  const result = Bun.spawnSync({
+    cmd: MCP_COMMAND,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.success) return { requested, command, status: "installed", exit_code: result.exitCode };
+
+  const stderr = new TextDecoder().decode(result.stderr).trim();
+  const stdout = new TextDecoder().decode(result.stdout).trim();
+  return {
+    requested,
+    command,
+    status: "failed",
+    exit_code: result.exitCode,
+    error: stderr || stdout || "codex mcp add failed",
+  };
+}
+
+function resolveCodexHome(codexHome?: string): string {
+  return resolve(codexHome ?? process.env.CODEX_HOME ?? join(process.env.HOME ?? process.env.USERPROFILE ?? homedir(), ".codex"));
+}
+
+function bundledPluginRoot(): string {
+  return join(dirname(dirname(dirname(fileURLToPath(import.meta.url)))), "plugins", "codetrap-agent");
+}

package/src/lib/command-requests.ts

@@ -1,5 +1,12 @@
 import { SEARCH_MODES, type SearchMode } from "./constants";
-import type { SearchDefaults } from "./config";
+import type { EmbeddingProviderSetting, EmbeddingSettings, SearchDefaults } from "./config";
+import {
+  DEFAULT_OLLAMA_DIMENSIONS,
+  DEFAULT_OLLAMA_ENDPOINT,
+  DEFAULT_OLLAMA_MODEL,
+} from "./embedder";
+import { capturedTrapMarkdownInput } from "./session-capture";
+import { uniqueStrings as uniqueStringList } from "./string-list";
 import type { SearchTrapsArgs, ListTrapsArgs } from "./trap-operations";
 
 type RawArgs = Record<string, unknown>;
@@ -12,6 +19,10 @@ export type EmbedRequest = {
   batchSize?: number;
 };
 
+export type EmbeddingsUseRequest = {
+  embeddings: EmbeddingSettings;
+};
+
 export type StatsRequest = {
   scope?: string;
 };
@@ -40,6 +51,15 @@ export type SessionCloseRequest = {
   proposeTraps: boolean;
 };
 
+export type SessionCaptureRequest = {
+  trap: Record<string, unknown>;
+  goal?: string;
+  kind?: string;
+  relatedFiles?: string[];
+  sourceRef?: string;
+  evidenceNote?: string;
+};
+
 export type SessionIdRequest = {
   sessionId?: string;
 };
@@ -73,6 +93,12 @@ export type SessionNoteStdin = {
   read: () => string;
 };
 
+export type SessionCaptureInput = {
+  isTTY: boolean;
+  readStdin: () => string;
+  readFile: (path: string) => string;
+};
+
 export function searchRequestFromArgs(query: string, args: RawArgs, defaults: SearchDefaults): SearchTrapsArgs {
   return {
     query,
@@ -117,6 +143,27 @@ export function embedRequestFromArgs(args: RawArgs): EmbedRequest {
   };
 }
 
+export function embeddingsUseRequestFromArgs(
+  positionals: string[],
+  args: RawArgs
+): EmbeddingsUseRequest {
+  const provider = embeddingProviderOption(requiredPositional(positionals, 0, "provider"));
+  if (provider === "jina") {
+    return {
+      embeddings: { provider },
+    };
+  }
+
+  return {
+    embeddings: {
+      provider,
+      endpoint: stringOption(args, "endpoint") ?? DEFAULT_OLLAMA_ENDPOINT,
+      model: stringOption(args, "model") ?? DEFAULT_OLLAMA_MODEL,
+      dimensions: optionalIntOption(args, "dimensions") ?? DEFAULT_OLLAMA_DIMENSIONS,
+    },
+  };
+}
+
 export function evidenceRequestFromArgs(args: RawArgs): RawArgs {
   return {
     source_type: stringOption(args, "source_type", "source-type"),
@@ -175,6 +222,35 @@ export function sessionCloseRequestFromArgs(positionals: string[], args: RawArgs
   };
 }
 
+export function sessionCaptureRequestFromArgs(args: RawArgs, input?: SessionCaptureInput): SessionCaptureRequest {
+  const sources = [
+    args["trap-json"] !== undefined,
+    args["trap-markdown"] !== undefined,
+    args["trap-markdown-file"] !== undefined,
+  ].filter(Boolean).length;
+  if (sources === 0) throw new Error("--trap-json, --trap-markdown, or --trap-markdown-file is required.");
+  if (sources > 1) throw new Error("Choose only one of --trap-json, --trap-markdown, or --trap-markdown-file.");
+
+  const markdown = markdownCaptureInput(args, input);
+  const parsedMarkdown = markdown === undefined ? null : capturedTrapMarkdownInput(markdown);
+  const trap: Record<string, unknown> | undefined = parsedMarkdown
+    ? { ...parsedMarkdown.trap }
+    : jsonObjectOption(args, "trap-json");
+  if (!trap) throw new Error("--trap-json, --trap-markdown, or --trap-markdown-file is required.");
+
+  return {
+    trap,
+    goal: stringOption(args, "goal"),
+    kind: stringOption(args, "kind"),
+    relatedFiles: uniqueStrings([
+      ...(csvOrArrayOption(args, "related_files", "related-files") ?? []),
+      ...(parsedMarkdown?.relatedFiles ?? []),
+    ]),
+    sourceRef: stringOption(args, "source_ref", "source-ref"),
+    evidenceNote: parsedMarkdown?.evidenceNote,
+  };
+}
+
 export function sessionIdRequestFromArgs(positionals: string[]): SessionIdRequest {
   return {
     sessionId: positionals[0],
@@ -249,6 +325,11 @@ function searchModeOption(args: RawArgs, key: string): SearchMode | undefined {
   throw new Error(`Invalid search mode: ${value}. Expected one of: ${SEARCH_MODES.join(", ")}`);
 }
 
+function embeddingProviderOption(value: string): EmbeddingProviderSetting {
+  if (value === "ollama" || value === "jina") return value;
+  throw new Error(`Invalid embedding provider: ${value}. Expected ollama or jina.`);
+}
+
 function booleanOption(args: RawArgs, ...keys: string[]): boolean | undefined {
   for (const key of keys) {
     const value = args[key];
@@ -296,6 +377,36 @@ function jsonObjectOption(args: RawArgs, key: string): Record<string, unknown> |
   }
 }
 
+function markdownCaptureInput(args: RawArgs, input: SessionCaptureInput | undefined): string | undefined {
+  const inline = stringOption(args, "trap-markdown");
+  const file = stringOption(args, "trap-markdown-file");
+  if (inline === undefined && file === undefined) return undefined;
+
+  const text = file !== undefined
+    ? readMarkdownFile(file, input)
+    : inline === "-"
+      ? readMarkdownStdin(input)
+      : inline ?? "";
+  if (text.trim() === "") throw new Error("Markdown trap input is required.");
+  return text;
+}
+
+function readMarkdownStdin(input: SessionCaptureInput | undefined): string {
+  if (!input) throw new Error("--trap-markdown - requires stdin support.");
+  if (input.isTTY) throw new Error("--trap-markdown - requires piped input.");
+  return input.readStdin();
+}
+
+function readMarkdownFile(path: string, input: SessionCaptureInput | undefined): string {
+  if (!input) throw new Error("--trap-markdown-file requires file read support.");
+  return input.readFile(path);
+}
+
+function uniqueStrings(values: string[]): string[] | undefined {
+  const unique = uniqueStringList(values);
+  return unique.length > 0 ? unique : undefined;
+}
+
 function parseDurationDays(value: string): number {
   const match = value.trim().match(/^(\d+)\s*(d|day|days)?$/i);
   if (!match) throw new Error(`Invalid duration: ${value}. Use a value like 90d.`);

package/src/lib/config.ts

@@ -1,7 +1,8 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { CODETRAP_DIR, SCOPES, SEARCH_MODES, type Scope, type SearchMode } from "./constants";
+import { isRecord } from "./value-types";
 
 export type CodetrapConfig = {
   search?: {
@@ -10,6 +11,16 @@ export type CodetrapConfig = {
     scope?: Scope;
     rerank?: boolean;
   };
+  embeddings?: EmbeddingSettings;
+};
+
+export type EmbeddingProviderSetting = "ollama" | "jina";
+
+export type EmbeddingSettings = {
+  provider?: EmbeddingProviderSetting;
+  endpoint?: string;
+  model?: string;
+  dimensions?: number;
 };
 
 export type SearchDefaults = {
@@ -19,6 +30,11 @@ export type SearchDefaults = {
   rerank: boolean;
 };
 
+export type ConfigWriteResult = {
+  path: string;
+  config: CodetrapConfig;
+};
+
 const BUILT_IN_SEARCH_DEFAULTS: SearchDefaults = {
   mode: "hybrid",
   limit: 20,
@@ -26,7 +42,7 @@ const BUILT_IN_SEARCH_DEFAULTS: SearchDefaults = {
 };
 
 export function loadCodetrapConfig(home = homedir()): CodetrapConfig {
-  const path = join(home, CODETRAP_DIR, "config.json");
+  const path = codetrapConfigPath(home);
   if (!existsSync(path)) return {};
 
   try {
@@ -38,6 +54,26 @@ export function loadCodetrapConfig(home = homedir()): CodetrapConfig {
   }
 }
 
+export function codetrapConfigPath(home = homedir()): string {
+  return join(home, CODETRAP_DIR, "config.json");
+}
+
+export function writeCodetrapConfig(config: CodetrapConfig, home = homedir()): ConfigWriteResult {
+  const path = codetrapConfigPath(home);
+  mkdirSync(join(home, CODETRAP_DIR), { recursive: true });
+  const normalized = normalizeConfig(config);
+  writeFileSync(path, `${JSON.stringify(normalized, null, 2)}\n`);
+  return { path, config: normalized };
+}
+
+export function setCodetrapEmbeddingSettings(
+  embeddings: EmbeddingSettings,
+  home = homedir()
+): ConfigWriteResult {
+  const current = loadCodetrapConfig(home);
+  return writeCodetrapConfig({ ...current, embeddings }, home);
+}
+
 export function searchDefaultsFromConfig(config = loadCodetrapConfig(), env = process.env): SearchDefaults {
   return {
     mode: config.search?.mode ?? parseSearchModeEnv(env.CODETRAP_SEARCH_MODE) ?? BUILT_IN_SEARCH_DEFAULTS.mode,
@@ -50,7 +86,11 @@ export function searchDefaultsFromConfig(config = loadCodetrapConfig(), env = pr
 function normalizeConfig(value: unknown): CodetrapConfig {
   if (!isRecord(value)) return {};
   const search = isRecord(value.search) ? normalizeSearchConfig(value.search) : undefined;
-  return search ? { search } : {};
+  const embeddings = isRecord(value.embeddings) ? normalizeEmbeddingSettings(value.embeddings) : undefined;
+  return {
+    ...(search ? { search } : {}),
+    ...(embeddings ? { embeddings } : {}),
+  };
 }
 
 function normalizeSearchConfig(value: Record<string, unknown>): CodetrapConfig["search"] {
@@ -62,6 +102,15 @@ function normalizeSearchConfig(value: Record<string, unknown>): CodetrapConfig["
   return out;
 }
 
+function normalizeEmbeddingSettings(value: Record<string, unknown>): EmbeddingSettings {
+  const out: EmbeddingSettings = {};
+  if (typeof value.provider === "string") out.provider = parseEmbeddingProvider(value.provider);
+  if (typeof value.endpoint === "string") out.endpoint = value.endpoint;
+  if (typeof value.model === "string") out.model = value.model;
+  if (typeof value.dimensions === "number") out.dimensions = parsePositiveInt(value.dimensions, "embeddings.dimensions");
+  return out;
+}
+
 function parseSearchModeEnv(value?: string): SearchMode | undefined {
   return value ? parseSearchMode(value) : undefined;
 }
@@ -92,11 +141,12 @@ function parseScope(value: string): Scope {
   throw new Error(`Invalid scope: ${value}. Expected one of: ${SCOPES.join(", ")}`);
 }
 
+function parseEmbeddingProvider(value: string): EmbeddingProviderSetting {
+  if (value === "ollama" || value === "jina") return value;
+  throw new Error("Invalid embeddings.provider: expected one of: ollama, jina");
+}
+
 function parsePositiveInt(value: number, label: string): number {
   if (Number.isInteger(value) && value > 0) return value;
   throw new Error(`Invalid ${label}: expected a positive integer.`);
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/lib/constants.ts

@@ -49,7 +49,7 @@ export const DEFAULT_TRAP_STATUS: TrapStatus = "active";
 
 // Increment this when schema changes in a breaking way.
 // Migrations are stored in src/db/migrations.ts
-export const SCHEMA_VERSION = 5;
+export const SCHEMA_VERSION = 6;
 
 // Directory and file names
 export const CODETRAP_DIR = ".codetrap";

package/src/lib/doctor.ts

@@ -1,8 +1,10 @@
 import type { TrapStore } from "./store";
 import type { TrapOperations } from "./trap-operations";
+import type { EmbeddingRuntimeStatus } from "./embedding-runtime";
 import type { EmbeddingStateSummary, EmbeddingStatsResult, HybridFallbackReason } from "./embedding-health";
 import { createScopeContext } from "./scope-context";
 import { hybridFallbackReason } from "./embedding-health";
+import type { ProjectCandidateReviewSummary } from "./session-review";
 
 export type DoctorNextAction = {
   command: string;
@@ -28,19 +30,22 @@ export type DoctorReport = {
       global_db_project_traps: ReturnType<TrapStore["diagnostics"]>["mis_scoped_traps"]["global_db_project_traps"];
     };
   };
+  candidate_review: ProjectCandidateReviewSummary | null;
   next_actions: DoctorNextAction[];
   mcp_hint: string;
 };
 
-export function buildDoctorReport(
+export async function buildDoctorReport(
   store: TrapStore,
   operations: TrapOperations,
-  cwd = process.cwd()
-): DoctorReport {
+  cwd = process.cwd(),
+  candidateReview: ProjectCandidateReviewSummary | null = null
+): Promise<DoctorReport> {
   const scope = createScopeContext(cwd);
   const stats = operations.getStats();
   const embeddings = operations.getEmbeddingStats();
-  const semanticAvailable = store.hasEmbeddingProvider();
+  const embeddingRuntime = await store.embeddingRuntimeHealth();
+  const semanticAvailable = embeddingRuntime.available;
   const diagnostics = store.diagnostics();
 
   return {
@@ -57,7 +62,8 @@ export function buildDoctorReport(
     diagnostics: {
       mis_scoped_traps: diagnostics.mis_scoped_traps,
     },
-    next_actions: buildDoctorNextActions(semanticAvailable, embeddings, diagnostics),
+    candidate_review: candidateReview,
+    next_actions: buildDoctorNextActions(embeddingRuntime, embeddings, diagnostics, candidateReview),
     mcp_hint: "Pass cwd in MCP tool calls, or restart codetrap serve after changing projects.",
   };
 }
@@ -78,6 +84,8 @@ export function formatDoctorText(report: DoctorReport): string {
     `  fallback_reason: ${report.hybrid_search.fallback_reason ?? "(none)"}`,
     "Diagnostics:",
     `  global_db_project_traps: ${report.diagnostics.mis_scoped_traps.global_db_project_traps.length}`,
+    "Candidate review:",
+    formatCandidateReview(report.candidate_review),
     "Next actions:",
     ...formatNextActions(report.next_actions),
     `mcp_hint: ${report.mcp_hint}`,
@@ -85,16 +93,14 @@ export function formatDoctorText(report: DoctorReport): string {
 }
 
 function buildDoctorNextActions(
-  semanticAvailable: boolean,
+  embeddingRuntime: EmbeddingRuntimeStatus,
   embeddings: EmbeddingStatsResult,
-  diagnostics: ReturnType<TrapStore["diagnostics"]>
+  diagnostics: ReturnType<TrapStore["diagnostics"]>,
+  candidateReview: ProjectCandidateReviewSummary | null
 ): DoctorNextAction[] {
   const actions: DoctorNextAction[] = [];
-  if (!semanticAvailable) {
-    actions.push({
-      command: "export JINA_API_KEY=<your-jina-api-key>",
-      reason: "Enable semantic and hybrid search; otherwise use --mode fts.",
-    });
+  if (!embeddingRuntime.available) {
+    if (embeddingRuntime.setup_action) actions.push(embeddingRuntime.setup_action);
   } else {
     const projectAction = embeddingRefreshAction("project", embeddings.project);
     const globalAction = embeddingRefreshAction("global", embeddings.global);
@@ -109,6 +115,18 @@ function buildDoctorNextActions(
       reason: `${stranded} project-scoped trap(s) are stored in the global database.`,
     });
   }
+  if (candidateReview && candidateReview.pending_count > 0) {
+    if (candidateReview.next_session_id) {
+      actions.push({
+        command: `codetrap session candidates ${candidateReview.next_session_id} --json`,
+        reason: `${candidateReview.pending_count} pending candidate trap(s) need review.`,
+      });
+    }
+    actions.push({
+      command: "codetrap web",
+      reason: "Open the candidate review console.",
+    });
+  }
   return actions;
 }
 
@@ -134,6 +152,18 @@ function formatNextActions(actions: DoctorNextAction[]): string[] {
   return actions.map((action) => `  - ${action.command} # ${action.reason}`);
 }
 
+function formatCandidateReview(summary: ProjectCandidateReviewSummary | null): string {
+  if (!summary) return "  unavailable";
+  return [
+    `  pending=${summary.pending_count}`,
+    `reviewed=${summary.reviewed_count}`,
+    `sessions=${summary.pending_session_count}/${summary.session_count}`,
+    `high_quality_pending=${summary.high_quality_pending_count}`,
+    `needs_edit=${summary.needs_edit_count}`,
+    `next_session=${summary.next_session_id ?? "(none)"}`,
+  ].join(", ");
+}
+
 function formatEmbeddingStats(
   label: string,
   stats: EmbeddingStatsResult["global"] | null