kanbo-cli 0.1.2 → 0.2.0

package/dist/lib/{manifest-CmiuDqH-.cjs → manifest-RDyoGrVR.cjs}

@@ -35,9 +35,11 @@ let drizzle_orm_postgres_js_migrator = require("drizzle-orm/postgres-js/migrator
 let postgres = require("postgres");
 postgres = __toESM(postgres, 1);
 let node_url = require("node:url");
+let _modelcontextprotocol_sdk_client_index_js = require("@modelcontextprotocol/sdk/client/index.js");
+let _modelcontextprotocol_sdk_client_stdio_js = require("@modelcontextprotocol/sdk/client/stdio.js");
+let node_child_process = require("node:child_process");
 let _modelcontextprotocol_sdk_server_stdio_js = require("@modelcontextprotocol/sdk/server/stdio.js");
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
-let node_child_process = require("node:child_process");
 let node_http = require("node:http");
 /**
 * Every exit code this tool promises, and what it means — the capabilities
@@ -1924,15 +1926,12 @@ async function approve(store, issueId, input, actor, scope) {
 * leaves even says "returned by you".
 */
 async function returnCard(store, issueId, input, actor, scope) {
-	if (actor.kind !== "user") throw new require_migrations_path.BoardError("board_return_requires_user", {
-		issueId,
-		actorKind: actor.kind
-	});
 	return await runBoardWrite(store, async ({ tx }) => {
+		await ensureDefaultColumns(tx, (await requireCard$1(tx, issueId)).workspaceId, { tx });
+		const target = await assertReturnable(tx, issueId, input, actor);
 		const card = await requireCard$1(tx, issueId);
-		const columns = await ensureDefaultColumns(tx, card.workspaceId, { tx });
 		const updates = {
-			statusId: (input.toStatusName ? await requireColumn(tx, card.workspaceId, input.toStatusName) : previousColumn(columns, card)).id,
+			statusId: target.id,
 			waitingFor: null,
 			updatedAt: currentUnixSeconds()
 		};
@@ -1953,6 +1952,27 @@ async function returnCard(store, issueId, input, actor, scope) {
 		};
 	}, scope);
 }
+/**
+* Every reason `returnCard` would refuse, asked on reads alone, and the column
+* the card would go back to when none applies.
+*
+* `returnCard` asks exactly this inside its write. A caller that has to undo
+* something of its own before the return — stop listening for the approval the
+* card is waiting on, say — asks it first, so a return the board refuses leaves
+* that untouched. The refusals are the same `BoardError` codes: an actor who is
+* not a person (`board_return_requires_user`), a card that is not there
+* (`issue_not_found`), a named column the workspace does not hold
+* (`issue_status_not_found`), and a card already in the first column with no
+* column named (`board_return_no_previous_column`).
+*/
+async function assertReturnable(store, issueId, input, actor) {
+	if (actor.kind !== "user") throw new require_migrations_path.BoardError("board_return_requires_user", {
+		issueId,
+		actorKind: actor.kind
+	});
+	const card = await requireCard$1(store, issueId);
+	return input.toStatusName ? await requireColumn(store, card.workspaceId, input.toStatusName) : previousColumn(await listColumns(store, card.workspaceId), card);
+}
 /** Write a comment on the card, as the actor unless the caller names another author. */
 async function addComment(store, input, actor, scope) {
 	return await runBoardWrite(store, async ({ tx }) => {
@@ -2830,6 +2850,7 @@ function createBoardOps(store) {
 		waitApproval: async (issueId, input, actor, scope) => await waitApproval(store, issueId, input, actor, scope),
 		approve: async (issueId, input, actor, scope) => await approve(store, issueId, input, actor, scope),
 		returnCard: async (issueId, input, actor, scope) => await returnCard(store, issueId, input, actor, scope),
+		assertReturnable: async (issueId, input, actor) => await assertReturnable(store, issueId, input, actor),
 		readApproval: async (issueId) => await readApproval(store, issueId),
 		linkPullRequest: async (issueId, urlOrRef, actor, scope) => await linkPullRequest(store, issueId, urlOrRef, actor, scope),
 		unlinkPullRequest: async (issueId, linkId, actor, scope) => await unlinkPullRequest(store, issueId, linkId, actor, scope),
@@ -4324,77 +4345,103 @@ function readRequestedRules(options) {
 	return options.require.split(",").map((rule) => rule.trim()).filter(Boolean);
 }
 //#endregion
-//#region src/default-board-file-path.ts
+//#region src/package-version.ts
+(0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
 /**
-* Where a board file of a project's own goes when nobody names a path —
-* `kanbo init --file` writes it here, and an app that attaches a project's
-* board file can import the same constant rather than spelling it again.
+* 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 DEFAULT_BOARD_FILE_PATH = (0, node_path.join)(".kanbo", "board.db");
+const KANBO_PACKAGE_VERSION = "0.2.0";
 //#endregion
-//#region src/cli/commands/init.ts
+//#region src/cli/failure.ts
 /**
-* `kanbo init` — tying a project folder to a board, and telling the agents
-* that work in it what the board expects.
+* What a failed command says, and what it leaves with.
 *
-* Three things come out of it, and each is optional except the first: the
-* binding, so no later command has to be told which workspace this is; a block
-* in the project's agent instructions, so an agent reads the board's rules
-* without being handed them; and a registration of the board's MCP server with
-* whichever tools the person actually uses. Nothing is written to a file the
-* person did not ask for, and nothing is written twice.
+* 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.
 */
-/** 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";
+/** How far down a chain of causes is still worth reading. */
+const CAUSE_DEPTH_LIMIT = 5;
 /**
-* 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
-* numbered under a guess carries that guess for the rest of its life.
+* 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.
 */
-const EXTERNAL_WORKSPACE_MESSAGE = "Could not tell which workspace this project is, and an external board holds no workspaces table to look it up in. Run this again with --workspace <id> --identifier <KEY>, or with --db (or KANBO_DB_PATH) naming a host database that knows this project.";
-/** What a person is told when a board file of the project's own and an external one are both named at once. */
-const FILE_AND_DATABASE_URL_MESSAGE = "One board at a time: pass --file for a board file of this project's own or --database-url for an external board, not both.";
+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 require_migrations_path.BoardError && error.code === "board_column_rules_unmet") return {
+		message: describeColumnRefusal(error.details),
+		exitCode: 1
+	};
+	if (error instanceof require_migrations_path.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
+	};
+}
 /**
-* What a person is told when their agents are about to reach the board as its
-* owner. Not a refusal: the board works this way from the first minute, and the
-* rule an agent is missing is one the database keeps, not this command.
+* 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.
 */
-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.";
+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 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.
+* 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.
 */
-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");
+/** The markers that make the block something this tool can find again. */
+const INSTRUCTION_START = "<!-- KANBO_START -->";
+const INSTRUCTION_END = "<!-- KANBO_END -->";
 /**
-* 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
+* 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 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.",
-	"",
+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 "..."\`)`,
@@ -4403,114 +4450,1067 @@ const INSTRUCTION_BLOCK = [
 	`- ${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.",
+	"- 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");
-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) => {
-		const projectDir = process.cwd();
-		if (options.file !== void 0) {
-			await initOwnFile(projectDir, options);
-			return;
-		}
-		const target = resolveInitTarget(projectDir, options);
-		if (target.kind === "postgres") {
-			await initExternalBoard(projectDir, target, options);
-			return;
-		}
-		await runBoardCommand(options, "read", async (session) => await initProject(projectDir, target, session.workspace, options));
-	});
-}
 /**
-* Which board `init` is binding this project to.
+* The block in that file, once.
 *
-* `--db` means something else here than it does in every other command: it
-* names the host database this one reads the workspace off, not the
-* board being bound. So the external board is asked for on its own — the flag,
-* the environment, then the binding this project already has — and only when
-* there is none is the board file itself the board. Always the person's
-* connection string: binding a project is not something an agent does.
+* 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 resolveInitTarget(projectDir, options) {
-	const url = resolveDatabaseUrl({
-		explicitUrl: options.databaseUrl,
-		cwd: projectDir,
-		asAgent: false
-	});
-	return url ? {
-		kind: "postgres",
-		url
-	} : resolveDbTarget({
-		explicitPath: options.db,
-		cwd: projectDir
-	});
+function planInstructionBlock(path, block) {
+	const existing = readText(path);
+	const next = withBlock(existing, block);
+	return {
+		path,
+		next: existing === next ? null : next
+	};
 }
 /**
-* Bind a project to an external board.
-*
-* The board is never opened. `init` is what a person runs *before*
-* `kanbo migrate`, and a database that holds no board yet is not a reason to
-* refuse to write down where it will be — nor could it answer the one question
-* that matters here, since it has no `workspaces` table to be asked.
+* 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.
 */
-async function initExternalBoard(projectDir, target, options) {
-	readFormat(options);
-	printResult(await initProject(projectDir, target, await resolveExternalWorkspace(projectDir, options), options), options);
+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 (0, node_fs.existsSync)(path) ? (0, node_fs.readFileSync)(path, "utf8") : null;
+}
+//#endregion
+//#region src/cli/setup/paths.ts
 /**
-* Create and use a board file of this project's own — `.kanbo/board.db` by
-* default — with no host app and no Postgres anywhere near it.
-*
-* The file is migrated with this package's own chain right here, because
-* nothing else ever will: a host app migrates its own database and an
-* external database is migrated by `kanbo migrate`, but a file of this
-* package's own has no other owner to do it later — `kanbo migrate` runs the
-* same chain again afterwards, and idempotently, for the day it falls behind a
-* newer build (ruling 5-5). The marker written right after is what every later
-* command reads to know not to look for a host `workspaces` table in it
-* (ruling 5-4).
+* Where each agent tool keeps the files kanbo writes into, for one project and
+* for the person's whole machine.
 *
-* The workspace is settled before a single byte is written, and nothing here
-* opens a host database at all (ruling 5-9): this is the one command that has
-* to work on a machine with nothing else installed, and the answer it needs —
-* an id and a card-key stem — is either typed, already in the binding, or the
-* folder's own name. Asking a host database first would turn `--workspace <id>`
-* into a refusal on every machine that has one, and leave a board file behind
-* with no binding beside it.
+* 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.
 */
-async function initOwnFile(projectDir, options) {
-	readFormat(options);
-	if (options.databaseUrl) throw new CliError(1, FILE_AND_DATABASE_URL_MESSAGE);
-	const relativePath = typeof options.file === "string" && options.file.trim() ? options.file.trim() : DEFAULT_BOARD_FILE_PATH;
-	const absolutePath = (0, node_path.resolve)(projectDir, relativePath);
-	const workspace = resolveOwnFileWorkspace(projectDir, options);
-	await createOwnBoardFile(absolutePath);
-	ignoreBoardFile(projectDir, absolutePath);
-	printResult(await initProject(projectDir, {
-		kind: "sqlite",
-		path: absolutePath,
-		owner: "kanbo"
-	}, workspace, options), options);
+/** 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() || (0, node_path.join)((0, node_os.homedir)(), ".codex");
+}
+/** The user-level instruction file of each tool. */
+function globalInstructionPath(client) {
+	switch (client) {
+		case "claude": return (0, node_path.join)((0, node_os.homedir)(), ".claude", "CLAUDE.md");
+		case "codex": return (0, node_path.join)(codexHome(), "AGENTS.md");
+		case "gemini": return (0, node_path.join)((0, node_os.homedir)(), ".gemini", "GEMINI.md");
+	}
 }
 /**
-* Put a migrated, marked board at this path — or leave the folder exactly as it
-* was found (ruling 5-9).
-*
-* A new board is built beside its own path and moved onto it at the end, so a
-* migration that fails half-way leaves no half-built file for the next command
-* to open and believe in. `rename` within one directory is the filesystem's own
-* atomic swap; a temporary name elsewhere would be a copy across devices and
-* not atomic at all. A file that is already there is a different question — it
-* may hold this project's cards — so it is migrated in place, idempotently,
-* which is what makes a second `kanbo init --file` a no-op.
-*
-* A file that is there and is *not* this package's is refused, for the reason
-* any careful host refuses it: migrating a board into somebody's own
-* database leaves it readable but contaminated, and only a different path
-* helps.
+* 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.
 */
-async function createOwnBoardFile(absolutePath) {
-	(0, node_fs.mkdirSync)((0, node_path.dirname)(absolutePath), { recursive: true });
+function globalMcpConfigPath(client) {
+	switch (client) {
+		case "claude": return (0, node_path.join)((0, node_os.homedir)(), ".claude.json");
+		case "codex": return (0, node_path.join)(codexHome(), "config.toml");
+		case "cursor": return (0, node_path.join)((0, node_os.homedir)(), ".cursor", "mcp.json");
+	}
+}
+/** The project-level MCP configuration of each tool. */
+function projectMcpConfigPath(projectDir, client) {
+	switch (client) {
+		case "claude": return (0, node_path.join)(projectDir, ".mcp.json");
+		case "codex": return (0, node_path.join)(projectDir, ".codex", "config.toml");
+		case "cursor": return (0, node_path.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 ((0, node_path.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(node_path.delimiter).filter(Boolean)) for (const extension of extensions) {
+		const candidate = (0, node_path.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 (!(0, node_fs.statSync)(path).isFile()) return false;
+		(0, node_fs.accessSync)(path, node_fs.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 = (0, node_fs.existsSync)(path) ? (0, node_fs.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 (!(0, node_fs.existsSync)(path)) return {
+		path,
+		next: null
+	};
+	const existing = (0, node_fs.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 (!(0, node_fs.existsSync)(path)) return;
+	const text = (0, node_fs.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 = (0, node_child_process.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 (!(0, node_fs.existsSync)(path)) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse((0, node_fs.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 (!(0, node_fs.existsSync)(path)) return null;
+	try {
+		const parsed = JSON.parse((0, node_fs.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 = (0, node_path.resolve)(cwd);
+	while (true) {
+		const kanboDirectory = (0, node_path.join)(directory, (0, node_path.dirname)(BINDING_FILE_PATH));
+		if ((0, node_fs.existsSync)(kanboDirectory) && (0, node_fs.statSync)(kanboDirectory).isDirectory()) return {
+			root: directory,
+			binding: readBinding((0, node_path.join)(directory, BINDING_FILE_PATH))
+		};
+		const parent = (0, node_path.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 = (0, node_path.join)(project.root, BINDING_FILE_PATH);
+	if (!project.binding) return {
+		check: "binding",
+		status: "fail",
+		detail: (0, node_fs.existsSync)(path) ? `${path} is not a binding this build can read.` : `${(0, node_path.join)(project.root, (0, node_path.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 require_migrate.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 require_migrate.openBoardDatabase(target.path);
+	try {
+		require_migrate.assertBoardSchema(board.database);
+		return [{
+			check: "board",
+			status: "ok",
+			detail: `${target.path} opens; its schema is current.`
+		}];
+	} catch (error) {
+		const outdated = error instanceof require_migrations_path.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 = (0, node_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 _modelcontextprotocol_sdk_client_stdio_js.StdioClientTransport({
+		command,
+		args: ["mcp"],
+		cwd: root,
+		env: stringEnvironment(),
+		stderr: "pipe"
+	});
+	let stderr = "";
+	transport.stderr?.on("data", (chunk) => {
+		stderr += chunk.toString();
+	});
+	const client = new _modelcontextprotocol_sdk_client_index_js.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 (0, node_fs.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 —
+* `kanbo init --file` writes it here, and an app that attaches a project's
+* board file can import the same constant rather than spelling it again.
+*/
+const DEFAULT_BOARD_FILE_PATH = (0, node_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"
+	};
+	(0, node_fs.mkdirSync)((0, node_path.dirname)(change.path), { recursive: true });
+	(0, node_fs.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
+* that work in it what the board expects.
+*
+* Three things come out of it, and each is optional except the first: the
+* binding, so no later command has to be told which workspace this is; a block
+* in the project's agent instructions, so an agent reads the board's rules
+* without being handed them; and a registration of the board's MCP server with
+* whichever tools the person actually uses. Nothing is written to a file the
+* person did not ask for, and nothing is written twice.
+*/
+/**
+* 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
+* numbered under a guess carries that guess for the rest of its life.
+*/
+const EXTERNAL_WORKSPACE_MESSAGE = "Could not tell which workspace this project is, and an external board holds no workspaces table to look it up in. Run this again with --workspace <id> --identifier <KEY>, or with --db (or KANBO_DB_PATH) naming a host database that knows this project.";
+/** What a person is told when a board file of the project's own and an external one are both named at once. */
+const FILE_AND_DATABASE_URL_MESSAGE = "One board at a time: pass --file for a board file of this project's own or --database-url for an external board, not both.";
+/**
+* What a person is told when their agents are about to reach the board as its
+* owner. Not a refusal: the board works this way from the first minute, and the
+* 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.";
+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; 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);
+			return;
+		}
+		const target = resolveInitTarget(projectDir, options);
+		if (target.kind === "postgres") {
+			await initExternalBoard(projectDir, target, options);
+			return;
+		}
+		await runBoardCommand(options, "read", async (session) => await initProject(projectDir, target, session.workspace, options));
+	});
+}
+/**
+* Which board `init` is binding this project to.
+*
+* `--db` means something else here than it does in every other command: it
+* names the host database this one reads the workspace off, not the
+* board being bound. So the external board is asked for on its own — the flag,
+* the environment, then the binding this project already has — and only when
+* there is none is the board file itself the board. Always the person's
+* connection string: binding a project is not something an agent does.
+*/
+function resolveInitTarget(projectDir, options) {
+	const url = resolveDatabaseUrl({
+		explicitUrl: options.databaseUrl,
+		cwd: projectDir,
+		asAgent: false
+	});
+	return url ? {
+		kind: "postgres",
+		url
+	} : resolveDbTarget({
+		explicitPath: options.db,
+		cwd: projectDir
+	});
+}
+/**
+* Bind a project to an external board.
+*
+* The board is never opened. `init` is what a person runs *before*
+* `kanbo migrate`, and a database that holds no board yet is not a reason to
+* refuse to write down where it will be — nor could it answer the one question
+* that matters here, since it has no `workspaces` table to be asked.
+*/
+async function initExternalBoard(projectDir, target, options) {
+	readFormat(options);
+	printResult(await initProject(projectDir, target, await resolveExternalWorkspace(projectDir, options), options), options);
+}
+/**
+* Create and use a board file of this project's own — `.kanbo/board.db` by
+* default — with no host app and no Postgres anywhere near it.
+*
+* The file is migrated with this package's own chain right here, because
+* nothing else ever will: a host app migrates its own database and an
+* external database is migrated by `kanbo migrate`, but a file of this
+* package's own has no other owner to do it later — `kanbo migrate` runs the
+* same chain again afterwards, and idempotently, for the day it falls behind a
+* newer build (ruling 5-5). The marker written right after is what every later
+* command reads to know not to look for a host `workspaces` table in it
+* (ruling 5-4).
+*
+* The workspace is settled before a single byte is written, and nothing here
+* opens a host database at all (ruling 5-9): this is the one command that has
+* to work on a machine with nothing else installed, and the answer it needs —
+* an id and a card-key stem — is either typed, already in the binding, or the
+* folder's own name. Asking a host database first would turn `--workspace <id>`
+* into a refusal on every machine that has one, and leave a board file behind
+* with no binding beside it.
+*/
+async function initOwnFile(projectDir, options) {
+	readFormat(options);
+	if (options.databaseUrl) throw new CliError(1, FILE_AND_DATABASE_URL_MESSAGE);
+	const relativePath = typeof options.file === "string" && options.file.trim() ? options.file.trim() : DEFAULT_BOARD_FILE_PATH;
+	const absolutePath = (0, node_path.resolve)(projectDir, relativePath);
+	const workspace = resolveOwnFileWorkspace(projectDir, options);
+	await createOwnBoardFile(absolutePath);
+	ignoreBoardFile(projectDir, absolutePath);
+	printResult(await initProject(projectDir, {
+		kind: "sqlite",
+		path: absolutePath,
+		owner: "kanbo"
+	}, workspace, options), options);
+}
+/**
+* Put a migrated, marked board at this path — or leave the folder exactly as it
+* was found (ruling 5-9).
+*
+* A new board is built beside its own path and moved onto it at the end, so a
+* migration that fails half-way leaves no half-built file for the next command
+* to open and believe in. `rename` within one directory is the filesystem's own
+* atomic swap; a temporary name elsewhere would be a copy across devices and
+* not atomic at all. A file that is already there is a different question — it
+* may hold this project's cards — so it is migrated in place, idempotently,
+* which is what makes a second `kanbo init --file` a no-op.
+*
+* A file that is there and is *not* this package's is refused, for the reason
+* any careful host refuses it: migrating a board into somebody's own
+* database leaves it readable but contaminated, and only a different path
+* helps.
+*/
+async function createOwnBoardFile(absolutePath) {
+	(0, node_fs.mkdirSync)((0, node_path.dirname)(absolutePath), { recursive: true });
 	if ((0, node_fs.existsSync)(absolutePath)) {
 		assertOwnBoardFile(absolutePath);
 		await migrateBoardFileAt(absolutePath);
@@ -4740,9 +5740,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((0, node_path.join)(projectDir, INSTRUCTION_FILES[target]));
+	return applyFileChange(planInstructionBlock((0, node_path.join)(projectDir, PROJECT_INSTRUCTION_FILES[target]), INSTRUCTION_BLOCK));
 }
 async function askInstructionTarget(options) {
 	showBlock(options);
@@ -4776,35 +5776,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 = (0, node_fs.existsSync)(path) ? (0, node_fs.readFileSync)(path, "utf8") : null;
-	const next = buildInstructionFile(existing);
-	if (existing === next) return {
-		path,
-		state: "unchanged"
-	};
-	(0, node_fs.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
@@ -4839,81 +5810,8 @@ async function askMcpClients(options) {
 	return prompts.isCancel(answer) ? [] : answer;
 }
 function registerMcpServer(projectDir, client) {
-	if (client === "codex") return writeCodexMcpServer((0, node_path.join)(projectDir, ".codex", "config.toml"));
-	return writeJsonMcpServer((0, node_path.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"]
-			}
-		}
-	};
-	(0, node_fs.mkdirSync)((0, node_path.dirname)(path), { recursive: true });
-	(0, node_fs.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 (!(0, node_fs.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((0, node_fs.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 = (0, node_fs.existsSync)(path) ? (0, node_fs.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"
-	};
-	(0, node_fs.mkdirSync)((0, node_path.dirname)(path), { recursive: true });
-	(0, node_fs.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}`];
@@ -5186,16 +6084,6 @@ async function createDbTransport(input) {
 	};
 }
 //#endregion
-//#region src/package-version.ts
-(0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
-/**
-* 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";
@@ -5648,74 +6536,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 require_migrations_path.BoardError && error.code === "board_column_rules_unmet") return {
-		message: describeColumnRefusal(error.details),
-		exitCode: 1
-	};
-	if (error instanceof require_migrations_path.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) => {
@@ -6219,21 +7039,6 @@ function sendBoardPage(response, pathname, assets) {
 * reason turned around: the answer will be yes once the card meets them, and
 * `details.unmet` says what is missing.
 *
-* The five failures about where a board is kept read the same rule. A database
-* that holds no board this build can speak for is 409 — the setting is there,
-* the board behind it is not yet, and `board-storage prepare` is what settles
-* that — and one nobody could reach at all is 503, because nothing about the
-* request was wrong. A workspace naming no board at all is 404: the caller
-* asked about a setting that is not there. A board still holding cards when
-* somebody asks to point the workspace elsewhere is 409, because the answer
-* would have been yes on an empty board and `board-storage migrate` is what
-* makes it one. An operation naming cards from two different boards is 400: no
-* transaction reaches both, so the caller asked for something that cannot be
-* done. A copy that would land on a card number or a column name the target
-* already holds under a different id is 409 for the same reason the others
-* are: the answer would have been yes on a target that did not hold that
-* board, and `details.conflicts` names every value that clashed.
-*
 * A failure may also be renamed here: the package names its codes after the
 * board, while every error the `/issues` routes answer with is named after the
 * issue, and a client matching on `issue_*` should not have to learn a second
@@ -6255,10 +7060,6 @@ const BOARD_ERROR_RESPONSES = {
 		message: "The card does not meet what that column asks for yet",
 		code: "issue_column_rules_unmet"
 	},
-	board_copy_conflict: {
-		status: 409,
-		message: "That board already holds cards or columns of this workspace under the same numbers or names; nothing was copied"
-	},
 	board_entry_rule_invalid: {
 		status: 400,
 		message: "Unknown column entry rule"
@@ -6267,10 +7068,6 @@ const BOARD_ERROR_RESPONSES = {
 		status: 400,
 		message: "Execution mode cannot change once the card has been launched"
 	},
-	board_mixed_workspaces: {
-		status: 400,
-		message: "Those cards are not all on the same board"
-	},
 	board_pull_request_invalid: {
 		status: 400,
 		message: "Not a GitHub pull request: give its URL or owner/repo#number"
@@ -6330,22 +7127,6 @@ const BOARD_ERROR_RESPONSES = {
 		status: 400,
 		message: "A sprint cannot start after it is due"
 	},
-	board_storage_not_configured: {
-		status: 404,
-		message: "This workspace names no board storage"
-	},
-	board_storage_not_empty: {
-		status: 409,
-		message: "That board still holds cards of this workspace; move them with migrate before changing where the board is kept"
-	},
-	board_storage_not_prepared: {
-		status: 409,
-		message: "That board has not been prepared yet"
-	},
-	board_storage_unavailable: {
-		status: 503,
-		message: "That board could not be reached"
-	},
 	issue_comment_delete_requires_user: {
 		status: 403,
 		message: "Only a person can delete a comment the board wrote"
@@ -7807,6 +8588,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 ? (0, node_path.join)(projectRoot, BINDING_FILE_PATH) : null;
+	const purgeBinding = bindingPath !== null && (0, node_fs.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) {
+			(0, node_fs.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((0, node_path.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 = (0, node_path.resolve)(root, binding.dbPath);
+	return (0, node_fs.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`
+	]) (0, node_fs.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.
@@ -7820,6 +8738,8 @@ function registerSprintCommands(program) {
 */
 function registerKanboCommands(program) {
 	registerInitCommand(program);
+	registerDoctorCommand(program);
+	registerUninstallCommand(program);
 	registerCapabilitiesCommand(program);
 	registerPrimeCommand(program);
 	registerReadyCommand(program);
@@ -8428,4 +9348,4 @@ Object.defineProperty(exports, "writeBinding", {
 	}
 });
 
-//# sourceMappingURL=manifest-CmiuDqH-.cjs.map
+//# sourceMappingURL=manifest-RDyoGrVR.cjs.map