bearings 0.2.0

package/README.md

@@ -0,0 +1,92 @@
+# bearings
+
+`bearings` is a small TypeScript CLI that helps you give your agents their bearings: it scaffolds an agent-friendly repository setup, exposes shared skills and commands to supported harnesses, records the generated files in a manifest, and leaves project-specific tailoring to your AI agent via `/setup-repo`.
+
+## Quick Start
+
+```sh
+npx bearings init
+/setup-repo
+bearings verify
+```
+
+1. `npx bearings init` writes the generic scaffold and prints the next step.
+2. `/setup-repo` runs inside your AI agent to merge backups, fill placeholders, seed docs, and tailor skills.
+3. `bearings verify` checks the scaffold for drift, missing files, broken exposures, and unresolved setup warnings.
+
+## What Gets Generated
+
+```text
+AGENTS.md
+CLAUDE.md
+docs/
+  CURRENT_STATE.md
+  conventions/
+    current-state.md
+    doc-lifecycle.md
+  adr/
+    0000-template.md
+  deferred/
+    INDEX.md
+.agents/
+  bearings.json
+  commands/
+    current-state.md
+    setup-repo.md
+  skills/
+    repo-navigation/SKILL.md
+    implementing-task/SKILL.md
+    installing-dependencies/SKILL.md
+    secrets-handling/SKILL.md
+    enforcement-gates/SKILL.md
+    commit-convention/SKILL.md
+    defer-work/SKILL.md
+    resurface-deferred-work/SKILL.md
+.claude/
+  commands/*
+  skills/*
+.opencode/
+  commands/*
+  skills/*
+```
+
+Existing scaffold targets are backed up as `<path>.bkp` before replacement. Re-running `init` skips unchanged managed files.
+
+## The Model
+
+Agent-friendly context is routed, not dumped.
+
+```text
+user task
+  -> root agent seed
+  -> current-state map
+  -> situation-specific skills
+  -> task/runbook/spec docs when needed
+  -> executable guardrails before completion
+```
+
+## Commands Reference
+
+### `bearings init`
+
+Scaffold the agent-friendly setup in the current repository.
+
+| Flag | Meaning |
+|---|---|
+| `--harness <name...>` | Expose to `claude` and/or `opencode`. Defaults to detected harness dirs, or both in a fresh repo. |
+| `--copy` | Copy exposures instead of symlinking them. `verify` checks copy drift. |
+| `-y`, `--yes` | Accept defaults and do not prompt. |
+
+### `bearings verify`
+
+Check the manifest and harness exposures for mechanical breakage. Exit code `0` means no failures; exit code `1` means one or more failures.
+
+| Code | Severity | Condition |
+|---|---|---|
+| `no-manifest` | fail | `.agents/bearings.json` missing |
+| `missing-file` | fail | manifest entry path doesn't exist |
+| `missing-exposure` | fail | a child of `.agents/skills` or `.agents/commands` absent from a configured harness dir |
+| `broken-symlink` | fail | harness entry is a symlink whose target doesn't resolve |
+| `copy-drift` | fail | copy mode: harness file content differs from `.agents` source content |
+| `unfilled-placeholder` | warn | a bearings-generated file still contains `<agent:` |
+| `unreviewed-backup` | warn | manifest `backup` path still exists on disk |

package/dist/cli.js

@@ -0,0 +1,477 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import { readFileSync } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname4, join as join8 } from "path";
+
+// src/commands/init.ts
+import { lstat as lstat2, readdir as readdir2 } from "fs/promises";
+import { join as join6 } from "path";
+
+// src/scanner.ts
+import { access, symlink, rm } from "fs/promises";
+import { join as join2 } from "path";
+
+// src/paths.ts
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+function templatesDir() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "templates");
+}
+var SKILLS = [
+  "repo-navigation",
+  "implementing-task",
+  "installing-dependencies",
+  "secrets-handling",
+  "enforcement-gates",
+  "commit-convention",
+  "defer-work",
+  "resurface-deferred-work"
+];
+var SCAFFOLD = [
+  { template: "AGENTS.md", target: "AGENTS.md", owner: "agent" },
+  { template: "CLAUDE.md", target: "CLAUDE.md", owner: "bearings" },
+  { template: "docs/CURRENT_STATE.md", target: "docs/CURRENT_STATE.md", owner: "agent" },
+  { template: "docs/conventions/current-state.md", target: "docs/conventions/current-state.md", owner: "bearings" },
+  { template: "docs/conventions/doc-lifecycle.md", target: "docs/conventions/doc-lifecycle.md", owner: "bearings" },
+  { template: "docs/adr/0000-template.md", target: "docs/adr/0000-template.md", owner: "bearings" },
+  { template: "docs/deferred/INDEX.md", target: "docs/deferred/INDEX.md", owner: "agent" },
+  { template: "agents/commands/current-state.md", target: ".agents/commands/current-state.md", owner: "bearings" },
+  { template: "agents/commands/setup-repo.md", target: ".agents/commands/setup-repo.md", owner: "bearings" },
+  ...SKILLS.map((s) => ({
+    template: `agents/skills/${s}/SKILL.md`,
+    target: `.agents/skills/${s}/SKILL.md`,
+    owner: s === "installing-dependencies" || s === "secrets-handling" ? "agent" : "bearings"
+  }))
+];
+
+// src/scanner.ts
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function scan(repoDir) {
+  const collisions = [];
+  for (const e of SCAFFOLD) if (await exists(join2(repoDir, e.target))) collisions.push(e.target);
+  const harnessDirsPresent = [];
+  for (const h of ["claude", "opencode"])
+    if (await exists(join2(repoDir, `.${h}`))) harnessDirsPresent.push(h);
+  let symlinksSupported = true;
+  const probe = join2(repoDir, ".bearings-symlink-probe");
+  try {
+    await symlink(".", probe);
+    await rm(probe);
+  } catch {
+    symlinksSupported = false;
+  }
+  return { collisions, harnessDirsPresent, symlinksSupported };
+}
+
+// src/generator.ts
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2, rename, access as access2 } from "fs/promises";
+import { dirname as dirname2, join as join4 } from "path";
+
+// src/manifest.ts
+import { createHash } from "crypto";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join as join3 } from "path";
+function sha256(content) {
+  return "sha256:" + createHash("sha256").update(content).digest("hex");
+}
+function manifestPath(repoDir) {
+  return join3(repoDir, ".agents", "bearings.json");
+}
+async function saveManifest(repoDir, m) {
+  await mkdir(join3(repoDir, ".agents"), { recursive: true });
+  await writeFile(manifestPath(repoDir), JSON.stringify(m, null, 2) + "\n");
+}
+async function loadManifest(repoDir) {
+  try {
+    return JSON.parse(await readFile(manifestPath(repoDir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// src/generator.ts
+async function exists2(p) {
+  try {
+    await access2(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function freeBackupPath(repoDir, target) {
+  let candidate = `${target}.bkp`;
+  for (let i = 1; await exists2(join4(repoDir, candidate)); i++) candidate = `${target}.bkp.${i}`;
+  return candidate;
+}
+async function generate(repoDir, bearingsVersion) {
+  const prior = await loadManifest(repoDir);
+  const result = { written: [], backedUp: [], skippedUnchanged: [], files: [] };
+  for (const entry of SCAFFOLD) {
+    const abs = join4(repoDir, entry.target);
+    const templateContent = await readFile2(join4(templatesDir(), entry.template), "utf8");
+    const priorEntry = prior?.files.find((f) => f.path === entry.target);
+    let backup;
+    if (await exists2(abs)) {
+      const current = await readFile2(abs, "utf8");
+      if (priorEntry && sha256(current) === priorEntry.hash) {
+        result.skippedUnchanged.push(entry.target);
+        result.files.push(priorEntry);
+        continue;
+      }
+      backup = await freeBackupPath(repoDir, entry.target);
+      await rename(abs, join4(repoDir, backup));
+      result.backedUp.push({ path: entry.target, backup });
+    }
+    await mkdir2(dirname2(abs), { recursive: true });
+    await writeFile2(abs, templateContent);
+    result.written.push(entry.target);
+    result.files.push({
+      path: entry.target,
+      template: entry.template,
+      templateVersion: bearingsVersion,
+      hash: sha256(templateContent),
+      owner: entry.owner,
+      ...backup ? { backup } : {}
+    });
+  }
+  return result;
+}
+
+// src/adapters.ts
+import { mkdir as mkdir3, readdir, symlink as symlink2, lstat, readlink, rm as rm2, cp, readFile as readFile3 } from "fs/promises";
+import { join as join5 } from "path";
+var KINDS = ["skills", "commands"];
+async function entriesMatch(src, dst) {
+  const srcStat = await lstat(src).catch(() => null);
+  const dstStat = await lstat(dst).catch(() => null);
+  if (!srcStat || !dstStat) return false;
+  if (srcStat.isSymbolicLink() || dstStat.isSymbolicLink()) {
+    return srcStat.isSymbolicLink() && dstStat.isSymbolicLink() && await readlink(src) === await readlink(dst);
+  }
+  if (srcStat.isDirectory() || dstStat.isDirectory()) {
+    if (!srcStat.isDirectory() || !dstStat.isDirectory()) return false;
+    const [srcEntries, dstEntries] = await Promise.all([readdir(src), readdir(dst)]);
+    if (srcEntries.length !== dstEntries.length) return false;
+    srcEntries.sort();
+    dstEntries.sort();
+    for (let i = 0; i < srcEntries.length; i++) {
+      if (srcEntries[i] !== dstEntries[i]) return false;
+      if (!await entriesMatch(join5(src, srcEntries[i]), join5(dst, dstEntries[i]))) return false;
+    }
+    return true;
+  }
+  if (srcStat.isFile() || dstStat.isFile()) {
+    return srcStat.isFile() && dstStat.isFile() && (await readFile3(src)).equals(await readFile3(dst));
+  }
+  return false;
+}
+async function expose(repoDir, harness, mode) {
+  const created = [];
+  for (const kind of KINDS) {
+    const srcDir = join5(repoDir, ".agents", kind);
+    let entries;
+    try {
+      entries = await readdir(srcDir);
+    } catch {
+      continue;
+    }
+    const dstDir = join5(repoDir, `.${harness}`, kind);
+    await mkdir3(dstDir, { recursive: true });
+    for (const name of entries) {
+      const dst = join5(dstDir, name);
+      const adapterPath = join5(`.${harness}`, kind, name);
+      const relTarget = join5("..", "..", ".agents", kind, name);
+      const stat2 = await lstat(dst).catch(() => null);
+      if (mode === "symlink") {
+        if (stat2?.isSymbolicLink() && await readlink(dst) === relTarget) continue;
+        if (stat2 && !stat2.isSymbolicLink()) throw new Error(`Refusing to replace existing adapter entry: ${adapterPath}`);
+        if (stat2) await rm2(dst, { recursive: true });
+        await symlink2(relTarget, dst);
+      } else {
+        const src = join5(srcDir, name);
+        if (stat2 && await entriesMatch(src, dst)) continue;
+        if (stat2 && !stat2.isSymbolicLink()) throw new Error(`Refusing to replace existing adapter entry: ${adapterPath}`);
+        if (stat2) await rm2(dst, { recursive: true });
+        await cp(src, dst, { recursive: true });
+      }
+      created.push(adapterPath);
+    }
+  }
+  return created;
+}
+
+// src/report.ts
+function renderInitReport(r, exposed, m) {
+  const lines = ["bearings init complete.", ""];
+  lines.push(`Written (${r.written.length}):`, ...r.written.map((p) => `  + ${p}`));
+  if (r.backedUp.length) {
+    lines.push("", `Backed up (${r.backedUp.length}) \u2014 review during /setup-repo:`);
+    lines.push(...r.backedUp.map((b) => `  \u26A0 ${b.path} -> ${b.backup}`));
+  }
+  if (r.skippedUnchanged.length) {
+    lines.push(
+      "",
+      `Skipped, unchanged (${r.skippedUnchanged.length}):`,
+      ...r.skippedUnchanged.map((p) => `  = ${p}`)
+    );
+  }
+  lines.push(
+    "",
+    `Exposed to harnesses [${m.harnesses.join(", ")}] via ${m.exposure}:`,
+    ...exposed.map((p) => `  ~ ${p}`)
+  );
+  lines.push(
+    "",
+    "Next step \u2014 finish setup with your AI agent:",
+    "  Open your agent (Claude Code, OpenCode, ...) in this repo and run:",
+    "    /setup-repo",
+    "  It will review any backups, interview you, and tailor the setup.",
+    "  Finish by running: bearings verify"
+  );
+  return lines.join("\n");
+}
+function renderVerifyReport(v) {
+  const lines = [];
+  for (const f of v.failures) lines.push(`FAIL ${f.code} ${f.path} \u2014 ${f.message}`);
+  for (const w of v.warnings) lines.push(`warn ${w.code} ${w.path} \u2014 ${w.message}`);
+  lines.push(v.failures.length ? `
+${v.failures.length} failure(s).` : "\nbearings verify: OK");
+  return lines.join("\n");
+}
+
+// src/commands/init.ts
+var VALID_HARNESSES = ["claude", "opencode"];
+var KINDS2 = ["skills", "commands"];
+function validateHarnesses(harnesses) {
+  if (!harnesses) return void 0;
+  for (const harness of harnesses) {
+    if (!VALID_HARNESSES.includes(harness)) {
+      throw new Error(`Invalid harness: ${String(harness)}`);
+    }
+  }
+  return harnesses;
+}
+function cancelInit(p) {
+  p.cancel("Init cancelled.");
+  throw new Error("Init cancelled.");
+}
+async function plannedAdapterSources(repoDir) {
+  const sources = { skills: /* @__PURE__ */ new Map(), commands: /* @__PURE__ */ new Map() };
+  for (const entry of SCAFFOLD) {
+    for (const kind of KINDS2) {
+      const prefix = `.agents/${kind}/`;
+      if (entry.target.startsWith(prefix)) {
+        const name = entry.target.slice(prefix.length).split("/")[0];
+        sources[kind].set(name, join6(templatesDir(), "agents", kind, name));
+      }
+    }
+  }
+  for (const kind of KINDS2) {
+    const srcDir = join6(repoDir, ".agents", kind);
+    for (const name of await readdir2(srcDir).catch(() => [])) {
+      if (!sources[kind].has(name)) sources[kind].set(name, join6(srcDir, name));
+    }
+  }
+  return sources;
+}
+async function preflightAdapterCollisions(repoDir, harnesses, exposure) {
+  const sources = await plannedAdapterSources(repoDir);
+  for (const h of harnesses) {
+    for (const kind of KINDS2) {
+      for (const [name, source] of sources[kind]) {
+        const adapterPath = join6(`.${h}`, kind, name);
+        const target = join6(repoDir, adapterPath);
+        const stat2 = await lstat2(target).catch(() => null);
+        if (!stat2 || stat2.isSymbolicLink()) continue;
+        if (exposure === "copy" && await entriesMatch(source, target)) continue;
+        throw new Error(`Refusing to replace existing adapter entry: ${adapterPath}`);
+      }
+    }
+  }
+}
+async function runInit(repoDir, flags, version) {
+  const s = await scan(repoDir);
+  let harnesses = validateHarnesses(flags.harnesses);
+  let exposure = flags.exposure;
+  if (!harnesses || !exposure) {
+    if (flags.yes || !process.stdin.isTTY) {
+      harnesses ??= s.harnessDirsPresent.length ? s.harnessDirsPresent : ["claude", "opencode"];
+      exposure ??= s.symlinksSupported ? "symlink" : "copy";
+    } else {
+      const p = await import("@clack/prompts");
+      if (!harnesses) {
+        const selectedHarnesses = await p.multiselect({
+          message: "Expose skills/commands to which harnesses?",
+          options: [
+            { value: "claude", label: "Claude Code (.claude/)" },
+            { value: "opencode", label: "OpenCode (.opencode/)" }
+          ],
+          initialValues: s.harnessDirsPresent.length ? s.harnessDirsPresent : ["claude", "opencode"]
+        });
+        if (p.isCancel(selectedHarnesses)) {
+          cancelInit(p);
+        }
+        harnesses = validateHarnesses(selectedHarnesses);
+      }
+      if (!exposure && s.symlinksSupported) {
+        const selectedExposure = await p.select({
+          message: "Exposure mode?",
+          options: [
+            { value: "symlink", label: "Symlinks (recommended)" },
+            { value: "copy", label: "Copies (verify checks drift)" }
+          ]
+        });
+        if (p.isCancel(selectedExposure)) {
+          cancelInit(p);
+        }
+        exposure = selectedExposure;
+      } else {
+        exposure ??= "copy";
+      }
+    }
+  }
+  await preflightAdapterCollisions(repoDir, harnesses, exposure);
+  const gen = await generate(repoDir, version);
+  const exposed = [];
+  for (const h of harnesses) exposed.push(...await expose(repoDir, h, exposure));
+  const manifest = {
+    version: 1,
+    bearingsVersion: version,
+    harnesses,
+    exposure,
+    files: gen.files
+  };
+  await saveManifest(repoDir, manifest);
+  return { manifest, report: renderInitReport(gen, exposed, manifest) };
+}
+
+// src/verifier.ts
+import { access as access3, lstat as lstat3, readFile as readFile4, readdir as readdir3, readlink as readlink2, stat } from "fs/promises";
+import { dirname as dirname3, join as join7, resolve } from "path";
+var KINDS3 = ["skills", "commands"];
+async function exists3(p) {
+  try {
+    await access3(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function verify(repoDir) {
+  const failures = [];
+  const warnings = [];
+  const m = await loadManifest(repoDir);
+  if (!m) return { failures: [{ code: "no-manifest", path: ".agents/bearings.json", message: "run bearings init first" }], warnings };
+  for (const f of m.files) {
+    const abs = join7(repoDir, f.path);
+    if (!await exists3(abs)) {
+      failures.push({ code: "missing-file", path: f.path, message: "managed file deleted" });
+      continue;
+    }
+    const content = await readFile4(abs, "utf8");
+    if (content.includes("<agent:")) {
+      warnings.push({ code: "unfilled-placeholder", path: f.path, message: "run /setup-repo to fill" });
+    }
+    if (f.backup && await exists3(join7(repoDir, f.backup))) {
+      warnings.push({ code: "unreviewed-backup", path: f.backup, message: "review during /setup-repo, then delete" });
+    }
+  }
+  for (const kind of KINDS3) {
+    const srcDir = join7(repoDir, ".agents", kind);
+    let entries = [];
+    try {
+      entries = await readdir3(srcDir);
+    } catch {
+    }
+    for (const h of m.harnesses) {
+      for (const name of entries) {
+        const exposurePath = join7(`.${h}`, kind, name);
+        const dst = join7(repoDir, `.${h}`, kind, name);
+        const l = await lstat3(dst).catch(() => null);
+        if (!l) {
+          failures.push({ code: "missing-exposure", path: exposurePath, message: `not exposed to ${h}` });
+          continue;
+        }
+        if (l.isSymbolicLink()) {
+          if (!await stat(dst).catch(() => null)) {
+            failures.push({ code: "broken-symlink", path: exposurePath, message: "symlink target missing" });
+          } else {
+            const target = await readlink2(dst);
+            if (resolve(dirname3(dst), target) !== resolve(srcDir, name)) {
+              failures.push({ code: "missing-exposure", path: exposurePath, message: `not exposed to ${h}` });
+            }
+          }
+        } else if (m.exposure === "symlink") {
+          failures.push({ code: "missing-exposure", path: exposurePath, message: `not exposed to ${h}` });
+        } else {
+          const src = join7(srcDir, name);
+          if (await copyDrifted(src, dst)) {
+            failures.push({ code: "copy-drift", path: exposurePath, message: "diverged from .agents source" });
+          }
+        }
+      }
+    }
+  }
+  return { failures, warnings };
+}
+async function copyDrifted(src, dst) {
+  const s = await stat(src);
+  if (s.isDirectory()) {
+    const [srcChildren, dstChildren] = await Promise.all([
+      readdir3(src),
+      readdir3(dst).catch(() => null)
+    ]);
+    if (dstChildren === null) return true;
+    const srcNames = new Set(srcChildren);
+    for (const child of dstChildren) {
+      if (!srcNames.has(child)) return true;
+    }
+    for (const child of srcChildren) {
+      if (await copyDrifted(join7(src, child), join7(dst, child))) return true;
+    }
+    return false;
+  }
+  const [a, b] = await Promise.all([
+    readFile4(src, "utf8"),
+    readFile4(dst, "utf8").catch(() => null)
+  ]);
+  return b === null || sha256(a) !== sha256(b);
+}
+
+// src/commands/verify.ts
+async function runVerify(repoDir) {
+  const v = await verify(repoDir);
+  console.log(renderVerifyReport(v));
+  return v.failures.length ? 1 : 0;
+}
+
+// src/cli.ts
+var pkg = JSON.parse(
+  readFileSync(join8(dirname4(fileURLToPath2(import.meta.url)), "../package.json"), "utf8")
+);
+var program = new Command("bearings").version(pkg.version);
+program.command("init").description("Scaffold the agent-friendly setup in the current repository").option("--harness <name...>", "claude and/or opencode").option("--copy", "copy instead of symlink").option("-y, --yes", "accept defaults, no prompts").action(async (o) => {
+  const { report } = await runInit(process.cwd(), {
+    harnesses: validateHarnesses(o.harness),
+    exposure: o.copy ? "copy" : void 0,
+    yes: o.yes
+  }, pkg.version);
+  console.log(report);
+});
+program.command("verify").description("Check the agent-friendly setup for drift and breakage").action(async () => {
+  process.exitCode = await runVerify(process.cwd());
+});
+program.parseAsync().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "bearings",
+  "version": "0.2.0",
+  "description": "Give your AI agents their bearings — scaffold an agent-friendly setup in any repository.",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "bearings": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/AGENTS.md

@@ -0,0 +1,43 @@
+# <agent: project name> - Agent Seed
+
+Read this first. Load deeper context only when the task matches.
+
+## Project
+
+<agent: fill during handoff — Short summary of what this repo is, who uses it, and what it produces.>
+
+## Where To Read What
+
+| You need... | Read |
+|---|---|
+| What exists today and where things live | `docs/CURRENT_STATE.md` |
+| Durable architecture and decisions | `docs/ARCHITECTURE.md`, `docs/adr/` |
+| Deferred work | `docs/deferred/INDEX.md` |
+
+## Load On Demand
+
+| When you are... | Load skill |
+|---|---|
+| finding where code lives or which docs to read | `repo-navigation` |
+| touching secrets, credentials, keys, tokens, or config containing secrets | `secrets-handling` |
+| implementing a planned task | `implementing-task` |
+| adding dependencies | `installing-dependencies` |
+| fixing failed checks | `enforcement-gates` |
+| about to commit | `commit-convention` |
+| building something listed in deferred work | `resurface-deferred-work` |
+
+## Hard Invariants
+
+- <agent: fill during handoff — Invariant 1 with required skill/doc.>
+- <agent: fill during handoff — Invariant 2 with required verification.>
+
+## Always-On Rules
+
+- Read `docs/CURRENT_STATE.md` before broad exploration.
+- Do not read archived or generated folders unless explicitly needed.
+- Do not silently rewrite durable docs during unrelated work.
+- Before claiming completion, run the smallest relevant verification command or say why it could not run.
+
+## Setup Status
+
+Setup pending — run /setup-repo. <agent: remove this section when handoff is complete>

package/templates/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/agents/commands/current-state.md

@@ -0,0 +1,163 @@
+---
+description: Generate or refresh docs/CURRENT_STATE.md and, if `docs/diagrams/` exists in this repo, docs/diagrams/c4-component.puml — the source-of-truth source map
+---
+
+# /current-state
+
+Refresh `docs/CURRENT_STATE.md` and, if `docs/diagrams/` exists in this repo, `docs/diagrams/c4-component.puml` when component topology changes. Runs after each committed task, or standalone when the source map has drifted.
+
+This command is the **only** writer for `CURRENT_STATE.md` and, if `docs/diagrams/` exists in this repo, `c4-component.puml`. Do not touch either during implementation.
+
+## When to run
+
+- After a task is implemented and committed — typical use, run in the same thread.
+- Standalone, when the source map has drifted and needs catching up without a task in progress.
+- First time, to seed `CURRENT_STATE.md` for an existing codebase or a freshly-skeletoned project.
+
+## Required sections — CURRENT_STATE.md
+
+Exactly these headings, in this order. Empty section: keep the heading with `(none)`. Do not remove.
+
+```markdown
+# CURRENT_STATE
+
+## Purpose
+
+<1–2 sentences, caveman: what codebase does, for whom>
+
+## Stack
+
+<lang ⊕ framework ⊕ key libs; versions only when material>
+
+## Shipped capabilities
+
+<flat list, 1 line each — only end-user functionality working today>
+
+## Source map
+
+<folder/file tree, 1-line purpose per node — tech-lead pointer granularity>
+
+## Design patterns in use
+
+<pattern name → file/dir>
+
+## Public interfaces
+
+<HTTP routes / UI routes / CLI cmds / events / queues>
+
+## Data model digest
+
+<link to docs/diagrams/erd.puml ⊕ 1-line table list>
+
+## Component diagram
+
+<embed of rendered docs/diagrams/rendered/c4-component.svg, if `docs/diagrams/` exists in this repo>
+
+## Known debt / TODOs
+
+<short, current; deleted once addressed>
+```
+
+## Caveman style — whole file
+
+- Bullet fragments. Drop articles (`the`, `a`).
+- Symbols: `→` leads-to · `⊕` and-also · `~` approximately · `Δ` change · `&` and-also.
+- `file:line` over prose: `auth/login.ts:42` ✓ · "line 42 of auth/login.ts" ✗.
+- No hedging (`might`, `could`, `perhaps`) — state or omit.
+- No preamble, no meta, no restating the question.
+- 1 line per entry where possible.
+
+Example:
+
+```
+## Shipped capabilities
+- email/pw signup ⊕ verify
+- JWT auth → 7d refresh
+- profile edit (name, avatar)
+
+## Source map
+- src/auth/ — signup, login, JWT issuance
+  - login.ts:42 → token mint
+  - guards/ — route protection
+- src/users/ — CRUD ⊕ profile
+- src/db/ — Prisma client ⊕ migrations
+```
+
+## Inputs
+
+Gather these in order — the diff is the truth source; task or issue context describes intent:
+
+1. **`docs/CURRENT_STATE.md`** — baseline to preserve.
+2. **If `docs/diagrams/` exists in this repo, `docs/diagrams/c4-component.puml`** — component baseline.
+3. **Task or issue context** — identify from conversation context, linked issue/spec, or `git log -1 --format=%B`. Read named context docs for intended Δ when present.
+4. **Adjacent planning docs** — read only if linked by the task, issue, spec, or commit message.
+5. **`git diff HEAD~1`** — what actually shipped; trust this over intent docs if they diverge.
+
+## Procedure A — generate from scratch (no file exists)
+
+Covers (a) existing codebase adopting the methodology, (b) new project past design/skeleton phase.
+
+1. **Stack** — read manifests: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `tsconfig.json`, `vite.config.*`, `next.config.*`, `prisma/schema.prisma`, etc.
+2. **Source map** — walk top-down. Per top-level folder: read `index.*` / `mod.rs` / `__init__.py`, the largest file, any `README.md`. Stop at tech-lead-pointer granularity (deep enough to route a dev to the right file, no deeper). Symbol-level entries only when the symbol _is_ the landmark.
+3. **Public interfaces** — find route registrations (Express/NestJS/FastAPI/Django/etc.), CLI entry points (`bin/`, `cmd/`, `cli.*`), event/queue handlers.
+4. **Data model digest** — read schema + migrations → 1-line table list. Link `docs/diagrams/erd.puml` if it exists; if not, link `prisma/schema.prisma` or equivalent. Do not inline schema.
+5. **Design patterns in use** — recurring shapes by directory naming + import graph (Repository, Service, UseCase, Controller, ...). Pattern → file/dir.
+6. **Shipped capabilities** — user-facing features actually working today. Skip in-flight or planned. If unsure what works, **ask the user**. Do not infer from task files or phase docs.
+7. **Component diagram** — if `docs/diagrams/` exists in this repo and `docs/diagrams/c4-component.puml` does not exist, create a minimal skeleton from the source map's top-level boundaries. Render to SVG via `docker run --rm -v "$PWD:/data" plantuml/plantuml -tsvg docs/diagrams/c4-component.puml`. Embed the rendered SVG path in the section. If `docs/diagrams/` does not exist in this repo, write `(none)` in the section.
+8. **Known debt / TODOs** — grep `TODO|FIXME|HACK|XXX`. Add obvious gaps spotted during the walk.
+9. **Purpose** — 1–2 caveman sentences. If unclear, **ask the user**. Do not guess.
+10. Apply caveman style end-to-end. Re-read once. Cut every word with no signal.
+
+After drafting: surface to user, ask for corrections. The first version is a draft, not the answer.
+
+## Procedure B — update an existing file
+
+Trigger: a task was just committed and `/current-state` is called in the same thread, or standalone drift correction.
+
+1. Read `docs/CURRENT_STATE.md` fully — establish the baseline.
+2. If `docs/diagrams/` exists in this repo, read `docs/diagrams/c4-component.puml` — establish the component baseline.
+3. Identify the completed task or issue from conversation context or `git log -1 --format=%B`. Read named context docs for intended Δ when present.
+4. Run `git diff HEAD~1` — confirm what actually shipped. This is the truth source.
+5. Map change to affected sections — most tasks touch 1–3:
+   - new dep → **Stack**
+   - new user-facing feature working today → **Shipped capabilities**
+   - new/renamed/removed file or folder, or purpose shift → **Source map**
+   - new endpoint/CLI/event → **Public interfaces**
+   - new migration → **Data model digest**
+   - new component or container relation → **Component diagram** if `docs/diagrams/` exists in this repo (edit `c4-component.puml`, re-render)
+   - new pattern adopted ⊕ old pattern retired → **Design patterns in use**
+   - debt resolved → **prune** from Known debt; new debt → add
+   - **Purpose** — touch only if scope actually shifted
+6. **Weigh new entries against the existing baseline.** A freshly-shipped task does not automatically replace older, more important entries. If the file is growing past one screen, prune low-signal entries first.
+7. Apply changes with the **Edit tool only** — surgical replacements. Never regenerate the file. Untouched sections stay byte-identical.
+8. **Prune obsolete entries.** File removed → delete source-map line. Pattern retired → delete entry. Debt resolved → delete item. Stale entries are worse than missing ones.
+9. New entries match surrounding density. Caveman throughout.
+10. If `docs/diagrams/` exists in this repo and `c4-component.puml` changed, re-render: `docker run --rm -v "$PWD:/data" plantuml/plantuml -tsvg docs/diagrams/c4-component.puml`. Update the embed path in the Component diagram section if the rendered filename changed.
+11. Re-read after editing. Cut redundancy the diff introduced.
+
+After updating: surface the diff of `CURRENT_STATE.md` to the user, flag any conflicts, ask for corrections. Once the user approves (or no corrections are needed), commit with a concise docs message such as:
+
+```
+docs: update CURRENT_STATE
+```
+
+Include only project-required trailers. Stage only `docs/CURRENT_STATE.md` and, if `docs/diagrams/` exists in this repo and changed, `docs/diagrams/c4-component.puml` plus its rendered SVG.
+
+## Conflict handling
+
+- **Task file says X, diff shows Y** → trust the diff. Note the divergence to the user.
+- **Manual human edit in `CURRENT_STATE.md` conflicts with new change** → trust the new change but **flag the conflict before overwriting**. The human edit may encode context the agent lacks.
+
+## Anti-bloat rules
+
+- No narrative. No restating code comments.
+- No planned, in-flight, or "next release" features. Only what works today.
+- No duplication of content that lives elsewhere — link instead (`→ prisma/schema.prisma`, `→ docs/diagrams/erd.puml`).
+- File grows with **source-tree structure**, not task count. Growing per-task → wrong content going in; rework the entry until it describes structure, not the task.
+- No business detail — that lives in `docs/features/`. `CURRENT_STATE.md` is a source map, not a feature catalog.
+- No history — `CURRENT_STATE.md` answers "what is"; `CHANGELOG.md` answers "how we got here". They never overlap.
+
+## Out of scope
+
+- Appending to `CHANGELOG.md`.
+- Editing unrelated requirements, prototypes, class diagrams, ERDs, context diagrams, or container diagrams.

package/templates/agents/commands/setup-repo.md

@@ -0,0 +1,49 @@
+---
+description: One-time (re-runnable) project tailoring after `bearings init`. Interviews the developer, explores the repo, and completes the agent-friendly setup.
+---
+
+# /setup-repo
+
+You are completing the agent-friendly setup that `bearings init` scaffolded.
+The scaffold is generic; your job is everything project-specific. Interview
+the developer relentlessly — one question at a time, with a recommended
+answer per question — and explore the code before asking anything the code
+can answer.
+
+## Required workflow
+
+1. Read `AGENTS.md`, `docs/conventions/doc-lifecycle.md`,
+   `docs/conventions/current-state.md`, and `.agents/bearings.json`.
+2. Review Backup Files: for every manifest entry with a `backup`, read the
+   backup, summarise what it contained, and ask the developer per file:
+   merge into the new scaffold / keep parts / discard. Apply their choice,
+   then delete the `.bkp` file once resolved.
+3. Explore the repo: stack, package manager, build/test/lint commands, CI,
+   generated files, secret/config paths, deployment surfaces.
+4. Interview the developer, one question at a time, covering at minimum:
+   - repository purpose and primary users/operators
+   - hard invariants that must never break
+   - off-limits paths
+   - what counts as verification ("smallest command that proves a change")
+   - concern detection: persisted data? secrets? IaC? frontend? release flow?
+5. Fill every `<agent: ...>` placeholder in `AGENTS.md` and the starter
+   skills. Keep `AGENTS.md` a router — deep content goes in docs/skills.
+6. For each detected concern with no matching skill, create
+   `.agents/skills/<name>/SKILL.md` (follow the shape of the starter
+   skills) and add a "Load on demand" row in `AGENTS.md`.
+7. Seed `docs/CURRENT_STATE.md` by running `/current-state`.
+8. Mirror any skills/commands you created into each harness dir the same
+   way existing ones are exposed (symlink or copy — check `.agents/bearings.json`).
+9. Run `bearings verify`. Fix every failure. Report remaining warnings to
+   the developer with a recommendation each.
+10. Remove the `## Setup Status` section from `AGENTS.md`.
+
+## Rules
+
+- Do not overwrite developer decisions silently — every merge/discard of a
+  backup is the developer's call.
+- Do not edit `.agents/bearings.json` except where this command requires it.
+- Do not invent invariants — every Hard Invariant line must come from the
+  developer or from clear evidence in the code (cite the path).
+- Re-running this command later is allowed: skip completed steps, focus on
+  drift between docs and reality.

package/templates/agents/skills/commit-convention/SKILL.md

@@ -0,0 +1,35 @@
+---
+description: Use before creating a git commit, writing a commit message, changelog entry, or release-affecting change.
+---
+
+# Commit Convention
+
+## Purpose
+
+Keep history searchable and release automation predictable.
+
+## Triggers
+
+- You are about to commit.
+- You are choosing a commit type, scope, footer, or release note.
+
+## Required Workflow
+
+1. Inspect `git status` and `git diff` -> stage only intended files.
+2. Choose the commit type and scope -> match the project's release rules.
+3. Write the commit message -> use the required format exactly.
+4. Commit without co-author trailers unless the developer asked for them.
+
+## Rules
+
+- Do: use `<agent: fill during handoff — commit message format and allowed types>`.
+- Do not: commit unrelated files, secrets, generated noise, or unverified work.
+
+## Verification
+
+- Run `<agent: fill during handoff — pre-commit verification command>` before committing when available.
+
+## References
+
+- `<agent: fill during handoff — release/changelog config path>` - release semantics.
+- `<agent: fill during handoff — contribution or commit policy path>` - local commit rules.

package/templates/agents/skills/defer-work/SKILL.md

@@ -0,0 +1,35 @@
+---
+description: Use when the developer explicitly parks, defers, postpones, skips-for-now, or chooses an interim solution instead of a fuller plan.
+---
+
+# Defer Work
+
+## Purpose
+
+Record intentional "yes, later" work so future agents do not silently build or forget it.
+
+## Triggers
+
+- The developer says work is deferred, parked, postponed, YAGNI, or skipped for now.
+- A simple interim solution ships instead of the fuller planned solution.
+
+## Required Workflow
+
+1. Confirm the deferred item -> get explicit developer approval to record it.
+2. Capture business need, parked approach, reason, and revisit trigger -> make the future decision self-contained.
+3. Create `docs/deferred/DEF-NNN-topic.md` -> assign the next available ID.
+4. Add a row to `docs/deferred/INDEX.md` -> include ID, parked item, revisit trigger, and detail path.
+
+## Rules
+
+- Do: record only currently parked work with a concrete revisit trigger.
+- Do not: record rejected-forever work or create deferred entries without developer confirmation.
+
+## Verification
+
+- Run `<agent: fill during handoff — docs verification command>` when deferred docs change.
+
+## References
+
+- `docs/deferred/INDEX.md` - registry of parked work.
+- `docs/conventions/doc-lifecycle.md` - deferred-work lifecycle.

package/templates/agents/skills/enforcement-gates/SKILL.md

@@ -0,0 +1,35 @@
+---
+description: Use when a local hook, lint, typecheck, test, build, validation, or CI gate fails.
+---
+
+# Enforcement Gates
+
+## Purpose
+
+Diagnose failed gates from evidence, fix the underlying issue, and avoid bypassing safety checks.
+
+## Triggers
+
+- A pre-commit, pre-push, CI, lint, typecheck, test, build, validation, or policy gate fails.
+- You are tempted to skip or weaken a check.
+
+## Required Workflow
+
+1. Capture the failing command and first relevant error -> identify the gate, not a symptom.
+2. Fix the smallest underlying cause -> keep the gate intact.
+3. Re-run the failed gate -> confirm it passes.
+4. Run adjacent verification if the fix changes behavior -> prevent regressions.
+
+## Rules
+
+- Do: preserve strict gate settings and cite the command/output in the report.
+- Do not: bypass hooks, lower thresholds, delete tests, or silence errors without a documented reason.
+
+## Verification
+
+- Run `<agent: fill during handoff — standard gate command>` after fixing any gate failure.
+
+## References
+
+- `<agent: fill during handoff — CI config path>` - canonical gate list.
+- `<agent: fill during handoff — local hook config path>` - developer gate list.

package/templates/agents/skills/implementing-task/SKILL.md

@@ -0,0 +1,36 @@
+---
+description: Use when implementing planned work from a task, issue, spec, or phase document.
+---
+
+# Implementing Task
+
+## Purpose
+
+Execute planned work without drifting from scope, skipping verification, or mixing unrelated changes.
+
+## Triggers
+
+- You are implementing a task/spec/issue with explicit requirements.
+- You are changing code under a feature or phase plan.
+
+## Required Workflow
+
+1. Read the task source and linked durable docs -> identify exact scope and exclusions.
+2. Write or update the smallest failing test first -> confirm the expected RED failure.
+3. Implement the minimal change -> keep unrelated files untouched.
+4. Run the required verification -> record command and outcome.
+5. Update current-state only through `/current-state` when shipped behavior or source map changed.
+
+## Rules
+
+- Do: preserve exact values, paths, and commands from the task source.
+- Do not: pull future-phase work forward or silently expand scope.
+
+## Verification
+
+- Run `<agent: fill during handoff — smallest command that proves a planned task>` before reporting completion.
+
+## References
+
+- `docs/CURRENT_STATE.md` - current source map.
+- `docs/conventions/doc-lifecycle.md` - durable vs planning document lifecycle.

package/templates/agents/skills/installing-dependencies/SKILL.md

@@ -0,0 +1,36 @@
+---
+description: Use when adding, removing, or updating dependencies, package-manager metadata, lockfiles, or workspace package links.
+---
+
+# Installing Dependencies
+
+## Purpose
+
+Keep dependency changes reproducible, scoped to the correct package, and aligned with the project's package manager.
+
+## Triggers
+
+- Adding, removing, or upgrading an external package.
+- Linking an internal workspace package.
+- Editing package manifests or lockfiles.
+
+## Required Workflow
+
+1. Identify package manager and workspace shape -> `<agent: fill during handoff — package manager and workspace command rules>`.
+2. Identify the owning package/app -> avoid installing at the wrong level.
+3. Run the package manager command -> update manifest and lockfile together.
+4. Run dependency-sensitive verification -> prove install and imports work.
+
+## Rules
+
+- Do: use `<agent: fill during handoff — approved package manager command>` for dependency changes.
+- Do not: edit lockfiles by hand or mix unrelated dependency upgrades.
+
+## Verification
+
+- Run `<agent: fill during handoff — install/build/test command after dependency changes>` when dependency metadata changes.
+
+## References
+
+- `<agent: fill during handoff — package manifest path>` - dependency owner.
+- `<agent: fill during handoff — lockfile path>` - resolved dependency graph.

package/templates/agents/skills/repo-navigation/SKILL.md

@@ -0,0 +1,34 @@
+---
+description: Use when exploring the repo, locating code, or deciding which docs and paths to read before making changes.
+---
+
+# Repo Navigation
+
+## Purpose
+
+Explore efficiently without crawling irrelevant, archived, generated, or project-specific material.
+
+## Triggers
+
+- You need to understand where code, docs, commands, or ownership rules live.
+- You are about to do broad repository exploration.
+
+## Required Workflow
+
+1. Read `docs/CURRENT_STATE.md` -> use it as the first source map.
+2. Read only the paths relevant to the task -> keep exploration proportional.
+3. If the source map is stale -> report the mismatch and continue from direct evidence.
+
+## Rules
+
+- Do: prefer durable docs, manifests, and entry points before deep file walks.
+- Do not: crawl archived, generated, vendored, or build-output folders unless the task explicitly needs them.
+
+## Verification
+
+- Run `<agent: fill during handoff — smallest command that proves navigation-sensitive changes>` when exploration changes generated docs or routing metadata.
+
+## References
+
+- `docs/CURRENT_STATE.md` - source map and current shipped shape.
+- `docs/conventions/current-state.md` - update policy and staleness rules.

package/templates/agents/skills/resurface-deferred-work/SKILL.md

@@ -0,0 +1,36 @@
+---
+description: Use before building, planning, or designing work that matches an entry in docs/deferred/INDEX.md.
+---
+
+# Resurface Deferred Work
+
+## Purpose
+
+Prevent agents from silently building over parked decisions without confirming the need and checking drift.
+
+## Triggers
+
+- A request matches a row in `docs/deferred/INDEX.md`.
+- You are about to plan or build something that was intentionally deferred.
+
+## Required Workflow
+
+1. Read the matching registry row and detail doc -> understand need, reason, and trigger.
+2. Confirm the developer still wants it -> do not expose stale implementation detail before confirming.
+3. Drift-check the parked plan against current code -> classify none, small, or too much drift.
+4. Present the viable path -> proceed, restructure, re-park, or reject forever.
+5. If shipped, remove the registry row and detail doc -> keep deferred work current.
+
+## Rules
+
+- Do: scan deferred work before planning new features.
+- Do not: silently build a parked item or trust an old plan without drift-checking it.
+
+## Verification
+
+- Run `<agent: fill during handoff — docs/code verification command>` when resurfaced work changes docs or code.
+
+## References
+
+- `docs/deferred/INDEX.md` - parked-work registry.
+- `docs/conventions/doc-lifecycle.md` - lifecycle for deferred plans.

package/templates/agents/skills/secrets-handling/SKILL.md

@@ -0,0 +1,36 @@
+---
+description: Use when touching credentials, tokens, keys, secret references, config containing secrets, or secret redaction paths.
+---
+
+# Secrets Handling
+
+## Purpose
+
+Prevent secrets from being committed, logged, exposed through APIs, or stored outside the approved secret store.
+
+## Triggers
+
+- Storing, reading, rotating, deleting, or displaying credentials.
+- Editing config, environment files, CI secrets, tokens, keys, or redaction logic.
+- Adding a new integration that needs a secret.
+
+## Required Workflow
+
+1. Identify the secret and owner -> `<agent: fill during handoff — secret store/provider and ownership rule>`.
+2. Store only references in code/config where possible -> keep raw values in the approved store.
+3. Verify redaction boundaries -> responses, logs, errors, docs, and tests must not reveal secret values.
+4. Rotate or revoke exposed values -> treat accidental disclosure as a security incident.
+
+## Rules
+
+- Do: use `<agent: fill during handoff — approved secret reference pattern>` for secret lookup and storage.
+- Do not: commit raw secrets, print them, include them in snapshots, or expose secret references where the project forbids it.
+
+## Verification
+
+- Run `<agent: fill during handoff — secret/config validation command>` when secret handling changes.
+
+## References
+
+- `<agent: fill during handoff — secret management doc/path>` - approved store and redaction contract.
+- `<agent: fill during handoff — config/env schema path>` - allowed secret references.

package/templates/docs/CURRENT_STATE.md

@@ -0,0 +1,38 @@
+# CURRENT_STATE
+
+## Purpose
+
+<agent: fill via /current-state>
+
+## Stack
+
+- <agent: fill via /current-state>
+- <agent: fill via /current-state>
+
+## Shipped capabilities
+
+- <agent: fill via /current-state>
+
+## Source map
+
+- `<agent: fill via /current-state>` - <agent: fill via /current-state>
+
+## Design patterns in use
+
+- <agent: fill via /current-state> -> <agent: fill via /current-state>
+
+## Public interfaces
+
+- <agent: fill via /current-state> -> <agent: fill via /current-state>
+
+## Data model digest
+
+- <agent: fill via /current-state> - <agent: fill via /current-state>
+
+## Component diagram
+
+- <agent: fill via /current-state>
+
+## Known debt / TODOs
+
+- <agent: fill via /current-state>

package/templates/docs/adr/0000-template.md

@@ -0,0 +1,17 @@
+# ADR-0000: <title>
+
+## Status
+
+State whether this decision is proposed, accepted, superseded, or rejected.
+
+## Context
+
+Describe the forces, constraints, and facts that make a decision necessary.
+
+## Decision
+
+Record the chosen approach and the scope where it applies.
+
+## Consequences
+
+List the tradeoffs, follow-up work, and verification impact.

package/templates/docs/conventions/current-state.md

@@ -0,0 +1,9 @@
+# Current State Policy
+
+## Policy
+
+- Agents read it before broad exploration.
+- If it answers the question, agents should not re-crawl the repo.
+- It should be updated only by an explicit command or maintenance workflow.
+- If stale, agents should report staleness instead of silently rewriting it during unrelated work.
+- Only `/current-state` writes `docs/CURRENT_STATE.md`.

package/templates/docs/conventions/doc-lifecycle.md

@@ -0,0 +1,16 @@
+# Documentation Lifecycle
+
+## Common categories
+
+| Category | Examples | Lifecycle |
+|---|---|---|
+| Durable | architecture, ADRs, glossary, operations, current-state conventions | Long-lived |
+| Planning | roadmap, phases, feature plans, task docs | Archived or removed after shipped |
+| Runbooks | deployment, rollback, manual checks, provider setup | Updated when operations change |
+| Deferred work | parked plans and revisit triggers | Removed when built or rejected |
+
+## Why this matters
+
+- Prevents agents from treating stale plans as shipped behavior.
+- Prevents durable docs from depending on soon-archived docs.
+- Gives agents a clear source of truth for scope disputes.

package/templates/docs/deferred/INDEX.md

@@ -0,0 +1,6 @@
+# Deferred Work
+
+| ID | Parked item | Revisit trigger | Detail |
+|---|---|---|---|
+
+Add a `DEF-NNN-topic.md` detail doc per entry. Scan this file before planning new features.