honestdocs 0.0.0-stage → 0.1.0

package/guide/skill/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: honestdocs
+description: Keeps this project's development documents (decisions, designs, plans, research, postmortems, standing rules in {{root}}/) true with the honestdocs CLI. Use when starting a session, before designing or building something non-trivial, when committing work that a document describes, when closing out work, or when asked why something is built the way it is.
+---
+
+# Development documents with honestdocs
+
+`{{root}}/` is the project's long-term memory. Every document is Markdown with a small
+frontmatter block; `INDEX.md` is generated. **The code is the truth** — where a document
+and the code disagree, believe the code and correct the document.
+
+## When a session starts
+
+```sh
+honestdocs brief
+```
+
+Work in progress with its next unticked items, what is planned, what changed lately,
+and the rules in force. Read the in-progress document you are continuing — its Log is
+the hand-over from the last session.
+
+## Before building
+
+1. **Has this been weighed before?** `honestdocs search <words>`; with
+   `--section alternatives` it shows only what was considered and rejected, with the
+   reason. Superseded and abandoned documents are included on purpose. Do not propose a
+   rejected option again without saying what has changed.
+2. **Which rules apply?** `honestdocs rules` lists the numbered rules in force and the
+   tests that prove them. Go through the `before-you-build` checklist in `{{root}}/rules/`.
+3. **Open a document** for anything non-trivial:
+
+   ```sh
+   honestdocs new <area> <slug> --type design --title "Token rotation"
+   ```
+
+   Types: `design` (how it should work), `plan` (ordered steps, checklist), `research`
+   (a question and sourced findings), `decision` (one choice, MADR), `postmortem` (what
+   went wrong, with evidence), `reference` and `rule` (living documents, edited in place).
+   Fill *Alternatives considered* — it is the part people and agents need most later.
+
+## While building
+
+- End every commit message that does the work with a trailer line:
+
+  ```
+  {{trailer}}: 2026-11-02-token-rotation
+  ```
+
+  That is how `honestdocs index` learns which files the document touched. Several ids:
+  comma-separated or one line each.
+- Tick checklist items (`- [x]`) as they land. Add dated notes to the Log.
+- Never write `progress`, `files`, `superseded-by` or `updated` by hand. Write only
+  `title`, `status`, `supersedes`, `related`.
+- Replacing a document: `supersedes: [<old id>]` in the **new** one, then
+  `honestdocs index` marks the old one.
+- A rule changed: edit its rule document in place and add a Log line — never a second
+  document beside it.
+
+## Finishing
+
+```sh
+honestdocs done <id>              # refuses while checklist items are unticked
+honestdocs done <id> --abandoned  # dropped on purpose; the reason goes in the Log
+honestdocs status <id> current    # living documents: draft | current | retired
+honestdocs index && honestdocs check
+```
+
+`check` exits 1 on anything that makes the set lie. A change is not finished while a
+document or rule it affects still describes the old behaviour.
+
+Every query command takes `--json`. The method in full: `honestdocs guide`.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "honestdocs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Development documents that stay true — decisions, designs, plans, research, postmortems and standing rules, kept honest for people and AI agents.",
+  "keywords": [
+    "documentation",
+    "adr",
+    "architecture-decision-records",
+    "design-docs",
+    "devdocs",
+    "git",
+    "ai-agents",
+    "agents-md",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Glivo",
+  "homepage": "https://github.com/glivo-dev/honestdocs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/glivo-dev/honestdocs.git"
+  },
+  "bugs": "https://github.com/glivo-dev/honestdocs/issues",
+  "type": "module",
+  "bin": {
+    "honestdocs": "bin/honestdocs.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "guide/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "assets": "node scripts/build-assets.mjs",
+    "docs:index": "node bin/honestdocs.mjs index",
+    "docs:check": "node bin/honestdocs.mjs check"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,67 @@
+// Small command-line plumbing shared by every command: arguments, colour, and the
+// convention that diagnostics go to stderr so stdout stays parseable when a caller —
+// a script, CI, an AI agent — pipes it.
+
+export class UsageError extends Error {}
+export class Failure extends Error {}
+
+const useColour = () =>
+  !process.env.NO_COLOR && (process.env.FORCE_COLOR || process.stderr.isTTY);
+
+const paint = (code) => (s) => (useColour() ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+
+export const c = {
+  dim: paint(2),
+  red: paint(31),
+  green: paint(32),
+  yellow: paint(33),
+};
+
+export const say = (msg = "") => console.error(msg);
+export const ok = (msg) => console.error(c.green("✓ ") + msg);
+export const warn = (msg) => console.error(c.yellow("! ") + msg);
+
+/** Stop with a message. A UsageError exits 2, anything else 1. */
+export function die(msg) {
+  throw new Failure(msg);
+}
+
+/**
+ * Parse `argv` against a spec of flags.
+ *
+ *   parseArgs(argv, { title: "string", force: "boolean", "code-repo": "list" })
+ *
+ * Returns `{ _: [positional…], title, force, "code-repo": [...] }`. An unknown flag is a
+ * UsageError rather than something silently ignored: a mistyped `--stauts` that does
+ * nothing is worse than one that stops.
+ */
+export function parseArgs(argv, spec = {}) {
+  const out = { _: [] };
+  for (const [k, kind] of Object.entries(spec)) if (kind === "list") out[k] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      out._.push(...argv.slice(i + 1));
+      break;
+    }
+    if (!a.startsWith("--") || a === "-") {
+      out._.push(a);
+      continue;
+    }
+    let [name, inline] = a.slice(2).split(/=(.*)/s, 2);
+    const kind = spec[name];
+    if (!kind) throw new UsageError(`unknown option --${name}`);
+    if (kind === "boolean") {
+      out[name] = inline === undefined ? true : !/^(false|0|no)$/i.test(inline);
+      continue;
+    }
+    const value = inline ?? argv[++i];
+    if (value === undefined) throw new UsageError(`--${name} needs a value`);
+    if (kind === "list") out[name].push(value);
+    else out[name] = value;
+  }
+  return out;
+}
+
+/** Print JSON on stdout — the one place a command writes data rather than talk. */
+export const emitJson = (value) => console.log(JSON.stringify(value, null, 2));

package/src/commands/brief.mjs

@@ -0,0 +1,78 @@
+import { emitJson, parseArgs } from "../cli.mjs";
+import { loadConfig } from "../config.mjs";
+import { loadDocs, openItems } from "../docs.mjs";
+import { MARK } from "../render.mjs";
+import { parseRules } from "../rules.mjs";
+
+export const summary = "what is under way, in a page — run it when a session starts";
+
+export const help = `honestdocs brief — ${summary}
+
+  honestdocs brief [--days <n>] [--json]
+
+The work in progress with its next unticked items, what is planned, what changed
+lately, and which rules are in force. Short on purpose: it is what a person back
+from a week away, or an AI agent with an empty context, reads first.
+
+  --days <n>   how far back "changed lately" reaches (default 14)
+  --json       everything, unabridged, as JSON on stdout
+`;
+
+const daysAgo = (n) => new Date(Date.now() - n * 864e5).toISOString().slice(0, 10);
+
+function collectBrief(config, { days = 14 } = {}) {
+  const docs = loadDocs(config).filter((d) => d.hasMeta);
+  const pick = (d) => ({ id: d.id, path: `${config.root}/${d.rel}`, title: d.meta.title, type: d.meta.type, status: d.meta.status });
+  const since = daysAgo(days);
+  return {
+    title: config.title,
+    documents: docs.length,
+    inProgress: docs.filter((d) => d.meta.status === "in-progress")
+      .map((d) => ({ ...pick(d), progress: d.meta.progress || "", next: openItems(d.body) })),
+    planned: docs.filter((d) => d.meta.status === "planned").map(pick),
+    drafts: docs.filter((d) => d.meta.status === "draft" && String(d.meta.updated ?? "") >= since).map(pick),
+    changed: docs.filter((d) => String(d.meta.updated ?? "") >= since)
+      .sort((a, b) => String(b.meta.updated).localeCompare(String(a.meta.updated)))
+      .map((d) => ({ ...pick(d), updated: d.meta.updated })),
+    rules: docs.filter((d) => d.meta.type === "rule" && (d.meta.status === "current" || d.meta.status === "draft"))
+      .map((d) => ({ ...pick(d), rules: parseRules(d.body).map((r) => r.id) })),
+  };
+}
+
+const range = (ids) => (ids.length === 0 ? "no rules yet" : ids.length <= 3 ? ids.join(", ") : `${ids[0]}…${ids.at(-1)} (${ids.length})`);
+
+export function run(argv) {
+  const args = parseArgs(argv, { days: "string", json: "boolean" });
+  const config = loadConfig();
+  const b = collectBrief(config, { days: Number(args.days ?? 14) || 14 });
+  if (args.json) return emitJson(b);
+
+  const out = [`${b.title} — ${b.documents} documents`, ""];
+  const line = (d, extra = "") => `  ${MARK[d.status] ?? " "} ${d.id} — ${d.title}${extra}`;
+
+  out.push(b.inProgress.length ? "In progress" : "In progress: nothing");
+  for (const d of b.inProgress.slice(0, 10)) {
+    out.push(line(d, d.progress ? ` (${d.progress})` : ""));
+    for (const item of d.next.slice(0, 3)) out.push(`      - [ ] ${item}`);
+    if (d.next.length > 3) out.push(`      … ${d.next.length - 3} more`);
+  }
+  if (b.inProgress.length > 10) out.push(`  … ${b.inProgress.length - 10} more (--json for all)`);
+
+  if (b.planned.length) {
+    out.push("", "Planned — re-check against the code before building");
+    for (const d of b.planned.slice(0, 8)) out.push(line(d));
+    if (b.planned.length > 8) out.push(`  … ${b.planned.length - 8} more`);
+  }
+
+  const recent = b.changed.filter((d) => d.status !== "in-progress").slice(0, 8);
+  if (recent.length) {
+    out.push("", "Changed lately");
+    for (const d of recent) out.push(line(d, `  · ${d.updated}`));
+  }
+
+  if (b.rules.length) {
+    out.push("", "Rules in force — read the ones a change touches before building");
+    for (const d of b.rules) out.push(`  ${d.path} — ${d.title}: ${range(d.rules)}`);
+  }
+  console.log(out.join("\n"));
+}

package/src/commands/check.mjs

@@ -0,0 +1,163 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { c, emitJson, parseArgs, say } from "../cli.mjs";
+import { lifecycleOf, loadConfig, statusesFor } from "../config.mjs";
+import { asList, checklistProgress, derive, folderArea, gitFacts, loadDocs, writeDoc } from "../docs.mjs";
+import { renderIndex } from "../render.mjs";
+import { parseRules } from "../rules.mjs";
+
+export const summary = "validate every document; exit 1 on any error";
+
+export const help = `honestdocs check — ${summary}
+
+  honestdocs check [--fix] [--json]
+
+Errors (exit 1) are things that make the set lie or break:
+  · frontmatter missing, or an id that does not match its filename
+  · an area, type or status outside the config — or a status the type's
+    lifecycle does not have
+  · a document in one area's folder that claims another area
+  · supersedes / related pointing at nothing
+  · a superseded document that still says it is in force
+  · a checklist whose progress was never recounted
+  · a rule whose named test file does not exist, or two rules with one id
+  · INDEX.md not regenerated since the frontmatter last changed
+
+Warnings are for a person to look at: derived fields git would now answer
+differently (run \`honestdocs index\`), a done document without a date, and so on.
+
+  --fix    correct what is mechanical: the area, from the folder
+  --json   { documents, errors, warnings, fixed } on stdout
+`;
+
+function runCheck(config, { fix = false } = {}) {
+  const docs = loadDocs(config);
+  const errors = [];
+  const warnings = [];
+  const fixed = [];
+  const err = (d, msg) => errors.push({ file: d.rel, msg });
+  const warnAt = (d, msg) => warnings.push({ file: d.rel, msg });
+
+  const ids = new Map();
+  for (const d of docs) {
+    if (ids.has(d.id)) err(d, `duplicate id — also ${ids.get(d.id).rel}`);
+    else ids.set(d.id, d);
+  }
+
+  for (const d of docs) {
+    const m = d.meta;
+    if (!d.hasMeta) {
+      err(d, "no frontmatter — start documents with `honestdocs new`, or add the block by hand");
+      continue;
+    }
+    if (!m.id) err(d, "missing `id`");
+    else if (m.id !== d.id) err(d, `id "${m.id}" does not match the filename "${d.id}" — the filename is the id`);
+    if (!m.title) err(d, "missing `title`");
+
+    const folder = folderArea(config, d.file);
+    if (!m.area) err(d, "missing `area`");
+    else if (!config.areas[m.area]) err(d, `unknown area "${m.area}" — add it to the config's areas, or move the file`);
+    if (folder && m.area && folder !== m.area) {
+      if (fix && config.areas[folder]) {
+        m.area = folder;
+        writeDoc(d);
+        fixed.push({ file: d.rel, msg: `area → ${folder}` });
+      } else err(d, `says area "${m.area}" but lives in ${folder}/ — the folder wins (check --fix)`);
+    }
+    if (!folder) warnAt(d, "at the top level — it belongs in an area folder");
+
+    if (!m.type) err(d, "missing `type`");
+    else if (!config.types[m.type]) err(d, `unknown type "${m.type}"`);
+    if (!m.status) err(d, "missing `status`");
+    else if (config.types[m.type]) {
+      const allowed = statusesFor(config, m.type);
+      if (!allowed[m.status]) {
+        err(d, `"${m.status}" is not a status for a ${m.type} (${lifecycleOf(config, m.type)} document) — expected one of: ${Object.keys(allowed).join(", ")}`);
+      }
+    }
+
+    for (const target of asList(m.supersedes)) {
+      if (target === d.id) err(d, "supersedes itself");
+      else if (!ids.has(target)) err(d, `supersedes "${target}", which does not exist`);
+    }
+    for (const target of asList(m.related)) {
+      const isPath = target.includes("/") || target.endsWith(".md");
+      if (isPath) {
+        if (!existsSync(resolve(config.base, target))) err(d, `related "${target}" is not a file under ${config.base}`);
+      } else if (!ids.has(target)) err(d, `related "${target}", which does not exist`);
+    }
+
+    if (m.status === "superseded" && !m["superseded-by"]) {
+      warnAt(d, "superseded, but nothing says by what — set `supersedes` on the newer document");
+    }
+    if ((m.status === "done" || m.status === "abandoned") && !m.completed && m.legacy !== true) {
+      warnAt(d, `${m.status} but \`completed\` is empty — close documents with \`honestdocs done\``);
+    }
+    if (m.status === "done") {
+      const p = checklistProgress(d.body);
+      if (p && p.split("/")[0] !== p.split("/")[1]) warnAt(d, `done, but its checklist is at ${p} — say in the Log what happened to the rest`);
+    }
+  }
+
+  // Rules: unique ids across every rule document, and tests that exist.
+  const ruleIds = new Map();
+  const roots = [config.base, ...config.codeRepos];
+  for (const d of docs) {
+    if (d.meta.type !== "rule") continue;
+    const rules = parseRules(d.body);
+    const inForce = d.meta.status === "current" || d.meta.status === "draft";
+    if (!rules.length && inForce) warnAt(d, "a rule document with no rules — write them as `- **R1** …`");
+    for (const r of rules) {
+      const where = `${d.rel}:${r.line}`;
+      if (ruleIds.has(r.id)) errors.push({ file: where, msg: `rule ${r.id} is also defined at ${ruleIds.get(r.id)}` });
+      else ruleIds.set(r.id, where);
+      if (!inForce) continue;
+      for (const t of r.tests) {
+        if (!roots.some((root) => existsSync(resolve(root, t)))) {
+          errors.push({ file: where, msg: `rule ${r.id} names the test \`${t}\`, which does not exist` });
+        }
+      }
+    }
+  }
+
+  // What the derivation would change. Fields a person could have fixed before the commit
+  // are errors; fields that only a later commit can settle (git's answer moves with every
+  // commit that names the document) are warnings.
+  const facts = gitFacts(config);
+  for (const ch of derive(config, docs.filter((d) => d.hasMeta && d.meta.id === d.id), facts)) {
+    for (const k of new Set([...Object.keys(ch.before), ...Object.keys(ch.meta)])) {
+      if (JSON.stringify(ch.before[k]) === JSON.stringify(ch.meta[k])) continue;
+      const msg = `\`${k}\` is ${JSON.stringify(ch.before[k] ?? "")}, should be ${JSON.stringify(ch.meta[k])} — run \`honestdocs index\``;
+      if (k === "status") err(ch.doc, `replaced by ${ch.meta["superseded-by"]} but still says "${ch.before.status}" — run \`honestdocs index\``);
+      else if (k === "progress" || k === "superseded-by") err(ch.doc, msg);
+      else warnAt(ch.doc, msg);
+    }
+  }
+
+  // The index must match the frontmatter as written — not as git would now derive it —
+  // so a commit can never make it stale on its own.
+  const indexFile = join(config.docsDir, "INDEX.md");
+  const expected = renderIndex(config, docs.filter((d) => d.hasMeta));
+  if (!existsSync(indexFile)) errors.push({ file: "INDEX.md", msg: "missing — run `honestdocs index`" });
+  else if (readFileSync(indexFile, "utf8") !== expected) {
+    errors.push({ file: "INDEX.md", msg: "stale: frontmatter changed since it was generated — run `honestdocs index`" });
+  }
+
+  return { documents: docs.length, git: facts.available ? "ok" : facts.reason, errors, warnings, fixed };
+}
+
+export function run(argv) {
+  const args = parseArgs(argv, { fix: "boolean", json: "boolean" });
+  const config = loadConfig();
+  const r = runCheck(config, { fix: args.fix });
+  if (args.json) emitJson(r);
+  else {
+    if (r.git !== "ok") say(c.yellow(`! git: ${r.git} — derived fields not compared`));
+    for (const f of r.fixed) say(c.green("  fixed ") + c.dim(`${f.file}: ${f.msg}`));
+    for (const w of r.warnings) say(c.yellow("  warn  ") + `${w.file}: ${w.msg}`);
+    for (const e of r.errors) say(c.red("  error ") + `${e.file}: ${e.msg}`);
+    const tail = `${r.documents} document(s), ${r.errors.length} error(s), ${r.warnings.length} warning(s)`;
+    say(r.errors.length ? c.red(`\n✗ ${tail}`) : c.green(`\n✓ ${tail}`));
+  }
+  if (r.errors.length) process.exitCode = 1;
+}

package/src/commands/done.mjs

@@ -0,0 +1,53 @@
+import { UsageError, c, die, ok, parseArgs, say } from "../cli.mjs";
+import { lifecycleOf, loadConfig } from "../config.mjs";
+import { checklistProgress, findDoc, loadDocs, today, writeDoc } from "../docs.mjs";
+import { report, runIndex } from "./index.mjs";
+
+export const summary = "close a work document as done (or abandoned)";
+
+export const help = `honestdocs done — ${summary}
+
+  honestdocs done <id> [--abandoned] [--force]
+
+Sets status and completed, then reruns the index so files and progress are final.
+A checklist with unticked items is refused: either the items are done, or "done"
+is not the word for what happened.
+
+  --abandoned   the work was dropped on purpose; the reasoning is the record
+  --force       close it anyway — after saying in the Log what became of the
+                unticked items
+`;
+
+export function run(argv) {
+  const args = parseArgs(argv, { abandoned: "boolean", force: "boolean" });
+  const [id] = args._;
+  if (!id) throw new UsageError("need a document id");
+  const config = loadConfig();
+  const doc = findDoc(loadDocs(config), id);
+  if (!doc) die(`no document with the id "${id}"`);
+  if (!doc.hasMeta) die(`${doc.rel} has no frontmatter`);
+
+  if (lifecycleOf(config, doc.meta.type) !== "work") {
+    die(`${id} is a ${doc.meta.type} — a living document is never finished. ` +
+      "Keep it current, or retire it: `honestdocs status " + id + " retired`");
+  }
+
+  const status = args.abandoned ? "abandoned" : "done";
+  const progress = checklistProgress(doc.body);
+  if (status === "done" && progress && !args.force) {
+    const [d, total] = progress.split("/").map(Number);
+    if (d < total) {
+      say(c.yellow(`! ${id} is at ${progress}.`));
+      say(c.dim("  Tick the rest, or write in the Log what happened to them and pass --force."));
+      say(c.dim("  If the work was dropped rather than finished: --abandoned."));
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  doc.meta.status = status;
+  doc.meta.completed = today();
+  writeDoc(doc);
+  ok(`${id} → ${status} (${doc.meta.completed})`);
+  report(config, runIndex(config), false);
+}

package/src/commands/guide.mjs

@@ -0,0 +1,29 @@
+import { UsageError, parseArgs } from "../cli.mjs";
+import { DEFAULT_ROOT, findConfig, loadConfig } from "../config.mjs";
+import { fill, packageFile } from "../templates.mjs";
+
+export const summary = "print the method, the agent instructions or the skill";
+
+const TOPICS = {
+  method: ["METHOD.md"],
+  agents: ["agents-snippet.md"],
+  skill: ["skill", "SKILL.md"],
+};
+
+export const help = `honestdocs guide — ${summary}
+
+  honestdocs guide [method|agents|skill]
+
+  method   the rules of the method itself (default)
+  agents   the section \`init --agents\` writes into AGENTS.md
+  skill    the agent skill \`init --skill\` installs
+`;
+
+export function run(argv) {
+  const args = parseArgs(argv, {});
+  const topic = args._[0] ?? "method";
+  if (!TOPICS[topic]) throw new UsageError(`unknown topic "${topic}" — expected: ${Object.keys(TOPICS).join(", ")}`);
+  const config = findConfig() ? loadConfig() : null;
+  const values = { root: config?.root ?? DEFAULT_ROOT, trailer: config?.trailer ?? "Doc" };
+  console.log(fill(packageFile("guide", ...TOPICS[topic]), values).trimEnd());
+}

package/src/commands/index.mjs

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { c, emitJson, ok, parseArgs, say, warn } from "../cli.mjs";
+import { loadConfig } from "../config.mjs";
+import { derive, gitFacts, loadDocs, writeDoc } from "../docs.mjs";
+import { renderIndex } from "../render.mjs";
+
+export const summary = "recompute the derived fields and regenerate INDEX.md";
+
+export const help = `honestdocs index — ${summary}
+
+  honestdocs index [--dry-run] [--json]
+
+Writes into each document the fields nobody should type: progress (from its
+checklist), files (from commits carrying the trailer), superseded-by (from the
+newer document's supersedes), updated (from git). Then regenerates INDEX.md.
+
+  --dry-run   report what would change, write nothing
+  --json      the report as JSON on stdout
+`;
+
+/** Derive, write, render. Shared by `done`, `status` and `init`, which end with an index. */
+export function runIndex(config, { dryRun = false } = {}) {
+  const docs = loadDocs(config);
+  const facts = gitFacts(config);
+  const changed = derive(config, docs, facts);
+  for (const ch of changed) {
+    ch.doc.meta = ch.meta;
+    if (!dryRun) writeDoc(ch.doc);
+  }
+  const indexFile = join(config.docsDir, "INDEX.md");
+  const content = renderIndex(config, docs.filter((d) => d.hasMeta));
+  const indexChanged = !existsSync(indexFile) || readFileSync(indexFile, "utf8") !== content;
+  if (indexChanged && !dryRun) writeFileSync(indexFile, content);
+  return {
+    documents: docs.length,
+    git: facts.available ? "ok" : facts.reason,
+    changed: changed.map((ch) => ({
+      file: ch.doc.rel,
+      fields: Object.keys({ ...ch.before, ...ch.meta }).filter(
+        (k) => JSON.stringify(ch.before[k]) !== JSON.stringify(ch.meta[k]),
+      ),
+    })),
+    index: indexChanged ? (dryRun ? "would change" : "written") : "unchanged",
+  };
+}
+
+export function report(config, r, dryRun) {
+  if (r.git !== "ok") warn(`git: ${r.git} — files and updated were left as they are`);
+  if (dryRun) say(c.yellow(`dry run — ${r.changed.length} document(s) would change; INDEX.md ${r.index}`));
+  else ok(`${config.root}/INDEX.md — ${r.documents} document(s), index ${r.index}`);
+  for (const ch of r.changed.slice(0, 20)) say(c.dim(`  ${ch.file}: ${ch.fields.join(", ")}`));
+  if (r.changed.length > 20) say(c.dim(`  … and ${r.changed.length - 20} more`));
+}
+
+export function run(argv) {
+  const args = parseArgs(argv, { "dry-run": "boolean", json: "boolean" });
+  const config = loadConfig();
+  const r = runIndex(config, { dryRun: args["dry-run"] });
+  if (args.json) emitJson(r);
+  else report(config, r, args["dry-run"]);
+}