kanbot 0.2.0 → 0.3.0

package/src/github/app.ts

@@ -0,0 +1,153 @@
+import { createSign } from "node:crypto";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Config } from "../config.ts";
+import { UserError } from "../errors.ts";
+import { Gh, type TokenSource } from "./gh.ts";
+
+const API = "https://api.github.com";
+/** Renew installation tokens this long before GitHub expires them (1 h). */
+const RENEW_MS = 5 * 60_000;
+
+export type AppConfig = NonNullable<Config["identity"]["app"]>;
+
+/** Where `kanbot app create` stores the app's private key. Never in the repo. */
+export function appKeyPath(appId: number) {
+	return join(homedir(), ".kanbot", "apps", `${appId}.pem`);
+}
+
+const b64url = (s: string) => Buffer.from(s).toString("base64url");
+
+/** A short-lived JWT that authenticates as the app itself. */
+export function appJwt(appId: number, key: string, now = Date.now()) {
+	const iat = Math.floor(now / 1000) - 60;
+	const head = b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+	const body = b64url(
+		JSON.stringify({ iat, exp: iat + 9 * 60, iss: String(appId) }),
+	);
+	const sig = createSign("RSA-SHA256")
+		.update(`${head}.${body}`)
+		.sign(key, "base64url");
+	return `${head}.${body}.${sig}`;
+}
+
+async function api<T>(
+	path: string,
+	jwt: string,
+	method = "GET",
+	body?: unknown,
+): Promise<T> {
+	const res = await fetch(`${API}${path}`, {
+		method,
+		headers: {
+			accept: "application/vnd.github+json",
+			authorization: `Bearer ${jwt}`,
+			"x-github-api-version": "2022-11-28",
+		},
+		body: body === undefined ? undefined : JSON.stringify(body),
+	});
+	if (!res.ok)
+		throw new Error(
+			`GitHub ${method} ${path} failed (${res.status}): ${await res.text()}`,
+		);
+	return (await res.json()) as T;
+}
+
+/**
+ * Installation tokens for one repo, cached until shortly before they expire.
+ * Scoped to that repo only.
+ */
+export function appTokens(app: AppConfig, repo: string): TokenSource {
+	const keyFile = appKeyPath(app.id);
+	let cached: { token: string; expires: number } | null = null;
+	let installation: number | null = null;
+	return async () => {
+		if (cached && Date.now() < cached.expires - RENEW_MS) return cached.token;
+		if (!existsSync(keyFile))
+			throw new UserError(`No private key for the kanbot app ${app.slug}.`, {
+				why: `Expected it at ${keyFile}.`,
+				fix: "Run `kanbot app create`, or copy the key there from the machine that created the app.",
+				docs: "identity#app-mode",
+			});
+		const jwt = appJwt(app.id, await Bun.file(keyFile).text());
+		installation ??= await api<{ id: number }>(
+			`/repos/${repo}/installation`,
+			jwt,
+		)
+			.then((r) => r.id)
+			.catch((e) => {
+				throw new UserError(`The kanbot app ${app.slug} can't reach ${repo}.`, {
+					why: String(e),
+					fix: `Install it on the repo: https://github.com/apps/${app.slug}/installations/new`,
+					docs: "identity#app-mode",
+				});
+			});
+		const res = await api<{ token: string; expires_at: string }>(
+			`/app/installations/${installation}/access_tokens`,
+			jwt,
+			"POST",
+			{ repositories: [repo.split("/")[1]] },
+		);
+		cached = { token: res.token, expires: Date.parse(res.expires_at) };
+		return res.token;
+	};
+}
+
+/**
+ * The client kanbot talks as: the app in app mode, otherwise the user's own.
+ * Commits, pushes, board moves and merges always stay on the user's client.
+ */
+export function botClient(config: Config, user: Gh): Gh {
+	const { mode, app } = config.identity;
+	if (mode !== "app") return user;
+	if (!app)
+		throw new UserError("identity.mode is app, but no app is set.", {
+			fix: "kanbot app create",
+			docs: "identity#app-mode",
+		});
+	return new Gh(config.repo, user.dryRun, appTokens(app, config.repo));
+}
+
+// ---- manifest flow --------------------------------------------------------------
+
+/** Permissions the app needs to talk on issues and PRs. Nothing else. */
+export const APP_PERMISSIONS = {
+	issues: "write",
+	pull_requests: "write",
+	contents: "read",
+	metadata: "read",
+} as const;
+
+export function appManifest(name: string, redirectUrl: string) {
+	return {
+		name,
+		url: "https://github.com/mikaelbr/kanbot",
+		redirect_url: redirectUrl,
+		description:
+			"kanbot's voice on GitHub: plans, reviews and replies. Commits stay yours.",
+		public: false,
+		hook_attributes: {
+			url: "https://github.com/mikaelbr/kanbot",
+			active: false,
+		},
+		default_permissions: APP_PERMISSIONS,
+		default_events: [],
+	};
+}
+
+export type CreatedApp = { id: number; slug: string; pem: string };
+
+/** Trade the manifest flow's one-time code for the new app's credentials. */
+export function convertManifest(code: string): Promise<CreatedApp> {
+	return fetch(`${API}/app-manifests/${code}/conversions`, {
+		method: "POST",
+		headers: { accept: "application/vnd.github+json" },
+	}).then(async (res) => {
+		if (!res.ok)
+			throw new Error(
+				`Creating the app failed (${res.status}): ${await res.text()}`,
+			);
+		return (await res.json()) as CreatedApp;
+	});
+}

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/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