docs: add foreign-regions reference and mark plan complete

Document the foreign-regions: config key, its override scoping, the
opacity contract, and the MDS073 malformed-region diagnostic. Regenerate
the CLAUDE.md, reference-index, AGENTS.md, and copilot-instructions
catalogs/includes, and mark plan 2607082049 done.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwKxDxhjkTQPPkBrNhsrNG

Author: claude

.github/copilot-instructions.md

@@ -141,6 +141,7 @@ row: "- [{summary}](../{filename})"
 - [Print the mdsmith build version and exit.](../docs/reference/cli/version.md)
 - [Each file under `.mdsmith/conventions/` declares one user convention. The basename is the convention name; the file body carries a `flavor:` plus a `rules:` map. Sits alongside inline `conventions.<name>:` in `.mdsmith.yml`.](../docs/reference/convention-files.md)
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](../docs/reference/conventions.md)
+- [The top-level `foreign-regions:` config lists `{start, end}` marker pairs whose spanned bytes mdsmith treats as opaque — style rules skip diagnostics inside a matched pair and fixers never rewrite it, while whole-file rules still count the bytes. Glob-scopable via `overrides:`; a start with no matching end reports MDS073.](../docs/reference/foreign-regions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](../docs/reference/globs.md)
 - [Look up exact CLI commands, config glob and schema syntax, the built-in conventions, and the section-schema grammar.](../docs/reference/index.md)
 - [Each file under `.mdsmith/kinds/` declares one kind. The basename is the kind name; the file body carries the full `KindBody` — schema, rules, `path-pattern:`, `extends:`. Sits alongside inline `kinds.<name>:` in `.mdsmith.yml`.](../docs/reference/kind-files.md)

AGENTS.md

@@ -147,6 +147,7 @@ row: "- [{summary}]({filename})"
 - [Print the mdsmith build version and exit.](docs/reference/cli/version.md)
 - [Each file under `.mdsmith/conventions/` declares one user convention. The basename is the convention name; the file body carries a `flavor:` plus a `rules:` map. Sits alongside inline `conventions.<name>:` in `.mdsmith.yml`.](docs/reference/convention-files.md)
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](docs/reference/conventions.md)
+- [The top-level `foreign-regions:` config lists `{start, end}` marker pairs whose spanned bytes mdsmith treats as opaque — style rules skip diagnostics inside a matched pair and fixers never rewrite it, while whole-file rules still count the bytes. Glob-scopable via `overrides:`; a start with no matching end reports MDS073.](docs/reference/foreign-regions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](docs/reference/globs.md)
 - [Look up exact CLI commands, config glob and schema syntax, the built-in conventions, and the section-schema grammar.](docs/reference/index.md)
 - [Each file under `.mdsmith/kinds/` declares one kind. The basename is the kind name; the file body carries the full `KindBody` — schema, rules, `path-pattern:`, `extends:`. Sits alongside inline `kinds.<name>:` in `.mdsmith.yml`.](docs/reference/kind-files.md)

CLAUDE.md

@@ -133,6 +133,7 @@ row: "- [{summary}]({filename})"
 - [Print the mdsmith build version and exit.](docs/reference/cli/version.md)
 - [Each file under `.mdsmith/conventions/` declares one user convention. The basename is the convention name; the file body carries a `flavor:` plus a `rules:` map. Sits alongside inline `conventions.<name>:` in `.mdsmith.yml`.](docs/reference/convention-files.md)
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](docs/reference/conventions.md)
+- [The top-level `foreign-regions:` config lists `{start, end}` marker pairs whose spanned bytes mdsmith treats as opaque — style rules skip diagnostics inside a matched pair and fixers never rewrite it, while whole-file rules still count the bytes. Glob-scopable via `overrides:`; a start with no matching end reports MDS073.](docs/reference/foreign-regions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](docs/reference/globs.md)
 - [Look up exact CLI commands, config glob and schema syntax, the built-in conventions, and the section-schema grammar.](docs/reference/index.md)
 - [Each file under `.mdsmith/kinds/` declares one kind. The basename is the kind name; the file body carries the full `KindBody` — schema, rules, `path-pattern:`, `extends:`. Sits alongside inline `kinds.<name>:` in `.mdsmith.yml`.](docs/reference/kind-files.md)

PLAN.md

@@ -247,7 +247,7 @@ footer: |
 | 2607051920 | ✅     | sonnet | [Consolidate duplicated leading-space/blank-line rule helpers into internal/rules/astutil](plan/2607051920_arch-fix-rule-whitespace-helpers-astutil.md) |
 | 2607071642 | ✅     | sonnet | [Single-file metric extraction via `mdsmith metrics get` (readability first)](plan/2607071642_extractable-file-metrics.md)                              |
 | 2607082048 | ✅     | sonnet | [Placeholder token for APM `${input:name}` prompt parameters](plan/2607082048_apm-input-placeholder-token.md)                                           |
-| 2607082049 | 🔲     | opus   | [Foreign managed-region protection for `mdsmith fix`](plan/2607082049_foreign-managed-regions.md)                                                       |
+| 2607082049 | ✅     | opus   | [Foreign managed-region protection for `mdsmith fix`](plan/2607082049_foreign-managed-regions.md)                                                       |
 | 2607082050 | 🔲     | sonnet | [APM coexistence: `mdsmith init --apm`, guide, and kind pack](plan/2607082050_apm-coexist-guide-and-kind-pack.md)                                       |
 | 2607082051 | 🔲     | opus   | [Schema extensions: closed frontmatter and filename agreement](plan/2607082051_apm-schema-extensions.md)                                                |
 | 2607082052 | ✅     | sonnet | [SARIF output format for `mdsmith check`](plan/2607082052_check-sarif-output.md)                                                                        |

docs/reference/foreign-regions.md

@@ -0,0 +1,98 @@
+---
+weight: 30
+summary: >-
+  The top-level `foreign-regions:` config lists `{start, end}` marker
+  pairs whose spanned bytes mdsmith treats as opaque — style rules skip
+  diagnostics inside a matched pair and fixers never rewrite it, while
+  whole-file rules still count the bytes. Glob-scopable via `overrides:`;
+  a start with no matching end reports MDS073.
+---
+# Foreign regions
+
+A **foreign region** is a span of a Markdown file that another
+generator owns. The top-level `foreign-regions:` key lists the marker
+pairs that bound such spans, so `mdsmith fix` leaves those bytes
+byte-for-byte unchanged and the style rules raise no diagnostics inside
+them. The first case is [APM][apm], whose `managed_section` mode writes
+a block bounded by `<!-- apm:start -->` and `<!-- apm:end -->` and pins
+a SHA-256 of the file; any reflow inside that block trips its drift
+check.
+
+This is the same exclusion the [generated-section engine][gensection]
+applies to `<?include?>` and `<?catalog?>` bodies. The difference is
+ownership: mdsmith regenerates its own directive bodies, but never
+touches a foreign region — the owning tool regenerates it.
+
+## Configuration
+
+Declare each marker pair under `foreign-regions:`. mdsmith matches
+`start` and `end` against whole lines with surrounding whitespace
+trimmed. A marker may be indented, but it must sit on its own line:
+
+```yaml
+foreign-regions:
+  - start: "<!-- apm:start -->"
+    end: "<!-- apm:end -->"
+```
+
+Both markers must be non-empty and must differ from each other; a pair
+that violates either rule is a config error.
+
+### Scoping to a subtree
+
+`foreign-regions:` is glob-scopable through
+[`overrides:`](globs.md). An override's `foreign-regions:` list is
+**appended** to the top-level list for every file its glob matches — it
+never replaces the global pairs. Use this to protect an extra marker
+pair that only appears under one path:
+
+```yaml
+foreign-regions:
+  - start: "<!-- apm:start -->"
+    end: "<!-- apm:end -->"
+overrides:
+  - glob: ["AGENTS.md"]
+    foreign-regions:
+      - start: "<!-- gen:start -->"
+        end: "<!-- gen:end -->"
+```
+
+## What the region protects
+
+mdsmith scans each file for every declared marker pair. It records the
+span from a `start` line through its matching `end` line. The markers
+themselves are part of the span.
+
+| Surface                           | Behavior inside a matched region                                                           |
+| --------------------------------- | ------------------------------------------------------------------------------------------ |
+| `mdsmith fix`                     | Bytes round-trip unchanged, even otherwise-fixable trailing spaces and table misalignment. |
+| Style and content rules           | Emit no diagnostics; the same violation outside the region still fires.                    |
+| Whole-file rules (MDS022, MDS028) | Still count the region's bytes toward file length and token budget.                        |
+
+Whole-file rules read the raw source. A large foreign region still
+counts against `max-file-length` and `token-budget`. The region is
+opaque to editing, not invisible to size accounting.
+
+## Malformed regions (MDS073)
+
+APM requires each marker exactly once. mdsmith reports **MDS073** on a
+malformed region and protects no bytes for it:
+
+| Condition                                       | Reported on                |
+| ----------------------------------------------- | -------------------------- |
+| A `start` marker with no matching `end`         | the `start` line           |
+| An `end` marker with no preceding `start`       | the `end` line             |
+| A second `start` before the first region closes | the duplicate `start` line |
+
+## Non-goals
+
+- **Regenerating the region.** mdsmith treats it as opaque; the owning
+  tool regenerates it.
+- **Resolving merge conflicts inside it.** The
+  [merge driver](cli/merge-driver.md) stays scoped to mdsmith's own
+  directive blocks.
+- **Auto-detecting markers.** Regions are declared in config, never
+  inferred.
+
+[apm]: ../research/apm-mdsmith/apm-model.md
+[gensection]: ../background/concepts/generated-section.md

docs/reference/index.md

@@ -37,6 +37,7 @@ row: "- [{summary}]({filename})"
 - [Print the mdsmith build version and exit.](cli/version.md)
 - [Each file under `.mdsmith/conventions/` declares one user convention. The basename is the convention name; the file body carries a `flavor:` plus a `rules:` map. Sits alongside inline `conventions.<name>:` in `.mdsmith.yml`.](convention-files.md)
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](conventions.md)
+- [The top-level `foreign-regions:` config lists `{start, end}` marker pairs whose spanned bytes mdsmith treats as opaque — style rules skip diagnostics inside a matched pair and fixers never rewrite it, while whole-file rules still count the bytes. Glob-scopable via `overrides:`; a start with no matching end reports MDS073.](foreign-regions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](globs.md)
 - [Each file under `.mdsmith/kinds/` declares one kind. The basename is the kind name; the file body carries the full `KindBody` — schema, rules, `path-pattern:`, `extends:`. Sits alongside inline `kinds.<name>:` in `.mdsmith.yml`.](kind-files.md)
 - [Every markdownlint rule and the mdsmith rule that covers it, generated from the rule README front matter — the same data `mdsmith init --from-markdownlint` reads.](markdownlint-mapping.md)

plan/2607082049_foreign-managed-regions.md

@@ -1,7 +1,7 @@
 ---
 id: 2607082049
 title: "Foreign managed-region protection for `mdsmith fix`"
-status: "🔳"
+status: "✅"
 model: opus
 summary: >-
   Add a `foreign-regions:` config listing `{start, end}` marker
@@ -87,20 +87,20 @@ metrics still count those bytes.
 
 ## Acceptance Criteria
 
-- [ ] `mdsmith fix` leaves bytes between a declared
+- [x] `mdsmith fix` leaves bytes between a declared
       `{start, end}` pair unchanged, including
       otherwise-fixable trailing spaces and table
       misalignment.
-- [ ] A style-rule violation inside the region emits
+- [x] A style-rule violation inside the region emits
       no diagnostic; the same violation outside it
       still does.
-- [ ] MDS022 and MDS028 still count the region's
+- [x] MDS022 and MDS028 still count the region's
       bytes toward file length and token budget.
-- [ ] A start marker with no matching end marker
+- [x] A start marker with no matching end marker
       produces a diagnostic.
-- [ ] The region config is glob-scopable via
+- [x] The region config is glob-scopable via
       `overrides:`.
-- [ ] All tests pass: `go test ./...`
-- [ ] `go tool -modfile=tools/go.mod golangci-lint
+- [x] All tests pass: `go test ./...`
+- [x] `go tool -modfile=tools/go.mod golangci-lint
       run` reports no issues.
-- [ ] `mdsmith check .` — 0 failures.
+- [x] `mdsmith check .` — 0 failures.