@karajan-family/code 4.21.0

package/src/environment/board-access.js

@@ -0,0 +1,97 @@
+/**
+ * Board access verification (KJC-TSK-0685). User rule: Karajan does not
+ * run without a board — it is what guarantees ordered, card-first work and
+ * meaningful lanes. There is NO "none". init/env-install verify an
+ * OPERATIONAL access path to the declared backend:
+ *   - hu-board       → always ok (ships inside the kj tarball).
+ *   - planning-game  → its MCP appears in a host agent config.
+ *   - external       → the named board's MCP appears in a host agent
+ *                      config, OR an API token is exported (conventional
+ *                      env var, or the one declared in board.token_env).
+ * Detection is presence-based and format-agnostic (the MCP config files
+ * are scanned as text) — v1 verifies a path exists, not connectivity.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const TOKEN_CONVENTIONS = {
+  linear: ["LINEAR_API_KEY"],
+  trello: ["TRELLO_TOKEN", "TRELLO_API_KEY"],
+  jira: ["JIRA_API_TOKEN"],
+  github: ["GITHUB_TOKEN", "GH_TOKEN"],
+  asana: ["ASANA_ACCESS_TOKEN"],
+};
+
+function mcpConfigPaths(projectDir, home) {
+  return [
+    path.join(projectDir, ".mcp.json"),
+    path.join(home, ".claude.json"),
+    path.join(home, ".codex", "config.toml"),
+    path.join(home, ".gemini", "settings.json"),
+  ];
+}
+
+function mcpConfigsMention(slug, projectDir, home) {
+  const needle = slug.toLowerCase();
+  for (const p of mcpConfigPaths(projectDir, home)) {
+    try {
+      if (existsSync(p) && readFileSync(p, "utf8").toLowerCase().includes(needle)) return p;
+    } catch { /* unreadable config — keep looking */ }
+  }
+  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";
+
+  if (backend === "planning-game") {
+    const hit = mcpConfigsMention("planning-game", projectDir, home);
+    if (hit) return { ok: true, backend, via: `planning-game MCP (${hit})` };
+    return {
+      ok: false, backend,
+      needed: ["configure the planning-game MCP in your host agent (project .mcp.json or the agent's global config)"],
+    };
+  }
+
+  if (backend === "external") {
+    const name = String(config.board?.name || "").trim();
+    if (!name) return { ok: false, backend, needed: ["declare board.name in kj.config.yml (e.g. Linear, Trello, Jira, GitHub Issues)"] };
+    const slug = name.toLowerCase().split(/\s+/)[0];
+    const hit = mcpConfigsMention(slug, projectDir, home);
+    if (hit) return { ok: true, backend, via: `${name} MCP detected (${hit})` };
+    const tokenEnvs = config.board?.token_env ? [config.board.token_env] : (TOKEN_CONVENTIONS[slug] || []);
+    const found = tokenEnvs.find((k) => env[k]);
+    if (found) return { ok: true, backend, via: `API token ${found}` };
+    return {
+      ok: false, backend, name,
+      needed: [
+        `configure the ${name} MCP in your host agent (project .mcp.json or the agent's global config), or`,
+        tokenEnvs.length > 0
+          ? `export an API token: ${tokenEnvs.join(" or ")}`
+          : "declare board.token_env in kj.config.yml and export that variable",
+      ],
+    };
+  }
+
+  return { ok: true, backend: "hu-board", via: "bundled HU Board" };
+}

package/src/environment/board-select.js

@@ -0,0 +1,59 @@
+/**
+ * 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);
+  const suffix = boardName ? ` (${boardName})` : "";
+  logger.info?.(`✓ board: ${backend}${suffix} — persisted in .karajan/kj.config.yml`);
+  return { backend, boardName, source: "chosen" };
+}

package/src/environment/briefs.js

@@ -0,0 +1,129 @@
+/**
+ * Role briefs (AB-C, KJC-TSK-0652; outcome-first rewrite AB-C2,
+ * KJC-TSK-0653) — the method of each role, exposed to the brain via
+ * `kj brief <role>`.
+ *
+ * Format is Mission + Invariants + Deliverable, never step scripts:
+ * frontier models choose better paths than a script would force, but they
+ * need the hard limits explicit. The real guarantee lives in the git
+ * gates, not in this text. Subprocess prompts stay in headless.
+ */
+
+const brief = (title, mission, invariants, deliverable) => [
+  `# ${title} brief`, "",
+  `Mission: ${mission}`, "",
+  "Invariants:",
+  ...invariants.map((i) => `- ${i}`), "",
+  `Deliverable: ${deliverable}`,
+].join("\n");
+
+const B = {
+  triage: {
+    purpose: "Size the task before touching anything",
+    render: () => brief("Triage",
+      "before any code exists, the task has a type (sw|infra|doc|add-tests|refactor), an honest size, its risk surfaces named (auth, persistence, external I/O, money, PII), and a DONE-statement that is falsifiable.",
+      [
+        "The RAG answers before you assume (`kj rag query`) — never size from guesses.",
+        "A task too big for one ~150-net-line PR is split into HUs BEFORE coding starts.",
+      ],
+      "type, size, risks, done-statement — or the HU split."),
+  },
+  planner: {
+    purpose: "Turn the task into an ordered, committable plan",
+    render: () => brief("Planner",
+      "the smallest ordered plan whose steps each fit one commit, name their files, and reach the done-statement — with an explicit out-of-scope list.",
+      [
+        "Behavior changes carry their test in the same step.",
+        "Data-model or API changes never share a step with anything else.",
+        "No PR beyond ~150 net lines — partition upfront, not at the gate.",
+        "Non-trivial task? Name at least two approaches — one as if the codebase didn't exist — and say why the winner won.",
+      ],
+      "numbered-free plan: steps {description, files}, risks, out-of-scope."),
+  },
+  researcher: {
+    purpose: "Ground the task in how the codebase actually works",
+    render: () => brief("Researcher",
+      "the design starts from how this codebase actually does things: the existing pattern for this kind of change is found and mimicked, the load-bearing files and the tests that pin them are known.",
+      [
+        "Facts carry file:line references — a claim without one is a guess.",
+        "Unknowns are listed explicitly, never papered over.",
+      ],
+      "grounded facts with references + the open unknowns."),
+  },
+  architect: {
+    purpose: "Decide structure before code when the change is cross-cutting",
+    render: () => brief("Architect",
+      "for medium/complex changes, one design is chosen over named alternatives, existing ADRs and module boundaries are respected, and any data-model/API change has a migration and compatibility story.",
+      [
+        "Check the ADRs before deciding — never against an accepted one.",
+        "Prefer the design that deletes code over the one that adds layers.",
+        "One alternative answers: what would you build as if the codebase didn't exist? Picking the legacy-shaped path is fine — picking it by inertia is not.",
+        "Ground that alternative in the canon: `kj rag query --library \"<problem signature>\"` serves distilled pattern cards with when-NOT-to-apply and citations.",
+      ],
+      "chosen design, discarded alternatives with reasons, affected boundaries."),
+  },
+  tester: {
+    purpose: "Prove the change does what DONE says",
+    render: (config) => {
+      const tdd = config?.development?.methodology !== "standard";
+      return brief("Tester",
+        "every behavior change is pinned by a test that fails without it, sad paths included (invalid input, empty state, boundaries), and the FULL suite is green.",
+        [
+          ...(tdd ? ["TDD is ON: the failing test exists FIRST, then the code."] : []),
+          "The suite is never left red, and never goes green by deleting or skipping tests.",
+          ...(config?.method_gates?.mutation
+            ? ["Green is not proof: run `kj mutate --since <base>` after the suite passes and BEFORE review — kill surviving mutants (weak asserts) first."]
+            : []),
+        ],
+        "green suite + the list of new/changed tests and what each one pins.");
+    },
+  },
+  security: {
+    purpose: "The security pass the brain absorbs — non-negotiable",
+    render: () => brief("Security",
+      "when you finish, no user-controlled data reaches HTML, shell, SQL or file paths unsanitized; no secret, key or credential lives in code, config, logs or commits; and every new endpoint/action checks identity AND permission.",
+      [
+        "These findings are never overridable — not even by Solomon arbitration.",
+        "PII is never logged; new dependencies need a reason and a pinned version.",
+        "Sensitive surface (auth, user input, secrets, network, deps)? Self-invoke `kj audit --security` — deterministic, zero tokens: prompt-injection over the agent-context files + OSV + Semgrep + Sonar — and remediate the findings before requesting review.",
+      ],
+      "findings with severity, category and file:line — or an explicit 'no security surface touched'."),
+  },
+  board: {
+    purpose: "What the HU Board is and how to act on it without breaking it",
+    render: () => brief("Board",
+      "the HU Board is the permanent record of work: every card traces to who created it and what happened to it — a dashboard warning is fixed with the command it names, never by rebuilding the board.",
+      [
+        "Before `kj hu add`, ALWAYS run `kj hu list`: if a card already covers the work (same scope, any plan), work THAT card instead of creating a twin.",
+        "Cards are NEVER deleted or recreated — not to fix warnings, not to tidy up. Discard = `kj hu move <id> skipped` (archived, history kept).",
+        "States move only via `kj hu move <id> <pending|running|done|failed|skipped>`.",
+        "A duplicate short_id or title means the card already exists: update that card, never add a twin.",
+        "A warning is information, not damage: run the command it names; if it looks like a kj bug, `kj report-issue` — never work around it by destroying state.",
+      ],
+      "the board reflects reality: the same cards before and after your action, with truthful states and provenance intact."),
+  },
+  audit: {
+    purpose: "Final look before shipping — does the whole thing hold?",
+    render: () => brief("Audit",
+      "the done-statement from triage is literally true, the diff carries no debug leftovers or card-less TODOs, user-visible behavior changes have their minimal doc, and suite + lint + review gate are verified green.",
+      [
+        "Verified means you ran it — never assumed from an earlier state.",
+        "There is no 'ship with caveats': it ships or it has a must-fix list.",
+      ],
+      "SHIP, or the concrete must-fix list."),
+  },
+};
+
+export const BRIEF_ROLES = Object.keys(B);
+
+export function listBriefs() {
+  return BRIEF_ROLES.map((role) => ({ role, purpose: B[role].purpose }));
+}
+
+export function renderBrief(role, config = {}) {
+  const entry = B[role];
+  if (!entry) {
+    throw new Error(`unknown role "${role}" — available: ${BRIEF_ROLES.join(", ")}`);
+  }
+  return entry.render(config);
+}

package/src/environment/issue-report.js

@@ -0,0 +1,72 @@
+/**
+ * Issue reporting core (AB-F, KJC-TSK-0655) — the self-healing loop: any
+ * user's brain diagnoses a kj friction and reports it to the public repo,
+ * so field feedback reaches the maintainer's board without a human relay.
+ *
+ * A public issue is a privacy boundary. sanitize() strips home paths,
+ * usernames and emails; the composer only ever includes what the brain
+ * explicitly passed (command, error, description) plus kj/node/platform
+ * metadata — never project code.
+ */
+
+export const REPO = "manufosela/karajan-code";
+
+export function sanitize(text) {
+  return String(text || "")
+    // any /home/<user>/ or /Users/<user>/ prefix collapses to ~/
+    .replaceAll(/\/(?:home|Users)\/[^/\s]+/g, "~")
+    // emails never belong in a public issue
+    .replaceAll(/[\w.+-]+@[\w-]+\.[\w.]+/g, "[redacted-email]");
+}
+
+export function composeIssue({ title, description = "", command = "", error = "", env = {} }) {
+  const body = [
+    sanitize(description),
+    command ? `\n**Command:** \`${sanitize(command)}\`` : "",
+    error ? `\n**Error:**\n\`\`\`\n${sanitize(error)}\n\`\`\`` : "",
+    "\n**Environment:**",
+    `- kj ${env.kjVersion || "unknown"}`,
+    `- node ${env.nodeVersion || "unknown"}`,
+    `- ${env.platform || "unknown"}`,
+    "\n---",
+    "_Reported via `kj report-issue` (sanitized: no project code, paths or personal data)._",
+  ].filter(Boolean).join("\n");
+  return { title: sanitize(title), body };
+}
+
+const STOPWORDS = new Set(["the", "a", "an", "is", "are", "from", "with", "for", "and", "not", "kj", "karajan"]);
+
+function meaningfulWords(title) {
+  return title.toLowerCase().split(/[^a-z0-9-]+/)
+    .filter((w) => w.length > 3 && !STOPWORDS.has(w));
+}
+
+/**
+ * Look for open issues that share meaningful title words (≥2 overlaps, or
+ * 1 when the title is short). Read-only public API — no auth needed. Any
+ * failure degrades to [] : dedup must never block reporting.
+ */
+export async function findSimilarIssues(title, { fetchFn = globalThis.fetch } = {}) {
+  try {
+    const res = await fetchFn(`https://api.github.com/repos/${REPO}/issues?state=open&per_page=100`, {
+      headers: { accept: "application/vnd.github+json" },
+    });
+    if (!res.ok) return [];
+    const issues = await res.json();
+    const words = meaningfulWords(title);
+    const needed = Math.min(2, Math.max(1, words.length));
+    return issues.filter((issue) => {
+      const theirs = new Set(meaningfulWords(issue.title || ""));
+      const overlap = words.filter((w) => theirs.has(w)).length;
+      return overlap >= needed;
+    }).map(({ number, title: t, html_url }) => ({ number, title: t, html_url }));
+  } catch {
+    return [];
+  }
+}
+
+/** Prefilled new-issue URL — publishing stays a human click by default. */
+export function newIssueUrl({ title, body }) {
+  const params = new URLSearchParams({ title, body });
+  return `https://github.com/${REPO}/issues/new?${params.toString().replaceAll("+", "%20")}`;
+}

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

@@ -0,0 +1,127 @@
+/**
+ * Karajan Environment playbook (ENV-A1, KJC-TSK-0639).
+ *
+ * ONE source renders the method for every host agent: a managed block in
+ * CLAUDE.md (Claude Code) and AGENTS.md (Codex). The body is data here —
+ * not a template file — so it never counts as a repo AI-rule file and can
+ * be parameterized later (rag/gate state, backend) without forking copies.
+ *
+ * The playbook is agent context: every line costs attention on every turn,
+ * so it stays under 60 lines by test. Method over prose.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { upsertManagedBlock } from "../utils/managed-markers.js";
+
+// AB-A (KJC-TSK-0650): any agent can be the brain. AGENTS.md is the
+// emerging standard (Codex, Cursor and most new CLIs read it); GEMINI.md
+// covers Gemini CLI. "both" is kept as a legacy alias of claude+codex.
+export const PLAYBOOK_TARGETS = ["claude", "codex", "gemini", "both", "all"];
+
+const TARGET_FILES = {
+  claude: ["CLAUDE.md"],
+  codex: ["AGENTS.md"],
+  gemini: ["GEMINI.md"],
+  both: ["CLAUDE.md", "AGENTS.md"],
+  all: ["CLAUDE.md", "AGENTS.md", "GEMINI.md"],
+};
+
+// ENV-D1 (KJC-TSK-0642): the tracking invariant names the CHOSEN state
+// backend — a playbook that says "board or PG" makes the host guess.
+// KJC-TSK-0684 (issue #1287): external boards (Linear, Trello, Jira…) are
+// first-class — card-first points at THE project's board, worked through
+// the host agent's own MCP/tools. kj never mirrors it: a half-empty
+// parallel board is worse than none.
+const BACKEND_TRACKING = {
+  "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj hu add` / `kj board`) before it starts — and `kj hu list` BEFORE `kj hu add`: reuse the existing card if one covers the work. Cards are permanent — never delete or recreate one; discard with `kj hu move <id> skipped`. `kj brief board` explains the board.",
+  "planning-game": "Every piece of work has a tracked card in the Planning Game MCP before it starts (In Progress while you work it).",
+};
+
+const externalTracking = (boardName) =>
+  `Every piece of work has a tracked card in ${boardName} — the project's board — before it starts (use its MCP/tools; move the card as you work it). kj does not mirror it: never create a parallel HU Board.`;
+
+function trackingLine(stateBackend, boardName) {
+  if (stateBackend === "external") return externalTracking(boardName || "the project's external board");
+  return BACKEND_TRACKING[stateBackend] || BACKEND_TRACKING["hu-board"];
+}
+
+// AB-C2 (KJC-TSK-0653): outcome-first — invariants over step scripts.
+// Frontier models choose their own path best; what they need explicit are
+// the limits. The git gates enforce these regardless of what any brain does.
+const playbookBody = (stateBackend, boardName) => `# Karajan method (v4)
+
+You are the orchestrator; Karajan governs. A task is DONE when its
+done-statement is literally true, the full suite is green, and every commit
+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. 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. Green is not proof: with \`method_gates.mutation\`
+  declared, run \`kj mutate --since <base>\` after green and BEFORE the
+  review — a surviving mutant is a weak assert; kill it first.
+- Every diff is reviewed by a DIFFERENT AI before it is committed
+  (\`kj review --staged\`): verdicts bind to the exact diff — change the code
+  and it must be reviewed again. Disagree with a rejection? \`kj solomon\`.
+- Security findings are never overridable — not even by arbitration. You
+  absorb the security role: \`kj brief security\` states what must be true.
+  Task touches auth, user input, secrets, network or deps? Run
+  \`kj audit --security\` (zero tokens) and remediate BEFORE the review.
+- A design decision the card's AC don't cover belongs to the USER: record
+  it as a proposed ADR (\`kj adr add\`) and ask — never bury it in a PR
+  bullet. An oversized-diff warning is not an opinion either: partition,
+  or get an explicit OK.
+- A non-trivial plan names at least two approaches — one as if the
+  codebase didn't exist — and says why the winner won. Following the
+  legacy line is a choice, never a default.
+- Publishing ANY artifact (a build's dist/, a docs site, a tarball)?
+  \`kj privacy scan <dir>\` first — nothing personal or secret-shaped ships.
+- Branch first: never commit on the base branch — every change reaches it
+  through an atomic PR (~150 net lines, Conventional Commits). More than one
+  task, or the base tree must stay untouched? \`kj worktree start <slug>\`
+  (one lane per task; \`kj worktree done <slug>\` after merge). Never CLAIM
+  isolation without proof: in a lane, \`git rev-parse --git-dir\` differs
+  from \`--git-common-dir\`.
+
+Commands: \`kj rag query\` · \`kj brief <role>\` (triage, planner, researcher,
+architect, tester, security, audit, board) · \`kj hu add|move|list\` ·
+\`kj worktree start|list|done\` · \`kj adr add|list\` ·
+\`kj review --staged\` · \`kj review --check\` · \`kj solomon --position\` ·
+\`kj agent run <agent>\` · \`kj report\` · \`kj check\`
+
+Hit a kj bug or friction? Diagnose it and file it upstream with
+\`kj report-issue\` (sanitized; ask your user before \`--publish\`).
+kj announces a newer version? Tell your user what it brings and ask —
+never run \`kj update\` on your own.
+`;
+
+export function renderPlaybook({ stateBackend = "hu-board", boardName = null } = {}) {
+  return playbookBody(stateBackend, boardName);
+}
+
+/**
+ * Install/refresh the playbook block in the target agent files.
+ * User content outside the managed block is never touched.
+ */
+export async function installPlaybook({ projectDir, target = "all", version = "1", stateBackend = "hu-board", boardName = null }) {
+  if (!PLAYBOOK_TARGETS.includes(target)) {
+    throw new Error(`unknown target "${target}" — use one of: ${PLAYBOOK_TARGETS.join(", ")}`);
+  }
+  const files = [];
+  for (const file of TARGET_FILES[target]) {
+    const fullPath = path.join(projectDir, file);
+    let source = "";
+    try { source = await fs.readFile(fullPath, "utf8"); } catch { /* new file */ }
+    const { content, action } = upsertManagedBlock({
+      source, blockId: "playbook", version, body: renderPlaybook({ stateBackend, boardName }), style: "html",
+      note: "do not edit: regenerated by kj env install",
+    });
+    if (action !== "unchanged") await fs.writeFile(fullPath, content);
+    files.push(file);
+  }
+  return { files, target };
+}