blume 2.1.3 → 2.2.1

package/skills/blume-migrate/references/docsify.md

@@ -0,0 +1,262 @@
+# Docsify → Blume
+
+Docsify has no build step. One `index.html` sets `window.$docsify = {…}`, loads Docsify and its plugins from a CDN, and renders each page's Markdown in the browser. Watch for five traps:
+
+- **URLs live after a `#`** (`/#/guide/setup?id=install`). A server never sees that part, so `redirects` can't match an old URL. The site needs a client-side redirect script (URLs below).
+- **Links resolve from the docs root**, not the page's folder, unless `relativePath: true`. Images and includes resolve from the page's folder either way, even with a leading `/`. Raw HTML `href`/`src` resolve from the docs root, because the document URL is always the folder holding `index.html`.
+- **Pages have no frontmatter.** The title is usually the first `# H1`, but not always.
+- **Navigation is a Markdown list** (`_sidebar.md`), and its groups usually sit flat in one folder.
+- **Heading ids differ from Blume's**, and old deep links carry them as `?id=`.
+
+**Fingerprint the version.** It changes callouts and heading ids. `docsify@4`, or any script URL with `/lib/` (even an unversioned `…/npm/docsify/lib/docsify.min.js`), runs v4 code: the v5 package still ships the v4 build under `lib/`. `docsify@5/dist/…` or `new Docsify({…})` is v5.
+
+## Detect
+
+- An **`index.html`** whose inline script sets **`window.$docsify`** (v5 can also use `new Docsify({…})`), usually in `docs/`. The folder holding it is the content root.
+- `_sidebar.md`, `_navbar.md`, `_coverpage.md`, and `.nojekyll` beside it, with `README.md` as the home page.
+- `docsify-cli` or `docsify` in `package.json`. Without either, the source has to be named: `npx blume migrate docsify`.
+- A GitHub wiki has `_Sidebar.md` and `Home.md` but no `index.html`. It isn't Docsify.
+
+**Where the Blume project goes.** Put `blume.config.ts` beside the `package.json` that runs `docsify serve <dir>` (usually the repo root), so the default `content.root: "docs"` matches. With no manifest, scaffold one there.
+
+Read the whole `index.html`: the `$docsify` object (it can be a function), every `<script src>` (each is a plugin), the `<head>`, and the `<body>`. Open a few routes on the live site too. **A page whose include target is missing rendered blank in Docsify 4**, so some "pages" never worked.
+
+## Run the codemod first
+
+On the Docsify folder, from the directory that will hold `blume.config.ts`, dry-run the bundled codemod, then apply it once, before any hand edits:
+
+```bash
+curl -s https://api.github.com/emojis > emojis.json   # only if pages use :shortcodes:
+node <skill>/scripts/docsify-codemod.mjs docs
+node <skill>/scripts/docsify-codemod.mjs --write --snapshot .docsify-old \
+  --group-folders --emoji emojis.json --site https://docs.example.com docs
+```
+
+It's zero-dependency and idempotent, and reads `version`, `relativePath`, `routerMode`, `noEmoji`, `homepage`, `loadSidebar`, `loadNavbar`, and `coverpage` from `index.html` (override with `--version` and `--relative-path`). It converts:
+
+- `!>` → `:::warning`, `?>` → `:::tip`, and `> [!TYPE]` alerts → directives, leaving fenced and indented code alone;
+- docsify-tabs → `<Tabs>`;
+- `':include'` lines → `<include>`, resolved from the page's folder as Docsify did, even with a leading `/`. A `:fragment=` is copied to its own file where Docsify cut one: code includes, plus Markdown ones in v5. Docsify 4 showed a Markdown include whole, so it stays whole;
+- `:id=` → `[#id]`, `{docsify-ignore}` → `[!toc]`, and setext headings → ATX;
+- links resolved the way Docsify resolved them (hash links, `?id=`, and `--site` absolute links included) → relative file links, without an anchor that named the target's title H1 (that heading becomes `title`);
+- images → rebased for moved pages. Docsify read a leading-slash image from the page's folder too, where Blume would read it from `public/`;
+- link and image attribute strings → dropped;
+- relative raw HTML URLs and `':ignore'` links → root paths. An `':ignore'` link to a page's own file opened the raw Markdown, so it becomes a raw `<a href>` to the page's Markdown copy (`/<new route>.md`): a Markdown link naming a page's file, even root-relative, lands on the page itself;
+- emoji shortcodes → Unicode;
+- the H1 or sidebar label → `title`, plus `sidebar.label`, `seo.title`, and `hidden: true`, with later H1s demoted;
+- `README.md` → `index.md`, and pages that need MDX → `.mdx` with MDX-safe comments, `<br>`, void tags, and autolinks.
+
+`--group-folders` moves each page into a folder per sidebar group, writes each folder's `meta.ts` in sidebar order plus a root `meta.ts` that keeps the groups in sidebar order, and writes the old → new route table to `docsify-routes.json`. Leave the flag off to keep the files where they are. With `homepage: "intro.md"`, the table also maps `/intro` → `/`, since Docsify served that page at both.
+
+`--snapshot` records every page's headings with the ids Docsify gave them, plus `old-routes.txt`. The pin step (URLs below) needs it, and it only works on the first run, while the pages are untouched. On Zenroom it matched Docsify 4.13.1's rendered ids on every page that rendered.
+
+**Every `REVIEW` line is a to-do**, and the sections below say what to do with each. The codemod never invents a fix: a missing include stays as written, and a file that must move to `public/` is only listed.
+
+## Config: `window.$docsify` → `blume.config.ts`
+
+| Docsify | Blume |
+| --- | --- |
+| `name` (may hold HTML) | `title`, as plain text. The `<title>` and `<meta name="description">` in `index.html` give `title` (when `name` is unset) and `description` |
+| `logo` | `logo`, with the file moved to `public/`. Docsify shows the logo instead of the name, so a wordmark needs `logo: { image, text: "" }`. Check it in dark mode |
+| `nameLink` | `logo.href` |
+| `repo` | `github: { owner, repo }` (with `branch` from an edit-on-github URL). A non-GitHub repo goes in `navigation.actions` |
+| `themeColor` (v4), `--theme-color` in a stylesheet (v5) | `theme.accent` |
+| A dark-only theme (`dark.css`, a themeable `*-dark.css`) | `theme.mode: "dark"`. Other themes map to nothing |
+| Fonts in the stylesheet or `<link>`s | `theme.fonts` |
+| `<link rel="icon">` | Copy the file to `public/favicon.<ext>` |
+| `<meta>` verification tags | `seo.metatags`. `twitter:site` goes to `seo.x.handle`. Drop `og:*` and `twitter:` card tags, since Blume writes them |
+| Custom CSS | A root `theme.css` with only the rules whose markup still exists. Docsify selectors (`.markdown-section`, `.sidebar`, `.cover`) match nothing |
+| Site URL (`CNAME`, a sitemap) | `deployment.site`. GitHub Pages isn't auto-detected |
+| `subMaxLevel: N` | `toc: { maxHeadingLevel: N }` when N ≥ 2 and isn't 3. Drop `maxLevel` |
+| `homepage: "x.md"` | Handled by the codemod. A remote URL needs vendoring |
+| `alias` | Local-to-local entries go in the route table. Remote targets: see Includes and aliases. Drop sidebar plumbing (`'/.*/_sidebar.md'`) and any alias whose target doesn't exist |
+| `externalLinkTarget: '_blank'` (explicit) | `markdown: { externalLinks: true }`. Docsify opens external links in a new tab even when this is unset, so report the change |
+| `notFoundPage` / `_404.md` | Blume's 404 page, or a custom `pages/404.astro` |
+| `formatUpdated`, `{docsify-updated}`, a last-modified plugin | `lastModified: "git"` (and `fetch-depth: 0` in CI) |
+| `collapsibleSidebarGroups` (v5) | `navigation.sidebar.display: "group"`, plus `collapsed: false` in each `meta.ts` that should start open |
+| `vueComponents`, `vueMounts`, `vueGlobalOptions`, `executeScript` | An island per widget (`islands/Name.vue`, `docs/content/islands.mdx`). Report |
+| `markdown` (marked options or a `renderer`) | Drop, and report what the renderer did. Common ones are mermaid (now native) and a `json` pretty-printer: minified JSON includes now render as one line, so fix that in whatever generates them. `breaks: true` has no equivalent |
+| `routes` (virtual routes) | Static ones become pages. Report dynamic ones |
+| `auto2top`, `topMargin`, `maxLevel`, `cornerExternalLinkTarget`, `requestHeaders`, `noCompileLinks`, `sidebarPosition`, `keyBindings`, `skipLink`, the search and pagination options, … | Drop |
+
+**Plugins** are `<script>` tags:
+
+- **Built in:** search, `docsify-copy-code`, `docsify-pagination`, and `zoom-image`. Delete them.
+- **Converted by the codemod:** emoji, `docsify-tabs`, and flexible-alerts.
+- **Prism language packs:** delete them. Shiki highlights the common languages in any case (` ```JSON ` works), and a fence in a language it doesn't know, or a misspelled one, renders as plain text and warns `BLUME_UNKNOWN_CODE_LANGUAGE`: fix the name, or write `text`.
+- **Mermaid** plugins or renderers → native ` ```mermaid ` in `.mdx`.
+- **KaTeX** → `$$…$$` in `.mdx`, with inline `$…$` becoming `$$…$$` inside its sentence.
+- **`ga` / `gtag`** → `googleAnalytics({ id })` for a `G-` id. A `UA-` id no longer collects data, so report it. Other analytics → `script()`.
+- **Comments** (Disqus, Gitalk, giscus) → nothing built in. Use a `PageFooter` slot, or report them.
+- **Anything else** (bibtex, remote-markdown, demo boxes, custom inline plugins) → report.
+
+## Navigation: `_sidebar.md` → folders and `meta.ts`
+
+- **Groups over pages in one flat folder** (everything in `docs/` or `docs/pages/`) flatten silently. Use `--group-folders`: it moves each group's pages into a folder and writes `meta.ts` and the route table, and the hash script maps every old route. This departs from SKILL.md's `(group)/`-first rule: every Docsify URL changes form anyway (`/#/x` → `/x`), so the script runs for each old link either way, and the codemod rebases the moved pages' links and images. To keep URLs instead, move pages at the content root into `(group)/` folders, which add no URL segment; under a subfolder like `pages/`, they keep `/pages/x` but nest every group under a "Pages" group. Or keep the files and write an explicit `navigation.sidebar`.
+- **Groups whose pages already sit in a folder named for the group** (`Guide` → `guide/`) stay put, and `--group-folders` writes that folder's `meta.ts`. It moves the pages of a group whose folder has another name into one named for the group, so on a site already laid out in folders, leave the flag off and write each `meta.ts` by hand, with the group label and the sidebar's order.
+- **The home page** stays the root `index`. The generated sidebar lists it first, never inside a group.
+- **Loose pages listed after groups** can't keep that order, because Blume lists loose pages first. Move them into a folder, or report the change.
+- **External links, and links to files** like a PDF or HTML in `public/`, become `navigation.featured`. A file link there warns at build ("no page matches it"); the warning is harmless.
+- **A `_sidebar.md` inside a folder** replaced the sidebar under that folder. Map the folder to a `navigation.tabs` entry.
+- **Pages the sidebar doesn't list** get `hidden: true` from the codemod. They stay reachable, as before.
+- **Sidebar link titles** (`[x](x.md "Tab title")`) become `seo.title`. Report any that look copy-pasted from another page: Docsify showed them as the browser tab title.
+
+## Navbar and cover page
+
+- **`_navbar.md`:** doc-section links become `navigation.tabs` (a nested list becomes a tab with `items`), and other links become `navigation.actions`. With `mergeNavbar: true`, put the other links in `navigation.featured` instead, not in both: featured shows on every screen size, while actions hide on phones. Language links (`/zh-cn/`) become `i18n`.
+- **`_coverpage.md`** (shown above `README.md` on `/`; the whole home page with `onlyCover: true`): rebuild it as the top of `index.md`. The `# name <small>1.2</small>` heading is already the title. The tagline is prose or `description`, the logo is a Markdown image, and the buttons become links or `<Card>`s. Drop the background image or `![color](#…)`, and report it. Use `mode: center` when the cover was the whole page.
+
+## Content: what the codemod leaves to you
+
+**Titles.** Docsify drops only the first H1 from its sidebar headings, so pages often have several. The codemod takes a leading H1 as the title and demotes every later heading from the second H1 on. When content comes before the first H1, it takes the sidebar label as the title and demotes everything. Check every title it flags: about one page in five on Zenroom started with a section ("Key generation", "Intro"). For those, use the sidebar label as the title, put the H1 back as an `##` section, and demote every heading.
+
+**MDX hazards** in a renamed page. The codemod lists each one, and all but the first fail the build:
+
+- An indented code block renders as a plain paragraph: fence it.
+- An HTML table whose cell tags share a line with text: give each `<tr>`/`<td>` its own line.
+- A block element inside `<p>`, typical of README banners: make the `<p>` a `<div>`.
+- A repeated attribute: keep one.
+- A brace in prose: escape it as `\{`.
+
+**Includes and aliases.**
+
+- **A missing include target:** the page was blank on the old site. Repoint the include to the file's new name (a folder was usually renamed), or drop it, and report it.
+- **A fragment copied from a generated file** goes stale. Have the generator write one file per fragment.
+- **An included file's own H1** becomes a second `<h1>`: remove it.
+- **An alias to a raw URL of a file in the same repo** (`'/CHANGELOG': 'https://raw.githubusercontent.com/<owner>/<repo>/main/CHANGELOG.md'`) becomes a page that `<include>`s the file through a symlink in `_snippets/`. Removing that file's H1 changes a file people read on GitHub, so say so.
+- **Other remote aliases and includes:** vendor a copy (with a source comment), or use `mdxRemote()`.
+- **iframe, video, and audio embeds** become raw HTML, with the file in `public/`.
+
+**Files the pages link** (listed under "must be served from public/"): Docsify served every file in its folder at its path. Blume publishes a file a page links relatively with that page, but at a new URL, and the codemod writes Docsify's root-resolved links as root paths, which keep the old URLs and are served from `public/`.
+
+- Copy each file into `public/` at the same path.
+- If a generator writes the files (test fixtures, examples), symlink the folder instead: `public/_media/examples → ../docs/examples`. Astro copies the target, and `validate` checks the links.
+- An HTML document saved as `.md` (generated API docs) goes to `public/` as HTML.
+- `blume validate --strict` reports a missing one as `BLUME_BROKEN_ASSET`.
+
+**Everything else:**
+
+- **Link attributes** the codemod dropped (`:target`, `:size`, `:no-zoom`, `:class`): restore any that matter as raw HTML (`<img src="/x.png" width="200" data-no-zoom />`, with the file in `public/`).
+- **Emoji shortcodes left over:** paste the emoji.
+- **Page `<script>`s:** Docsify 4 ran them only with `executeScript` or Vue, so they often never ran. Move one that did into an island.
+- **Vendored READMEs** keep Blume's ids (they had GitHub-style ids already), and they aren't in the snapshot.
+
+## URLs and redirects
+
+**Hash mode (the default).** Every page lived at `/#/<route>`, also reachable as `/#/<route>.md` and `/index.html#/<route>`, with folder indexes at `#/<folder>/` and headings at `?id=<id>`. The server only saw `/`.
+
+**A. Blume takes over the old address** (the usual case). `docsify-routes.json` holds the page moves the codemod made. Add an entry for each alias you turned into a page. Routes that now land on a file in `public/` go in a separate `files` map that only the script reads: a redirect page would sit where the file is. Name a `public/` folder with its slash (`/api/`) or name the file itself (`/api/index.html`): static hosts, `blume dev`, and `blume preview` serve its `index.html` at `/api/` (and redirect `/api` there), where its relative links resolve.
+
+```ts blume.config.ts
+import { defineConfig } from "blume";
+
+import moved from "./docsify-routes.json" with { type: "json" };
+
+// Old routes that now land on a file in public/: the script sends readers
+// there, but a redirect can't, so they stay out of `redirects`.
+const files = {}; // e.g. { "/onepage": "/onepage.md" }
+
+// Docsify served every page at /#/<route>; a server never sees the hash.
+// Swap an old hash URL for its new route, and ?id=<heading> for #<heading>.
+const base = ""; // the site's deployment.base plus basePath, if it has either
+const docsifyRedirects = `(() => {
+  const base = ${JSON.stringify(base)};
+  const routes = ${JSON.stringify({ ...moved, ...files })};
+  const go = () => {
+    const hash = location.hash;
+    if (!hash.startsWith("#/")) return;
+    const q = hash.indexOf("?");
+    let path = q === -1 ? hash.slice(1) : hash.slice(1, q);
+    const id = q === -1 ? null : new URLSearchParams(hash.slice(q + 1)).get("id");
+    try { path = decodeURI(new URL(path, "http://x").pathname); } catch {}
+    path = path.replace(/\\.md$/i, "").replace(/(^|\\/)README$/i, "$1");
+    if (path.length > 1) path = path.replace(/\\/+$/, "");
+    // location.origin keeps a crafted #//other.host/ link on this site.
+    location.replace(location.origin + base + (routes[path] ?? path) + (id ? "#" + id : ""));
+  };
+  go();
+  addEventListener("hashchange", go);
+})();`;
+
+export default defineConfig({
+  redirects: Object.entries(moved).map(([from, to]) => ({ from, to })),
+  integrations: [
+    {
+      name: "docsify-hash-redirects",
+      hooks: {
+        "astro:config:setup": ({ injectScript }) => {
+          injectScript("head-inline", docsifyRedirects);
+        },
+      },
+    },
+  ],
+});
+```
+
+The script runs from every page's `<head>`, the 404 page included, before the body loads, in `blume dev` and in every build. Keep its two safeguards: `new URL(…).pathname` resolves the `./` and `../` segments Docsify left in links (`#/./guide`), and `location.origin` stops a crafted `#//other.host/` from sending readers off the site. Unmoved routes need no entry. The `redirects` also cover direct visits to a moved path and its `/old.md` Markdown twin. Don't use the `script()` analytics adapter for this: it's emitted in production builds only, and held until consent when `consent` is set.
+
+**B. The old site keeps its own address** (an old GitHub Pages URL, while the docs move to a new domain). Replace the old `index.html` with a page running the same parsing, with the new origin in place of `location.origin`, and a `<noscript><meta http-equiv="refresh" content="0; url=https://new.example/"></noscript>` fallback.
+
+**History mode** (`routerMode: 'history'`). URLs were real paths, so the route table and `redirects` carry moved pages. Anchors were still `?id=`, so add this after `go();`:
+
+```js
+if (!location.hash) {
+  const id = new URLSearchParams(location.search).get("id");
+  if (id) location.replace(location.pathname + "#" + id);
+}
+```
+
+**Keep old heading anchors.** Docsify 4 leaks entity names into ids (`Foo & Bar` → `foo-amp-bar`, `Don't` → `don39t`), collapses dash runs, keeps emoji and shortcode names, and prefixes a leading digit with `_`. Docsify 5 is closer to Blume, but still differs in that prefix, in non-ASCII capitals, and where a heading has emphasis (`_When_` stays in the id) or a shortcode. After the first build, pin each old id where it differs, and rebuild until it reports 0:
+
+```bash
+node <skill>/scripts/pin-heading-ids.mjs --old .docsify-old --map docsify-routes.json --write
+```
+
+On Zenroom, one pass kept every old id except those of title H1s (58 of 968), and a link to one of those lands at the top of the page anyway. A page that never rendered on the old site (a missing include) has nothing to pin.
+
+**Check every old route** against `blume preview`. In `.docsify-old/old-routes.txt`, a folder route is listed without its slash, but Docsify served it only with one. Both forms reach the script.
+
+```bash
+node -e '
+const routes = { ...require("./docsify-routes.json") };   // add the files map too
+const old = require("fs").readFileSync(".docsify-old/old-routes.txt", "utf8").split("\n").filter(Boolean);
+(async () => { for (const r of old) {
+  const res = await fetch("http://localhost:4321" + (routes[r] ?? r));
+  if (res.status !== 200) console.log(res.status, r);
+} })();'
+```
+
+Then open a few old hash URLs, with and without `?id=`, in a browser on the deployed site. A plain `curl` can't test the hash script.
+
+**GitHub Pages**, where most Docsify sites live:
+
+- Switch the Pages source from the branch folder to GitHub Actions, using the workflow in https://useblume.dev/guides/markdown-docs-github-pages (with `fetch-depth: 0` for `lastModified: "git"`).
+- Pages has no redirect rules of its own. A static build writes each exact `redirects` entry as a page that forwards to the new URL, which is all the table holds; a pattern redirect wouldn't work there.
+- A project URL (`user.github.io/repo/`) becomes `deployment: { site: "https://user.github.io", base: "/repo" }`, and that base goes in the script too. Blume adds the base to root paths in Markdown and raw HTML alike, so the codemod's root paths need nothing more.
+- The custom domain stays in the Pages settings. Neither `CNAME` nor `.nojekyll` is needed.
+- The workflow's `npm ci` needs a lockfile, so commit one.
+
+## Teardown
+
+After harvesting what they declare, delete:
+
+- `index.html`;
+- `_sidebar.md`, `_navbar.md`, `_coverpage.md`, and `_404.md` (Blume ignores `_` files meanwhile), or the files `loadSidebar`, `loadNavbar`, and `coverpage` name instead. Without the `_`, Blume publishes them as pages until they're gone;
+- `.nojekyll`, the theme CSS, and generators that read the sidebar or Docsify syntax (sitemaps, one-page builds).
+
+Swap `docsify-cli`/`docsify` for `blume` and `docsify serve` for `blume dev`/`blume build`/`blume preview`. Keep `docsify-routes.json` and `.docsify-old/` until the pins are done and old links stop mattering.
+
+## Dropped — report these
+
+- The cover's background and the navbar's language links (now `i18n`).
+- The home page's place in a sidebar group, and loose pages after groups.
+- Link and image attributes you didn't restore.
+- Fragments now frozen as copies.
+- Vendored or `mdxRemote()` aliases.
+- Pages that were blank on the old site (missing includes) and what you did with each.
+- Title H1 anchors (they land at the page top).
+- Comment plugins, a `UA-` analytics id, Vue widgets, and page scripts.
+- Custom `markdown` renderers (JSON pretty-printing included) and `breaks: true`.
+- Dynamic virtual `routes`.
+- Theme CSS with no Blume target, and copy-pasted sidebar link titles now in `seo.title`.
+- New-tab external links, unless you set `markdown.externalLinks`.

package/skills/blume-migrate/references/docus.md

@@ -0,0 +1,298 @@
+# Docus → Blume
+
+Docus is a Nuxt layer for docs sites. It's built on Nuxt Content (pages are Markdown files in `content/`, routed by their path) and Nuxt UI (the theme, and the prose components pages use). Navigation is the file tree plus per-folder `.navigation.yml` files, and settings live in `app.config.ts` and `nuxt.config.ts`. Pages are written in **MDC**, Nuxt Content's Markdown-with-components syntax. The bundled codemod converts most of it; these traps are why it exists:
+
+- **MDC's `::note` … `::` looks like a Blume directive and isn't one.** Blume prints `::note` and its `::` closer as text (in `.md`, every MDC construct), and `blume check` and `build` warn `BLUME_MDC_SYNTAX` at each block opener and inline component (`:badge[New]{color="primary"}`) left in either format: convert them as below.
+- **MDX is stricter than MDC.** `[text]{.class}` spans fail the build, and so do `{…}`, `<Name>`, and `<50` in prose. Prompt bodies are full of these.
+- **Icons are Iconify names** (`i-lucide-zap`, `i-simple-icons-github`). Blume renders nothing for them, and warns only for sidebar and tab icons.
+- **Docus sorts siblings by file path as text,** so `10.faq.md` lists between `1.` and `2.`. Blume sorts the prefixes as numbers.
+
+Scope:
+
+- **Docus 3.x–5.x** is covered: the `docus` package on Nuxt Content 3 and Nuxt UI, whose content syntax is the same across the three. 5.x is current and is by far the most installed, and it's the one this reference was run on.
+- **Docus 1.x** (`@nuxt-themes/docus`, on Nuxt Content 2 with Nuxt Elements components) is flagged. Its section near the end was written from the package source, not tested on a site, and the codemod doesn't convert its components.
+- **The Nuxt UI docs template** (`nuxt-ui-templates/docs`, no `docus` dependency) writes the same content: the codemod and this reference apply, and its `app.config.ts` is read by hand.
+
+## Detect
+
+- **A `docus` dependency** means 3.x–5.x, and **`@nuxt-themes/docus`** means 1.x. It's usually in the docs package's own `package.json` (`docs/`, `apps/docs/`) in a module's monorepo.
+- Usually a `nuxt.config.ts` with `extends: ['docus']`. The 4.x starters have no config and run `nuxt dev --extends docus`, and 3.x ran `docus dev`.
+- A `content/` folder beside it with `.navigation.yml` files (3.x+) or `_dir.yml` files (1.x).
+
+**Where the Blume project goes.** Put `blume.config.ts` beside the `package.json` that depends on `docus`, and set `content.root: "content"`. `public/` stays where it is: both tools serve it at the site root. In a workspace, read `references/monorepo.md` too.
+
+- **No `content/docs/` folder:** every file under `content/` is a page, and `content/index.md` is the landing page at `/`.
+- **A `content/docs/` folder:** Docus publishes only `content/docs/**`, under `/docs/…`, plus `content/index.md`. Exclude anything else under `content/` and report it. Docus hides the `docs` level in its sidebar. In Blume, add a tab `{ label: "Docs", path: "/docs" }`, or the section tabs below, or the sidebar wraps everything in a "Docs" group.
+- **`content/<locale>/` folders:** see i18n.
+
+## Record the old site first
+
+Before editing anything, save the URL list, the old heading ids, and the record of what rendered:
+
+- **URLs:** the live `/sitemap.xml` (on an i18n site, an index of one sitemap per locale), plus every `routeRules` redirect source in `nuxt.config.ts`.
+- **HTML:** `nuxt generate` writes `.output/public`, one `<route>.html` per page plus a meta-refresh stub per redirect. Copy it outside the repo; it's `<old build>` below. Or point the anchor script at the live origin.
+- **Check components against the live site.** A local build can miss a component a Nuxt module registers in its own build: it shows as an empty tag (`<InstallButton …></InstallButton>`) while production renders it. Request live pages with a browser user agent (`curl -A 'Mozilla/5.0'`): some Docus deployments answer `curl` with Markdown.
+
+## Run the codemod first
+
+On the `content/` directory, dry-run and apply the bundled codemod:
+
+```bash
+node <skill>/scripts/docus-codemod.mjs content          # report only
+node <skill>/scripts/docus-codemod.mjs --write content  # apply
+```
+
+It's zero-dependency, deterministic, and idempotent. Icon names are checked against Blume's Lucide set once `blume` is installed (or with `--lucide <icons.json>`).
+
+**What it does:**
+
+- **Pairs MDC blocks** as remark-mdc does (see MDC syntax).
+- **Converts the Nuxt UI prose components:**
+  - callouts → `:::type` directives, or `<Callout type icon>` when a callout's icon isn't its type's own
+  - `card-group`/`card`, `field-group`/`field` → `<ResponseField>`, `steps`, `tabs`, `accordion`, `collapsible`
+  - `code-group` → `<CodeGroup>`, or one `package-install` fence when the group only repeats an install command
+  - `code-collapse`, `code-tree`, `code-preview`, `prompt`, `badge`
+  - the inline `:icon`, `:kbd`, `:badge`, `:video`, and `:u-color-mode-image`
+- **Strips Markdown attributes:** `[text]{.class}` spans and `{…}` attributes go.
+- **Rewrites fence labels and frontmatter:** fence `[label]`s become titles, `navigation` → `sidebar`, `seo.ogImage` → `seo.image`, `links` → `related`, a body H1 → `title`, and `.navigation.yml` → `meta.ts`.
+- **Renames to `.mdx`** each page that now needs MDX, and makes its prose MDX-safe (see MDC syntax).
+
+Every `REVIEW` line is your to-do list, including:
+
+- custom and landing-page components, left as written
+- blocks with a slot the conversion doesn't read (a card's `#footer`), left as written
+- card descriptions, which Nuxt UI's prose card never rendered
+- callouts that linked somewhere
+- icons outside Lucide
+- unclosed blocks and stray closers
+- `links` lists longer than `related` takes, and frontmatter keys Blume rejects
+- MDC blocks inside blockquotes
+- file names whose URL changes
+
+## Config: `app.config.ts` → `blume.config.ts`
+
+Read `app/app.config.ts` (`app.config.ts` at the project root on Nuxt 3), `nuxt.config.ts`, the CSS that `css` lists, and `.env.example`.
+
+| `app.config.ts` | Blume |
+| --- | --- |
+| `seo.title` | `title`. Docus falls back to `site.name` in `nuxt.config.ts`, then the `package.json` `name`, then the git repository's name, so carry the one the site showed |
+| `seo.description` | `description` (Docus falls back to the `package.json` `description`) |
+| `seo.titleTemplate` | drop. The default `%s - <site>` is Blume's; report a custom one |
+| `seo.schema` | drop (report). Blume writes its own JSON-LD |
+| `header.title` | `title`, when there's no logo |
+| `header.logo.{light,dark,alt}` | `logo: { image: { light, dark, alt }, text: "" }`. Docus shows the logo without the title. A monochrome SVG → `currentColor` and the string form (SKILL.md) |
+| `header.logo.display: 'wordmark'` | the `wordmark` files as the logo |
+| `socials` (Simple Icons slug → URL) | `footer.socials` for the platforms Blume lists (`twitter` → `x`). Others (`nuxt`, `npm`) → `footer.links`, or drop (report) |
+| `github` (`url`, `branch`, `rootDir`), or nothing | `github: { owner, repo, branch, dir }`. **Docus reads the git remote when `github` isn't set,** so edit links showed anyway: take `owner`/`repo` from the remote. `dir` = `rootDir`; `branch` only when it isn't `main`. `github: false` → leave it out |
+| `toc.bottom.links` | `navigation.featured` (`to` → `href`). Report the move |
+| `navigation.sub` | `navigation.tabs` (see Navigation). `'aside'` anchors have no Blume form; report |
+| `docus.locale` (not `en`) | a one-locale `i18n` block |
+| `docus.colorMode` | `theme.mode`. Blume always shows the toggle; report |
+| `assistant.faqQuestions` | `ai.assistant.suggestions` (`[{ label }]`; flatten categories) |
+| `ui.colors.primary` | `theme.accent`. Nuxt UI paints shade 500 in light mode and 400 in dark: a Blume preset of the same name, else `{ light, dark }` with those Tailwind values. **Not declared means Docus's emerald:** the site turns Blume's default color unless you offer `theme.accent: "green"`; report it either way |
+| `--ui-radius: 0` in CSS | `theme.radius: "none"` |
+| `toc.title`, `docus.shortcuts`, `search.fts`, other `assistant.*` and `ui.*` keys | drop (report the `ui` overrides) |
+
+| `nuxt.config.ts` | Blume |
+| --- | --- |
+| `site.url` / `NUXT_SITE_URL` | `deployment.site`, unless the host is Vercel or Netlify (SKILL.md) |
+| `routeRules` with `redirect` | `redirects` (see URLs and redirects) |
+| `@nuxtjs/i18n` and `i18n` | see i18n |
+| `llms.notes`, `llms.sections` | `agents.llmsTxt: { details }` as Markdown, if worth keeping; `llms.title`/`description` drop |
+| `mcp` | Docus serves an MCP server at `/mcp` (or `mcp.route`) unless `mcp: false` or `mcp.enabled: false`. To keep one: `agents.mcp: { enabled: true, name }` (and `route` when it isn't `/mcp`) plus a host adapter (server output). Blume's tools are fixed, so report the site's own tools and prompts in `server/mcp/` |
+| `docus.assistant` | Docus turns the assistant on when the build has `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN`: check the live site for it. Keep it as `ai: { assistant: { enabled: true, provider: gateway({ model }) } }` (`gateway` from `blume/ai`; Docus's default model is `google/gemini-3-flash`) plus a host adapter, or drop it (report) |
+| `app.head`, `@vercel/analytics`, `@nuxtjs/plausible`, `@nuxt/scripts` analytics | the provider's factory from `blume/analytics` (`vercel()`, `plausible({ domain })`, `cloudflare({ token })`); other scripts → `script()`; `meta` → `seo.metatags`. `@vercel/speed-insights` has no adapter (report) |
+| `content.build.markdown` (`toc`, `highlight.theme`, plugins), `mdc.highlight.theme` | `toc` and `markdown.code.theme` only when they differ from the defaults; each remark/rehype plugin's syntax converted by hand (report) |
+| `css` | what still applies → a root `theme.css` against Blume's tokens |
+| `studio`, `agentDiscovery`, `ogImage`, `sitemap`, `robots`, `schemaOrg`, `image`, `icon`, `nitro`, `vite` | drop (report). Blume writes its own sitemap, robots, OG images, and JSON-LD |
+
+**A project `content.config.ts`** adds collections such as a blog or changelog. Those aren't docs pages: map a blog to `type: blog` and a changelog to `type: changelog` (or `githubReleases()`, SKILL.md Changelogs), and report anything else.
+
+**Theme overrides** (`AppHeader*.vue`, `AppFooter*.vue`, `Docs*.vue`) aren't content. Map what they add to config (`navigation.cta`, `navigation.actions`, `footer.links`, `banner`), but read their `v-if`s first: a button shown only on the landing page (`route.path === '/'`) belongs on the landing page, since Blume's `cta` shows site-wide.
+
+## Navigation
+
+The codemod writes each `.navigation.yml` as a `meta.ts` (`title`, `icon`) and each page's `navigation` as `sidebar` (`title` → `label`, `icon`, `false` → `hidden`). What's left:
+
+- **A folder's `navigation: false`** hides it: set `sidebar.hidden: true` on its pages (the codemod reports it).
+- **A folder with an `index.md` but no `.navigation.yml`:** Docus labels it with the index page's title. Blume uses the humanized folder name, so set `meta.ts` `title` when they differ.
+- **Order:**
+  - Docus compares paths as text: `1.intro`, `10.faq`, `11.glossary`, `2.setup`. Blume sorts the numbers. In a folder with ten or more unpadded siblings, keep Blume's order (almost always what the author meant) and report the change.
+  - Docus also interleaves pages and subfolders. Blume lists a level's pages above its subfolders, so report a page that sorted after a folder.
+- **Display:** Docus draws every folder as an always-open group, which is Blume's default `flat` display.
+- **`navigation.sub`** (a header tab bar, or anchors in the sidebar) makes each top-level folder a section that scopes the sidebar. That's `navigation.tabs`: one `{ label, path, icon? }` per top-level folder with pages, with `label` and `icon` from its `.navigation.yml`. A section with no index page needs no `href`, since a Blume tab falls back to the section's first page, as Docus did.
+
+## Pages: frontmatter and titles
+
+The codemod maps `navigation`, `links` (header buttons → `related` cards at the foot of the page), and `seo.ogImage`. It removes `layout: docs` and `sitemap`. What's left:
+
+- **No `description`:** when a page opens with a paragraph (after an optional `# H1`), Docus took it as the description, so it showed twice. Blume derives none. To keep the meta description without the repeat, set `seo.description` to that paragraph (optional; say which you did).
+- **`sitemap: false`** has no sitemap-only switch: add `seo: { noindex: true }` only when the page should also leave search engines.
+- **`toc: false`** → `mode: wide` (report), or drop. Another `layout` → a Blume `mode`.
+- **Other keys** Nuxt Content kept and Blume rejects: drop and report each one, or declare it with `frontmatter.extend` if a component you wrote reads it.
+- **Titles:** Docus renders frontmatter `title` in the page header, falling back to the first `# H1`, so a body H1 showed twice. The codemod moves a lone H1 into `title` and reports the rest.
+
+## MDC syntax
+
+The codemod applies these rules; you need them for what it leaves. They're remark-mdc's behavior (checked against `remark-mdc@3.11.1`):
+
+- **Block component:** an opening line `::name`, optionally followed by `{attributes}` and nothing else, then Markdown, then a closing line of colons only.
+  - Props are inline (`{key="value" flag .class #id}`) or a YAML block, from `---` right after the opener to the next `---`. A `:key='[…]'` holds JSON.
+  - Slots are `#name` lines inside the block.
+  - An inline component is `:name[text]{attrs}`; alone on a line, it renders as a block.
+- **Pairing:**
+  - Every opener nests, even at the same colon count.
+  - A closer closes the innermost open block **whose opener has exactly as many colons**, together with anything still open inside it. It must not be indented deeper than that opener. Any other colon line, or a `::` mid-line, is text.
+  - An unclosed block runs to the end of its parent, and a closer inside a code fence is code.
+  - Check the old HTML for a literal `::` to see what the live site already showed broken.
+- **MDX safety:** in a `.mdx` page, prose must escape `{` and `}` as `\{` and `\}`, and turn **any `<` followed by a non-space character** into `&lt;` (or `\<`) unless it opens a real tag: `useFetch<User>()`, `<script setup>` written as text, `<50 ms`, `<= 5`. Case matters as in JSX: `<input>` is HTML, but `<Input>` is a component, so a generic like `useTool<Input>()` is text. HTML comments become `{/* … */}`, `<https://…>` autolinks become links, and `<br>` becomes `<br />`. Code spans and `$$` math stay as written.
+- **Code fences:** ` ```ts [file.ts]{2} ` → ` ```ts file.ts {2} ` (`title="Two words"` for a label with spaces). Blume reads ` ```ts [file.ts]{2} ` and a multi-word title as written too, the range highlighting its lines, so this only tidies. Leave MDC samples inside fences alone: they're documentation.
+
+## What the codemod leaves
+
+- **Custom components:** `app/components/content/*.vue`, or a Nuxt module's. Read the SFC to see what it renders and which props and slots it reads, then convert it:
+  - to Markdown
+  - to a Blume component
+  - to a static `.astro` component registered in `components.ts`
+  - to the `.vue` file as an island in `islands/`, with `@astrojs/vue` and `vue` installed. `:items='["a"]'` becomes `items={["a"]}`, and named slots become props or children.
+
+  Report each one. A component that rendered nothing on the live site (an unknown tag) has nothing to convert.
+
+- **Callouts with `to`:** the whole callout was a link. Add the link to its text when it isn't there already.
+- **Card descriptions:** Nuxt UI's prose card renders neither a `description` prop nor a `#description` slot, so that text never showed. The codemod keeps it as the card's body and flags it: keep it, or delete it to match the old page.
+- **Blocks with a slot the conversion doesn't read** (a card's `#footer`, a tab's extra slot) stay as written: convert them by hand.
+- **`code-tree`** becomes a `<CodeGroup>` titled by file path. The tree view is gone; a `<FileTree>` before it can show the layout.
+- **`prompt`:** Blume has no `windsurf` or `claude` action, and no prompt icon (the codemod reports both).
+- **Prose about features that didn't carry over:** grep the content for the dropped MCP tool and prompt names, `docus`, `/.well-known/skills`, and `Studio`, and list every page that now says something false.
+
+## Landing page
+
+`content/index.md` renders full-width, with no sidebar, title, or table of contents. Its `title` and `description` feed only the meta tags. The codemod leaves its `u-page-*` and custom components as written.
+
+- **Markdown landing** → `index.mdx` with `mode: custom` (no title or sidebar rendered, so write the heading) and `sidebar.hidden: true` (Docus never listed it).
+- **A designed landing**, or `app/pages/index.vue` → `pages/index.astro` on `PageLayout`.
+
+| Nuxt UI | Blume, in the `mode: custom` page |
+| --- | --- |
+| `u-page-hero` (`title`, `description`, `links`, or slots) | `# Title`, a paragraph, and a line of Markdown links; the primary one can also be `navigation.cta` |
+| `u-page-section` | `## Title`, a paragraph, and its features as cards |
+| `u-page-feature`, `u-page-card` (`title`, `description`, `icon`, `to`) | `<Card title icon href>description</Card>` in `<CardGroup cols={3}>` |
+| `u-page-grid`, `u-page-columns` | `<CardGroup cols={3}>` |
+| `u-button`, `u-page-cta` | Markdown links; a heading and a paragraph |
+| `u-page-logos`, decorative `div`s (glows, gradients) | a row of images, or drop (report) |
+
+## Icons
+
+Blume resolves Lucide names only (`zap`, or `lucide:zap`); **anything else renders nothing.** The codemod converts `i-lucide-*` (aliases of renamed icons included) and reports the rest:
+
+- **Other sets** (`i-heroicons-*`, `i-ph-*`): the closest Lucide name, checked at [lucide.dev/icons](https://lucide.dev/icons).
+- **Brands** (`i-simple-icons-*`): Lucide has a few (`github`, `gitlab`, `slack`, `linkedin`, `youtube`), but **`i-simple-icons-x` is not Lucide's `x`, a close cross.** Otherwise, save the SVG under `public/` and pass its path (`icon="/icons/nuxt.svg"`), or drop it (report).
+- **`i-custom-*`** (Docus's `app/assets/icons/*.svg`): copy the SVG to `public/icons/` and pass the path.
+
+## i18n
+
+Docus i18n is `@nuxtjs/i18n` (`defaultLocale`, `locales: [{ code, name }]`) plus one `content/<code>/` folder per locale, and it forces the `prefix` strategy: every locale is under its code, the default included, and `/` redirects to the default.
+
+- Move `content/<default>/` up to `content/` (a default-locale folder warns `BLUME_I18N_DEFAULT_LOCALE_FOLDER`). Keep the others as `content/<code>/`, and run the codemod on `content/`.
+- Write `i18n: { defaultLocale, locales: [{ code, label }], hideDefaultLocalePrefix: false }`, `label` = `name`. That keeps every `/en/…` URL. Nothing serves `/` then, so add `{ from: "/", to: "/<default>", status: 302 }` as Docus did.
+- **Regional codes are lowercase in Docus URLs** (`zh-TW` → `/zh-tw/…`): use the lowercase code as Blume's `code` and folder.
+- Leave out any configured locale with no `content/<code>/` folder: Docus skipped it.
+
+## URLs and redirects
+
+Docus routes a page by its path under `content/`. It strips an `N.` prefix from each segment, drops `index`, and slugifies (lowercase, spaces → `-`). Blume strips `N.`, `N-`, and `N_` prefixes and `index` the same way, so **most URLs carry over unchanged**, with no trailing slash or `.html` to redirect. The codemod reports the exceptions:
+
+- **A dash prefix** (`01-intro.md`) stays in the Docus URL and Blume strips it: pin `slug` or redirect.
+- **Uppercase letters or spaces** were lowercased by Docus: rename the file.
+- **A version name** (`1.x`, `2.0`) stays whole in Docus: pin `slug`.
+- **`_` files** are pages in Docus and excluded by Blume: rename them.
+
+**Redirects:**
+
+- **`routeRules` → `redirects`.** A string `redirect` is a 307 in Nitro (`status: 307`); `{ to, statusCode }` → `{ to, status }`. A `/**` key strips its base: `'/old/**': { redirect: '/new/**' }` → `{ from: "/old/:path*", to: "/new/:path*" }`.
+- **`/raw/<route>.md`** is the Markdown copy of each page, which Docus links from `llms.txt`. Blume serves it at `/<route>.md`, so one rule covers it: `{ from: "/raw/:path*", to: "/:path*" }`. A `routeRules` redirect between two `/raw/…md` paths should target Blume's copy directly (`/raw/old.md` → `/new.md`), or it chains through that rule.
+- **Agent skills:** a `skills/` folder Docus published under `/.well-known/skills/` → `agents.skills: "./skills"`. Blume publishes them under `/.well-known/agent-skills/`, a skill with references as one `.tar.gz`. Redirect the old index to the new one, and report the change. Links can name the new index (`/.well-known/agent-skills/index.json`): `blume validate` accepts the files Blume generates.
+- **Anchors:** MDC slugs headings like Blume (`github-slugger`), then collapses repeated dashes, trims edge dashes, and prefixes a leading digit with `_`. `## Name & Title` is `#name-title` in Docus and `#name--title` in Blume; `## 1. Install` is `#_1-install`. After the first build, run `node <skill>/scripts/pin-heading-ids.mjs --old <old build>`, `--write`, and rebuild until it reports 0. On a server build (`vercel()`, `node()`) it reads the pages from `dist/client` itself.
+- **Verify** every old URL: a built page, or a redirect `from` whose target is built (SKILL.md Verification).
+
+## Deploy and teardown
+
+- **Keeping the assistant or the MCP server** needs server output: `deployment: vercel()` (or `node()`, `netlify()`, `cloudflare()`). `blume preview` can't serve a `vercel()` build, so check it with `blume dev`, then a preview deployment.
+- **Vercel with `vercel()`:**
+  - The build writes the Build Output API folder `.vercel/output` in the Blume project, not `dist/`.
+  - In the project's `vercel.json`, set `"framework": null` and the install and build commands (`references/monorepo.md` §4 for a workspace), and **no `outputDirectory`**. `framework: null` overrides a project still set to the Nuxt preset.
+  - In the dashboard, set the Root Directory to the docs package and Node to 22.19 or later. Set `AI_GATEWAY_API_KEY` unless the project relies on Vercel's OIDC token.
+  - With Turborepo, add `.vercel/output/**` to the docs' build outputs.
+  - List the dashboard settings as steps for the user.
+- **Dependencies:** remove `docus`, `nuxt`, the `@nuxt/*`/`@nuxtjs/*` modules, `nuxt-studio`, `better-sqlite3`, `@iconify-json/*`, `tailwindcss` (if only the theme used it), mapped analytics packages, `@nuxt/eslint-config`, and `vue` (keep it with `@astrojs/vue` for islands). Keep what the site's tests or scripts still import.
+- **Scripts:** `dev`/`build`/`generate`/`preview` → `blume dev`/`build`/`build`/`preview`. **Delete `postinstall: nuxt prepare`**, which fails once Nuxt is gone.
+- **Files:** after harvesting, delete `nuxt.config.ts`, `app/`, `content.config.ts`, `server/` (report its routes), and a Nuxt `eslint.config.mjs`. The codemod leaves a `.navigation.yml` whose keys `meta.ts` can't hold.
+- **`tsconfig.json`:** a Nuxt one points into `.nuxt/`, and `blume build` then fails with `BLUME_TSCONFIG_EXTENDS`. Delete or replace it.
+- **`.gitignore`:** in the docs package's own file, `.nuxt`, `.output`, `.data` → `.blume`, `dist`.
+- **CI:** grep for `nuxt generate`, `nuxi`, `.output/public`, and `--extends docus`.
+
+## Docus 1.x (`@nuxt-themes/docus`)
+
+Written from `@nuxt-themes/docus@1.15.1` and `@nuxt-themes/elements@0.9.5`. Everything above applies (run the codemod for fences, frontmatter, and the H1), with these differences:
+
+- **Config** is `app.config.ts` → `docus: { … }`:
+  - `title`, `description` → same keys
+  - `url` → `deployment.site`
+  - `socials` → `footer.socials`. Values are handles (`twitter: '@nuxt_js'`, `github: 'owner/repo'`), so build each URL.
+  - `github: { owner, repo, branch, dir }` → `github`
+  - `header.logo`/`title` → `logo`/`title`
+  - `aside.collapsed` → `navigation.sidebar.display: "group"`
+  - `footer.textLinks`/`iconLinks` → `footer.links`
+  - everything else → drop (report)
+- **Folders** use `_dir.yml` (`title`, `icon`, `navigation: false`, `navigation.redirect` → a redirect from the folder's route).
+- **Titles** are the body `# H1` (the codemod moves it).
+- **Frontmatter:**
+  - `layout: page` → `mode: custom` or `mode: center`
+  - `aside: false` → `mode: center`
+  - `toc: false` → `mode: wide`
+  - `redirect` → a redirect
+  - `bottom`, `header`, `fluid`, `main` → drop
+- **Components** (Nuxt Elements, left as written and reported):
+  - `::alert{type}` → that directive (`primary` → `tip`)
+  - `::callout{type}` with `#summary`/`#content` → the directive holding the summary, then `<Expandable title="Details">` around the content
+  - `::list{type}` → a plain list
+  - `::badge{type}` → `<Badge>`
+  - `::button-link{href}` → a link
+  - `::terminal{content}` → a `bash` fence
+  - `::card-grid` + `::card{icon}` with `#title`/`#description` → `<CardGroup>` + `<Card>`
+  - `::block-hero` → the landing page
+  - `::code-block{label}` → a titled fence in `<CodeGroup>`
+  - `::video-player{src}` → `<video>`
+  - `::sandbox`, `::props`, `::copy-button`, `:ellipsis` → drop (report)
+- **URLs:** Nuxt Content 2 routes the same way, so check the old sitemap for trailing slashes and pin heading ids as above.
+
+## Dropped — report these
+
+Report each of these, and anything else you drop:
+
+- **Theme:**
+  - the brand color, when it was Docus's default emerald
+  - Nuxt UI overrides and theme CSS that doesn't map
+  - a custom `seo.titleTemplate`, `seo.schema`, and the TOC title
+  - logo extras, and socials with no Blume platform
+  - a forced color mode (the toggle stays)
+  - `navigation.sub: 'aside'` anchors
+  - a header button that showed only on the landing page (now site-wide)
+- **Navigation:** text-order sorting (`10.` before `2.`), and pages that sorted after a folder.
+- **Frontmatter:**
+  - `links` (now `related` cards)
+  - `sitemap: false`, `toc`, `layout`, and other unknown keys
+  - derived descriptions
+- **Components:**
+  - callout `to` links, callout colors (mapped to the nearest type; `<Callout color>` takes a CSS color when a tint matters), and card colors
+  - prompt icons and Windsurf/Claude actions
+  - the `code-tree` file browser and `code-preview` live rendering
+  - Nuxt UI landing decorations
+  - custom and module components
+  - brand icons with no SVG
+- **Server features:**
+  - the site's own MCP tools and prompts
+  - server routes and `@vercel/speed-insights`
+  - the assistant, if not kept
+  - old `/.well-known/skills/` file URLs, and pages whose prose describes any of these
+- **Anchors:** old ids that were already broken.

package/skills/blume-migrate/references/docusaurus.md

@@ -23,10 +23,10 @@ Read `themeConfig`, `presets`, and `plugins`:
 | `themeConfig.colorMode.defaultMode` | `theme.mode` (`respectPrefersColorScheme: true` → `"system"`) |
 | `themeConfig.prism.theme` / `.darkTheme` | `markdown.code.theme: { light, dark }` (map Prism theme names to Shiki themes, e.g. `github`/`github-dark`) |
 | `themeConfig.metadata` / `themeConfig.image` | per-page `seo` frontmatter / `seo.og`; report what doesn't fit |
-| `url` + `baseUrl` | **`url` → `deployment.site`**, unless the target host is Vercel, Netlify, or Cloudflare Pages, which Blume auto-detects (see SKILL.md — GitHub Pages, a common Docusaurus host, is not one of them); `baseUrl` (when not `/`) → `deployment: { base: "/…" }`, or the `base` option of a host adapter (`vercel({ base })`) when the site also needs one |
+| `url` + `baseUrl` | **`url` → `deployment.site`**, unless the target host is Vercel or Netlify, which Blume auto-detects (see SKILL.md — GitHub Pages, a common Docusaurus host, is not one of them); `baseUrl` (when not `/`) → `deployment: { base: "/…" }`, or the `base` option of a host adapter (`vercel({ base })`) when the site also needs one |
 | preset `docs.routeBasePath` — **including the default!** | Docusaurus serves docs at **`/docs/…` by default**; the "map only declared fields" rule does **not** apply here because the _URLs_ are load-bearing. Either keep them with top-level **`basePath: "/docs"`** (invisible to the sidebar), or intentionally move to root and emit a `redirects` entry per page. Decide explicitly and say which. (`routeBasePath: '/'` = docs-only mode — nothing to do.) |
 | preset `docs.editUrl` | `github` (owner/repo/branch; a path after the branch → `github.dir`; **an origin other than `https://github.com` → `github.host`** — a GitHub Enterprise repo's edit links and header mark point at the public site without it) |
-| `themeConfig.footer` | `footer.links`, one row of `{ label, href }`: every column's items flatten into it in order (an item's `to`, a route, is its `href`); column `title`s, `copyright`, `logo`, and `style` drop (report), or keep the whole footer as a Footer override (`defineComponents` layout slot) |
+| `themeConfig.footer` | `footer.links`, one row of `{ label, href }`: every column's items flatten into it in order (an item's `to`, a route, is its `href`); `copyright` (HTML) → `footer.copyright`, plain text: strip the tags, decode entities (`&copy;` → `©`), keep a `${new Date().getFullYear()}` template literal as written, and drop a "Built with Docusaurus." credit; a link inside it loses its URL (report, or add it to `footer.links`); a translated one in `i18n/<locale>/docusaurus-theme-classic/footer.json` → a locale map; column `title`s, `logo`, and `style` drop (report), or keep the whole footer as a Footer override (`defineComponents` layout slot) |
 | `themeConfig.announcementBar` | `banner` (`{ content, dismissible, id }` — `isCloseable` → `dismissible`; colors drop) |
 | `i18n.locales` / `defaultLocale` | `i18n` — translated files live at `i18n/<locale>/docusaurus-plugin-content-docs/current/…`; move them to `<locale>/…` under `content.root` |
 | `themeConfig.algolia` | drop — Blume ships built-in search (Orama); remove the Algolia dep. To keep the index, `search: algolia({ appId, apiKey, indexName })` from `blume/search` (the DocSearch `apiKey` is the search-only key) |
@@ -59,11 +59,11 @@ A Docusaurus `blog/` → Blume `type: blog` pages. **Dates come from filenames/f
 ## Content & components
 
 - **`.md` vs `.mdx` — both majors need renames, for opposite reasons.** Blume parses `.md` as plain Markdown: no directives, no JSX, no `$$` math, no mermaid/package-install fences. **v3** treats `.md` as MDX (so a `.md` with imports/JSX/`{}` renders them as literal text in Blume); **v2** content is looser MDX v1. Rule: **rename any `.md` that contains admonitions, JSX, imports, or math to `.mdx`** — for typical Docusaurus repos that is most files.
-- **Admonitions are directives — but check the version.** v3: `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger` pass through; `:::caution` → `:::warning` (or rely on Blume's alias); titles `:::note[Title]` work. **v2:** titles are space-separated (`:::note Your Title`) — rewrite to brackets or the title is silently lost; and v2's `:::warning` rendered **red/danger** — audit whether it should become `:::danger`.
+- **Admonitions are directives — but check the version.** v3: `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger` pass through; `:::caution` → `:::warning` (or rely on Blume's alias); titles `:::note[Title]` work. **v2:** titles are space-separated (`:::note Your Title`) — rewrite to brackets or the title is lost (`BLUME_DIRECTIVE_OPENING_TEXT` names each one); and v2's `:::warning` rendered **red/danger** — audit whether it should become `:::danger`.
 - **Tabs:** `<Tabs>`/`<TabItem label="…" value="…">` → `<Tabs>`/`<Tab title="…">`. Drop `groupId`/`queryString`/`value`; strip the `@theme/Tabs` imports.
 - **Theme JSX in content:** `<DocCardList/>` (standard on category index pages) → delete it and set `directory: "card"` in that folder's `meta.ts`: Blume then lists the folder's pages as cards below the `index` page's content and keeps the list current (nested folders inherit the setting; give one `directory: "none"` to opt out). A hand-written `CardGroup` is only for a curated subset; `<TOCInline/>` → drop (report); `<CodeBlock>` JSX → a fenced code block; `<Admonition>` → the matching directive; `<details>`/`<summary>` → `<Accordion>`/`<AccordionItem>` or leave as raw HTML.
 - **`@theme/*` / `@site/*` imports** — strip `@theme/*` (Blume injects components globally); rewrite `@site/` asset/module paths to `/public` URLs or inline. **MDX partials** (`_partial.mdx` imports) → inline the partial's body (Blume's default `**/_*` exclude already hides the partial files themselves).
-- **Code blocks:** `title="file.js"` → works as-is; `showLineNumbers` → `lineNumbers`; **magic comments** (`// highlight-next-line`, `highlight-start`/`end`) → `{ranges}` or `// [!code highlight]` — unconverted they ship as literal comments in every sample; ` ```bash npm2yarn ` → ` ```package-install `.
+- **Code blocks:** `title="file.js"` → works as-is; `showLineNumbers` → `lineNumbers` (`BLUME_CODE_FENCE_OPTION` flags any left); **magic comments** (`// highlight-next-line`, `highlight-start`/`end`) → `{ranges}` or `// [!code highlight]` — unconverted they ship as literal comments in every sample; ` ```bash npm2yarn ` → ` ```package-install `.
 - **MDX v1 (v2 sources) pitfalls:** unescaped `<`/`{` in prose, HTML comments `<!-- -->` (→ `{/* */}`), string `style="…"` attributes (→ objects). Fix as build errors surface.
 
 ## Frontmatter
@@ -95,4 +95,4 @@ Remove `@docusaurus/*` and Algolia deps; delete `docusaurus.config.*`, `sidebars
 
 ## Dropped — report these
 
-Custom/swizzled theme components (layout slots or `blume eject`), the footer's copyright, logo, and HTML items, the blog's generated tag, author, and archive pages, Algolia config, `sidebar_custom_props` and the other dropped frontmatter keys, `createRedirects` functions (→ host rules), React pages under `src/pages/`, `<TOCInline>`, per-category `className`/`customProps`, and any `@theme/*` component with no Blume equivalent.
+Custom/swizzled theme components (layout slots or `blume eject`), the footer's logo and HTML items (and any link inside its copyright), the blog's generated tag, author, and archive pages, Algolia config, `sidebar_custom_props` and the other dropped frontmatter keys, `createRedirects` functions (→ host rules), React pages under `src/pages/`, `<TOCInline>`, per-category `className`/`customProps`, and any `@theme/*` component with no Blume equivalent.