kanbo-cli 0.1.1 → 0.1.3

package/dist/lib/{manifest-wdwFSquz.cjs → manifest-BBJIrMw7.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
@@ -2314,32 +2316,61 @@ async function migrateCards(store, input) {
 	};
 }
 //#endregion
-//#region src/ops/prime.ts
-/**
-* The rules of this board, as an agent needs to hear them.
+//#region src/ops/agent-rules.ts
+/**
+* The sentences that tell an agent how to work this board, written once.
+*
+* Four surfaces say them: the text `kanbo prime` returns (`BOARD_RULES`), the
+* block `kanbo init` writes into a project's `CLAUDE.md` / `AGENTS.md`, the
+* `instructions` the `kanbo mcp` server sends when a client connects, and the
+* `kanbo_card_create` tool's description. Each surface adds its own way of
+* doing the thing — a command, a tool name — but the rule itself is read from
+* here, so the four cannot come to say different things.
+*
+* No sentence names a tool or a command: the same text reaches an agent holding
+* MCP tools, one with a command line, and one talking to a server over HTTP.
+*/
+const MOVE_CARD_RULE = "You move the card between columns yourself, at the moment its real state changes. The board never moves a card for you.";
+const STATUS_LINE_RULE = "Write a status line at every step, including before and after anything long-running. One sentence, present tense, about what is happening right now.";
+const WAIT_FOR_PERSON_RULE = "When you need a person, mark the card as waiting for approval and end your turn. You will be told when the answer comes.";
+const PERSON_ONLY_RULE = "Only a person approves a card, and only a person takes one out of waiting. Never do either yourself.";
+const EXECUTION_MODE_RULE = "Each card says where it runs: `worktree` means a separate copy of the project, `main` means the project folder itself. Work in the mode the card names.";
+/** When to split a card at all — said on its own where the surface names the parent its own way. */
+const SUBTASK_WHEN_SENTENCE = "Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go.";
+/** How to split one, with the way this surface names the parent card. */
+function subtaskSplitSentence(parentReference) {
+	return `When you do split a card, make the parts subtasks of it (${parentReference}), not separate top-level cards.`;
+}
+const SUBTASK_RULE = `${SUBTASK_WHEN_SENTENCE} ${subtaskSplitSentence("the parent card's id")}`;
+const PULL_REQUEST_RULE = "Opened a pull request? Link it to the card. Its state and CI checks then reach the card as comments on their own — nothing else tells the board a pull request exists.";
+const OWN_SESSION_RULE = "Started the work yourself, not launched by an app that tracks the run for you? Say so when you start the run — `claude:<session id>` from Claude Code, `codex:<session id>` from Codex (the session id Codex prints) — so your own log of it can be found later.";
+/** Said by the `kanbo init` block and the MCP instructions, which name the comment command or tool beside it. */
+const COMMENT_RULE = "Findings, results, decisions and questions go on the card as comments.";
+/**
+* The rules of this board, as `kanbo prime` says them under its column list.
 *
 * They are about the board and nothing else. The board does not hand out a role, a
 * method or a pipeline — that belongs to the instructions the person wrote for
 * their own agent — so the list stops at what the board itself guarantees and
-* expects. No tool is named either: the same text reaches an agent holding MCP
-* tools, one with a command line, and one talking to a server over HTTP, and each
-* of them already knows what it is holding.
+* expects.
 *
-* Exported because it is also the source `buildCapabilitiesManifest` reads its
-* `rules` from — one list, read by the prompt an agent sees and by the manifest
-* an orchestrator reads about the board.
+* Also the source `buildCapabilitiesManifest` reads its `rules` from — one list,
+* read by the prompt an agent sees and by the manifest an orchestrator reads
+* about the board.
 */
 const BOARD_RULES = [
-	"You move the card between columns yourself, at the moment its real state changes. The board never moves a card for you.",
-	"Write a status line at every step, including before and after anything long-running. One sentence, present tense, about what is happening right now.",
-	"When you need a person, mark the card as waiting for approval and end your turn. You will be told when the answer comes.",
-	"Only a person approves a card, and only a person takes one out of waiting. Never do either yourself.",
-	"Each card says where it runs: `worktree` means a separate copy of the project, `main` means the project folder itself. Work in the mode the card names.",
-	"Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go. When you do split a card, make the parts subtasks of it (the parent card's id), not separate top-level cards.",
-	"Opened a pull request? Link it to the card. Its state and CI checks then reach the card as comments on their own — nothing else tells the board a pull request exists.",
-	"Started the work yourself, not launched by an app that tracks the run for you? Say so when you start the run — `claude:<session id>` from Claude Code, `codex:<session id>` from Codex (the session id Codex prints) — so your own log of it can be found later.",
+	MOVE_CARD_RULE,
+	STATUS_LINE_RULE,
+	WAIT_FOR_PERSON_RULE,
+	PERSON_ONLY_RULE,
+	EXECUTION_MODE_RULE,
+	SUBTASK_RULE,
+	PULL_REQUEST_RULE,
+	OWN_SESSION_RULE,
 	"Read the column descriptions above before moving a card, and do all of this through the board tools or commands you have — a statement in your reply changes nothing."
 ];
+//#endregion
+//#region src/ops/prime.ts
 /**
 * What the board tells an agent about itself: the columns it has, what each one
 * means, and how a card is expected to travel across them.
@@ -4295,211 +4326,1192 @@ 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.1.3";
 //#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.
+* 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.",
 	"",
-	"- Take a card from `kanbo ready`.",
-	"- Move the card yourself (`kanbo card move <id> <column>`) — a card in the wrong column is a lie.",
-	"- Write a status line at every step (`kanbo card status-line <id> --text \"...\"`).",
-	"- Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go. When you do split a card, make the parts subtasks of it (the parent card's id), not separate top-level cards. (`kanbo card create --description \"...\" --parent <id>`).",
-	"- Findings, decisions and questions go on the card (`kanbo card comment <id> --content \"...\"`).",
-	"- When you need a person, run `kanbo card wait-approval <id>` and end your turn. Never approve your own work, and never take a card out of a column where it is waiting for a person.",
-	"- Started the work yourself, not launched by an app that tracks the run? Pass your own session to `kanbo run start --session` — `claude:<session id>` from Claude Code, `codex:<session id>` from Codex (the session id Codex prints).",
-	"- Run `kanbo capabilities` for the full list of tools, commands and rules.",
+	...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 });
-	if ((0, node_fs.existsSync)(absolutePath)) {
-		assertOwnBoardFile(absolutePath);
-		await migrateBoardFileAt(absolutePath);
-		return;
+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");
 	}
-	const temporaryPath = `${absolutePath}.${process.pid}.tmp`;
-	try {
-		await migrateBoardFileAt(temporaryPath);
-		(0, node_fs.renameSync)(temporaryPath, absolutePath);
-	} catch (error) {
-		for (const leftover of [
-			temporaryPath,
-			`${temporaryPath}-wal`,
-			`${temporaryPath}-shm`
-		]) (0, node_fs.rmSync)(leftover, { force: true });
-		throw error;
+}
+/** 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");
 	}
 }
-/** Refuse a file already at the board's path that this package did not write. */
-function assertOwnBoardFile(absolutePath) {
+/**
+* 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);
+		return;
+	}
+	const temporaryPath = `${absolutePath}.${process.pid}.tmp`;
+	try {
+		await migrateBoardFileAt(temporaryPath);
+		(0, node_fs.renameSync)(temporaryPath, absolutePath);
+	} catch (error) {
+		for (const leftover of [
+			temporaryPath,
+			`${temporaryPath}-wal`,
+			`${temporaryPath}-shm`
+		]) (0, node_fs.rmSync)(leftover, { force: true });
+		throw error;
+	}
+}
+/** Refuse a file already at the board's path that this package did not write. */
+function assertOwnBoardFile(absolutePath) {
 	let contents;
 	try {
 		contents = require_migrate.readBoardFileContents(absolutePath);
@@ -4709,9 +5721,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);
@@ -4745,35 +5757,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
@@ -4808,81 +5791,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}`];
@@ -5155,16 +6065,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.1";
-//#endregion
 //#region src/mcp/resources.ts
 /** The URI a client reads the manifest as JSON from. */
 const KANBO_CAPABILITIES_RESOURCE_URI = "kanbo://capabilities";
@@ -5204,6 +6104,36 @@ function registerKanboCapabilitiesResources(server) {
 	}] }));
 }
 //#endregion
+//#region src/mcp/instructions.ts
+/** A tool name as the instructions print it — typed, so a renamed tool fails the build here. */
+function tool(name) {
+	return `\`${name}\``;
+}
+/**
+* What `kanbo mcp` tells a client when it connects — the `instructions` of the
+* MCP initialize result, which a client hands its model before any tool is
+* called. An agent with nothing but this server connected learns from it how
+* to work the board, with no instruction file in the project.
+*
+* Static on purpose: it is sent before any board is resolved, so it says
+* nothing about columns — `kanbo_prime` returns those. The rules are the
+* sentences `ops/agent-rules.ts` holds for every surface, with the tool beside
+* each; the full manifest stays a resource.
+*/
+const KANBO_MCP_INSTRUCTIONS = [
+	"kanbo is a kanban board shared by people and agents; these tools read and change its cards.",
+	"",
+	`- At the start of a session call ${tool("kanbo_prime")} — it returns this board's columns and what each one means.`,
+	`- Take work from ${tool("kanbo_ready")}.`,
+	`- ${MOVE_CARD_RULE} (${tool("kanbo_card_move")})`,
+	`- ${STATUS_LINE_RULE} (${tool("kanbo_status_line")})`,
+	`- ${COMMENT_RULE} (${tool("kanbo_card_comment")})`,
+	`- ${SUBTASK_RULE} (${tool("kanbo_card_create")} with \`parent\`)`,
+	`- ${WAIT_FOR_PERSON_RULE} (${tool("kanbo_wait_approval")})`,
+	`- ${PERSON_ONLY_RULE}`,
+	`- Every tool, rule and canonical string: the resource \`${KANBO_CAPABILITIES_MARKDOWN_RESOURCE_URI}\`.`
+].join("\n");
+//#endregion
 //#region src/mcp/tools/tool.ts
 /**
 * Declare a tool: what it is called, what it takes, and the one thing it does.
@@ -5301,7 +6231,7 @@ const SUBTASK_SENTENCE = "To create a subtask (sub-card) under another card, pas
 const cardCreateTool = defineKanboTool({
 	name: "kanbo_card_create",
 	title: "Create a card",
-	description: `Put a new card on this board. ${SUBTASK_SENTENCE} Create subtasks only when the person asks for them, or when a task has parts that can be done and checked separately (different stages, owners or pull requests); do not split small work you will finish in one go. When you do split a card, make the parts subtasks of it (pass \`parent\`), not separate top-level cards.`,
+	description: `Put a new card on this board. ${SUBTASK_SENTENCE} ${SUBTASK_WHEN_SENTENCE} ${subtaskSplitSentence("pass `parent`")}`,
 	inputSchema: {
 		title: zod.z.string().optional().describe("What the card is called. Leave it out and the card is titled with its own key; the description then says what the task is."),
 		description: zod.z.string().optional().describe("What the card is about, spelled out for whoever picks it up."),
@@ -5573,85 +6503,20 @@ function registerKanboTools(server, transport, options) {
 * function: it documents its capabilities its own way, and adding a second
 * `kanbo://` resource namespace to an inventory that is not only the board's
 * is a decision for that server to make, not this one.
+*
+* For the same reason it alone sends `KANBO_MCP_INSTRUCTIONS` in the initialize
+* result: the instructions of a server that is only the board.
 */
 function createKanboMcpServer(transport, options) {
 	const server = new _modelcontextprotocol_sdk_server_mcp_js.McpServer({
 		name: KANBO_MCP_SERVER_NAME,
 		version: KANBO_MCP_SERVER_VERSION
-	});
+	}, { instructions: KANBO_MCP_INSTRUCTIONS });
 	registerKanboTools(server, transport, options);
 	registerKanboCapabilitiesResources(server);
 	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) => {
@@ -7743,6 +8608,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.
@@ -7756,6 +8758,8 @@ function registerSprintCommands(program) {
 */
 function registerKanboCommands(program) {
 	registerInitCommand(program);
+	registerDoctorCommand(program);
+	registerUninstallCommand(program);
 	registerCapabilitiesCommand(program);
 	registerPrimeCommand(program);
 	registerReadyCommand(program);
@@ -8027,6 +9031,12 @@ Object.defineProperty(exports, "KANBO_CAPABILITIES_RESOURCE_URI", {
 		return KANBO_CAPABILITIES_RESOURCE_URI;
 	}
 });
+Object.defineProperty(exports, "KANBO_MCP_INSTRUCTIONS", {
+	enumerable: true,
+	get: function() {
+		return KANBO_MCP_INSTRUCTIONS;
+	}
+});
 Object.defineProperty(exports, "KANBO_MCP_SERVER_NAME", {
 	enumerable: true,
 	get: function() {
@@ -8358,4 +9368,4 @@ Object.defineProperty(exports, "writeBinding", {
 	}
 });
 
-//# sourceMappingURL=manifest-wdwFSquz.cjs.map
+//# sourceMappingURL=manifest-BBJIrMw7.cjs.map