@evertonferreira96/agents 0.1.2 → 0.1.3

package/README.md

@@ -21,6 +21,7 @@
   - [The big picture](#the-big-picture)
   - [What `setup:pull` does, step by step](#what-setuppull-does-step-by-step)
   - [How each file is decided](#how-each-file-is-decided)
+  - [Projects that already have an AGENTS.md](#projects-that-already-have-an-agentsmd)
   - [What lands in your project](#what-lands-in-your-project)
 - [Working in a configured project](#working-in-a-configured-project)
 - [Command reference](#command-reference)
@@ -188,6 +189,60 @@ flowchart TD
 | Configured project, nothing edited | New files added, changed files updated, removed files deleted |
 | You edited a shipped file | Kept and listed; `--force` replaces it with the config version |
 | Project configured before the manifest existed | Differing files count as edited; review them, then run `--force` once |
+| The project has its own `AGENTS.md` | You choose: keep, overwrite, append or print ([next section](#projects-that-already-have-an-agentsmd)) |
+
+### Projects that already have an AGENTS.md
+
+Many projects already carry an `AGENTS.md` with their own rules. When the project copy differs from the config, `setup:pull` asks what to do. Press Enter to keep yours; outside a terminal (CI, scripts) it keeps yours and lists the options.
+
+```text
+AGENTS.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
+Choice [k/o/a/p]:
+```
+
+```mermaid
+flowchart TD
+    A["Project AGENTS.md differs<br/>from the config"] --> B{"Has a managed block?"}
+    B -- yes --> RB["Refresh only the block<br/>no question asked"]
+    B -- no --> Q{"Your choice<br/>prompt or --agents-md"}
+    Q -- keep --> K["Yours stays as it is"]
+    Q -- overwrite --> O["Replaced by the config version<br/>later pulls keep it current"]
+    Q -- append --> AP["Config version added at the end<br/>inside the managed block"]
+    Q -- print --> P["Config version printed<br/>you paste it where you want"]
+    AP -. "next pull" .-> RB
+    P -. "pasted with the markers" .-> RB
+
+    classDef keep fill:#f3f4f6,stroke:#9ca3af,color:#374151
+    classDef upd fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
+    classDef add fill:#dcfce7,stroke:#16a34a,color:#14532d
+    classDef out fill:#fef3c7,stroke:#d97706,color:#78350f
+    class K keep
+    class O,RB upd
+    class AP add
+    class P out
+```
+
+The managed block is plain Markdown between two comments. Everything outside the markers is yours; later pulls replace only what is inside them:
+
+```markdown
+# My project
+Rules that belong to this project.
+
+<!-- agents-config:start -->
+<!-- Managed by @evertonferreira96/agents: `chew agents setup:pull` refreshes this block. Edit outside the markers. -->
+...the config AGENTS.md...
+<!-- agents-config:end -->
+```
+
+| Want | Command |
+|---|---|
+| Decide without the question | `chew agents setup:pull --agents-md=keep` (or `overwrite`, `append`, `print`) |
+| Just see the config version | `chew agents setup:print` (in the managed block) or `chew agents setup:print --raw` (file alone) |
+| Concatenate from the shell | `chew agents setup:print >> AGENTS.md` (bash, zsh, cmd; in Windows PowerShell 5, `>>` writes UTF-16, so use `--agents-md=append`) |
 
 ### What lands in your project
 
@@ -291,6 +346,7 @@ The full flow, with every section of the playbook, is in [`.claude/skills/orches
 |---|---|
 | `chew agents setup:pull [dir]` | Download the latest version and install or refresh it in `dir` (default: current folder) |
 | `chew agents setup:check [dir]` | Compare the project with the latest version; exit code 1 on drift |
+| `chew agents setup:print` | Print the latest config `AGENTS.md` in its managed block, to concatenate into yours (`--raw`: the file alone) |
 | `chew --version` | Version of the installed `chew` |
 
 | Flag | Effect |
@@ -298,6 +354,7 @@ The full flow, with every section of the playbook, is in [`.claude/skills/orches
 | `--force` | Also overwrite files edited in the project (protected files excepted) |
 | `--dry-run` | Show what would change, write nothing |
 | `--local` | Use the version installed with `chew` instead of downloading |
+| `--agents-md=<choice>` | When the project has its own `AGENTS.md`: `keep` (default), `overwrite`, `append` or `print`; skips the question |
 
 ### `agents` (same package, via `npx` or global)
 
@@ -306,6 +363,9 @@ The full flow, with every section of the playbook, is in [`.claude/skills/orches
 | `agents init [dir]` | Copy what is missing; never overwrites |
 | `agents update [dir]` | Same rules as `setup:pull`, using this installed version |
 | `agents check [dir]` | Report missing, outdated, edited and obsolete files; exit 1 on drift |
+| `agents print-agents-md` | Same as `chew agents setup:print`, for this installed version |
+
+`init` and `update` accept `--force`, `--dry-run` and `--agents-md=<choice>`, like `chew`.
 
 ### Legacy, from a local clone
 
@@ -409,6 +469,13 @@ By design: files edited in the project are kept and listed as `edited`. `chew ag
 
 </details>
 
+<details>
+<summary><b>My project's AGENTS.md was not touched</b></summary>
+
+Keeping it is the default when no choice is given, including every run outside a terminal. Run `chew agents setup:pull --agents-md=append` to add the config in a managed block below your content, or `--agents-md=overwrite` to replace it. See [Projects that already have an AGENTS.md](#projects-that-already-have-an-agentsmd).
+
+</details>
+
 <details>
 <summary><b>"no manifest from a previous install"</b></summary>
 

package/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.3

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evertonferreira96/agents",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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

@@ -25,6 +25,12 @@ export const GITIGNORE = [".claude/worktrees/", ".claude/handoffs/", ".claude/.c
 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; } };
@@ -61,6 +67,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,6 +168,20 @@ 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)) {
@@ -94,6 +190,7 @@ export function install({ src = DEFAULT_SRC, target, mode = "init", force = fals
       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];
   }
 
@@ -155,9 +252,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).