[thekevinbot]

The /migrations page on the docs site is being removed because it only surfaced pre-fragment migration history via a VitePress include. Since the project now uses per-package migration fragments (one file per breaking change under packages/*/migrations.d/), a page built from the frozen root MIGRATIONS.md would silently omit all current migrations and present an incomplete, misleading upgrade guide.

Fixes #885

Changes:

• Deleted docs/migrations.md (the VitePress include wrapper)
• Removed the "Migrations" link from the docs site navigation (docs/.vitepress/config.ts)
• Updated documentation references to clarify that:
  • Pre-fragment history is frozen in the root MIGRATIONS.md (not published)
  • Current migrations live as fragments under each package's migrations.d/ directory
  • The canonical explanation is in AGENTS.md under "Changelog and Migrations"
• Simplified links in MIGRATIONS.md and package MIGRATIONS.md files to remove references to the now-removed /migrations page
• Updated README.md to point users to the per-package migration fragments instead of a single docs page
• Removed MIGRATIONS.md from the docs release workflow trigger (no longer published)
• Updated agents/reference/changelog-migrations.md to explain why the frozen file is not published

This aligns the docs site with the actual migration workflow where contributors add fragments to their package's migrations.d/ directory rather than editing a central file.

The alternative considered — aggregating packages/*/migrations.d/*.md into the page at build time — is recorded in agents/reference/changelog-migrations.md as the option not taken: it needs a build step and a fragment ordering convention.

Every file touched beyond docs/ linked to the page being deleted; without those edits the change would leave dead links in README.md, all four MIGRATIONS.md pointer stubs, and two agent docs. Editing the frozen MIGRATIONS.md files here removes a dead pointer rather than appending an entry, so it does not cross the freeze rule.

Manual verification

• pnpm build in docs/ — clean. VitePress fails the build on dead links, so this is what proves the sidebar entry removal is complete. The built dist/ contains no migrations.html and zero occurrences of "migrations".
• Ran the built site: npx vitepress preview --port 5199.
  • curl -o /dev/null -w '%{http_code}' http://127.0.0.1:5199/dirsql/migrations → 404
  • The rendered sidebar on /dirsql/reference/sdk.html lists every other reference page (CLI, Configuration File, Command Hooks, Columns, Path-tables, HTTP API, SDK) and no Migrations entry.
• e2e verify run locally with CI-equivalent scoping for both bindings → exit 0, so the committed attestations stay fresh (nothing under packages/*/src changed):
  uvx testing-conventions e2e verify --base ddb7208 --scope packages/python/dirsql --extra-scope packages/rust/src packages/python
• changelog-gate run locally over this diff → exit 0.

E2E Verification

N/A - docs/lint/typo only

Changelog / Migrations

• Changelog fragment added under packages/<pkg>/changelog.d/ for each changed package (or: skip-changelog trailer on a commit with reason) — not required: the only files touched under packages/ are the MIGRATIONS.md pointer stubs, which changelog_gate's _is_exempt excludes from code_touched. Verified by running the gate locally over this diff (exit 0).
• Migration fragment added under packages/<pkg>/migrations.d/ (or: not required — additive/bugfix only) — not required: no public API, config key, CLI flag, or runtime behavior changes.

PARITY.md is unchanged: no SDK public API surface is touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_014Wb5FG2GSbcfUMothCFZej