diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 63000d7c..f7b281be 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -533,7 +533,21 @@ 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>`. 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 8fed101a..e6605ef5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,49 @@ 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.
+- **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.
+
+### 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 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.2] - 2026-09-24
 
 ### Fixed
diff --git a/ONBOARDING.md b/ONBOARDING.md
index 384d378d..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"]
@@ -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 66c785bd..38516c4f 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
 ```
 
@@ -388,6 +388,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.
@@ -400,7 +409,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 dafce55f..0dc4d446 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:
@@ -806,10 +806,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 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/`,
@@ -820,7 +824,9 @@ tools` fixes that without changing what `sync` emits.
   `.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
@@ -1315,14 +1321,14 @@ 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`. 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).                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
@@ -1720,7 +1726,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/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 52b462f4..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,27 +126,32 @@ 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. 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` and, when it already exists, Continue's forge-owned
+`.continue/rules/00-forge.md`; MCP config is repaired by `forge sync`.)
 
 ### `--adopt` semantics
 
@@ -154,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/cli/core.mdx b/mintlify/cli/core.mdx
index 72736b7b..17ac93c0 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,21 @@ 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).
+
+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/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 9ac36113..2ab8451d 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}` : ""}`,
@@ -571,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;
@@ -579,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`,
@@ -2944,12 +2970,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/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 e70f7eec..40afbf48 100644
--- a/src/cortex_hook_main.js
+++ b/src/cortex_hook_main.js
@@ -106,8 +106,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..1dccf1f8 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, strandedAgentsBackup, sync } from "./sync.js";
 import { updateStatus } from "./update.js";
 
 const ok = (label, note = "") => ({ status: "ok", label, note });
@@ -539,27 +539,47 @@ 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]());
+  // 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 e98110eb..aa4453c5 100644
--- a/src/emit/_shared.js
+++ b/src/emit/_shared.js
@@ -45,3 +45,91 @@ 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);
+
+/** 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(MARKER_LINE_RE, " $&").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..0d85c4db 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");
@@ -49,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`;
 
 // ---------------------------------------------------------------------------
@@ -400,13 +416,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 +436,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..618bb31f 100644
--- a/src/init.js
+++ b/src/init.js
@@ -14,9 +14,17 @@ 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 { 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 +744,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 +762,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 +823,7 @@ export function init({
   settingsOnly = false,
   settingsPath,
   onSettingsNotice,
+  tools,
 } = {}) {
   if (settingsOnly) {
     return {
@@ -783,13 +840,22 @@ 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" });
+  // 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);
@@ -799,7 +865,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..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 { 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,16 +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.
-  const rows = emitMcp({ targetRoot, servers, owns });
+  const rows = emitMcp({ targetRoot, servers, owns, tools });
   const failed = rows.filter((r) => r.action === "error");
   if (failed.length)
     return {
@@ -222,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 54a42a99..a12ffa72 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,70 @@ 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)))],
+  };
+}
+
+/**
+ * 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][]} */
@@ -247,23 +312,35 @@ 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 };
 }
 
 /**
- * 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 +353,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`);
   }
@@ -316,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")
@@ -336,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/src/sync.js b/src/sync.js
index c6ff8b04..00abe3b9 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,27 +162,174 @@ 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 };
+  };
+  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)",
+    );
+  }
+  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.",
+      ].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",
+  };
+}
+
+/**
+ * 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
+ * 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 });
+  // 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,
@@ -185,11 +338,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 +357,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 +367,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 +380,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,14 +391,21 @@ 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);
+  const stranded = strandedAgentsBackup(targetRoot);
+  if (stranded) warnings.push(stranded);
+  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(
       `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
@@ -256,7 +417,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 +433,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..c4cf0c61
--- /dev/null
+++ b/test/agents_block.test.js
@@ -0,0 +1,367 @@
+// 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,
+  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);
+
+/** 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.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
+// ---------------------------------------------------------------------------
+
+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..59931caa
--- /dev/null
+++ b/test/init_tools.test.js
@@ -0,0 +1,361 @@
+// 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, MCP_TARGET_FILES, mcpTargetFilesFor } from "../src/emit/mcp.js";
+import { init, resolveInitTools } from "../src/init.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";
+
+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`);
+});
+
+// ---------------------------------------------------------------------------
+// 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"] }));
+  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");