docs: flatten the migration guide and its MCP tool (nuxt/ui@a3c3ff3, nuxt/ui@60db60e)

.sync/dep-parity.json

@@ -1,6 +1,6 @@
 {
   "$note": "Upstream's pinned versions for every dependency both trees declare in the SAME section, snapshotted at `cursor`. The sync ports deltas, which is correct per commit and lets a one-time divergence become permanent: once a version is off upstream's line, every later `chore(deps)` batch skips it, because those ports bump only where this fork already matched upstream's pre-image. `prettier` sat at ^3.8.4 against upstream's ^3.9.6 for that reason, through four ported batches, until this file was written. Section-aware on purpose: 18 packages are declared on both sides but in different sections — the whole `@tiptap/*` family is a peer `^3` upstream and a dependency `^3.29.2` here, and `ai` is a peer there and a devDependency here. Those are structural divergences, not drift, and comparing a peer range against a dependency range says nothing. They are absent from this file by construction rather than by omission. Guarded by `test/utils/dep-parity.spec.ts`. Refresh with `node .sync/dep-parity.mjs <path-to-nuxt-ui-mirror> [cursor]`, which preserves `exceptions`.",
-  "cursor": "ee37a5b4a8af2c8fa651288dcfbb263710f6d907",
+  "cursor": "60db60e05f2c605b9b96883218629754babc73e6",
   "manifests": {
     "package.json": {
       "dependencies": {

.sync/log/60db60e05f2c605b9b96883218629754babc73e6.md

@@ -0,0 +1,43 @@
+# port — nuxt/ui@60db60e05f2c605b9b96883218629754babc73e6
+
+**Upstream:** docs(mcp): resolve flattened page in `get-migration-guide` (#6963)
+
+**Decision:** port — the companion to `a3c3ff34`; without it the MCP tool queries
+a path that no longer exists.
+
+## Upstream change
+
+The tool loses its `version` input. `z.enum(['v4'])`, the `inputExamples` and the
+`version` key in the response all go, the description stops promising
+"version-specific" guides, and the lookup changes from a `LIKE %/migration/${version}`
+pattern to an exact match on the flattened path.
+
+## What changed here
+
+The same five edits to `docs/server/mcp/tools/b24-ui-get-migration-guide.ts`, with
+`v2` in place of `v4`:
+
+- `import { z } from 'zod'` dropped — it had no other use in the file
+- `inputSchema` / `inputExamples` removed
+- `async handler({ version })` → `async handler()`
+- `.where('path', 'LIKE', `%/migration/${version}`)` → `.where('path', '=', '/docs/getting-started/migration')`
+- the 404 message and the `version` response key
+
+**Two fork-only lines were deliberately left alone.** The response's `path` and
+`url` are built as
+`${config.public.baseUrl}${withTrailingSlash(page.path)}` — this site is served
+under a base path and with trailing slashes, which upstream's tool does not do.
+Taking upstream's `path: page.path` would have returned a URL that 301s at best.
+
+Note the asymmetry that results, and that it is correct: the **query** matches
+`'/docs/getting-started/migration'` without a trailing slash, because that is the
+`path` nuxt/content stores for the collection entry; the **returned** URL adds one,
+because that is what the site serves. The two are different things and only look
+inconsistent.
+
+## Why it ships with `a3c3ff34`
+
+The two are adjacent upstream and inseparable in effect: after the flattening the
+old `LIKE %/migration/v2` matches nothing, so the tool would answer 404 for the
+only guide this library has. §6 step 4b permits one PR for a contiguous run, and
+this is one.

.sync/log/a3c3ff34b187b6447f9c5082fdd2bd3671f442a2.md

@@ -0,0 +1,56 @@
+# port — nuxt/ui@a3c3ff34b187b6447f9c5082fdd2bd3671f442a2
+
+**Upstream:** docs: flatten migration guide to a single page
+
+**Decision:** port — the same one-page-in-a-directory shape is here, and the
+reasoning (the major lives in the package, not in the URL) holds for a fork whose
+major is 2.
+
+## Upstream change
+
+`3.migration/1.v4.md` → `3.migration.md`; the directory and its `.navigation.yml`
+go; the prose link loses its `/v4`; and the redirect reverses — `/migration` used
+to send readers to `/migration/v4`, now `/migration/v4` sends them to
+`/migration`, 301, with the `/raw/**.md` twin redirected alongside. Their comment
+gives the reason: *the version lives in the domain,
+ui4.nuxt.com/docs/getting-started/migration*.
+
+## Ported, not copied
+
+Five places here against upstream's four, and none of the URL lines could be
+taken verbatim.
+
+**This site uses trailing slashes.** Every route in `docs/nuxt.config.ts` is
+written `/docs/getting-started/migration/`, not `/docs/getting-started/migration`.
+Copying upstream's redirect targets would have produced a 301 to a path this site
+does not serve.
+
+**The redirect had to reverse, not be edited.** Ours read
+
+```ts
+'/docs/getting-started/migration/': { redirect: '/docs/getting-started/migration/v2/', … }
+```
+
+and after flattening `/migration/` *is* the page, so a rule pointing away from it
+would shadow the page with a redirect to a route that no longer exists. It now
+points the other way, plus a 301 for the raw twin.
+
+**There is a fork-only prerender list.** `docs/nuxt.config.ts:12` holds a `pages`
+array that line 401 maps into `/raw/<page>.md` prerender routes — the mechanism
+that publishes every page's Markdown twin. Upstream has no such list. Leaving
+`/docs/getting-started/migration/v2/` in it would have kept generating
+`/raw/.../migration/v2.md` for a page that no longer exists and stopped generating
+the one that does. This is the edit with no counterpart in the upstream diff, and
+the one a faithful-looking port would have missed.
+
+**`.navigation.yml` held only `shadow: true`** — upstream's also had an `icon`.
+Asserted before deleting, so nothing else went with it. `shadow` marks a directory
+whose index defers to a child; with no directory it has no meaning. The page keeps
+its own `navigation.title: 'Migration'` in frontmatter, so the sidebar entry is
+unchanged.
+
+## Note
+
+The page is still titled *Migration to v2* and still describes v1 → v2. Only its
+location changed. A fork on major 2 with one guide is exactly the shape upstream
+just moved to, so this is convergence rather than divergence.

.sync/nuxt-ui.json

@@ -1,7 +1,7 @@
 {
   "upstream": "nuxt/ui",
   "branch": "v4",
-  "cursor": "ee37a5b4a8af2c8fa651288dcfbb263710f6d907",
+  "cursor": "60db60e05f2c605b9b96883218629754babc73e6",
   "_cursor_note": "cursor = last upstream commit ported into b24ui. The sync is manual by decision: one commit at a time, oldest-first, each with a `.sync/log/<sha>.md` journal and an entry in `processed`. There is no dispatcher, no porter workflow and no kill-switch — `.sync/PORTING.md` is the whole procedure. `processed` is maintained per port (backfilled #68-#72 on 2026-06-09).",
   "processed": {
     "2799fa6f2b25ce3eb15e050f3ef7c57d0d9a2fdb": {
@@ -1981,10 +1981,22 @@
       "summary": "refactor(unplugin): resolve vue runtime paths from a file url — second half of b0e1d715; an absolute Windows path like `D:/...` parses as a `d:` url scheme, so the four sites take a relative id against a new `runtimeUrl` (pathToFileURL of runtimeDir WITH a trailing slash, which is load-bearing). Drops the now-unused `join` import from bitrix24-environment.ts, as upstream does"
     },
     "ee37a5b4a8af2c8fa651288dcfbb263710f6d907": {
-      "pr": "pending-merge",
-      "b24ui_sha": "pending-merge",
+      "pr": 607,
+      "b24ui_sha": "ecd9e83a",
       "decision": "n/a",
       "summary": "chore(github): drop `@nuxt/ui` placeholder from consumer fixtures — n/a: module.yml and test/fixtures/ do not exist here (recorded with b2cb53f8 / #598). Worth noting the reason: the placeholder made the job resolve the released package, so the build under test was never the one whose optional peers were checked"
+    },
+    "a3c3ff34b187b6447f9c5082fdd2bd3671f442a2": {
+      "pr": "pending-merge",
+      "b24ui_sha": "pending-merge",
+      "decision": "port",
+      "summary": "docs: flatten migration guide to a single page — 3.migration/1.v2.md -> 3.migration.md, directory + .navigation.yml (shadow only) removed, prose link updated, redirect REVERSED (/migration/ is the page now) + a 301 for the raw twin. Five places against upstream’s four: our routes carry trailing slashes and we have a fork-only `pages` prerender list that generates /raw/**.md, which upstream has no counterpart for"
+    },
+    "60db60e05f2c605b9b96883218629754babc73e6": {
+      "pr": "pending-merge",
+      "b24ui_sha": "pending-merge",
+      "decision": "port",
+      "summary": "docs(mcp): resolve flattened page in `get-migration-guide` (#6963) — drops the `version` input and queries the flattened path exactly. Kept the fork-only baseUrl/withTrailingSlash construction of the returned path and url; the query matches without a trailing slash (nuxt/content’s stored path) while the response adds one (what the site serves)"
     }
   }
 }

docs/content/docs/1.getting-started/1.index.md

@@ -45,7 +45,7 @@ title: Production Ready
 
 We support almost all components of Nuxt UI v4.
 
-Read more in the [migration guide](/docs/getting-started/migration/v2/).
+Read more in the [migration guide](/docs/getting-started/migration/).
 
 ## Core technologies
 

docs/nuxt.config.ts

@@ -12,7 +12,7 @@ const pages = [
   '/docs/getting-started/',
   '/docs/getting-started/installation/nuxt/',
   '/docs/getting-started/installation/vue/',
-  '/docs/getting-started/migration/v2/',
+  '/docs/getting-started/migration/',
   '/docs/getting-started/contribution/',
   '/docs/getting-started/theme/design-system/',
   '/docs/getting-started/theme/css-variables/',
@@ -355,7 +355,9 @@ export default defineNuxtConfig({
     '/raw/**': { headers: { Vary: 'Accept, User-Agent' } },
     // v4 redirects - default root pages
     '/docs/': { redirect: '/docs/getting-started/', prerender: false },
-    '/docs/getting-started/migration/': { redirect: '/docs/getting-started/migration/v2/', prerender: false },
+    // the version lives in the package, not the url — `/migration/` is the page
+    '/docs/getting-started/migration/v2/': { redirect: { to: '/docs/getting-started/migration/', statusCode: 301 }, prerender: false },
+    '/raw/docs/getting-started/migration/v2.md': { redirect: { to: '/raw/docs/getting-started/migration.md', statusCode: 301 }, prerender: false },
     '/docs/getting-started/theme/': { redirect: '/docs/getting-started/theme/design-system/', prerender: false },
     '/docs/getting-started/integrations/': { redirect: '/docs/getting-started/integrations/icons/', prerender: false },
     '/docs/getting-started/ai/': { redirect: '/docs/getting-started/ai/llms-txt/', prerender: false },

docs/server/mcp/tools/b24-ui-get-migration-guide.ts

@@ -1,41 +1,33 @@
-import { z } from 'zod'
 import { queryCollection } from '@nuxt/content/server'
 import { withTrailingSlash } from 'ufo'
 
 export default defineMcpTool({
   title: 'Get Migration Guide',
-  description: 'Retrieves version-specific migration guides and upgrade instructions',
+  description: 'Retrieves the migration guide and upgrade instructions for this version of Bitrix24 UI',
   annotations: {
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,
     openWorldHint: false
   },
-  inputSchema: {
-    version: z.enum(['v2']).describe('The migration version (e.g., v2)')
-  },
-  inputExamples: [
-    { version: 'v2' }
-  ],
   cache: '30m',
-  async handler({ version }) {
+  async handler() {
     const event = useEvent()
     const config = useRuntimeConfig()
 
     const page = await queryCollection(event, 'docs')
-      .where('path', 'LIKE', `%/migration/${version}`)
+      .where('path', '=', '/docs/getting-started/migration')
       .where('extension', '=', 'md')
       .select('title', 'description', 'path')
       .first()
 
     if (!page) {
-      throw createError({ status: 404, message: `Migration guide for '${version}' not found` })
+      throw createError({ status: 404, message: 'Migration guide not found' })
     }
 
     const documentation = await $fetch<string>(`/raw${page.path}.md`)
 
     return {
-      version,
       title: page.title,
       description: page.description,
       path: `${config.public.baseUrl}${withTrailingSlash(page.path)}`,