simt-dev 0.3.1 → 0.5.0

package/src/commands/decide.mjs

@@ -0,0 +1,116 @@
+// `simt decide` — scaffold an ADR with the next free number, a Status: line,
+// a rulings skeleton, and structured `simt-affects` + `simt-supersedes` frontmatter
+// (plan 0003 R34).
+
+import { join, resolve } from 'node:path';
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { DECISIONS_DIR } from '../decisions/index.mjs';
+import { lintDecisions, scaffoldDecision } from '../memory/decide.mjs';
+import { parsePathList } from '../argv.mjs';
+
+export async function decideCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+
+  if (flags.check === true) {
+    const decisionsDir = join(root, 'docs', 'decisions');
+    const allowHistorical = resolve(decisionsDir) === DECISIONS_DIR;
+    const res = await lintDecisions(decisionsDir, { allowHistorical });
+
+    if (isJson(flags)) {
+      emitJson({
+        ok: res.ok,
+        command: 'decide --check',
+        root,
+        findings: res.findings,
+      });
+      return res.ok ? EXIT.OK : EXIT.FAIL;
+    }
+
+    if (res.findings.length === 0) {
+      emit('decisions  ok', { maxBytes: flags.maxBytes ?? 0 });
+      return EXIT.OK;
+    }
+
+    emit(
+      res.findings
+        .flatMap((f) => [
+          `${f.status.toUpperCase()}  ${f.file}  ${f.detail}`,
+          ...(f.remedy ? [`  remedy: ${f.remedy}`] : []),
+        ])
+        .join('\n'),
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return EXIT.FAIL;
+  }
+
+  const mode = writeMode(flags);
+  const title = args.join(' ').trim() || flags.task || 'Untitled decision';
+  const parsedPaths = parsePathList(flags.paths);
+  const explicitPaths = flags.paths !== undefined ? parsedPaths : undefined;
+
+  const res = await scaffoldDecision(root, {
+    title,
+    affects: explicitPaths,
+    supersedes: flags.supersedes,
+    write: mode.apply,
+  });
+
+  if (!res.ok) {
+    return fail(
+      res.errors[0],
+      EXIT.USAGE,
+      `usage: ${CLI} decide "<title>" [--supersedes ADR-NNN:<ruling>] [--yes]`,
+    );
+  }
+
+  if (mode.apply) {
+    note(`wrote    ${res.relPath}`);
+  } else if (flags.dryRun === true) {
+    note('dry-run  no files written');
+  }
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'decide',
+      root,
+      id: res.id,
+      number: res.number,
+      title: res.title,
+      file: res.file,
+      path: res.relPath,
+      affects: res.affects,
+      supersedes: res.supersedes,
+      written: res.written,
+      dryRun: !mode.apply,
+    });
+    return EXIT.OK;
+  }
+
+  const supersedesLabel =
+    res.supersedes.length > 0
+      ? res.supersedes
+          .map((s) => (s.ruling !== null ? `${s.adr} ruling ${s.ruling} (${s.kind})` : s.adr))
+          .join('; ')
+      : '(none)';
+
+  const lines = [
+    `id          ${res.id}`,
+    `title       ${res.title}`,
+    `file        ${res.relPath}`,
+    `affects     ${res.affects.length > 0 ? res.affects.join(', ') : '(none)'}`,
+    `supersedes  ${supersedesLabel}`,
+    '',
+    res.text.trimEnd(),
+    '',
+    mode.apply
+      ? `wrote ${res.relPath}`
+      : flags.dryRun === true
+        ? 'dry-run; nothing written'
+        : `would write ${res.relPath}; apply with: ${CLI} decide ${JSON.stringify(res.title)} --yes`,
+  ];
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/commands/distill.mjs

@@ -0,0 +1,36 @@
+// `simt distill <skill|doc>` (plan 0003 R38).
+//
+// A budgeted summary with citations to source line ranges, written to
+// `.simt-dev/distilled/` as a proposal a human merges. The deterministic engine
+// is the default; a local model proposes only when the caller asks for it and the
+// manifest names one (ADR-090, ADR-075). Model output never lands anywhere
+// projected or committed text does — that is the direction this command cannot
+// take (principle P2).
+
+import { CLI } from '../name.mjs';
+import { EXIT, emit, emitJson, isJson } from '../output/index.mjs';
+import { distillTarget } from '../distill/distill.mjs';
+
+export async function distillCommand(args, flags) {
+  const result = await distillTarget(args, flags);
+  if (typeof result === 'number') return result;
+
+  if (isJson(flags)) {
+    emitJson(result, { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+
+  emit(
+    [
+      `source    ${result.target.kind}  ${result.target.source} (${result.target.bytes} bytes, ${result.target.lines} lines)`,
+      `digest    ${result.digest}`,
+      `engine    ${result.engine}`,
+      `budget    ${result.budget} bytes`,
+      `citations ${result.citations}`,
+      ...(result.verified === true ? [] : result.faults.map((f) => `unverified ${f}`)),
+      `proposal  ${result.proposal.path}  (${result.proposal.state}, ${result.proposal.bytes} bytes)`,
+    ].join('\n'),
+    { maxBytes: flags.maxBytes ?? 0 },
+  );
+  return EXIT.OK;
+}

package/src/commands/help.mjs

@@ -16,6 +16,12 @@ ${CLI} upgrade                move every consumer to this simt-dev SHA, as one s
                            (dry-run unless --yes; moves a pin only - it never
                            adopts or repairs a repo; never commits or pushes)
 
+${CLI} brief "<task>"         one packet for a task: the kind, the commands, the
+                           likely files, the tests and the decisions that govern
+                           them, inside --budget bytes (default 2048; 0 is
+                           unlimited). Says how many items it cut; --explain
+                           says why each was kept or dropped
+
 ${CLI} skills index           tier-0 catalog: every skill, one line each
 ${CLI} skills brief --task    tier-1 pre-assembled brief  <- the common case
 ${CLI} skills show <name>     tier-2 body (respects --max-bytes)
@@ -28,6 +34,9 @@ ${CLI} skills eval [corpus]   measure the resolver against a gold corpus
 ${CLI} skills install <name>  pin a skill into the repo as a local override
                            (dry-run unless --yes; a multi-variant skill needs
                            --variant or --from rather than a guess)
+${CLI} skills compile [<name>] compile a skill to Agent Skills standard, flag bodies
+                           over 5000 tokens with a split plan, and report per-skill
+                           trigger recall and precision from R02 transcripts
 
 ${CLI} rules list             the rule catalogue (--root marks what applies to a repo)
 ${CLI} rules show <id>        one rule body
@@ -39,7 +48,8 @@ ${CLI} hooks install [--yes]   install the shared dispatcher; report what it wou
 ${CLI} hooks status            what each git event routes to, and whether it is wired
 ${CLI} hooks run <event>       run one event's gates now, as git would
                            (pre-commit, pre-push, post-merge, ...)
-${CLI} agent-hook <event>      the entry point a harness calls before a tool call
+${CLI} agent-hook <event>      the entry point a harness calls: pre-tool-use decides,
+                            prompt-submit delivers the packet as prompt context
                            (reads one JSON payload on stdin and answers in that
                             harness's dialect; exit 2 blocks; needs --harness)
 ${CLI} agent-hooks install     write this repo's policies into the harnesses that
@@ -82,6 +92,32 @@ ${CLI} map [--task "<text>"] [--level outline|names|signatures]
 ${CLI} evidence                the runs recorded against the tree on disk
 ${CLI} evidence check <file>   a commit message that claims a run this tree does not
                            have: a warning, or a block when gates.evidence is "block"
+${CLI} lessons list            deterministic lesson candidates in .simt-dev/lessons.jsonl
+                           and promoted lessons in docs/lessons/*.md
+${CLI} lessons review [<id>]   promote a lesson candidate to docs/lessons/NNNN-<slug>.md
+                           (dry-run unless --yes; writes Appendix A frontmatter)
+${CLI} decide [<title>]        scaffold an ADR with the next free number, a Status: line,
+                           a rulings skeleton, and structured simt-affects +
+                           simt-supersedes frontmatter (dry-run unless --yes;
+                           --check lints ADRs for prose-only partial supersessions)
+${CLI} local doctor            probe configured local model endpoints (chat and embed)
+                           (reads local in ${MANIFEST_FILE}; opens no socket when
+                           unset; refuses non-loopback URLs without --allow-remote)
+${CLI} distill <skill|doc>     a budgeted proposal summary of a skill body or doc,
+                           every claim citing the source line range it rests on
+                           (writes .simt-dev/distilled/<digest>.md; a proposal a
+                           human merges - never projected or committed;
+                           deterministic outline by default; --local proposes
+                           from the configured chat model instead; the cache is
+                           keyed by source digest and budget, --refresh regenerates)
+${CLI} review [--local]        an ADR-008 verdict skeleton for the staged diff,
+                           the brief listing everything that governs it (R25)
+                           (deterministic without --local: the brief and its
+                           governing ids only; --local proposes from the
+                           configured chat model and writes
+                           .simt-dev/reviews/<digest>.md — a proposal a human
+                           reads, verified against the verdict vocabulary and
+                           the brief's ids; advisory always, never a gate)
 ${CLI} shared plan            what a workspace's repeated rules cost to carry
                            once: the shared set, its bytes, and every path that would be written
                            (read-only; touches nothing, not even your home directory)
@@ -117,6 +153,14 @@ ${CLI} bench ablate [--yes]    leave-one-out ablation across core, profile and p
 ${CLI} bench probes [--yes]    12 synthetic rule-compliance probes with deterministic graders
                             (dry-run unless --yes; grades git state, transcript and ledger,
                             and reports compliance per arm)
+${CLI} bench variants [--yes]  evaluate simt-variants rule slots on the canary suite and lock
+                            winning variants in simt-dev.lock.json (dry-run unless --yes;
+                            re-opens when model or harness changes)
+${CLI} bench critic          precision and recall of the local critic over a labelled
+                            set of historical diffs (.simt-dev/critic-labels.jsonl;
+                            overrides --labels; labels are human-written verdicts
+                            under ADR-008; the critic is advisory until precision
+                            reaches 0.8 on 30 labelled diffs)
 ${CLI} mcp                    the read-only surface as MCP tools over stdio
                            (--list prints it without reading stdin; init, sync,
                            upgrade and the installers stay CLI-only by design)`;
@@ -124,7 +168,8 @@ ${CLI} mcp                    the read-only surface as MCP tools over stdio
 const FLAGS = `--json                 structured output (compact; one document, one line)
 --pretty                indent --json for a human
 --max-bytes <n>         hard ceiling on emitted bytes (0 = unlimited, default 0)
---budget <n>            context budget for skills brief (default 20480)
+--budget <n>            context budget for a brief (default 2048)
+                        (skills brief keeps its own default of 20480)
 --plan                  emit a fetch plan instead of inlining skill bodies
 --skill <name>          force a skill into the brief (repeatable)
 --task "<text>"         the task text used for capability resolution
@@ -142,7 +187,8 @@ const FLAGS = `--json                 structured output (compact; one document,
 --frozen                check: the lock must match this projection; an output
                         change no input change explains fails the gate
 --explain               sync: name each line dropped as already inferable, with
-                        the fact behind it
+                        the fact behind it; brief: name every item and why it
+                        was kept or cut, with its section's value
 --all                   ignore a cap: every ruling of a record, or the skills budget
 --variant <id>          which body of a multi-variant skill to use
 --from <repo/path>      install from a declared source by name
@@ -176,6 +222,19 @@ const FLAGS = `--json                 structured output (compact; one document,
 --compare <a> <b>       bench report: compare two arms with deltas and p-values
 --test <cmd>            plan done: the test command that closes the row
 --state <name>          plan done: target state (default: Complete)
+--level <name>          map: detail level (outline, names, signatures)
+--supersedes <spec>     decide: superseded ADR or ruling (ADR-NNN or ADR-NNN:<ruling>[:<kind>]; repeatable)
+--allow-remote          local doctor / distill / review: allow non-loopback model
+                         URLs (refused by default)
+--embed                 index / map / brief: compute or query optional local vector embeddings
+                        (off by default unless recall@10 gains at least 10 points)
+--labels <path>         bench critic: the labelled set of historical diffs to score
+                        (default .simt-dev/critic-labels.jsonl; one human-written
+                        {sha, verdict} pair per line)
+--refresh               distill / review: regenerate a proposal that is already cached
+--local                 distill / review: propose the answer from the configured
+                         local chat model (local.chat); off by default, which
+                         uses the deterministic path instead
 --help                  this text
 --version               the version, and the SHA it was built from`;
 

package/src/commands/index.mjs

@@ -25,6 +25,7 @@ import {
   whyCommand as skillsWhy,
   evalCommand as skillsEval,
 } from './skills.mjs';
+import { briefCommand } from './brief.mjs';
 import { syncCommand, checkCommand } from './sync.mjs';
 import { initCommand } from './init.mjs';
 import { ciCommand } from './ci.mjs';
@@ -34,6 +35,7 @@ import { compareCommand } from './compare.mjs';
 import { upgradeCommand } from './upgrade.mjs';
 import { mcpCommand } from './mcp.mjs';
 import { installCommand } from './skillsinstall.mjs';
+import { compileCommand } from './skillscompile.mjs';
 import { listCommand as rulesList, showCommand as rulesShow, whyCommand as rulesWhy } from './rules.mjs';
 import { tokensCommand } from './tokens.mjs';
 import { harnessCommand, harnessLoadersCommand } from './harness.mjs';
@@ -43,6 +45,8 @@ import {
   benchReportCommand,
   benchAblateCommand,
   benchProbesCommand,
+  benchVariantsCommand,
+  benchCriticCommand,
 } from './bench.mjs';
 import { planCommand } from './plan.mjs';
 import { sharedPlanCommand, sharedInstallCommand, sharedWarning } from './shared.mjs';
@@ -53,7 +57,13 @@ import { testsCommand } from './tests.mjs';
 import { whyCommand } from './why.mjs';
 import { gateCommand } from './gate.mjs';
 import { impactCommand } from './impact.mjs';
+import { lessonsListCommand, lessonsReviewCommand } from './lessons.mjs';
+import { decideCommand } from './decide.mjs';
+import { reviewCommand } from './review.mjs';
+import { localDoctorCommand } from './local.mjs';
+import { distillCommand } from './distill.mjs';
 import { parse } from '../argv.mjs';
+import { CLI } from '../name.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { resolveWorkspace } from '../workspace.mjs';
 
@@ -79,6 +89,8 @@ const GROUPS = new Map([
   // where", and `install` — the subcommand that touches a reader's home directory — is the
   // one that needs `--yes` before it does anything.
   ['shared', 'plan'],
+  ['lessons', 'list'],
+  ['local', 'doctor'],
 ]);
 
 /**
@@ -95,6 +107,7 @@ const GROUPS = new Map([
  * just correct: nothing in the map depends on the call.
  */
 export const IMPLEMENTED = {
+  brief: briefCommand,
   doctor: runDoctor,
   'graph lint': lintCommand,
   'skills index': skillsIndex,
@@ -104,6 +117,7 @@ export const IMPLEMENTED = {
   'skills why': skillsWhy,
   'skills eval': skillsEval,
   'skills install': installCommand,
+  'skills compile': compileCommand,
   'rules list': rulesList,
   'rules show': rulesShow,
   'rules why': rulesWhy,
@@ -121,6 +135,14 @@ export const IMPLEMENTED = {
   why: (args, flags) => whyCommand(args, flags, COMMANDS),
   gate: gateCommand,
   impact: (args, flags) => impactCommand(args, flags, COMMANDS),
+  'lessons list': lessonsListCommand,
+  'lessons review': lessonsReviewCommand,
+  decide: decideCommand,
+  distill: distillCommand,
+  // R25 machinery needs the runnable command names for Affects command tokens,
+  // same wiring `why` and `impact` get through their lambdas.
+  review: (args, flags) => reviewCommand(args, flags, COMMANDS),
+  'local doctor': localDoctorCommand,
   'evidence check': (args, flags) => evidenceCommand(['check', ...args], flags),
   init: initCommand,
   ci: ciCommand,
@@ -139,6 +161,12 @@ export const IMPLEMENTED = {
   'bench report': benchReportCommand,
   'bench ablate': benchAblateCommand,
   'bench probes': benchProbesCommand,
+  'bench variants': benchVariantsCommand,
+  // plan 0003 R39. The critic's acceptance bench measures BLOCK-precision and
+  // recall over a labelled set; until it reports its floor, the critic entries
+  // stay advisory and no gate reads them. COMMANDS rides along so the brief
+  // resolves Affects command tokens the way `simt why` does.
+  'bench critic': (args, flags) => benchCriticCommand(args, flags, COMMANDS),
   upgrade: upgradeCommand,
   mcp: mcpCommand,
 };
@@ -186,7 +214,7 @@ export async function dispatch(argv) {
     // simt-dev: they run this tool, not its source tree. The step number is the
     // stable handle; the file that documents it is an implementation detail.
     return fail(
-      `\`simt-dev ${path}\` is declared but not implemented`,
+      `\`${CLI} ${path}\` is declared but not implemented`,
       EXIT.UNSUPPORTED,
       `implementation step ${step} is not built yet`,
     );

package/src/commands/lessons.mjs

@@ -0,0 +1,127 @@
+// `simt lessons [list|review]` — deterministic lesson candidates and promotion to
+// `docs/lessons/NNNN-<slug>.md` (plan 0003 R32).
+
+import { resolve } from 'node:path';
+
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { parsePathList } from '../argv.mjs';
+import {
+  LESSONS_DIR,
+  LESSONS_FILE,
+  captureFromLedger,
+  captureRevertedCommits,
+  listPromotedLessons,
+  promoteLesson,
+  readLessonCandidates,
+} from '../memory/lessons.mjs';
+
+export async function lessonsListCommand(args, flags) {
+  if (args.length > 0) {
+    return fail(`unknown lessons argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} lessons`);
+  }
+  const root = resolve(flags.root ?? process.cwd());
+  await captureFromLedger(root);
+  await captureRevertedCommits(root);
+
+  const [{ candidates, errors }, promoted] = await Promise.all([
+    readLessonCandidates(root),
+    listPromotedLessons(root),
+  ]);
+
+  const payload = {
+    ok: errors.length === 0,
+    command: 'lessons list',
+    root,
+    ledgerFile: LESSONS_FILE,
+    lessonsDir: LESSONS_DIR,
+    candidateCount: candidates.length,
+    promotedCount: promoted.length,
+    candidates,
+    promoted,
+    errors,
+  };
+
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
+  }
+
+  const lines = [
+    `candidates  ${candidates.length} (${LESSONS_FILE})`,
+    `promoted    ${promoted.length} (${LESSONS_DIR})`,
+  ];
+
+  if (candidates.length > 0) {
+    lines.push('', 'CANDIDATES');
+    for (const c of candidates) {
+      const sigShort = c.signature.slice(0, 19);
+      const state = c.status === 'promoted' ? `promoted -> ${c.promotedTo}` : 'candidate';
+      lines.push(`  ${c.id}  ${c.kind.padEnd(14)}  ${sigShort}  ${state}  ${c.summary}`);
+    }
+  }
+
+  if (promoted.length > 0) {
+    lines.push('', 'LESSONS');
+    for (const l of promoted) {
+      lines.push(`  ${l.id.padEnd(28)}  ${(l.signature ?? 'no-signature').slice(0, 19)}  ${l.title}`);
+    }
+  }
+
+  for (const err of errors) lines.push(`error       ${err}`);
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
+}
+
+export async function lessonsReviewCommand(args, flags) {
+  if (args.length > 1) {
+    return fail(`unknown lessons review argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} lessons review [<id>] [--yes]`);
+  }
+  const root = resolve(flags.root ?? process.cwd());
+  const mode = writeMode(flags);
+  const parsedPaths = parsePathList(flags.paths);
+  const paths = parsedPaths.length > 0 ? parsedPaths : undefined;
+  const title = flags.task ? String(flags.task) : undefined;
+
+  const result = await promoteLesson(root, {
+    id: args[0],
+    apply: mode.apply,
+    paths,
+    title,
+  });
+
+  if (!result.ok) {
+    return fail(result.error, EXIT.FAIL, `record a session failure-then-fix or run: ${CLI} lessons`);
+  }
+
+  const payload = {
+    ok: true,
+    command: 'lessons review',
+    root,
+    dryRun: mode.dryRun,
+    written: result.written,
+    path: result.path,
+    candidate: result.candidate,
+    markdown: result.markdown,
+  };
+
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+
+  const lines = [
+    `promote     ${result.candidate.id} (${result.candidate.kind}) -> ${result.path}`,
+    `signature   ${result.candidate.signature}`,
+    `mode        ${mode.apply ? 'applied' : mode.dryRun ? 'dry-run (writes nothing)' : `preview (pass --yes to write ${result.path})`}`,
+    '',
+    result.markdown.trimEnd(),
+  ];
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  if (!mode.apply) {
+    note(`note    dry-run  nothing written; apply with: ${CLI} lessons review --yes`);
+  }
+  return EXIT.OK;
+}

package/src/commands/local.mjs

@@ -0,0 +1,97 @@
+// `simt local doctor` — probe configured local model endpoints (plan 0003 R37).
+//
+// Reads `local: { chat: { url, model }, embed: { url, model } }` from `simt.json`.
+// When `local` is unset, opens no socket and exits 0. Refuses non-loopback URLs
+// without `--allow-remote` (ADR-075).
+
+import { resolve } from 'node:path';
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI, MANIFEST_FILE } from '../name.mjs';
+import { probeLocal } from '../local/client.mjs';
+
+function formatRoleLine(role, report) {
+  if (!report) return `${role.padEnd(8)} (unset)`;
+  if (report.status === 'refused-remote') {
+    return `${role.padEnd(8)} refused-remote  ${report.model} @ ${report.url}`;
+  }
+  if (!report.ok) {
+    return `${role.padEnd(8)} ${report.status}  ${report.model} @ ${report.url} (${report.error})`;
+  }
+  const extra =
+    role === 'embed' && Number.isInteger(report.dimensions)
+      ? `  dimensions=${report.dimensions}`
+      : '';
+  const listed =
+    report.modelListed === true
+      ? '  listed=yes'
+      : report.modelListed === false
+        ? '  listed=no'
+        : '';
+  return `${role.padEnd(8)} ok  ${report.model} @ ${report.url}${extra}${listed}`;
+}
+
+function remedyFor(result) {
+  if (result.status === 'refused-remote') {
+    return `set a loopback URL (http://127.0.0.1:<port>/v1) in ${MANIFEST_FILE}, or run: ${CLI} local doctor --allow-remote`;
+  }
+  if (result.status === 'invalid-config' || result.status === 'invalid-manifest') {
+    return `fix the \`local\` configuration in ${MANIFEST_FILE}`;
+  }
+  if (result.status === 'unreachable') {
+    return `start the local model server at the URL in ${MANIFEST_FILE}, then rerun: ${CLI} local doctor`;
+  }
+  return null;
+}
+
+export async function localDoctorCommand(args, flags) {
+  const root = resolve(flags.root ?? args[0] ?? process.cwd());
+  const allowRemote = flags.allowRemote === true;
+  const result = await probeLocal(root, { allowRemote });
+
+  const code = result.ok
+    ? EXIT.OK
+    : result.status === 'refused-remote' ||
+        result.status === 'invalid-config' ||
+        result.status === 'invalid-manifest'
+      ? EXIT.CONFIG
+      : EXIT.FAIL;
+
+  const error = result.ok ? null : result.findings[0] ?? `local model probe failed (${result.status})`;
+  const remedy = result.ok ? null : remedyFor(result);
+
+  if (isJson(flags)) {
+    emitJson(
+      {
+        ok: code === EXIT.OK,
+        command: 'local doctor',
+        root,
+        configured: result.configured,
+        status: result.status,
+        allowRemote: result.allowRemote,
+        remoteBlocked: result.remoteBlocked,
+        socketsOpened: result.socketsOpened,
+        chat: result.chat,
+        embed: result.embed,
+        findings: result.findings,
+        ...(error ? { error, remedy, exitCode: code } : {}),
+      },
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return code;
+  }
+
+  const lines = [
+    `root     ${root}`,
+    `local    ${result.configured ? result.status : '(unset)  optional adapter is off; no socket opened'}`,
+    formatRoleLine('chat', result.chat),
+    formatRoleLine('embed', result.embed),
+    `sockets  ${result.socketsOpened}`,
+  ];
+
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+
+  if (!result.ok) {
+    return fail(error, code, remedy);
+  }
+  return EXIT.OK;
+}

package/src/commands/map.mjs

@@ -5,8 +5,15 @@
 
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
-import { readEdges, readFiles, readSymbols, reindex } from '../index/store.mjs';
-import { DEFAULT_BUDGET, formatRecall, measureRecall, rankFiles, renderMap } from '../index/map.mjs';
+import { readEdges, readEmbeddings, readFiles, readFts, readSymbols, reindex, searchFtsBm25 } from '../index/store.mjs';
+import {
+  DEFAULT_BUDGET,
+  embedTaskQuery,
+  formatRecall,
+  measureRecall,
+  rankFiles,
+  renderMap,
+} from '../index/map.mjs';
 
 const LEVELS = new Set(['outline', 'names', 'signatures']);
 
@@ -25,7 +32,15 @@ export async function mapCommand(args, flags) {
   const loaded = await loadGraph(root);
   if (loaded.error) return loaded.error;
   const task = typeof flags.task === 'string' ? flags.task : '';
-  const ranked = rankFiles({ ...loaded, task });
+  const bm25 = task.trim().length > 0 ? await searchFtsBm25(root, task, { fts: loaded.fts }) : [];
+  const queryVector =
+    flags.embed === true && loaded.embeddings.length > 0
+      ? await embedTaskQuery(root, task, {
+          embed: true,
+          allowRemote: flags.allowRemote === true,
+        })
+      : null;
+  const ranked = rankFiles({ ...loaded, bm25, queryVector, task });
   const rendered = renderMap(ranked, loaded.symbols, { level, budget });
   const payload = {
     ok: true,
@@ -57,7 +72,10 @@ export async function mapCommand(args, flags) {
 async function recall(root, flags) {
   let result;
   try {
-    result = await measureRecall(root);
+    result = await measureRecall(root, {
+      embed: flags.embed === true,
+      allowRemote: flags.allowRemote === true,
+    });
   } catch (error) {
     return fail(`could not measure recall (${error.message})`, EXIT.UNSUPPORTED, `run ${CLI} index in a git repository`);
   }
@@ -70,9 +88,21 @@ async function recall(root, flags) {
   return EXIT.OK;
 }
 
-async function loadGraph(root) {
+/**
+ * The files, symbols, edges, FTS rows and stored vector embeddings the index holds,
+ * building the index once when it is empty.
+ *
+ * `build: false` refuses that rebuild and answers with `cold: true` instead. The one
+ * caller that passes it is the prompt-submit hook (R29), and the reason is the bar that
+ * hook has to meet: a delivered packet that built an index would make a person's first
+ * prompt in a fresh clone wait on a walk of the whole repository, and a prompt that takes
+ * a minute to appear is how a hook gets uninstalled. The next prompt gets the packet, and
+ * a command a person typed at a terminal always builds what it needs.
+ */
+export async function loadGraph(root, { build = true } = {}) {
   let files = await readFiles(root);
   if (files.length === 0) {
+    if (!build) return { files: [], symbols: [], edges: [], fts: [], embeddings: [], cold: true };
     try {
       await reindex(root);
     } catch (error) {
@@ -86,6 +116,11 @@ async function loadGraph(root) {
     }
     files = await readFiles(root);
   }
-  const [symbols, edges] = await Promise.all([readSymbols(root), readEdges(root)]);
-  return { files, symbols, edges };
+  const [symbols, edges, fts, embeddings] = await Promise.all([
+    readSymbols(root),
+    readEdges(root),
+    readFts(root),
+    readEmbeddings(root),
+  ]);
+  return { files, symbols, edges, fts, embeddings };
 }