kanbot 0.1.0 → 0.2.0

package/README.md

@@ -101,3 +101,13 @@ bun test
 pnpm check
 pnpm typecheck
 ```
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org). A `commit-msg` hook and CI lint them.
+
+### Releasing
+
+1. Merge or push conventional commits to `main`.
+2. A draft release updates with the next version and notes. `feat` bumps minor, `fix` patch. On 0.x, breaking changes bump minor.
+3. Publish the draft on GitHub. This tags the commit, publishes to npm with provenance, and commits the version to `package.json` on `main`.
+
+Preview the next release with `pnpm release:preview`. Mark the draft as a pre-release to publish under the `next` tag.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kanbot",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Run an autonomous dev team (Claude Code or Codex) from a GitHub Project board",
 	"type": "module",
 	"license": "MIT",
@@ -41,7 +41,9 @@
 		"docs:dev": "pnpm --dir site dev",
 		"docs:build": "pnpm --dir site build",
 		"hashes": "bun scripts/known-hashes.ts",
-		"prepublishOnly": "bun run check && bun run typecheck && bun test"
+		"prepublishOnly": "bun run check && bun run typecheck && bun test",
+		"prepare": "lefthook install",
+		"release:preview": "git-cliff --unreleased --bump --strip all && git-cliff --bumped-version"
 	},
 	"dependencies": {
 		"citty": "^0.2.2",
@@ -51,7 +53,24 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.6.4",
+		"@commitlint/cli": "^21.2.4",
+		"@commitlint/config-conventional": "^21.2.4",
 		"@types/bun": "^1.4.4",
+		"git-cliff": "^2.14.2",
+		"lefthook": "^2.2.2",
 		"typescript": "^7.0.2"
+	},
+	"commitlint": {
+		"extends": [
+			"@commitlint/config-conventional"
+		],
+		"rules": {
+			"body-max-line-length": [
+				0
+			],
+			"footer-max-line-length": [
+				0
+			]
+		}
 	}
 }

package/src/agents/load.ts

@@ -1,7 +1,9 @@
+import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { parse } from "yaml";
 import { z } from "zod";
+import { UserError } from "../errors.ts";
 import { RESULT_SCHEMAS } from "../schemas/results.ts";
 
 export const TOOL_CAPABILITIES = ["read", "edit", "bash", "web"] as const;
@@ -34,16 +36,23 @@ export function agentsDir(root: string) {
 
 export function parseAgent(text: string, file: string): AgentDef {
 	const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-	if (!m) throw new Error(`${file}: missing YAML frontmatter`);
+	if (!m) throw invalid(file, "Missing YAML frontmatter between `---` lines.");
 	const fm = Frontmatter.safeParse(parse(m[1] as string));
 	if (!fm.success) {
-		throw new Error(`${file}: ${z.prettifyError(fm.error)}`);
+		throw invalid(file, z.prettifyError(fm.error));
 	}
 	return { ...fm.data, body: (m[2] as string).trim(), file };
 }
 
 export async function loadAgents(root: string): Promise<AgentDef[]> {
 	const dir = agentsDir(root);
+	if (!existsSync(dir)) {
+		throw new UserError("kanbot agents are missing.", {
+			why: "No .kanbot/agents directory in this repo.",
+			fix: "kanbot init (or kanbot upgrade to restore missing files)",
+			docs: "getting-started#set-up-a-repository",
+		});
+	}
 	const files = (await readdir(dir)).filter((f) => f.endsWith(".md")).sort();
 	const agents = await Promise.all(
 		files.map(async (f) =>
@@ -57,25 +66,38 @@ export async function loadAgents(root: string): Promise<AgentDef[]> {
 function validate(agents: AgentDef[]) {
 	const names = new Set(agents.map((a) => a.name));
 	if (names.size !== agents.length) {
-		throw new Error("Duplicate agent names in .kanbot/agents");
+		throw new UserError("Duplicate agent names in .kanbot/agents.", {
+			why: "Two agent files declare the same `name`.",
+			fix: "Give each agent a unique name matching its filename.",
+			docs: "agents#frontmatter",
+		});
 	}
 	for (const a of agents) {
 		if (!a.file.endsWith(`${a.name}.md`)) {
-			throw new Error(`${a.file}: name "${a.name}" must match the filename`);
+			throw invalid(a.file, `name "${a.name}" must match the filename.`);
 		}
 		if (a.tier === "column" && !a.output) {
-			throw new Error(`${a.file}: column agents must declare an output schema`);
+			throw invalid(a.file, "Column agents must declare an `output` schema.");
 		}
 		for (const s of a.subagents) {
 			const sub = agents.find((x) => x.name === s);
-			if (!sub) throw new Error(`${a.file}: unknown subagent "${s}"`);
+			if (!sub)
+				throw invalid(a.file, `Unknown subagent "${s}" in \`subagents\`.`);
 			if (sub.tier !== "sub") {
-				throw new Error(`${a.file}: "${s}" is not a tier: sub agent`);
+				throw invalid(a.file, `Subagent "${s}" must have \`tier: sub\`.`);
 			}
 		}
 	}
 }
 
+function invalid(file: string, why: string) {
+	return new UserError(`Invalid agent file ${file}`, {
+		why,
+		fix: "Fix the file, then run `kanbot sync`.",
+		docs: "agents#frontmatter",
+	});
+}
+
 export function getAgent(agents: AgentDef[], name: string): AgentDef {
 	const a = agents.find((x) => x.name === name);
 	if (!a) throw new Error(`No agent named "${name}" in .kanbot/agents`);

package/src/agents/sync.ts

@@ -3,6 +3,7 @@ import { mkdir, readdir, rm, symlink } from "node:fs/promises";
 import { join } from "node:path";
 import { stringify } from "yaml";
 import { configPath, loadConfig } from "../config.ts";
+import { UserError } from "../errors.ts";
 import type { AgentDef } from "./load.ts";
 
 /*
@@ -205,9 +206,11 @@ async function linkSkills(root: string, check: boolean) {
 	const ok = existsSync(link) && lstatSync(link).isSymbolicLink();
 	if (ok || check) return ok;
 	if (existsSync(link)) {
-		throw new Error(
-			".claude/skills exists and is not a symlink. Move its skills into .agents/skills.",
-		);
+		throw new UserError("Cannot link .claude/skills.", {
+			why: ".claude/skills exists and is not a symlink. kanbot keeps skills in .agents/skills and links to them.",
+			fix: "Move its skills into .agents/skills, delete .claude/skills, then rerun.",
+			docs: "skills#add-a-skill",
+		});
 	}
 	await mkdir(join(root, ".agents", "skills"), { recursive: true });
 	await mkdir(join(root, ".claude"), { recursive: true });

package/src/cli.ts

@@ -1,5 +1,27 @@
 #!/usr/bin/env bun
-import { runMain } from "citty";
+import { runCommand, runMain } from "citty";
+import { formatError } from "./errors.ts";
 import { main } from "./main.ts";
 
-runMain(main);
+const args = process.argv.slice(2);
+const usage =
+	!args.length ||
+	args.some((a) => a === "--help" || a === "-h") ||
+	(args.length === 1 && (args[0] === "--version" || args[0] === "-v"));
+
+// citty prints usage for help, version and a bare `kanbot`.
+if (usage) {
+	await runMain(main);
+} else {
+	try {
+		await runCommand(main, { rawArgs: args });
+	} catch (e) {
+		// Leading positionals name the command, e.g. "board create".
+		const end = args.findIndex((a) => a.startsWith("-"));
+		const command = args.slice(0, end < 0 ? undefined : end).join(" ");
+		console.error(
+			formatError(e, { debug: !!process.env.KANBOT_DEBUG, command }),
+		);
+		process.exit(1);
+	}
+}

package/src/commands/completion.ts

@@ -1,6 +1,7 @@
 import { basename } from "node:path";
 import { defineCommand } from "citty";
 import { buildSpec, render, SHELLS, type Shell } from "../completion.ts";
+import { UserError } from "../errors.ts";
 
 export default defineCommand({
 	meta: {
@@ -17,7 +18,12 @@ export default defineCommand({
 	async run({ args }) {
 		const shell = args.shell ?? basename(process.env.SHELL ?? "");
 		if (!SHELLS.includes(shell as Shell))
-			throw new Error(`Pass --shell ${SHELLS.join("|")}`);
+			throw new UserError("Could not detect your shell.", {
+				why: `$SHELL is "${shell}", which is not supported.`,
+				fix: `kanbot completion --shell ${SHELLS.join("|")}`,
+				docs: "getting-started#shell-completion",
+				more: "",
+			});
 		const { main } = await import("../main.ts");
 		process.stdout.write(render(shell as Shell, await buildSpec(main)));
 	},

package/src/commands/doctor.ts

@@ -5,6 +5,7 @@ import { loadAgents } from "../agents/load.ts";
 import { sync } from "../agents/sync.ts";
 import { loadConfig, writeConfigSchema } from "../config.ts";
 import { git } from "../daemon/git.ts";
+import { describeError } from "../errors.ts";
 import { copilotReviewRule } from "../github/api.ts";
 import { Gh, run } from "../github/gh.ts";
 import {
@@ -27,6 +28,16 @@ async function cmd(args: string[]) {
 	return { ok: code === 0, out: `${out}${err}`.trim() };
 }
 
+/** Failure detail and fix for a check, from a thrown error. */
+function explain(e: unknown, fallback?: string) {
+	const d = describeError(e);
+	const detail = [d.message, d.why].filter(Boolean).join("\n");
+	return {
+		detail: detail.replace(/\n/g, "\n    "),
+		fix: d.fix ?? fallback,
+	};
+}
+
 export default defineCommand({
 	meta: {
 		name: "doctor",
@@ -59,7 +70,7 @@ export default defineCommand({
 				detail: `${config.repo}, provider ${config.provider}`,
 			});
 		} catch (e) {
-			add({ name: "config", ok: false, detail: String(e), fix: "kanbot init" });
+			add({ name: "config", ok: false, ...explain(e, "kanbot init") });
 			return process.exit(1);
 		}
 
@@ -119,7 +130,7 @@ export default defineCommand({
 				fix: "kanbot sync",
 			});
 		} catch (e) {
-			add({ name: "agents", ok: false, detail: String(e) });
+			add({ name: "agents", ok: false, ...explain(e) });
 		}
 
 		const plan = await planUpgrade(root);
@@ -197,8 +208,7 @@ export default defineCommand({
 			add({
 				name: "project board",
 				ok: false,
-				detail: String(e),
-				fix: "kanbot board create",
+				...explain(e, "kanbot board create"),
 			});
 		}
 

package/src/commands/init.ts

@@ -4,6 +4,7 @@ import { defineCommand } from "citty";
 import { loadAgents } from "../agents/load.ts";
 import { sync } from "../agents/sync.ts";
 import { configPath, saveConfig, writeConfigSchema } from "../config.ts";
+import { UserError } from "../errors.ts";
 import { run } from "../github/gh.ts";
 import { log } from "../log.ts";
 import { applyUpgrade, NEW_SUFFIX, planUpgrade } from "../templates.ts";
@@ -32,9 +33,31 @@ export default defineCommand({
 	async run({ args }) {
 		const root = process.cwd();
 		if (!existsSync(join(root, ".git")))
-			throw new Error("Run inside a git repository.");
+			throw new UserError("Not a git repository.", {
+				why: `No .git in ${root}. Run init from the repo root.`,
+				fix: "cd into your repo's root, or run `git init`.",
+				docs: "getting-started#set-up-a-repository",
+				more: "",
+			});
 		if (!["claude", "codex"].includes(args.provider))
-			throw new Error("--provider must be claude or codex");
+			throw new UserError(`Unknown provider "${args.provider}".`, {
+				fix: "kanbot init --provider claude|codex",
+				docs: "providers#choose-a-provider",
+				more: "",
+			});
+
+		// Fail on gh or remote problems before writing anything.
+		const repo =
+			!existsSync(configPath(root)) || args.force
+				? (JSON.parse(
+						await run([
+							"repo",
+							"view",
+							"--json",
+							"nameWithOwner,defaultBranchRef",
+						]),
+					) as { nameWithOwner: string; defaultBranchRef: { name: string } })
+				: null;
 
 		const plan = await planUpgrade(root, { force: args.force });
 		await applyUpgrade(root, plan);
@@ -47,13 +70,7 @@ export default defineCommand({
 		}
 		log.info("+ .kanbot/manifest.json");
 
-		if (!existsSync(configPath(root)) || args.force) {
-			const repo = JSON.parse(
-				await run(["repo", "view", "--json", "nameWithOwner,defaultBranchRef"]),
-			) as {
-				nameWithOwner: string;
-				defaultBranchRef: { name: string };
-			};
+		if (repo) {
 			await saveConfig(root, {
 				provider: args.provider as "claude" | "codex",
 				repo: repo.nameWithOwner,

package/src/commands/status.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { defineCommand } from "citty";
 import { COLUMN_KEYS, LABELS, loadConfig } from "../config.ts";
 import { State } from "../daemon/state.ts";
-import { Gh } from "../github/gh.ts";
+import { Gh, run } from "../github/gh.ts";
 import { listItems, loadBoard } from "../github/project.ts";
 
 export default defineCommand({
@@ -38,7 +38,16 @@ export default defineCommand({
 		}
 
 		const needsHuman = JSON.parse(
-			await Bun.$`gh issue list --repo ${config.repo} --label ${LABELS.needsHuman} --json number,title`.text(),
+			await run([
+				"issue",
+				"list",
+				"--repo",
+				config.repo,
+				"--label",
+				LABELS.needsHuman,
+				"--json",
+				"number,title",
+			]),
 		) as { number: number; title: string }[];
 		if (needsHuman.length) {
 			console.log(

package/src/config.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { parse, parseDocument } from "yaml";
 import { z } from "zod";
+import { UserError } from "./errors.ts";
 
 export const COLUMN_KEYS = [
 	"ideas",
@@ -197,9 +198,35 @@ export async function writeConfigSchema(
 export async function loadConfig(root: string): Promise<Config> {
 	const path = configPath(root);
 	if (!existsSync(path)) {
-		throw new Error(`No ${path}. Run \`kanbot init\` first.`);
+		throw new UserError("kanbot is not set up in this repo.", {
+			why: "No .kanbot/config.yml in this directory.",
+			fix: "kanbot init",
+			docs: "getting-started#set-up-a-repository",
+		});
 	}
-	return ConfigSchema.parse(parse(await Bun.file(path).text()) ?? {});
+	let raw: unknown;
+	try {
+		raw = parse(await Bun.file(path).text());
+	} catch (e) {
+		throw new UserError(
+			".kanbot/config.yml is not valid YAML.",
+			{
+				why: (e as Error).message.trim(),
+				fix: "Fix the syntax at the line shown above.",
+				docs: "configuration#config-file",
+			},
+			{ cause: e },
+		);
+	}
+	const config = ConfigSchema.safeParse(raw ?? {});
+	if (!config.success) {
+		throw new UserError(".kanbot/config.yml has invalid values.", {
+			why: z.prettifyError(config.error),
+			fix: "Fix the fields above. .kanbot/config.schema.json lists allowed values.",
+			docs: "configuration#config-file",
+		});
+	}
+	return config.data;
 }
 
 /** Sets top-level keys, keeping the user's comments and formatting. */

package/src/daemon/lock.ts

@@ -1,5 +1,6 @@
 import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { UserError } from "../errors.ts";
 
 /** One daemon per repo. Stale locks (dead pid) are taken over. */
 export async function acquireLock(root: string): Promise<() => void> {
@@ -7,7 +8,11 @@ export async function acquireLock(root: string): Promise<() => void> {
 	if (existsSync(file)) {
 		const pid = Number(await Bun.file(file).text());
 		if (pid && isAlive(pid)) {
-			throw new Error(`kanbot is already running for this repo (pid ${pid})`);
+			throw new UserError("kanbot is already running for this repo.", {
+				why: `Process ${pid} holds .kanbot/daemon.pid. Only one daemon runs per repo.`,
+				fix: `Stop it with \`kill ${pid}\`, or check it with \`kanbot status\`.`,
+				docs: "usage#kanbot-run",
+			});
 		}
 	}
 	await Bun.write(file, String(process.pid));

package/src/daemon/loop.ts

@@ -1,6 +1,7 @@
 import { loadAgents } from "../agents/load.ts";
 import { sync } from "../agents/sync.ts";
 import { type Config, loadConfig } from "../config.ts";
+import { UserError } from "../errors.ts";
 import { Gh } from "../github/gh.ts";
 import { loadBoard, missingColumns } from "../github/project.ts";
 import { Trust } from "../github/trust.ts";
@@ -45,7 +46,11 @@ export async function runDaemon(root: string, opts: RunOptions) {
 	const board = await loadBoard(gh, config);
 	const missing = missingColumns(board);
 	if (missing.length)
-		throw new Error(`Board is missing columns: ${missing.join(", ")}`);
+		throw new UserError("The project board is missing columns.", {
+			why: `No Status option for: ${missing.map((k) => config.columns[k]).join(", ")}.`,
+			fix: "kanbot board create adds them. Or match `columns` in .kanbot/config.yml to your board.",
+			docs: "configuration#columns",
+		});
 
 	const release = opts.dryRun ? () => {} : await acquireLock(root);
 	const state = await new State(root).load();

package/src/errors.ts

@@ -0,0 +1,171 @@
+export const DOCS_URL = "https://kanbot.mib.im";
+const ISSUES_URL = "https://github.com/mikaelbr/kanbot/issues";
+
+export type ErrorHelp = {
+	/** Why it failed: the underlying error or the rule that was broken. */
+	why?: string;
+	/** What to do about it, usually a command. */
+	fix?: string;
+	/** Docs page and anchor, e.g. "configuration#config-file". */
+	docs?: string;
+	/** How to learn more. Defaults to `kanbot doctor`; "" hides it. */
+	more?: string;
+};
+
+/** An expected failure. Printed without a stack trace. */
+export class UserError extends Error {
+	constructor(
+		message: string,
+		readonly help: ErrorHelp = {},
+		options?: ErrorOptions,
+	) {
+		super(message, options);
+		this.name = "UserError";
+	}
+}
+
+const INSTALL: Record<string, ErrorHelp> = {
+	gh: {
+		fix: "Install the GitHub CLI from https://cli.github.com, then run `gh auth login`.",
+		docs: "getting-started#requirements",
+	},
+	git: {
+		fix: "Install git from https://git-scm.com/downloads.",
+		docs: "getting-started#requirements",
+	},
+	claude: {
+		fix: "Install Claude Code, then run `claude auth login`.",
+		docs: "providers#claude-code",
+	},
+	codex: {
+		fix: "Install Codex (npm i -g @openai/codex), then run `codex login`.",
+		docs: "providers#codex",
+	},
+};
+
+/** Known failures from gh, git and the GitHub API, matched on message. */
+const KNOWN: [RegExp, string, ErrorHelp][] = [
+	[
+		/gh auth login|not logged in|HTTP 401|Bad credentials/i,
+		"GitHub CLI is not logged in.",
+		{ fix: "gh auth login", docs: "getting-started#requirements" },
+	],
+	[
+		/INSUFFICIENT_SCOPES|required scopes|scope.*project/i,
+		"GitHub token is missing the `project` scope.",
+		{ fix: "gh auth refresh -s project", docs: "getting-started#requirements" },
+	],
+	[
+		/rate limit/i,
+		"GitHub API rate limit reached.",
+		{ fix: "Wait a few minutes and try again." },
+	],
+	[
+		/Could not resolve to a ProjectV2/i,
+		"Project board not found.",
+		{
+			fix: "Check `project` in .kanbot/config.yml, or run `kanbot board create`.",
+			docs: "getting-started#create-the-board",
+		},
+	],
+	[
+		/Could not resolve to a Repository|HTTP 404/i,
+		"GitHub repository not found, or gh has no access to it.",
+		{
+			fix: "Check `repo` in .kanbot/config.yml and run `gh repo view <owner/name>`.",
+			docs: "configuration#config-file",
+		},
+	],
+	[
+		/not a git repository/i,
+		"Not inside a git repository.",
+		{ fix: "cd into your repo, or run `git init`." },
+	],
+	[
+		/no git remotes|none of the git remotes/i,
+		"This repo has no GitHub remote.",
+		{
+			fix: "git remote add origin <url> && git push -u origin HEAD",
+			docs: "getting-started#set-up-a-repository",
+		},
+	],
+	[
+		/ENOTFOUND|ECONNREFUSED|ETIMEDOUT|dial tcp|error connecting/i,
+		"Could not reach GitHub.",
+		{ fix: "Check your network connection and try again." },
+	],
+];
+
+export type Described = ErrorHelp & { message: string; expected: boolean };
+
+export function describeError(e: unknown, command = ""): Described {
+	if (e instanceof UserError)
+		return { message: e.message, ...e.help, expected: true };
+	if (!(e instanceof Error)) return { message: String(e), expected: false };
+	const raw = e.message.trim();
+
+	// citty argument errors: unknown command, bad flag value, …
+	if (e.name === "CLIError") {
+		const unknown = (e as { code?: string }).code === "E_UNKNOWN_COMMAND";
+		return {
+			message: Bun.stripANSI(raw),
+			fix: `Run \`kanbot ${unknown ? "" : `${command} `}--help\` to see valid options.`,
+			docs: "usage",
+			more: "",
+			expected: true,
+		};
+	}
+
+	const bin = raw.match(/Executable not found in \$PATH: "(.+)"/)?.[1];
+	if (bin)
+		return {
+			message: `\`${bin}\` is not installed or not on PATH.`,
+			why: raw,
+			...INSTALL[bin],
+			expected: true,
+		};
+
+	const known = KNOWN.find(([re]) => re.test(raw));
+	if (known)
+		return { message: known[1], why: raw, ...known[2], expected: true };
+	const tool = raw.match(/^(gh|git) .* failed/)?.[1];
+	if (tool)
+		return {
+			message: `A \`${tool}\` command failed.`,
+			why: raw,
+			fix:
+				tool === "gh"
+					? "Read the gh error above. `gh auth status` shows login and scopes."
+					: "Read the git error above. `git status` shows the repo state.",
+			expected: true,
+		};
+	return { message: raw, expected: false };
+}
+
+const indent = (s: string) => s.replace(/^(?=.)/gm, "  ");
+
+export function formatError(
+	e: unknown,
+	opts: { debug?: boolean; command?: string } = {},
+): string {
+	const d = describeError(e, opts.command);
+	const lines = [`✖ ${d.message}`];
+	if (d.why) lines.push("", indent(d.why));
+	lines.push("");
+	if (d.fix) lines.push(`  Fix:  ${d.fix}`);
+	if (d.docs) lines.push(`  Docs: ${DOCS_URL}/${d.docs}`);
+	if (opts.debug && e instanceof Error && e.stack) {
+		lines.push("", e.stack);
+		if (e.cause instanceof Error && e.cause.stack)
+			lines.push("", `Caused by: ${e.cause.stack}`);
+	} else if (d.expected) {
+		const more = d.more ?? "Run `kanbot doctor` to check your setup.";
+		if (more) lines.push(`  More: ${more}`);
+	} else {
+		lines.push(
+			"  More: rerun with KANBOT_DEBUG=1 for a stack trace.",
+			`        If it looks like a bug, report it at ${ISSUES_URL}`,
+		);
+	}
+	return lines.join("\n");
+}

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);