docs: restructure migration guide — codemod-first, two-journey split, SKILL folded into upgrade-to-v2 (#2360)

Author: felixweinberger

.changeset/codec-split-wire-break.md

@@ -4,7 +4,7 @@
 '@modelcontextprotocol/server': major
 ---
 
-Split the wire layer into per-era codecs and make protocol-revision deletions physical. Deliberate wire/schema behavior changes (see docs/migration.md "Per-era wire codecs"):
+Split the wire layer into per-era codecs and make protocol-revision deletions physical. Deliberate wire/schema behavior changes (see docs/migration/support-2026-07-28.md "Per-era wire codecs"):
 
 - `resultType` is no longer modeled by any neutral wire schema: `EmptyResultSchema` (strict) now rejects `{resultType}` bodies; on 2025-era connections a foreign `resultType` is stripped before validation instead of rejected; the member exists only inside the 2026-era codec, which requires it.
 - `CallToolResult.content` / `ToolResultContent.content` are required at the wire boundary (`content.default([])` removed): handler results without `content` are rejected with `-32602` instead of silently defaulted, and content-less wire results fail the client parse loudly.

.changeset/hide-wire-only-members.md

@@ -4,4 +4,4 @@
 '@modelcontextprotocol/server': major
 ---
 
-Hide wire-only protocol members from the public surface, at the type level and at runtime. `resultType` (the 2026-07-28 result discrimination field) is no longer declared on any public result type — the wire schemas keep parsing it, and the client funnel now consumes it raw-first: `'complete'` results are stripped to the public shape and any other kind (e.g. `input_required`) rejects with the new `SdkErrorCode.UnsupportedResultType` instead of masking into an empty success. The reserved `_meta` envelope keys are lifted out of inbound requests and notifications before handlers run, and the multi-round-trip retry fields (`inputResponses`, `requestState`) out of inbound requests only (the spec reserves those names on client-initiated requests; notification params keep them), so handler params keep the 2025-era shape; for requests the lifted material surfaces at `ctx.mcpReq.envelope`, `ctx.mcpReq.inputResponses`, and `ctx.mcpReq.requestState` (notifications have no ctx — their lifted envelope keys are not surfaced). High-level client/server methods now return the named public result types (`Promise<CallToolResult>` etc.). Task wire vocabulary stays importable but is `@deprecated` and excluded from the typed method maps (`RequestMethod`/`RequestTypeMap`/`ResultTypeMap`/`NotificationTypeMap`), and `callTool` is typed as plain `CallToolResult`. See docs/migration.md "Wire-only protocol members hidden from the public types".
+Hide wire-only protocol members from the public surface, at the type level and at runtime. `resultType` (the 2026-07-28 result discrimination field) is no longer declared on any public result type — the wire schemas keep parsing it, and the client funnel now consumes it raw-first: `'complete'` results are stripped to the public shape and any other kind (e.g. `input_required`) rejects with the new `SdkErrorCode.UnsupportedResultType` instead of masking into an empty success. The reserved `_meta` envelope keys are lifted out of inbound requests and notifications before handlers run, and the multi-round-trip retry fields (`inputResponses`, `requestState`) out of inbound requests only (the spec reserves those names on client-initiated requests; notification params keep them), so handler params keep the 2025-era shape; for requests the lifted material surfaces at `ctx.mcpReq.envelope`, `ctx.mcpReq.inputResponses`, and `ctx.mcpReq.requestState` (notifications have no ctx — their lifted envelope keys are not surfaced). High-level client/server methods now return the named public result types (`Promise<CallToolResult>` etc.). Task wire vocabulary stays importable but is `@deprecated` and excluded from the typed method maps (`RequestMethod`/`RequestTypeMap`/`ResultTypeMap`/`NotificationTypeMap`), and `callTool` is typed as plain `CallToolResult`. See docs/migration/support-2026-07-28.md "Wire-only members hidden from public types".

CLAUDE.md

@@ -24,10 +24,11 @@ pnpm --filter @modelcontextprotocol/core test -- -t "test name"
 
 ## Breaking Changes
 
-When making breaking changes, document them in **both**:
-
-- `docs/migration.md` — human-readable guide with before/after code examples
-- `docs/migration-SKILL.md` — LLM-optimized mapping tables for mechanical migration
+When making breaking changes, add to the relevant subsystem section in
+`docs/migration/upgrade-to-v2.md` (or `docs/migration/support-2026-07-28.md` if the
+change is 2026-07-28-only). Mechanical renames go in
+`packages/codemod/src/migrations/v1-to-v2/mappings/` and the codemod handles them — do
+not reproduce mapping tables in the guide; link to the mapping file instead.
 
 Include what changed, why, and how to migrate. Search for related sections and group related changes together rather than adding new standalone sections.
 

REVIEW.md

@@ -50,7 +50,7 @@ review rounds and grows over time.
 
 **Tests & docs**
 - New behavior has vitest coverage including error paths
-- Breaking changes documented in `docs/migration.md` and `docs/migration-SKILL.md`
+- Breaking changes documented in `docs/migration/upgrade-to-v2.md` (or `docs/migration/support-2026-07-28.md` if 2026-only); mechanical renames added to `packages/codemod/src/migrations/v1-to-v2/mappings/`
 - Bugfix or behavior change: check whether `docs/**/*.md` describes the old behavior and needs updating; flag prose that now contradicts the implementation
 - New feature: verify prose documentation is added (not just JSDoc), and assess whether `examples/` needs a new or updated example
 - Behavior change: assess whether existing `examples/` still compile and demonstrate the current API

docs/behavior-surface-pins.md

@@ -16,7 +16,7 @@ surface-visible and must be deliberate:
    accidental break.
 2. Update the pin in the same PR.
 3. Add a changeset if the surface is consumer-facing.
-4. Update `docs/migration.md` / `docs/migration-SKILL.md` where consumer-facing.
+4. Update `docs/migration/upgrade-to-v2.md` (or `docs/migration/support-2026-07-28.md` if 2026-only) where consumer-facing.
 
 Never weaken a pin (loosen an exact match, delete an assertion) just to make
 CI pass — that reopens the silent-drift hole the pin exists to close.

docs/client.md

@@ -118,7 +118,7 @@ client.getNegotiatedProtocolVersion(); // '2026-07-28' or '2025-11-25'
 - **`mode: { pin: '2026-07-28' }`** — modern era at exactly that revision; no fallback. Against a 2025-only server `connect()` rejects with a typed error. Use `pin` where a silent downgrade would be worse than an error (tests, CI, servers you control).
 
 Once a modern era is negotiated, the client automatically attaches the per-request `_meta` envelope (the reserved protocol-version / client-info / client-capabilities keys) to every outgoing request and notification. You can also configure negotiation pre-connect on an
-already-constructed instance via {@linkcode @modelcontextprotocol/client!client/client.Client#setVersionNegotiation | client.setVersionNegotiation()}. See the [migration guide](./migration.md#opt-in-protocol-version-negotiation-2026-07-28-draft) for the full failure semantics,
+already-constructed instance via {@linkcode @modelcontextprotocol/client!client/client.Client#setVersionNegotiation | client.setVersionNegotiation()}. See the [2026-07-28 support guide](./migration/support-2026-07-28.md#serving-the-2026-07-28-revision) for the full failure semantics,
 probe policy, and the `'auto'`-mode compatibility table.
 
 ### Disconnecting
@@ -827,7 +827,7 @@ For an end-to-end example of server-initiated SSE disconnection and automatic cl
 - [`examples/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples) — Full runnable client examples
 - [Server guide](./server.md) — Building MCP servers with this SDK
 - [MCP overview](https://modelcontextprotocol.io/docs/learn/architecture) — Protocol-level concepts: participants, layers, primitives
-- [Migration guide](./migration.md) — Upgrading from previous SDK versions
+- [Migration guide](./migration/index.md) — Upgrading from previous SDK versions
 - [FAQ](./faq.md) — Frequently asked questions and troubleshooting
 
 ### Additional examples