kanbo-cli 0.1.2 → 0.1.3

package/dist/lib/{manifest-NRhhhOkC.mjs → manifest-mkDJmxt2.mjs}

@@ -3,18 +3,20 @@ import { c as getBoardMigrationsPath, i as BOARD_PERSON_ROLE, l as createPostgre
 import { a as openBoardDatabase, c as createSqliteBoardStore, i as markBoardFileOwnedByKanbo, n as migrateBoardFile, o as readBoardFileContents, r as assertBoardSchema$1 } from "./migrate-BhYi9cXw.mjs";
 import { Command } from "commander";
 import { z } from "zod";
-import { hostname, userInfo } from "node:os";
+import { homedir, hostname, userInfo } from "node:os";
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { sql } from "drizzle-orm";
-import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { accessSync, chmodSync, constants, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { drizzle } from "drizzle-orm/postgres-js";
 import { migrate } from "drizzle-orm/postgres-js/migrator";
 import postgres from "postgres";
 import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { spawn, spawnSync } from "node:child_process";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 /**
 * Every exit code this tool promises, and what it means — the capabilities
@@ -4301,6 +4303,866 @@ function readRequestedRules(options) {
 	return options.require.split(",").map((rule) => rule.trim()).filter(Boolean);
 }
 //#endregion
+//#region src/package-version.ts
+dirname(fileURLToPath(import.meta.url));
+/**
+* This build's own version, one source for the CLI's `--version`, the MCP
+* server's reported version and the capabilities manifest's
+* `package.version`. A build carries it as a literal; running from source
+* (tests, `tsx`) reads the package's own `package.json` instead.
+*/
+const KANBO_PACKAGE_VERSION = "0.1.3";
+//#endregion
+//#region src/cli/failure.ts
+/**
+* What a failed command says, and what it leaves with.
+*
+* One place, because a failure is output as much as a result is: the exit code
+* a caller may branch on, the sentence a person reads, and the chain underneath
+* it that says what actually went wrong.
+*/
+/** How far down a chain of causes is still worth reading. */
+const CAUSE_DEPTH_LIMIT = 5;
+/**
+* What to say about a failure, and what to leave with.
+*
+* A `CliError` already carries both. A `BoardError` is a rule of the board the
+* caller broke: its code is the honest name of what happened, and its details
+* say which value did it, so both are printed rather than translated into a
+* sentence that could drift away from the rule. The one exception is a card
+* held at a column's door: its details are a list, and a person reads it as
+* one line per rule the card does not meet yet (`describeColumnRefusal`).
+*
+* Whatever it is, its causes are printed under it. A driver's failure arrives
+* wrapped — `Failed query: create schema …` with the connection refused
+* underneath — and the wrapper alone tells a person nothing they can act on.
+* Every line goes through the masking on its way out, because a message this
+* tool did not write is free to carry the whole connection string in it.
+*/
+function describeFailure(error) {
+	const { message, exitCode } = readFailure(error);
+	return {
+		message: maskDatabaseUrls([message, ...describeCauses(error, 1)].join("\n")),
+		exitCode
+	};
+}
+function readFailure(error) {
+	if (error instanceof CliError) return {
+		message: error.message,
+		exitCode: error.exitCode
+	};
+	if (error instanceof BoardError && error.code === "board_column_rules_unmet") return {
+		message: describeColumnRefusal(error.details),
+		exitCode: 1
+	};
+	if (error instanceof BoardError) {
+		const details = error.details ? ` ${JSON.stringify(error.details)}` : "";
+		return {
+			message: `${error.code}${details}`,
+			exitCode: 1
+		};
+	}
+	return {
+		message: error instanceof Error ? error.message : String(error),
+		exitCode: 1
+	};
+}
+/**
+* The chain under a failure, one indented line per link.
+*
+* Bounded, because `cause` is an ordinary property and nothing stops it
+* pointing back at the error it came from; a chain longer than this has stopped
+* explaining anything anyway.
+*/
+function describeCauses(error, depth) {
+	const cause = error instanceof Error ? error.cause : void 0;
+	if (cause === void 0 || cause === null || depth > CAUSE_DEPTH_LIMIT) return [];
+	const message = cause instanceof Error ? cause.message : String(cause);
+	return [`${"  ".repeat(depth)}Caused by: ${message}`, ...describeCauses(cause, depth + 1)];
+}
+//#endregion
+//#region src/cli/setup/instructions.ts
+/**
+* The instruction block kanbo writes into an agent's standing instructions,
+* and the three things done to it: written, found again, taken out.
+*
+* Two versions of the block exist. The project block says "this project is on
+* a board"; the global one, for a person's user-level file, says "a project
+* with `.kanbo/` is on a board" and binds nothing — one user file serves every
+* project, and most of them have no board.
+*/
+/** The markers that make the block something this tool can find again. */
+const INSTRUCTION_START = "<!-- KANBO_START -->";
+const INSTRUCTION_END = "<!-- KANBO_END -->";
+/**
+* What to run and when, and nothing about how to do the work: the method is
+* the person's own instructions to their agent. The rules are the sentences
+* `ops/agent-rules.ts` holds for every surface, with the command beside each.
+*/
+const RULE_LINES = [
+	"- Take a card from `kanbo ready`.",
+	`- ${MOVE_CARD_RULE} (\`kanbo card move <id> <column>\`)`,
+	`- ${STATUS_LINE_RULE} (\`kanbo card status-line <id> --text "..."\`)`,
+	`- ${SUBTASK_RULE} (\`kanbo card create --description "..." --parent <id>\`)`,
+	`- ${COMMENT_RULE} (\`kanbo card comment <id> --content "..."\`)`,
+	`- ${WAIT_FOR_PERSON_RULE} (\`kanbo card wait-approval <id>\`)`,
+	`- ${PERSON_ONLY_RULE}`,
+	`- ${OWN_SESSION_RULE} (\`kanbo run start <id> --agent <name> --session <ref>\`)`,
+	"- Run `kanbo capabilities` for the full list of tools, commands and rules."
+];
+/** The block `kanbo init --instructions …` writes into a project's own file. */
+const INSTRUCTION_BLOCK = [
+	INSTRUCTION_START,
+	"## Kanbo board",
+	"",
+	"Work on this project is tracked on a kanbo board. Before starting a task run `kanbo prime` — it prints the board's columns and what each one means.",
+	"",
+	...RULE_LINES,
+	INSTRUCTION_END
+].join("\n");
+/** The block `kanbo init --global` writes into a person's user-level file. */
+const GLOBAL_INSTRUCTION_BLOCK = [
+	INSTRUCTION_START,
+	"## Kanbo boards",
+	"",
+	"A project with a `.kanbo/` directory tracks its work on a kanbo board. In such a project, before starting a task run `kanbo prime` (or call the `kanbo_prime` tool) — it prints the board's columns and what each one means. A project without `.kanbo/` has no board: ignore this section there, and do not create one — a person sets a board up with `kanbo init`.",
+	"",
+	...RULE_LINES,
+	INSTRUCTION_END
+].join("\n");
+/**
+* The block in that file, once.
+*
+* A file that already carries the markers has its block replaced rather than
+* appended to, so a current block changes nothing at all and an outdated one is
+* brought forward. Everything outside the markers is the person's own writing
+* and is never touched.
+*/
+function planInstructionBlock(path, block) {
+	const existing = readText(path);
+	const next = withBlock(existing, block);
+	return {
+		path,
+		next: existing === next ? null : next
+	};
+}
+/**
+* The file without the block, or no change when it carries none. The file
+* itself stays even when nothing is left in it: kanbo does not record which
+* files it created, and a person's file is not this tool's to delete.
+*/
+function planInstructionBlockRemoval(path) {
+	const existing = readText(path);
+	const bounds = existing === null ? null : findBlock(existing);
+	if (existing === null || bounds === null) return {
+		path,
+		next: null
+	};
+	const joined = [existing.slice(0, bounds.start).replace(/\s*$/, ""), existing.slice(bounds.end).trim()].filter((part) => part.length > 0).join("\n\n");
+	return {
+		path,
+		next: joined ? `${joined}\n` : ""
+	};
+}
+/** The block a file carries, markers included, or `null` when it carries none. */
+function readInstructionBlock(path) {
+	const existing = readText(path);
+	const bounds = existing === null ? null : findBlock(existing);
+	return existing === null || bounds === null ? null : existing.slice(bounds.start, bounds.end);
+}
+function withBlock(existing, block) {
+	if (existing === null || !existing.trim()) return `${block}\n`;
+	const bounds = findBlock(existing);
+	if (bounds) return existing.slice(0, bounds.start) + block + existing.slice(bounds.end);
+	return `${existing.replace(/\s*$/, "")}\n\n${block}\n`;
+}
+function findBlock(text) {
+	const start = text.indexOf(INSTRUCTION_START);
+	const end = text.indexOf(INSTRUCTION_END);
+	return start >= 0 && end > start ? {
+		start,
+		end: end + 18
+	} : null;
+}
+function readText(path) {
+	return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+//#endregion
+//#region src/cli/setup/paths.ts
+/**
+* Where each agent tool keeps the files kanbo writes into, for one project and
+* for the person's whole machine.
+*
+* Resolved on every call rather than at import, so `HOME` and `CODEX_HOME` set
+* by a test (or a person) are the ones obeyed. Each path was checked against
+* the tool's own documentation; `docs/agents.md` lists the pages.
+*/
+/** The tools whose user-level instruction file `kanbo init --global` can write. */
+const GLOBAL_INSTRUCTION_CLIENTS = [
+	"claude",
+	"codex",
+	"gemini"
+];
+/** The files a project's agents read their standing instructions from. */
+const PROJECT_INSTRUCTION_FILES = {
+	claude: "CLAUDE.md",
+	agents: "AGENTS.md"
+};
+/** The tools that can be told about the board's MCP server. */
+const MCP_CLIENTS = [
+	"claude",
+	"codex",
+	"cursor"
+];
+/** Where Codex keeps its global files: `$CODEX_HOME`, else `~/.codex`. */
+function codexHome() {
+	return process.env.CODEX_HOME?.trim() || join(homedir(), ".codex");
+}
+/** The user-level instruction file of each tool. */
+function globalInstructionPath(client) {
+	switch (client) {
+		case "claude": return join(homedir(), ".claude", "CLAUDE.md");
+		case "codex": return join(codexHome(), "AGENTS.md");
+		case "gemini": return join(homedir(), ".gemini", "GEMINI.md");
+	}
+}
+/**
+* The user-level MCP configuration of each tool. Claude Code's is
+* `~/.claude.json`, its own state file: kanbo reads it but never writes it —
+* `claude mcp add` and `claude mcp remove` do.
+*/
+function globalMcpConfigPath(client) {
+	switch (client) {
+		case "claude": return join(homedir(), ".claude.json");
+		case "codex": return join(codexHome(), "config.toml");
+		case "cursor": return join(homedir(), ".cursor", "mcp.json");
+	}
+}
+/** The project-level MCP configuration of each tool. */
+function projectMcpConfigPath(projectDir, client) {
+	switch (client) {
+		case "claude": return join(projectDir, ".mcp.json");
+		case "codex": return join(projectDir, ".codex", "config.toml");
+		case "cursor": return join(projectDir, ".cursor", "mcp.json");
+	}
+}
+/**
+* Every executable of that name on `PATH`, in the order a shell would find
+* them. A path with a separator in it is looked at directly, as a shell does.
+*/
+function findAllOnPath(command) {
+	if (isAbsolute(command) || command.includes("/")) return isExecutableFile(command) ? [command] : [];
+	const extensions = process.platform === "win32" ? ["", ...(process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")] : [""];
+	const found = [];
+	for (const directory of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) for (const extension of extensions) {
+		const candidate = join(directory, command + extension);
+		if (isExecutableFile(candidate) && !found.includes(candidate)) found.push(candidate);
+	}
+	return found;
+}
+/** The executable a shell would start for that command, or `null` when there is none. */
+function findOnPath(command) {
+	return findAllOnPath(command)[0] ?? null;
+}
+function isExecutableFile(path) {
+	try {
+		if (!statSync(path).isFile()) return false;
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/cli/setup/mcp-config.ts
+/**
+* The board's MCP server entry, in the two formats the tools keep it in: the
+* `mcpServers` JSON map Claude Code (`.mcp.json`) and Cursor (`mcp.json`) read,
+* and the `[mcp_servers.<name>]` TOML table Codex reads (`config.toml`). Each
+* is planned before anything is written, found again by the doctor, and taken
+* out by `kanbo uninstall` without touching any other server.
+*/
+/** The name the board's MCP server is registered under, in every tool. */
+const MCP_SERVER_NAME = "kanbo";
+/** How every registration kanbo writes starts the server. */
+const MCP_COMMAND = "kanbo";
+const MCP_ARGS = ["mcp"];
+/** The line that registers the server with Claude Code for every project of this user. */
+const CLAUDE_USER_ADD = [
+	"claude",
+	"mcp",
+	"add",
+	"--scope",
+	"user",
+	MCP_SERVER_NAME,
+	"--",
+	MCP_COMMAND,
+	...MCP_ARGS
+];
+/** The line that takes that registration out again. */
+const CLAUDE_USER_REMOVE = [
+	"claude",
+	"mcp",
+	"remove",
+	MCP_SERVER_NAME,
+	"--scope",
+	"user"
+];
+/**
+* A Codex table header naming this server or one of its subtables
+* (`[mcp_servers.kanbo.env]`), in every spelling TOML allows for the key: bare,
+* double-quoted and single-quoted all name the same server, and a check that
+* only knew the bare one would write a second table beside a registration the
+* person already has.
+*/
+const CODEX_HEADER_PATTERN = new RegExp(String.raw`^\s*\[\s*mcp_servers\s*\.\s*(?:${MCP_SERVER_NAME}|"${MCP_SERVER_NAME}"|'${MCP_SERVER_NAME}')\s*(\.[^\]]*)?\]`);
+/** Any table header, which is where a table's keys end. */
+const TOML_HEADER_PATTERN = /^\s*\[/;
+/** A `command = "..."` line, either string spelling. */
+const TOML_COMMAND_PATTERN = /^\s*command\s*=\s*(?:"([^"]*)"|'([^']*)')/m;
+/**
+* The `mcpServers` map, merged rather than replaced: the file may already
+* describe servers that have nothing to do with this board. A `kanbo` entry
+* that is already there belongs to the person — it may point at a different
+* binary or carry arguments of its own — and is left as it is.
+*/
+function planJsonMcpServer(path) {
+	const existing = readJsonConfig(path);
+	if (existing.mcpServers && "kanbo" in existing.mcpServers) return {
+		path,
+		next: null
+	};
+	const next = {
+		...existing,
+		mcpServers: {
+			...existing.mcpServers,
+			[MCP_SERVER_NAME]: {
+				type: "stdio",
+				command: MCP_COMMAND,
+				args: [...MCP_ARGS]
+			}
+		}
+	};
+	return {
+		path,
+		next: `${JSON.stringify(next, null, 2)}\n`
+	};
+}
+/**
+* The same file without the `kanbo` entry. Everything else stays, the
+* `mcpServers` object included when nothing else is left in it: kanbo does not
+* record which files it created, so it leaves the structure rather than guess.
+* A file it cannot read as a JSON object is not touched at all.
+*/
+function planJsonMcpServerRemoval(path) {
+	const existing = readJsonIfObject(path);
+	if (!existing || !isPlainObject(existing.mcpServers) || !("kanbo" in existing.mcpServers)) return {
+		path,
+		next: null
+	};
+	const { [MCP_SERVER_NAME]: _removed, ...others } = existing.mcpServers;
+	return {
+		path,
+		next: `${JSON.stringify({
+			...existing,
+			mcpServers: others
+		}, null, 2)}\n`
+	};
+}
+/**
+* The command a JSON registration starts the server with: `undefined` when the
+* file registers no `kanbo` server, `null` when it does but names no command
+* (a URL server, say).
+*/
+function readJsonMcpCommand(path) {
+	const servers = readJsonIfObject(path)?.mcpServers;
+	if (!isPlainObject(servers) || !isPlainObject(servers["kanbo"])) return;
+	const command = servers[MCP_SERVER_NAME].command;
+	return typeof command === "string" && command.trim() ? command.trim() : null;
+}
+/** Codex keeps its servers in TOML tables, so the table is appended rather than merged. */
+function planCodexMcpServer(path) {
+	const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+	if (findCodexSections(existing).length > 0) return {
+		path,
+		next: null
+	};
+	const table = `[mcp_servers.${MCP_SERVER_NAME}]\ncommand = "${MCP_COMMAND}"\nargs = ${JSON.stringify(MCP_ARGS)}\n`;
+	return {
+		path,
+		next: existing.trim() ? `${existing.replace(/\s*$/, "")}\n\n${table}` : table
+	};
+}
+/**
+* The same file without the `kanbo` table and its subtables. A table runs from
+* its header to the next header, so every other table — and every line before
+* the first — is kept byte for byte.
+*/
+function planCodexMcpServerRemoval(path) {
+	if (!existsSync(path)) return {
+		path,
+		next: null
+	};
+	const existing = readFileSync(path, "utf8");
+	const sections = findCodexSections(existing);
+	if (sections.length === 0) return {
+		path,
+		next: null
+	};
+	const lines = existing.split("\n");
+	const removed = new Set(sections.flatMap(({ start, end }) => range(start, end)));
+	const next = lines.filter((_, index) => !removed.has(index)).join("\n").replace(/^\n+/, "");
+	return {
+		path,
+		next: next.trim() ? `${next.replace(/\s*$/, "")}\n` : ""
+	};
+}
+/** The command the Codex table starts the server with, with the same `undefined`/`null` meaning as the JSON one. */
+function readCodexMcpCommand(path) {
+	if (!existsSync(path)) return;
+	const text = readFileSync(path, "utf8");
+	const main = findCodexSections(text).find((section) => section.main);
+	if (!main) return;
+	const body = text.split("\n").slice(main.start, main.end).join("\n");
+	const match = TOML_COMMAND_PATTERN.exec(body);
+	return match ? match[1] ?? match[2] ?? null : null;
+}
+/** Is the server registered with Claude Code for every project of this user (`~/.claude.json`, read only)? */
+function readClaudeUserMcpCommand() {
+	return readJsonMcpCommand(globalMcpConfigPath("claude"));
+}
+/**
+* Run `claude mcp …` when Claude Code is here to run it, and hand the line to
+* the person when it is not — or when it failed, with the first line it said.
+* `~/.claude.json` is Claude Code's own state file and is never edited by hand.
+*/
+function runClaudeMcp(argv) {
+	const command = argv.join(" ");
+	const executable = findOnPath(argv[0]);
+	if (!executable) return {
+		state: "manual",
+		command,
+		reason: `${argv[0]} is not on PATH`
+	};
+	const result = spawnSync(executable, argv.slice(1), {
+		encoding: "utf8",
+		timeout: 6e4
+	});
+	if (result.status === 0) return {
+		state: "ran",
+		command
+	};
+	const said = `${result.stderr ?? ""}${result.stdout ?? ""}`.trim().split("\n")[0];
+	return {
+		state: "manual",
+		command,
+		reason: result.error ? result.error.message : `${argv[0]} exited ${result.status ?? "on a signal"}${said ? `: ${said}` : ""}`
+	};
+}
+/** The line ranges (`end` exclusive) of the `kanbo` table and its subtables. */
+function findCodexSections(text) {
+	const lines = text.split("\n");
+	const sections = [];
+	for (let index = 0; index < lines.length; index += 1) {
+		const match = CODEX_HEADER_PATTERN.exec(lines[index]);
+		if (!match) continue;
+		let end = index + 1;
+		while (end < lines.length && !TOML_HEADER_PATTERN.test(lines[end])) end += 1;
+		sections.push({
+			start: index,
+			end,
+			main: match[1] === void 0
+		});
+		index = end - 1;
+	}
+	return sections;
+}
+function range(start, end) {
+	return Array.from({ length: end - start }, (_, offset) => start + offset);
+}
+/**
+* The tool's configuration file as an object to merge into — or a refusal.
+*
+* A file that is valid JSON but not an object (a list, a string, `null`) is
+* something this command has no idea how to merge into, and spreading it would
+* quietly throw the person's file away. The file is left exactly as it is and
+* they are told which one to look at.
+*/
+function readJsonConfig(path) {
+	if (!existsSync(path)) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		throw new CliError(1, `${path} is not valid JSON. Fix or remove it, then run kanbo init again.`);
+	}
+	if (!isPlainObject(parsed)) throw new CliError(1, `${path} does not hold a JSON object. Fix or remove it, then run kanbo init again.`);
+	if (parsed.mcpServers !== void 0 && !isPlainObject(parsed.mcpServers)) throw new CliError(1, `${path} has an "mcpServers" that is not an object. Fix it, then run kanbo init again.`);
+	return parsed;
+}
+/** The file as a JSON object, or `null` when it is missing or anything else — for reading and removal, which never refuse. */
+function readJsonIfObject(path) {
+	if (!existsSync(path)) return null;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		return isPlainObject(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/cli/doctor.ts
+/** How long an external board may take to answer before the doctor gives up on it. */
+const POSTGRES_TIMEOUT_MS = 5e3;
+async function collectDoctorFindings(input) {
+	const findings = [{
+		check: "version",
+		status: "ok",
+		detail: `kanbo ${KANBO_PACKAGE_VERSION}${input.self ? ` (${input.self})` : ""}`
+	}, checkPath(input.self)];
+	const project = findKanboProject(input.cwd);
+	findings.push(checkProject(project));
+	const target = project?.binding ? resolveTarget(project.root) : null;
+	if (project?.binding && !project.binding.databaseUrl) findings.push(await checkSqlite());
+	if (project?.binding && findings.every((finding) => finding.check !== "sqlite" || finding.status === "ok")) findings.push(...await checkBoard(target));
+	findings.push(...checkInstructions(project?.root ?? null));
+	const registrations = findRegistrations(project?.root ?? null);
+	findings.push(...checkRegistrations(registrations));
+	if (project?.binding && !(target instanceof Error)) findings.push(await checkHandshake(registrations, project.root, input.handshakeTimeoutMs));
+	findings.push(checkActor());
+	return findings;
+}
+/** Is the `kanbo` a client would start this one? */
+function checkPath(self) {
+	const all = findAllOnPath(MCP_COMMAND);
+	if (all.length === 0) return {
+		check: "path",
+		status: "warn",
+		detail: "No kanbo on PATH: a shell or MCP client that runs `kanbo` will not find it.",
+		fix: "Install kanbo globally (see docs/installation.md), or put the directory that holds it on PATH."
+	};
+	const first = all[0];
+	if (self && realPath(first) !== realPath(self)) return {
+		check: "path",
+		status: "warn",
+		detail: `${first} comes first on PATH and is not this kanbo (${self}): agents and MCP clients start that one.`,
+		fix: "Remove the other install, or put this one first on PATH."
+	};
+	return {
+		check: "path",
+		status: "ok",
+		detail: `kanbo on PATH: ${first}`
+	};
+}
+/** The nearest folder at or above `cwd` with a `.kanbo/` directory, and its binding. */
+function findKanboProject(cwd) {
+	let directory = resolve(cwd);
+	while (true) {
+		const kanboDirectory = join(directory, dirname(BINDING_FILE_PATH));
+		if (existsSync(kanboDirectory) && statSync(kanboDirectory).isDirectory()) return {
+			root: directory,
+			binding: readBinding(join(directory, BINDING_FILE_PATH))
+		};
+		const parent = dirname(directory);
+		if (parent === directory) return null;
+		directory = parent;
+	}
+}
+function checkProject(project) {
+	if (!project) return {
+		check: "binding",
+		status: "warn",
+		detail: "Not inside a kanbo project (no .kanbo/ here or above); board checks are skipped.",
+		fix: "Run kanbo init --file in a project to give it a board."
+	};
+	const path = join(project.root, BINDING_FILE_PATH);
+	if (!project.binding) return {
+		check: "binding",
+		status: "fail",
+		detail: existsSync(path) ? `${path} is not a binding this build can read.` : `${join(project.root, dirname(BINDING_FILE_PATH))} has no ${BINDING_FILE_PATH.split(/[\\/]/).pop()}: nothing says which board this project is on.`,
+		fix: `Run kanbo init (with --file, or the --database-url you used) in ${project.root} to bind it again.`
+	};
+	return {
+		check: "binding",
+		status: "ok",
+		detail: `${path}: workspace ${project.binding.workspaceId}`
+	};
+}
+function resolveTarget(root) {
+	try {
+		return resolveDbTarget({ cwd: root });
+	} catch (error) {
+		return error instanceof Error ? error : new Error(String(error));
+	}
+}
+/** The native module a board file needs, loaded on a database of its own in memory. */
+async function checkSqlite() {
+	try {
+		(await openBoardDatabase(":memory:")).close();
+		return {
+			check: "sqlite",
+			status: "ok",
+			detail: "better-sqlite3 loads."
+		};
+	} catch (error) {
+		return {
+			check: "sqlite",
+			status: "fail",
+			detail: `better-sqlite3 cannot be loaded: ${describeFailure(error).message}`,
+			fix: "Install better-sqlite3 next to kanbo (npm install -g better-sqlite3 for a global kanbo)."
+		};
+	}
+}
+/** The board itself: it opens, and its schema is this build's. */
+async function checkBoard(target) {
+	if (target === null) return [];
+	if (target instanceof Error) return [{
+		check: "board",
+		status: "fail",
+		detail: describeFailure(target).message,
+		fix: "Run kanbo init in the project to bind it to a board."
+	}];
+	if (target.kind === "postgres") return [await checkPostgresBoard(target.url)];
+	const board = await openBoardDatabase(target.path);
+	try {
+		assertBoardSchema$1(board.database);
+		return [{
+			check: "board",
+			status: "ok",
+			detail: `${target.path} opens; its schema is current.`
+		}];
+	} catch (error) {
+		const outdated = error instanceof BoardError && error.code === "board_schema_outdated";
+		const ownFile = target.owner === "kanbo";
+		return [{
+			check: "board",
+			status: "fail",
+			detail: outdated ? `${target.path}: ${ownFile ? FILE_SCHEMA_OUTDATED_MESSAGE : SCHEMA_OUTDATED_MESSAGE}` : `${target.path}: ${describeFailure(error).message}`,
+			fix: ownFile ? "Run kanbo migrate." : "Start the app this database belongs to, so it applies its migrations."
+		}];
+	} finally {
+		board.close();
+	}
+}
+async function checkPostgresBoard(url) {
+	const where = maskDatabaseUrl(url);
+	let timer;
+	const timeout = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`no answer within ${POSTGRES_TIMEOUT_MS / 1e3}s`)), POSTGRES_TIMEOUT_MS);
+	});
+	try {
+		const board = await Promise.race([openPostgresBoard(url), timeout]);
+		try {
+			await Promise.race([assertInstalledBoard(board.database), timeout]);
+		} finally {
+			board.close();
+		}
+		return {
+			check: "board",
+			status: "ok",
+			detail: `${where} answers; its schema is current.`
+		};
+	} catch (error) {
+		return {
+			check: "board",
+			status: "fail",
+			detail: `${where}: ${describeFailure(error).message}`,
+			fix: "Check the connection string, then run kanbo migrate."
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* Every instruction block kanbo could have written, compared with the one this
+* build writes. Only files that carry a block are reported: a file without one
+* is not a fault, but having no block anywhere is worth a warning.
+*/
+function checkInstructions(root) {
+	const findings = [];
+	if (root) for (const [target, name] of Object.entries(PROJECT_INSTRUCTION_FILES)) {
+		const path = join(root, name);
+		const block = readInstructionBlock(path);
+		if (block !== null) findings.push(blockFinding(path, block === INSTRUCTION_BLOCK, `cd ${root} && kanbo init --instructions ${target} --yes`));
+	}
+	for (const client of GLOBAL_INSTRUCTION_CLIENTS) {
+		const path = globalInstructionPath(client);
+		const block = readInstructionBlock(path);
+		if (block !== null) findings.push(blockFinding(path, block === GLOBAL_INSTRUCTION_BLOCK, `kanbo init --global --instructions ${client}`));
+	}
+	if (findings.length === 0) findings.push({
+		check: "instructions",
+		status: "warn",
+		detail: "No kanbo instruction block in this project's or your own agent files: agents learn the rules only from the MCP server.",
+		fix: "Run kanbo init --instructions claude in the project, or kanbo init --global."
+	});
+	return findings;
+}
+function blockFinding(path, current, fix) {
+	return current ? {
+		check: "instructions",
+		status: "ok",
+		detail: `${path}: block is current.`
+	} : {
+		check: "instructions",
+		status: "fail",
+		detail: `${path}: block differs from the one this kanbo writes (stale).`,
+		fix: `Run ${fix} to rewrite it.`
+	};
+}
+/** Every `kanbo` registration in the project's and the person's own tool configuration. */
+function findRegistrations(root) {
+	const found = [];
+	for (const client of MCP_CLIENTS) {
+		const paths = [...root ? [projectMcpConfigPath(root, client)] : [], globalMcpConfigPath(client)];
+		for (const path of paths) {
+			const command = client === "codex" ? readCodexMcpCommand(path) : readJsonMcpCommand(path);
+			if (command !== void 0) found.push({
+				client,
+				path,
+				command
+			});
+		}
+	}
+	return found;
+}
+function checkRegistrations(registrations) {
+	if (registrations.length === 0) return [{
+		check: "mcp",
+		status: "warn",
+		detail: "No MCP client has the kanbo server registered.",
+		fix: "Run kanbo init --mcp claude,codex,cursor in the project, or kanbo init --global."
+	}];
+	return registrations.map(({ client, path, command }) => {
+		const check = `mcp:${client}`;
+		if (command === null) return {
+			check,
+			status: "warn",
+			detail: `${path}: the kanbo entry names no command.`,
+			fix: `Set "command" to kanbo in ${path}.`
+		};
+		const resolved = findOnPath(command);
+		return resolved ? {
+			check,
+			status: "ok",
+			detail: `${path}: starts ${command} (${resolved}).`
+		} : {
+			check,
+			status: "fail",
+			detail: `${path}: starts ${command}, which is not on PATH — the client cannot start the server.`,
+			fix: `Install kanbo globally, or change the command in ${path} to a path that exists.`
+		};
+	});
+}
+/**
+* Start the server a client would start, from the project folder, and ask it
+* `initialize`. It has to call itself `kanbo` and send its instructions.
+*/
+async function checkHandshake(registrations, root, timeoutMs) {
+	const command = registrations.map((entry) => entry.command && findOnPath(entry.command)).find(Boolean) ?? findOnPath("kanbo");
+	if (!command) return {
+		check: "mcp:handshake",
+		status: "warn",
+		detail: "No kanbo to start, so the MCP server was not tried.",
+		fix: "Put kanbo on PATH."
+	};
+	const transport = new StdioClientTransport({
+		command,
+		args: ["mcp"],
+		cwd: root,
+		env: stringEnvironment(),
+		stderr: "pipe"
+	});
+	let stderr = "";
+	transport.stderr?.on("data", (chunk) => {
+		stderr += chunk.toString();
+	});
+	const client = new Client({
+		name: "kanbo-doctor",
+		version: KANBO_PACKAGE_VERSION
+	});
+	try {
+		await client.connect(transport, { timeout: timeoutMs });
+		const name = client.getServerVersion()?.name;
+		const instructions = client.getInstructions();
+		if (name !== "kanbo" || !instructions?.trim()) return {
+			check: "mcp:handshake",
+			status: "fail",
+			detail: `${command} mcp answered as ${name ?? "nothing"}${instructions?.trim() ? "" : ", without instructions"}.`,
+			fix: "Put a current kanbo first on PATH."
+		};
+		return {
+			check: "mcp:handshake",
+			status: "ok",
+			detail: `${command} mcp answers initialize as kanbo, with instructions.`
+		};
+	} catch (error) {
+		return {
+			check: "mcp:handshake",
+			status: "fail",
+			detail: `${command} mcp did not answer initialize: ${stderr.trim().split("\n")[0] || describeFailure(error).message}`,
+			fix: "Run kanbo mcp in the project yourself to see why it does not start."
+		};
+	} finally {
+		await client.close().catch(() => {});
+	}
+}
+function checkActor() {
+	if (isAgentShell()) return {
+		check: "actor",
+		status: "warn",
+		detail: "This shell says it belongs to an agent (KANBO_ACTOR_KIND=agent): approve and return refuse here.",
+		fix: "If this is your own terminal, remove KANBO_ACTOR_KIND from your shell profile."
+	};
+	return {
+		check: "actor",
+		status: "ok",
+		detail: "This shell is a person's."
+	};
+}
+/** The environment as the SDK wants it: every value a string, so `KANBO_*` reaches the server as it would from a client. */
+function stringEnvironment() {
+	return Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== void 0));
+}
+function realPath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+//#endregion
+//#region src/cli/commands/doctor.ts
+/** How long `kanbo mcp` may take to answer `initialize`. */
+const HANDSHAKE_TIMEOUT_MS = 1e4;
+const MARKS = {
+	ok: "ok  ",
+	warn: "warn",
+	fail: "FAIL"
+};
+function registerDoctorCommand(program) {
+	program.command("doctor").description("check this install, this project's binding and board, instruction blocks and MCP registrations").option("--json", "print the findings as JSON").action(async (options) => {
+		const findings = await collectDoctorFindings({
+			cwd: process.cwd(),
+			self: process.argv[1] ?? null,
+			handshakeTimeoutMs: HANDSHAKE_TIMEOUT_MS
+		});
+		if (options.json) console.log(JSON.stringify({
+			version: KANBO_PACKAGE_VERSION,
+			findings
+		}, null, 2));
+		else for (const finding of findings) {
+			console.log(`${MARKS[finding.status]}  ${finding.check.padEnd(14)} ${finding.detail}`);
+			if (finding.fix) console.log(`${" ".repeat(21)}fix: ${finding.fix}`);
+		}
+		const failed = findings.filter((finding) => finding.status === "fail").length;
+		if (failed > 0) throw new CliError(1, `kanbo doctor: ${failed} check${failed === 1 ? "" : "s"} failed.`);
+	});
+}
+//#endregion
 //#region src/default-board-file-path.ts
 /**
 * Where a board file of a project's own goes when nobody names a path —
@@ -4309,6 +5171,168 @@ function readRequestedRules(options) {
 */
 const DEFAULT_BOARD_FILE_PATH = join(".kanbo", "board.db");
 //#endregion
+//#region src/cli/setup/confirm.ts
+/**
+* Show a plan of file changes and ask before carrying it out.
+*
+* `--yes` is the answer given in advance. A shell with nobody at its terminal
+* cannot be asked, so it is refused rather than taken as a yes: these commands
+* write into a person's own configuration, which is the kind of thing a person
+* says yes to. When the caller asked for machine output, stdout belongs to the
+* result and the plan goes to stderr.
+*/
+async function confirmPlan(input) {
+	(input.machineOutput ? console.error : console.log)(input.preview);
+	if (input.yes) return true;
+	if (!isInteractive()) throw new CliError(1, `Nothing was changed. Run ${input.command} again with --yes to do this without being asked.`);
+	return await (await import("@clack/prompts")).confirm({ message: input.question }) === true;
+}
+/** Is there a person on the other end of this shell to ask? */
+function isInteractive() {
+	return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+//#endregion
+//#region src/cli/setup/file-change.ts
+/** Write the change, creating the directory it lives in, and say what happened. */
+function applyFileChange(change) {
+	if (change.next === null) return {
+		path: change.path,
+		state: "unchanged"
+	};
+	mkdirSync(dirname(change.path), { recursive: true });
+	writeFileSync(change.path, change.next);
+	return {
+		path: change.path,
+		state: "written"
+	};
+}
+//#endregion
+//#region src/cli/commands/init-global.ts
+/**
+* `kanbo init --global` — this person's own agent tools, told about kanbo once
+* for every project.
+*
+* It binds no board and creates none: the block it writes says "a project with
+* `.kanbo/` is on a board", and a project becomes one with a plain `kanbo init`.
+* The MCP registrations are the same `kanbo mcp` every project registration
+* starts, which resolves the board from the folder the client starts it in.
+*
+* Every change is worked out first and shown; nothing is written until the
+* person says yes (or said `--yes`), and a file that already says it is
+* reported `unchanged`.
+*/
+/** Written when `--instructions` is not given. Gemini is asked for by name. */
+const DEFAULT_INSTRUCTION_CLIENTS = ["claude", "codex"];
+/** The flags that are about binding a project, which `--global` does not do. */
+const PROJECT_ONLY_FLAGS = [
+	["file", "--file"],
+	["db", "--db"],
+	["databaseUrl", "--database-url"],
+	["workspace", "--workspace"],
+	["board", "--board"],
+	["identifier", "--identifier"],
+	["agentUrl", "--agent-url"]
+];
+async function initGlobal(options) {
+	const format = readFormat(options);
+	const given = PROJECT_ONLY_FLAGS.filter(([key]) => options[key] !== void 0).map(([, flag]) => flag);
+	if (given.length > 0) throw new CliError(1, `--global binds no board; ${given.join(", ")} ${given.length === 1 ? "is" : "are"} for a project. Run kanbo init in the project for that.`);
+	const instructionClients = parseGlobalInstructions(options.instructions);
+	const mcpClients = options.mcp ?? [...MCP_CLIENTS];
+	const instructionChanges = instructionClients.map((client) => ({
+		client,
+		change: planInstructionBlock(globalInstructionPath(client), GLOBAL_INSTRUCTION_BLOCK)
+	}));
+	const fileMcpChanges = mcpClients.filter((client) => client !== "claude").map((client) => ({
+		client,
+		change: planGlobalMcpFile(client)
+	}));
+	const claudeNeeded = mcpClients.includes("claude") && readClaudeUserMcpCommand() === void 0;
+	const pending = [...instructionChanges, ...fileMcpChanges].filter(({ change }) => change.next !== null);
+	let confirmed = true;
+	if (pending.length > 0 || claudeNeeded) confirmed = await confirmPlan({
+		preview: describePlan$1(pending.map(({ change }) => change), claudeNeeded),
+		question: "Make these changes?",
+		yes: options.yes,
+		machineOutput: Boolean(options.json || format),
+		command: "kanbo init --global"
+	});
+	if (!confirmed) throw new CliError(1, "Nothing was changed.");
+	printResult(describeResult(instructionChanges.map(({ client, change }) => ({
+		client,
+		...applyFileChange(change)
+	})), mcpClients.map((client) => {
+		if (client === "claude") return registerWithClaude(claudeNeeded);
+		return {
+			client,
+			...applyFileChange(fileMcpChanges.find((entry) => entry.client === client).change)
+		};
+	})), options);
+}
+function planGlobalMcpFile(client) {
+	const path = globalMcpConfigPath(client);
+	return client === "codex" ? planCodexMcpServer(path) : planJsonMcpServer(path);
+}
+/** Claude Code's user-scope registration goes through its own command, never an edit of `~/.claude.json`. */
+function registerWithClaude(needed) {
+	const path = globalMcpConfigPath("claude");
+	if (!needed) return {
+		client: "claude",
+		path,
+		state: "unchanged"
+	};
+	const outcome = runClaudeMcp(CLAUDE_USER_ADD);
+	return outcome.state === "ran" ? {
+		client: "claude",
+		path,
+		state: "written",
+		command: outcome.command
+	} : {
+		client: "claude",
+		path,
+		state: "manual",
+		command: outcome.command,
+		reason: outcome.reason
+	};
+}
+function describePlan$1(changes, claudeNeeded) {
+	const lines = ["kanbo init --global will:"];
+	for (const change of changes) lines.push(`  write  ${change.path}`);
+	if (claudeNeeded) lines.push(`  run    ${CLAUDE_USER_ADD.join(" ")}`);
+	lines.push("No board is created. Narrow this with --instructions and --mcp.");
+	return lines.join("\n");
+}
+function describeResult(instructions, mcp) {
+	const lines = [];
+	for (const outcome of instructions) lines.push(`Instructions: ${outcome.path} (${outcome.state})`);
+	for (const outcome of mcp) if (outcome.state === "manual") lines.push(`MCP: ${outcome.client} — run this yourself: ${outcome.command} (${outcome.reason})`);
+	else lines.push(`MCP: ${outcome.path} (${outcome.state})`);
+	lines.push("A project uses the board once it has run kanbo init. Check everything with kanbo doctor.");
+	return {
+		value: {
+			scope: "global",
+			instructions,
+			mcp
+		},
+		text: lines.join("\n"),
+		fields: [
+			"scope",
+			"instructions",
+			"mcp"
+		]
+	};
+}
+function parseGlobalInstructions(value) {
+	if (value === void 0) return DEFAULT_INSTRUCTION_CLIENTS;
+	const names = value.split(",").map((name) => name.trim()).filter((name) => name.length > 0);
+	if (names.length === 1 && names[0] === "none") return [];
+	return names.map((name) => {
+		const client = GLOBAL_INSTRUCTION_CLIENTS.find((candidate) => candidate === name);
+		if (!client) throw new CliError(1, `Unknown instructions target "${name}" for --global. Use one or more of ${GLOBAL_INSTRUCTION_CLIENTS.join(", ")}, or none.`);
+		return client;
+	});
+}
+//#endregion
 //#region src/cli/commands/init.ts
 /**
 * `kanbo init` — tying a project folder to a board, and telling the agents
@@ -4321,22 +5345,6 @@ const DEFAULT_BOARD_FILE_PATH = join(".kanbo", "board.db");
 * whichever tools the person actually uses. Nothing is written to a file the
 * person did not ask for, and nothing is written twice.
 */
-/** The markers that make the instruction block something this tool can find again. */
-const INSTRUCTION_START = "<!-- KANBO_START -->";
-const INSTRUCTION_END = "<!-- KANBO_END -->";
-/** The files an agent reads its standing instructions from. */
-const INSTRUCTION_FILES = {
-	claude: "CLAUDE.md",
-	agents: "AGENTS.md"
-};
-/** The tools that can be told about the board's MCP server. */
-const MCP_CLIENTS = [
-	"claude",
-	"codex",
-	"cursor"
-];
-/** The name the board's MCP server is registered under, in every tool. */
-const MCP_SERVER_NAME = "kanbo";
 /**
 * What a person is told when an external board is named and nothing says which
 * workspace it is about. There is no table to look the answer up in, and a card
@@ -4351,40 +5359,13 @@ const FILE_AND_DATABASE_URL_MESSAGE = "One board at a time: pass --file for a bo
 * rule an agent is missing is one the database keeps, not this command.
 */
 const AGENT_URL_MISSING_WARNING = "kanbo: agents in this project will reach the board with the connection string you gave, which owns it. Until you run \"kanbo roles apply\" and record the agent role's own string with --agent-url, an agent here can approve its own work.";
-/**
-* The Codex table this command writes, in every spelling TOML allows for the
-* key: bare, double-quoted and single-quoted all name the same server, and a
-* check that only knew the bare one would write a second table beside a
-* registration the person already has.
-*/
-const CODEX_TABLE_PATTERN = new RegExp(String.raw`^\s*\[\s*mcp_servers\s*\.\s*(?:${MCP_SERVER_NAME}|"${MCP_SERVER_NAME}"|'${MCP_SERVER_NAME}')\s*\]`, "m");
-/**
-* What an agent working in this project is told about the board.
-*
-* It says what to run and when, and nothing about how to do the work: the
-* method is the person's own instructions to their agent, and the board only
-* insists on the part that keeps the card honest. The rules are the sentences
-* `ops/agent-rules.ts` holds for every surface, with the command beside each.
-*/
-const INSTRUCTION_BLOCK = [
-	INSTRUCTION_START,
-	"## Kanbo board",
-	"",
-	"Work on this project is tracked on a kanbo board. Before starting a task run `kanbo prime` — it prints the board's columns and what each one means.",
-	"",
-	"- Take a card from `kanbo ready`.",
-	`- ${MOVE_CARD_RULE} (\`kanbo card move <id> <column>\`)`,
-	`- ${STATUS_LINE_RULE} (\`kanbo card status-line <id> --text "..."\`)`,
-	`- ${SUBTASK_RULE} (\`kanbo card create --description "..." --parent <id>\`)`,
-	`- ${COMMENT_RULE} (\`kanbo card comment <id> --content "..."\`)`,
-	`- ${WAIT_FOR_PERSON_RULE} (\`kanbo card wait-approval <id>\`)`,
-	`- ${PERSON_ONLY_RULE}`,
-	`- ${OWN_SESSION_RULE} (\`kanbo run start <id> --agent <name> --session <ref>\`)`,
-	"- Run `kanbo capabilities` for the full list of tools, commands and rules.",
-	INSTRUCTION_END
-].join("\n");
 function registerInitCommand(program) {
-	program.command("init").description("bind this project to a board, and tell its agents about it").option("--db <path>", "host database file to read this project's workspace from").option("--database-url <url>", "external Postgres board to bind this project to").option("--file [path]", `use a board file of this project's own instead of a host database or an external board (default ${DEFAULT_BOARD_FILE_PATH})`).option("--workspace <nameOrId>", "workspace this project is").option("--json <fields>", "print only these comma-separated fields, as JSON").option("--format <format>", "output format: json or pretty").option("--board <id>", "the board inside the workspace, when it has more than one").option("--identifier <key>", "what this workspace's card keys start with, for an external board").option("--agent-url <url>", "the connection string agents get, when it is not the one above").option("--instructions <file>", "where to write the instruction block: claude, agents or none", parseInstructions).option("--mcp <clients>", `register the board's MCP server with ${MCP_CLIENTS.join(", ")}`, parseMcpClients).option("--yes", "take the defaults instead of asking").action(async (options) => {
+	program.command("init").description("bind this project to a board, and tell its agents about it").option("--db <path>", "host database file to read this project's workspace from").option("--database-url <url>", "external Postgres board to bind this project to").option("--file [path]", `use a board file of this project's own instead of a host database or an external board (default ${DEFAULT_BOARD_FILE_PATH})`).option("--workspace <nameOrId>", "workspace this project is").option("--json <fields>", "print only these comma-separated fields, as JSON").option("--format <format>", "output format: json or pretty").option("--board <id>", "the board inside the workspace, when it has more than one").option("--identifier <key>", "what this workspace's card keys start with, for an external board").option("--agent-url <url>", "the connection string agents get, when it is not the one above").option("--instructions <file>", "where to write the instruction block: claude, agents or none; with --global, a comma-separated list of claude, codex, gemini, or none").option("--mcp <clients>", `register the board's MCP server with ${MCP_CLIENTS.join(", ")}`, parseMcpClients).option("--global", "set up your own agent tools for every project instead of binding this one; binds no board").option("--yes", "take the defaults instead of asking").action(async (options) => {
+		if (options.global) {
+			await initGlobal(options);
+			return;
+		}
+		if (options.instructions !== void 0) parseInstructions(options.instructions);
 		const projectDir = process.cwd();
 		if (options.file !== void 0) {
 			await initOwnFile(projectDir, options);
@@ -4717,9 +5698,9 @@ function warnAboutOwnerAccess(target, options) {
 * instructions is the kind of thing a person says yes to.
 */
 async function writeInstructions(projectDir, options) {
-	const target = options.instructions ?? await askInstructionTarget(options);
+	const target = options.instructions === void 0 ? await askInstructionTarget(options) : parseInstructions(options.instructions);
 	if (target === "none") return null;
-	return writeInstructionBlock(join(projectDir, INSTRUCTION_FILES[target]));
+	return applyFileChange(planInstructionBlock(join(projectDir, PROJECT_INSTRUCTION_FILES[target]), INSTRUCTION_BLOCK));
 }
 async function askInstructionTarget(options) {
 	showBlock(options);
@@ -4753,35 +5734,6 @@ function showBlock(options) {
 	if (!options.json && !options.format) console.log(`${INSTRUCTION_BLOCK}\n`);
 }
 /**
-* The block, in that file, once.
-*
-* A file that already carries the markers has its block replaced rather than
-* appended to, so running `init` again on a project whose block is current
-* changes nothing at all, and running it after an upgrade brings the block
-* forward. Everything outside the markers is the person's own writing and is
-* never touched.
-*/
-function writeInstructionBlock(path) {
-	const existing = existsSync(path) ? readFileSync(path, "utf8") : null;
-	const next = buildInstructionFile(existing);
-	if (existing === next) return {
-		path,
-		state: "unchanged"
-	};
-	writeFileSync(path, next);
-	return {
-		path,
-		state: "written"
-	};
-}
-function buildInstructionFile(existing) {
-	if (existing === null) return `${INSTRUCTION_BLOCK}\n`;
-	const start = existing.indexOf(INSTRUCTION_START);
-	const end = existing.indexOf(INSTRUCTION_END);
-	if (start >= 0 && end > start) return existing.slice(0, start) + INSTRUCTION_BLOCK + existing.slice(end + 18);
-	return `${existing.replace(/\s*$/, "")}\n\n${INSTRUCTION_BLOCK}\n`;
-}
-/**
 * Tell the tools the person uses about the board's MCP server.
 *
 * Only the ones they named, and only when the tool does not already know: a
@@ -4816,81 +5768,8 @@ async function askMcpClients(options) {
 	return prompts.isCancel(answer) ? [] : answer;
 }
 function registerMcpServer(projectDir, client) {
-	if (client === "codex") return writeCodexMcpServer(join(projectDir, ".codex", "config.toml"));
-	return writeJsonMcpServer(join(projectDir, ...client === "claude" ? [".mcp.json"] : [".cursor", "mcp.json"]));
-}
-/**
-* The `mcpServers` map Claude Code and Cursor both read, merged rather than
-* replaced: the file is the project's, and it may already describe servers that
-* have nothing to do with this board.
-*/
-function writeJsonMcpServer(path) {
-	const existing = readJsonFile(path);
-	if (existing.mcpServers && MCP_SERVER_NAME in existing.mcpServers) return {
-		path,
-		state: "unchanged"
-	};
-	const next = {
-		...existing,
-		mcpServers: {
-			...existing.mcpServers,
-			[MCP_SERVER_NAME]: {
-				type: "stdio",
-				command: "kanbo",
-				args: ["mcp"]
-			}
-		}
-	};
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
-	return {
-		path,
-		state: "written"
-	};
-}
-/**
-* The tool's configuration file as an object to merge into — or a refusal.
-*
-* A file that is valid JSON but not an object (a list, a string, `null`) is
-* something this command has no idea how to merge into, and spreading it would
-* quietly throw the person's file away. The file is left exactly as it is and
-* they are told which one to look at.
-*/
-function readJsonFile(path) {
-	if (!existsSync(path)) return {};
-	const parsed = parseJsonFile(path);
-	if (!isPlainObject(parsed)) throw new CliError(1, `${path} does not hold a JSON object. Fix or remove it, then run kanbo init again.`);
-	if (parsed.mcpServers !== void 0 && !isPlainObject(parsed.mcpServers)) throw new CliError(1, `${path} has an "mcpServers" that is not an object. Fix it, then run kanbo init again.`);
-	return parsed;
-}
-function parseJsonFile(path) {
-	try {
-		return JSON.parse(readFileSync(path, "utf8"));
-	} catch {
-		throw new CliError(1, `${path} is not valid JSON. Fix or remove it, then run kanbo init again.`);
-	}
-}
-function isPlainObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** Codex keeps its servers in TOML tables, so the table is appended rather than merged. */
-function writeCodexMcpServer(path) {
-	const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
-	const table = `[mcp_servers.${MCP_SERVER_NAME}]\ncommand = "kanbo"\nargs = ["mcp"]\n`;
-	if (CODEX_TABLE_PATTERN.test(existing)) return {
-		path,
-		state: "unchanged"
-	};
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, existing.trim() ? `${existing.replace(/\s*$/, "")}\n\n${table}` : table);
-	return {
-		path,
-		state: "written"
-	};
-}
-/** Is there a person on the other end of this shell to ask? */
-function isInteractive() {
-	return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+	const path = projectMcpConfigPath(projectDir, client);
+	return applyFileChange(client === "codex" ? planCodexMcpServer(path) : planJsonMcpServer(path));
 }
 function describeInit(workspace, target, bindingPath, instructions, mcp) {
 	const lines = [`Bound this project to ${workspace.name} — ${bindingPath}`];
@@ -5163,16 +6042,6 @@ async function createDbTransport(input) {
 	};
 }
 //#endregion
-//#region src/package-version.ts
-dirname(fileURLToPath(import.meta.url));
-/**
-* This build's own version, one source for the CLI's `--version`, the MCP
-* server's reported version and the capabilities manifest's
-* `package.version`. A build carries it as a literal; running from source
-* (tests, `tsx`) reads the package's own `package.json` instead.
-*/
-const KANBO_PACKAGE_VERSION = "0.1.2";
-//#endregion
 //#region src/mcp/resources.ts
 /** The URI a client reads the manifest as JSON from. */
 const KANBO_CAPABILITIES_RESOURCE_URI = "kanbo://capabilities";
@@ -5625,74 +6494,6 @@ function createKanboMcpServer(transport, options) {
 	return server;
 }
 //#endregion
-//#region src/cli/failure.ts
-/**
-* What a failed command says, and what it leaves with.
-*
-* One place, because a failure is output as much as a result is: the exit code
-* a caller may branch on, the sentence a person reads, and the chain underneath
-* it that says what actually went wrong.
-*/
-/** How far down a chain of causes is still worth reading. */
-const CAUSE_DEPTH_LIMIT = 5;
-/**
-* What to say about a failure, and what to leave with.
-*
-* A `CliError` already carries both. A `BoardError` is a rule of the board the
-* caller broke: its code is the honest name of what happened, and its details
-* say which value did it, so both are printed rather than translated into a
-* sentence that could drift away from the rule. The one exception is a card
-* held at a column's door: its details are a list, and a person reads it as
-* one line per rule the card does not meet yet (`describeColumnRefusal`).
-*
-* Whatever it is, its causes are printed under it. A driver's failure arrives
-* wrapped — `Failed query: create schema …` with the connection refused
-* underneath — and the wrapper alone tells a person nothing they can act on.
-* Every line goes through the masking on its way out, because a message this
-* tool did not write is free to carry the whole connection string in it.
-*/
-function describeFailure(error) {
-	const { message, exitCode } = readFailure(error);
-	return {
-		message: maskDatabaseUrls([message, ...describeCauses(error, 1)].join("\n")),
-		exitCode
-	};
-}
-function readFailure(error) {
-	if (error instanceof CliError) return {
-		message: error.message,
-		exitCode: error.exitCode
-	};
-	if (error instanceof BoardError && error.code === "board_column_rules_unmet") return {
-		message: describeColumnRefusal(error.details),
-		exitCode: 1
-	};
-	if (error instanceof BoardError) {
-		const details = error.details ? ` ${JSON.stringify(error.details)}` : "";
-		return {
-			message: `${error.code}${details}`,
-			exitCode: 1
-		};
-	}
-	return {
-		message: error instanceof Error ? error.message : String(error),
-		exitCode: 1
-	};
-}
-/**
-* The chain under a failure, one indented line per link.
-*
-* Bounded, because `cause` is an ordinary property and nothing stops it
-* pointing back at the error it came from; a chain longer than this has stopped
-* explaining anything anyway.
-*/
-function describeCauses(error, depth) {
-	const cause = error instanceof Error ? error.cause : void 0;
-	if (cause === void 0 || cause === null || depth > CAUSE_DEPTH_LIMIT) return [];
-	const message = cause instanceof Error ? cause.message : String(cause);
-	return [`${"  ".repeat(depth)}Caused by: ${message}`, ...describeCauses(cause, depth + 1)];
-}
-//#endregion
 //#region src/cli/commands/mcp.ts
 function registerMcpCommand(program) {
 	program.command("mcp").description("serve this board to an MCP client over stdio").option("--db <path>", "board database file to open").option("--database-url <url>", "external Postgres board to serve instead of a board file").option("--workspace <nameOrId>", "workspace the board tools are about").action(async (options) => {
@@ -7784,6 +8585,143 @@ function registerSprintCommands(program) {
 	});
 }
 //#endregion
+//#region src/cli/commands/uninstall.ts
+function registerUninstallCommand(program) {
+	program.command("uninstall").description("remove what kanbo init wrote: instruction blocks and kanbo MCP entries; boards stay unless --purge").option("--project", "only this project's files").option("--global", "only your own user-level files").option("--purge", "also remove this project's .kanbo/binding.json, and its board file after a confirmation naming it").option("--yes", "do it without asking (never deletes a board file)").option("--json", "print what was done as JSON").action(async (options) => {
+		await uninstall(options);
+	});
+}
+async function uninstall(options) {
+	const both = !options.project && !options.global;
+	const withProject = both || Boolean(options.project);
+	const withGlobal = both || Boolean(options.global);
+	if (options.purge && !withProject) throw new CliError(1, "--purge removes a project's binding and board; run it without --global, in the project.");
+	const projectRoot = withProject ? findKanboProject(process.cwd())?.root ?? process.cwd() : null;
+	const edits = [...projectRoot ? planProjectEdits(projectRoot) : [], ...withGlobal ? planGlobalEdits() : []].filter((edit) => edit.change.next !== null);
+	const claudeUser = withGlobal && readClaudeUserMcpCommand() !== void 0;
+	const bindingPath = projectRoot && options.purge ? join(projectRoot, BINDING_FILE_PATH) : null;
+	const purgeBinding = bindingPath !== null && existsSync(bindingPath);
+	const boardFile = projectRoot && options.purge ? findOwnBoardFile(projectRoot) : null;
+	const actions = [];
+	if (edits.length > 0 || claudeUser || purgeBinding || boardFile) {
+		if (!await confirmPlan({
+			preview: describePlan(edits, claudeUser, purgeBinding ? bindingPath : null, boardFile),
+			question: "Remove these?",
+			yes: options.yes,
+			machineOutput: Boolean(options.json),
+			command: "kanbo uninstall"
+		})) throw new CliError(1, "Nothing was changed.");
+		for (const edit of edits) {
+			applyFileChange(edit.change);
+			actions.push({
+				path: edit.change.path,
+				action: "edited",
+				note: edit.what
+			});
+		}
+		if (claudeUser) {
+			const outcome = runClaudeMcp(CLAUDE_USER_REMOVE);
+			actions.push({
+				path: globalMcpConfigPath("claude"),
+				action: outcome.state,
+				note: outcome.state === "ran" ? outcome.command : `run this yourself: ${outcome.command} (${outcome.reason})`
+			});
+		}
+		if (purgeBinding) {
+			rmSync(bindingPath);
+			actions.push({
+				path: bindingPath,
+				action: "deleted",
+				note: "project binding"
+			});
+		}
+		if (boardFile) actions.push(await purgeBoardFile(boardFile));
+	}
+	printActions(actions, options);
+}
+function planProjectEdits(root) {
+	return [...Object.values(PROJECT_INSTRUCTION_FILES).map((name) => ({
+		change: planInstructionBlockRemoval(join(root, name)),
+		what: "kanbo instruction block"
+	})), ...[
+		"claude",
+		"codex",
+		"cursor"
+	].map((client) => ({
+		change: planMcpRemoval(projectMcpConfigPath(root, client), client),
+		what: "kanbo MCP server"
+	}))];
+}
+function planGlobalEdits() {
+	return [...GLOBAL_INSTRUCTION_CLIENTS.map((client) => ({
+		change: planInstructionBlockRemoval(globalInstructionPath(client)),
+		what: "kanbo instruction block"
+	})), ...["codex", "cursor"].map((client) => ({
+		change: planMcpRemoval(globalMcpConfigPath(client), client),
+		what: "kanbo MCP server"
+	}))];
+}
+function planMcpRemoval(path, client) {
+	return client === "codex" ? planCodexMcpServerRemoval(path) : planJsonMcpServerRemoval(path);
+}
+/**
+* The board file `kanbo init --file` made for this project — the only board
+* `--purge` may offer to delete. A host app's database or an external board is
+* not kanbo's to delete, and a binding that names none offers nothing.
+*/
+function findOwnBoardFile(root) {
+	const binding = findKanboProject(root)?.binding;
+	if (!binding?.dbPath) return null;
+	const path = resolve(root, binding.dbPath);
+	return existsSync(path) ? path : null;
+}
+/** Delete the board file only on a yes to a question that names it; `--yes` is not that answer. */
+async function purgeBoardFile(path) {
+	if (!isInteractive()) return {
+		path,
+		action: "kept",
+		note: "board file: deleting it needs a confirmation in a terminal; delete it yourself if you mean to"
+	};
+	if (await (await import("@clack/prompts")).confirm({
+		message: `Delete the board file ${path} and every card in it? This cannot be undone.`,
+		initialValue: false
+	}) !== true) return {
+		path,
+		action: "kept",
+		note: "board file"
+	};
+	for (const file of [
+		path,
+		`${path}-wal`,
+		`${path}-shm`
+	]) rmSync(file, { force: true });
+	return {
+		path,
+		action: "deleted",
+		note: "board file"
+	};
+}
+function describePlan(edits, claudeUser, bindingPath, boardFile) {
+	const lines = ["kanbo uninstall will:"];
+	for (const edit of edits) lines.push(`  edit    ${edit.change.path}  (remove the ${edit.what})`);
+	if (claudeUser) lines.push(`  run     ${CLAUDE_USER_REMOVE.join(" ")}`);
+	if (bindingPath) lines.push(`  delete  ${bindingPath}`);
+	if (boardFile) lines.push(`  ask     whether to delete the board file ${boardFile} (only in a terminal; --yes does not answer this)`);
+	lines.push("Files stay even when nothing is left in them. Boards stay unless you confirm deleting one.");
+	return lines.join("\n");
+}
+function printActions(actions, options) {
+	if (options.json) {
+		console.log(JSON.stringify({ actions }, null, 2));
+		return;
+	}
+	if (actions.length === 0) {
+		console.log("Nothing to remove: no kanbo block or MCP entry in the files kanbo writes.");
+		return;
+	}
+	for (const action of actions) console.log(`${action.action.padEnd(8)} ${action.path}${action.note ? `  (${action.note})` : ""}`);
+}
+//#endregion
 //#region src/cli/commands/index.ts
 /**
 * Every command the `kanbo` binary answers to, put on one program.
@@ -7797,6 +8735,8 @@ function registerSprintCommands(program) {
 */
 function registerKanboCommands(program) {
 	registerInitCommand(program);
+	registerDoctorCommand(program);
+	registerUninstallCommand(program);
 	registerCapabilitiesCommand(program);
 	registerPrimeCommand(program);
 	registerReadyCommand(program);
@@ -8010,4 +8950,4 @@ function buildCapabilitiesManifest() {
 //#endregion
 export { commentAuthorReference as $, maskDatabaseUrls as A, readEntryRules as B, cardDisplayTitle as C, readProjectBinding as D, readBinding as E, ENTRY_RULES as F, normalizeStatusName as G, readChangeSeq as H, ENTRY_RULE_DESCRIPTIONS as I, BOARD_ACTOR as J, TRACKED_FIELDS as K, UNMET_ENTRY_RULE_REASONS as L, formatExternalSessionRef as M, parseExternalSessionRef as N, writeBinding as O, pullRequestFactKeys as P, activityToken as Q, evaluateEntryRules as R, renderCapabilitiesMarkdown as S, ignoreBoardFile as T, runBoardWrite as U, serializeEntryRules as V, DEFAULT_STATUSES as W, activityKindOrder as X, currentUnixSeconds as Y, activityText as Z, projectKanboPullRequest as _, BOARD_ERROR_RESPONSES as a, isOutsideWriter as at, projectKanboSubCard as b, registerKanboTools as c, formatIssueId as ct, KANBO_MCP_INSTRUCTIONS as d, nextIssueOrder as dt, formatActivityIssueReference as et, KANBO_CAPABILITIES_MARKDOWN_RESOURCE_URI as f, readIssuePrefix as ft, projectKanboColumn as g, projectKanboCard as h, KANBO_TOOL_NAMES as i, readSystemCommentKind as it, createBoardOps as j, maskDatabaseUrl as k, KANBO_TOOLS as l, nextIssueIdentity as lt, registerKanboCapabilitiesResources as m, buildCapabilitiesManifest as n, isEmptyActivityValue as nt, KANBO_MCP_SERVER_NAME as o, normalizeCommentAuthorKind as ot, KANBO_CAPABILITIES_RESOURCE_URI as p, diffFieldChanges as q, KANBO_TOOL_CLI_EQUIVALENTS as r, parseActivityStringArray as rt, createKanboMcpServer as s, toIssueView as st, CAPABILITIES_MANIFEST_VERSION as t, formatPlainActivityValue as tt, buildKanboTools as u, nextIssueNumber as ut, projectKanboRun as v, BINDING_FILE_PATH as w, DEFAULT_BOARD_FILE_PATH as x, projectKanboSprint as y, readChecklist as z };
 
-//# sourceMappingURL=manifest-NRhhhOkC.mjs.map
+//# sourceMappingURL=manifest-mkDJmxt2.mjs.map