From 61aa2db16b415ad7d7ed850ecfab7de4c4bfe281 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 23 Sep 2026 20:48:06 +0000
Subject: [PATCH 1/3] fix(sync): own only a marked block in AGENTS.md; init
 emits only used tools

forge init/sync replaced a hand-written AGENTS.md (the original went to
AGENTS.md.forge-bak, which no agent reads), and the Stop-hook auto-sync
then reverted any human edit to the now fully managed file.

Forge now owns only the text between <!-- forge:begin --> and
<!-- forge:end -->:
- sync appends the block to a hand-written file and afterwards compares
  and rewrites only the block (agentsMdStatus is the one classifier for
  sync, auto-sync and doctor; hasManagedBlock replaces isManaged here)
- auto-sync refreshes only the block, never adopts a file without one,
  and no longer runs the full per-tool emit
- a legacy fully generated AGENTS.md converts losslessly: the header hash
  identifies forge's bytes, so text added around them is kept; one edited
  inside the generated text is converted only by an explicit sync, after
  a timestamped AGENTS.md.forge-bak-<time> backup
- damaged markers are reported and left alone
- a generated CLAUDE.md keeps notes added under its header (marker line
  refreshed in place)
- doctor reports "hand-written AGENTS.md (no Forge block)" and its fix
  appends the block

forge init now emits config only for Claude plus the tools the repo
already shows (.cursor/, .codex/, .github/copilot-instructions.md, ...)
or an explicit --tools <list|all>, and records the set in
.forge/forge.config.json so sync, doctor --fix and integrations add emit
the same set. A repo with no recorded set still gets every tool.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UUhB8JaPayd43w37dxiXrW
Signed-off-by: Claude <noreply@anthropic.com>
---
 ARCHITECTURE.md           |  12 +-
 CHANGELOG.md              |  24 ++++
 ONBOARDING.md             |  18 ++-
 README.md                 |  13 +-
 docs/GUIDE.md             |  18 ++-
 mintlify/cli/config.mdx   |   6 +-
 mintlify/cli/core.mdx     |  25 +++-
 src/cli.js                |  36 ++++-
 src/commands.js           |  16 ++-
 src/cortex_hook_main.js   |   5 +-
 src/doctor.js             |  59 +++++----
 src/emit/_shared.js       |  82 ++++++++++++
 src/emit/claude.js        |   9 ++
 src/emit/mcp.js           |  46 ++++---
 src/init.js               |  85 ++++++++++--
 src/integrations.js       |  10 +-
 src/repo_config.js        |  69 ++++++++--
 src/sync.js               | 224 +++++++++++++++++++++++++++-----
 test/agents_block.test.js | 267 ++++++++++++++++++++++++++++++++++++++
 test/init.test.js         |  10 +-
 test/init_tools.test.js   | 225 ++++++++++++++++++++++++++++++++
 test/regressions.test.js  |  25 ++--
 test/sync.test.js         |  11 +-
 23 files changed, 1154 insertions(+), 141 deletions(-)
 create mode 100644 test/agents_block.test.js
 create mode 100644 test/init_tools.test.js

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index fa568c34..3fc0e477 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -516,7 +516,17 @@ an **MCP server** for Roo Code and VS Code.
 | **OpenClaw**       | execution-folder `AGENTS.md` as project context; MCP registry is global | Rely on root `AGENTS.md`; write an OpenClaw-shaped `.openclaw/mcp.json` the operator applies with one `openclaw mcp add` |
 
 Roo Code and VS Code receive the Forge MCP server via `forge init`
-(`.roo/mcp.json`, `.vscode/mcp.json`) rather than a rules file.
+(`.roo/mcp.json`, `.vscode/mcp.json`) rather than a rules file — like every per-tool file,
+only for tools the repo uses (detected, or `forge init --tools`); the set is recorded in
+`.forge/forge.config.json` so `forge sync` emits the same targets.
+
+`AGENTS.md` is shared with people, so forge owns only a marked block in it
+(`<!-- forge:begin -->` … `<!-- forge:end -->`). Sync appends that block to a hand-written
+file and afterwards compares and rewrites only the block; the Stop-hook auto-sync does the
+same and never adopts a file without one. A pre-block, fully generated `AGENTS.md` is
+recognised by the hash in its header and converted to a block keeping any text a person
+added around it; only one edited inside its generated text needs a full rewrite, which
+`forge sync` does after saving a timestamped `AGENTS.md.forge-bak-<time>`.
 
 ### OpenClaw: what is automatic and what is not
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc97f4ec..070e32b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,30 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Fixed
+
+- **`forge init` / `forge sync` no longer replace a hand-written `AGENTS.md`, and the Stop-hook
+  auto-sync no longer reverts human edits.** Forge now owns only a marked block
+  (`<!-- forge:begin -->` … `<!-- forge:end -->`): sync appends it to an existing file and
+  afterwards compares and rewrites only that block; auto-sync does the same and never adopts
+  a file without one. An `AGENTS.md` generated whole by an older version converts to a block
+  on the next sync, keeping any text added above or below the generated part (verified by
+  the hash in its header). If the generated text itself was edited, `forge sync` saves the
+  old file as a timestamped `AGENTS.md.forge-bak-<time>` first, instead of overwriting one
+  fixed `.forge-bak`. `forge doctor` reports a hand-written file as "no Forge block" and its
+  fix appends the block.
+- **Notes added under a generated `CLAUDE.md` header survive later syncs.** Sync refreshes
+  only the marker line instead of regenerating the file.
+
+### Changed
+
+- **`forge init` emits config only for the tools a repo uses:** Claude Code plus every tool
+  with a sign on disk (`.cursor/`, `.codex/`, `.github/copilot-instructions.md`, …), or an
+  explicit `--tools <list|all>`. The choice is recorded in `.forge/forge.config.json`
+  (`tools`) and later syncs and `forge integrations add` honour it; a repo with no recorded
+  set still gets every tool. `forge tools --reset` now clears only the primary tool and keeps
+  that set.
+
 ## [1.3.0] - 2026-09-23
 
 ### Added
diff --git a/ONBOARDING.md b/ONBOARDING.md
index 384d378d..cac96479 100644
--- a/ONBOARDING.md
+++ b/ONBOARDING.md
@@ -44,16 +44,22 @@ Full matrix (no-registry `github:` install, symlink dev setup) →
 ## 2. Configure a repo (once per repo)
 
 One config for every tool. Author your rules once; `forge init` emits each tool's
-native file.
+native file — for the tools this repo uses.
 
 ```bash
 cd ~/your-project
-forge init                 # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml …
+forge init                 # AGENTS.md + CLAUDE.md + .mcp.json, plus each tool it detects
+forge init --tools all     # or pick: --tools claude,cursor,gemini (recorded for later syncs)
 ```
 
-Now Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, Continue, and
-OpenClaw all read the **same** rules — each from its own native file (plus MCP server
-config for Roo Code and VS Code).
+With `--tools all`, Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed,
+Continue, and OpenClaw all read the **same** rules — each from its own native file (plus
+MCP server config for Roo Code and VS Code). Without it, init emits Claude Code's files and
+those of any tool the repo already shows (`.cursor/`, `.codex/`,
+`.github/copilot-instructions.md`, …); AGENTS.md-reading tools get the rules regardless.
+
+Already have an `AGENTS.md`? It is kept: Forge appends its rules between
+`<!-- forge:begin -->` and `<!-- forge:end -->` and only ever rewrites that block.
 
 On OpenClaw the rules arrive automatically (it reads the execution folder's `AGENTS.md`
 as project context), but the MCP server is a deliberate one-command step, because
@@ -72,7 +78,7 @@ Change a rule later by editing `source/rules.json` (or dropping a per-repo
 `.forge/rules.json`), then:
 
 ```bash
-forge sync                 # recompiles into every tool; idempotent (only rewrites what changed)
+forge sync                 # recompiles into each selected tool; idempotent (only rewrites what changed)
 ```
 
 ## 3. Use the cognitive substrate
diff --git a/README.md b/README.md
index 5c2095f3..0f7ee0af 100644
--- a/README.md
+++ b/README.md
@@ -95,7 +95,7 @@ without corresponding public evidence.
 
 ```bash
 npm install -g @codewithjuber/forgekit   # or: npm install -g github:CodeWithJuber/forgekit
-forge init                               # emit native configuration from one source
+forge init                               # emit native config for the tools this repo uses
 forge doctor                             # verify providers, hooks, and MCP wiring
 ```
 
@@ -385,6 +385,15 @@ forge doctor --fix
 Forgekit-managed entries. The implementation preserves unrelated entries and creates a
 timestamped backup before changing the file.
 
+`forge init` emits configuration only for the agent tools the repository already uses:
+Claude Code plus any tool with a sign on disk (`.cursor/`, `.codex/`,
+`.github/copilot-instructions.md`, and so on). Choose explicitly with
+`forge init --tools claude,cursor` or `--tools all`; the choice is recorded in
+`.forge/forge.config.json`, so later `forge sync` runs emit the same set. In `AGENTS.md`,
+Forgekit owns only the block between `<!-- forge:begin -->` and `<!-- forge:end -->`. A
+hand-written `AGENTS.md` keeps every line and gets the block appended; `forge sync` and the
+Stop-hook auto-sync rewrite that block and nothing else.
+
 For an explicit model provider, inspect or update configuration with `forge config`. API keys
 remain environment variables; Forgekit's provider file stores the environment-variable name,
 not the secret value.
@@ -397,7 +406,7 @@ and output live in [`docs/GUIDE.md`](docs/GUIDE.md).
 <!-- forge:render:commands-table:begin (generated by `forge docs render` — do not edit) -->
 | Group                   | Command              | Does                                                                                                                                                                                                                        |
 | ----------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Core**                | `forge init`         | scaffold this repo's config — emits every tool from one shared source                                                                                                                                                       |
+| **Core**                | `forge init`         | scaffold this repo's config — emits the tools it uses (Claude + detected, or --tools) from one shared source                                                                                                                |
 |                         | `forge sync`         | recompile the canonical source into each tool's native config files                                                                                                                                                         |
 |                         | `forge doctor`       | health-check installed tools, guards, MCP auth, and config drift                                                                                                                                                            |
 |                         | `forge tools`        | primary-tool config — gitignore secondary-tool artifacts (.cursor/.gemini/…) for tools this repo doesn't use (`forge tools <name>` sets it, `--reset` clears)                                                               |
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
index b6d6aa9c..7d400de9 100644
--- a/docs/GUIDE.md
+++ b/docs/GUIDE.md
@@ -83,7 +83,7 @@ flowchart LR
 
 ```bash
 cd your-project
-forge init                              # once per repo: emit every tool's config
+forge init                              # once per repo: emit config for the tools it uses
 forge atlas build                       # once: index symbols so impact/scope work well
 
 # then, for any non-trivial change:
@@ -789,10 +789,14 @@ command instead. Accepts `0.17.0` or `v0.17.0`.
 
 ### `forge tools` — one repo, one agent tool (gitignore the rest)
 
-`forge sync` emits config for **every** supported agent tool from one source — great for
-portability, noisy for a repo where only one tool is ever used: `.cursor/`, `.gemini/`,
+`forge init` emits config only for the tools a repo uses (Claude plus the tools it detects,
+or an explicit `--tools <list|all>`) and records that set in `.forge/forge.config.json`
+(`tools`), so `forge sync` emits the same set afterwards. A repo with no recorded set, or
+one initialised with `--tools all`, gets config for **every** supported agent tool — great
+for portability, noisy for a repo where only one tool is ever used: `.cursor/`, `.gemini/`,
 `.codex/`, `.zed/`, `.aider.conf.yml`, and friends all show up as tracked clutter. `forge
-tools` fixes that without changing what `sync` emits.
+tools` fixes that without changing what `sync` emits (`--reset` clears the primary tool and
+leaves the recorded `tools` set alone).
 
 - `forge tools` — show the detected/primary tool (from `.forge/config.json`, else
   auto-detected from which agent folder exists — `CLAUDE.md`, `.cursor/`, `.gemini/`,
@@ -1298,8 +1302,8 @@ Plain `forge cost` remains the per-day spend view via `ccusage`.
 
 | Command                          | Answers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `forge init`                     | Emit every tool's native config from one source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `forge sync`                     | Recompile `source/` → each tool's files (idempotent).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `forge init`                     | Emit native config for the tools this repo uses — Claude + detected ones, or `--tools <list|all>` (recorded for later syncs). In `AGENTS.md` forge owns only its `<!-- forge:begin/end -->` block; a hand-written file keeps every line.                                                                                                                                                                                                                                                                                                                                                                |
+| `forge sync`                     | Recompile `source/` → each selected tool's files (idempotent); rewrites only forge's block in `AGENTS.md`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `forge doctor`                   | Health check: layers, install, drift, cortex. `forge doctor --fix` auto-repairs the safely fixable findings (missing settings hooks/permissions, ledger union-merge rule, stale `AGENTS.md`, non-executable guards) by reusing the same idempotent functions `forge init`/`forge sync` use, then re-checks.                                                                                                                                                                                                                                                                                             |
 | `forge docs check`               | Docs↔code drift: commands, env vars, MCP tools, CHANGELOG, and the Mintlify site (`mintlify/`) reconciled against the code (CI-gated on the forge repo itself).                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `forge docs sync`                | Diff-driven stale-docs sweep: UPDATED / STALE (file:line hits) / VERIFIED-UNAFFECTED per artifact (see the full section above).                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
@@ -1664,7 +1668,7 @@ code reads but this table misses fails CI on the forge repo):
 | `FORGE_LLM_AMBIENT`                                            | `1` lets the ambient hook use the proposer too                                                                                                                                                                                          |
 | `FORGE_LLM_HTTP`                                               | `1` forces direct HTTP (Anthropic Messages or OpenAI-compatible, per the resolved provider) instead of the `claude` CLI; automatic when the CLI is absent                                                                               |
 | `FORGE_ENFORCE`                                                | `1` turns the substrate advisory into a hard block on the strongest signals                                                                                                                                                             |
-| `FORGE_AUTOSYNC`                                               | `0` disables the Stop-hook AGENTS.md auto-repair                                                                                                                                                                                        |
+| `FORGE_AUTOSYNC`                                               | `0` disables the Stop-hook auto-repair of forge's block in AGENTS.md                                                                                                                                                                    |
 | `FORGE_LEDGER_ONLY`                                            | Ledger-only is the DEFAULT (the ledger is the sole store). `0` is the escape hatch — restores the legacy `lessons/*.md` + recall/brain file store while external tooling migrates                                                       |
 | `FORGE_EMBED` / `FORGE_EMBED_MODEL` / `FORGE_EMBED_TIMEOUT_MS` | optional embeddings tier (ADR-0005)                                                                                                                                                                                                     |
 | `FORGE_HOME`                                                   | override `~/.forge` (recall store location)                                                                                                                                                                                             |
diff --git a/mintlify/cli/config.mdx b/mintlify/cli/config.mdx
index 52b462f4..1de8bcd4 100644
--- a/mintlify/cli/config.mdx
+++ b/mintlify/cli/config.mdx
@@ -142,9 +142,9 @@ spec:
 - and the rest of the tools Forge emits config for
 
 The installed set is recorded in `.forge/forge.config.json` under `mcp.integrations`, so
-every subsequent `forge sync` re-emits the same servers. The stop-hook auto-sync
-byte-compares the whole config file, so a hand-edit to that file is detected and
-repaired.
+every subsequent `forge sync` re-emits the same servers and byte-compares each forge-owned
+entry, so a hand-edit to one is detected and repaired. (The stop-hook auto-sync refreshes
+only Forge's block in `AGENTS.md`; MCP config is repaired by `forge sync`.)
 
 ### `--adopt` semantics
 
diff --git a/mintlify/cli/core.mdx b/mintlify/cli/core.mdx
index 72736b7b..f20ef17a 100644
--- a/mintlify/cli/core.mdx
+++ b/mintlify/cli/core.mdx
@@ -7,15 +7,23 @@ The Core group bootstraps a repo and keeps it healthy.
 
 ## `forge init`
 
-Scaffold this repo's config — emits every tool from one shared source.
+Scaffold this repo's config — emits the tools it uses (Claude + detected, or `--tools`) from
+one shared source.
 
 ```bash
 forge init
+forge init --tools claude,cursor        # choose the tools explicitly (or --tools all)
 ```
 
-Emits `AGENTS.md`, `CLAUDE.md`, `.gemini/settings.json`, `.aider.conf.yml`, and the rest
-(plus MCP server config for Roo Code and VS Code), and the `.gitattributes` union-merge
-rule the ledger needs.
+Emits `AGENTS.md`, Claude Code's `CLAUDE.md` and `.mcp.json`, and the config of every tool
+the repo already shows signs of (`.cursor/`, `.codex/`, `.gemini/`,
+`.github/copilot-instructions.md`, …) — plus the `.gitattributes` union-merge rule the
+ledger needs. `--tools all` emits every tool (`.aider.conf.yml`, Roo Code and VS Code MCP
+config, and the rest). The selection is recorded in `.forge/forge.config.json` (`tools`) so
+later `forge sync` runs emit the same set; re-run `forge init --tools …` to change it.
+
+An existing `AGENTS.md` is never replaced: Forge appends its rules between
+`<!-- forge:begin -->` and `<!-- forge:end -->` and from then on rewrites only that block.
 
 `forge init` also merges Forge's hooks and permissions into the **global**
 `~/.claude/settings.json`, so it announces the merge before writing. The merge is
@@ -25,6 +33,7 @@ idempotent, marker-guarded, and never clobbers user entries.
 
 | Flag                  | What it does                                                                                                                                               |
 | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--tools <list>`      | Agent tools to emit config for, comma-separated (`claude`, `cursor`, `gemini`, `codex`, `zed`, `vscode`, `aider`, `continue`, `windsurf`, `roo`, `openclaw`) or `all`. An unknown name aborts before anything is written. |
 | `--profile <name>`    | Pick the policy profile for this repo. Accepts `minimal` or `standard` (default). An invalid value aborts before any scaffold, `.forge/` write, or merge.  |
 | `--no-settings`       | Skip the global `~/.claude/settings.json` merge entirely — only the per-repo config is written.                                                            |
 | `--remove-settings`   | Reverse a past settings merge. Forge-shaped hooks, permissions, statusline, and the `_forge` marker are removed; a timestamped backup is written first, and your own entries are preserved. Also invoked by `install.sh --uninstall`. |
@@ -64,6 +73,14 @@ forge sync
 Idempotent — it only rewrites what changed. Run it after editing `source/rules.json` or a
 per-repo `.forge/rules.json`.
 
+In `AGENTS.md` sync compares and rewrites only the block between `<!-- forge:begin -->` and
+`<!-- forge:end -->`; text above or below it is yours and is never touched. The Stop hook
+runs the same block refresh after each session (disable with `FORGE_AUTOSYNC=0`). An
+`AGENTS.md` generated whole by an older Forge converts to a block on the next sync, keeping
+any text you added around the generated part; if you edited inside the generated text, sync
+first saves the old file as `AGENTS.md.forge-bak-<time>`. Sync emits for the tools recorded
+by `forge init` (all tools when none are recorded).
+
 ## `forge doctor`
 
 Health-check installed tools, guards, MCP auth, and config drift.
diff --git a/src/cli.js b/src/cli.js
index b03c8087..c7cfe6a0 100755
--- a/src/cli.js
+++ b/src/cli.js
@@ -179,16 +179,27 @@ HANDLERS.init = async (argv) => {
   }
   const profileIdx = argv.indexOf("--profile");
   const profile = profileIdx >= 0 ? argv[profileIdx + 1] : undefined;
+  // --tools <list> (or --tools=<list>): the agent tools to emit config for. Omitted = the set an
+  // earlier init recorded, else Claude plus the tools this repo already uses.
+  const toolsEq = argv.find((a) => a.startsWith("--tools="));
+  const toolsIdx = argv.indexOf("--tools");
+  const tools = toolsEq
+    ? toolsEq.slice("--tools=".length)
+    : toolsIdx >= 0
+      ? (argv[toolsIdx + 1] ?? "")
+      : undefined;
   // ME-22: emit the GLOBAL-settings disclosure BEFORE the merge mutates the file. init
   // forwards `onSettingsNotice` to mergeSettings, which fires it right before touching
   // ~/.claude/settings.json — so the notice always precedes the mutation it describes.
-  heading(`${BRAND.brand} init — this repo now speaks every AI tool from one source.\n`);
+  heading(`${BRAND.brand} init — one source for every AI tool this repo uses.\n`);
   const {
     report,
     bytes,
     settings,
     detected,
+    warnings,
     profile: profileResult,
+    tools: toolsResult,
   } = /** @type {any} */ (
     init({
       targetRoot: process.cwd(),
@@ -196,18 +207,29 @@ HANDLERS.init = async (argv) => {
       profile,
       settingsPath,
       onSettingsNotice: consentLine,
+      tools,
     })
   );
-  if (profileResult?.error) {
-    console.error(`  ${profileResult.error}`);
+  if (profileResult?.error || toolsResult?.error) {
+    console.error(`  ${profileResult?.error ?? toolsResult.error}`);
     process.exitCode = 1;
     return;
   }
   const wrote = report.filter((r) => r.action === "written").map((r) => r.target);
   console.log(`  emitted:  ${wrote.length ? wrote.join(", ") : "(all up to date)"}`);
+  const toolOrigin = {
+    "--tools": "from --tools",
+    config: "recorded in .forge/forge.config.json",
+    detected: "Claude + tools found in this repo",
+  }[toolsResult.source];
   console.log(
-    `  source:   AGENTS.md (${bytes} B) — edit rules in source/, re-run \`${BRAND.cli} sync\``,
+    `  tools:    ${toolsResult.tools === null ? "all" : toolsResult.tools.join(", ")} (${toolOrigin}) — change with \`${BRAND.cli} init --tools <list|all>\``,
   );
+  console.log(
+    `  source:   AGENTS.md (${bytes} B) — forge owns only the block between <!-- forge:begin --> and <!-- forge:end -->; edit rules in source/, re-run \`${BRAND.cli} sync\``,
+  );
+  for (const w of [...(warnings ?? []), ...(toolsResult.warning ? [toolsResult.warning] : [])])
+    console.warn(`  ! ${w}`);
   // ME-19: sync is non-transactional — if a target failed mid-emit, say so instead of
   // implying every tool is ready, and fail the command.
   const failedTargets = report.filter((r) => r.action === "error");
@@ -416,10 +438,14 @@ HANDLERS.taste = async (argv) => {
 };
 HANDLERS.sync = async () => {
   const { sync } = await import("./sync.js");
-  const { report, warnings, bytes, partial, status } = sync({
+  const { report, warnings, bytes, partial, status, tools } = sync({
     targetRoot: process.cwd(),
   });
   heading(`${BRAND.brand} sync — one source → every tool\n`);
+  if (tools !== null)
+    console.log(
+      `  tools: ${tools.length ? tools.join(", ") : "none"} + AGENTS.md (recorded by \`${BRAND.cli} init\`; change with \`${BRAND.cli} init --tools <list|all>\`)\n`,
+    );
   for (const r of report) {
     console.log(
       `  ${r.action.padEnd(16)} ${String(r.target).padEnd(22)} ${r.tool}${r.note ? `  · ${r.note}` : ""}`,
diff --git a/src/commands.js b/src/commands.js
index 6b00a072..ccc2829c 100644
--- a/src/commands.js
+++ b/src/commands.js
@@ -10,10 +10,15 @@
 
 export const COMMANDS = {
   init: {
-    summary: "scaffold this repo's config — emits every tool from one shared source",
+    summary:
+      "scaffold this repo's config — emits the tools it uses (Claude + detected, or --tools) from one shared source",
     usage:
-      "forge init [--profile minimal|standard] [--no-settings | --settings-only | --remove-settings]",
+      "forge init [--tools <list|all>] [--profile minimal|standard] [--no-settings | --settings-only | --remove-settings]",
     flags: [
+      {
+        flag: "--tools <list|all>",
+        desc: "agent tools to emit config for, comma-separated (claude, cursor, gemini, codex, zed, vscode, aider, continue, windsurf, roo, openclaw) or all. Default: the set an earlier init recorded, else Claude plus every tool the repo already uses (.cursor/, .codex/, .github/copilot-instructions.md, …). Recorded in .forge/forge.config.json so later syncs emit the same set.",
+      },
       {
         flag: "--profile <minimal|standard>",
         desc: "policy profile: minimal = the five core-safety rules only; standard = the full pack (default). Legacy names (web-app, backend-service, library, regulated) are deprecated aliases of standard.",
@@ -31,7 +36,12 @@ export const COMMANDS = {
         desc: "reverse the merge — remove forge-managed hooks/permissions/statusline from ~/.claude/settings.json (backed up first)",
       },
     ],
-    examples: ["forge init", "forge init --profile minimal", "forge init --remove-settings"],
+    examples: [
+      "forge init",
+      "forge init --tools claude,cursor",
+      "forge init --profile minimal",
+      "forge init --remove-settings",
+    ],
   },
   sync: {
     summary: "recompile the canonical source into each tool's native config files",
diff --git a/src/cortex_hook_main.js b/src/cortex_hook_main.js
index 4077055e..c7eac0cf 100644
--- a/src/cortex_hook_main.js
+++ b/src/cortex_hook_main.js
@@ -97,8 +97,9 @@ async function main() {
     }
     // Auto-sync: anything this session taught the memory (lessons, facts) reaches
     // every AGENTS.md-reading tool NOW — drift used to be detected by doctor but
-    // repaired by nobody. Only touches an already-Forge-managed AGENTS.md;
-    // kill switch FORGE_AUTOSYNC=0. Fail-safe like everything else here.
+    // repaired by nobody. Rewrites ONLY forge's marked block in an AGENTS.md that already
+    // has one; text a person wrote outside it is never touched, and a hand-written file
+    // is never adopted. Kill switch FORGE_AUTOSYNC=0. Fail-safe like everything else here.
     try {
       const { autoSyncIfDrifted } = await import("./sync.js");
       autoSyncIfDrifted(root);
diff --git a/src/doctor.js b/src/doctor.js
index bd283d9d..1c99758c 100644
--- a/src/doctor.js
+++ b/src/doctor.js
@@ -19,13 +19,13 @@ import { isStale, load as loadAtlas } from "./atlas.js";
 import { BRAND } from "./brand.js";
 import { summary as cortexSummary } from "./cortex.js";
 import { docsCheck } from "./docs_check.js";
-import { hashContent, mdHeader } from "./emit/_shared.js";
+import { extractHash, hashContent } from "./emit/_shared.js";
 import { gatewayBase, gatewayModelMap } from "./gateway_model_map.js";
 import { ensureLedgerGitattributes, guardKey, isStaleManagedHook, mergeSettings } from "./init.js";
 import { verify as ledgerVerify, repoLedger } from "./ledger_store.js";
 import { PRICING_VERIFIED } from "./model_tiers.js";
 import { activeProvider, envModelOverride } from "./providers.js";
-import { canonical, sync } from "./sync.js";
+import { agentsMdStatus, canonical, sync } from "./sync.js";
 import { updateStatus } from "./update.js";
 
 const ok = (label, note = "") => ({ status: "ok", label, note });
@@ -539,27 +539,42 @@ function checkDrift(out, targetRoot) {
     label: "emit/refresh AGENTS.md (forge sync)",
     run: () => sync({ targetRoot }),
   };
-  const agents = join(targetRoot, "AGENTS.md");
-  if (!existsSync(agents)) {
-    out.push({
-      ...warn("AGENTS.md", "not emitted here — run `forge sync`"),
-      fix: syncFix,
-    });
-    return;
-  }
-  // Compare the actual file to the full expected content, not just the embedded marker —
-  // a hand-edited body with an intact marker would otherwise report "in sync" (P0-08).
+  // The same classifier sync and the Stop-hook auto-sync use, so doctor can never advise a
+  // write they would refuse. Forge owns only its marked block: the block is compared byte
+  // for byte (an edited block with an intact marker still counts as drift, P0-08), and text
+  // outside it is the person's, never "stale". Every fix below is sync, which only touches
+  // the block (a pre-block file edited inside its generated text is backed up first).
   const body = canonical(targetRoot);
-  const expected = `${mdHeader(hashContent(body))}\n${body}\n`;
-  const actual = readFileSync(agents, "utf8");
-  out.push(
-    actual === expected
-      ? ok("AGENTS.md", "in sync")
-      : {
-          ...warn("AGENTS.md", "stale or hand-edited — run `forge sync`"),
-          fix: syncFix,
-        },
-  );
+  const status = agentsMdStatus(targetRoot, body);
+  const fixable = (note) => ({ ...warn("AGENTS.md", note), fix: syncFix });
+  const rows = {
+    missing: () => fixable("not emitted here — run `forge sync`"),
+    "hand-written": () =>
+      fixable(
+        "hand-written AGENTS.md (no Forge block) — `forge sync` appends the Forge section and leaves your text as is",
+      ),
+    "in-sync": () => ok("AGENTS.md", "in sync (Forge block)"),
+    drifted: () =>
+      fixable(
+        "Forge block stale or edited inside its markers — run `forge sync` (text outside the block is kept)",
+      ),
+    legacy: () =>
+      extractHash(status.text) === hashContent(body)
+        ? ok("AGENTS.md", "in sync (pre-block format — the next sync converts it to a Forge block)")
+        : fixable(
+            "stale, pre-block format — `forge sync` converts it to a Forge block and keeps any text you added around it",
+          ),
+    "legacy-edited": () =>
+      fixable(
+        "pre-block format edited inside the generated text — `forge sync` converts it to a Forge block and saves the old file as AGENTS.md.forge-bak-<time>",
+      ),
+    damaged: () =>
+      warn(
+        "AGENTS.md",
+        "damaged Forge markers (forge:begin without forge:end, or the reverse) — fix them by hand",
+      ),
+  };
+  out.push(rows[status.state]());
 }
 
 // MCP hygiene: past ~6 servers, tool-selection accuracy drops and the context bloats.
diff --git a/src/emit/_shared.js b/src/emit/_shared.js
index e98110eb..f93b0a63 100644
--- a/src/emit/_shared.js
+++ b/src/emit/_shared.js
@@ -45,3 +45,85 @@ export const managedContent = (header, body) => `${header}\n${body}\n`;
 
 export const writeManaged = (absPath, header, body) =>
   writeIfChanged(absPath, managedContent(header, body));
+
+// ---------------------------------------------------------------------------
+// Managed BLOCK: how forge owns PART of a file a human also writes (AGENTS.md). Forge
+// rewrites only the lines between the two markers; everything outside them belongs to
+// the human and is never rewritten, reordered or dropped.
+// ---------------------------------------------------------------------------
+
+const MARKER_NS = MARKER.split(":")[0];
+export const BLOCK_BEGIN = `<!-- ${MARKER_NS}:begin -->`;
+export const BLOCK_END = `<!-- ${MARKER_NS}:end -->`;
+
+/** A marker counts only as a whole line, so prose that mentions it inline is never taken
+ *  for the block. `\r?` tolerates a CRLF checkout. */
+const wholeLine = (marker) => new RegExp(`^${marker}\\r?$`, "m");
+const BEGIN_RE = wholeLine(BLOCK_BEGIN);
+const END_RE = wholeLine(BLOCK_END);
+
+/** The exact bytes of the managed block: begin marker, the generated header (it carries the
+ *  `forge:sync:<hash>` marker), the body, end marker. The writer and every drift check build
+ *  their expectation through this one helper, as with managedContent (RA-16). */
+export const managedBlock = (header, body) =>
+  `${BLOCK_BEGIN}\n${header}\n${body.replace(/\n*$/, "\n")}${BLOCK_END}\n`;
+
+/**
+ * Locate the managed block. null when there is none; `{damaged: true}` when only one marker
+ * is present or the end comes first (forge must not guess where its text stops); otherwise
+ * the extent `[start, end)`, where `end` includes the end marker's newline.
+ * @param {string|null} text
+ * @returns {null | {damaged: true} | {damaged: false, start: number, end: number}}
+ */
+export function findManagedBlock(text) {
+  if (typeof text !== "string") return null;
+  const begin = BEGIN_RE.exec(text);
+  const anyEnd = END_RE.exec(text);
+  if (!begin && !anyEnd) return null;
+  if (!begin) return { damaged: true };
+  const from = begin.index + begin[0].length;
+  const end = END_RE.exec(text.slice(from));
+  if (!end) return { damaged: true };
+  let stop = from + end.index + end[0].length;
+  if (text[stop] === "\n") stop += 1;
+  return { damaged: false, start: begin.index, end: stop };
+}
+
+/** True iff the text holds a complete (begin + end) forge-managed block. */
+export function hasManagedBlock(text) {
+  const b = findManagedBlock(text);
+  return Boolean(b && !b.damaged);
+}
+
+/** The generated-header line (any hash) — how a pre-block, fully generated file starts, and
+ *  the line an adopted file's marker is refreshed through in place. */
+export const MD_HEADER_RE = new RegExp(
+  `^<!-- GENERATED by .*${MARKER}:([a-f0-9]{12}) -->[ \\t]*\\r?$`,
+  "m",
+);
+
+/**
+ * Split a legacy fully generated file (the pre-block format: `mdHeader` line, then the body)
+ * into the human text around forge's region. The header's hash is the hash of the body forge
+ * wrote, so the split whose body hashes to it is forge's text byte for byte: whatever sits
+ * above the header or below that body was added by a person and is returned verbatim.
+ * `lossless: false` means no split matched (the generated region itself was edited), so
+ * forge cannot tell its bytes from the person's and the caller must keep a backup.
+ * @param {string|null} text
+ * @returns {null | {lossless: boolean, before: string, after: string}}
+ */
+export function splitLegacyManaged(text) {
+  if (typeof text !== "string" || findManagedBlock(text)) return null;
+  const m = MD_HEADER_RE.exec(text);
+  if (!m) return null;
+  const before = text.slice(0, m.index);
+  let rest = text.slice(m.index + m[0].length);
+  if (rest.startsWith("\n")) rest = rest.slice(1);
+  // managedContent wrote `${header}\n${body}\n` and a body always ends in "\n", so forge's
+  // region ends at a blank line: test only those (one sha256 each, a few dozen at most).
+  for (let k = rest.indexOf("\n\n") + 1; k > 0; k = rest.indexOf("\n\n", k) + 1) {
+    if (hashContent(rest.slice(0, k)) === m[1])
+      return { lossless: true, before, after: rest.slice(k + 1) };
+  }
+  return { lossless: false, before, after: "" };
+}
diff --git a/src/emit/claude.js b/src/emit/claude.js
index e00893dc..383f175d 100644
--- a/src/emit/claude.js
+++ b/src/emit/claude.js
@@ -30,6 +30,15 @@ export default {
         note: "prepended @AGENTS.md import to your existing CLAUDE.md (content preserved)",
       };
     }
+    // A CLAUDE.md forge generated invites notes below its header, so a later sync must keep
+    // them: refresh only the marker line in place (re-adding the import if it was removed),
+    // never regenerate the file around the person's notes.
+    if (existing !== null) {
+      let next = existing.replace(ctx.shared.MD_HEADER_RE, ctx.shared.mdHeader(ctx.hash));
+      if (!IMPORTS_AGENTS.test(next)) next = `@AGENTS.md\n\n${next}`;
+      const action = ctx.shared.writeIfChanged(path, next);
+      return { tool: this.tool, target: "CLAUDE.md", action, note: "@AGENTS.md import" };
+    }
     const content = [
       "@AGENTS.md",
       "",
diff --git a/src/emit/mcp.js b/src/emit/mcp.js
index 456e303e..915eea70 100644
--- a/src/emit/mcp.js
+++ b/src/emit/mcp.js
@@ -29,14 +29,15 @@ export const OPENCLAW_TARGET = ".openclaw/mcp.json";
 
 // `key` is a DOTTED PATH into the document, not a single top-level key: OpenClaw nests its
 // registry under `mcp.servers`, every other tool uses one flat key. `bucketAt` resolves both.
+// `id` is the tool's canonical key (repo_config KNOWN_TOOLS), used to honour a tool selection.
 const JSON_TARGETS = [
-  { tool: "Claude Code", file: ".mcp.json", key: "mcpServers" },
-  { tool: "Cursor", file: ".cursor/mcp.json", key: "mcpServers" },
-  { tool: "Gemini CLI", file: ".gemini/settings.json", key: "mcpServers" },
-  { tool: "Roo Code", file: ".roo/mcp.json", key: "mcpServers" },
-  { tool: "Zed", file: ".zed/settings.json", key: "context_servers" },
-  { tool: "VS Code / Copilot", file: ".vscode/mcp.json", key: "servers" },
-  { tool: "OpenClaw", file: OPENCLAW_TARGET, key: "mcp.servers" },
+  { id: "claude", tool: "Claude Code", file: ".mcp.json", key: "mcpServers" },
+  { id: "cursor", tool: "Cursor", file: ".cursor/mcp.json", key: "mcpServers" },
+  { id: "gemini", tool: "Gemini CLI", file: ".gemini/settings.json", key: "mcpServers" },
+  { id: "roo", tool: "Roo Code", file: ".roo/mcp.json", key: "mcpServers" },
+  { id: "zed", tool: "Zed", file: ".zed/settings.json", key: "context_servers" },
+  { id: "vscode", tool: "VS Code / Copilot", file: ".vscode/mcp.json", key: "servers" },
+  { id: "openclaw", tool: "OpenClaw", file: OPENCLAW_TARGET, key: "mcp.servers" },
 ];
 
 const CONTINUE_DIR = join(".continue", "mcpServers");
@@ -400,13 +401,15 @@ function openclawEnableHint(servers) {
  * pre-existing divergent entry is preserved and reported unless that exact target adopted
  * the name. Every name is validated and Continue filenames checked for collisions before
  * any write (ME-11); a per-target write failure surfaces as an `error` row (never a throw)
- * so callers can keep disk and the managed-set record consistent (ME-10).
+ * so callers can keep disk and the managed-set record consistent (ME-10). `tools` limits the
+ * emit to those tools' targets (canonical keys); null/omitted = every target, as before.
  * @param {{targetRoot:string, servers:Record<string,{command:string,args?:string[]}>,
- *   owns?:(target:string, name:string)=>boolean}} opts
+ *   owns?:(target:string, name:string)=>boolean, tools?:string[]|null}} opts
  */
-export function emitMcp({ targetRoot, servers, owns = () => true }) {
+export function emitMcp({ targetRoot, servers, owns = () => true, tools = null }) {
   validateServers(servers);
-  const rows = JSON_TARGETS.map((t) => {
+  const emits = (id) => tools === null || tools.includes(id);
+  const rows = JSON_TARGETS.filter((t) => emits(t.id)).map((t) => {
     const r = mergeJson(join(targetRoot, t.file), t.key, servers, (name) => owns(t.file, name));
     return {
       tool: `${t.tool} MCP`,
@@ -418,15 +421,18 @@ export function emitMcp({ targetRoot, servers, owns = () => true }) {
       note: t.file === OPENCLAW_TARGET ? `${r.note}; ${openclawEnableHint(servers)}` : r.note,
     };
   });
-  const codex = emitCodexToml(join(targetRoot, CODEX_FILE), servers, (name) =>
-    owns(CODEX_TARGET, name),
-  );
-  rows.push({
-    tool: "Codex MCP",
-    target: CODEX_TARGET,
-    action: codex.action,
-    note: codex.note,
-  });
+  if (emits("codex")) {
+    const codex = emitCodexToml(join(targetRoot, CODEX_FILE), servers, (name) =>
+      owns(CODEX_TARGET, name),
+    );
+    rows.push({
+      tool: "Codex MCP",
+      target: CODEX_TARGET,
+      action: codex.action,
+      note: codex.note,
+    });
+  }
+  if (!emits("continue")) return rows;
   const dir = join(targetRoot, CONTINUE_DIR);
   for (const [name, def] of Object.entries(servers)) {
     const r = emitContinueServer(dir, name, def);
diff --git a/src/init.js b/src/init.js
index 5da039c9..48641e20 100644
--- a/src/init.js
+++ b/src/init.js
@@ -16,7 +16,14 @@ import { BRAND } from "./brand.js";
 import { ensureForgePrivateIgnored } from "./gitignore.js";
 import { GITATTRIBUTES_RULE } from "./ledger_store.js";
 import { autoDetectProvider } from "./providers.js";
-import { validateProfile, writeForgeConfig } from "./repo_config.js";
+import {
+  detectTools,
+  KNOWN_TOOLS,
+  parseTools,
+  readForgeConfig,
+  validateProfile,
+  writeForgeConfig,
+} from "./repo_config.js";
 import { sync } from "./sync.js";
 import { list as tasteList } from "./taste.js";
 import { toPosix } from "./util.js";
@@ -736,14 +743,17 @@ export function removeForgeSettings({ settingsPath } = {}) {
  *  any existing config rather than clobbering it (unknown keys round-trip); a corrupt
  *  config file makes the write refuse loudly instead of discarding the bytes (RA-15).
  *  Legacy profile names are accepted, stored as their mapped profile, and surfaced via
- *  `deprecated` so the CLI can warn (RA-14). Returns the resolved profile or null. */
-function writeProfile(targetRoot, profile) {
+ *  `deprecated` so the CLI can warn (RA-14). The tool selection rides the same write
+ *  (writeForgeConfig backs the file up on every write, so one write, not two). Returns the
+ *  resolved profile or null. */
+function writeProfile(targetRoot, profile, tools) {
   if (!profile) return null;
   const v = validateProfile(profile);
   // `=== false` (not `!v.ok`): tsc only narrows the discriminated union this way here.
   if (v.ok === false) return { error: v.error };
   const res = writeForgeConfig(targetRoot, (cfg) => {
     cfg.profile = v.profile;
+    cfg.tools = toolsValue(tools);
     return cfg;
   });
   if (res.ok === false) return { error: res.reason };
@@ -751,14 +761,59 @@ function writeProfile(targetRoot, profile) {
 }
 
 /**
- * Scaffold this repo's cross-tool config (emit every tool) in one step.
+ * Decide which agent tools `forge init` emits config for. Pure (reads, never writes):
+ *   1. an explicit `--tools` list (`all` = every tool); unknown names are an error;
+ *   2. else the selection an earlier init recorded in `.forge/forge.config.json` (`tools`);
+ *   3. else Claude plus every tool the repo already shows signs of (`.cursor/`, `.codex/`,
+ *      `.github/copilot-instructions.md`, …) — never a folder for a tool nobody uses.
+ * `tools: null` means every tool. AGENTS.md is always emitted: it is the shared source.
+ * @param {string} targetRoot
+ * @param {string|string[]} [explicit]
+ * @returns {{tools: string[]|null, source: "--tools"|"config"|"detected"} | {error: string}}
+ */
+export function resolveInitTools(targetRoot, explicit) {
+  if (explicit !== undefined) {
+    const { tools, unknown } = parseTools(explicit);
+    if (unknown.length)
+      return {
+        error: `unknown tool(s) for --tools: ${unknown.join(", ")} (known: ${KNOWN_TOOLS.join(", ")}, or all)`,
+      };
+    if (tools !== null && !tools.length)
+      return { error: "--tools needs at least one tool name (or all)" };
+    return { tools, source: "--tools" };
+  }
+  const recorded = readForgeConfig(targetRoot).tools;
+  if (typeof recorded === "string" || Array.isArray(recorded))
+    return { tools: parseTools(recorded).tools, source: "config" };
+  return { tools: [...new Set(["claude", ...detectTools(targetRoot)])], source: "detected" };
+}
+
+/** Record the resolved selection so later `forge sync` runs (and doctor's fix) emit the same
+ *  set. Written only when it changed, since writeForgeConfig backs the file up on every
+ *  write. Returns the refusal reason when the config cannot be written, else null. */
+function recordTools(targetRoot, tools) {
+  const value = toolsValue(tools);
+  if (JSON.stringify(readForgeConfig(targetRoot).tools) === JSON.stringify(value)) return null;
+  const res = writeForgeConfig(targetRoot, (cfg) => {
+    cfg.tools = value;
+    return cfg;
+  });
+  return res.ok === false ? res.reason : null;
+}
+
+/** How a selection is stored: the key list, or "all" (so tools added later are included). */
+const toolsValue = (tools) => (tools === null ? "all" : tools);
+
+/**
+ * Scaffold this repo's cross-tool config in one step, for the tools the repo uses (see
+ * resolveInitTools) rather than a config folder for every tool forge knows.
  *
  * `settingsOnly` runs the idempotent, marker-guarded `mergeSettings` ONLY — no repo
  * emit, no AGENTS.md, no gitattributes. That is the surface `install.sh` calls to wire
  * hooks + permissions into ~/.claude/settings.json without ever touching the user's repo.
  * `onSettingsNotice(target)` is forwarded to `mergeSettings` so the GLOBAL-settings
  * disclosure is emitted BEFORE the merge mutates ~/.claude/settings.json (ME-22).
- * @param {{targetRoot?: string, noSettings?: boolean, profile?: string, settingsOnly?: boolean, settingsPath?: string, onSettingsNotice?: (target: string) => void}} [opts]
+ * @param {{targetRoot?: string, noSettings?: boolean, profile?: string, settingsOnly?: boolean, settingsPath?: string, onSettingsNotice?: (target: string) => void, tools?: string|string[]}} [opts]
  */
 export function init({
   targetRoot = process.cwd(),
@@ -767,6 +822,7 @@ export function init({
   settingsOnly = false,
   settingsPath,
   onSettingsNotice,
+  tools,
 } = {}) {
   if (settingsOnly) {
     return {
@@ -783,13 +839,19 @@ export function init({
   const valid = validateProfile(profile);
   // `=== false` (not `!valid.ok`): tsc only narrows the discriminated union this way here.
   if (valid.ok === false) return { profile: { error: valid.error }, aborted: true };
-  const profileResult = writeProfile(targetRoot, profile);
+  // A bad --tools list aborts just as early: nothing emitted, nothing written.
+  const selection = resolveInitTools(targetRoot, tools);
+  if ("error" in selection) return { tools: { error: selection.error }, aborted: true };
+  const profileResult = writeProfile(targetRoot, profile, selection.tools);
   // HI-09: the profile name is valid, but persistence can still FAIL at write time when
   // `.forge/forge.config.json` is corrupt (writeForgeConfig refuses). Abort BEFORE any further
   // side effect — no sync/AGENTS.md, no .gitattributes append, no settings merge — exactly like
   // the invalid-name path, so a corrupt config never leaves a half-initialized repo.
   if (profileResult?.error) return { profile: profileResult, aborted: true };
-  const r = sync({ targetRoot });
+  // A config that cannot record the selection still gets it for THIS run; the result says
+  // that later syncs fall back to every tool rather than failing the whole init.
+  const unrecorded = profileResult ? null : recordTools(targetRoot, selection.tools);
+  const r = sync({ targetRoot, tools: selection.tools ?? "all" });
   ensureLedgerGitattributes(targetRoot);
   // Session hook logs hold raw prompts/commands — never let them be committed.
   ensureForgePrivateIgnored(targetRoot);
@@ -799,7 +861,14 @@ export function init({
     onNotice: onSettingsNotice,
   });
   const detected = autoDetectProvider();
-  return { ...r, settings, detected, profile: profileResult };
+  const toolsResult = {
+    tools: selection.tools,
+    source: selection.source,
+    ...(unrecorded
+      ? { warning: `tool selection not recorded (${unrecorded}); later syncs emit every tool` }
+      : {}),
+  };
+  return { ...r, settings, detected, profile: profileResult, tools: toolsResult };
 }
 
 function skillDescription(dir) {
diff --git a/src/integrations.js b/src/integrations.js
index e796a0f6..2e63b3fa 100644
--- a/src/integrations.js
+++ b/src/integrations.js
@@ -27,7 +27,7 @@ import {
   removeMcp,
   validateServerName,
 } from "./emit/mcp.js";
-import { readForgeConfig, writeForgeConfig } from "./repo_config.js";
+import { parseTools, readForgeConfig, writeForgeConfig } from "./repo_config.js";
 
 /** The catalog of known optional integrations. Keep each entry honest about what running it
  *  actually does (network, third-party code execution). */
@@ -193,8 +193,12 @@ export function addIntegration(name, { targetRoot = process.cwd(), adopt = false
   for (const t of MCP_TARGET_FILES)
     if (!foreign.has(t) || adopt) newAdoptions.push({ server: name, target: t });
   const owns = adoptionOwns([...rec.adopted, ...newAdoptions]);
-  // Emit FIRST (ME-10). A per-target write failure surfaces as an `error` row.
-  const rows = emitMcp({ targetRoot, servers, owns });
+  // Emit FIRST (ME-10). A per-target write failure surfaces as an `error` row. Only into the
+  // tools `forge init` recorded for this repo (every tool when none are recorded), the same
+  // set `forge sync` emits for, so adding a server never creates an unused tool's config.
+  const recorded =
+    typeof cfg.tools === "string" || Array.isArray(cfg.tools) ? parseTools(cfg.tools).tools : null;
+  const rows = emitMcp({ targetRoot, servers, owns, tools: recorded });
   const failed = rows.filter((r) => r.action === "error");
   if (failed.length)
     return {
diff --git a/src/repo_config.js b/src/repo_config.js
index 54a42a99..811a7f93 100644
--- a/src/repo_config.js
+++ b/src/repo_config.js
@@ -1,6 +1,7 @@
 // forge repo config — THE single per-repo config module (RA-15). The unified file is
-// <root>/.forge/forge.config.json: profile / disableSections / rules (read by sync)
-// plus primaryTool / tools (read by `forge tools`), and any future keys — unknown keys
+// <root>/.forge/forge.config.json: profile / disableSections / rules / tools (read by
+// sync; `tools` is the set of agent tools this repo emits config for, recorded by
+// `forge init`) plus primaryTool (read by `forge tools`), and any future keys — unknown keys
 // always round-trip through writeForgeConfig. The legacy <root>/.forge/config.json
 // (primaryTool/tools only) is still migration-read; on key conflicts the unified
 // forge.config.json wins, and the legacy file is left in place.
@@ -58,6 +59,58 @@ export const KNOWN_TOOLS = [
   "openclaw",
 ];
 
+// Every on-disk sign that a repo already uses a tool — the evidence `forge init` needs to
+// emit that tool's config. Broader than DETECT (which only ranks a single primary tool):
+// a tool's legacy rules files count too, e.g. `.github/copilot-instructions.md` for Copilot.
+/** @type {Record<string, string[]>} */
+const TOOL_MARKERS = {
+  claude: ["CLAUDE.md", ".claude", ".mcp.json"],
+  cursor: [".cursor", ".cursorrules"],
+  gemini: [".gemini", "GEMINI.md"],
+  codex: [".codex"],
+  zed: [".zed", ".rules"],
+  vscode: [".vscode", ".github/copilot-instructions.md"],
+  aider: [".aider.conf.yml"],
+  continue: [".continue"],
+  windsurf: [".windsurf", ".windsurfrules", ".devin"],
+  roo: [".roo", ".roomodes"],
+  openclaw: [".openclaw"],
+};
+
+// Names people type for a tool whose canonical key differs.
+/** @type {Record<string, string>} */
+const TOOL_ALIASES = { copilot: "vscode", devin: "windsurf", "claude-code": "claude" };
+
+/**
+ * Every tool this repo already shows signs of using (KNOWN_TOOLS order). Pure read.
+ * @param {string} [root]
+ * @returns {string[]}
+ */
+export function detectTools(root = process.cwd()) {
+  return KNOWN_TOOLS.filter((t) => TOOL_MARKERS[t].some((m) => existsSync(join(root, m))));
+}
+
+/**
+ * Normalise a tool selection — a `--tools` value (`"claude,cursor"`, `"all"`) or the config's
+ * `tools` key (an array, or `"all"`) — into canonical keys in KNOWN_TOOLS order. `tools: null`
+ * means every tool. Unrecognised names come back in `unknown` so a caller can refuse them
+ * (init) or warn (sync). Pure.
+ * @param {unknown} value
+ * @returns {{tools: string[]|null, unknown: string[]}}
+ */
+export function parseTools(value) {
+  const list = typeof value === "string" ? value.split(",") : Array.isArray(value) ? value : [];
+  const names = list
+    .map((t) => String(t).trim().toLowerCase())
+    .filter(Boolean)
+    .map((t) => TOOL_ALIASES[t] ?? t);
+  if (names.includes("all")) return { tools: null, unknown: [] };
+  return {
+    tools: KNOWN_TOOLS.filter((t) => names.includes(t)),
+    unknown: [...new Set(names.filter((t) => !KNOWN_TOOLS.includes(t)))],
+  };
+}
+
 // Map a sync-report row's tool label to a canonical tool key. The shared source
 // (AGENTS.md) and any unmapped label return null and are never gitignored.
 /** @type {[string, RegExp][]} */
@@ -260,10 +313,11 @@ export function setPrimaryTool(root, tool) {
 }
 
 /**
- * Clear the primary-tool config: removes the `primaryTool`/`tools` keys from BOTH the
- * unified forge.config.json and the legacy config.json (else a legacy value would
- * resurface on the next migration read), preserving every other key. A file left empty
- * is deleted; a corrupt file is left untouched (never rewritten). Never throws.
+ * Clear the primary-tool config: removes the `primaryTool` key from BOTH the unified
+ * forge.config.json and the legacy config.json (else a legacy value would resurface on the
+ * next migration read), preserving every other key. `tools` (the emit set `forge init`
+ * recorded) stays: dropping it would make the next sync emit every tool again. A file left
+ * empty is deleted; a corrupt file is left untouched (never rewritten). Never throws.
  * @param {string} root
  * @returns {{cleared:boolean, path:string}}
  */
@@ -276,10 +330,9 @@ export function clearRepoConfig(root) {
       warnCorrupt(file);
       continue;
     }
-    if (!("primaryTool" in data) && !("tools" in data)) continue;
+    if (!("primaryTool" in data)) continue;
     had = true;
     delete data.primaryTool;
-    delete data.tools;
     if (Object.keys(data).length === 0) rmSync(file, { force: true });
     else writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
   }
diff --git a/src/sync.js b/src/sync.js
index c6ff8b04..0eaf53ee 100644
--- a/src/sync.js
+++ b/src/sync.js
@@ -18,7 +18,13 @@ import openclaw from "./emit/openclaw.js";
 import windsurf from "./emit/windsurf.js";
 import zed from "./emit/zed.js";
 import { managedMcpState } from "./integrations.js";
-import { LEGACY_PROFILES, readForgeConfig } from "./repo_config.js";
+import {
+  KNOWN_TOOLS,
+  LEGACY_PROFILES,
+  parseTools,
+  readForgeConfig,
+  rowToolKey,
+} from "./repo_config.js";
 
 const MODULES = [
   codex,
@@ -156,20 +162,154 @@ function buildCanonical(targetRoot) {
   return assemble(rules) + (brain ? `\n${brain}` : "") + (lessons ? `\n${lessons}` : "");
 }
 
-export function sync({ targetRoot = process.cwd() } = {}) {
+/** Filesystem-safe timestamp for backup names (same convention as init / repo_config). */
+const stamp = () => new Date().toISOString().replace(/[:.]/g, "-");
+
+/**
+ * Where AGENTS.md stands against the block sync would write. The ONE reader shared by sync,
+ * the Stop-hook auto-sync and doctor, so they can never disagree about which text is forge's:
+ *   missing        no AGENTS.md
+ *   hand-written   a person's file with no forge block (sync appends one, never rewrites it)
+ *   in-sync        the block matches the canonical source byte for byte
+ *   drifted        the block differs (stale source, or an edit inside the markers)
+ *   legacy         the pre-block, fully generated format, hash-verified: it converts to a block
+ *                  keeping any text a person added above or below forge's region
+ *   legacy-edited  pre-block format whose generated region was itself edited; converting it
+ *                  needs a backup, so only an explicit `forge sync` does it
+ *   damaged        one marker without the other; forge will not guess where its text ends
+ * @param {string} [targetRoot]
+ * @param {string} [body] the canonical body (built from the repo when omitted)
+ * @returns {{state:"missing"|"hand-written"|"in-sync"|"drifted"|"legacy"|"legacy-edited"|"damaged",
+ *   path:string, text:string|null, block:string,
+ *   found?:{start:number, end:number}, legacy?:{lossless:boolean, before:string, after:string}}}
+ */
+export function agentsMdStatus(targetRoot = process.cwd(), body = buildCanonical(targetRoot)) {
+  const path = join(targetRoot, "AGENTS.md");
+  const text = shared.readIfExists(path);
+  const block = shared.managedBlock(shared.mdHeader(shared.hashContent(body)), body);
+  if (text === null) return { state: "missing", path, text, block };
+  const found = shared.findManagedBlock(text);
+  if (found?.damaged === true) return { state: "damaged", path, text, block };
+  if (found?.damaged === false) {
+    const current = text.slice(found.start, found.end);
+    return { state: current === block ? "in-sync" : "drifted", path, text, block, found };
+  }
+  const legacy = shared.splitLegacyManaged(text);
+  if (legacy)
+    return { state: legacy.lossless ? "legacy" : "legacy-edited", path, text, block, legacy };
+  return { state: "hand-written", path, text, block };
+}
+
+/**
+ * Bring AGENTS.md to the canonical block, touching nothing outside the markers. A person's
+ * file gets the block APPENDED; a legacy fully generated file is converted, keeping every
+ * byte a person added around forge's region. Only `legacy-edited` needs a full rewrite, and
+ * only when `allowBackup` is set: the whole old file is first copied to a timestamped
+ * `AGENTS.md.forge-bak-<time>` (never one fixed name that a later run would overwrite).
+ * @param {ReturnType<typeof agentsMdStatus>} status
+ * @param {{allowBackup:boolean}} opts
+ * @returns {{action:string, note:string, backup?:string, warning?:string}}
+ */
+function writeAgentsBlock(status, { allowBackup }) {
+  const { state, path, block } = status;
+  const text = status.text ?? "";
+  const put = (next, note, extra = {}) => {
+    writeFileSync(path, next);
+    return { action: "written", note, ...extra };
+  };
+  // An older forge moved a hand-written AGENTS.md aside to this one fixed name.
+  const oldBak = existsSync(`${path}.forge-bak`)
+    ? "AGENTS.md.forge-bak (the hand-written file an older forge replaced) can now go back into AGENTS.md, outside the Forge block."
+    : "";
+  if (state === "in-sync") return { action: "unchanged", note: "Forge block current" };
+  if (state === "missing") return put(block, "new file (Forge block)");
+  if (state === "drifted" && status.found) {
+    const { start, end } = status.found;
+    return put(
+      text.slice(0, start) + block + text.slice(end),
+      "Forge block refreshed; text outside it untouched",
+    );
+  }
+  if (state === "hand-written") {
+    const sep = !text.trim()
+      ? ""
+      : text.endsWith("\n\n")
+        ? ""
+        : text.endsWith("\n")
+          ? "\n"
+          : "\n\n";
+    return put(
+      `${text.trim() ? text : ""}${sep}${block}`,
+      "Forge block appended; your text untouched",
+    );
+  }
+  if (state === "legacy" && status.legacy) {
+    const { before, after } = status.legacy;
+    return put(
+      `${before}${block}${after ? `\n${after}` : ""}`,
+      "converted to a Forge block (lossless)",
+      oldBak ? { warning: oldBak } : {},
+    );
+  }
+  if (state === "legacy-edited" && status.legacy) {
+    if (!allowBackup)
+      return { action: "skipped", note: "generated text was hand-edited — run `forge sync`" };
+    const backup = `${path}.forge-bak-${stamp()}`;
+    writeFileSync(backup, text);
+    const name = `AGENTS.md${backup.slice(path.length)}`;
+    return put(`${status.legacy.before}${block}`, "converted to a Forge block", {
+      backup,
+      warning: [
+        `AGENTS.md was fully generated but edited inside the generated text — converted to a Forge block; the previous file is saved as ${name}.`,
+        "Copy your edits back OUTSIDE the <!-- forge:begin --> / <!-- forge:end --> markers, where sync never touches them.",
+        oldBak,
+      ]
+        .filter(Boolean)
+        .join(" "),
+    });
+  }
+  return {
+    action: "skipped",
+    note: "damaged Forge markers",
+    warning:
+      "AGENTS.md has a forge:begin marker without forge:end (or the reverse) — nothing written; fix or remove the marker lines by hand",
+  };
+}
+
+/**
+ * Which tools sync emits for: an explicit list (init passes one) wins, then the repo config's
+ * `tools` key (recorded by `forge init`), else every tool — a repo that never chose keeps the
+ * emit-everything behaviour it always had. `tools: null` means every tool.
+ * @param {unknown} explicit
+ * @param {Record<string, any>} cfg
+ * @returns {{tools: string[]|null, unknown: string[]}}
+ */
+function resolveTools(explicit, cfg) {
+  if (explicit !== undefined && explicit !== null) return parseTools(explicit);
+  if (typeof cfg.tools === "string" || Array.isArray(cfg.tools)) return parseTools(cfg.tools);
+  return { tools: null, unknown: [] };
+}
+
+/**
+ * Compile the canonical source into AGENTS.md (forge's marked block only) and each selected
+ * tool's native config.
+ * @param {{targetRoot?: string, tools?: string|string[]|null}} [opts] `tools`: KNOWN_TOOLS keys
+ *   or "all"; omitted = the repo config's `tools`, else every tool.
+ */
+export function sync({ targetRoot = process.cwd(), tools } = {}) {
   // Inline portable memory + learned lessons so every AGENTS.md-reading tool shares them.
   const canonical = buildCanonical(targetRoot);
   const hash = shared.hashContent(canonical);
   const bytes = Buffer.byteLength(canonical);
+  const cfg = loadConfig(targetRoot);
+  const selection = resolveTools(tools, cfg);
+  const emits = (key) => selection.tools === null || selection.tools.includes(key);
 
   // The shared AGENTS.md — read directly by Codex, Cursor, Copilot, Windsurf, Zed, OpenClaw.
-  // If the repo already has a hand-written (unmanaged) AGENTS.md, never destroy it
-  // silently — back it up first so no rules are lost when adopting Forge.
+  // Forge owns only its marked block in it: a hand-written file keeps every line (the old
+  // behaviour replaced the whole file and parked the original in AGENTS.md.forge-bak).
   const agentsPath = join(targetRoot, "AGENTS.md");
-  const existingAgents = shared.readIfExists(agentsPath);
-  const backedUp = existingAgents !== null && !shared.isManaged(existingAgents);
-  if (backedUp) writeFileSync(`${agentsPath}.forge-bak`, existingAgents);
-  const agentsAction = shared.writeManaged(agentsPath, shared.mdHeader(hash), canonical);
+  const agents = writeAgentsBlock(agentsMdStatus(targetRoot, canonical), { allowBackup: true });
 
   const ctx = {
     targetRoot,
@@ -185,11 +325,12 @@ export function sync({ targetRoot = process.cwd() } = {}) {
     {
       tool: "shared source",
       target: "AGENTS.md",
-      action: agentsAction,
-      note: `${bytes} B`,
+      action: agents.action,
+      note: `${bytes} B · ${agents.note}`,
     },
   ];
   for (const mod of MODULES) {
+    if (!emits(rowToolKey(mod.tool))) continue;
     try {
       report.push(mod.emit(ctx));
     } catch (err) {
@@ -203,7 +344,7 @@ export function sync({ targetRoot = process.cwd() } = {}) {
   }
 
   // MCP servers — emit the FULL managed set (registry ∪ recorded integrations) into each
-  // tool's MCP config (real formats). Sharing managedMcpState with `integrations add`
+  // selected tool's MCP config (real formats). Sharing managedMcpState with `integrations add`
   // means sync can never drop a server that add installed, and vice versa (RA-03). A
   // corrupt repo config falls back to registry-only with a warning — never treated as
   // "no integrations installed, overwrite everything".
@@ -213,7 +354,8 @@ export function sync({ targetRoot = process.cwd() } = {}) {
     try {
       const { servers, owns, warning } = managedMcpState(targetRoot);
       if (warning) warnings.push(warning);
-      for (const row of emitMcp({ targetRoot, servers, owns })) report.push(row);
+      for (const row of emitMcp({ targetRoot, servers, owns, tools: selection.tools }))
+        report.push(row);
     } catch (err) {
       report.push({
         tool: "MCP",
@@ -225,7 +367,6 @@ export function sync({ targetRoot = process.cwd() } = {}) {
   }
   // Corrupt repo config: rules were built from defaults (fail-open), but say so in the
   // report instead of only on stderr — a typo'd config must not vanish silently (RA-15).
-  const cfg = loadConfig(targetRoot);
   if (cfg.corrupt)
     warnings.push(
       `${cfg.path} is not valid JSON — config ignored, default rules used (fix or delete it)`,
@@ -237,9 +378,10 @@ export function sync({ targetRoot = process.cwd() } = {}) {
     warnings.push(
       `${legacyRules.path} is not valid JSON — ignored, default rules used (fix or delete it)`,
     );
-  if (backedUp)
+  if (agents.warning) warnings.push(agents.warning);
+  if (selection.unknown.length)
     warnings.push(
-      "existing AGENTS.md was not Forge-managed — backed up to AGENTS.md.forge-bak; move any custom rules into source/rules.json or a per-repo .forge/rules.json",
+      `unknown tool(s) in the tool selection ignored: ${selection.unknown.join(", ")} (known: ${KNOWN_TOOLS.join(", ")})`,
     );
   if (bytes > SIZE_BUDGET_BYTES)
     warnings.push(
@@ -256,7 +398,11 @@ export function sync({ targetRoot = process.cwd() } = {}) {
     bytes,
     report,
     warnings,
-    backedUp,
+    // A backup is written only when a legacy file edited inside its generated text had to be
+    // rewritten in full; a hand-written AGENTS.md is never moved aside any more.
+    backedUp: Boolean(agents.backup),
+    backup: agents.backup ?? null,
+    tools: selection.tools,
     partial,
     status: partial ? "PARTIAL" : "OK",
   };
@@ -268,26 +414,42 @@ export function canonical(targetRoot = process.cwd()) {
 }
 
 /**
- * Re-run sync ONLY when the managed AGENTS.md no longer matches the canonical source.
+ * Refresh ONLY forge's block in AGENTS.md when it no longer matches the canonical source.
  * The Stop hook calls this, so lessons/facts learned in a session reach every
- * AGENTS.md-reading tool immediately — not whenever someone remembers `forge sync`
- * (nothing did before: doctor DETECTED drift but nothing repaired it).
- * Never adopts a repo: AGENTS.md must already exist AND be Forge-managed.
+ * AGENTS.md-reading tool immediately — not whenever someone remembers `forge sync`.
+ * It never adopts a repo (no block → no write), never touches text outside the markers,
+ * and never runs the full per-tool emit. The one other file it refreshes is Continue's
+ * rules copy of the same body, and only when that forge-owned file already exists.
+ * A legacy fully generated AGENTS.md is converted in place only when the conversion is
+ * provably lossless; one edited inside its generated text is left for `forge sync`.
  * Kill switch: FORGE_AUTOSYNC=0.
  * @returns {{synced: boolean, reason: string}}
  */
 export function autoSyncIfDrifted(targetRoot = process.cwd()) {
   if (process.env.FORGE_AUTOSYNC === "0") return { synced: false, reason: "disabled" };
-  const existing = shared.readIfExists(join(targetRoot, "AGENTS.md"));
-  if (existing === null || !shared.isManaged(existing))
-    return { synced: false, reason: "no managed AGENTS.md here" };
-  // Full-byte comparison against the exact content sync would write (RA-16): the embedded
-  // marker hash alone proves nothing — a hand-edited body with an intact marker must
-  // still count as drift. managedContent is the same helper writeManaged writes through,
-  // so the two paths cannot diverge again.
   const body = buildCanonical(targetRoot);
-  const expected = shared.managedContent(shared.mdHeader(shared.hashContent(body)), body);
-  if (existing === expected) return { synced: false, reason: "in sync" };
-  sync({ targetRoot });
-  return { synced: true, reason: "drifted — resynced" };
+  const status = agentsMdStatus(targetRoot, body);
+  switch (status.state) {
+    case "in-sync":
+      return { synced: false, reason: "in sync" };
+    case "missing":
+    case "hand-written":
+      return { synced: false, reason: "no managed AGENTS.md here" };
+    case "legacy-edited":
+      return {
+        synced: false,
+        reason:
+          "legacy AGENTS.md edited inside its generated text — run `forge sync` to convert it",
+      };
+    case "damaged":
+      return { synced: false, reason: "damaged Forge markers in AGENTS.md — fix them by hand" };
+  }
+  writeAgentsBlock(status, { allowBackup: false });
+  const continueRules = join(targetRoot, ".continue", "rules", "00-forge.md");
+  if (shared.isManaged(shared.readIfExists(continueRules)))
+    shared.writeManaged(continueRules, shared.mdHeader(shared.hashContent(body)), body);
+  return {
+    synced: true,
+    reason: status.state === "legacy" ? "converted to a Forge block" : "drifted — block refreshed",
+  };
 }
diff --git a/test/agents_block.test.js b/test/agents_block.test.js
new file mode 100644
index 00000000..96aefe3f
--- /dev/null
+++ b/test/agents_block.test.js
@@ -0,0 +1,267 @@
+// AGENTS.md is shared with people: forge owns only the block between
+// <!-- forge:begin --> and <!-- forge:end -->. These tests pin the contract for every path
+// that writes AGENTS.md (sync, init, the Stop-hook auto-sync, doctor --fix): a person's text
+// is never rewritten, moved aside or reverted, the block itself is still repaired, and a
+// repo whose AGENTS.md is fully generated today converts without losing a byte.
+import assert from "node:assert/strict";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { doctor } from "../src/doctor.js";
+import {
+  BLOCK_BEGIN,
+  BLOCK_END,
+  findManagedBlock,
+  hashContent,
+  hasManagedBlock,
+  managedBlock,
+  managedContent,
+  mdHeader,
+  splitLegacyManaged,
+} from "../src/emit/_shared.js";
+import { init } from "../src/init.js";
+import { agentsMdStatus, assemble, autoSyncIfDrifted, canonical, sync } from "../src/sync.js";
+
+const fixture = () => mkdtempSync(join(tmpdir(), "forge-block-"));
+const agentsOf = (root) => readFileSync(join(root, "AGENTS.md"), "utf8");
+const HAND =
+  "# HostLelo agents\n\n- Lint: `npm run lint`\n- Never call the WHMCS API from the client.\n";
+
+/** The file the pre-block forge wrote: the generated header, then the whole body. */
+const legacyFile = (body) => managedContent(mdHeader(hashContent(body)), body);
+
+/** Change the canonical source (a per-repo rule) so the block goes stale. */
+function addRule(root, rule) {
+  mkdirSync(join(root, ".forge"), { recursive: true });
+  writeFileSync(
+    join(root, ".forge", "rules.json"),
+    JSON.stringify({ sections: [{ title: "Repo", rules: [rule] }] }),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// The block helpers
+// ---------------------------------------------------------------------------
+
+test("findManagedBlock locates a whole-line block and flags a half-open one as damaged", () => {
+  const block = managedBlock(mdHeader("abcdefabcdef"), "# body\n");
+  assert.ok(block.startsWith(`${BLOCK_BEGIN}\n`) && block.endsWith(`${BLOCK_END}\n`));
+  const text = `mine above\n\n${block}mine below\n`;
+  const found = findManagedBlock(text);
+  assert.equal(found?.damaged, false);
+  if (found?.damaged !== false) return;
+  assert.equal(text.slice(found.start, found.end), block, "extent is exactly the block");
+  assert.equal(hasManagedBlock(text), true);
+
+  assert.equal(findManagedBlock("no markers here\n"), null);
+  assert.deepEqual(findManagedBlock(`${BLOCK_BEGIN}\nno end\n`), { damaged: true });
+  assert.deepEqual(findManagedBlock(`no begin\n${BLOCK_END}\n`), { damaged: true });
+  assert.deepEqual(findManagedBlock(`${BLOCK_END}\n${BLOCK_BEGIN}\n`), { damaged: true });
+  assert.equal(hasManagedBlock(`${BLOCK_BEGIN}\nno end\n`), false);
+  // A marker quoted inside prose is not a block boundary.
+  assert.equal(findManagedBlock(`forge writes \`${BLOCK_BEGIN}\` then its rules\n`), null);
+});
+
+test("splitLegacyManaged separates a person's text from a fully generated body by its hash", () => {
+  const body = assemble({ title: "t", sections: [{ title: "Workflow", rules: ["do X"] }] });
+  const pristine = legacyFile(body);
+  assert.deepEqual(splitLegacyManaged(pristine), { lossless: true, before: "", after: "" });
+
+  const withNotes = `Notes on top\n${pristine}## My notes\n- keep me\n`;
+  assert.deepEqual(splitLegacyManaged(withNotes), {
+    lossless: true,
+    before: "Notes on top\n",
+    after: "## My notes\n- keep me\n",
+  });
+
+  const edited = pristine.replace("- do X", "- do X, but carefully");
+  assert.equal(splitLegacyManaged(edited)?.lossless, false, "edit inside the generated text");
+  assert.equal(splitLegacyManaged(HAND), null, "hand-written file is not legacy");
+  assert.equal(splitLegacyManaged(managedBlock(mdHeader(hashContent(body)), body)), null);
+});
+
+// ---------------------------------------------------------------------------
+// A hand-written AGENTS.md is preserved by init, sync and auto-sync
+// ---------------------------------------------------------------------------
+
+test("sync appends the block to a hand-written AGENTS.md and never rewrites the person's text", () => {
+  const root = fixture();
+  writeFileSync(join(root, "AGENTS.md"), HAND);
+  const r = sync({ targetRoot: root });
+  const after = agentsOf(root);
+  assert.ok(after.startsWith(HAND), "hand-written text first, byte for byte");
+  assert.equal(after.slice(HAND.length), `\n${agentsMdStatus(root).block}`);
+  assert.equal(r.backedUp, false);
+  assert.ok(!readdirSync(root).some((f) => f.includes("forge-bak")), "no backup file at all");
+  assert.equal(agentsMdStatus(root).state, "in-sync");
+});
+
+test("init preserves a hand-written AGENTS.md", () => {
+  const root = fixture();
+  writeFileSync(join(root, "AGENTS.md"), HAND);
+  init({ targetRoot: root, noSettings: true });
+  assert.ok(agentsOf(root).startsWith(HAND), "init kept the hand-written file");
+  assert.ok(hasManagedBlock(agentsOf(root)), "and added forge's block");
+});
+
+test("auto-sync never adopts a hand-written AGENTS.md (no block → no write)", () => {
+  const root = fixture();
+  writeFileSync(join(root, "AGENTS.md"), HAND);
+  assert.deepEqual(autoSyncIfDrifted(root), {
+    synced: false,
+    reason: "no managed AGENTS.md here",
+  });
+  assert.equal(agentsOf(root), HAND, "byte-identical");
+});
+
+test("a human edit OUTSIDE the block survives auto-sync; the stale block is refreshed", () => {
+  const root = fixture();
+  sync({ targetRoot: root });
+  const block = agentsOf(root);
+  const edited = `# Repo notes\nRun \`npm run e2e\` against port 3100.\n\n${block}\n## Deploy\n- Vercel only.\n`;
+  writeFileSync(join(root, "AGENTS.md"), edited);
+  assert.equal(autoSyncIfDrifted(root).synced, false, "an edit outside the block is not drift");
+  assert.equal(agentsOf(root), edited);
+
+  addRule(root, "always frob the widget");
+  const r = autoSyncIfDrifted(root);
+  assert.equal(r.synced, true);
+  const after = agentsOf(root);
+  assert.ok(after.startsWith("# Repo notes\nRun `npm run e2e` against port 3100.\n\n"));
+  assert.ok(after.endsWith("\n## Deploy\n- Vercel only.\n"), "text below the block kept");
+  assert.match(after, /always frob the widget/, "block now carries the new rule");
+  assert.equal(autoSyncIfDrifted(root).synced, false, "second pass: in sync");
+});
+
+test("drift INSIDE the block is repaired by auto-sync without touching the text around it", () => {
+  const root = fixture();
+  writeFileSync(join(root, "AGENTS.md"), HAND);
+  sync({ targetRoot: root });
+  const good = agentsOf(root);
+  writeFileSync(join(root, "AGENTS.md"), good.replace("## Workflow", "## Workflow\n- SNEAKY"));
+  assert.equal(agentsMdStatus(root).state, "drifted");
+  assert.equal(autoSyncIfDrifted(root).synced, true);
+  assert.equal(agentsOf(root), good, "block restored, hand-written text untouched");
+});
+
+test("auto-sync refreshes Continue's forge-owned rules copy only when it already exists", () => {
+  const root = fixture();
+  sync({ targetRoot: root });
+  const rules = join(root, ".continue", "rules", "00-forge.md");
+  assert.ok(existsSync(rules));
+  addRule(root, "continue sees this too");
+  autoSyncIfDrifted(root);
+  assert.match(readFileSync(rules, "utf8"), /continue sees this too/);
+
+  const bare = fixture();
+  sync({ targetRoot: bare, tools: ["claude"] });
+  addRule(bare, "x");
+  autoSyncIfDrifted(bare);
+  assert.ok(!existsSync(join(bare, ".continue")), "auto-sync never creates tool config");
+});
+
+test("damaged markers: sync and auto-sync leave the file alone and say why", () => {
+  const root = fixture();
+  const broken = `${HAND}\n${BLOCK_BEGIN}\n# half a block, end marker deleted\n`;
+  writeFileSync(join(root, "AGENTS.md"), broken);
+  const r = sync({ targetRoot: root });
+  assert.equal(r.report.find((row) => row.target === "AGENTS.md").action, "skipped");
+  assert.ok(r.warnings.some((w) => /forge:begin marker without forge:end/.test(w)));
+  assert.equal(autoSyncIfDrifted(root).synced, false);
+  assert.equal(agentsOf(root), broken, "not a byte changed");
+});
+
+// ---------------------------------------------------------------------------
+// Backwards compatibility: an AGENTS.md that forge fully generated before blocks existed
+// ---------------------------------------------------------------------------
+
+test("a legacy fully generated AGENTS.md converts to a block, keeping text a person added", () => {
+  const root = fixture();
+  const notes = "## Team notes\n- ship on Fridays? never.\n";
+  writeFileSync(join(root, "AGENTS.md"), `${legacyFile(canonical(root))}${notes}`);
+  assert.equal(agentsMdStatus(root).state, "legacy");
+  const r = sync({ targetRoot: root });
+  const after = agentsOf(root);
+  assert.equal(after, `${agentsMdStatus(root).block}\n${notes}`, "block, then the notes");
+  assert.equal(r.backedUp, false, "lossless: nothing to back up");
+  assert.ok(!readdirSync(root).some((f) => f.includes("forge-bak")));
+});
+
+test("a stale legacy file converts losslessly on auto-sync too (old rules replaced)", () => {
+  const root = fixture();
+  const old = assemble({ title: "old", sections: [{ title: "Old", rules: ["stale rule"] }] });
+  writeFileSync(join(root, "AGENTS.md"), legacyFile(old));
+  const r = autoSyncIfDrifted(root);
+  assert.deepEqual(r, { synced: true, reason: "converted to a Forge block" });
+  assert.equal(agentsOf(root), agentsMdStatus(root).block);
+  assert.doesNotMatch(agentsOf(root), /stale rule/);
+});
+
+test("a legacy file edited INSIDE the generated text: auto-sync refuses, sync backs up then converts", () => {
+  const root = fixture();
+  const edited = legacyFile(canonical(root)).replace(
+    "## Workflow",
+    "## Workflow\n- my edit in the generated text",
+  );
+  writeFileSync(join(root, "AGENTS.md"), edited);
+  assert.equal(agentsMdStatus(root).state, "legacy-edited");
+  const auto = autoSyncIfDrifted(root);
+  assert.equal(auto.synced, false);
+  assert.match(auto.reason, /run `forge sync`/);
+  assert.equal(agentsOf(root), edited, "auto-sync wrote nothing");
+
+  writeFileSync(join(root, "AGENTS.md.forge-bak"), HAND); // what an older forge left behind
+  const r = sync({ targetRoot: root });
+  assert.equal(r.backedUp, true);
+  assert.match(r.backup, /AGENTS\.md\.forge-bak-\d{4}-\d\d-\d\dT/, "timestamped, never one name");
+  assert.equal(readFileSync(r.backup, "utf8"), edited, "the whole previous file is kept");
+  assert.equal(agentsOf(root), agentsMdStatus(root).block);
+  const warning = r.warnings.find((w) => w.includes("forge-bak-"));
+  assert.ok(warning, "the backup is named in a warning");
+  assert.match(warning, /AGENTS\.md\.forge-bak \(the hand-written file an older forge replaced\)/);
+  assert.equal(readFileSync(join(root, "AGENTS.md.forge-bak"), "utf8"), HAND, "old backup kept");
+});
+
+// ---------------------------------------------------------------------------
+// doctor speaks the same states
+// ---------------------------------------------------------------------------
+
+test("doctor: hand-written AGENTS.md is 'not managed' and --fix appends the block, keeping it", () => {
+  const root = fixture();
+  const settingsPath = join(fixture(), "settings.json");
+  writeFileSync(join(root, "AGENTS.md"), HAND);
+  const row = doctor({ targetRoot: root, settingsPath }).results.find(
+    (r) => r.label === "AGENTS.md",
+  );
+  assert.equal(row.status, "warn");
+  assert.match(row.note, /hand-written AGENTS\.md \(no Forge block\)/);
+  assert.match(row.note, /leaves your text as is/);
+  doctor({ targetRoot: root, settingsPath, fix: true });
+  assert.ok(agentsOf(root).startsWith(HAND));
+  const again = doctor({ targetRoot: root, settingsPath }).results.find(
+    (r) => r.label === "AGENTS.md",
+  );
+  assert.deepEqual([again.status, again.note], ["ok", "in sync (Forge block)"]);
+});
+
+test("doctor: a current legacy file is ok; a damaged block warns with no automatic fix", () => {
+  const root = fixture();
+  writeFileSync(join(root, "AGENTS.md"), legacyFile(canonical(root)));
+  const legacy = doctor({ targetRoot: root }).results.find((r) => r.label === "AGENTS.md");
+  assert.equal(legacy.status, "ok");
+  assert.match(legacy.note, /pre-block format/);
+
+  writeFileSync(join(root, "AGENTS.md"), `${BLOCK_BEGIN}\nno end\n`);
+  const damaged = doctor({ targetRoot: root }).results.find((r) => r.label === "AGENTS.md");
+  assert.equal(damaged.status, "warn");
+  assert.match(damaged.note, /damaged Forge markers/);
+  assert.equal(damaged.fix, undefined, "doctor --fix must not guess where forge's text ends");
+});
diff --git a/test/init.test.js b/test/init.test.js
index 089a279e..bd480f39 100644
--- a/test/init.test.js
+++ b/test/init.test.js
@@ -32,17 +32,21 @@ import { toPosix } from "../src/util.js";
  *  as-is. Tests assert on this so they are form-agnostic. */
 const effectiveCmd = (h) => (Array.isArray(h.args) ? [h.command, ...h.args].join(" ") : h.command);
 
-test("init emits the shared config for a fresh repo in one call", () => {
+test("init emits the shared config for a fresh repo in one call — Claude + AGENTS.md only", () => {
   const root = mkdtempSync(join(tmpdir(), "forge-init-"));
   // Hermeticity: pin settingsPath under the temp root so the hook-guard merge never
   // touches the developer's real ~/.claude/settings.json (mergeSettings defaults there).
-  init({
+  const r = init({
     targetRoot: root,
     settingsPath: join(root, ".claude", "settings.json"),
   });
   assert.ok(existsSync(join(root, "AGENTS.md")), "AGENTS.md");
   assert.ok(existsSync(join(root, "CLAUDE.md")), "CLAUDE.md");
-  assert.ok(existsSync(join(root, ".aider.conf.yml")), ".aider.conf.yml");
+  assert.ok(existsSync(join(root, ".mcp.json")), ".mcp.json (Claude Code MCP)");
+  // A fresh repo shows no other tool, so none of their config appears.
+  for (const other of [".aider.conf.yml", ".cursor", ".gemini", ".codex", ".continue", ".zed"])
+    assert.ok(!existsSync(join(root, other)), `${other} not emitted for an unused tool`);
+  assert.deepEqual(r.tools, { tools: ["claude"], source: "detected" });
 });
 
 test("init gitignores the per-session hook logs under .forge/sessions (B5)", () => {
diff --git a/test/init_tools.test.js b/test/init_tools.test.js
new file mode 100644
index 00000000..b4065828
--- /dev/null
+++ b/test/init_tools.test.js
@@ -0,0 +1,225 @@
+// forge init emits config only for the tools a repo uses — Claude + AGENTS.md by default,
+// plus every tool with a sign of life on disk, or an explicit --tools list — and records the
+// choice so later syncs emit the same set. It used to create .aider.conf.yml, .codex/,
+// .continue/, .cursor/, .gemini/, .openclaw/, .roo/, .vscode/ and .zed/ in every repo.
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { emitMcp } from "../src/emit/mcp.js";
+import { init, resolveInitTools } from "../src/init.js";
+import { addIntegration } from "../src/integrations.js";
+import {
+  clearRepoConfig,
+  detectTools,
+  KNOWN_TOOLS,
+  parseTools,
+  readForgeConfig,
+  writeForgeConfig,
+} from "../src/repo_config.js";
+import { sync } from "../src/sync.js";
+
+const fixture = () => mkdtempSync(join(tmpdir(), "forge-init-tools-"));
+const CLI = fileURLToPath(new URL("../src/cli.js", import.meta.url));
+const OTHER_TOOL_PATHS = [
+  ".aider.conf.yml",
+  ".codex",
+  ".continue",
+  ".cursor",
+  ".gemini",
+  ".openclaw",
+  ".roo",
+  ".vscode",
+  ".zed",
+];
+
+test("detectTools reads each tool's on-disk signs, including legacy rules files", () => {
+  assert.deepEqual(detectTools(fixture()), []);
+  const root = fixture();
+  mkdirSync(join(root, ".cursor"));
+  mkdirSync(join(root, ".github"));
+  writeFileSync(join(root, ".github", "copilot-instructions.md"), "be nice\n");
+  writeFileSync(join(root, ".windsurfrules"), "x\n");
+  writeFileSync(join(root, "CLAUDE.md"), "# mine\n");
+  assert.deepEqual(detectTools(root), ["claude", "cursor", "vscode", "windsurf"]);
+});
+
+test("parseTools normalises lists, aliases and `all`; unknown names are reported", () => {
+  assert.deepEqual(parseTools("cursor, Claude"), { tools: ["claude", "cursor"], unknown: [] });
+  assert.deepEqual(parseTools(["copilot", "devin"]), {
+    tools: ["vscode", "windsurf"],
+    unknown: [],
+  });
+  assert.deepEqual(parseTools("all"), { tools: null, unknown: [] });
+  assert.deepEqual(parseTools("claude,nope,nope"), { tools: ["claude"], unknown: ["nope"] });
+  assert.deepEqual(parseTools(42), { tools: [], unknown: [] });
+});
+
+test("resolveInitTools: --tools wins, then the recorded set, else Claude + detected", () => {
+  const root = fixture();
+  mkdirSync(join(root, ".codex"));
+  assert.deepEqual(resolveInitTools(root), { tools: ["claude", "codex"], source: "detected" });
+  assert.deepEqual(resolveInitTools(root, "cursor"), { tools: ["cursor"], source: "--tools" });
+  assert.deepEqual(resolveInitTools(root, "all"), { tools: null, source: "--tools" });
+  assert.match(resolveInitTools(root, "claude,bogus").error, /unknown tool\(s\).*bogus/);
+  assert.match(resolveInitTools(root, "").error, /at least one tool/);
+  writeForgeConfig(root, (cfg) => ({ ...cfg, tools: ["gemini"] }));
+  assert.deepEqual(resolveInitTools(root), { tools: ["gemini"], source: "config" });
+});
+
+test("init on a fresh repo emits Claude + AGENTS.md only and records the choice", () => {
+  const root = fixture();
+  const r = init({ targetRoot: root, noSettings: true });
+  assert.deepEqual(r.tools, { tools: ["claude"], source: "detected" });
+  for (const p of ["AGENTS.md", "CLAUDE.md", ".mcp.json"]) assert.ok(existsSync(join(root, p)), p);
+  for (const p of OTHER_TOOL_PATHS) assert.ok(!existsSync(join(root, p)), `${p} not created`);
+  assert.deepEqual(readForgeConfig(root).tools, ["claude"]);
+  // A later plain sync (and doctor --fix, and `forge tools`) honours the recorded set.
+  sync({ targetRoot: root });
+  for (const p of OTHER_TOOL_PATHS) assert.ok(!existsSync(join(root, p)), `${p} still absent`);
+});
+
+test("init emits for tools the repo already uses (.cursor/, copilot-instructions.md)", () => {
+  const root = fixture();
+  mkdirSync(join(root, ".cursor"));
+  mkdirSync(join(root, ".github"));
+  writeFileSync(join(root, ".github", "copilot-instructions.md"), "x\n");
+  const r = init({ targetRoot: root, noSettings: true });
+  assert.deepEqual(r.tools.tools, ["claude", "cursor", "vscode"]);
+  assert.ok(existsSync(join(root, ".cursor", "mcp.json")), "Cursor MCP");
+  assert.ok(existsSync(join(root, ".vscode", "mcp.json")), "VS Code / Copilot MCP");
+  for (const p of [".aider.conf.yml", ".gemini", ".codex", ".continue", ".roo", ".zed"])
+    assert.ok(!existsSync(join(root, p)), `${p} not created`);
+});
+
+test("init --tools all emits every tool (the old behaviour, on request)", () => {
+  const root = fixture();
+  const r = init({ targetRoot: root, noSettings: true, tools: "all" });
+  assert.equal(r.tools.tools, null);
+  for (const p of OTHER_TOOL_PATHS) assert.ok(existsSync(join(root, p)), `${p} emitted`);
+  assert.equal(readForgeConfig(root).tools, "all");
+});
+
+test("init with an unknown --tools name aborts before touching the repo", () => {
+  const root = fixture();
+  const r = init({ targetRoot: root, noSettings: true, tools: "claude,notatool" });
+  assert.equal(r.aborted, true);
+  assert.match(r.tools.error, /notatool/);
+  assert.deepEqual(readdirSync(root), [], "zero side effects");
+});
+
+test("re-running init keeps the recorded set and does not churn config backups", () => {
+  const root = fixture();
+  init({ targetRoot: root, noSettings: true, tools: "claude,gemini" });
+  mkdirSync(join(root, ".roo")); // appears later; the recorded choice still wins
+  const again = init({ targetRoot: root, noSettings: true });
+  assert.deepEqual(again.tools, { tools: ["claude", "gemini"], source: "config" });
+  assert.ok(!existsSync(join(root, ".roo", "mcp.json")), "not re-detected over the choice");
+  const baks = readdirSync(join(root, ".forge")).filter((f) => f.includes("forge-bak"));
+  assert.deepEqual(baks, [], "config written once, not rewritten (and backed up) every run");
+});
+
+test("init --profile records profile and tools in ONE config write (no stray backup)", () => {
+  const root = fixture();
+  init({ targetRoot: root, noSettings: true, profile: "minimal" });
+  assert.deepEqual(readForgeConfig(root), { profile: "minimal", tools: ["claude"] });
+  const baks = readdirSync(join(root, ".forge")).filter((f) => f.includes("forge-bak"));
+  assert.deepEqual(baks, []);
+});
+
+test("sync without a recorded selection still emits every tool (back-compat)", () => {
+  const root = fixture();
+  const r = sync({ targetRoot: root });
+  assert.equal(r.tools, null);
+  assert.ok(existsSync(join(root, ".aider.conf.yml")));
+  assert.ok(existsSync(join(root, ".cursor", "mcp.json")));
+});
+
+test("sync warns about unknown names in a hand-edited `tools` config instead of failing", () => {
+  const root = fixture();
+  writeForgeConfig(root, (cfg) => ({ ...cfg, tools: ["claude", "emacs"] }));
+  const r = sync({ targetRoot: root });
+  assert.deepEqual(r.tools, ["claude"]);
+  assert.ok(r.warnings.some((w) => /unknown tool\(s\).*emacs/.test(w)));
+});
+
+test("emitMcp writes only the selected tools' MCP targets", () => {
+  const root = fixture();
+  const servers = { "forge-cortex": { command: "forge", args: ["mcp"] } };
+  const rows = emitMcp({ targetRoot: root, servers, tools: ["claude", "codex"] });
+  assert.deepEqual(
+    rows.map((r) => r.target),
+    [".mcp.json", ".codex/config.toml"],
+  );
+  assert.deepEqual(readdirSync(root).sort(), [".codex", ".mcp.json"]);
+  assert.ok(KNOWN_TOOLS.length > 2, "every other known tool was skipped");
+});
+
+test("integrations add honours the recorded tool set (no config for unused tools)", () => {
+  const root = fixture();
+  init({ targetRoot: root, noSettings: true });
+  const res = addIntegration("context7", { targetRoot: root });
+  assert.equal(res.ok, true, res.reason);
+  const mcp = JSON.parse(readFileSync(join(root, ".mcp.json"), "utf8"));
+  assert.ok(mcp.mcpServers.context7, "written for Claude Code");
+  for (const p of OTHER_TOOL_PATHS) assert.ok(!existsSync(join(root, p)), `${p} not created`);
+});
+
+test("`forge tools --reset` keeps the recorded emit set (clearRepoConfig drops primaryTool only)", () => {
+  const root = fixture();
+  writeForgeConfig(root, (cfg) => ({ ...cfg, primaryTool: "claude", tools: ["claude"] }));
+  assert.equal(clearRepoConfig(root).cleared, true);
+  assert.deepEqual(readForgeConfig(root), { tools: ["claude"] });
+});
+
+test("notes a person adds under the generated CLAUDE.md header survive a later sync", () => {
+  const root = fixture();
+  sync({ targetRoot: root, tools: ["claude"] });
+  const claudeMd = join(root, "CLAUDE.md");
+  const notes = "\n## Claude-only\n- prefer small diffs\n";
+  writeFileSync(claudeMd, readFileSync(claudeMd, "utf8") + notes);
+  mkdirSync(join(root, ".forge"), { recursive: true });
+  writeFileSync(
+    join(root, ".forge", "rules.json"),
+    JSON.stringify({ sections: [{ title: "New", rules: ["changes the hash"] }] }),
+  );
+  const r = sync({ targetRoot: root, tools: ["claude"] });
+  const after = readFileSync(claudeMd, "utf8");
+  assert.ok(after.endsWith(notes), "the person's notes are still there");
+  assert.match(after, new RegExp(`forge:sync:${r.hash}`), "marker refreshed in place");
+  assert.equal((after.match(/@AGENTS\.md/g) || []).length, 1);
+});
+
+test("CLI: `forge init --tools` prints the selection; a bad name exits 1 with nothing written", () => {
+  const env = { ...process.env, FORGE_NO_HINT: "1" };
+  const root = fixture();
+  const ok = spawnSync("node", [CLI, "init", "--no-settings", "--tools", "claude,cursor"], {
+    cwd: root,
+    encoding: "utf8",
+    env,
+  });
+  assert.equal(ok.status, 0, ok.stderr);
+  assert.match(ok.stdout, /tools: {4}claude, cursor \(from --tools\)/);
+  assert.match(ok.stdout, /forge owns only the block between <!-- forge:begin -->/);
+  assert.ok(existsSync(join(root, ".cursor", "mcp.json")));
+
+  const bad = fixture();
+  const r = spawnSync("node", [CLI, "init", "--no-settings", "--tools=nope"], {
+    cwd: bad,
+    encoding: "utf8",
+    env,
+  });
+  assert.equal(r.status, 1);
+  assert.match(r.stderr, /unknown tool\(s\) for --tools: nope/);
+  assert.deepEqual(readdirSync(bad), []);
+});
diff --git a/test/regressions.test.js b/test/regressions.test.js
index e86665a5..ff81af7f 100644
--- a/test/regressions.test.js
+++ b/test/regressions.test.js
@@ -10,19 +10,22 @@ import { fakeAnthropic, fakeGoogle, fakeJwt, fakeSlack } from "./_fixtures.js";
 const dir = () => mkdtempSync(join(tmpdir(), "forge-reg-"));
 
 // Regression (verifier finding #1): sync must NOT silently destroy a hand-written AGENTS.md.
-test("sync backs up a pre-existing unmanaged AGENTS.md instead of clobbering it", () => {
+// It used to replace the file and park the original in AGENTS.md.forge-bak, which no agent
+// reads; now it appends forge's block and leaves every hand-written line where it was.
+test("sync keeps a pre-existing hand-written AGENTS.md in place and appends the Forge block", () => {
   const root = dir();
-  writeFileSync(join(root, "AGENTS.md"), "# my hand-written rules\n- do the thing\n");
+  const mine = "# my hand-written rules\n- do the thing\n";
+  writeFileSync(join(root, "AGENTS.md"), mine);
   const res = sync({ targetRoot: root });
-  assert.equal(res.backedUp, true);
-  assert.ok(existsSync(join(root, "AGENTS.md.forge-bak")), "backup exists");
-  assert.match(readFileSync(join(root, "AGENTS.md.forge-bak"), "utf8"), /hand-written rules/);
-  assert.ok(
-    res.warnings.some((w) => /backed up/.test(w)),
-    "warns about the backup",
-  );
-  // second run: AGENTS.md is now Forge-managed, so no re-backup
-  assert.equal(sync({ targetRoot: root }).backedUp, false);
+  assert.equal(res.backedUp, false, "nothing to back up: the file is not replaced");
+  assert.ok(!existsSync(join(root, "AGENTS.md.forge-bak")), "no backup file");
+  const after = readFileSync(join(root, "AGENTS.md"), "utf8");
+  assert.ok(after.startsWith(mine), "hand-written text kept verbatim, first");
+  assert.match(after, /<!-- forge:begin -->[\s\S]*## Workflow[\s\S]*<!-- forge:end -->\n$/);
+  // second run: only the block is compared, and it is current
+  const again = sync({ targetRoot: root });
+  assert.equal(again.report.find((r) => r.target === "AGENTS.md").action, "unchanged");
+  assert.equal(readFileSync(join(root, "AGENTS.md"), "utf8"), after);
 });
 
 // Regression (verifier finding #2): secret detection catches common real key formats.
diff --git a/test/sync.test.js b/test/sync.test.js
index 4614286c..de689fcd 100644
--- a/test/sync.test.js
+++ b/test/sync.test.js
@@ -214,10 +214,17 @@ test("RA-16: a hand-edited AGENTS.md body with an INTACT marker still counts as
   sync({ targetRoot: root });
   const p = join(root, "AGENTS.md");
   const lines = readFileSync(p, "utf8").split("\n");
-  // Keep line 0 (the GENERATED header with the forge:sync:<hash> marker), tamper the body.
+  // Keep the begin marker and the GENERATED header (forge:sync:<hash>) intact; tamper the
+  // body's title line right below them, inside the block.
+  const header = lines.findIndex((l) => l.includes("forge:sync:"));
+  assert.equal(header, 1, "the header sits right under <!-- forge:begin -->");
   writeFileSync(
     p,
-    [lines[0], "# AGENTS.md — quietly rewritten by hand", ...lines.slice(2)].join("\n"),
+    [
+      ...lines.slice(0, header + 1),
+      "# AGENTS.md — quietly rewritten by hand",
+      ...lines.slice(header + 2),
+    ].join("\n"),
   );
   const r = autoSyncIfDrifted(root);
   assert.equal(r.synced, true, "marker-only agreement must not pass as in-sync");

From 2aae4445030748e2a48629985dccbca68d19de13 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 23 Sep 2026 22:21:57 +0000
Subject: [PATCH 2/3] fix(sync): keep the AGENTS.md block convergent,
 size-check the real file, report a stranded .forge-bak

Review follow-ups to the managed AGENTS.md block:

- A body line that reads exactly like `<!-- forge:end -->` (a multi-line
  rule, brain fact or lesson) ended the block early, so every sync and
  every Stop-hook auto-sync saw drift and left another stale tail behind;
  the file grew on each run. managedBlock now indents such lines one
  space (same Markdown rendering, no longer a whole-line marker).
- Codex's 32 KiB and Windsurf's ~12k-char checks measured only the
  canonical body. AGENTS.md is now the person's text plus the block, and
  those tools cut the end of the file, where the block sits. The rows and
  a new sync warning measure the file on disk (a 37,992 B file was
  reported as 6,476 B before).
- AGENTS.md.forge-bak (the hand-written file an older forge replaced) was
  mentioned only when an explicit sync converted a legacy file. The Stop
  hook usually converts first and its result is discarded, so the rules
  stayed invisible. strandedAgentsBackup() now drives a warning in both
  sync and doctor for as long as the backup holds text AGENTS.md lacks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UUhB8JaPayd43w37dxiXrW
Signed-off-by: Claude <noreply@anthropic.com>
---
 ARCHITECTURE.md                       |   6 +-
 CHANGELOG.md                          |   8 ++
 docs/GUIDE.md                         |   2 +-
 mintlify/cli/config.mdx               |   3 +-
 mintlify/cli/core.mdx                 |   7 ++
 mintlify/concepts/config-compiler.mdx |   3 +-
 src/doctor.js                         |   7 +-
 src/emit/_shared.js                   |   8 +-
 src/sync.js                           |  41 +++++++---
 test/agents_block.test.js             | 104 +++++++++++++++++++++++++-
 10 files changed, 170 insertions(+), 19 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 3fc0e477..939909b5 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -526,7 +526,11 @@ file and afterwards compares and rewrites only the block; the Stop-hook auto-syn
 same and never adopts a file without one. A pre-block, fully generated `AGENTS.md` is
 recognised by the hash in its header and converted to a block keeping any text a person
 added around it; only one edited inside its generated text needs a full rewrite, which
-`forge sync` does after saving a timestamped `AGENTS.md.forge-bak-<time>`.
+`forge sync` does after saving a timestamped `AGENTS.md.forge-bak-<time>`. A body line that
+reads exactly like a marker (a multi-line rule, fact or lesson) is indented one space so it
+cannot end the block early. The Codex/Windsurf size checks measure the whole file, the
+person's text included. Sync and doctor warn while an `AGENTS.md.forge-bak` from an older
+forge still holds text AGENTS.md lacks, since no agent reads it.
 
 ### OpenClaw: what is automatic and what is not
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 070e32b8..3b41e11b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,14 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   old file as a timestamped `AGENTS.md.forge-bak-<time>` first, instead of overwriting one
   fixed `.forge-bak`. `forge doctor` reports a hand-written file as "no Forge block" and its
   fix appends the block.
+- **Rules an older version moved to `AGENTS.md.forge-bak` are no longer forgotten.** No agent
+  reads that file, so `forge sync` and `forge doctor` now warn for as long as it holds text
+  that `AGENTS.md` lacks, even when the Stop hook did the conversion out of sight.
+- **Size checks cover the whole `AGENTS.md`.** The Codex (32 KiB) and Windsurf (~12k
+  characters) checks now count your text as well as Forge's block, and sync warns when your
+  text pushes the file over budget, since those tools drop the end of the file first. A rule,
+  fact or lesson containing a line that reads exactly like a block marker can no longer end
+  the block early.
 - **Notes added under a generated `CLAUDE.md` header survive later syncs.** Sync refreshes
   only the marker line instead of regenerating the file.
 
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
index 7d400de9..62d496dd 100644
--- a/docs/GUIDE.md
+++ b/docs/GUIDE.md
@@ -1303,7 +1303,7 @@ Plain `forge cost` remains the per-day spend view via `ccusage`.
 | Command                          | Answers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `forge init`                     | Emit native config for the tools this repo uses — Claude + detected ones, or `--tools <list|all>` (recorded for later syncs). In `AGENTS.md` forge owns only its `<!-- forge:begin/end -->` block; a hand-written file keeps every line.                                                                                                                                                                                                                                                                                                                                                                |
-| `forge sync`                     | Recompile `source/` → each selected tool's files (idempotent); rewrites only forge's block in `AGENTS.md`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `forge sync`                     | Recompile `source/` → each selected tool's files (idempotent); rewrites only forge's block in `AGENTS.md`. Size checks measure the whole `AGENTS.md`; warns while an older `AGENTS.md.forge-bak` holds rules no agent reads.                                                                                                                                                                                                                                                                                                                                                                            |
 | `forge doctor`                   | Health check: layers, install, drift, cortex. `forge doctor --fix` auto-repairs the safely fixable findings (missing settings hooks/permissions, ledger union-merge rule, stale `AGENTS.md`, non-executable guards) by reusing the same idempotent functions `forge init`/`forge sync` use, then re-checks.                                                                                                                                                                                                                                                                                             |
 | `forge docs check`               | Docs↔code drift: commands, env vars, MCP tools, CHANGELOG, and the Mintlify site (`mintlify/`) reconciled against the code (CI-gated on the forge repo itself).                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `forge docs sync`                | Diff-driven stale-docs sweep: UPDATED / STALE (file:line hits) / VERIFIED-UNAFFECTED per artifact (see the full section above).                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
diff --git a/mintlify/cli/config.mdx b/mintlify/cli/config.mdx
index 1de8bcd4..ada34a9c 100644
--- a/mintlify/cli/config.mdx
+++ b/mintlify/cli/config.mdx
@@ -144,7 +144,8 @@ spec:
 The installed set is recorded in `.forge/forge.config.json` under `mcp.integrations`, so
 every subsequent `forge sync` re-emits the same servers and byte-compares each forge-owned
 entry, so a hand-edit to one is detected and repaired. (The stop-hook auto-sync refreshes
-only Forge's block in `AGENTS.md`; MCP config is repaired by `forge sync`.)
+only Forge's block in `AGENTS.md` and, when it already exists, Continue's forge-owned
+`.continue/rules/00-forge.md`; MCP config is repaired by `forge sync`.)
 
 ### `--adopt` semantics
 
diff --git a/mintlify/cli/core.mdx b/mintlify/cli/core.mdx
index f20ef17a..17ac93c0 100644
--- a/mintlify/cli/core.mdx
+++ b/mintlify/cli/core.mdx
@@ -81,6 +81,13 @@ any text you added around the generated part; if you edited inside the generated
 first saves the old file as `AGENTS.md.forge-bak-<time>`. Sync emits for the tools recorded
 by `forge init` (all tools when none are recorded).
 
+The Codex (32 KiB) and Windsurf (~12k characters) size checks measure the whole
+`AGENTS.md`, your text included. Those tools drop the end of an oversized file first, so
+when your part pushes it over budget, sync warns; the Forge block can sit anywhere in the
+file, and sync keeps it where you put it. While an `AGENTS.md.forge-bak` left by an older
+Forge still holds text that `AGENTS.md` lacks, `forge sync` and `forge doctor` warn: no
+agent reads that file, so move its rules back into `AGENTS.md`, outside the block.
+
 ## `forge doctor`
 
 Health-check installed tools, guards, MCP auth, and config drift.
diff --git a/mintlify/concepts/config-compiler.mdx b/mintlify/concepts/config-compiler.mdx
index 66c6eaa1..46e81a3f 100644
--- a/mintlify/concepts/config-compiler.mdx
+++ b/mintlify/concepts/config-compiler.mdx
@@ -107,5 +107,6 @@ Roo Code and VS Code receive the Forge MCP server via `forge init` (`.roo/mcp.js
 
 <Warning>
   **Char caps are real.** Codex truncates at 32 KiB, Windsurf at 6k/12k. `forge sync`
-  enforces a source size budget so a config never silently truncates.
+  enforces a source size budget and checks the whole `AGENTS.md`, including any text you
+  wrote outside the Forge block, so a config never silently truncates.
 </Warning>
diff --git a/src/doctor.js b/src/doctor.js
index 1c99758c..1dccf1f8 100644
--- a/src/doctor.js
+++ b/src/doctor.js
@@ -25,7 +25,7 @@ import { ensureLedgerGitattributes, guardKey, isStaleManagedHook, mergeSettings
 import { verify as ledgerVerify, repoLedger } from "./ledger_store.js";
 import { PRICING_VERIFIED } from "./model_tiers.js";
 import { activeProvider, envModelOverride } from "./providers.js";
-import { agentsMdStatus, canonical, sync } from "./sync.js";
+import { agentsMdStatus, canonical, strandedAgentsBackup, sync } from "./sync.js";
 import { updateStatus } from "./update.js";
 
 const ok = (label, note = "") => ({ status: "ok", label, note });
@@ -575,6 +575,11 @@ function checkDrift(out, targetRoot) {
       ),
   };
   out.push(rows[status.state]());
+  // Rules an older forge moved aside when it replaced a hand-written AGENTS.md. The Stop hook
+  // often converts AGENTS.md first and its result is never shown, so doctor keeps saying it.
+  // No automatic fix: only a person can tell which of those rules still apply.
+  const stranded = strandedAgentsBackup(targetRoot);
+  if (stranded) out.push(warn("AGENTS.md.forge-bak", stranded));
 }
 
 // MCP hygiene: past ~6 servers, tool-selection accuracy drops and the context bloats.
diff --git a/src/emit/_shared.js b/src/emit/_shared.js
index f93b0a63..aa4453c5 100644
--- a/src/emit/_shared.js
+++ b/src/emit/_shared.js
@@ -62,11 +62,17 @@ const wholeLine = (marker) => new RegExp(`^${marker}\\r?$`, "m");
 const BEGIN_RE = wholeLine(BLOCK_BEGIN);
 const END_RE = wholeLine(BLOCK_END);
 
+/** A body line that reads exactly like a marker (a multi-line rule, fact or lesson can hold
+ *  one) would end the block early: every sync would then see drift and leave another stale
+ *  tail behind, growing the file. Such a line is indented one space, which Markdown renders
+ *  the same and which no longer matches a whole-line marker. */
+const MARKER_LINE_RE = new RegExp(`^(?:${BLOCK_BEGIN}|${BLOCK_END})\\r?$`, "gm");
+
 /** The exact bytes of the managed block: begin marker, the generated header (it carries the
  *  `forge:sync:<hash>` marker), the body, end marker. The writer and every drift check build
  *  their expectation through this one helper, as with managedContent (RA-16). */
 export const managedBlock = (header, body) =>
-  `${BLOCK_BEGIN}\n${header}\n${body.replace(/\n*$/, "\n")}${BLOCK_END}\n`;
+  `${BLOCK_BEGIN}\n${header}\n${body.replace(MARKER_LINE_RE, " $&").replace(/\n*$/, "\n")}${BLOCK_END}\n`;
 
 /**
  * Locate the managed block. null when there is none; `{damaged: true}` when only one marker
diff --git a/src/sync.js b/src/sync.js
index 0eaf53ee..00abe3b9 100644
--- a/src/sync.js
+++ b/src/sync.js
@@ -217,10 +217,6 @@ function writeAgentsBlock(status, { allowBackup }) {
     writeFileSync(path, next);
     return { action: "written", note, ...extra };
   };
-  // An older forge moved a hand-written AGENTS.md aside to this one fixed name.
-  const oldBak = existsSync(`${path}.forge-bak`)
-    ? "AGENTS.md.forge-bak (the hand-written file an older forge replaced) can now go back into AGENTS.md, outside the Forge block."
-    : "";
   if (state === "in-sync") return { action: "unchanged", note: "Forge block current" };
   if (state === "missing") return put(block, "new file (Forge block)");
   if (state === "drifted" && status.found) {
@@ -248,7 +244,6 @@ function writeAgentsBlock(status, { allowBackup }) {
     return put(
       `${before}${block}${after ? `\n${after}` : ""}`,
       "converted to a Forge block (lossless)",
-      oldBak ? { warning: oldBak } : {},
     );
   }
   if (state === "legacy-edited" && status.legacy) {
@@ -262,10 +257,7 @@ function writeAgentsBlock(status, { allowBackup }) {
       warning: [
         `AGENTS.md was fully generated but edited inside the generated text — converted to a Forge block; the previous file is saved as ${name}.`,
         "Copy your edits back OUTSIDE the <!-- forge:begin --> / <!-- forge:end --> markers, where sync never touches them.",
-        oldBak,
-      ]
-        .filter(Boolean)
-        .join(" "),
+      ].join(" "),
     });
   }
   return {
@@ -276,6 +268,23 @@ function writeAgentsBlock(status, { allowBackup }) {
   };
 }
 
+/**
+ * The hand-written AGENTS.md an older forge replaced is parked in `AGENTS.md.forge-bak`, a file
+ * no agent reads. Whichever path converts AGENTS.md to a block (often the Stop hook, whose
+ * result nobody sees), those rules stay invisible until a person moves them back, so sync and
+ * doctor keep saying so for as long as the backup holds text that AGENTS.md does not.
+ * Pure read. Returns the warning, or null when there is nothing stranded.
+ * @param {string} [targetRoot]
+ * @returns {string|null}
+ */
+export function strandedAgentsBackup(targetRoot = process.cwd()) {
+  const saved = shared.readIfExists(join(targetRoot, "AGENTS.md.forge-bak"))?.trim();
+  if (!saved) return null;
+  const agents = shared.readIfExists(join(targetRoot, "AGENTS.md")) ?? "";
+  if (agents.includes(saved)) return null;
+  return "AGENTS.md.forge-bak holds the hand-written AGENTS.md an older forge replaced, and no agent reads it — move its text back into AGENTS.md outside the Forge block (sync never touches it there), then delete the backup";
+}
+
 /**
  * Which tools sync emits for: an explicit list (init passes one) wins, then the repo config's
  * `tools` key (recorded by `forge init`), else every tool — a repo that never chose keeps the
@@ -310,13 +319,17 @@ export function sync({ targetRoot = process.cwd(), tools } = {}) {
   // behaviour replaced the whole file and parked the original in AGENTS.md.forge-bak).
   const agentsPath = join(targetRoot, "AGENTS.md");
   const agents = writeAgentsBlock(agentsMdStatus(targetRoot, canonical), { allowBackup: true });
+  // Tools read the whole file, not just forge's block, and a person's text now shares it.
+  // Size checks (Codex's 32 KiB truncation, Windsurf's ~12k-char cap) measure what is on disk.
+  const agentsText = shared.readIfExists(agentsPath) ?? canonical;
+  const agentsBytes = Buffer.byteLength(agentsText);
 
   const ctx = {
     targetRoot,
     canonical,
     hash,
-    bytes,
-    chars: canonical.length,
+    bytes: agentsBytes,
+    chars: agentsText.length,
     agentsPath,
     shared,
     join,
@@ -379,6 +392,8 @@ export function sync({ targetRoot = process.cwd(), tools } = {}) {
       `${legacyRules.path} is not valid JSON — ignored, default rules used (fix or delete it)`,
     );
   if (agents.warning) warnings.push(agents.warning);
+  const stranded = strandedAgentsBackup(targetRoot);
+  if (stranded) warnings.push(stranded);
   if (selection.unknown.length)
     warnings.push(
       `unknown tool(s) in the tool selection ignored: ${selection.unknown.join(", ")} (known: ${KNOWN_TOOLS.join(", ")})`,
@@ -387,6 +402,10 @@ export function sync({ targetRoot = process.cwd(), tools } = {}) {
     warnings.push(
       `canonical is ${bytes} B (> ${SIZE_BUDGET_BYTES} B budget) — trim source/rules.json`,
     );
+  else if (agentsBytes > SIZE_BUDGET_BYTES)
+    warnings.push(
+      `AGENTS.md is ${agentsBytes} B (> ${SIZE_BUDGET_BYTES} B budget; Forge's rules are ${bytes} B of it) — Codex stops reading at 32 KiB and Windsurf at ~12k chars, so the end of the file is lost first: shorten the hand-written text, or move the Forge block nearer the top (sync keeps it where it sits)`,
+    );
   // Aggregate status (ME-19): sync writes AGENTS.md, then per-tool files, then MCP files
   // and is NOT transactional — a mid-way failure is recorded as an `action:"error"` row but
   // used to be reported per-target only, so a caller (init/CLI) could still imply every
diff --git a/test/agents_block.test.js b/test/agents_block.test.js
index 96aefe3f..c4cf0c61 100644
--- a/test/agents_block.test.js
+++ b/test/agents_block.test.js
@@ -28,13 +28,23 @@ import {
   splitLegacyManaged,
 } from "../src/emit/_shared.js";
 import { init } from "../src/init.js";
-import { agentsMdStatus, assemble, autoSyncIfDrifted, canonical, sync } from "../src/sync.js";
+import {
+  agentsMdStatus,
+  assemble,
+  autoSyncIfDrifted,
+  canonical,
+  strandedAgentsBackup,
+  sync,
+} from "../src/sync.js";
 
 const fixture = () => mkdtempSync(join(tmpdir(), "forge-block-"));
 const agentsOf = (root) => readFileSync(join(root, "AGENTS.md"), "utf8");
 const HAND =
   "# HostLelo agents\n\n- Lint: `npm run lint`\n- Never call the WHMCS API from the client.\n";
 
+/** The warning while an older forge's AGENTS.md.forge-bak holds rules no agent reads. */
+const STRANDED_RE = /AGENTS\.md\.forge-bak holds the hand-written AGENTS\.md an older forge/;
+
 /** The file the pre-block forge wrote: the generated header, then the whole body. */
 const legacyFile = (body) => managedContent(mdHeader(hashContent(body)), body);
 
@@ -226,10 +236,100 @@ test("a legacy file edited INSIDE the generated text: auto-sync refuses, sync ba
   assert.equal(agentsOf(root), agentsMdStatus(root).block);
   const warning = r.warnings.find((w) => w.includes("forge-bak-"));
   assert.ok(warning, "the backup is named in a warning");
-  assert.match(warning, /AGENTS\.md\.forge-bak \(the hand-written file an older forge replaced\)/);
+  assert.ok(
+    r.warnings.some((w) => STRANDED_RE.test(w)),
+    "the older fixed-name backup is reported too",
+  );
   assert.equal(readFileSync(join(root, "AGENTS.md.forge-bak"), "utf8"), HAND, "old backup kept");
 });
 
+// ---------------------------------------------------------------------------
+// Review follow-ups: marker lines in the body, whole-file size, stranded backups
+// ---------------------------------------------------------------------------
+
+test("a body line that reads like a marker cannot end the block early (sync and auto-sync converge)", () => {
+  const root = fixture();
+  writeFileSync(join(root, "AGENTS.md"), HAND);
+  mkdirSync(join(root, ".forge"), { recursive: true });
+  // A multi-line rule keeps its newlines, so either marker can land on a line of its own.
+  writeFileSync(
+    join(root, ".forge", "rules.json"),
+    JSON.stringify({
+      sections: [{ title: "Quoted", rules: [`ends with\n${BLOCK_END}`, `starts\n${BLOCK_BEGIN}`] }],
+    }),
+  );
+  sync({ targetRoot: root });
+  const first = agentsOf(root);
+  assert.ok(first.startsWith(HAND), "the person's text is untouched");
+  const found = findManagedBlock(first);
+  assert.equal(found?.damaged, false);
+  if (found?.damaged !== false) return;
+  assert.equal(found.end, first.length, "the block runs to the real end marker");
+  assert.match(first, new RegExp(`^ ${BLOCK_END}$`, "m"), "the quoted marker is indented");
+  assert.equal(agentsMdStatus(root).state, "in-sync");
+
+  sync({ targetRoot: root });
+  assert.equal(agentsOf(root), first, "a second sync writes the same bytes");
+  assert.deepEqual(autoSyncIfDrifted(root), { synced: false, reason: "in sync" });
+  assert.equal(agentsOf(root), first, "auto-sync does not grow the file");
+});
+
+test("size checks measure the whole AGENTS.md, not only Forge's block", () => {
+  const root = fixture();
+  const big = `# Team rules\n\n${"- a hand-written rule that the team relies on every day\n".repeat(560)}`;
+  writeFileSync(join(root, "AGENTS.md"), big);
+  const r = sync({ targetRoot: root, tools: ["codex", "windsurf"] });
+  const onDisk = Buffer.byteLength(agentsOf(root));
+  assert.ok(onDisk > 32 * 1024 && r.bytes < 32 * 1024, "only the whole file is over the cap");
+  const codex = r.report.find((row) => row.tool === "Codex");
+  assert.equal(codex?.action, "warn");
+  assert.equal(codex?.note, `${onDisk} B exceeds 32 KiB cap — will truncate`);
+  assert.equal(r.report.find((row) => row.tool === "Windsurf/Devin")?.action, "warn");
+  const warning = r.warnings.find((w) => w.startsWith("AGENTS.md is "));
+  assert.ok(warning, "sync warns about the file it just wrote");
+  assert.match(warning, new RegExp(`^AGENTS\\.md is ${onDisk} B .*Forge's rules are ${r.bytes} B`));
+  assert.match(warning, /move the Forge block nearer the top/);
+
+  const small = fixture();
+  writeFileSync(join(small, "AGENTS.md"), HAND);
+  const s = sync({ targetRoot: small, tools: ["codex"] });
+  const codexSmall = s.report.find((row) => row.tool === "Codex");
+  assert.equal(codexSmall?.note, `native (${Buffer.byteLength(agentsOf(small))}/32768 B)`);
+  assert.ok(!s.warnings.some((w) => w.startsWith("AGENTS.md is ")));
+});
+
+test("a stranded AGENTS.md.forge-bak is reported by sync and doctor until its text is back", () => {
+  const root = fixture();
+  const settingsPath = join(fixture(), "settings.json");
+  // What an older forge left: the generated file, with the person's original moved aside.
+  writeFileSync(join(root, "AGENTS.md"), legacyFile(canonical(root)));
+  writeFileSync(join(root, "AGENTS.md.forge-bak"), HAND);
+  // The Stop hook usually converts first, and nobody sees its result.
+  assert.equal(autoSyncIfDrifted(root).synced, true);
+  assert.equal(agentsMdStatus(root).state, "in-sync");
+  assert.match(strandedAgentsBackup(root) ?? "", STRANDED_RE);
+
+  assert.ok(sync({ targetRoot: root }).warnings.some((w) => STRANDED_RE.test(w)));
+  const row = doctor({ targetRoot: root, settingsPath }).results.find(
+    (r) => r.label === "AGENTS.md.forge-bak",
+  );
+  assert.equal(row?.status, "warn");
+  assert.match(row?.note ?? "", /outside the Forge block/);
+  assert.equal(row?.fix, undefined, "moving rules back is a person's call");
+
+  // The person moves the text back above the block: nothing stranded any more.
+  writeFileSync(join(root, "AGENTS.md"), `${HAND}\n${agentsOf(root)}`);
+  assert.equal(strandedAgentsBackup(root), null);
+  assert.ok(!sync({ targetRoot: root }).warnings.some((w) => STRANDED_RE.test(w)));
+  const after = doctor({ targetRoot: root, settingsPath }).results;
+  assert.ok(!after.some((r) => r.label === "AGENTS.md.forge-bak"));
+
+  // An empty backup strands nothing.
+  const blank = fixture();
+  writeFileSync(join(blank, "AGENTS.md.forge-bak"), "\n");
+  assert.equal(strandedAgentsBackup(blank), null);
+});
+
 // ---------------------------------------------------------------------------
 // doctor speaks the same states
 // ---------------------------------------------------------------------------

From 399573faf1ac7c35cd27eaa2a34e0d09acb0dcc0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 23 Sep 2026 22:28:44 +0000
Subject: [PATCH 3/3] feat(init): honour the recorded tool set in integrations
 and `forge tools`

`forge init --tools <list|all>` and the Claude-plus-detected default
arrived in 61aa2db under a fix type. This commit completes that feature
and carries its feat type, so the auto-release is a minor bump, not a
patch.

- integrations add recorded ownership (mcp.adopted) for every MCP
  target, including ones outside the recorded tool set that it never
  wrote. A same-name entry a person later wrote for such a tool was then
  overwritten by `forge init --tools ...` and deleted by `forge
  integrations remove` (breaks ME-08). Adoptions now cover only
  mcpTargetFilesFor(recorded set). When a tool joins the set later,
  claimEmittedIntegrations (run by init and `forge tools`) claims the
  copies sync wrote there by add's absent-or-identical rule, so spec
  updates and remove still reach forge's own copies and a divergent
  entry stays the person's.
- `forge tools <name>` synced with the recorded set only, so after a
  default init the chosen primary tool got no config at all.
  setPrimaryTool now adds the tool to a recorded set in the same config
  write; the CLI says so.
- The integrations dry run lists the files it would write instead of a
  fixed every-tool list.
- Docs: quickstart, integrations and tools docs, the examples README,
  the landing copy and the onboarding diagrams no longer say init or
  add write every tool.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UUhB8JaPayd43w37dxiXrW
Signed-off-by: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                               |  23 +++-
 ONBOARDING.md                              |   2 +-
 docs/GUIDE.md                              |  10 +-
 examples/README.md                         |   6 +-
 landing/app.js                             |   2 +-
 mintlify/cli/config.mdx                    |  22 ++--
 mintlify/guides/zero-config-onboarding.mdx |   2 +-
 mintlify/quickstart.mdx                    |  21 ++--
 src/cli.js                                 |  18 ++-
 src/emit/mcp.js                            |  15 +++
 src/init.js                                |   4 +
 src/integrations.js                        |  85 ++++++++++---
 src/repo_config.js                         |  38 +++++-
 test/init_tools.test.js                    | 140 ++++++++++++++++++++-
 14 files changed, 330 insertions(+), 58 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3b41e11b..9e9d5262 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,14 +29,25 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Notes added under a generated `CLAUDE.md` header survive later syncs.** Sync refreshes
   only the marker line instead of regenerating the file.
 
+### Added
+
+- **`forge init --tools <list|all>` chooses the agent tools a repo emits config for.** The
+  choice is recorded in `.forge/forge.config.json` (`tools`), and later `forge sync`,
+  `forge doctor --fix` and `forge integrations add` emit the same set.
+
 ### Changed
 
-- **`forge init` emits config only for the tools a repo uses:** Claude Code plus every tool
-  with a sign on disk (`.cursor/`, `.codex/`, `.github/copilot-instructions.md`, …), or an
-  explicit `--tools <list|all>`. The choice is recorded in `.forge/forge.config.json`
-  (`tools`) and later syncs and `forge integrations add` honour it; a repo with no recorded
-  set still gets every tool. `forge tools --reset` now clears only the primary tool and keeps
-  that set.
+- **`forge init` emits config only for the tools a repo uses by default:** Claude Code plus
+  every tool with a sign on disk (`.cursor/`, `.codex/`, `.github/copilot-instructions.md`,
+  …). A repo with no recorded set still gets every tool on sync; `--tools all` restores the
+  old init behaviour.
+- **`forge integrations add` writes to, and takes ownership in, only the recorded tools' MCP
+  config** (its dry run lists the files). A tool added to the set later gets the recorded
+  servers on that run and Forge owns those copies, while a same-name entry you configured
+  for that tool yourself stays yours: it is never overwritten or removed.
+- **`forge tools <name>` adds the tool to a recorded set that lacks it**, so the primary tool
+  gets its own config. `forge tools --reset` now clears only the primary tool and keeps the
+  set.
 
 ## [1.3.0] - 2026-09-23
 
diff --git a/ONBOARDING.md b/ONBOARDING.md
index cac96479..1ffce1e7 100644
--- a/ONBOARDING.md
+++ b/ONBOARDING.md
@@ -13,7 +13,7 @@ start paying off on day two.
 ```mermaid
 %%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','edgeLabelBackground':'#201a15','clusterBkg':'#171310','clusterBorder':'#4a3b2e','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'14px'},'flowchart':{'curve':'basis','padding':10,'nodeSpacing':36,'rankSpacing':44}}}%%
 flowchart TD
-    I["forge init"] --> Cfg["every tool configured<br/>from one source"]
+    I["forge init"] --> Cfg["your tools configured<br/>from one source"]
     Cfg --> Work["you work as usual"]
     Work --> Gate["substrate checks each task:<br/>ask first? · which model? · what breaks?"]
     Gate --> Edit["agent edits, with guardrails"]
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
index 62d496dd..921d69ab 100644
--- a/docs/GUIDE.md
+++ b/docs/GUIDE.md
@@ -795,8 +795,8 @@ or an explicit `--tools <list|all>`) and records that set in `.forge/forge.confi
 one initialised with `--tools all`, gets config for **every** supported agent tool — great
 for portability, noisy for a repo where only one tool is ever used: `.cursor/`, `.gemini/`,
 `.codex/`, `.zed/`, `.aider.conf.yml`, and friends all show up as tracked clutter. `forge
-tools` fixes that without changing what `sync` emits (`--reset` clears the primary tool and
-leaves the recorded `tools` set alone).
+tools` fixes that without dropping anything `sync` emits (`--reset` clears the primary tool
+and leaves the recorded `tools` set alone).
 
 - `forge tools` — show the detected/primary tool (from `.forge/config.json`, else
   auto-detected from which agent folder exists — `CLAUDE.md`, `.cursor/`, `.gemini/`,
@@ -807,7 +807,9 @@ leaves the recorded `tools` set alone).
   `.forge/config.json`, then write a **marked, reversible** block into `.gitignore`
   (`# forge:gitignore:begin … # forge:gitignore:end`) that ignores every OTHER tool's
   emitted artifacts. Your own `.gitignore` lines are never touched, and the shared
-  `AGENTS.md` plus the primary tool's own files always stay tracked.
+  `AGENTS.md` plus the primary tool's own files always stay tracked. When `forge init`
+  recorded a tool set without `<name>`, `<name>` joins it first, so the sync emits its
+  config (and Forge owns the copies of your integrations it writes there).
 - `forge tools --reset` — clear the config and strip the managed block (only the block).
 
 This is **opt-in** — plain `forge sync` never writes `.gitignore`. The block lists the
@@ -1309,7 +1311,7 @@ Plain `forge cost` remains the per-day spend view via `ccusage`.
 | `forge docs sync`                | Diff-driven stale-docs sweep: UPDATED / STALE (file:line hits) / VERIFIED-UNAFFECTED per artifact (see the full section above).                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `forge docs impact`              | Documentation-reference graph: extract typed entities (commands/flags/env/MCP/symbols/version), index every doc surface, and report which docs reference the entities THIS diff changed — ranked by confidence (see the full section above).                                                                                                                                                                                                                                                                                                                                                            |
 | `forge catalog`                  | Start-Here index of every tool / crew / guard.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `forge integrations`             | Opt-in third-party MCP servers (e.g. `context7`, no longer installed by default). `integrations add <name>` prints the package, its network behaviour, and the files it touches, then writes only with `--yes`; the install is recorded in `.forge/forge.config.json` (`mcp.integrations`), so every later sync keeps emitting it. A same-name server you configured yourself is never overwritten unless you pass `--adopt` (recorded under `mcp.adopted`). `integrations remove <name>` reverses the add — it deletes only forge-owned entries/blocks/files and is a no-op when nothing is installed. |
+| `forge integrations`             | Opt-in third-party MCP servers (e.g. `context7`, no longer installed by default). `integrations add <name>` prints the package, its network behaviour, and the files it touches, then writes only with `--yes`, into the MCP config of the tools `forge init` recorded (every tool when none are); the install is recorded in `.forge/forge.config.json` (`mcp.integrations`), so every later sync keeps emitting it. A same-name server you configured yourself is never overwritten unless you pass `--adopt` (recorded under `mcp.adopted`). `integrations remove <name>` reverses the add — it deletes only forge-owned entries/blocks/files and is a no-op when nothing is installed. |
 | `forge brain` / `forge remember` | Portable project memory inlined into `AGENTS.md`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `forge cost`                     | Real per-day spend (via `ccusage`) + the cost ceiling; `--stages` for the measured report.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `forge scan <target>`            | Vet a skill/MCP (SKILL.md/.mcp.json) for injection/RCE/exfil before install.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
diff --git a/examples/README.md b/examples/README.md
index 64198443..15e3ce32 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -7,11 +7,11 @@ your team learns from one machine to the next.
 
 ## 1. First run — install, scaffold, see the gate
 
-Install the CLI, scaffold configs for every tool from one source, and health-check the setup:
+Install the CLI, scaffold config for the tools this repo uses from one source, and health-check the setup:
 
 ```bash
 npm i -g @codewithjuber/forgekit
-forge init          # emit every tool's native config from one source
+forge init          # emit native config for Claude + the tools this repo uses (--tools all: every tool)
 forge doctor        # health-check tools, guards, MCP, and drift
 ```
 
@@ -52,7 +52,7 @@ else's model on the next pull.
 
 [`rules.override.json`](./rules.override.json) shows a project adding its own rules on top of
 forgekit's shared source. Copy it to `.forge/rules.json` in your repo, then run `forge sync` —
-the extra rules are appended to every tool's config (AGENTS.md, CLAUDE.md, Cursor, Gemini, …).
+the extra rules reach every emitted tool's config (AGENTS.md, CLAUDE.md, Cursor, Gemini, …).
 
 ## Cortex demo
 
diff --git a/landing/app.js b/landing/app.js
index 6499c886..a0d1ac39 100644
--- a/landing/app.js
+++ b/landing/app.js
@@ -50,7 +50,7 @@ const installs = [
   {
     id: "npm",
     command: "npm install -g @codewithjuber/forgekit\nforge init",
-    note: "Emits every tool’s native config from one source",
+    note: "Emits native config for the tools your repo uses, from one source",
   },
   {
     id: "github",
diff --git a/mintlify/cli/config.mdx b/mintlify/cli/config.mdx
index ada34a9c..344c0ccf 100644
--- a/mintlify/cli/config.mdx
+++ b/mintlify/cli/config.mdx
@@ -106,7 +106,9 @@ forge report
 ## `forge tools`
 
 Select this repo's primary AI coding tool and wire the matching `.gitignore` entries, so
-generated config and `.forge/` artifacts are ignored correctly for your setup.
+generated config and `.forge/` artifacts are ignored correctly for your setup. If
+`forge init` recorded a tool set without that tool, `forge tools <name>` adds it first, so
+the tool gets its own config.
 
 ```bash
 forge tools
@@ -115,8 +117,8 @@ forge tools
 ## `forge integrations`
 
 Opt-in third-party MCP servers (for example `context7`), managed non-destructively across
-every tool Forge emits config for — Claude Code, Codex, Cursor, Gemini, Continue, OpenClaw,
-and the rest.
+the tools Forge emits config for in this repo — the set `forge init` recorded (Claude plus
+detected tools, or `--tools`), or every tool when none is recorded.
 
 Third-party MCP servers are **not** installed by default. Nothing lands on disk until you
 run `forge integrations add <name> --yes`.
@@ -124,22 +126,26 @@ run `forge integrations add <name> --yes`.
 ```bash
 forge integrations                        # list opt-in servers with package + purpose
 forge integrations add <name>             # dry-run: prints package, network, files it would touch
-forge integrations add <name> --yes       # apply — write MCP config for every tool
+forge integrations add <name> --yes       # apply — write MCP config for this repo's tools
 forge integrations add <name> --yes --adopt   # also claim a same-name entry you already configured
 forge integrations remove <name>          # reverse the add — deletes only forge-owned entries
 ```
 
 ### What `add` writes
 
-`add --yes` writes the server into every tool's native MCP config from one canonical
-spec:
+`add --yes` writes the server from one canonical spec into the native MCP config of each
+tool in the recorded set (the dry run lists the exact files):
 
 - `.mcp.json` (Claude Code)
 - `.cursor/mcp.json` (Cursor)
 - `.gemini/settings.json` (Gemini)
 - `.codex/config.toml` — as a `# forge:managed:<name>` block, refreshed by byte-compare
 - `.continue/mcpServers/<name>.yaml` — one forge-marked YAML per managed server
-- and the rest of the tools Forge emits config for
+- and the other MCP targets (Roo Code, Zed, VS Code, OpenClaw) when those tools are selected
+
+Forge owns only the entries it wrote. A tool added to the set later (`forge init --tools …`
+or `forge tools <name>`) gets the recorded servers on that run, and Forge owns those copies
+too; a same-name entry you had already configured for that tool stays yours.
 
 The installed set is recorded in `.forge/forge.config.json` under `mcp.integrations`, so
 every subsequent `forge sync` re-emits the same servers and byte-compares each forge-owned
@@ -155,7 +161,7 @@ did not put it there, `add` **does not overwrite it**. Instead it reports the fi
 `mcp.adopted` in `.forge/forge.config.json` and will manage it from then on.
 
 Use `--adopt` when you configured a server by hand earlier and now want Forge to keep it
-in sync across every tool.
+in sync across this repo's tools.
 
 ### `remove`
 
diff --git a/mintlify/guides/zero-config-onboarding.mdx b/mintlify/guides/zero-config-onboarding.mdx
index beeaa215..c0abfc06 100644
--- a/mintlify/guides/zero-config-onboarding.mdx
+++ b/mintlify/guides/zero-config-onboarding.mdx
@@ -11,7 +11,7 @@ the CLI, run `forge init` in each repo, and some paths assume Bash, Git, and `jq
 ```mermaid
 %%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','edgeLabelBackground':'#201a15','clusterBkg':'#171310','clusterBorder':'#4a3b2e','fontFamily':'ui-sans-serif, system-ui, sans-serif','fontSize':'14px'},'flowchart':{'curve':'basis','padding':10,'nodeSpacing':36,'rankSpacing':44}}}%%
 flowchart TD
-    I["forge init"] --> Cfg["every tool configured from one source"]
+    I["forge init"] --> Cfg["your tools configured from one source"]
     Cfg --> Work["you work as usual"]
     Work --> Gate["substrate checks each task · ask first? · which model? · what breaks?"]
     Gate --> Edit["agent edits, with guardrails"]
diff --git a/mintlify/quickstart.mdx b/mintlify/quickstart.mdx
index c6ecba99..d0f7b84b 100644
--- a/mintlify/quickstart.mdx
+++ b/mintlify/quickstart.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Quickstart"
-description: "Install Forge, emit every tool's config from one source, and run your first pre-action gate — in about 60 seconds."
+description: "Install Forge, emit your tools' config from one source, and run your first pre-action gate — in about 60 seconds."
 ---
 
 Get from zero to a configured repo and your first substrate check in about a minute.
@@ -31,16 +31,21 @@ including the symlink dev setup.
 ## 2. Configure a repo
 
 <Steps>
-  <Step title="Emit every tool's config">
+  <Step title="Emit your tools' config">
     ```bash
     cd ~/your-project
-    forge init
+    forge init                          # Claude + the tools this repo already uses
+    forge init --tools claude,cursor    # or name them (--tools all for every tool)
     ```
-    This emits `AGENTS.md`, `CLAUDE.md`, `.gemini/settings.json`, `.aider.conf.yml`, and
-    the rest — plus the `.gitattributes` union-merge rule the ledger needs. Claude Code,
-    Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, Continue, and OpenClaw now
-    read the **same** rules, each from its own native file. On OpenClaw the MCP server is
-    one extra command: `openclaw mcp add forge-cortex --command forge --arg cortex-mcp`.
+    This emits `AGENTS.md`, Claude Code's `CLAUDE.md` and `.mcp.json`, and the config of
+    each tool the repo already shows (`.cursor/`, `.codex/`, `.gemini/`,
+    `.github/copilot-instructions.md`, …) — plus the `.gitattributes` union-merge rule the
+    ledger needs. The choice is recorded, so later syncs emit the same set. Codex, Cursor,
+    Copilot, Windsurf, Zed, and OpenClaw read the rules from `AGENTS.md` either way; Gemini,
+    Aider, and Continue need their own files, which init writes when it detects those tools
+    or you name them in `--tools`. An existing `AGENTS.md` is kept: Forge adds its rules in
+    a marked block. On OpenClaw the MCP server is one extra command:
+    `openclaw mcp add forge-cortex --command forge --arg cortex-mcp`.
   </Step>
   <Step title="Health-check the setup">
     ```bash
diff --git a/src/cli.js b/src/cli.js
index c7cfe6a0..7299437b 100755
--- a/src/cli.js
+++ b/src/cli.js
@@ -597,7 +597,7 @@ HANDLERS.integrations = async (argv) => {
   const sub = argv[1];
   if (sub === "add") {
     const name = argv[2];
-    const plan = planIntegration(name);
+    const plan = planIntegration(name, { targetRoot: process.cwd() });
     if (!plan.ok) {
       console.error(plan.reason);
       process.exitCode = 1;
@@ -605,11 +605,11 @@ HANDLERS.integrations = async (argv) => {
     }
     if (!argv.includes("--yes")) {
       heading(`${BRAND.brand} integrations — add ${name}\n`);
-      console.log(`  This adds a THIRD-PARTY MCP server to every detected tool's config:`);
+      console.log(`  This adds a THIRD-PARTY MCP server to the MCP config of this repo's tools:`);
       console.log(`    package: ${plan.pkg}`);
       console.log(`    network: ${plan.network}`);
       console.log(`    purpose: ${plan.why}`);
-      console.log(`    writes:  .mcp.json, .cursor/mcp.json, .gemini/…, .codex/…, .continue/…`);
+      console.log(`    writes:  ${plan.writes.join(", ")}`);
       console.log(`    records: .forge/forge.config.json (mcp.integrations — the managed set)`);
       console.log(
         `\n  Not installed. Re-run with --yes to apply:  ${BRAND.cli} integrations add ${name} --yes`,
@@ -2953,12 +2953,22 @@ HANDLERS.tools = async (argv) => {
     // Inject the sync runner from here (the orchestration layer) so repo_config —
     // a config-leaf module — no longer reaches back into the sync compiler.
     const { sync } = await import("./sync.js");
+    const { claimEmittedIntegrations } = await import("./integrations.js");
     const r = await applyPrimaryTool(root, name, {
-      syncFn: (r2) => sync({ targetRoot: r2 }),
+      syncFn: (r2) => {
+        const out = sync({ targetRoot: r2 });
+        // The tool may have just joined the recorded set: own its integration copies too.
+        claimEmittedIntegrations(r2);
+        return out;
+      },
     });
     if (json) return console.log(JSON.stringify(r, null, 2));
     heading(`${BRAND.brand} tools — primary set\n`);
     console.log(`  primary tool   ${paint(r.primaryTool, "ok")}`);
+    if (r.addedTool)
+      console.log(
+        `  tool set       ${name} added to the tools \`${BRAND.cli} init\` recorded, so sync now emits its config`,
+      );
     console.log(
       `  gitignored     ${r.targets.length ? r.targets.join(", ") : "none"}  (block ${r.gitignore})`,
     );
diff --git a/src/emit/mcp.js b/src/emit/mcp.js
index 915eea70..0d85c4db 100644
--- a/src/emit/mcp.js
+++ b/src/emit/mcp.js
@@ -50,6 +50,21 @@ export const CODEX_TARGET = ".codex/config.toml";
  *  and of the per-target adoption record. Continue files are owned by marker, not record. */
 export const MCP_TARGET_FILES = [...JSON_TARGETS.map((t) => t.file), CODEX_TARGET];
 
+/**
+ * The ownable targets (MCP_TARGET_FILES entries) emitMcp writes for a tool selection —
+ * canonical keys, null = every tool. An adoption must never name a target outside this list:
+ * forge wrote nothing there, so a same-name entry a person adds there later is theirs (ME-08).
+ * @param {string[]|null} [tools]
+ * @returns {string[]}
+ */
+export function mcpTargetFilesFor(tools = null) {
+  const emits = (id) => tools === null || tools.includes(id);
+  return [
+    ...JSON_TARGETS.filter((t) => emits(t.id)).map((t) => t.file),
+    ...(emits("codex") ? [CODEX_TARGET] : []),
+  ];
+}
+
 const adoptHint = (name) => `adopt with: ${BRAND.cli} integrations add ${name} --adopt`;
 
 // ---------------------------------------------------------------------------
diff --git a/src/init.js b/src/init.js
index 48641e20..618bb31f 100644
--- a/src/init.js
+++ b/src/init.js
@@ -14,6 +14,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { BRAND } from "./brand.js";
 import { ensureForgePrivateIgnored } from "./gitignore.js";
+import { claimEmittedIntegrations } from "./integrations.js";
 import { GITATTRIBUTES_RULE } from "./ledger_store.js";
 import { autoDetectProvider } from "./providers.js";
 import {
@@ -852,6 +853,9 @@ export function init({
   // that later syncs fall back to every tool rather than failing the whole init.
   const unrecorded = profileResult ? null : recordTools(targetRoot, selection.tools);
   const r = sync({ targetRoot, tools: selection.tools ?? "all" });
+  // A tool that just joined the set got the recorded integrations too: own those copies the
+  // way `integrations add` would have, so spec updates and `remove` reach them (ME-08).
+  claimEmittedIntegrations(targetRoot);
   ensureLedgerGitattributes(targetRoot);
   // Session hook logs hold raw prompts/commands — never let them be committed.
   ensureForgePrivateIgnored(targetRoot);
diff --git a/src/integrations.js b/src/integrations.js
index 2e63b3fa..0889ae3f 100644
--- a/src/integrations.js
+++ b/src/integrations.js
@@ -11,7 +11,9 @@
 // tool's config never authorises overwriting another tool's same-name entry. Legacy bare
 // names (`adopted: ["context7"]`) are still honoured — treated as "adopted for every
 // target" — and migrated to per-target pairs on the next write. A fresh add that forge
-// itself creates owns exactly the targets where it wrote (auto-adopt); a pre-existing
+// itself creates owns exactly the targets where it wrote (auto-adopt), which are only the
+// recorded tool set's targets; a tool that joins the set later has the copies sync wrote
+// for it claimed by claimEmittedIntegrations under the same rule. A pre-existing
 // DIVERGENT same-name entry needs an explicit --adopt for THAT target. Registry names carry
 // no implicit ownership (ME-09): a divergent user entry named e.g. `forge-cortex` is
 // preserved and reported like any other collision. Add/remove are ordered so disk and the
@@ -21,13 +23,15 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { BRAND } from "./brand.js";
 import {
+  continueFileFor,
   emitMcp,
   foreignTargets,
   MCP_TARGET_FILES,
+  mcpTargetFilesFor,
   removeMcp,
   validateServerName,
 } from "./emit/mcp.js";
-import { parseTools, readForgeConfig, writeForgeConfig } from "./repo_config.js";
+import { readForgeConfig, recordedTools, writeForgeConfig } from "./repo_config.js";
 
 /** The catalog of known optional integrations. Keep each entry honest about what running it
  *  actually does (network, third-party code execution). */
@@ -49,11 +53,20 @@ export function listIntegrations() {
   }));
 }
 
-/** Describe what `add <name>` would do, without writing anything. */
-export function planIntegration(name) {
+/** Describe what `add <name>` would do, without writing anything. `writes` lists the files
+ *  it would touch: those of the tool set `forge init` recorded (every tool when none is). */
+export function planIntegration(name, { targetRoot = process.cwd() } = {}) {
   const m = INTEGRATIONS[name];
   if (!m) return { ok: false, reason: `unknown integration: ${name}` };
-  return { ok: true, name, pkg: m.pkg, network: m.network, why: m.why };
+  const cfg = readForgeConfig(targetRoot);
+  const tools = cfg.corrupt ? null : recordedTools(cfg);
+  const writes = [
+    ...mcpTargetFilesFor(tools),
+    ...(tools === null || tools.includes("continue")
+      ? [`.continue/mcpServers/${continueFileFor(name)}`]
+      : []),
+  ];
+  return { ok: true, name, pkg: m.pkg, network: m.network, why: m.why, writes };
 }
 
 /**
@@ -185,20 +198,22 @@ export function addIntegration(name, { targetRoot = process.cwd(), adopt = false
     };
   const rec = mcpRecord(cfg);
   const servers = { ...managedServers(rec), [name]: m.server };
+  // Only the tools `forge init` recorded for this repo (every tool when none are), the same
+  // set `forge sync` emits for, so adding a server never creates an unused tool's config.
+  const tools = recordedTools(cfg);
   // Per-target ownership: forge owns the targets where it writes fresh (or byte-identical);
-  // a pre-existing divergent entry is owned only with --adopt.
+  // a pre-existing divergent entry is owned only with --adopt. A target outside the tool set
+  // gets nothing written, so it is never claimed: a same-name entry a person adds there later
+  // stays theirs, even once that tool joins the set (ME-08).
+  const targets = mcpTargetFilesFor(tools);
   const foreign = foreignTargets(targetRoot, name, m.server);
-  const anyForeign = foreign.size > 0;
+  const anyForeign = targets.some((t) => foreign.has(t));
   const newAdoptions = [];
-  for (const t of MCP_TARGET_FILES)
+  for (const t of targets)
     if (!foreign.has(t) || adopt) newAdoptions.push({ server: name, target: t });
   const owns = adoptionOwns([...rec.adopted, ...newAdoptions]);
-  // Emit FIRST (ME-10). A per-target write failure surfaces as an `error` row. Only into the
-  // tools `forge init` recorded for this repo (every tool when none are recorded), the same
-  // set `forge sync` emits for, so adding a server never creates an unused tool's config.
-  const recorded =
-    typeof cfg.tools === "string" || Array.isArray(cfg.tools) ? parseTools(cfg.tools).tools : null;
-  const rows = emitMcp({ targetRoot, servers, owns, tools: recorded });
+  // Emit FIRST (ME-10). A per-target write failure surfaces as an `error` row.
+  const rows = emitMcp({ targetRoot, servers, owns, tools });
   const failed = rows.filter((r) => r.action === "error");
   if (failed.length)
     return {
@@ -226,6 +241,48 @@ export function addIntegration(name, { targetRoot = process.cwd(), adopt = false
   return { ok: true, name, adopted: anyForeign ? adopt : true, rows };
 }
 
+/**
+ * After the tool set grows (`forge init --tools …`, `forge tools <name>`) and sync has emitted
+ * the recorded integrations into the new tools' configs, claim those copies by the rule `add`
+ * applies at install time: an entry that is absent or byte-identical to forge's spec is
+ * forge's, a divergent one stays the person's (ME-08). Later spec updates then refresh those
+ * copies and `remove` deletes them. Writes the config only when something new is claimed
+ * (every write leaves a backup), so re-running it is free. Never throws.
+ * @param {string} [targetRoot]
+ * @returns {{claimed: {server:string, target:string}[]}}
+ */
+export function claimEmittedIntegrations(targetRoot = process.cwd()) {
+  const cfg = readForgeConfig(targetRoot);
+  if (cfg.corrupt) return { claimed: [] };
+  const rec = mcpRecord(cfg);
+  const owns = adoptionOwns(rec.adopted);
+  const targets = mcpTargetFilesFor(recordedTools(cfg));
+  const claimed = [];
+  for (const name of rec.integrations) {
+    const m = INTEGRATIONS[name];
+    if (!m) continue;
+    let foreign;
+    try {
+      foreign = foreignTargets(targetRoot, name, m.server);
+    } catch {
+      continue; // an unreadable target: claim nothing for this server
+    }
+    for (const target of targets)
+      if (!owns(target, name) && !foreign.has(target)) claimed.push({ server: name, target });
+  }
+  if (!claimed.length) return { claimed };
+  const w = writeForgeConfig(targetRoot, (c) => {
+    const cur = mcpRecord(c);
+    c.mcp = {
+      ...(typeof c.mcp === "object" && c.mcp ? c.mcp : {}),
+      integrations: cur.integrations,
+      adopted: expandAdopted([...cur.adopted, ...claimed]),
+    };
+    return c;
+  });
+  return w.ok === false ? { claimed: [] } : { claimed };
+}
+
 /**
  * Reverse `add <name>`. ME-10 order: clean every target FIRST (per-server Continue file,
  * forge-marked Codex block, and JSON entries adopted for that target or byte-identical to
diff --git a/src/repo_config.js b/src/repo_config.js
index 811a7f93..a12ffa72 100644
--- a/src/repo_config.js
+++ b/src/repo_config.js
@@ -111,6 +111,18 @@ export function parseTools(value) {
   };
 }
 
+/**
+ * The tool set a repo config records (`tools`, written by `forge init`) as canonical keys, or
+ * null when it records none or `all`: every tool. The one reader shared by sync, integrations
+ * and `forge tools`, so they always emit for the same set. Pure.
+ * @param {Record<string, any>} cfg a parsed repo config (readForgeConfig)
+ * @returns {string[]|null}
+ */
+export function recordedTools(cfg) {
+  const value = cfg?.tools;
+  return typeof value === "string" || Array.isArray(value) ? parseTools(value).tools : null;
+}
+
 // Map a sync-report row's tool label to a canonical tool key. The shared source
 // (AGENTS.md) and any unmapped label return null and are never gitignored.
 /** @type {[string, RegExp][]} */
@@ -300,16 +312,27 @@ export function resolvePrimaryTool(root = process.cwd()) {
   return { tool: null, source: "none" };
 }
 
-/** Persist primaryTool into <root>/.forge/forge.config.json, preserving other keys.
- *  Throws (fail loudly) when the existing file is corrupt JSON — it is never replaced. */
+/** Persist primaryTool into <root>/.forge/forge.config.json, preserving other keys. When
+ *  `forge init` recorded a tool set that lacks the tool, the tool joins it in the same write:
+ *  sync emits only the recorded set, and a primary tool without its own config is a dead end.
+ *  Throws (fail loudly) when the existing file is corrupt JSON — it is never replaced.
+ *  @param {string} root
+ *  @param {string} tool canonical tool key
+ *  @returns {{path:string, addedTool:boolean}} */
 export function setPrimaryTool(root, tool) {
+  let addedTool = false;
   const res = writeForgeConfig(root, (cfg) => {
     cfg.primaryTool = tool;
+    const tools = recordedTools(cfg);
+    if (tools !== null && !tools.includes(tool)) {
+      cfg.tools = Array.isArray(cfg.tools) ? [...cfg.tools, tool] : [...tools, tool];
+      addedTool = true;
+    }
     return cfg;
   });
   // `=== false` (not `!res.ok`): tsc only narrows the discriminated union this way here.
   if (res.ok === false) throw new Error(res.reason);
-  return res.path;
+  return { path: res.path, addedTool };
 }
 
 /**
@@ -369,16 +392,18 @@ export function nonPrimaryTargets(report, primary) {
  * Set `name` as the repo's primary tool and gitignore every other tool's emitted
  * artifacts. The caller injects `syncFn` (the sync runner) so this config-leaf module
  * never imports the sync compiler; the gitignore block reflects what Forge actually emits.
+ * A tool missing from the set `forge init` recorded is added to it first (`addedTool`), so
+ * the sync emits the primary tool's config.
  * @param {string} root
  * @param {string} name canonical primary-tool key (must be in KNOWN_TOOLS)
  * @param {{syncFn?:(root:string)=>Promise<{report:any[]}>|{report:any[]}}} [opts] syncFn is required at runtime
- * @returns {Promise<{primaryTool:string, configPath:string, targets:string[],
- *   gitignore:string, gitignorePath:string}>}
+ * @returns {Promise<{primaryTool:string, configPath:string, addedTool:boolean,
+ *   targets:string[], gitignore:string, gitignorePath:string}>}
  */
 export async function applyPrimaryTool(root, name, { syncFn } = {}) {
   if (!KNOWN_TOOLS.includes(name))
     throw new Error(`unknown tool: ${name} (known: ${KNOWN_TOOLS.join(", ")})`);
-  const cfgFile = setPrimaryTool(root, name);
+  const { path: cfgFile, addedTool } = setPrimaryTool(root, name);
   // syncFn is injected by the caller (cli.js / tests). Required so this config-leaf
   // module never imports the sync compiler — keeping the layering acyclic.
   if (typeof syncFn !== "function")
@@ -389,6 +414,7 @@ export async function applyPrimaryTool(root, name, { syncFn } = {}) {
   return {
     primaryTool: name,
     configPath: cfgFile,
+    addedTool,
     targets,
     gitignore: gi.action,
     gitignorePath: gi.path,
diff --git a/test/init_tools.test.js b/test/init_tools.test.js
index b4065828..59931caa 100644
--- a/test/init_tools.test.js
+++ b/test/init_tools.test.js
@@ -16,15 +16,23 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
 import { fileURLToPath } from "node:url";
-import { emitMcp } from "../src/emit/mcp.js";
+import { emitMcp, MCP_TARGET_FILES, mcpTargetFilesFor } from "../src/emit/mcp.js";
 import { init, resolveInitTools } from "../src/init.js";
-import { addIntegration } from "../src/integrations.js";
 import {
+  addIntegration,
+  claimEmittedIntegrations,
+  INTEGRATIONS,
+  planIntegration,
+  removeIntegration,
+} from "../src/integrations.js";
+import {
+  applyPrimaryTool,
   clearRepoConfig,
   detectTools,
   KNOWN_TOOLS,
   parseTools,
   readForgeConfig,
+  recordedTools,
   writeForgeConfig,
 } from "../src/repo_config.js";
 import { sync } from "../src/sync.js";
@@ -175,6 +183,134 @@ test("integrations add honours the recorded tool set (no config for unused tools
   for (const p of OTHER_TOOL_PATHS) assert.ok(!existsSync(join(root, p)), `${p} not created`);
 });
 
+// ---------------------------------------------------------------------------
+// Review follow-ups: ownership stays per written target; the set grows safely
+// ---------------------------------------------------------------------------
+
+const readJson = (p) => JSON.parse(readFileSync(p, "utf8"));
+const configBackups = (root) =>
+  readdirSync(join(root, ".forge")).filter((f) => f.includes("forge-bak")).length;
+
+test("recordedTools, mcpTargetFilesFor and planIntegration agree on the tool set", () => {
+  assert.equal(recordedTools({}), null, "nothing recorded = every tool");
+  assert.equal(recordedTools({ tools: "all" }), null);
+  assert.deepEqual(recordedTools({ tools: ["cursor", "claude", "nope"] }), ["claude", "cursor"]);
+  assert.deepEqual(recordedTools({ tools: "copilot" }), ["vscode"]);
+  assert.deepEqual(mcpTargetFilesFor(["claude", "codex", "aider"]), [
+    ".mcp.json",
+    ".codex/config.toml",
+  ]);
+  assert.deepEqual(mcpTargetFilesFor(null), MCP_TARGET_FILES);
+
+  const root = fixture();
+  writeForgeConfig(root, (c) => ({ ...c, tools: ["claude", "continue"] }));
+  assert.deepEqual(planIntegration("context7", { targetRoot: root }).writes, [
+    ".mcp.json",
+    ".continue/mcpServers/forge-context7.yaml",
+  ]);
+  const everyTool = planIntegration("context7", { targetRoot: fixture() }).writes;
+  assert.deepEqual(everyTool, [...MCP_TARGET_FILES, ".continue/mcpServers/forge-context7.yaml"]);
+});
+
+test("integrations add owns only the targets it wrote; a person's entry in a later tool stays theirs", () => {
+  const root = fixture();
+  init({ targetRoot: root, noSettings: true }); // records ["claude"]
+  assert.equal(addIntegration("context7", { targetRoot: root }).ok, true);
+  assert.deepEqual(readForgeConfig(root).mcp.adopted, [
+    { server: "context7", target: ".mcp.json" },
+  ]);
+
+  // Later the person configures their own context7 for Cursor, then enables Cursor.
+  const mine = { command: "my-context7", args: ["--local"] };
+  const cursorPath = join(root, ".cursor", "mcp.json");
+  mkdirSync(join(root, ".cursor"), { recursive: true });
+  writeFileSync(cursorPath, JSON.stringify({ mcpServers: { context7: mine } }));
+  init({ targetRoot: root, noSettings: true, tools: "claude,cursor" });
+  assert.deepEqual(readJson(cursorPath).mcpServers.context7, mine, "not overwritten");
+  assert.ok(readJson(cursorPath).mcpServers["forge-cortex"], "forge's own server sits beside it");
+  assert.ok(
+    !readForgeConfig(root).mcp.adopted.some((a) => a.target === ".cursor/mcp.json"),
+    "a divergent entry forge did not write is never claimed",
+  );
+
+  const rm = removeIntegration("context7", { targetRoot: root });
+  assert.equal(rm.ok && rm.removed, true);
+  assert.deepEqual(readJson(cursorPath).mcpServers.context7, mine, "remove leaves it in place");
+  assert.equal(
+    readJson(join(root, ".mcp.json")).mcpServers.context7,
+    undefined,
+    "forge's copy gone",
+  );
+});
+
+test("a tool that joins the set later gets the integration, owned like an add would own it", () => {
+  const root = fixture();
+  init({ targetRoot: root, noSettings: true });
+  addIntegration("context7", { targetRoot: root });
+  init({ targetRoot: root, noSettings: true, tools: "claude,cursor" });
+  const cursorPath = join(root, ".cursor", "mcp.json");
+  assert.deepEqual(readJson(cursorPath).mcpServers.context7, INTEGRATIONS.context7.server);
+  assert.ok(
+    readForgeConfig(root).mcp.adopted.some(
+      (a) => a.server === "context7" && a.target === ".cursor/mcp.json",
+    ),
+    "claimed: forge wrote it",
+  );
+
+  // Claiming again finds nothing new and writes no config (no backup churn).
+  const before = configBackups(root);
+  assert.deepEqual(claimEmittedIntegrations(root), { claimed: [] });
+  init({ targetRoot: root, noSettings: true });
+  assert.equal(configBackups(root), before);
+
+  // Owned, so a spec update reaches it and remove deletes it.
+  const stale = readJson(cursorPath);
+  stale.mcpServers.context7 = { command: "npx", args: ["-y", "@upstash/context7-mcp@3.0.0"] };
+  writeFileSync(cursorPath, JSON.stringify(stale));
+  sync({ targetRoot: root });
+  assert.deepEqual(readJson(cursorPath).mcpServers.context7, INTEGRATIONS.context7.server);
+  removeIntegration("context7", { targetRoot: root });
+  assert.equal(readJson(cursorPath).mcpServers.context7, undefined);
+});
+
+test("`forge tools <name>` adds the tool to the recorded set, so its config is emitted", async () => {
+  const root = fixture();
+  init({ targetRoot: root, noSettings: true }); // records ["claude"]
+  const syncFn = (dir) => sync({ targetRoot: dir });
+  const r = await applyPrimaryTool(root, "cursor", { syncFn });
+  assert.equal(r.addedTool, true);
+  assert.deepEqual(readForgeConfig(root).tools, ["claude", "cursor"]);
+  assert.equal(readForgeConfig(root).primaryTool, "cursor");
+  assert.ok(existsSync(join(root, ".cursor", "mcp.json")), "the primary tool has its MCP config");
+  assert.ok(!r.targets.includes(".cursor/mcp.json"), "and it stays tracked");
+  assert.equal((await applyPrimaryTool(root, "cursor", { syncFn })).addedTool, false);
+
+  // No recorded set means every tool is emitted already: nothing is added or recorded.
+  const open = fixture();
+  const o = await applyPrimaryTool(open, "cursor", { syncFn: () => ({ report: [] }) });
+  assert.equal(o.addedTool, false);
+  assert.equal(readForgeConfig(open).tools, undefined);
+});
+
+test("CLI: `forge tools <name>` after a default init emits the tool and owns its integration copy", () => {
+  const env = { ...process.env, FORGE_NO_HINT: "1" };
+  const root = fixture();
+  const run = (...args) => spawnSync("node", [CLI, ...args], { cwd: root, encoding: "utf8", env });
+  assert.equal(run("init", "--no-settings").status, 0);
+  assert.equal(addIntegration("context7", { targetRoot: root }).ok, true);
+  const dry = run("integrations", "add", "context7");
+  assert.match(dry.stdout, /writes: {2}\.mcp\.json\n/, "the dry run lists only the recorded tools");
+
+  const res = run("tools", "cursor");
+  assert.equal(res.status, 0, res.stderr);
+  assert.match(res.stdout, /cursor added to the tools `forge init` recorded/);
+  assert.ok(readJson(join(root, ".cursor", "mcp.json")).mcpServers.context7);
+  assert.ok(
+    readForgeConfig(root).mcp.adopted.some((a) => a.target === ".cursor/mcp.json"),
+    "the new copy is forge's",
+  );
+});
+
 test("`forge tools --reset` keeps the recorded emit set (clearRepoConfig drops primaryTool only)", () => {
   const root = fixture();
   writeForgeConfig(root, (cfg) => ({ ...cfg, primaryTool: "claude", tools: ["claude"] }));