diff --git a/.github/workflows/docs-release.yml b/.github/workflows/docs-release.yml
index ecc7ab81f..c45321e3a 100644
--- a/.github/workflows/docs-release.yml
+++ b/.github/workflows/docs-release.yml
@@ -8,7 +8,6 @@ on:
     branches: [main]
     paths:
       - 'docs/**'
-      - 'MIGRATIONS.md'
       - '.github/workflows/docs-release.yml'
   workflow_dispatch:
 
diff --git a/MIGRATIONS.md b/MIGRATIONS.md
index ff1e48f0d..c4274a304 100644
--- a/MIGRATIONS.md
+++ b/MIGRATIONS.md
@@ -9,11 +9,9 @@ migration entries are **per-package fragments** under
 five-subsection entry — so PRs never conflict on a shared file. See each
 package's `MIGRATIONS.md` (`packages/python`, `packages/ts`, `packages/rust`)
 and AGENTS.md, "Changelog and Migrations". This frozen archive is still the
-source of truth for the pre-fragment history; the docs site
-([Migrations](https://thekevinscott.github.io/dirsql/migrations)) surfaces it
-via a VitePress include — do not edit the rendered page.
+source of truth for the pre-fragment history.
 
-See also: [`CHANGELOG.md`](https://github.com/thekevinscott/dirsql/blob/main/CHANGELOG.md) for the full release log. (The relative path is not used because this file is also included into the docs site via a VitePress include, where relative paths would break.)
+See also: [`CHANGELOG.md`](CHANGELOG.md) for the full release log.
 
 ## Frozen history (pre-fragment)
 
diff --git a/README.md b/README.md
index 286ac4fa5..6be05dc43 100644
--- a/README.md
+++ b/README.md
@@ -84,7 +84,7 @@ The canonical facts -- flags, schemas, contracts, and API shapes:
 - [Stat columns & glob captures](docs/reference/columns.md) -- `path`, `basename`, `dir`, `ext`, `size`, `mtime`, `ctime`, and `{name}` captures
 - [HTTP API](docs/reference/http-api.md) -- `POST /query`, `GET /events`, errors
 - [SDK](docs/reference/sdk.md) -- `DirSQL`, `Table`, and `RowEvent` across Python, Rust, and TypeScript
-- [Migrations](docs/migrations.md) -- upgrade notes for breaking changes; the canonical source is [`MIGRATIONS.md`](MIGRATIONS.md) at the repo root
+- Migrations -- upgrade notes for breaking changes, one file per change under each package's `migrations.d/` ([python](packages/python/migrations.d/), [rust](packages/rust/migrations.d/), [ts](packages/ts/migrations.d/)); pre-fragment history is frozen in [`MIGRATIONS.md`](MIGRATIONS.md) at the repo root
 
 ## Explanation
 
diff --git a/agents/reference/changelog-migrations.md b/agents/reference/changelog-migrations.md
index 0500498ae..740fcd5fe 100644
--- a/agents/reference/changelog-migrations.md
+++ b/agents/reference/changelog-migrations.md
@@ -47,7 +47,7 @@ Migration fragments are per-package too, one file per changed package under `pac
 
 If a subsection does not apply, keep the heading and write `_None._`. Do not omit subsections. The template lives at the bottom of the frozen root `MIGRATIONS.md`.
 
-The frozen root `MIGRATIONS.md` is surfaced on the docs site at `/migrations` via a VitePress include (`docs/migrations.md`). Do not edit the rendered page.
+The frozen root `MIGRATIONS.md` is not published on the docs site: it holds only pre-fragment history, so a page built from it silently omits every migration written under the fragment convention -- an upgrade guide that looks authoritative and is not (#885). Aggregating `packages/*/migrations.d/*.md` into a page at build time is the option not taken; it needs a build step and a fragment ordering convention.
 
 **PR body requirement:** PRs that touch SDK code must contain the following block (checkboxes filled in):
 
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index bccf8c053..cd610f937 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -72,8 +72,7 @@ export default defineConfig({
             { text: 'Columns', link: '/reference/columns' },
             { text: 'Path-tables', link: '/reference/path-tables' },
             { text: 'HTTP API', link: '/reference/http-api' },
-            { text: 'SDK', link: '/reference/sdk' },
-            { text: 'Migrations', link: '/migrations' }
+            { text: 'SDK', link: '/reference/sdk' }
           ]
         },
         {
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index 6f30bb723..676d5d422 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -60,15 +60,13 @@ migrated -- a page survives only if a slot wants its content):
   protocol, exit codes, timeouts); the columns model (named tables get their
   hook's output; path-tables get stat columns); the
   HTTP API; the SDK page (`reference/sdk.md`, one page with
-  Python/TypeScript/Rust code-groups -- the sole SDK home); plus the
-  Migrations include (`migrations.md`).
+  Python/TypeScript/Rust code-groups -- the sole SDK home).
 - **Explanation** (`explanation.md`) -- one page: how `dirsql` thinks (the
   filesystem is the source of truth; the database is a derived, ephemeral,
   read-only view; reconcile and diffing). Its canonical home is the root
-  `ARCHITECTURE.md`;
-  #374 surfaces it via an include page, the same mechanism
-  `docs/migrations.md` uses for `MIGRATIONS.md`. Edit the root file, never
-  a rendered include.
+  `ARCHITECTURE.md`; #374 surfaces it via a VitePress include
+  (`<!--@include: ../ARCHITECTURE.md-->`). Edit the root file, never a
+  rendered include.
 
 Working rules:
 
diff --git a/docs/migrations.md b/docs/migrations.md
deleted file mode 100644
index 0f3e6867c..000000000
--- a/docs/migrations.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-title: Migrations
----
-
-<!--@include: ../MIGRATIONS.md-->
diff --git a/packages/python/MIGRATIONS.md b/packages/python/MIGRATIONS.md
index da2b990ef..dcc5b932e 100644
--- a/packages/python/MIGRATIONS.md
+++ b/packages/python/MIGRATIONS.md
@@ -7,5 +7,4 @@ Migration entries for this package live as one file per breaking change under
 Nothing is assembled back into this file.
 
 Pre-fragment history (all packages) is frozen in the repository-root
-[`MIGRATIONS.md`](../../MIGRATIONS.md), surfaced on the docs site at
-[`/migrations`](https://thekevinscott.github.io/dirsql/migrations).
+[`MIGRATIONS.md`](../../MIGRATIONS.md).
diff --git a/packages/rust/MIGRATIONS.md b/packages/rust/MIGRATIONS.md
index 58a8fcb98..720b4fa71 100644
--- a/packages/rust/MIGRATIONS.md
+++ b/packages/rust/MIGRATIONS.md
@@ -7,5 +7,4 @@ Migration entries for this package live as one file per breaking change under
 Nothing is assembled back into this file.
 
 Pre-fragment history (all packages) is frozen in the repository-root
-[`MIGRATIONS.md`](../../MIGRATIONS.md), surfaced on the docs site at
-[`/migrations`](https://thekevinscott.github.io/dirsql/migrations).
+[`MIGRATIONS.md`](../../MIGRATIONS.md).
diff --git a/packages/ts/MIGRATIONS.md b/packages/ts/MIGRATIONS.md
index 13a868892..27f1feebb 100644
--- a/packages/ts/MIGRATIONS.md
+++ b/packages/ts/MIGRATIONS.md
@@ -7,5 +7,4 @@ Migration entries for this package live as one file per breaking change under
 Nothing is assembled back into this file.
 
 Pre-fragment history (all packages) is frozen in the repository-root
-[`MIGRATIONS.md`](../../MIGRATIONS.md), surfaced on the docs site at
-[`/migrations`](https://thekevinscott.github.io/dirsql/migrations).
+[`MIGRATIONS.md`](../../MIGRATIONS.md).