karajan-code 4.10.0 → 4.12.0

package/README.md

@@ -24,12 +24,15 @@
 
 Your AI agent (Claude Code, Codex, Gemini CLI, Cursor…) writes the code. **Karajan governs how it happens**: it installs a method your agent follows on every task, and enforces it with git gates that make a false green structurally impossible.
 
-- **RAG before assuming** — `kj rag query` answers what your codebase does; no agent guesses. Works out of the box: local Ollama, or the built-in ONNX embedder when nothing can be installed; cloud embedders require an explicit sensitivity declaration and PII-redact every chunk.
+- **RAG before assuming** — `kj rag query` answers what your codebase does; no agent guesses. The install wires it as a native MCP tool (`kj_rag_query`) so querying the index is the agent's cheapest path. Works out of the box: local Ollama, or the built-in ONNX embedder when nothing can be installed; cloud embedders require an explicit sensitivity declaration and PII-redact every chunk. A distilled engineering canon rides along: `kj rag query --library` serves pattern cards (when it applies, when it does NOT, the canonical citation) so plans name a greenfield alternative instead of following the legacy line by inertia.
 - **Card first, on YOUR board** — every piece of work is tracked before it starts: kj's HU Board (`kj hu add|move|list`), the Planning Game, or the board the project already uses (Linear, Trello, Jira, GitHub Issues) via your agent's own MCP/tools. Declared, verified at install, never optional — Karajan does not run without a board. ADRs live in git (`kj adr add|list`).
 - **Tests prove behavior** — the failing test exists first; the suite is never left red.
 - **Deterministic first, then cross-AI review** — `kj review --staged` runs SonarQube on the changed files before any AI opinion (BLOCKER/CRITICAL reject on the spot), then binds a verdict from a *different* AI to the sha256 of the exact diff — stamped with the workspace it ran from. Without an approved verdict, **the commit does not enter** (pre-commit gate).
 - **A third AI arbitrates disputes** — `kj solomon` rules when brain and reviewer disagree. Security findings are never overridable — not even by arbitration.
 - **Branch first, lanes for parallel work** — the base branch only moves through atomic PRs; `kj worktree start|list|done` gives each concurrent task its own isolated lane.
+- **Least privilege for agents** — spawned agent subprocesses receive an env allowlist (their own CLI's auth, never your cloud keys or registry tokens), and `kj check` inventories every MCP the project can reach, flagging what appeared since the last check. Sensitive-surface tasks self-invoke `kj audit --security` — a zero-token pass (prompt-injection over the agent-context files + OSV + Semgrep + Sonar) — and remediate before review.
+- **Nothing personal ships** — every outbound boundary audits before it leaves the machine: the pre-commit rejects a staged diff carrying your denylisted personal data, hardcoded platform tokens (`ghp_`, `sk-`, `AKIA`…) block outright, `verify-pack`-style tarball scans guard the publish, and `kj privacy scan <dir>` audits any build output. Your denylist lives in `~/.karajan/privacy.yml` — the install asks and writes it for you.
+- **Installing IS activating** — `kj env install` performs the enforcement itself (git hooks, verdict gate, tool gate) instead of trusting the agent to run setup steps, and ends by printing the method into the very conversation that installed it. A commit outside the method is rejected, not narrated.
 
 This repo runs under its own environment: every commit to karajan-code carries a cross-AI verdict.
 

package/docs/README.es.md

@@ -16,12 +16,15 @@
 
 Tu agente de IA (Claude Code, Codex, Gemini CLI, Cursor…) escribe el código. **Karajan gobierna cómo ocurre**: instala un método que tu agente sigue en cada tarea y lo hace cumplir con gates de git que hacen el falso verde estructuralmente imposible.
 
-- **RAG antes de suponer** — `kj rag query` responde qué hace tu código; ningún agente adivina. Funciona de serie: Ollama local, o el embedder ONNX integrado cuando no se puede instalar nada; los embedders cloud exigen declarar la sensibilidad y redactan PII de cada chunk.
+- **RAG antes de suponer** — `kj rag query` responde qué hace tu código; ningún agente adivina. La instalación lo cablea como herramienta MCP nativa (`kj_rag_query`), de modo que consultar el índice sea el camino más barato del agente. Funciona de serie: Ollama local, o el embedder ONNX integrado cuando no se puede instalar nada; los embedders cloud exigen declarar la sensibilidad y redactan PII de cada chunk. Y viaja con un canon de ingeniería destilado: `kj rag query --library` sirve fichas de patrón (cuándo aplica, cuándo NO, la cita canónica) para que los planes nombren una alternativa greenfield en vez de seguir la línea del legacy por inercia.
 - **Card primero, en TU board** — todo trabajo se registra antes de empezar: el HU Board de kj (`kj hu add|move|list`), el Planning Game, o el board que el proyecto ya use (Linear, Trello, Jira, GitHub Issues) vía los MCP/tools de tu agente. Declarado, verificado en la instalación, jamás opcional — Karajan no funciona sin board. Los ADRs viven en git (`kj adr add|list`).
 - **Los tests prueban el comportamiento** — el test que falla existe primero; la suite nunca se queda en rojo.
 - **Determinista primero, luego revisión IA-cruzada** — `kj review --staged` pasa SonarQube sobre los ficheros cambiados antes de cualquier opinión de IA (BLOCKER/CRITICAL rechazan en el acto), y después liga el veredicto de una IA *distinta* al sha256 del diff exacto — estampado con el workspace desde el que corrió. Sin veredicto aprobado, **el commit no entra** (gate pre-commit).
 - **Una tercera IA arbitra las disputas** — `kj solomon` decide cuando brain y reviewer discrepan. Los hallazgos de seguridad no los anula nadie — ni siquiera el arbitraje.
 - **Rama primero, carriles para el paralelo** — la rama base solo se mueve por PRs atómicas; `kj worktree start|list|done` da a cada tarea concurrente su carril aislado.
+- **Mínimo privilegio para agentes** — los subprocesos de agente reciben un allowlist de entorno (la auth de su propio CLI, jamás tus claves cloud ni tokens de registro), y `kj check` inventaría cada MCP alcanzable del proyecto marcando lo aparecido desde el último check. Las tareas con superficie sensible se auto-invocan `kj audit --security` — pasada de cero tokens (prompt-injection sobre los ficheros de contexto del agente + OSV + Semgrep + Sonar) — y remedian antes del review.
+- **Nada personal se publica** — cada boundary de salida se audita antes de dejar la máquina: el pre-commit rechaza un diff con tus datos vetados, los tokens de plataforma hardcodeados (`ghp_`, `sk-`, `AKIA`…) bloquean directamente, el scan del tarball guarda el publish, y `kj privacy scan <dir>` audita cualquier build. Tu denylist vive en `~/.karajan/privacy.yml` — la instalación pregunta y la escribe por ti.
+- **Instalar ES activar** — `kj env install` ejecuta él mismo el enforcement (hooks de git, gate de veredicto, tool gate) en vez de confiar en que el agente corra pasos de setup, y termina imprimiendo el método en la propia conversación que instaló. Un commit fuera del método se rechaza, no se narra.
 
 Este repo corre bajo su propio entorno: cada commit de karajan-code lleva un veredicto de IA cruzada.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.10.0",
+  "version": "4.12.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/checks/release-check.js

@@ -0,0 +1,109 @@
+/**
+ * release-check (KJC-TSK-0712) — the release checklist made verifiable:
+ * a note loses salience; a check fails RED with the exact list. Generics
+ * fit any karajan project; each project extends via `release_check.items`
+ * (file_contains with {version}, or command with exit-0 semantics).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { runCommand } from "../utils/process.js";
+import { loadPrivacyList, scanPaths } from "../privacy/scan.js";
+
+const semverCmp = (a, b) => {
+  const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  return 0;
+};
+
+async function genericChecks(projectDir) {
+  const checks = [];
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(pkgPath)) {
+    checks.push({ name: "manifest", ok: true, detail: "no package.json — generic version checks skipped (declared items still run)" });
+    return { checks, version: null, pkg: null };
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const version = pkg.version;
+  checks.push({ name: "manifest", ok: Boolean(version), detail: version ? `version ${version}` : "package.json has no version" });
+
+  const clPath = join(projectDir, "CHANGELOG.md");
+  if (!existsSync(clPath)) {
+    checks.push({ name: "changelog-current", ok: false, detail: "no CHANGELOG.md — the release story must exist before the release" });
+  } else {
+    const cl = readFileSync(clPath, "utf8");
+    const topVersioned = (cl.match(/^## \[(\d+\.\d+\.\d+)\]/m) || [])[1] || null;
+    // Content still sitting under [Unreleased] means unpromoted entries —
+    // the tarball would ship changes its release notes do not tell.
+    const afterUnreleased = cl.split(/^## \[Unreleased\]\s*$/m)[1] ?? "";
+    const unreleasedBody = afterUnreleased.split(/^## \[/m)[0] ?? "";
+    const pending = /\S/.test(unreleasedBody);
+    const ok = topVersioned === version && !pending;
+    checks.push({
+      name: "changelog-current",
+      ok,
+      detail: ok
+        ? `top section is [${version}], Unreleased empty`
+        : pending
+          ? `[Unreleased] still carries content — promote it into [${version}] before releasing`
+          : `top CHANGELOG section is [${topVersioned ?? "none"}] but the manifest says ${version} — promote Unreleased before releasing`,
+    });
+  }
+
+  const tagsOut = await runCommand("git", ["-C", projectDir, "tag", "--list", "v[0-9]*"]);
+  const tags = (tagsOut.stdout || "").split("\n").map((t) => t.trim().replace(/^v/, "")).filter((t) => /^\d+\.\d+\.\d+$/.test(t));
+  const ahead = version ? tags.filter((t) => semverCmp(t, version) > 0) : [];
+  checks.push({
+    name: "tags",
+    ok: ahead.length === 0,
+    detail: ahead.length ? `tag(s) ahead of the manifest exist: v${ahead.join(", v")}` : (tags.includes(version) ? `v${version} already tagged` : `tag v${version} pending (created after publish)`),
+  });
+  return { checks, version, pkg };
+}
+
+async function packPrivacyCheck(projectDir, pkg) {
+  // Every non-private named package is publishable (exports/files-based
+  // packages carry no main/bin) — they all get the scan.
+  if (!pkg || pkg.private === true || !pkg.name || !pkg.version) return null;
+  try {
+    const out = await runCommand("npm", ["pack", "--dry-run", "--json", "--silent"], { cwd: projectDir });
+    const files = (JSON.parse(out.stdout || "[]")[0]?.files || []).map((f) => join(projectDir, f.path));
+    const blocks = scanPaths(files, { list: loadPrivacyList() }).filter((f) => f.severity === "block");
+    return { name: "pack-privacy", ok: blocks.length === 0, detail: blocks.length ? `${blocks.length} personal-data/secret hit(s) in the publishable files` : `${files.length} publishable file(s) clean` };
+  } catch (err) {
+    return { name: "pack-privacy", ok: false, detail: `npm pack --dry-run failed: ${err.message}` };
+  }
+}
+
+async function declaredItems(projectDir, config, version) {
+  const items = config?.release_check?.items;
+  if (!Array.isArray(items)) return [];
+  const checks = [];
+  for (const item of items) {
+    const name = item?.name || "unnamed item";
+    if (item?.file_contains?.path && item.file_contains.pattern != null) {
+      const p = isAbsolute(item.file_contains.path) ? item.file_contains.path : join(projectDir, item.file_contains.path);
+      const needle = String(item.file_contains.pattern).replaceAll("{version}", version ?? "");
+      const ok = existsSync(p) && readFileSync(p, "utf8").includes(needle);
+      checks.push({ name, ok, detail: ok ? `"${needle}" found in ${item.file_contains.path}` : `"${needle}" NOT found in ${item.file_contains.path}` });
+    } else if (item?.command) {
+      try {
+        const res = await runCommand("sh", ["-c", String(item.command).replaceAll("{version}", version ?? "")], { cwd: projectDir });
+        checks.push({ name, ok: res.exitCode === 0, detail: res.exitCode === 0 ? "command exited 0" : `command exited ${res.exitCode}` });
+      } catch (err) {
+        checks.push({ name, ok: false, detail: `command failed to run: ${err.message}` });
+      }
+    } else {
+      checks.push({ name, ok: false, detail: "unknown item shape — use file_contains {path, pattern} or command" });
+    }
+  }
+  return checks;
+}
+
+export async function runReleaseCheck({ projectDir = process.cwd(), config = {} } = {}) {
+  const { checks, version, pkg } = await genericChecks(projectDir);
+  const pack = await packPrivacyCheck(projectDir, pkg);
+  if (pack) checks.push(pack);
+  checks.push(...await declaredItems(projectDir, config, version));
+  return { ok: checks.every((c) => c.ok), version, checks };
+}

package/src/cli/advanced-commands.js

@@ -30,7 +30,7 @@ export const ADVANCED_GROUPS = [
   { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan"] },
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
-  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy"] },
+  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release"] },
   { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },

package/src/cli/register-meta.js

@@ -20,6 +20,7 @@ import { mutateCommand } from "../commands/mutate.js";
 import { hardenCommand } from "../commands/harden.js";
 import { telemetryPreviewCommand, telemetryStatusCommand } from "../commands/telemetry.js";
 import { envInstallCommand, briefCommand } from "../commands/env.js";
+import { runReleaseCheck } from "../checks/release-check.js";
 import { agentRunCommand } from "../commands/agent-run.js";
 import { reportIssueCommand } from "../commands/report-issue.js";
 import { huCommand } from "../commands/hu.js";
@@ -262,6 +263,23 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-0712 — memory is the reminder, the check is the guarantee.
+  const release = program.command("release").description("Release ceremony helpers");
+  release.command("check")
+    .description("Verify the release checklist deterministically (manifest vs CHANGELOG vs tags, privacy scan of publishable files, plus the project's release_check.items); exit 1 lists exactly what is missing")
+    .option("--json", "Machine-readable result")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "release-check", flags, async ({ config }) => {
+        const res = await runReleaseCheck({ projectDir: config?.projectDir || process.cwd(), config });
+        if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
+        else {
+          for (const c of res.checks) console.log(`  ${c.ok ? "✓" : "✗"} ${c.name}: ${c.detail}`);
+          console.log(res.ok ? `release check: ready to release ${res.version ?? ""}`.trim() : "release check: NOT ready — fix the red items first");
+        }
+        process.exitCode = res.ok ? 0 : 1;
+      });
+    });
+
   // KJC-TSK-0704 — the outbound privacy boundary: audit before anything ships.
   const privacy = program.command("privacy").description("Personal-data (PII) auditing of outbound boundaries: staged diffs, build outputs, docs trees");
   privacy.command("scan [paths...]")

package/src/commands/env.js

@@ -12,7 +12,9 @@ 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";
@@ -48,6 +50,23 @@ export function briefCommand({ config = null, flags = {}, role = null }) {
 
 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",
@@ -55,6 +74,14 @@ export async function envInstallCommand({ config = null, logger = null, flags =
   });
   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

package/src/config/schema.js

@@ -238,8 +238,10 @@ export const ConfigSchema = v.looseObject({
   // ENV-D1 (KJC-TSK-0642): where work items live — the integrated HU Board
   // or the user's Planning Game. The v4 playbook renders per backend.
   state_backend: v.optional(v.picklist(
-    ["hu-board", "planning-game"],
-    "state_backend must be \"hu-board\" or \"planning-game\""
+    // KJC-TSK-0709 caught the drift: "external" shipped in v4.5.0 (any
+    // board via the agent's own MCP/tools) but this picklist never learned it.
+    ["hu-board", "planning-game", "external"],
+    "state_backend must be \"hu-board\", \"planning-game\" or \"external\""
   )),
   review_rules: v.optional(v.string()),
   coder_rules: v.optional(v.string()),

package/src/environment/board-access.js

@@ -42,6 +42,25 @@ function mcpConfigsMention(slug, projectDir, home) {
   return null;
 }
 
+/**
+ * Boards reachable from this machine (KJC-TSK-0709): the bundled HU Board
+ * always; planning-game / external candidates when their MCP appears in a
+ * host config or a conventional token is exported. Presence-based, like
+ * verifyBoardAccess — an OPTION list, not a connectivity check.
+ */
+export function detectAvailableBoards({ projectDir = process.cwd(), env = process.env, home = os.homedir() } = {}) {
+  const boards = [{ value: "hu-board", label: "HU Board (bundled, zero setup)" }];
+  if (mcpConfigsMention("planning-game", projectDir, home)) {
+    boards.push({ value: "planning-game", label: "Planning Game (MCP detected)" });
+  }
+  for (const [slug, envs] of Object.entries(TOKEN_CONVENTIONS)) {
+    const token = envs.find((k) => env[k]);
+    if (token) boards.push({ value: `external:${slug}`, label: `${slug} (token ${token})` });
+    else if (mcpConfigsMention(slug, projectDir, home)) boards.push({ value: `external:${slug}`, label: `${slug} (MCP detected)` });
+  }
+  return boards;
+}
+
 export function verifyBoardAccess({ config = {}, projectDir = process.cwd(), env = process.env, home = os.homedir() } = {}) {
   const backend = config.state_backend || "hu-board";
 

package/src/environment/board-select.js

@@ -0,0 +1,58 @@
+/**
+ * board-select (KJC-TSK-0709) — never hu-board silently when alternatives
+ * are reachable. Field case 2026-08-02: an install defaulted to hu-board
+ * with the user's Planning Game MCP sitting configured and detectable.
+ * Interactive installs ASK and persist the choice; headless installs name
+ * the default and the exact line to change it. Declared = never asked.
+ */
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { parse as parseYaml, parseDocument } from "yaml";
+import { detectAvailableBoards } from "./board-access.js";
+import { getConfigPath, getProjectConfigPath } from "../config.js";
+
+// "Declared" means the USER wrote state_backend in a config FILE — the
+// merged config object always carries the hu-board default (defaults.js),
+// so it can never tell a choice from a fallback.
+async function declaredStateBackend(projectDir) {
+  for (const p of [getProjectConfigPath(projectDir), getConfigPath()]) {
+    try {
+      const raw = parseYaml(await fs.readFile(p, "utf8")) || {};
+      if (raw.state_backend) return { backend: raw.state_backend, boardName: raw.board?.name || null };
+    } catch { /* missing or unreadable — keep looking */ }
+  }
+  return null;
+}
+
+async function persistStateBackend(projectDir, backend, boardName) {
+  const configPath = getProjectConfigPath(projectDir);
+  let source = "";
+  try { source = await fs.readFile(configPath, "utf8"); } catch { /* no config yet — create it */ }
+  const doc = parseDocument(source || "{}");
+  doc.setIn(["state_backend"], backend);
+  if (boardName) doc.setIn(["board", "name"], boardName);
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, doc.toString(), "utf8");
+  return configPath;
+}
+
+export async function pickStateBackend({ projectDir = process.cwd(), home = os.homedir(), env = process.env, wizard = null, isTTY = false, logger = console } = {}) {
+  const declared = await declaredStateBackend(projectDir);
+  if (declared) return { ...declared, source: "declared" };
+  const boards = detectAvailableBoards({ projectDir, home, env });
+  if (boards.length <= 1) return { backend: "hu-board", boardName: null, source: "default" };
+  if (!wizard || !isTTY) {
+    logger.info?.(`⚠ board: defaulting to the bundled HU Board, but this machine can reach: ${boards.slice(1).map((b) => b.label).join(", ")} — switch with \`state_backend: planning-game\` (or \`external\` + board.name) in .karajan/kj.config.yml and re-run kj env install`);
+    return { backend: "hu-board", boardName: null, source: "default-informed" };
+  }
+  logger.info?.("Karajan needs a board (there is no 'none') — pick where card-first work lives:");
+  const value = await wizard.select("Which board governs this project?", boards);
+  const external = value.startsWith("external:");
+  const backend = external ? "external" : value;
+  const boardName = external ? value.slice("external:".length) : null;
+  await persistStateBackend(projectDir, backend, boardName);
+  logger.info?.(`✓ board: ${backend}${boardName ? ` (${boardName})` : ""} — persisted in .karajan/kj.config.yml`);
+  return { backend, boardName, source: "chosen" };
+}

package/src/environment/mcp-wiring.js

@@ -0,0 +1,44 @@
+/**
+ * mcp-wiring — RAG as a NATIVE tool (KJC-TSK-0711). Field case 2026-08-03:
+ * agents in karajan projects grep code by hand because the RAG is only "a
+ * Bash command a text line told them about". Agents use the tools in their
+ * toolbox, so env install wires kj's RAG-only MCP server (`kj-rag-mcp`,
+ * ships with the package) into the project's `.mcp.json` — the official
+ * path must be cheaper than the shortcut. Merge preserves the user's
+ * entries; invalid JSON is left untouched (preserve, never clobber).
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function installProjectMcp({ projectDir = process.cwd(), logger = console } = {}) {
+  const mcpPath = join(projectDir, ".mcp.json");
+  let cfg = {};
+  if (existsSync(mcpPath)) {
+    try {
+      cfg = JSON.parse(readFileSync(mcpPath, "utf8"));
+    } catch {
+      logger.warn?.(`kj env: ${mcpPath} is not valid JSON — leaving it untouched (wire kj-rag-mcp manually for native RAG queries)`);
+      return { wired: false, reason: "invalid-json" };
+    }
+  }
+  if (cfg.mcpServers && typeof cfg.mcpServers !== "object") {
+    logger.warn?.(`kj env: ${mcpPath} has a non-object mcpServers — leaving it untouched`);
+    return { wired: false, reason: "unexpected-shape" };
+  }
+  cfg.mcpServers = cfg.mcpServers || {};
+  // Wired = the LAUNCH SPEC runs kj-rag-mcp (command or an arg, so `npx
+  // kj-rag-mcp` and absolute paths count) — never env/description fields.
+  const launchesRagMcp = (s) =>
+    Boolean(s) && typeof s === "object" && (
+      (typeof s.command === "string" && s.command.includes("kj-rag-mcp")) ||
+      (Array.isArray(s.args) && s.args.some((a) => typeof a === "string" && a.includes("kj-rag-mcp")))
+    );
+  const present = Object.values(cfg.mcpServers).some(launchesRagMcp);
+  if (!present) {
+    cfg.mcpServers["kj-rag"] = { command: "kj-rag-mcp", args: [] };
+    writeFileSync(mcpPath, `${JSON.stringify(cfg, null, 2)}\n`);
+    logger.info?.("✓ kj_rag_query wired as a NATIVE tool (.mcp.json → kj-rag-mcp): querying the RAG is now the agent's cheapest path");
+  }
+  return { wired: true, added: !present };
+}

package/src/environment/playbook.js

@@ -57,7 +57,8 @@ carries a cross-AI verdict.
 Invariants (the git gates enforce these — they are not suggestions):
 
 - The project RAG answers before you assume: \`kj rag query\` — never guess
-  what the codebase does.
+  what the codebase does. In MCP hosts the same index is the native
+  \`kj_rag_query\` tool: reach for it before grepping by hand.
 - ${trackingLine(stateBackend, boardName)}
 - Tests prove behavior: the failing test exists first (TDD), and the suite
   is never left red.