@gonxped31/agent-kit 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gonxped31
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# agent-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sets up a git repo for Claude Code, new or existing, in two steps: `agk setup` copies
+the kit's files in, then the agent finishes the setup with you. `agk update` brings in
+the kit's later changes.
+
+## What a repo gets
+
+- **A short `CLAUDE.md`**: only what must be true on every change, and where
+  everything else is.
+- **Three skills**:
+  - `git`: a branch per task, files staged by name, `main` only with your approval.
+  - `todo`: a work queue the agent drives through a script, including deferred work
+    with its trigger ("when X happens, do Y").
+  - `agent-setup`: where each kind of knowledge goes, when to add a rule or a skill,
+    and the size limits.
+- **Guardrails that don't rely on the agent remembering**:
+  - a git hook: no commits on `main`, and the checks before every commit;
+  - a Claude hook (Bash and PowerShell): refuses `--no-verify` and bulk staging, and
+    asks you before merges, pushes and commands that discard work;
+  - a Claude hook that refuses whole-file reads of huge files.
+- **Scripts with short output**:
+  - `scripts/check.mjs`: every check, printing only what failed;
+  - `scripts/doctor.mjs`: keeps the agent setup within its size limits and catches
+    dead paths in the docs;
+  - `scripts/merge.mjs`: the only way into `main`.
+
+It works with local git alone: no GitHub, no remote needed.
+
+## Requirements
+
+- git, and Node 18 or later with its npm. No npm packages.
+- Claude Code: the skills, hooks and settings are in its formats.
+- Only for `agk setup --github`: the [GitHub CLI](https://cli.github.com) (`gh`),
+  logged in (`gh auth login`).
+
+## Install
+
+    npm install -g @gonxped31/agent-kit
+
+That puts the `agk` command on your PATH, on Windows, macOS and Linux. The same command
+updates it; `npm uninstall -g @gonxped31/agent-kit` removes it. To run it once without
+installing: `npx @gonxped31/agent-kit setup`.
+
+## Use
+
+1. In the project's folder, run `agk setup` (or `agk setup <folder>` from its
+   parent). It runs `git init` if the folder isn't a repo yet, then copies the kit's
+   files in. It never overwrites a file: where the repo has one already (its own
+   `CLAUDE.md`, say), the kit's version goes next to it as `CLAUDE.md.kit`, and the
+   agent merges the two in step 2.
+
+   With `--github`, it also creates the repo on GitHub as `origin`: private, or public
+   with `--public`. It checks `gh`, your login and the name first, so a problem stops
+   it before anything changes. The agent pushes `main` after the first commit, once
+   you agree.
+2. Open Claude Code there and say "follow BOOTSTRAP.md". It looks around, asks
+   you up to six questions, and fills in the setup. Whatever isn't decided yet (like
+   the stack) becomes a todo with its trigger. Then it makes the first commit.
+3. After cloning the repo somewhere else, run `git config core.hooksPath .githooks`.
+   `doctor` reminds you if you forget.
+
+### Updating a repo
+
+When the kit changes, run `agk update` in the repo. `.claude/agk.json` records each
+file as the kit wrote it, so `agk update` can tell the files you changed:
+
+- a file you haven't changed is updated (or added, or removed, as the kit's is);
+- a file you changed stays as it is, and the kit's new version goes next to it as
+  `<file>.kit`. Say "merge the .kit files" to Claude Code: `doctor` fails until it's
+  done.
+
+It commits nothing: review the changes and commit them on a branch, like any change.
+
+### Presets: your own setup, in every new repo
+
+Once a repo is set up the way you like (your skills, rules, check steps, CI), save
+that as a preset and start new repos from it:
+
+    agk preset save web               # lists what the repo has beyond the kit
+    agk preset save web --only 1-3,6  # keeps the parts you pick
+    agk setup shop --preset web       # the kit, plus your preset
+
+- **What's saved**: setup files the kit doesn't have (in `.claude/`, `.github/`,
+  `.githooks/`, `scripts/hooks/`, `.gitignore`, `.mcp.json`), and what you added to the
+  kit's files: settings rules, check steps, `CLAUDE.md` bullets. Additions are kept
+  apart from the files, so they still apply when the kit's files change. Project code
+  is never looked at. In a terminal, `save` asks which parts to keep.
+- **Where**: `~/.config/agk/presets/<name>/` on every OS (`$XDG_CONFIG_HOME` moves it).
+  A preset named `default` is used by every `agk setup`, unless `--no-preset`.
+- **Defaults**: `agk preset save web --github [--public]` makes `agk setup --preset
+  web` create the GitHub repo too. `--no-github` and `--private` override it.
+- **Updates**: improve the preset (save it again), then `agk update` in each repo. A
+  repo cloned on a machine without the preset still updates the kit's files.
+- **Sharing**: a preset is a folder; make it a git repo and push it. Someone else
+  runs `agk preset add <its URL>`: agk shows the code it runs and the permissions it
+  gives Claude, asks first, and pins the commit. `agk preset pull web` fetches later
+  changes the same way.
+- **Copying a repo's setup**: `agk preset add <URL of a repo agk set up>` lists what
+  that repo has beyond the kit, and keeps the parts you pick as a preset of your own.
+- `agk preset list` shows your presets; `agk preset remove web` deletes one.
+
+Your own habits, the ones that hold in every repo, go in `~/.claude/CLAUDE.md`, not in
+the kit.
+
+## Working on the kit
+
+`npm test` installs the template into temporary repos and runs its scripts and hooks.
+On GitHub, `.github/workflows/test.yml` runs it on Windows, macOS and Linux, with Node
+18 and the current LTS. In a clone, `npm link` makes `agk` run the clone's files (a
+`git pull` updates it), and `node bin/agk.mjs` runs them without linking. The design
+and its decisions are in `docs/design.md`.
+
+## License
+
+MIT, in `LICENSE`.

package/bin/agk.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// agk: sets up git repos for Claude Code, and brings the kit's later changes into them.
+// - `agk setup` (lib/setup.mjs) copies template/, and a preset if any, into a folder; the agent
+//   there follows BOOTSTRAP.md.
+// - `agk update` (lib/update.mjs) brings in the kit's and the preset's later changes.
+// - `agk preset ...` (lib/preset-commands.mjs) saves, shares and fetches presets: a user's own
+//   setup, layered over the kit's (lib/presets.mjs).
+// Installed with `npm install -g @gonxped31/agent-kit` (or `npm link` in a clone); template/ is next
+// to this file. AGK_GH=<path> runs that instead of gh (the kit's tests only).
+import { VERSION } from "../lib/kit.mjs";
+import { presetCommand } from "../lib/preset-commands.mjs";
+import { setup } from "../lib/setup.mjs";
+import { Failure, blank, header, line, out, showFailure } from "../lib/ui.mjs";
+import { update } from "../lib/update.mjs";
+
+function help() {
+  header(VERSION, "Sets up git repos for Claude Code");
+  const row = (a, b) => line(`  ${out.cyan(a.padEnd(30))}${b}`);
+  const section = (title, rows) => {
+    line(out.bold(title));
+    for (const [a, b] of rows) row(a, b);
+    blank();
+  };
+  section("Usage", [
+    ["agk setup [folder] [options]", "Set up folder (default: this one): git init if needed,"],
+    ["", "then the kit's files. For a file it has already, the"],
+    ["", "kit's version goes next to it, as <file>.kit, to merge"],
+    ["agk update [folder]", "Bring in the kit's changes: updates the files the repo"],
+    ["", "hasn't changed, and puts the kit's next to the others"],
+    ["agk preset <command>", "Your own setup on top of the kit's (below)"],
+    ["agk help", "Show this help"],
+    ["agk --version", "Print the version"],
+  ]);
+  section("Setup options", [
+    ["--github", "Also create the repo on GitHub (with gh), as remote origin"],
+    ["--public, --private", "With --github: its visibility (default: private)"],
+    ["--preset <name>", "Set up with that preset"],
+    ["--no-preset", "Leave out your default preset"],
+    ["--no-github", "No GitHub repo, even if the preset asks for one"],
+  ]);
+  section("Presets", [
+    ["preset save <name> [folder]", "Save what a repo has beyond the kit, as a preset"],
+    ["", "(--list, --only 1,3-5, --all; --github [--public]: defaults)"],
+    ["preset list", "Your presets"],
+    ["preset add <git-url|folder>", "Add a shared preset, or copy the setup of a repo agk"],
+    ["", "set up (--name <name>, --yes)"],
+    ["preset pull <name>", "Fetch a shared preset's changes, for you to review"],
+    ["preset remove <name>", "Delete a preset (repos set up with it keep their files)"],
+  ]);
+  line(out.bold("Examples"));
+  for (const e of ["agk setup", "agk setup my-app --github", "agk update", "agk preset save web", "agk setup shop --preset web"]) {
+    line(`  ${out.dim("$")} ${e}`);
+  }
+  blank();
+}
+
+async function main([cmd, ...args]) {
+  const wantsHelp = args.includes("--help") || args.includes("-h");
+  switch (cmd) {
+    case "setup":
+      return wantsHelp ? help() : setup(args);
+    case "update":
+      return wantsHelp ? help() : update(args);
+    case "preset":
+      return wantsHelp ? help() : presetCommand(args);
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      return help();
+    case "--version":
+    case "-v":
+      return console.log(VERSION);
+    default:
+      throw new Failure(`Unknown command '${cmd}'`, { hint: "Run agk help for the commands." });
+  }
+}
+
+main(process.argv.slice(2)).catch((e) => {
+  if (!(e instanceof Failure)) throw e;
+  showFailure(e);
+  process.exitCode = 1;
+});

package/lib/cli.mjs

@@ -0,0 +1,90 @@
+// What agk's commands share: running git and gh, reading arguments, asking the user.
+import { spawn, spawnSync } from "node:child_process";
+import path from "node:path";
+import { Failure, ask, interactive } from "./ui.mjs";
+
+export const NOTHING_CHANGED = "Nothing was changed.";
+
+export const git = (cwd, ...args) => spawnSync("git", args, { cwd, encoding: "utf8" });
+export const noGit = () => new Failure("git isn't installed, or isn't on the PATH", { hint: "The kit needs it: https://git-scm.com" });
+
+/** Runs a command without blocking (so the spinner moves). `error` is set if it couldn't start. */
+export function run(cmd, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", (error) => resolve({ status: null, stdout, stderr, error }));
+    child.on("close", (status) => resolve({ status, stdout, stderr }));
+  });
+}
+
+/** gh, or the command in AGK_GH (run with node if it ends in .mjs: the kit's tests only). */
+export function gh(...args) {
+  const env = { ...process.env, GH_PROMPT_DISABLED: "1" };
+  const fake = process.env.AGK_GH;
+  return fake?.endsWith(".mjs") ? run(process.execPath, [fake, ...args], { env }) : run(fake || "gh", args, { env });
+}
+
+/** The last lines of what a command said, to show under a failure. */
+export const said = (r) => (r.stderr || r.stdout).trim().split(/\r?\n/).filter(Boolean).slice(-3);
+
+export const each = (n) => (n === 1 ? "it" : "each");
+
+/**
+ * A command's arguments: `flags` take no value, `values` take one (`--preset web` or
+ * `--preset=web`), and up to `max` positional arguments, described by `what` when there are more.
+ */
+export function parse(cmd, args, { flags = [], values = [], max = 1, what = "one folder" } = {}) {
+  const opts = new Set();
+  const vals = {};
+  const pos = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith("-") || a === "-") {
+      pos.push(a);
+      continue;
+    }
+    const [name, inline] = a.split(/=(.*)/s);
+    if (values.includes(name)) {
+      const value = inline ?? args[++i];
+      if (value === undefined || value === "" || value.startsWith("-")) throw new Failure(`${name} needs a value`, { hint: "Run agk help for the options." });
+      vals[name] = value;
+    } else if (flags.includes(name) && inline === undefined) {
+      opts.add(name);
+    } else {
+      throw new Failure(`Unknown option '${a}'`, { hint: "Run agk help for the options." });
+    }
+  }
+  if (pos.length > max) throw new Failure(`${cmd} takes ${what}, got ${pos.length}: ${pos.join(", ")}`);
+  return { opts, vals, pos };
+}
+
+/** Both of two options that exclude each other: refused. */
+export function exclusive(opts, a, b) {
+  if (opts.has(a) && opts.has(b)) throw new Failure(`${a} and ${b} don't go together`);
+}
+
+export const shownPath = (folder) => path.relative(process.cwd(), folder) || ".";
+
+/** The root of the git repo `folder` is in. */
+export function repoRoot(folder, command) {
+  const shown = shownPath(folder);
+  const probe = git(folder, "rev-parse", "--show-toplevel");
+  if (probe.error) throw noGit();
+  if (probe.status !== 0) {
+    throw new Failure(`${shown === "." ? "This folder" : shown} isn't in a git repo`, {
+      hint: `agk ${command} works in a repo the kit set up. To set one up, run agk setup.`,
+    });
+  }
+  return path.resolve(probe.stdout.trim());
+}
+
+/** The user's OK: --yes, or a yes in a terminal. Without a terminal, --yes is needed. */
+export async function confirm(question, opts) {
+  if (opts.has("--yes")) return true;
+  if (!interactive) throw new Failure(`${question.replace(/\?$/, "")}: that needs your OK`, { hint: "Run it in a terminal to answer, or add --yes." });
+  return /^y(es)?$/i.test(await ask(`${question} [y/N]`));
+}

package/lib/kit.mjs

@@ -0,0 +1,134 @@
+// The kit's files, and the record agk keeps of them in each repo it sets up (.claude/agk.json):
+// the hash of each file as the kit wrote it. agk update compares a repo's files with it, to tell
+// the files the repo changed from those it didn't.
+// Text is compared and written with LF endings, whatever endings a checkout has.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Failure } from "./ui.mjs";
+
+export const KIT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const TEMPLATE = path.join(KIT, "template");
+const pkg = JSON.parse(fs.readFileSync(path.join(KIT, "package.json"), "utf8"));
+export const VERSION = pkg.version;
+/** The npm package agk comes in. */
+export const PACKAGE = pkg.name;
+export const RECORD = ".claude/agk.json";
+/** The setup's instructions. The bootstrap deletes the file, so agk update never brings it back. */
+export const SETUP_ONLY = "BOOTSTRAP.md";
+const HOOK = ".githooks/pre-commit";
+// Kept under other names in the kit, so Claude Code working on the kit doesn't load the template's
+// CLAUDE.md and skills as the kit's own. The template's name -> the name in a repo.
+const RENAMED = { "CLAUDE.template.md": "CLAUDE.md", "dot-claude": ".claude" };
+
+/** Where the kit puts its version of a file a repo already has, or changed: next to it. */
+export const kitCopy = (rel) => `${rel}.kit`;
+
+export function walk(dir, rel = "") {
+  return fs.readdirSync(path.join(dir, rel), { withFileTypes: true }).flatMap((e) => {
+    const child = path.join(rel, e.name);
+    return e.isDirectory() ? walk(dir, child) : [child];
+  });
+}
+
+export const lf = (file) => fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+export const hash = (text) => crypto.createHash("sha256").update(text).digest("hex");
+
+/**
+ * The kit's files, sorted by `to`: where each is in template/ (`from`), its path in a repo (`to`,
+ * with forward slashes), its text and that text's hash.
+ */
+export function kitFiles() {
+  return walk(TEMPLATE)
+    .map((from) => {
+      const [first, ...rest] = from.split(path.sep);
+      const text = lf(path.join(TEMPLATE, from));
+      return { from, to: [RENAMED[first] ?? first, ...rest].join("/"), text, hash: hash(text) };
+    })
+    .sort((a, b) => (a.to < b.to ? -1 : 1));
+}
+
+/** The hash of a repo's file; null if there's nothing there, "not a file" for a folder. */
+export function hashAt(root, rel) {
+  const file = path.join(root, rel);
+  if (!fs.existsSync(file)) return null;
+  return fs.statSync(file).isFile() ? hash(lf(file)) : "not a file";
+}
+
+/** Writes a file, making its folders. The git hook is made executable. */
+export function put(root, rel, text) {
+  const file = path.join(root, rel);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+  if (rel === HOOK) fs.chmodSync(file, 0o755);
+}
+
+/** Deletes a file, then the folders it leaves empty, up to the repo's root. */
+export function remove(root, rel) {
+  fs.rmSync(path.join(root, rel));
+  for (let dir = path.dirname(rel); dir !== "."; dir = path.dirname(dir)) {
+    const full = path.join(root, dir);
+    if (fs.readdirSync(full).length) break;
+    fs.rmdirSync(full);
+  }
+}
+
+/** A path in a repo, as the record may hold one: relative, inside the repo, and not in .git. */
+export const inRepo = (rel) => !/^[\\/]|^[a-z]:|\\/i.test(rel) && !rel.split("/").some((p) => p === ".." || p === "") && !/^\.git(\/|$)/.test(rel);
+
+/** A repo's record, or null if it has none. */
+export function readRecord(root) {
+  const file = path.join(root, RECORD);
+  if (!fs.existsSync(file)) return null;
+  let record;
+  try {
+    record = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {}
+  const files = record?.files;
+  const preset = record?.preset;
+  const valid =
+    typeof record?.version === "string" &&
+    files &&
+    typeof files === "object" &&
+    Object.entries(files).every(([rel, h]) => inRepo(rel) && typeof h === "string") &&
+    (preset === undefined ||
+      (typeof preset?.name === "string" && Array.isArray(preset.files ?? []) && (preset.files ?? []).every((rel) => typeof rel === "string" && inRepo(rel))));
+  if (!valid) {
+    throw new Failure(`${RECORD} isn't what agk wrote`, {
+      hint: `agk reads it to tell the files you changed. Restore it from git, or delete it to update\nas if the repo had none. Nothing was changed.`,
+    });
+  }
+  return record;
+}
+
+/**
+ * Records the files agk wrote (all but the setup's instructions) in a repo, and the preset they
+ * came with. `keep` holds entries to keep as they are (a preset's files, when it's missing).
+ * False if the record held all that already.
+ */
+export function writeRecord(root, files, { preset = null, keep = {} } = {}) {
+  const wrote = { ...keep, ...Object.fromEntries(files.filter((f) => f.to !== SETUP_ONLY).map((f) => [f.to, f.hash])) };
+  const record = {
+    about: "Written by agk setup and agk update: the kit's files as it wrote them, so agk update can tell the ones you changed.",
+    version: VERSION,
+    ...(preset && { preset }),
+    files: Object.fromEntries(Object.entries(wrote).sort(([a], [b]) => (a < b ? -1 : 1))),
+  };
+  const text = `${JSON.stringify(record, null, 2)}\n`;
+  const file = path.join(root, RECORD);
+  if (fs.existsSync(file) && lf(file) === text) return false;
+  put(root, RECORD, text);
+  return true;
+}
+
+/** True if the kit has set up `root`: it has a record, or a file only the kit writes (agk 0.1.0 kept no record). */
+export const setUpAlready = (root) =>
+  [RECORD, ".claude/skills/agent-setup/SKILL.md"].some((rel) => fs.existsSync(path.join(root, rel)));
+
+/** True if version `a` is newer than `b` (both like 1.2.3). */
+export function newer(a, b) {
+  const [x, y] = [a, b].map((v) => v.split(".").map((n) => Number.parseInt(n, 10) || 0));
+  for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) > (y[i] ?? 0);
+  return false;
+}

package/lib/merge.mjs

@@ -0,0 +1,225 @@
+// Additions: what a repo added to one of the kit's files, kept apart from the file, so a preset can
+// add it to whatever version of the file the kit has next. Each is a file of the same kind:
+// - JSON: an object holding only the added keys and list entries;
+// - Markdown: the added blocks (a bullet with its lines, a paragraph, a table row), each under the
+//   `## ` heading it goes under;
+// - other text: the added lines.
+// Code (scripts, hooks) doesn't merge by lines: a preset replaces such a file whole.
+
+export function kindOf(rel) {
+  if (/\.json$/i.test(rel)) return "json";
+  if (/\.md$/i.test(rel)) return "markdown";
+  if (/\.(mjs|cjs|js|ts|sh|bash|ps1|py)$/i.test(rel) || rel.startsWith(".githooks/")) return "code";
+  return "lines";
+}
+
+// ---- JSON
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** What `repo` has that `kit` hasn't: { keys (the path), value, array (an entry of the list at keys) }. */
+function jsonItems(repo, kit, keys = []) {
+  if (isObject(repo) && isObject(kit)) {
+    return Object.entries(repo).flatMap(([k, v]) => (k in kit ? jsonItems(v, kit[k], [...keys, k]) : [{ keys: [...keys, k], value: v }]));
+  }
+  if (Array.isArray(repo) && Array.isArray(kit)) {
+    return keys.length ? repo.filter((v) => !kit.some((w) => same(v, w))).map((value) => ({ keys, value, array: true })) : [];
+  }
+  return same(repo, kit) || !keys.length ? [] : [{ keys, value: repo }];
+}
+
+function buildJson(items) {
+  const root = {};
+  for (const { keys, value, array } of items) {
+    let node = root;
+    for (const k of keys.slice(0, -1)) node = node[k] ??= {};
+    const last = keys[keys.length - 1];
+    if (array) (node[last] ??= []).push(value);
+    else node[last] = value;
+  }
+  return `${JSON.stringify(root, null, 2)}\n`;
+}
+
+/** Objects merge key by key, lists get the entries they lack, anything else takes the addition. */
+function mergeValue(base, add) {
+  if (isObject(base) && isObject(add)) {
+    const merged = { ...base };
+    for (const [k, v] of Object.entries(add)) merged[k] = k in base ? mergeValue(base[k], v) : v;
+    return merged;
+  }
+  if (Array.isArray(base) && Array.isArray(add)) return [...base, ...add.filter((v) => !base.some((w) => same(v, w)))];
+  return add;
+}
+
+// ---- Markdown
+const START = /^([-*+]|\d+[.)])\s|^\||^#{1,6}\s|^(```|~~~)/;
+const FENCE = /^\s*(```|~~~)/;
+const isItem = (block) => /^([-*+]|\d+[.)])\s/.test(block);
+const key = (block) => block.split("\n").map((l) => l.trimEnd()).join("\n");
+
+/** The text before the first `## ` heading (heading ""), then each `## ` section. */
+function sections(text) {
+  const out = [{ heading: "", lines: [] }];
+  let fence = false;
+  for (const line of text.replace(/\n$/, "").split("\n")) {
+    if (FENCE.test(line)) fence = !fence;
+    if (!fence && /^## /.test(line)) out.push({ heading: line.trim(), lines: [] });
+    else out[out.length - 1].lines.push(line);
+  }
+  return out;
+}
+
+/** A section's blocks: a list item with its indented lines, a paragraph, a table row, a code block. */
+function blocks(lines) {
+  const out = [];
+  let current = null;
+  let fence = false;
+  for (const line of lines) {
+    if (fence) {
+      current.push(line);
+      if (FENCE.test(line)) fence = false;
+      continue;
+    }
+    if (!line.trim()) {
+      current = null;
+      continue;
+    }
+    if (!current || (!/^\s/.test(line) && START.test(line))) {
+      current = [line];
+      out.push(current);
+    } else {
+      current.push(line);
+    }
+    if (FENCE.test(line)) fence = true;
+  }
+  return out.map((b) => b.join("\n"));
+}
+
+function markdownItems(repo, kit, skipTop) {
+  const kitBlocks = new Map(sections(kit).map((s) => [s.heading, new Set(blocks(s.lines).map(key))]));
+  return sections(repo)
+    .filter((s) => !(skipTop && s.heading === ""))
+    .flatMap((s) => {
+      const have = kitBlocks.get(s.heading) ?? new Set();
+      return blocks(s.lines)
+        .filter((b) => !have.has(key(b)))
+        .map((text) => ({ heading: s.heading, text }));
+    });
+}
+
+function joinBlocks(texts) {
+  return texts.reduce((all, b, i) => (i === 0 ? b : `${all}${isItem(texts[i - 1]) && isItem(b) ? "\n" : "\n\n"}${b}`), "");
+}
+
+function buildMarkdown(items) {
+  const groups = new Map();
+  for (const { heading, text } of items) {
+    if (!groups.has(heading)) groups.set(heading, []);
+    groups.get(heading).push(text);
+  }
+  const top = groups.get("") ?? [];
+  groups.delete("");
+  const parts = [...(top.length ? [joinBlocks(top)] : []), ...[...groups].map(([heading, texts]) => `${heading}\n\n${joinBlocks(texts)}`)];
+  return `${parts.join("\n\n")}\n`;
+}
+
+/** Adds a block at the end of a section, keeping lists tight and other blocks a blank line apart. */
+function append(section, block) {
+  const lines = section.lines;
+  while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+  const last = blocks(lines).pop();
+  if (!lines.length) {
+    if (section.heading) lines.push("");
+  } else if (!(last && isItem(last) && isItem(block))) {
+    lines.push("");
+  }
+  lines.push(...block.split("\n"));
+}
+
+function mergeMarkdown(baseText, addText) {
+  const base = sections(baseText);
+  const changed = new Set();
+  for (const add of sections(addText)) {
+    const added = blocks(add.lines);
+    if (!added.length) continue;
+    let target = base.find((s) => s.heading === add.heading);
+    if (!target) {
+      target = { heading: add.heading, lines: [] };
+      base.push(target);
+    }
+    const have = new Set(blocks(target.lines).map(key));
+    for (const b of added.filter((b) => !have.has(key(b)))) {
+      append(target, b);
+      have.add(key(b));
+      changed.add(target);
+    }
+  }
+  // A section that grew, or that a new section now follows, ends with a blank line.
+  base.forEach((s, i) => {
+    if (i < base.length - 1 && s.lines.length && s.lines[s.lines.length - 1].trim()) s.lines.push("");
+  });
+  const text = base.flatMap((s) => (s.heading ? [s.heading, ...s.lines] : s.lines)).join("\n");
+  return `${text.replace(/\n+$/, "")}\n`;
+}
+
+// ---- Lines
+const lineSet = (text) => new Set(text.split("\n").map((l) => l.trimEnd()));
+const lineItems = (repo, kit) => {
+  const have = lineSet(kit);
+  return [...new Set(repo.split("\n").map((l) => l.trimEnd()))].filter((l) => l.trim() && !have.has(l)).map((text) => ({ text }));
+};
+function mergeLines(base, add) {
+  const have = lineSet(base);
+  const extra = [...new Set(add.split("\n").map((l) => l.trimEnd()))].filter((l) => l.trim() && !have.has(l));
+  return extra.length ? `${base.replace(/\n*$/, "\n")}${extra.join("\n")}\n` : base;
+}
+
+// ---- By kind
+
+/**
+ * What a repo's version of a kit file adds to the kit's: a list of items, or null for code, which
+ * doesn't merge. CLAUDE.md's text before its first `## ` heading is the project's name and
+ * description, so it never counts.
+ */
+export function additionsOf(rel, repoText, kitText) {
+  switch (kindOf(rel)) {
+    case "json":
+      try {
+        return jsonItems(JSON.parse(repoText), JSON.parse(kitText));
+      } catch {
+        return null;
+      }
+    case "markdown":
+      return markdownItems(repoText, kitText, rel === "CLAUDE.md");
+    case "lines":
+      return lineItems(repoText, kitText);
+    default:
+      return null;
+  }
+}
+
+/** The additions file for chosen items of one file. */
+export function buildAdditions(rel, items) {
+  const kind = kindOf(rel);
+  if (kind === "json") return buildJson(items);
+  if (kind === "markdown") return buildMarkdown(items);
+  return `${items.map((i) => i.text).join("\n")}\n`;
+}
+
+/** A file with an additions file merged in. Throws on JSON that doesn't parse. */
+export function mergeAdditions(rel, baseText, addText) {
+  const kind = kindOf(rel);
+  if (kind === "json") return `${JSON.stringify(mergeValue(JSON.parse(baseText), JSON.parse(addText)), null, 2)}\n`;
+  if (kind === "markdown") return mergeMarkdown(baseText, addText);
+  return mergeLines(baseText, addText);
+}
+
+const clipText = (s, n = 72) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+/** One line saying what an addition is. */
+export function describeAddition(rel, item) {
+  const kind = kindOf(rel);
+  if (kind === "json") return clipText(`${item.keys.join(".")}${item.array ? "[]" : ""}: ${JSON.stringify(item.value)}`);
+  if (kind === "markdown") return clipText(`${item.heading ? `${item.heading.replace(/^##\s*/, "")}: ` : ""}${item.text.split("\n")[0]}`);
+  return clipText(item.text);
+}