@karajan-family/code 4.21.0

package/src/commands/config.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import yaml from "js-yaml";
+import { loadConfig, validateConfig, getConfigPath, writeConfig } from "../config.js";
+import { ensureDir } from "../utils/fs.js";
+import path from "node:path";
+
+function resolveEditor() {
+  const raw = process.env.VISUAL || process.env.EDITOR || "vi";
+  const parts = raw.split(/\s+/);
+  return { cmd: parts[0], args: parts.slice(1) };
+}
+
+export async function editConfigOnce(configPath) {
+  const { cmd, args } = resolveEditor();
+  const result = spawnSync(cmd, [...args, configPath], { stdio: "inherit" });
+
+  if (result.status !== 0) {
+    return { ok: false, error: `Editor exited with code ${result.status}` };
+  }
+
+  let raw;
+  try {
+    raw = await fs.readFile(configPath, "utf8");
+  } catch (err) {
+    return { ok: false, error: `Could not read config: ${err.message}` };
+  }
+
+  let parsed;
+  try {
+    parsed = yaml.load(raw);
+  } catch (err) {
+    return { ok: false, error: `Invalid YAML: ${err.message}` };
+  }
+
+  try {
+    validateConfig(parsed || {});
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+
+  return { ok: true, config: parsed };
+}
+
+export async function configCommand({ json = false, edit = false }) {
+  if (edit) {
+    const configPath = getConfigPath();
+    await ensureDir(path.dirname(configPath));
+    const { exists: configExists } = await loadConfig();
+    if (!configExists) {
+      const { config: defaults } = await loadConfig();
+      await writeConfig(configPath, defaults);
+    }
+
+    const result = await editConfigOnce(configPath);
+    if (result.ok) {
+      console.log("Configuration saved and validated.");
+    } else {
+      console.error(`Validation error: ${result.error}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const { config, path: cfgPath, exists } = await loadConfig();
+  if (json) {
+    console.log(JSON.stringify({ path: cfgPath, exists, config }, null, 2));
+    return;
+  }
+
+  console.log(`Config path: ${cfgPath}`);
+  console.log(`Exists: ${exists}`);
+  console.log(JSON.stringify(config, null, 2));
+}

package/src/commands/discover.js

@@ -0,0 +1,105 @@
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { resolveRole } from "../config.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+import { createCliProgressReporter } from "../utils/cli-progress.js";
+import { buildDiscoverPrompt, parseDiscoverOutput } from "../prompts/discover.js";
+
+function formatGaps(gaps, lines) {
+  lines.push("## Gaps");
+  for (const g of gaps) {
+    const sev = g.severity ? ` [${g.severity}]` : "";
+    lines.push(`- ${g.description || g}${sev}`);
+    if (g.suggestedQuestion) lines.push(`  → ${g.suggestedQuestion}`);
+  }
+  lines.push("");
+}
+
+function formatMomTest(questions, lines) {
+  lines.push("## Mom Test Questions");
+  for (const q of questions) {
+    lines.push(`- ${q.question || q}`);
+    if (q.rationale) lines.push(`  _${q.rationale}_`);
+  }
+  lines.push("");
+}
+
+function formatWendel(checklist, lines) {
+  lines.push("## Wendel Checklist");
+  for (const w of checklist) {
+    const icon = w.status === "pass" ? "✓" : w.status === "fail" ? "✗" : "?";
+    lines.push(`- [${icon}] ${w.condition}: ${w.justification || ""}`);
+  }
+  lines.push("");
+}
+
+function formatClassification(classification, lines) {
+  lines.push("## Classification");
+  lines.push(`- Type: ${classification.type}`);
+  if (classification.adoptionRisk) lines.push(`- Adoption risk: ${classification.adoptionRisk}`);
+  if (classification.frictionEstimate) lines.push(`- Friction: ${classification.frictionEstimate}`);
+  lines.push("");
+}
+
+function formatJtbds(jtbds, lines) {
+  lines.push("## Jobs-to-be-Done");
+  for (const j of jtbds) {
+    lines.push(`- **${j.id || ""}**: ${j.functional || j}`);
+  }
+  lines.push("");
+}
+
+function formatDiscover(result, mode) {
+  const lines = [];
+  lines.push(`## Discovery (${mode})`);
+  lines.push(`**Verdict:** ${result.verdict || "unknown"}`, "");
+
+  if (result.gaps?.length) formatGaps(result.gaps, lines);
+  if (result.momTestQuestions?.length) formatMomTest(result.momTestQuestions, lines);
+  if (result.wendelChecklist?.length) formatWendel(result.wendelChecklist, lines);
+  if (result.classification) formatClassification(result.classification, lines);
+  if (result.jtbds?.length) formatJtbds(result.jtbds, lines);
+  if (result.summary) lines.push(`---\n${result.summary}`);
+  return lines.join("\n");
+}
+
+export async function discoverCommand({ task, config, logger, mode, json }) {
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("discover", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const discoverRole = resolveRole(config, "discover");
+    await assertAgentsAvailable([discoverRole.provider]);
+    logger.info(`Discover (${discoverRole.provider}) starting — mode: ${mode || "gaps"}...`);
+    runLog.logText(`[discover] provider=${discoverRole.provider} mode=${mode || "gaps"}`);
+
+    const agent = createAgent(discoverRole.provider, config, logger);
+    const prompt = buildDiscoverPrompt({ task, mode: mode || "gaps" });
+    const progress = createCliProgressReporter({ role: "discover" });
+    let result;
+    try {
+      result = await withBrainRecovery({
+        agent, taskArgs: { prompt, onOutput: progress.onOutput, role: "discover" },
+        role: "discover", provider: discoverRole.provider, logger,
+      });
+      progress.finish(result.ok ? "done" : (result.action || "failed"));
+    } catch (err) { progress.finish("failed"); throw err; }
+
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Discover failed");
+    }
+
+    const parsed = parseDiscoverOutput(result.output);
+
+    if (json) {
+      console.log(JSON.stringify(parsed || result.output, null, 2));
+      return { ok: true };
+    }
+
+    if (parsed?.verdict) {
+      console.log(formatDiscover(parsed, mode || "gaps"));
+    } else {
+      console.log(result.output);
+    }
+    logger.info("Discover completed.");
+    return { ok: true };
+  });
+}

package/src/commands/doctor.js

@@ -0,0 +1,251 @@
+/**
+ * `kj doctor` command. Runs the unified check runner and prints a
+ * human-readable report by default. Supports flags:
+ *
+ *   --check-only   : only detect, do not apply fixes
+ *   --yes / -y     : auto-confirm prompts for invasive remediations (CI mode)
+ *   --json         : emit machine-readable JSON to stdout
+ *   --verbose      : include fix hints and timing per check
+ *
+ * Exit code is 1 whenever any check ends with FAIL (including remediation
+ * failures). WARN, OK, FIXED, SKIPPED and TIMEOUT do not fail the command.
+ */
+
+import readline from "node:readline";
+import { runChecks as runCheckPipeline, toLegacyShape } from "../checks/runner.js";
+import { collectGuaranteeFacts } from "../checks/guarantee-level.js";
+import { STATUS } from "../checks/types.js";
+import { getSystemChecks } from "../checks/system.js";
+import { getConfigFileChecks } from "../checks/config-files.js";
+import { getBinaryChecks } from "../checks/binaries.js";
+import { getSonarChecks } from "../checks/sonar.js";
+import { getOllamaChecks } from "../checks/ollama.js";
+import { getHarnessScorecardChecks } from "../checks/harness-scorecard.js";
+import { getCiChecks } from "../checks/ci.js";
+import { getRtkChecks } from "../checks/rtk.js";
+import { getSqueezrChecks } from "../checks/squeezr.js";
+import { getAiTrashChecks } from "../checks/ai-trash.js";
+import { getQmdChecks } from "../checks/qmd.js";
+import { getRagHooksChecks } from "../checks/rag-hooks.js";
+import { getNodeChecks } from "../checks/node.js";
+import { getNativeBuildChecks } from "../checks/native-build.js";
+import { getPortChecks } from "../checks/ports.js";
+import { getTokenChecks } from "../checks/tokens.js";
+import { getMcpHealthChecks } from "../checks/mcp-health.js";
+import { getSkillsChecks } from "../checks/skills.js";
+import { getDirSetupChecks } from "../checks/dir-setup.js";
+import { getProjectChecks } from "../checks/project-checks.js";
+import { getHardwareChecks } from "../checks/hardware.js";
+import { getOrphanChecks } from "../checks/orphans.js";
+import { getMethodChecks } from "../checks/method.js";
+
+/**
+ * Build the list of Check objects applicable to the current config.
+ *
+ * KJC-TSK-0393: cuando `projectOnly === true`, devuelve SOLO los project-aware
+ * checks (signals, tools per signal, write perms, .env consistency, gh remote
+ * access). Útil para validar un proyecto específico sin re-correr todos los
+ * checks globales (CLIs, node, sonar, etc.).
+ *
+ * @param {Object} config
+ * @param {{ projectOnly?: boolean }} [opts]
+ * @returns {import("../checks/types.js").Check[]}
+ */
+function buildChecks(config, { projectOnly = false } = {}) {
+  const projectDir = config?.projectDir || process.cwd();
+  if (projectOnly) {
+    return getProjectChecks({ projectDir });
+  }
+  return [
+    ...getSystemChecks(),
+    ...getNodeChecks(),
+    ...getNativeBuildChecks(),
+    ...getHardwareChecks(),
+    ...getDirSetupChecks(),
+    ...getConfigFileChecks(),
+    ...getBinaryChecks(),
+    ...getSonarChecks(),
+    ...getOllamaChecks(),
+    ...getHarnessScorecardChecks(),
+    ...getPortChecks(),
+    ...getTokenChecks(config),
+    ...getMcpHealthChecks(),
+    ...getSkillsChecks(),
+    ...getCiChecks(),
+    ...getRtkChecks(),
+    ...getSqueezrChecks(),
+    ...getAiTrashChecks(),
+    ...getOrphanChecks(),
+    ...getMethodChecks(),
+    ...getQmdChecks(),
+    ...getRagHooksChecks({ projectDir }),
+    ...getProjectChecks({ projectDir }),
+  ];
+}
+
+/**
+ * Interactive terminal confirmation. Returns false when stdin is not a TTY
+ * so non-interactive contexts don't hang forever.
+ *
+ * @param {string} describe
+ * @returns {Promise<boolean>}
+ */
+function confirmViaTty(describe) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      resolve(false);
+      return;
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`? ${describe} [y/N] `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+
+/**
+ * Run the full doctor pipeline without CLI formatting. Consumers that need
+ * the raw report (preflight, status command) should use this.
+ *
+ * @param {{ config: Object, checkOnly?: boolean, yes?: boolean, onConfirm?: Function, logger?: Object }} args
+ * @returns {Promise<import("../checks/types.js").RunReport>}
+ */
+async function runDoctor({ config, checkOnly = false, yes = false, onConfirm, logger, projectOnly = false }) {
+  const checks = buildChecks(config, { projectOnly });
+  return runCheckPipeline(checks, { config }, {
+    mode: checkOnly ? "check-only" : "fix",
+    yes,
+    onConfirm: onConfirm ?? confirmViaTty,
+    logger,
+  });
+}
+
+/**
+ * Legacy shape (backwards-compat for callers that still expect
+ * {name,label,ok,detail,fix}). Kept public because tests and the CI gate
+ * still rely on it.
+ *
+ * @param {{ config: Object }} args
+ */
+export async function runChecks({ config }) {
+  const report = await runDoctor({ config });
+  return toLegacyShape(report);
+}
+
+/**
+ * `kj doctor` CLI entrypoint. Returns the exit code (0 OK, 1 when FAIL).
+ *
+ * @param {{ config: Object, checkOnly?: boolean, yes?: boolean, json?: boolean, verbose?: boolean }} args
+ * @returns {Promise<number>}
+ */
+export async function doctorCommand({ config, checkOnly = false, yes = false, json = false, verbose = false, projectOnly = false }) {
+  const report = await runDoctor({ config, checkOnly, yes, projectOnly });
+  // KJC-TSK-0756 (campo, Pedro): el guarantee level del host actual se
+  // DECLARA en runtime — la doctrina no vive solo en el README.
+  report.guarantee = collectGuaranteeFacts({ projectDir: config?.projectDir || process.cwd() });
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printHuman(report, { verbose });
+    printGuaranteeLevel(report.guarantee);
+  }
+
+  return hasBlockingFailure(report) ? 1 : 0;
+}
+
+// KJC-TSK-0756: la seccion de guarantee level — consola es el medio del
+// doctor (excepcion no-console de commands).
+function printGuaranteeLevel(g) {
+  const mark = (t) => (t.active ? "ACTIVE " : "OFF    ");
+  console.log();
+  console.log(`Guarantee level (host: ${g.host ?? "desconocido"}) — kj jamas finge una supervision que no puede aplicar:`);
+  console.log(`  ${mark(g.tierA)} A tool-time (Sentinel en el turno): ${g.tierA.reason}`);
+  console.log(`  ${mark(g.tierB)} B commit-time (git gates, el SUELO): ${g.tierB.reason}`);
+  console.log(`  ${mark(g.tierC)} C merge-time (re-check en CI): ${g.tierC.reason}`);
+}
+
+function hasBlockingFailure(report) {
+  return report.checks.some((c) => c.status === STATUS.FAIL || c.status === STATUS.TIMEOUT);
+}
+
+function statusIcon(status) {
+  switch (status) {
+    case STATUS.OK: return "OK   ";
+    case STATUS.FIXED: return "FIXED";
+    case STATUS.WARN: return "WARN ";
+    case STATUS.FAIL: return "FAIL ";
+    case STATUS.SKIPPED: return "SKIP ";
+    case STATUS.TIMEOUT: return "TIME ";
+    default: return "?    ";
+  }
+}
+
+// The `kj` binary bundles no toolchain: it orchestrates external tools. So
+// beyond the per-check wall, spell out what is *required* to run kj at all
+// (git + at least one agent CLI) versus what is *optional* (enables extra
+// features). We derive the verdict from the checks already collected rather
+// than re-probing, so it always agrees with the lines printed above.
+function printPrerequisites(report) {
+  const git = report.checks.find((c) => c.name === "git");
+  const agents = report.checks.filter((c) => c.name?.startsWith("agent:"));
+  const okAgent = agents.find((c) => c.status === STATUS.OK);
+  const mark = (ok) => (ok ? "OK" : "MISSING");
+
+  const gitOk = git?.status === STATUS.OK;
+  const agentLabel = okAgent
+    ? `OK (${okAgent.label.replace(/^Agent:\s*/, "")})`
+    : "MISSING — install Claude Code, Codex or Gemini";
+
+  console.log();
+  console.log("Prerequisites (kj orchestrates external tools, it bundles none):");
+  console.log(`  Required: git ${mark(gitOk)}; agent CLI ${agentLabel}`);
+  console.log("  Optional: Docker (local models, SonarQube); Node/npm (helper tools: Squeezr, qmd)");
+}
+
+function printHuman(report, { verbose }) {
+  for (const check of report.checks) {
+    console.log(`${statusIcon(check.status)} ${check.label}: ${check.detail}`);
+    if (check.fix && (check.status === STATUS.FAIL || check.status === STATUS.WARN || verbose)) {
+      console.log(`     -> ${check.fix}`);
+    }
+    if (verbose) {
+      console.log(`     (${check.runMs}ms, strategy=${check.strategy})`);
+    }
+  }
+
+  const s = report.summary;
+  const total = s.ok + s.fixed + s.warn + s.fail + s.skipped + s.timeout;
+  console.log();
+  if (s.fail === 0 && s.timeout === 0) {
+    const label = s.fixed > 0 ? `All checks passed (${s.fixed} auto-fixed)` : "All checks passed.";
+    console.log(label);
+  } else {
+    console.log(
+      `${s.fail + s.timeout} issue(s) found, ${s.fixed} auto-fixed, ${s.warn} warnings, ${s.skipped} skipped out of ${total}.`
+    );
+  }
+  if (Object.keys(report.overrides).length > 0) {
+    console.log(`Runtime overrides applied: ${JSON.stringify(report.overrides)}`);
+  }
+
+  printPrerequisites(report);
+
+  // KJC-TSK v2.18 — if any external audit tool (semgrep, osv-scanner,
+  // lighthouse) reported missing, surface the one-line remediation so
+  // the user doesn't have to dig the fix lines out of the wall of
+  // checks. The audit-tool checks emit names like "audit-tool:semgrep"
+  // and embed { tool, suggested } in `extra` (see binaries.js).
+  const installable = report.checks
+    .filter((c) => c.name?.startsWith("audit-tool:") && c.status === STATUS.WARN && c.extra?.tool)
+    .map((c) => c.extra.tool);
+  if (installable.length > 0) {
+    console.log();
+    const list = installable.join(", ");
+    const only = installable.length === 1 ? ` --only ${installable[0]}` : "";
+    console.log(`Tip: run \`kj install-tools${only}\` to install: ${list}.`);
+  }
+}
+
+export const __test = { printHuman, printPrerequisites };

package/src/commands/env.js

@@ -0,0 +1,207 @@
+/**
+ * `kj env install` (ENV-A1/E1, KJC-TSK-0639/0640) — install/refresh the
+ * Karajan Environment playbook as a managed block in the host agents' rule
+ * files (CLAUDE.md, AGENTS.md), and make its step 1 real: when the project
+ * has no RAG index yet, build it (default ON, `--no-rag` opts out).
+ */
+import { installPlaybook, renderPlaybook } from "../environment/playbook.js";
+import { renderBrief, listBriefs } from "../environment/briefs.js";
+import { existsSync } from "node:fs";
+import { openVecStore, projectSlug, getLastIndexedCommit, dbPath } from "../rag/vec-store.js";
+import { ragIndexCommand } from "./rag.js";
+import { renderPendingBlock, PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
+import { onnxConfig, persistOnnxChoice, resetEmptyStore } from "../rag/onnx-fallback.js";
+import { verifyBoardAccess } from "../environment/board-access.js";
+import { pickStateBackend } from "../environment/board-select.js";
+import { ensurePrivacyList } from "../privacy/onboarding.js";
+import { installProjectMcp } from "../environment/mcp-wiring.js";
+import { createWizard } from "../utils/wizard.js";
+import { hardenCommand } from "./harden.js";
+import { reviewGateCommand } from "./review-gate.js";
+import { join } from "node:path";
+
+function hasRagIndex(config, projectDir) {
+  // KJC-BUG-0128: probing must never CREATE the store — openVecStore runs
+  // the DDL, and a table born at the default dim (768) breaks the ONNX
+  // fallback (384) later. No file → no index, without side effects.
+  if (!existsSync(dbPath())) return false;
+  const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+  try { return Boolean(getLastIndexedCommit(db, projectSlug(projectDir))); }
+  finally { db.close(); }
+}
+
+/**
+ * `kj brief [role]` (AB-C, KJC-TSK-0652) — the distilled method of a role,
+ * for the brain to execute or delegate. No role → list them.
+ */
+export function briefCommand({ config = null, flags = {}, role = null }) {
+  if (!role) {
+    const list = listBriefs();
+    if (flags.json) { console.log(JSON.stringify(list, null, 2)); return list; }
+    console.log("Available role briefs (kj brief <role>):");
+    for (const { role: r, purpose } of list) console.log(`  ${r.padEnd(11)} ${purpose}`);
+    return list;
+  }
+  const text = renderBrief(role, config || {});
+  if (flags.json) { console.log(JSON.stringify({ role, brief: text })); return { role, brief: text }; }
+  console.log(text);
+  return { role, brief: text };
+}
+
+export async function envInstallCommand({ config = null, logger = null, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+
+  // KJC-TSK-0709 — the board is chosen BEFORE the playbook renders (its
+  // tracking line depends on the backend): interactive installs ask when
+  // alternatives are reachable, headless installs name the default. The
+  // choice persists so it is only ever asked once.
+  try {
+    const wizard = process.stdin.isTTY && process.stdout.isTTY ? createWizard() : null;
+    const sel = await pickStateBackend({ projectDir, wizard, isTTY: Boolean(wizard), logger: console });
+    wizard?.close();
+    // The effective backend feeds the render on EVERY non-error path —
+    // chosen, declared-in-file or default — so the playbook never falls
+    // back to hu-board while the selection said otherwise.
+    config = { ...config, state_backend: sel.backend, board: sel.boardName ? { ...config?.board, name: sel.boardName } : config?.board };
+  } catch (err) {
+    console.log(`⚠ board selection failed (${err.message}) — continuing with the configured default`);
+  }
+
+  const result = await installPlaybook({
+    projectDir, target: flags.target || "all",
+    stateBackend: config?.state_backend || "hu-board",
+    boardName: config?.board?.name || null,
+  });
+  console.log(`✓ Karajan playbook installed in: ${result.files.join(", ")}`);
+
+  // KJC-TSK-0711 — RAG as a native tool: agents use what is in their
+  // toolbox, so the official path must be cheaper than the grep shortcut.
+  try {
+    installProjectMcp({ projectDir, logger: console });
+  } catch (err) {
+    console.log(`⚠ could not wire kj-rag-mcp into .mcp.json: ${err.message}`);
+  }
+
+  // KJC-TSK-0685 (user rule): Karajan does not run without a board — it is
+  // what guarantees ordered, card-first work. Verify an OPERATIONAL access
+  // path to the declared backend BEFORE anything else; no path → block
+  // (exit 3) with the exact steps. The playbook stays installed.
+  const access = verifyBoardAccess({ config, projectDir });
+  if (!access.ok) {
+    result.boardError = access.needed.join(" | ");
+    result.exitCode = PENDING_EXIT_CODE;
+    console.log(renderPendingBlock(
+      [{ tool: `${access.name || access.backend} board`, action: "needs-user", reason: `Karajan does not run without a board. To use ${access.name || access.backend}: ${access.needed.join(" ")}` }],
+      { retry: "kj env install" },
+    ));
+    return result;
+  }
+  if (access.backend !== "hu-board") console.log(`✓ board access verified: ${access.via}`);
+
+  // KJC-BUG-0133 — installing IS activating. The setup flow used to order
+  // harden + the verdict gate as TEXT steps the agent runs (or narrates);
+  // a session that skipped them got a decorative method — field case
+  // 2026-08-02: installed karajan, then wrote everything by hand with
+  // nothing to stop it. env install now does them itself, idempotently.
+  if (flags.enforce !== false) {
+    if (!existsSync(join(projectDir, ".git"))) {
+      result.exitCode = PENDING_EXIT_CODE;
+      console.log(renderPendingBlock(
+        [{ tool: "git", action: "needs-user", reason: "the enforcement gates live in git hooks — run `git init` (Karajan's guarantees do not exist without git)" }],
+        { retry: "kj env install" },
+      ));
+      return result;
+    }
+    try {
+      const h = await hardenCommand({ projectDir, logger: console });
+      if (h?.ok === false) throw new Error(h.error || "kj harden failed");
+      await reviewGateCommand({ config, flags: { installGate: true } });
+      console.log("✓ enforcement active: git hooks + cross-AI verdict gate — a commit outside the method is rejected, not narrated");
+    } catch (err) {
+      result.exitCode = PENDING_EXIT_CODE;
+      console.log(renderPendingBlock(
+        [{ tool: "enforcement", action: "needs-user", reason: `hooks/gate could not be installed: ${err.message} — without them the method is narratable` }],
+        { retry: "kj env install" },
+      ));
+      return result;
+    }
+  }
+
+  // ENV-E1: RAG-first — the playbook orders "query the RAG before coding",
+  // so installing the environment guarantees the index exists. KJC-TSK-0659
+  // stop-on-sudo: an index that cannot be built is a BLOCKING condition —
+  // "success" with 0 chunks would leave every future session running the
+  // method against an empty RAG (field-reproduced: 0/727 without Ollama).
+  // The playbook stays installed; the command exits 3 so the driving agent
+  // stops, shows the block, and waits for the user.
+  if (flags.rag !== false) {
+    const provider = config?.rag?.embedder?.provider || "ollama";
+    const blockRag = (why) => {
+      result.ragError = why;
+      result.exitCode = PENDING_EXIT_CODE;
+      const item = provider === "ollama"
+        ? { tool: "ollama", action: "needs-user", reason: `the RAG cannot index: ${why}` }
+        : { tool: `${provider} embedder`, action: "needs-user", reason: `the RAG cannot index: ${why} — check rag.embedder in kj config`, manualUrl: "kj config" };
+      console.log(renderPendingBlock([item], { retry: "kj rag index --with-sources   (then re-run: kj env install)" }));
+    };
+    // KJC-TSK-0683: on limited machines (no Ollama, no Docker) the DEFAULT
+    // provider falls back to the built-in ONNX embedder instead of blocking.
+    // Only for the first index and only when the user didn't pick a provider
+    // explicitly — the election is persisted (dims differ, it must stick).
+    const explicitProvider = Boolean(config?.rag?.embedder?.provider);
+    const tryOnnxFallback = async (why) => {
+      if (explicitProvider) return false;
+      console.log(`⚠ default embedder unavailable (${why}) — trying the built-in ONNX embedder (no install needed)…`);
+      try {
+        // KJC-BUG-0128: an empty store may carry a vec table at the wrong
+        // dim (the old probe created it at 768) — reset it so ONNX (384)
+        // can index. A store with data is never touched.
+        if (!resetEmptyStore()) {
+          console.log("  the vector store already has data at another dimension — not switching automatically");
+          return false;
+        }
+        const totals = await ragIndexCommand({ config: onnxConfig(config), logger, flags: { withSources: true } });
+        if ((totals?.indexed ?? 0) > 0) {
+          const p = await persistOnnxChoice(projectDir);
+          console.log(`✓ RAG indexed with the built-in ONNX embedder — persisted in ${p}`);
+          console.log("  To move to Ollama later: install it, remove the rag.embedder block from .karajan/kj.config.yml,");
+          console.log("  delete the store (~/.karajan/rag.db) and run: kj rag index --with-sources");
+          return true;
+        }
+      } catch (fallbackErr) {
+        console.log(`  ONNX fallback also failed: ${fallbackErr.message}`);
+      }
+      return false;
+    };
+    try {
+      if (hasRagIndex(config, projectDir)) {
+        console.log("✓ RAG index present");
+      } else {
+        console.log("⏳ no RAG index for this project — building it (first time only)…");
+        const totals = await ragIndexCommand({ config, logger, flags: { withSources: true } });
+        if ((totals?.indexed ?? 0) === 0 && (totals?.files ?? 0) > 0) {
+          const why = `0 of ${totals.files} files indexed — is the embedder running?`;
+          if (!(await tryOnnxFallback(why))) blockRag(why);
+        }
+      }
+    } catch (err) {
+      if (!(await tryOnnxFallback(err.message))) blockRag(err.message);
+    }
+  }
+  if (result.exitCode !== PENDING_EXIT_CODE) {
+    // KJC-TSK-0707 (PV-D) — privacy onboarding rides the install: kj asks,
+    // kj writes the denylist. Best-effort (stubbed in the SEA binary).
+    try {
+      const wizard = process.stdin.isTTY && process.stdout.isTTY ? createWizard() : null;
+      await ensurePrivacyList({ wizard, logger: console, isTTY: Boolean(wizard) });
+      wizard?.close();
+    } catch { /* privacy onboarding is best-effort */ }
+    console.log("  The host agent now follows the method: RAG first, TDD, cross-AI review before commit.");
+    // KJC-BUG-0133 (part 2): a mid-session install lands the playbook in
+    // CLAUDE.md, but the running session loaded its context BEFORE — nobody
+    // re-reads it. Print the method so it enters THIS conversation now.
+    console.log("\n— The Karajan method below is IN EFFECT from this very message. If your session started before this install, apply it from now on:\n");
+    console.log(renderPlaybook({ stateBackend: config?.state_backend || "hu-board", boardName: config?.board?.name || null }));
+  }
+  return result;
+}