kanbot 0.1.0 → 0.3.0

package/src/github/gh.ts

@@ -1,15 +1,29 @@
 import { log } from "../log.ts";
 
+/** Returns a GitHub token to use instead of `gh`'s own login. */
+export type TokenSource = () => Promise<string>;
+
 /**
  * Thin wrapper over the `gh` CLI so kanbot reuses the user's existing auth.
+ * With a `token`, calls run as that identity instead (the kanbot app).
  * Reads always run; writes are skipped (and logged) in dry-run mode.
  */
 export class Gh {
 	constructor(
 		readonly repo: string,
 		readonly dryRun = false,
+		private readonly token?: TokenSource,
 	) {}
 
+	/** True when calls run as the kanbot app, not the user. */
+	get isBot() {
+		return this.token !== undefined;
+	}
+
+	private async env() {
+		return this.token ? { GH_TOKEN: await this.token() } : undefined;
+	}
+
 	get owner() {
 		return this.repo.split("/")[0] as string;
 	}
@@ -35,7 +49,11 @@ export class Gh {
 	}
 
 	private async queryOnce<T>(input: string): Promise<T> {
-		const out = await run(["api", "graphql", "--input", "-"], input);
+		const out = await run(
+			["api", "graphql", "--input", "-"],
+			input,
+			await this.env(),
+		);
 		const json = JSON.parse(out) as { data: T; errors?: { message: string }[] };
 		if (json.errors?.length) {
 			throw new Error(
@@ -58,7 +76,9 @@ export class Gh {
 	}
 
 	async rest<T = unknown>(path: string): Promise<T> {
-		return JSON.parse(await run(["api", path])) as T;
+		return JSON.parse(
+			await run(["api", path], undefined, await this.env()),
+		) as T;
 	}
 
 	async restWrite<T = unknown>(
@@ -80,6 +100,7 @@ export class Gh {
 				...(body === undefined ? [] : ["--input", "-"]),
 			],
 			body === undefined ? undefined : JSON.stringify(body),
+			await this.env(),
 		);
 		return (out.trim() ? JSON.parse(out) : null) as T;
 	}
@@ -90,9 +111,14 @@ export class Gh {
 	}
 }
 
-export async function run(args: string[], input?: string): Promise<string> {
+export async function run(
+	args: string[],
+	input?: string,
+	env?: Record<string, string>,
+): Promise<string> {
 	const proc = Bun.spawn(["gh", ...args], {
 		stdin: input === undefined ? "ignore" : new Blob([input]),
+		env: env ? { ...process.env, ...env } : undefined,
 		stdout: "pipe",
 		stderr: "pipe",
 	});

package/src/github/project.ts

@@ -1,4 +1,5 @@
 import { COLUMN_KEYS, type ColumnKey, type Config } from "../config.ts";
+import { UserError } from "../errors.ts";
 import type { Gh } from "./gh.ts";
 
 export type Board = {
@@ -60,7 +61,11 @@ function toBoard(p: RawProject, config: Config): Board {
 
 export async function loadBoard(gh: Gh, config: Config): Promise<Board> {
 	if (!config.project) {
-		throw new Error("No project configured. Run `kanbot board create`.");
+		throw new UserError("No project board configured.", {
+			why: "`project` is not set in .kanbot/config.yml.",
+			fix: "kanbot board create (or kanbot board link --owner <login> --number <n>)",
+			docs: "getting-started#create-the-board",
+		});
 	}
 	const data = await gh.query<{
 		repositoryOwner: { projectV2: RawProject | null } | null;
@@ -74,8 +79,13 @@ export async function loadBoard(gh: Gh, config: Config): Promise<Board> {
 	);
 	const p = data.repositoryOwner?.projectV2;
 	if (!p) {
-		throw new Error(
-			`Project ${config.project.owner}#${config.project.number} not found (does gh have the "project" scope? run: gh auth refresh -s project)`,
+		throw new UserError(
+			`Project ${config.project.owner}#${config.project.number} not found.`,
+			{
+				why: "It does not exist, or your gh token lacks the `project` scope.",
+				fix: "gh auth refresh -s project, then check `project` in .kanbot/config.yml",
+				docs: "getting-started#create-the-board",
+			},
 		);
 	}
 	return toBoard(p, config);

package/src/jobs/prompts.ts

@@ -6,6 +6,7 @@ import {
 	reviewPasses,
 } from "../daemon/derive.ts";
 import type { Comment, Issue, PR } from "../daemon/types.ts";
+import { SIGNATURE } from "../github/api.ts";
 import { extractPlan, isKanbot, stripPlan } from "../github/markers.ts";
 import type { Finding } from "../schemas/results.ts";
 
@@ -36,7 +37,10 @@ function conversation(comments: Comment[], limit = 30) {
 }
 
 function stripMarkers(body: string) {
-	return body.replace(/<!--\s*kanbot[^>]*-->/g, "").trim();
+	return body
+		.replace(SIGNATURE, "")
+		.replace(/<!--\s*kanbot[^>]*-->/g, "")
+		.trim();
 }
 
 /**

package/src/jobs/run.ts

@@ -24,10 +24,12 @@ import {
 	createPR,
 	failedCheckLogs,
 	fetchIssue,
+	mergePR,
 	postComment,
 	react,
 	removeLabel,
 	replyToThread,
+	requestReview,
 	resolveThread,
 	updateIssueBody,
 	updatePRBody,
@@ -62,7 +64,12 @@ import {
 export type JobDeps = {
 	root: string;
 	config: Config;
+	/** The user's own client: reads, board moves, merges. */
 	gh: Gh;
+	/** Who kanbot talks as: comments, labels, PRs. Same as `gh` in user mode. */
+	bot: Gh;
+	/** Login of the user running the daemon. */
+	me: string;
 	board: Board;
 	agents: AgentDef[];
 	provider: Provider;
@@ -145,9 +152,9 @@ export function runJob(job: Job, deps: JobDeps): Promise<void> {
 // ---- plan -------------------------------------------------------------------
 
 async function plan(job: PlanJob, deps: JobDeps) {
-	const { gh } = deps;
+	const { gh, bot } = deps;
 	const { issue } = job.item;
-	await Promise.all(job.comments.map((c) => react(gh, c.id, "EYES")));
+	await Promise.all(job.comments.map((c) => react(bot, c.id, "EYES")));
 	const cwd = await deps.worktrees.detached(worktreeName(job));
 	const result = await runAgent(
 		deps,
@@ -161,13 +168,13 @@ async function plan(job: PlanJob, deps: JobDeps) {
 
 	// Re-read so concurrent human edits to the description are kept.
 	const fresh = await fetchIssue(gh, issue.number);
-	await updateIssueBody(gh, issue.number, withPlan(fresh.body, result.plan));
+	await updateIssueBody(bot, issue.number, withPlan(fresh.body, result.plan));
 
 	const allowed = result.labels.filter(
 		(l) => l === LABELS.technical || l.startsWith(LABELS.typePrefix),
 	);
 	await addLabels(
-		gh,
+		bot,
 		issue.number,
 		allowed.filter((l) => !fresh.labels.includes(l)),
 	);
@@ -175,12 +182,12 @@ async function plan(job: PlanJob, deps: JobDeps) {
 	const created: string[] = [];
 	for (const ni of result.newIssues) {
 		const res = await createIssue(
-			gh,
+			bot,
 			ni.title,
 			`${ni.body}\n\n_Split from #${issue.number} by kanbot._\n${marker("created", issue.number)}`,
 		);
 		if (!res) continue;
-		if (ni.subIssue) await addSubIssue(gh, issue.id, res.node_id);
+		if (ni.subIssue) await addSubIssue(bot, issue.id, res.node_id);
 		await addToBoard(gh, deps.board, res.node_id, ni.column);
 		created.push(`#${res.number}`);
 	}
@@ -206,18 +213,18 @@ async function plan(job: PlanJob, deps: JobDeps) {
 	lines.push(
 		[marker("plan"), ...job.comments.map((c) => marker("re", c.id))].join("\n"),
 	);
-	await postComment(gh, issue.number, lines.join("\n\n"));
-	await Promise.all(job.comments.map((c) => react(gh, c.id, "THUMBS_UP")));
+	await postComment(bot, issue.number, lines.join("\n\n"));
+	await Promise.all(job.comments.map((c) => react(bot, c.id, "THUMBS_UP")));
 }
 
 // ---- implement ----------------------------------------------------------------
 
 async function implement(job: ImplementJob, deps: JobDeps) {
-	const { gh, config, worktrees } = deps;
+	const { gh, bot, config, worktrees } = deps;
 	const { issue } = job.item;
 	if (job.item.column === "ready") {
 		await moveItem(gh, deps.board, job.item.itemId, "inProgress");
-		await addLabels(gh, issue.number, [LABELS.working]);
+		await addLabels(bot, issue.number, [LABELS.working]);
 	}
 
 	const resumed = await worktrees.remoteHas(job.branch);
@@ -240,9 +247,9 @@ async function implement(job: ImplementJob, deps: JobDeps) {
 			implementPrompt(job, config.baseBranch),
 		);
 		if (result.status === "blocked") {
-			await addLabels(gh, issue.number, [LABELS.needsHuman]);
+			await addLabels(bot, issue.number, [LABELS.needsHuman]);
 			await postComment(
-				gh,
+				bot,
 				issue.number,
 				`**Implementation blocked${job.variant ? ` (approach ${job.variant})` : ""}.** ${result.blockedReason ?? ""}\n\nRemove \`${LABELS.needsHuman}\` once resolved and kanbot will retry.\n${marker("blocked", job.branch)}`,
 			);
@@ -292,7 +299,7 @@ async function implement(job: ImplementJob, deps: JobDeps) {
 	]
 		.filter(Boolean)
 		.join("\n\n");
-	const pr = await createPR(gh, {
+	const pr = await createPR(bot, {
 		title: `${result?.prTitle ?? issue.title}${variant}`,
 		body,
 		head: job.branch,
@@ -304,7 +311,7 @@ async function implement(job: ImplementJob, deps: JobDeps) {
 		);
 		if (job.variant !== null)
 			labels.push(`${LABELS.variantPrefix}${job.variant}`);
-		await addLabels(gh, pr.number, labels);
+		await addLabels(bot, pr.number, labels);
 		log.info(`✔ opened ${pr.html_url}`);
 	}
 }
@@ -354,13 +361,13 @@ async function review(job: ReviewJob, deps: JobDeps) {
 		marker("review", job.pass),
 		embedJson("findings", result.findings),
 	].join("\n\n");
-	await postComment(deps.gh, job.pr.number, body);
+	await postComment(deps.bot, job.pr.number, body);
 }
 
 // ---- fix ----------------------------------------------------------------------
 
 async function fix(job: FixJob, deps: JobDeps) {
-	const { gh, worktrees, config } = deps;
+	const { gh, bot, worktrees, config } = deps;
 	const { pr } = job;
 	const cwd = await worktrees.checkout(worktreeName(job), pr.headRefName);
 	if (job.reason.type === "conflict") return mergeBase(job, deps, cwd);
@@ -387,7 +394,7 @@ async function fix(job: FixJob, deps: JobDeps) {
 	if (changed) await worktrees.push(cwd, pr.headRefName);
 	if (result.prBody) {
 		const desc = absoluteImages(result.prBody, config.repo, pr.headRefName);
-		await updatePRBody(gh, pr.number, withDescription(pr.body, desc));
+		await updatePRBody(bot, pr.number, withDescription(pr.body, desc));
 	}
 	const by = new Map(result.addressed.map((a) => [a.ref, a]));
 	const pushed = changed ? "Pushed fixes." : "No code changes.";
@@ -399,7 +406,7 @@ async function fix(job: FixJob, deps: JobDeps) {
 			return `- ${a?.resolved ? "✅" : "⏭️"} **${f.id}** ${a?.reply ?? "Not addressed."}`;
 		});
 		await postComment(
-			gh,
+			bot,
 			pr.number,
 			[
 				`**Addressed agent review ${r.pass}/${reviewPasses(job.item.issue).length}.** ${result.summary} ${pushed}`,
@@ -411,7 +418,7 @@ async function fix(job: FixJob, deps: JobDeps) {
 	}
 	if (r.type === "ci") {
 		await postComment(
-			gh,
+			bot,
 			pr.number,
 			`**CI fix attempt.** ${result.summary} ${pushed}\n\n${marker("ci", pr.headSha)}`,
 		);
@@ -423,11 +430,11 @@ async function fix(job: FixJob, deps: JobDeps) {
 	for (const t of r.threads) {
 		const a = by.get(t.id);
 		await replyToThread(
-			gh,
+			bot,
 			t.id,
 			`${a?.reply ?? "Looked at this but made no change."}\n\n${marker("re", t.id)}`,
 		);
-		if (a?.resolved) await resolveThread(gh, t.id);
+		if (a?.resolved) await resolveThread(bot, t.id);
 		else open++;
 	}
 	if (r.type === "copilot") return;
@@ -438,7 +445,7 @@ async function fix(job: FixJob, deps: JobDeps) {
 			return `> ${excerpt(c.body)}\n\n${a?.reply ?? "Noted."}`;
 		});
 		await postComment(
-			gh,
+			bot,
 			pr.number,
 			[
 				`**Feedback round.** ${result.summary} ${pushed}`,
@@ -452,7 +459,7 @@ async function fix(job: FixJob, deps: JobDeps) {
 		: "All feedback addressed — ready for another look.";
 	if (!r.comments.length)
 		await postComment(
-			gh,
+			bot,
 			pr.number,
 			`${msg} ${pushed}\n\n${marker("feedback-round")}`,
 		);
@@ -469,7 +476,7 @@ const CONFLICT_MARKER = /^(<{7}|>{7})( |$)/m;
 
 /** Merge the base branch into a conflicting PR; the fixer resolves conflicts. */
 async function mergeBase(job: FixJob, deps: JobDeps, cwd: string) {
-	const { gh, worktrees, config } = deps;
+	const { bot, worktrees, config } = deps;
 	const { pr } = job;
 	const base = `origin/${config.baseBranch}`;
 	const files = await worktrees.merge(cwd, base);
@@ -503,7 +510,7 @@ async function mergeBase(job: FixJob, deps: JobDeps, cwd: string) {
 		throw new Error(`${base} was not merged`);
 	await worktrees.push(cwd, pr.headRefName);
 	await postComment(
-		gh,
+		bot,
 		pr.number,
 		`**Merged \`${config.baseBranch}\`.** ${summary}\n\n${marker("conflict", pr.headSha)}`,
 	);
@@ -512,35 +519,68 @@ async function mergeBase(job: FixJob, deps: JobDeps, cwd: string) {
 // ---- deterministic actions ----------------------------------------------------
 
 export async function applyAction(action: Action, deps: JobDeps) {
-	const { gh } = deps;
+	const { gh, bot, config } = deps;
 	switch (action.kind) {
 		case "move":
 			log.info(`#${action.item.issue.number} → ${action.to} (${action.why})`);
 			return moveItem(gh, deps.board, action.item.itemId, action.to);
 		case "label":
-			await addLabels(gh, action.number, action.add);
-			for (const l of action.remove) await removeLabel(gh, action.number, l);
+			await addLabels(bot, action.number, action.add);
+			for (const l of action.remove) await removeLabel(bot, action.number, l);
 			return;
-		case "agentReviewed":
-			await addLabels(gh, action.pr.number, [LABELS.agentReviewed]);
+		case "agentReviewed": {
+			await addLabels(bot, action.pr.number, [LABELS.agentReviewed]);
+			const next =
+				config.merge.onApproval && action.pr.headRefName.startsWith("kanbot/")
+					? "Approve to merge."
+					: "Ready for you to test and merge.";
 			await postComment(
-				gh,
+				bot,
 				action.pr.number,
-				`**Agent review complete.** Ready for you to test and merge.\n\n${marker("ready")}`,
+				`**Agent review complete.** ${next}\n\n${marker("ready")}`,
 			);
+			// The bot opened the PR, so the user can be asked to review it.
+			if (bot.isBot)
+				await requestReview(bot, action.pr.number, [deps.me]).catch((e) =>
+					log.warn(`request review on #${action.pr.number}: ${e}`),
+				);
 			deps.notify.send(
 				`Ready to test: PR #${action.pr.number}`,
 				action.pr.title,
 				action.pr.url,
 			);
 			return;
+		}
+		case "merge": {
+			const { pr } = action;
+			log.info(`merging #${pr.number}, approved by ${action.by}`);
+			try {
+				await mergePR(gh, pr.number, pr.headSha, config.merge.method);
+			} catch (e) {
+				return applyAction(
+					{
+						kind: "needsHuman",
+						number: action.item.issue.number,
+						why: `Approved, but merging #${pr.number} failed:\n\n\`\`\`\n${String(e).slice(0, 1500)}\n\`\`\``,
+					},
+					deps,
+				);
+			}
+			await postComment(
+				bot,
+				pr.number,
+				`**Merged** after approval by @${action.by}.\n\n${marker("merged")}`,
+			);
+			deps.notify.send(`Merged PR #${pr.number}`, pr.title, pr.url);
+			return;
+		}
 		case "compare": {
 			const rows = action.prs.map(
 				(p) =>
 					`| ${p.labels.find((l) => l.startsWith(LABELS.variantPrefix)) ?? "?"} | #${p.number} | ${p.title} |`,
 			);
 			await postComment(
-				gh,
+				bot,
 				action.item.issue.number,
 				`**All ${action.prs.length} approaches are agent-reviewed.** Try them and merge the one you want; the others are closed automatically.\n\n| Variant | PR | Title |\n|---|---|---|\n${rows.join("\n")}\n\n${marker("compare")}`,
 			);
@@ -552,9 +592,9 @@ export async function applyAction(action: Action, deps: JobDeps) {
 			return;
 		}
 		case "needsHuman":
-			await addLabels(gh, action.number, [LABELS.needsHuman]);
+			await addLabels(bot, action.number, [LABELS.needsHuman]);
 			await postComment(
-				gh,
+				bot,
 				action.number,
 				`**kanbot needs a human.** ${action.why}\n\nRemove \`${LABELS.needsHuman}\` to let agents retry.\n${marker("needs-human")}`,
 			);

package/src/known-hashes.json

@@ -19,8 +19,12 @@
 	],
 	".agents/skills/kanbot-admin/SKILL.md": [
 		"3789c559be9fb6a78f82708ae9857395a5556f6b",
+		"557532f241c0fc1e04f03ce8edb69efaa7b5165b",
 		"e427c711b532963c0916f07ecc6b11e9b47cb9fa"
 	],
+	".agents/skills/kanbot-guide/SKILL.md": [
+		"cf3e95d137a5a58a273262bca6ba25fbc95fa037"
+	],
 	".agents/skills/kanbot-idea/SKILL.md": [
 		"8ab28cec8d3f30250ffe080106d0de8e3c2eaa8a"
 	],
@@ -125,6 +129,7 @@
 	"AGENTS.md": [
 		"3da9115cbf52b7b7d0feb8325503a8caf43ff2c7",
 		"b821013b5be7051327b349eda603218590a41f33",
+		"c688ed7f42f7a6f6a5ac600de857b42fb04aa613",
 		"cf7ef593ccfda953055dfb76b3e9c267fc9637f6",
 		"e5b76bcbaf155b79a8ff3f2e70977cc0c589566b"
 	],

package/src/main.ts

@@ -10,6 +10,7 @@ export const main = defineCommand({
 	subCommands: {
 		init: () => import("./commands/init.ts").then((m) => m.default),
 		board: () => import("./commands/board.ts").then((m) => m.default),
+		app: () => import("./commands/app.ts").then((m) => m.default),
 		upgrade: () => import("./commands/upgrade.ts").then((m) => m.default),
 		skills: () => import("./commands/skills.ts").then((m) => m.default),
 		sync: () => import("./commands/sync.ts").then((m) => m.default),

package/src/templates.ts

@@ -24,6 +24,7 @@ export type FileClass = "kanbot" | "user" | "shared";
 const CLASSES: [prefix: string, FileClass][] = [
 	[".github/workflows/kanbot-", "kanbot"],
 	[".agents/skills/kanbot-admin/", "kanbot"],
+	[".agents/skills/kanbot-guide/", "kanbot"],
 	[".agents/skills/kanbot-idea/", "kanbot"],
 	["AGENTS.md", "user"],
 	["CLAUDE.md", "user"],

package/templates/.agents/skills/kanbot-admin/SKILL.md

@@ -1,12 +1,12 @@
 ---
 
 name: kanbot-admin
-description: Maintain this repo's kanbot setup with a human. Use to add or edit kanbot agents, skills or project memory, change `.kanbot/config.yml`, run `kanbot upgrade` or merge `.kanbot-new` files. Not for board jobs.
+description: Change this repo's kanbot setup with a human. Use to add or edit kanbot agents, skills or project memory, change `.kanbot/config.yml`, switch identity mode, turn on merge on approval, run `kanbot upgrade` or merge `.kanbot-new` files. Not for board jobs. For setup walkthroughs and explaining options, use kanbot-guide.
 ---
 
 # kanbot admin
 
-You are helping a human maintain kanbot, the board-driven agent team in this repo. Board agents (planner, implementers, reviewers, fixer) never use this skill.
+You are helping a human maintain kanbot, the board-driven agent team in this repo. Board agents (planner, implementers, reviewers, fixer) never use this skill. To explain options or set kanbot up from scratch, use `kanbot-guide`.
 
 ## Map
 
@@ -14,15 +14,30 @@ You are helping a human maintain kanbot, the board-driven agent team in this rep
 | -------------------------- | -------------------------------------- | ------------------------------- |
 | `.kanbot/agents/<name>.md` | Agent definitions, the source of truth | Yes, then `kanbot sync`         |
 | `.agents/skills/<name>/`   | Skills shared by all agents            | Yes                             |
-| `.kanbot/config.yml`       | Daemon config; schema next to it       | Yes                             |
+| `.kanbot/config.yml`       | Daemon config; schema next to it       | Yes, then restart the daemon    |
 | `.kanbot/manifest.json`    | Template hashes from the last upgrade  | Never by hand                   |
 | `.claude/`, `.codex/`      | Generated by `kanbot sync`             | Never; edit the source and sync |
+| `~/.kanbot/apps/<id>.pem`  | Private key of the kanbot GitHub App   | Never commit                    |
 
-`kanbot <command> --help` lists every flag. Agent frontmatter fields and output schemas: read an existing agent in `.kanbot/agents/` and copy its shape.
+`kanbot <command> --help` lists every flag. `.kanbot/config.schema.json` describes every config field. Docs: https://kanbot.mib.im.
 
 ## Recipes
 
-Finish every recipe with `kanbot sync` when agents changed, then `kanbot doctor`, then show the human the diff. The human commits and pushes; worktrees are made from the pushed base branch, so agents see nothing until then.
+Finish every recipe with `kanbot sync` when agents changed, then `kanbot doctor`, then show the human the diff. The human commits and pushes; worktrees are made from the pushed base branch, so agents see nothing until then. Restart the daemon after config changes.
+
+### Switch to app mode
+
+1. `kanbot app create`. The human clicks **Create GitHub App** on GitHub, then installs it on the repo.
+2. Already have an app from another repo? `kanbot app link --id <id> --slug <slug>`, add the repo to its installation, and copy `~/.kanbot/apps/<id>.pem` if on another machine.
+3. `kanbot doctor` checks the app, its key and the install.
+
+Back to user mode: set `identity.mode: user`.
+
+### Turn on merge on approval
+
+1. Set `merge.onApproval: true` and pick `merge.method` (`squash`, `merge` or `rebase`).
+2. Recommend app mode, so they can approve their own kanbot PRs.
+3. Warn: never enable the branch rule "Require approval of the most recent reviewable push". It blocks their own approval.
 
 ### Add or change an agent
 

package/templates/.agents/skills/kanbot-guide/SKILL.md

@@ -0,0 +1,91 @@
+---
+
+name: kanbot-guide
+description: Explain kanbot and guide a human through it. Use when someone asks what kanbot is, how to set it up in a repo, which config options to pick (provider, bot or user identity, merge on approval, Copilot, notifications), how the board flow works, where something is documented, or why something isn't working. Works before kanbot is installed in the repo. For changing agents, skills or upgrading, use kanbot-admin.
+---
+
+# kanbot guide
+
+You are helping a human understand and set up kanbot: a daemon that runs a team of Claude Code or Codex agents from a GitHub Project board. They write and prioritize issues; agents plan, build, review and fix; they approve plans and merge.
+
+Explain in plain words. Ask before choosing for them; give a recommendation with one line of why. Docs live at https://kanbot.mib.im/<slug>. Link the page instead of repeating it.
+
+## Docs
+
+| Question                                      | Slug                |
+| --------------------------------------------- | ------------------- |
+| How do I install and set up a repo?           | `getting-started`   |
+| How does a card move across the board?        | `workflow`          |
+| How do I file ideas by chatting?              | `capturing-ideas`   |
+| My own PRs, local sessions, direct commits?   | `outside-the-board` |
+| Which agents are there, how do I change them? | `agents`            |
+| Skills and project memory?                    | `skills`            |
+| Claude or Codex?                              | `providers`         |
+| Every config field, labels, notifications     | `configuration`     |
+| Copilot as an extra reviewer                  | `copilot-review`    |
+| Bot or user identity, merge by approving      | `identity`          |
+| Upgrading and `.kanbot-new` files             | `upgrading`         |
+| Every command and flag                        | `usage`             |
+
+## Board flow
+
+Ideas (you write) → Planning (agent plans, you comment) → Ready (you approve by moving the card) → In Progress (agent builds, opens a PR) → Review (two agent reviews with fixes; you comment) → Done (you merge, or approve and kanbot merges).
+
+Agents never get a GitHub token. The daemon does every comment, push and PR. Only collaborators with write access can steer agents.
+
+## Guided setup
+
+Go step by step. Run each command, check its output, then go on. If `.kanbot/config.yml` exists, run `kanbot doctor` first and skip what passes.
+
+1. **Requirements.** Bun 1.3+, `gh` logged in, `claude` or `codex` logged in with a subscription (not an API key). Run `gh auth refresh -s project`.
+2. **Provider.** Ask which subscription they have, then `bunx kanbot init --provider claude|codex` in the repo root.
+3. **Conventions.** Fill in `.agents/skills/project-conventions/SKILL.md` with them: stack, commands to test, lint and typecheck. Adjust `.github/workflows/ci.yml` to run the same. Every agent reads this first.
+4. **Board.** `kanbot board create`, or `kanbot board link --owner <login> --number <n>` for an existing project. Have them enable the four built-in project workflows it prints; they can't be set through the API.
+5. **Options.** Go through [Choose options](#choose-options). For app mode, run `kanbot app create` and have them install the app on the repo.
+6. **Commit and push** the kanbot files. Agents only see what's on the pushed base branch.
+7. **Check.** `kanbot doctor` until it passes, then `kanbot run --once --dry-run`, then `kanbot run`.
+8. **First card.** Have them write an issue, put it in Planning and read the plan. Point to `workflow`.
+
+## Choose options
+
+Ask only about what matters to them. Defaults are fine for the rest. Options live in `.kanbot/config.yml`; restart the daemon after changes.
+
+| Option                             | Ask                                                       | Recommend                                                                                                                       |
+| ---------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `identity.mode` (`user` \| `app`)  | Should kanbot talk as you, or as its own bot?             | `app`: clear who said what, GitHub notifies you, and you can approve its PRs. `user` for zero setup. Commits are yours in both. |
+| `merge.onApproval`, `merge.method` | Merge by approving the PR, or press merge yourself?       | `true` with `app` mode. In `user` mode only another collaborator can approve.                                                   |
+| `provider`                         | Claude or ChatGPT subscription?                           | Whichever they pay for.                                                                                                         |
+| `concurrency`                      | How many agents at once?                                  | Default 3. Lower on a small machine or near usage limits.                                                                       |
+| `review.copilot`                   | Want GitHub Copilot as an extra reviewer? (costs credits) | Off unless they have a paid Copilot plan.                                                                                       |
+| `notify.desktop`, `notify.webhook` | Where do you want to hear that a PR is ready?             | Desktop. Add an ntfy.sh webhook for phone alerts.                                                                               |
+| `codex.networkAccess`              | Do agents need to install packages? (Codex only)          | Off unless installs fail.                                                                                                       |
+| `explore:N` label                  | Want several approaches built for some issues?            | Per issue, not config.                                                                                                          |
+
+### Who does what
+
+| Action                                    | `user` mode            | `app` mode   |
+| ----------------------------------------- | ---------------------- | ------------ |
+| Comments, PRs, labels, issue and PR edits | User, `🤖 kanbot` line | `<app>[bot]` |
+| Commits, pushes, merges, board moves      | User                   | User         |
+
+Board moves stay on the user's account: GitHub Apps can't use boards owned by a personal account.
+
+### App mode
+
+- `kanbot app create` opens GitHub; they click **Create GitHub App**, then install it on the repo. The key goes in `~/.kanbot/apps/<id>.pem`; never commit it.
+- Same app in another repo: `kanbot app link --id <id> --slug <slug>`, then add the repo to the app's installation.
+- Back to user mode: `identity.mode: user`.
+
+### Merge on approval
+
+kanbot merges, as the user, only `kanbot/*` PRs that are agent-reviewed, approved on the latest commit by a collaborator, with no open change request, passing checks, no conflicts and no `needs-human`. A push after approval needs a new approval.
+
+Warn: never enable the branch rule "Require approval of the most recent reviewable push". The user's account pushes kanbot's commits, so it blocks their own approval.
+
+## Troubleshoot
+
+1. `kanbot doctor`: prints a fix for each failed check.
+2. `kanbot status`: board by column, daemon, failures, rate-limit pause.
+3. `.kanbot/logs/*.jsonl`: full agent transcripts.
+4. `needs-human` label: the issue has a comment saying why. Fix the cause, then remove the label to retry.
+5. Nothing happens: is the daemon running, are kanbot files pushed to the base branch, is the card in an active column?

package/templates/AGENTS.md

@@ -13,7 +13,7 @@ Board flow:
 3. **Ready**: a human approves the plan by moving the card here.
 4. **In Progress**: an `implementer-*` agent builds the plan on a branch and commits.
 5. **Review**: `reviewer-code`, then `reviewer-spec`, then `fixer` for findings, human review comments, failing CI and merge conflicts.
-6. **Done**: a human merges.
+6. **Done**: a human merges, or approves and the daemon merges.
 
 ## Golden rules