@evertonferreira96/agents 0.1.2 → 0.1.4

package/bin/agents.mjs

@@ -3,43 +3,67 @@
 //   agents init   [dir]  copy the config into the project (default: current directory); never overwrites
 //   agents update [dir]  refresh files the project did not edit, add new ones, delete untouched ones that left the config
 //   agents check  [dir]  report missing, outdated, edited and obsolete files; exit 1 on drift
+//   agents print-agents-md  print this version's AGENTS.md in its managed block (--raw: the file alone)
 // Flags: --force (update also overwrites files edited in the project, except CLAUDE.md, settings.local.json and agent memory),
-//        --dry-run (init/update: show what would change, write nothing).
-import { resolve } from "node:path";
-import { DEFAULT_SRC, drift, install, readPackage, report } from "../scripts/bootstrap.mjs";
+//        --dry-run (init/update: show what would change, write nothing),
+//        --agents-md=keep|overwrite|append|print (a project AGENTS.md that differs; asked in a terminal, default keep).
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { AGENTS_MD_CHOICES, DEFAULT_SRC, agentsBlock, drift, install, readPackage, report, settleAgentsMd } from "../scripts/bootstrap.mjs";
 
-const HELP = `Usage: agents <command> [dir] [--force] [--dry-run]
+const HELP = `Usage: agents <command> [dir] [flags]
 
 Commands:
-  init     copy the config into the project (never overwrites existing files)
-  update   refresh untouched files, add new ones, delete untouched files that left the config
-  check    report missing, outdated, edited and obsolete files (exit 1 on drift)
+  init             copy the config into the project (never overwrites existing files)
+  update           refresh untouched files, add new ones, delete untouched files that left the config
+  check            report missing, outdated, edited and obsolete files (exit 1 on drift)
+  print-agents-md  print the config AGENTS.md inside its managed block (--raw: the file alone)
 
 Flags:
-  --force    update also overwrites files edited in the project
-             (CLAUDE.md, .claude/settings.local.json and .claude/agent-memory/** are never touched)
-  --dry-run  show what init/update would change without writing
+  --force      update also overwrites files edited in the project
+               (CLAUDE.md, .claude/settings.local.json and .claude/agent-memory/** are never touched)
+  --dry-run    show what init/update would change without writing
+  --agents-md=<choice>
+               when the project already has its own AGENTS.md (asked in a terminal; default keep):
+               keep, overwrite, append (managed block refreshed by later updates) or print
 
 dir defaults to the current directory.`;
 
 const args = process.argv.slice(2);
-const flags = new Set(args.filter((a) => a.startsWith("-")));
-const [command, dir] = args.filter((a) => !a.startsWith("-"));
+const flags = new Set(), opts = {}, pos = [];
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === "--agents-md") opts["agents-md"] = args[++i] ?? "";
+  else if (a.startsWith("--") && a.includes("=")) opts[a.slice(2, a.indexOf("="))] = a.slice(a.indexOf("=") + 1);
+  else if (a.startsWith("-")) flags.add(a);
+  else pos.push(a);
+}
+const [command, dir] = pos;
 const pkg = readPackage(DEFAULT_SRC);
 
-if (flags.has("--version") || flags.has("-v")) { console.log(pkg.version); process.exit(0); }
-if (!command || command === "help" || flags.has("--help") || flags.has("-h")) { console.log(`${pkg.name} ${pkg.version}\n\n${HELP}`); process.exit(command ? 0 : 2); }
-if (!["init", "update", "check"].includes(command)) { console.error(`unknown command: ${command}\n\n${HELP}`); process.exit(2); }
+async function main() {
+  if (flags.has("--version") || flags.has("-v")) { console.log(pkg.version); return 0; }
+  if (!command || command === "help" || flags.has("--help") || flags.has("-h")) { console.log(`${pkg.name} ${pkg.version}\n\n${HELP}`); return command ? 0 : 2; }
+  if (!["init", "update", "check", "print-agents-md"].includes(command)) { console.error(`unknown command: ${command}\n\n${HELP}`); return 2; }
+  const agentsMd = opts["agents-md"];
+  if (agentsMd !== undefined && !AGENTS_MD_CHOICES.includes(agentsMd)) { console.error(`--agents-md must be one of: ${AGENTS_MD_CHOICES.join(", ")}`); return 2; }
+
+  if (command === "print-agents-md") {
+    process.stdout.write(flags.has("--raw") ? readFileSync(join(DEFAULT_SRC, "AGENTS.md"), "utf8") : agentsBlock(DEFAULT_SRC));
+    return 0;
+  }
 
-try {
   const target = resolve(dir ?? process.cwd());
-  const r = install({ target, mode: command, force: flags.has("--force"), dryRun: flags.has("--dry-run") });
+  const dryRun = flags.has("--dry-run");
+  const r = install({ target, mode: command, force: flags.has("--force"), dryRun });
   report(r);
-  if (command === "init" && !flags.has("--dry-run")) {
+  if (command !== "check") {
+    await settleAgentsMd({ target, r, choice: agentsMd, dryRun, interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY) });
+  }
+  if (command === "init" && !dryRun) {
     console.log("\nnext: fill in purpose and commands in CLAUDE.md; optional: `npx impeccable install` (for /ui) and `/graphify .`");
   }
-  process.exit(command === "check" && drift(r) ? 1 : 0);
-} catch (e) {
-  console.error(e.message);
-  process.exit(2);
+  return command === "check" && drift(r) ? 1 : 0;
 }
+
+main().then((code) => { process.exitCode = code; }, (e) => { console.error(e.message); process.exitCode = 2; });

package/bin/chew.mjs

@@ -3,8 +3,10 @@
 //   chew agents setup:pull [dir]   download the latest published config and install it (fresh project: everything;
 //                                  configured project: refresh what was not edited there, add new files, drop obsolete ones)
 //   chew agents setup:check [dir]  compare the project with the latest published config; exit 1 on drift
+//   chew agents setup:print        print the latest config AGENTS.md in its managed block (--raw: the file alone)
 // Flags: --force (also overwrite files edited in the project), --dry-run (show, write nothing),
-//        --local (use the version installed with chew instead of downloading the latest).
+//        --local (use the version installed with chew instead of downloading the latest),
+//        --agents-md=keep|overwrite|append|print (a project AGENTS.md that differs; asked in a terminal, default keep).
 // The install runs with the engine of the downloaded version, so an old global chew still applies the newest setup.
 // Test hook: CHEW_TARBALL=<path to a .tgz from `npm pack`> replaces the registry download.
 import { spawnSync } from "node:child_process";
@@ -21,18 +23,26 @@ const SCOPE = SELF.name.startsWith("@") ? SELF.name.split("/")[0] : null;
 
 const HELP = `chew ${SELF.version}
 
-Usage: chew agents <command> [dir] [--force] [--dry-run] [--local]
+Usage: chew agents <command> [dir] [flags]
 
 Commands:
   setup:pull   download the latest ${SELF.name} and install it into the project
                (fresh project: everything; configured project: refresh what was not edited there)
   setup:check  compare the project with the latest published config (exit 1 on drift)
+  setup:print  print the latest config AGENTS.md inside its managed block, to concatenate into yours
+               (--raw: the file alone, without the markers)
 
 Flags:
-  --force    also overwrite files edited in the project
-             (CLAUDE.md, .claude/settings.local.json and .claude/agent-memory/** are never touched)
-  --dry-run  show what would change without writing
-  --local    use the version installed with chew (${SELF.version}) instead of downloading
+  --force      also overwrite files edited in the project
+               (CLAUDE.md, .claude/settings.local.json and .claude/agent-memory/** are never touched)
+  --dry-run    show what would change without writing
+  --local      use the version installed with chew (${SELF.version}) instead of downloading
+  --agents-md=<choice>
+               when the project already has its own AGENTS.md (asked in a terminal; default keep):
+                 keep       leave yours as it is
+                 overwrite  replace it with the config version
+                 append     add the config version at the end, in a managed block that later pulls refresh
+                 print      print the config version to concatenate yourself
 
 dir defaults to the current directory.`;
 
@@ -99,16 +109,46 @@ function fetchConfig(local) {
 
 const newer = (a, b) => { const x = a.split(".").map(Number), y = b.split(".").map(Number); for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i]; return false; };
 
+const COMMANDS = ["setup:pull", "setup:check", "setup:print"];
+const AGENTS_MD = ["keep", "overwrite", "append", "print"];
+
+// Flags, `--name=value` / `--name value` options and positionals.
+function parseArgs(argv) {
+  const flags = new Set(), opts = {}, pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--agents-md") opts["agents-md"] = argv[++i] ?? "";
+    else if (a.startsWith("--") && a.includes("=")) { const k = a.slice(2, a.indexOf("=")); opts[k] = a.slice(a.indexOf("=") + 1); }
+    else if (a.startsWith("-")) flags.add(a);
+    else pos.push(a);
+  }
+  return { flags, opts, pos };
+}
+
 async function main(argv) {
-  const flags = new Set(argv.filter((a) => a.startsWith("-")));
-  const [ns, command, dir] = argv.filter((a) => !a.startsWith("-"));
+  const { flags, opts, pos } = parseArgs(argv);
+  const [ns, command, dir] = pos;
   if (flags.has("--version") || flags.has("-v")) { console.log(SELF.version); return 0; }
   if (!ns || ns === "help" || flags.has("--help") || flags.has("-h")) { console.log(HELP); return ns ? 0 : 2; }
-  if (ns !== "agents" || !["setup:pull", "setup:check"].includes(command)) {
+  const agentsMd = opts["agents-md"];
+  if (agentsMd !== undefined && !AGENTS_MD.includes(agentsMd)) { console.error(`--agents-md must be one of: ${AGENTS_MD.join(", ")}`); return 2; }
+  if (ns !== "agents" || !COMMANDS.includes(command)) {
     console.error(`unknown command: chew ${[ns, command].filter(Boolean).join(" ")}\n\n${HELP}`);
     return 2;
   }
 
+  if (command === "setup:print") { // stdout carries only the content, so it can be redirected or piped
+    const config = fetchConfig(flags.has("--local"));
+    try {
+      const engine = await import(pathToFileURL(join(config.dir, "scripts", "bootstrap.mjs")).href);
+      const raw = readFileSync(join(config.dir, "AGENTS.md"), "utf8");
+      process.stdout.write(flags.has("--raw") || !engine.agentsBlock ? raw : engine.agentsBlock(config.dir));
+      return 0;
+    } finally {
+      config.cleanup();
+    }
+  }
+
   const target = resolve(dir ?? process.cwd());
   if (!existsSync(target)) throw new Error(`target is not a directory: ${target}`);
   try { if (JSON.parse(readFileSync(join(target, "package.json"), "utf8")).name === SELF.name) throw new Error("this is the config repo itself; run chew inside a project"); }
@@ -120,6 +160,10 @@ async function main(argv) {
     const mode = command === "setup:check" ? "check" : "update";
     const r = engine.install({ src: config.dir, target, mode, force: flags.has("--force"), dryRun: flags.has("--dry-run") });
     engine.report(r);
+    if (mode === "update" && engine.settleAgentsMd) {
+      const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+      await engine.settleAgentsMd({ src: config.dir, target, r, choice: agentsMd, dryRun: flags.has("--dry-run"), interactive });
+    }
     if (mode === "update" && !flags.has("--dry-run") && r.written.some((w) => w.startsWith("CLAUDE.md"))) {
       console.log("\nnext: fill in purpose and commands in CLAUDE.md; optional: `npx impeccable install` (for /ui) and `/graphify .`");
     }

package/docs/adr/README.md

@@ -12,12 +12,14 @@ One file per architecture decision: `docs/adr/NNNN-<slug>.md`.
 
 `/architect` returns an ADR proposal, the orchestrator copies it into `docs/plans/<task>.md`, and at DoD creates the ADR file in the same diff as the change.
 
+Skill `domain-modeling` decides whether a decision earns an ADR (hard to reverse, surprising without context, the result of a real trade-off); this file decides how it looks and lives, and wins over the skill's `ADR-FORMAT.md`. In a multi-context repo (`GLOSSARY-MAP.md` at the root), context decisions live in `<context>/docs/adr/` with their own numbering and system-wide ones here.
+
 ## Template
 
 ```markdown
 # NNNN - <title>
 
-Status: Proposed | Accepted | Superseded by NNNN | Deprecated
+Status: Proposed | Accepted | Partly superseded by NNNN (<which part>) | Superseded by NNNN | Deprecated
 Date: YYYY-MM-DD
 
 ## Context

package/docs/plans/README.md

@@ -7,9 +7,11 @@ The newest plan is re-injected after context compaction by the post-compact hook
 Rules of the file:
 
 - Paths appear only under Scope. Decisions name modules, interfaces and contracts, never files or code.
-- Test seams are the contract between `/product`, the implementers (`tdd`) and `/verifier`: a seam not listed here is not tested, a seam listed here must be.
+- Test seams are the contract between `/product`, the implementers (`tdd`) and `/verifier`: a seam not listed here is not tested, a seam listed here must be. One row per level (e2e, entry, service, repository, unit) and public interface; each row says which criteria it proves, what it catches and what it leaves to another level. The user confirms the table at the ticket gate (`Confirmed:` line), which makes the rows the pre-agreed seams `tdd` asks for: implementers never ask, and never add a row.
+- Terms holds the domain words this plan introduces or uses differently from `GLOSSARY.md`. The user confirms them at the ticket gate and the orchestrator moves them into `GLOSSARY.md` (skill `domain-modeling`).
 - Tickets are vertical slices with `Blocked by` edges; the orchestrator works the frontier (tickets whose blockers are done) and marks Status as they land.
 - Session state is the compaction insurance: everything the orchestrator would lose with its window goes there first (skill `orchestrate` section 14).
+- Grill record is the grill on paper: the orchestrator appends to it after every round, while the conversation is still in its window, and `/product` plans from it. Nobody rewrites it later; corrections are appended. It is the last section because the post-compact hook re-injects only the first 120 lines, which must keep carrying Session state and the tickets; for the same reason Test seams, which grows with the levels, comes after Tickets.
 - A section that does not apply says `n/a` and why, so a reader knows it was considered.
 
 ## Template
@@ -48,20 +50,27 @@ Size: S | M | L
 ## Decisions
 - <decision> - <why> (modules, interfaces, schema, contracts; architect verdict and constraints)
 
-## Test seams
-| Seam | Catches | Misses | Prior art |
-|------|---------|--------|-----------|
-| S1: <public interface> | <behavior it proves> | <what it cannot see> | <existing test, or none> |
-
 ## Tickets
 <one ticket = one tracer bullet = one brief = one agent = one context window>
 | # | Ticket | Delivers | Blocked by | Agent | Paths | Seams | Status |
 |---|--------|----------|------------|-------|-------|-------|--------|
 | 1 | <title> | <end-to-end behavior, from the user's perspective> | - | /api | <globs> | S1 | todo |
 
+## Test seams
+<one row per level and public interface; default levels per size in agent `product` (step 6); levels per stack in the `arch-*` testing references>
+Confirmed: <YYYY-MM-DD at the ticket gate | pending>
+| # | Level | Seam (public interface) | ACs | Catches | Leaves to | Prior art |
+|---|-------|-------------------------|-----|---------|-----------|-----------|
+| S1 | e2e | <flow: create -> approve -> list> | AC1, AC2 | <the flow end to end, happy path and the failures that hurt most> | <rule detail: S3, S5> | <existing test, or none> |
+| S2 | entry | <POST /invoices> | AC1 | <contract, validation, authorization, error codes> | <business rule: S3> | <...> |
+| S3 | service | <CreateInvoice use case> | AC3 | <business rules and decisions, ports faked> | <SQL: S4> | <...> |
+| S4 | repository | <invoices repository adapter> | AC4 | <SQL, mapping, constraints, pagination, real database> | <-> | <...> |
+| S5 | unit | <invoice rules> | AC3 | <every edge case of the pure rule> | <-> | <...> |
+
 ## Definition of Done
 - [ ] lint, build, tests green (evidence pasted)
-- [ ] a test exists at every seam listed above
+- [ ] a test exists at every seam listed above, at its level
+- [ ] the slow suites (integration, e2e) ran in `/verifier`; the Stop hook runs only the fast one
 - [ ] diff only inside scoped paths
 - [ ] docs updated if route/job/store/integration/fallback changed
 - [ ] no secrets in diff
@@ -70,4 +79,26 @@ Size: S | M | L
 
 ## Open questions
 - ...
+
+## Terms
+<domain words this plan introduces or uses differently from GLOSSARY.md, confirmed by the user at the ticket gate and then written to GLOSSARY.md; n/a when the plan uses only glossary terms>
+- **<Term>**: <one or two sentences: what it is> _Avoid_: <synonyms> - new | conflicts with GLOSSARY.md (<entry>) | confirmed
+
+## Grill record
+<appended by the orchestrator after every grill round; never rewritten, corrections appended; n/a when no grill ran (S, or M with no open decision)>
+- Q<n> <question title>: <decision> - why: <reason, in the user's words when they add nuance>
+  - Rejected: <alternative> - <why not>
+  - Constraint: <anything said in passing that binds the work>
 ```
+
+## Wayfinder efforts
+
+Work too big and too foggy for one plan (the destination is clear, the way is not) is charted by skill `wayfinder` in its own folder, one level down so the post-compact hook never mistakes it for a task plan:
+
+```
+docs/plans/<effort>/
+  map.md                     Status, Destination, Notes, Decisions so far, Not yet specified, Out of scope
+  decisions/NN-<slug>.md     one question per file: Type, Status, Blocked by, ## Question, ## Answer
+```
+
+The map is an index: a decision lives in its ticket, and the map only gists it and links. When the map is done, the build starts as an L task with its own `docs/plans/<task>.md`, and `/product` reads the map as the source of the decisions already made.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evertonferreira96/agents",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Personal agents, rules, hooks and skills for Claude Code (portable to Cursor and Codex through AGENTS.md), installable into any project.",
   "type": "module",
   "bin": {

package/scripts/bootstrap.mjs

@@ -7,6 +7,8 @@
 //   node scripts/bootstrap.mjs <target> --force    update --force: also overwrite files edited in the project
 //   node scripts/bootstrap.mjs --sync              inside a project bootstrapped from a local clone: pull it, then update
 // Protected (never written over): CLAUDE.md, .claude/settings.local.json, .claude/agent-memory/**
+// Project-owned (never shipped, written over or deleted, even with --force): GLOSSARY.md and GLOSSARY-MAP.md, docs/plans/** and docs/adr/**
+// except their README.md templates, .claude/agent-memory/**, .claude/handoffs/**. check-catalog.mjs fails if SYNC would ship one.
 // .claude/config-manifest.json records the hash of every file the config installed. `update` uses it to tell a file that is
 // only outdated (overwritten) from one edited in the project (kept unless --force), and deletes files that left the config
 // only when the project copy is untouched.
@@ -20,11 +22,20 @@ export const SYNC = [".claude/agents", ".claude/hooks", ".claude/rules", ".claud
   "docs/plans/README.md", "docs/adr/README.md", "docs/brief-template.md", "scripts/skills-update.mjs", "scripts/check-catalog.mjs", "scripts/bootstrap.mjs", "skills-lock.json"];
 export const SKIP = /(^|\/)(scripts\/bin|__pycache__|node_modules|\.context-band)(\/|$)|\.pyc$/;
 export const PROTECTED = /^(CLAUDE\.md|\.claude\/settings\.local\.json|\.claude\/agent-memory\/.*)$/;
+// What the project's work produces: plans, wayfinder maps, ADRs, glossaries, agent memory, handoffs. The config only ships the two READMEs.
+export const PROJECT_OWNED = /^((?!\.claude\/)(.+\/)?GLOSSARY\.md|GLOSSARY-MAP\.md|docs\/plans\/(?!README\.md$).+|((?!\.claude\/).+\/)?docs\/adr\/(?!README\.md$).+|\.claude\/agent-memory\/.+|\.claude\/handoffs\/.+)$/;
+const isProtected = (rel) => PROTECTED.test(rel) || PROJECT_OWNED.test(rel);
 export const GITIGNORE = [".claude/worktrees/", ".claude/handoffs/", ".claude/.context-band", ".claude/.stop-verify-ran", ".claude/settings.local.json",
   ".claude/agent-memory-local/", "graphify-out/", ".claude/skills/impeccable/scripts/bin/", "__pycache__/", "*.pyc"];
 export const MANIFEST = ".claude/config-manifest.json";
 export const SOURCE_FILE = ".claude/config-source.json";
 export const DEFAULT_SRC = fileURLToPath(new URL("..", import.meta.url));
+// AGENTS.md of a project that already had its own: the config version can live inside it as a managed block,
+// which `update` refreshes in place without touching the rest of the file.
+export const AGENTS_FILE = "AGENTS.md";
+export const BLOCK_START = "<!-- agents-config:start -->";
+export const BLOCK_END = "<!-- agents-config:end -->";
+export const AGENTS_MD_CHOICES = ["keep", "overwrite", "append", "print"];
 
 const sha = (p) => createHash("sha256").update(readFileSync(p)).digest("hex");
 const readJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
@@ -39,14 +50,15 @@ export function readPackage(src = DEFAULT_SRC) {
 }
 
 // Every file the config installs, keyed by its path relative to the config root (forward slashes).
-export function configFiles(src = DEFAULT_SRC) {
+// Project-owned paths are never installed; `includeProjectOwned` lists them anyway, for check-catalog.mjs.
+export function configFiles(src = DEFAULT_SRC, { includeProjectOwned = false } = {}) {
   const files = new Map();
   for (const entry of SYNC) {
     const abs = join(src, entry);
     if (!existsSync(abs)) continue;
     for (const f of walk(abs)) {
       const rel = relative(src, f).split(sep).join("/");
-      if (!SKIP.test(rel)) files.set(rel, f);
+      if (!SKIP.test(rel) && (includeProjectOwned || !PROJECT_OWNED.test(rel))) files.set(rel, f);
     }
   }
   return files;
@@ -61,6 +73,82 @@ function removeEmptyParents(target, rel) {
   }
 }
 
+// The config's AGENTS.md wrapped in the managed-block markers (LF line endings, trailing newline).
+export function agentsBlock(src = DEFAULT_SRC) {
+  const body = readFileSync(join(src, AGENTS_FILE), "utf8").replace(/\r\n/g, "\n").trimEnd();
+  const note = `<!-- Managed by ${readPackage(src).name}: \`chew agents setup:pull\` refreshes this block. Edit outside the markers. -->`;
+  return `${BLOCK_START}\n${note}\n${body}\n${BLOCK_END}\n`;
+}
+
+// Position of the managed block in `text` (normalized to LF), or null when the file has none.
+function findBlock(text) {
+  const t = text.replace(/\r\n/g, "\n");
+  const start = t.indexOf(BLOCK_START);
+  const end = start < 0 ? -1 : t.indexOf(BLOCK_END, start + BLOCK_START.length);
+  return end < 0 ? null : { text: t, start, end: end + BLOCK_END.length, eol: text.includes("\r\n") ? "\r\n" : "\n" };
+}
+
+function recordHash(target, rel, hash) {
+  const p = join(target, MANIFEST);
+  const m = readJson(p);
+  if (!m?.files) return;
+  m.files[rel] = hash;
+  writeFileSync(p, JSON.stringify(m, null, 2) + "\n");
+}
+
+// What to do with a project AGENTS.md that differs from the config and has no managed block:
+//   keep (nothing), overwrite (config version, refreshed by later updates), append (managed block at the end, refreshed by
+//   later updates), print (returns the managed block for the user to paste). The manifest records the config hash, so a
+//   file with a block never counts as untouched and is never overwritten whole.
+export function applyAgentsMd({ src = DEFAULT_SRC, target, choice, dryRun = false }) {
+  if (!AGENTS_MD_CHOICES.includes(choice)) throw new Error(`unknown AGENTS.md choice: ${choice} (${AGENTS_MD_CHOICES.join(", ")})`);
+  const abs = join(src, AGENTS_FILE);
+  const dst = join(target, AGENTS_FILE);
+  if (choice === "print") return { choice, text: agentsBlock(src) };
+  if (choice === "keep" || dryRun) return { choice };
+  if (choice === "overwrite") copyFileSync(abs, dst);
+  if (choice === "append") {
+    const cur = existsSync(dst) ? readFileSync(dst, "utf8") : "";
+    const eol = cur.includes("\r\n") ? "\r\n" : "\n";
+    const block = agentsBlock(src).replace(/\n/g, eol);
+    const found = findBlock(cur);
+    if (found) writeFileSync(dst, (found.text.slice(0, found.start) + agentsBlock(src).trimEnd() + found.text.slice(found.end)).replace(/\n/g, eol));
+    else writeFileSync(dst, cur + (cur === "" || cur.endsWith(eol + eol) ? "" : cur.endsWith(eol) ? eol : eol + eol) + block);
+  }
+  recordHash(target, AGENTS_FILE, sha(abs));
+  return { choice };
+}
+
+// Ask once in a terminal (default keep).
+export async function askAgentsMd({ input = process.stdin, output = process.stdout } = {}) {
+  const { createInterface } = await import("node:readline/promises");
+  output.write(`\nAGENTS.md already exists in this project and differs from the config. What should happen to it?
+  [k] keep yours as it is (default)
+  [o] overwrite it with the config version
+  [a] append the config version at the end, in a managed block that later pulls keep current
+  [p] print the config version here, to concatenate it yourself\n`);
+  const rl = createInterface({ input, output });
+  try {
+    const answer = (await rl.question("Choice [k/o/a/p]: ")).trim().toLowerCase();
+    return { o: "overwrite", a: "append", p: "print" }[answer[0]] ?? "keep";
+  } finally {
+    rl.close();
+  }
+}
+
+// After init/update: settle an AGENTS.md conflict with `choice`, or ask when interactive, or keep and say how to choose.
+export async function settleAgentsMd({ src = DEFAULT_SRC, target, r, choice, dryRun = false, interactive = false, log = console.log }) {
+  if (!r.agentsMdConflict) return null;
+  const picked = choice || (interactive ? await askAgentsMd() : "keep");
+  const out = applyAgentsMd({ src, target, choice: picked, dryRun });
+  const dry = dryRun ? " (dry run: nothing written)" : "";
+  if (picked === "keep") log(`\nAGENTS.md: kept yours. To change that: --agents-md=overwrite, --agents-md=append or --agents-md=print`);
+  if (picked === "overwrite") log(`\nAGENTS.md: overwritten with the config version${dry}`);
+  if (picked === "append") log(`\nAGENTS.md: config version appended at the end in a managed block${dry}; later pulls refresh only that block`);
+  if (picked === "print") log(`\nAGENTS.md: the config version is below. Paste it into yours with the markers, so later pulls refresh it:\n\n${out.text}`);
+  return picked;
+}
+
 // mode: "init" (copy what is missing), "update" (also refresh untouched files and drop obsolete ones), "check" (report only).
 export function install({ src = DEFAULT_SRC, target, mode = "init", force = false, dryRun = false }) {
   if (!["init", "update", "check"].includes(mode)) throw new Error(`unknown mode: ${mode}`);
@@ -86,24 +174,40 @@ export function install({ src = DEFAULT_SRC, target, mode = "init", force = fals
     }
     const have = sha(dst);
     if (have === want) { r.same++; next[rel] = want; continue; }
+    if (rel === AGENTS_FILE) {
+      const cur = readFileSync(dst, "utf8");
+      const found = findBlock(cur);
+      if (found) { // the project's own AGENTS.md carrying the config in a managed block: only the block is ours
+        next[rel] = want; // never the project file's hash, so no engine treats the file as untouched and replaces it whole
+        const block = agentsBlock(src).trimEnd();
+        if (found.text.slice(found.start, found.end) === block) { r.same++; continue; }
+        if (mode === "check") { r.outdated.push(`${rel} (managed block)`); continue; }
+        if (mode === "init") { r.kept.push(`${rel} (managed block outdated; run update)`); continue; }
+        if (write) writeFileSync(dst, (found.text.slice(0, found.start) + block + found.text.slice(found.end)).replace(/\n/g, found.eol));
+        r.updated.push(`${rel} (managed block)`);
+        continue;
+      }
+    }
     const untouched = installed?.[rel] === have;
     if (mode === "check") { (untouched ? r.outdated : r.edited).push(rel); continue; }
-    if (mode === "update" && (untouched || force) && !PROTECTED.test(rel)) {
+    if (mode === "update" && (untouched || force) && !isProtected(rel)) {
       if (write) copyFileSync(abs, dst);
       r.updated.push(rel); next[rel] = want;
       continue;
     }
     r.kept.push(rel);
+    if (rel === AGENTS_FILE) r.agentsMdConflict = true; // the CLI offers keep / overwrite / append / print
     if (installed?.[rel]) next[rel] = installed[rel];
   }
 
   for (const [rel, hash] of Object.entries(installed ?? {})) {
     if (files.has(rel)) continue;
+    if (PROJECT_OWNED.test(rel)) continue; // an older config shipped it: it is the project's now, so stop tracking it, never delete it
     const dst = join(target, rel);
     if (!existsSync(dst)) continue;
     const untouched = sha(dst) === hash;
     if (mode === "check") { r.obsolete.push(rel); continue; }
-    if (mode === "update" && untouched && !PROTECTED.test(rel)) {
+    if (mode === "update" && untouched && !isProtected(rel)) {
       if (write) { rmSync(dst); removeEmptyParents(target, rel); }
       r.removed.push(rel);
       continue;
@@ -155,9 +259,10 @@ export function report(r, log = console.log) {
   list("kept", r.kept, r.mode === "init" ? "  (differs; init never overwrites)" : "  (edited here)");
   list("kept", r.obsoleteKept, "  (left the config, but edited here)");
   if (r.written.length) { log("written:"); for (const w of r.written) log(`  ${w}`); }
-  if (r.mode === "update" && !r.hadManifest && r.kept.length) log("no manifest from a previous install, so differing files count as edited; review them and run `update --force` once to adopt the config versions");
-  else if (r.kept.length && r.mode === "update") log("`update --force` overwrites the files kept above (protected files excepted)");
-  else if (r.kept.length) log("run `update` to refresh differing files");
+  const others = r.kept.filter((k) => !(r.agentsMdConflict && k === AGENTS_FILE)); // AGENTS.md gets its own choice (settleAgentsMd)
+  if (r.mode === "update" && !r.hadManifest && others.length) log("no manifest from a previous install, so differing files count as edited; review them and run `update --force` once to adopt the config versions");
+  else if (others.length && r.mode === "update") log("`update --force` overwrites the files kept above (protected files excepted)");
+  else if (others.length) log("run `update` to refresh differing files");
 }
 
 // Legacy CLI (scripts/bootstrap.mjs <target> [--check|--force] | --sync).

package/scripts/check-catalog.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
-// Drift checks: skills on disk vs docs/skills.md vs frontmatter vs skills-lock.json vs agents' skills: vs settings hooks.
+// Drift checks: skills on disk vs docs/skills.md vs frontmatter vs skills-lock.json vs agents' skills: vs settings hooks,
+// and no project-owned path (plans, ADRs, glossary, agent memory, handoffs) among the files the config ships.
 // Exit 1 on any error. Warnings do not fail.
 import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { configFiles, PROJECT_OWNED } from "./bootstrap.mjs";
 const errors = [], warnings = [];
 const read = (p) => readFileSync(p, "utf8");
 const fm = (p) => read(p).split("---")[1] ?? "";
@@ -37,6 +39,7 @@ for (const list of Object.values(settings.hooks ?? {})) for (const e of list) fo
   const m = /\$CLAUDE_PROJECT_DIR\/(\.claude\/hooks\/[^" ]+)/.exec(h.command ?? "");
   if (m && !existsSync(m[1])) errors.push(`settings.json: hook file ${m[1]} does not exist`);
 }
+for (const rel of configFiles(undefined, { includeProjectOwned: true }).keys()) if (PROJECT_OWNED.test(rel)) errors.push(`${rel}: project-owned path shipped by the config (scripts/bootstrap.mjs SYNC)`);
 for (const w of warnings) console.log(`warn  ${w}`);
 for (const e of errors) console.log(`ERROR ${e}`);
 console.log(`${skills.length} skills, ${rows.size} catalog rows, ${Object.keys(lock).length} lock entries: ${errors.length} error(s), ${warnings.length} warning(s)`);

package/skills-lock.json

@@ -69,6 +69,13 @@
       "skillPath": "skills/engineering/diagnosing-bugs/SKILL.md",
       "sha256": "849198df88cdb65fd0d97236604c1fca7ff2f22d2f705f9724a800d0266b118d"
     },
+    "domain-modeling": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/engineering/domain-modeling/SKILL.md",
+      "sha256": "7b925d7b1e341a2eeae33ad68a8a8c0ab889a38ddd22a7598e4c240e5a7556a3"
+    },
     "emil-design-eng": {
       "source": "emilkowalski/skills",
       "sourceType": "github",
@@ -107,10 +114,9 @@
       "sourceType": "github",
       "sourceCommit": "49dd158",
       "skillPath": "skills/engineering/grill-with-docs/SKILL.md",
-      "note": "adapted: upstream calls grilling + domain-modeling; local version inlines glossary/ADR rules and adds docs/plans read-first, graphify and the decisions block for the orchestrator",
+      "note": "adapted: calls grilling + domain-modeling like upstream; adds docs/plans read-first, graphify, the Grill record, the ADR template and lifecycle of docs/adr/README.md (which wins over domain-modeling's ADR-FORMAT.md) and the decisions block for the orchestrator",
       "adapted": true,
-      "sha256": "4a6d8bb82e01431ecee9a13b06ccfc4b911f6ee2efcf09bc6686a8e4cee58f72",
-      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`"
+      "sha256": "7de372c13488f1ee96cc11cd8907b56b6809cc93eef776eeddd37de6b6cbe3fe"
     },
     "grilling": {
       "source": "mattpocock/skills",
@@ -253,6 +259,15 @@
       "adapted": true,
       "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
     },
+    "wayfinder": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/engineering/wayfinder/SKILL.md",
+      "sha256": "9be7b478c389605a24517d27752f278933588da97a1b5921b165f455edf4c5b7",
+      "adapted": true,
+      "adaptedNote": "no issue tracker: the map is docs/plans/<effort>/map.md (with a Status line for the post-compact hook) and tickets are docs/plans/<effort>/decisions/NN-<slug>.md with Type, Status and Blocked by lines (upstream's local-markdown layout, moved under docs/plans); research tickets run as a read-only subagent with a brief instead of skill research (not vendored); prototype tickets go to /ui (skill prototype, emilkowalski) or the owning implementer in a spike worktree, never merged or pushed, since this repo's prototype is a different skill; sessions end with /clear; adds the hand-off to an L task in orchestrate when the way is clear (ADR 0012)"
+    },
     "writing-for-agents": {
       "source": "mattpocock/skills",
       "sourceType": "github",