{"owner":"middleapi","repo":"orpc","hasSkills":true,"totalSkillsCount":56,"totalTokensCount":393304,"categories":["anthropic-skill","claude-rule","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/blume-migrate/SKILL.md",".agents/skills/blume-migrate/references/docsify.md",".agents/skills/blume-migrate/references/docus.md",".agents/skills/blume-migrate/references/docusaurus.md",".agents/skills/blume-migrate/references/fern.md",".agents/skills/blume-migrate/references/fumadocs.md",".agents/skills/blume-migrate/references/gitbook.md",".agents/skills/blume-migrate/references/github-wiki.md",".agents/skills/blume-migrate/references/jekyll.md",".agents/skills/blume-migrate/references/mdbook.md",".agents/skills/blume-migrate/references/mintlify.md",".agents/skills/blume-migrate/references/mkdocs.md",".agents/skills/blume-migrate/references/monorepo.md",".agents/skills/blume-migrate/references/nextra.md",".agents/skills/blume-migrate/references/readme.md",".agents/skills/blume-migrate/references/redocly.md",".agents/skills/blume-migrate/references/starlight.md",".agents/skills/blume-migrate/references/vitepress.md",".agents/skills/blume-migrate/references/vuepress.md",".agents/skills/blume-update-docs/SKILL.md",".agents/skills/blume-update-docs/references/audit-checklist.md",".agents/skills/blume/SKILL.md","CLAUDE.md","packages/ai-sdk/README.md","packages/arktype/README.md","packages/bun/README.md","packages/client/README.md","packages/cloudflare/README.md","packages/contract/README.md","packages/effect/README.md","packages/evlog/README.md","packages/hibernation/README.md","packages/json-schema/README.md","packages/lock/README.md","packages/mcp/README.md","packages/msw/README.md","packages/nest/README.md","packages/next/README.md","packages/node/README.md","packages/openapi/README.md","packages/opentelemetry/README.md","packages/pinia-colada/README.md","packages/pino/README.md","packages/publisher/README.md","packages/ratelimit/README.md","packages/server/README.md","packages/shared/README.md","packages/swr/README.md","packages/tanstack-query/README.md","packages/trpc/README.md","packages/valibot/README.md","packages/zod/README.md","skills/orpc-contract/SKILL.md","skills/orpc-migrate/SKILL.md","skills/orpc-openapi/SKILL.md","skills/orpc/SKILL.md"],"skills":{".agents/skills/blume-migrate/SKILL.md":"---\nname: blume-migrate\ndescription: Migrate an existing documentation site (Mintlify, Docusaurus, Fumadocs, Nextra, Starlight, VitePress, VuePress, Docus, MkDocs, mdBook, Fern, GitBook, ReadMe, Redocly, Docsify, Jekyll (Just the Docs), GitHub Wiki, or any docs framework) to Blume, the markdown-first docs framework on Astro. Translate the source config to blume.config.ts, restructure content into Blume's filesystem-derived navigation, rewrite JSX callouts to directives, convert icons to Lucide, and inline snippets. Use when the user asks to migrate/convert/port a docs repo to Blume, or when the repo has a docs.json/mint.json, docusaurus.config.*, meta.json with fumadocs, _meta.* with nextra, an astro.config.* with starlight(), a .vitepress/config.* or .vuepress/config.*, an mkdocs.yml or zensical.toml, a book.toml (mdBook), a fern/docs.yml, a GitBook .gitbook.yaml/gitbook-docs.yaml, ReadMe _order.yaml files in docs/ or reference/, a Redocly sidebars.yaml or @redocly/realm dependency, an index.html that sets window.$docsify, a docus or @nuxt-themes/docus dependency, a Jekyll _config.yml (Just the Docs theme), or a GitHub wiki clone (Home.md with _Sidebar.md, [[Page Name]] links).\n---\n\n# Migrate to Blume\n\nBlume is a **markdown-first** documentation framework on Astro/Vite. You drop Markdown/MDX into a folder and get navigation, search, theming, Open Graph images, and a component library with no app boilerplate — **the framework is the template**. There is no starter to clone; the only thing a project owns is its content and a `blume.config.ts`.\n\nYour job is to convert a source docs repo into an **idiomatic** Blume project — not a 1:1 transliteration. Read this file, detect the source framework, open the matching `references/.md` for the exact mappings, and work the loop below. Report everything you drop or approximate.\n\nThroughout this skill (including the `references/` files), **`` means the absolute path of the directory containing this SKILL.md** — resolve it from wherever you read this file (e.g. `node_modules/blume/skills/blume-migrate` or `.claude/skills/blume-migrate`). It is a placeholder to substitute, never a literal path.\n\n## Migration philosophy\n\n- **Target idiomatic Blume, not a mechanical port.** Prefer filesystem-derived navigation over an exhaustive explicit `navigation.sidebar`. Prefer `:::` directives over JSX callouts. Prefer Blume defaults over restating them in config.\n- **Every field has a default; `{}` is a valid config.** Map only what the source _declares_. If the source uses a framework default, don't write it.\n- **Drop chrome that has no Blume equivalent — and say so.** Navbar CTAs, custom theming, conditional redirects, and unmappable icons get reported to the user, not silently discarded or faked.\n- **Convert, don't preserve.** Blume's page frontmatter schema is **strict** — unknown keys are build errors. A source-only frontmatter key must be mapped to a Blume key or removed (and reported), never left to \"maybe validate.\"\n\n## Migration workflow\n\n1. **Detect the source framework** and read its reference file:\n - `docs.json` / `mint.json` → **Mintlify** (`references/mintlify.md`) — the deepest, config-declared nav.\n - `docusaurus.config.*` → **Docusaurus** (`references/docusaurus.md`).\n - `meta.json` + `fumadocs-*` deps (content under `content/docs/`) → **Fumadocs** (`references/fumadocs.md`).\n - `_meta.{js,ts,json}` + `nextra` deps → **Nextra** (`references/nextra.md`).\n - `astro.config.*` calling `starlight({…})` → **Starlight** (`references/starlight.md`).\n - `.vitepress/config.{js,ts,mjs,mts}` (often `docs/.vitepress/`) or a `vitepress` dependency → **VitePress** (`references/vitepress.md`). `.vuepress/` is VuePress (next bullet).\n - `.vuepress/config.{js,ts,mjs}` (v1 also `config.yml`/`config.toml`; often `docs/.vuepress/`), a `vuepress.config.*`, or a `vuepress` dependency → **VuePress** (`references/vuepress.md`). It builds on `references/vitepress.md` for the Markdown layer the two share, so read both.\n - A `docus` dependency (often in `docs/package.json` beside a `nuxt.config.ts` with `extends: ['docus']`), or `@nuxt-themes/docus` for 1.x → **Docus** (`references/docus.md`). Pages are MDC, Nuxt Content's component syntax: `::note` … `::` is not a Blume directive, and Blume prints it as text (`BLUME_MDC_SYNTAX` warns at its line).\n - `mkdocs.yml`/`mkdocs.yaml` (also Zensical's `zensical.toml` and ProperDocs' `properdocs.yml`) → **MkDocs / Material for MkDocs** (`references/mkdocs.md`): nav declared in config, Python-Markdown extension syntax (`!!!` admonitions, `===` tabs, `--8<--` snippets), and Python deps, so usually no `package.json`. Run `node /scripts/mkdocs-codemod.mjs --write ` first, then `pin-heading-ids.mjs` after the first build.\n - `fern/docs.yml` (beside `fern/fern.config.json`) → **Fern** (`references/fern.md`). A `fern/` folder without `docs.yml` only generates SDKs: the docs are elsewhere.\n - `.gitbook.yaml`/`.gitbook.yml`, `gitbook-docs.yaml`, or a `SUMMARY.md` beside a `.gitbook/` folder → **GitBook** (`references/gitbook.md`). `book.json` + `SUMMARY.md` is the legacy GitBook CLI or HonKit (same reference, its own section); `book.toml` + `src/SUMMARY.md` is mdBook (`references/mdbook.md`).\n - `book.toml` (at the book root, often `docs/`, `book/`, or `guide/` in a code repo; chapters in its `[book] src`, beside a `SUMMARY.md`) → **mdBook** (`references/mdbook.md`). Every URL ends in `.html`, `SUMMARY.md` is the whole nav, and `{{#include}}` pulls anchored code from across the repo: build the old book first, since it's the URL list, the old ids, and the only record of what the includes showed.\n - `sidebars.yaml` or an `@redocly/realm`-family dependency, usually beside a `redocly.yaml` and with Markdoc `{% … %}` tags in pages → **Redocly** (`references/redocly.md`). GitBook pages use `{% … %}` tags too, so check for GitBook's files first. A `redocly.yaml` holding only lint/bundle keys (`extends`, `rules`, `decorators`, `apis`) is Redocly CLI config, not a docs site: keep it and detect the framework from the other signals.\n - `_order.yaml` files in `docs/`, `reference/`, `recipes/`, or `custom_pages/` (ReadMe's bi-directional Git sync), or a CI step running `readmeio/rdme` beside pages with `category`/`parentDoc` (or `category.uri`/`parent.uri`) frontmatter (`rdme` uploads) → **ReadMe** (`references/readme.md`). ReadMe keeps settings, redirects, the glossary, and variables in its dashboard, not the repo, and changelogs only on the `main` branch.\n - An `index.html` setting `window.$docsify` (usually in `docs/`, beside `_sidebar.md`), or `docsify-cli` in `package.json` → **Docsify** (`references/docsify.md`). Run `node /scripts/docsify-codemod.mjs --write --snapshot .docsify-old --group-folders ` first, then `pin-heading-ids.mjs --old .docsify-old --map docsify-routes.json` after the first build. Its default URLs live after `#` (`/#/page`), which no server-side redirect can match; the reference adds a client-side script.\n - `_config.yml` (root or `docs/`) → **Jekyll** (`references/jekyll.md`); Just the Docs is `just-the-docs` in `_config.yml` or the `Gemfile`. Build the old site first with a project-local bundle: the nav comes from front matter (`parent`/`nav_order`) and is rebuilt from the old build's sidebar, and URLs end in `/` or `.html`. A `_toc.yml` beside it is Jupyter Book, not Jekyll. Run `node /scripts/jekyll-codemod.mjs --old --write .` from the Jekyll source dir first, then `pin-heading-ids.mjs --old ` after the first build.\n - A clone of `.wiki.git` (`Home.md` at the root, often `_Sidebar.md` and `_Footer.md`, `[[Page Name]]` links, no config) → **GitHub Wiki** (`references/github-wiki.md`). Never detected: the source is named. Its old URLs stay on github.com, which can't redirect, so the reference writes a route table and link stubs for the old wiki instead of `redirects`. Run `node /scripts/github-wiki-codemod.mjs routes --repo / --write` first, classify `wiki-routes.json`, then `convert --repo / --write`.\n - Anything else → apply this file's mental model directly; there's no framework-specific reference, so inventory by hand.\n - **Also note the host repo, independent of source framework:** a pnpm/Turbo workspace, a non-`docs/` content layout, or a Vercel deploy each need integration steps (`content.root` scoping, `minimumReleaseAge`, lockfile, `vercel.json`, an Astro/Vite patch) — all in `references/monorepo.md`. Read it whenever the target isn't a bare single-package docs folder.\n2. **Inventory the repo** before changing anything (a page whose body is only a `` is a redirect, not a page: add the redirect from its old URL and report it): the config file(s), the content tree, the nav definition, snippets/partials/includes, static assets, OpenAPI/AsyncAPI specs and GraphQL schemas, redirects, i18n locales, custom components, and icon usage. Note what's declared vs. defaulted. Pages the old site published by accident (a `.github/` template, files under dot-folders, planning notes) aren't content: leave them out, add no redirects, and list them in the report.\n3. **Write `blume.config.ts`** with `defineConfig` from `blume`. Map only declared fields (see the reference's mapping table); rely on defaults everywhere else. A minimal result is `defineConfig({ title: \"…\" })`.\n4. **Restructure content.** Put `blume.config.ts` in the directory whose `package.json` runs the old docs build, which may be a workspace package such as `packages/docs` rather than the repo root. Choose `content.root` (default `docs`) — **detect where `.md`/`.mdx` actually live, don't assume a `docs/` folder.** Many repos keep content directly under an app dir (`apps/docs/api/`, `.../getting-started/`) with no `docs/` subfolder; when so, set `content.root` to that dir and scope `content.include` to the real content folders rather than leaving a bare `content.root: \".\"` that scans everything (see `references/monorepo.md` §1). Order with numeric prefixes (`01-intro.mdx`), group without a URL segment via `(group)/` folders, and add a `meta.ts` (`defineMeta`) only where filesystem order isn't enough. **A source that already declares per-folder navigation in a sidecar file — Fumadocs `meta.json`, Nextra `_meta.*` — _is_ that case: convert each one to a `meta.ts`, carrying over its title/icon/order/collapse, rather than dropping it and hoping filenames reproduce the intent. Filesystem inference is the fallback for folders that declare no per-folder nav, never a reason to discard one that does.** A group that exists only in the source's nav config, with its pages flat on disk, becomes a **`(group)/` folder**: it adds the sidebar group and keeps every URL, with no redirects (moving pages a folder deeper instead changes their URLs and breaks their relative asset paths). Reach for an explicit `navigation.sidebar` only when the source nav genuinely can't be expressed by files. **Reshaping into folder-per-tab moves URLs** — track every old→new path as you go; you'll turn them into `redirects` in step 5.\n5. **Rewrite pages.** Map frontmatter to Blume's strict schema; convert callout JSX to `:::` directives — **directives (and math/mermaid/package-install fences) are MDX-only, so rename any `.md` page that needs them to `.mdx`**; rename components; turn snippets/partials into `` statements or inline them (Blume has no import-based includes: `import Snippet from \"…\"` plus `` has to become one or the other; when a source includes part of a file (mdBook `ANCHOR`s, VitePress `#region`s, MkDocs snippet line ranges) or a file outside the content root, copy `/scripts/include-excerpts.mjs` into the project and run it before every `dev`, `build`, and `validate` rather than pasting code the project compiles: it reports every missing anchor or region in one pass, and a restored marker in the source beats a line range, which goes stale silently); fix asset paths; **rewrite internal links** to their new routes (including OpenAPI/GraphQL operation links — see the API-reference sections, their slugs differ from most sources — and links inside OpenAPI descriptions, which Blume renders and validates, though a redirect `from` hides a stale one; rewrite links that hardcode the old site's own origin to root-relative paths); **add a `redirects` entry for every route you moved** in step 4 (a hash-routed source like Docsify also needs its reference's client-side redirect, because `redirects` only see paths); **convert every icon name to Lucide** (Blume is Lucide-only — no FontAwesome/Tabler). Remove any duplicated H1 in the body (`title` renders the H1; bodies start at `##`), and fix links to its anchor (`#`), which no longer exists: drop the fragment. `blume validate --strict` also reports fragments the old site never checked; fix each or drop it, and report it. A page with no frontmatter `title` takes its opening `# H1` as the title and shows it once, so that one can stay; moving it into `title` is still the idiomatic form. **If the source has a hand-maintained changelog and the repo is open source on GitHub, offer to swap it for the `githubReleases()` source** (see \"Changelogs\" below) rather than porting the entries. For **Mintlify**, run the bundled codemod first — `node /scripts/mintlify-codemod.mjs --write ` deterministically remaps icons and drops/renames unsupported frontmatter keys, and reports the rest (unknown icons, OpenAPI-stub flags) for you to finish by hand (see `references/mintlify.md`). For **Docus**, run the bundled codemod first: `node /scripts/docus-codemod.mjs --write content` pairs MDC blocks as remark-mdc does, converts the Nuxt UI prose components, fence labels, icons, frontmatter, and `.navigation.yml` files, makes the MDX prose safe, and lists every `REVIEW` item (custom and landing-page components stay as written; check them against the live site, not only a local build; see `references/docus.md`). For **VitePress**, run the bundled codemod first: `node /scripts/vitepress-codemod.mjs --write ` converts containers (paired as markdown-it pairs them), code groups, alerts, fence labels, `<<<` imports and includes, `.html` links, badges, and H1 titles, and lists every `REVIEW` item for you to finish (see `references/vitepress.md`). Before converting any source's components, check its built output: a component its theme never registered rendered nothing there (``), so converting it shows content readers never saw; report it. For **mdBook**, convert every `{{#…}}` helper before anything else: anchored, line-range, and out-of-root code becomes generated excerpts, one-line files become `variables`; then strip hidden `# ` lines and `rust,…` fence attributes, and convert admonish blocks (see `references/mdbook.md`). For **Jekyll**, convert every Kramdown IAL (`{: .note }`) and Liquid tag: in `.md` they ship as literal text (a Liquid tag warns `BLUME_TEMPLATE_TAG`, an IAL `BLUME_MD_ATTRIBUTE_LIST`), and in `.mdx` they fail the build (`blume check` names each IAL's line as `BLUME_MDX_ATTRIBUTE_LIST` and a Liquid tag's as `BLUME_MDX_SYNTAX`, at the partial's own line for one in an included partial). Run the bundled codemod first: it converts callout IALs, the in-page TOC, H1s, front matter, Markdown includes, and Liquid links and variables, rebuilds the Just the Docs sidebar as folders, `slug`s, and `meta.ts`, and writes the redirects and variables to `jekyll-migration.json` (see `references/jekyll.md`). For a **GitHub Wiki**, run the bundled codemod (`routes`, then `convert`): it builds the route table (one flat route per page name) and converts every `[[…]]` link outside code, which Blume would otherwise render as literal text (`BLUME_WIKILINK_UNSUPPORTED` warns only for one that names a page or has a `|`; Markdown pages put the link text first: `[[text|Page]]`). For **Redocly**, convert every Markdoc `{% … %}` tag: Blume never parses them, so an unconverted tag ships as literal text in `.md` (`BLUME_TEMPLATE_TAG` warns at its line) and fails an `.mdx` build. For **VuePress**, rename every `README.md` to `index` first, then run the VitePress codemod (its limits on VuePress content are in `references/vuepress.md`), then grep for hyphenated theme tags (``, ``, ``): they pass through `.mdx` as unknown HTML elements with no diagnostic. For **MkDocs**, decide `.md` vs `.mdx` per page before converting: MDX rejects HTML comments, `` autolinks, unclosed void tags, and `{…}` attribute lists that Python-Markdown accepts (`blume check` names each at its line: `BLUME_MDX_SYNTAX` for what MDX can't parse, and the last two as `BLUME_MDX_UNCLOSED_ELEMENT` and `BLUME_MDX_ATTRIBUTE_LIST`), and snippet paths resolve from the snippets `base_path` (default: where MkDocs runs), not the page (see `references/mkdocs.md`). For **Fern**, URLs come from `docs.yml`, not file paths: run `node /scripts/fern-codemod.mjs --sitemap old-urls.txt` before moving anything (dry run, then `--write`), and after the first build its `endpoints` step, which joins `operation-routes.mjs` output to Fern's old API URLs and writes `fern-redirects.json`; export a Fern Definition to OpenAPI with `fern export` (see `references/fern.md`). For **GitBook**, put each page at its old URL first (GitBook's URLs follow `SUMMARY.md`, not the file tree), then convert every `{% … %}` tag: in `.md` an unconverted tag ships as literal text (`BLUME_TEMPLATE_TAG` warns), and in `.mdx` it fails the build. For **ReadMe**, run the bundled codemod first: `node /scripts/readme-codemod.mjs --write --site --glossary .` keeps every page at its flat URL, converts callouts, `doc:`/`ref:` links (`blume validate` names any left as `BLUME_UNSUPPORTED_LINK_SCHEME`), ReadMe components, and frontmatter, writes `meta.ts`, overlays, and redirects, and lists what needs a person; after the first build, its `--routes` pass adds the endpoint redirects and per-tag order (see `references/readme.md`). A pasted widget's JSX event handler (`onClick={…}`) builds green and never runs on a static page: `BLUME_MDX_EVENT_HANDLER` names each one, so move the widget into an island (`islands/`) or drop it and report it.\n6. **Adopt `package.json`.** Repoint `dev`/`build`/`start` → `blume dev`/`blume build`/`blume preview`, remove the old framework's deps, add `blume`. A config-only source (e.g. a bare Mintlify `docs.json`) has no manifest — scaffold one. **In a pnpm workspace:** if `pnpm-workspace.yaml`/`.npmrc` sets `minimumReleaseAge`, add **only** `blume` to `minimumReleaseAgeExclude` (don't disable the guard) so the just-published version installs. Yarn's `npmMinimalAgeGate` refuses a fresh `blume` the same way: add it to `npmPreapprovedPackages`. **Always regenerate the lockfile in the same change** with the repo's own package manager (`pnpm install` from the workspace root, `yarn install`, `npm install`, or `bun install`; check `packageManager` and the lockfile's name) and commit it alongside `package.json` — CI and hosts install from a frozen lockfile, so a stale one fails the build before it starts. After creating the first new file in the content root (a `meta.ts`, a partial), run `git check-ignore -v /meta.ts`: a repo `.gitignore` rule that covers the content root leaves every new file out of `git add` while the old pages stay tracked, so fix the rule or report that each new file needs `git add -f`. Blume needs **Node 22.19 or later**: update `.nvmrc`/`.node-version`, `engines.node`, and any CI `node-version` in the same change. pnpm 11 and later run a dependency's build script only once `pnpm-workspace.yaml` approves it: add `allowBuilds: { esbuild: true }` (plus `\"@scarf/scarf\": false`, as `blume init` writes) unless the workspace already lists `esbuild`, keeping its other entries. Add `.blume/`, `dist/`, and `.env.local` to the docs package's own `.gitignore` when it has one, else the root's (as `blume init` does; a `vercel()` build appends `.vercel/` itself), and remove any line that ignores `public/` before moving assets into it. **`blume build` empties `/dist`:** if the host repo already uses `dist/` for something else (Python wheels, a library build), put the Blume project in its own folder (`docs/`). If the repo formats with Prettier, extend its `*.md` overrides (`.prettierrc`, `.editorconfig`) to `*.mdx` and keep `{/* */}` comments on one line. After renaming or moving pages, grep the whole repo (release config, CI, bot and ignore files) for their old paths. Check any `tsconfig.json` in the Blume project dir too: Blume's build reads it, so an `extends` that resolves only after a root workspace install, or `include`s of the old framework's folders, fail `blume build`. Install the workspace first, fix the paths, or delete the file if only the old framework used it (a Nuxt `tsconfig.json` that `extends` or `references` `./.nuxt/*` fails with `BLUME_TSCONFIG_EXTENDS`, and a `postinstall: nuxt prepare` script goes with the Nuxt dependency). **If the repo uses (or the user wants) [Ultracite](https://www.ultracite.ai) for formatting:** its oxfmt formatter mangles the `:::` directives you just wrote unless you ship the bundled `assets/oxfmt@0.71.0.patch` and register it under `patchedDependencies` — see `references/monorepo.md` §6. See `references/monorepo.md` §2–3.\n7. **Wire up the host repo & deploy (non-trivial repos).** Settings a host keeps in its dashboard (Netlify's publish directory, build command, `NODE_VERSION`) can't be committed: list them in the summary. In `.gitignore`, replace only the docs' own entries and keep ones other packages use. For a monorepo on Vercel, emit the root-aware install/build recipe and `apps/docs/vercel.json`: with `outputDirectory: \"dist\"` for a static build, and with no `outputDirectory` for `deployment: vercel()`, whose build writes `.vercel/output` (add `.vercel/output/**` to Turborepo outputs). Tell the user the settings you can't commit (Vercel Root Directory, Node 22, and server secrets such as `AI_GATEWAY_API_KEY`). If the workspace pins Vite and `blume build` crashes inside Astro/Vite, apply the pnpm-patch workaround. All copy-pasteable in `references/monorepo.md` §4–5.\n8. **Verify.** Run `blume build` (frontmatter schema, duplicate routes, config — it fails on any error diagnostic by default; **never pass `--no-strict`**, which builds anyway and silently drops pages with invalid front matter or `.mdx` that doesn't parse) and `blume validate --strict` (internal links, heading anchors, assets, redirect targets — the link checker lives in `validate`, not `build`), fix diagnostics, then `blume dev` for a visual pass. End with a written summary of what was migrated, dropped, and approximated — **and every repo-specific edit you made** (pnpm-workspace, vercel.json, config globs) with the reason, plus any manual step left to the user (the Astro patch, Vercel dashboard settings).\n\n## The Blume mental model\n\nThe single biggest shift for most sources — especially Mintlify — is that **navigation is derived from the filesystem**, not declared in config.\n\n### Navigation is the file tree\n\n- **Folders become groups, files become pages.** A page's sidebar label is its frontmatter `title`; a group's label is the humanized folder name.\n- **Ordering resolves highest-priority-first:** an explicit `navigation.sidebar` (replaces the whole tree) → a folder's `meta.ts` `pages` array → a page's frontmatter `sidebar.order` → the filesystem (`index` first, then numeric filename prefix like `01-`, then alphabetical).\n- **`meta.ts` refines one folder** (`defineMeta({ title, icon, order, collapsed, pages, display, directory })`). The `pages` array lists children by slug (numeric prefix, parentheses, and extension stripped; an entry that names nothing warns `BLUME_META_UNKNOWN_PAGE` with the slug it likely meant, so write that one); children you omit fall back to their own `sidebar.order`, then filesystem order (`index` still sorts first) — so a partial `pages` list is safe, but list every child when the source declared a complete order. `directory` inherits down the tree: set `directory: \"none\"` on nested folders that shouldn't list cards. `pages` can't interleave loose pages with subgroups inside a `flat` group, or at the top of the sidebar in any mode: when a source interleaves them (mdBook, MkDocs `navigation.sections`), use `display: \"group\"`, where the order holds inside groups, and say what moved at the top level.\n- **Sidebar render mode: a global default with per-folder overrides.** `navigation.sidebar.display` in `blume.config.ts` is `\"flat\"` (default), `\"group\"` (collapsible), or `\"page\"` (drill-in sub-panel) and sets the mode for every group at once. A folder can override its **own** group: `display` in its `meta.ts`, or — sugar when the folder has an `index` page — `sidebar.display` in that index page's frontmatter. Precedence: index frontmatter → `meta.ts` → global config → `flat`; an override applies to that one group only (nested subgroups resolve their own chain). So a source's per-category collapse/drill-in modes migrate per folder — only reach for the global mode when the whole sidebar changes. Under an explicit `navigation.sidebar`, the config item's own `display` field is the only per-group control (frontmatter/meta `display` is ignored there, with a `BLUME_SIDEBAR_DISPLAY_IGNORED` warning).\n- **An explicit `navigation.sidebar` replaces filesystem generation entirely.** Use it only for a nav shape files can't express. Its items are a page route string, a group (`{ label, items }`), or a link (`{ label, href }`).\n- **Config-declared nesting has no on-disk counterpart — materialize it or it flattens silently.** When a source (Mintlify `groups`, Nextra `_meta`, a Docusaurus sidebar…) declares a nested group, its pages usually sit **flat in one folder** and the grouping lives only in config. Filesystem-derived nav sees the flat folder and drops the inner group. To keep the nesting, **use a `(group)/` folder first**: move the pages into `/()/` with a `meta.ts` for the label, order, and `collapsed`. A parenthesized folder adds the sidebar group but no URL segment, so no route changes and no redirects are needed, and a page from another folder can join with a `slug` that keeps its old route. A group whose landing page is a sibling file keeps every URL too: move the landing page to `(group)/index.md` with `slug: `, and the slugged index becomes the group's link. Moving a page a folder deeper breaks its relative links and assets (`./img.png`, `../other.md`), so re-base them. (Docsify is the exception: its old `#/` URLs are remapped by script whatever the paths, so its reference moves pages into real folders.) Only when that can't express the shape, move the pages into a real subfolder (URLs change: add `redirects`) or declare the group in an explicit `navigation.sidebar`, which nests the existing routes without moving a file. Walk config `pages`/nav arrays **recursively** during inventory and record where config nesting depth exceeds on-disk depth; that gap is exactly what gets lost.\n\n### Tabs and selectors\n\n- **`navigation.tabs`** (`{ label, path, icon? }`) render top-of-header sections and **scope the sidebar by route** — the folder at a tab's `path` becomes the section, so this needs no config beyond the tabs themselves; structure content as **one folder per tab**. **A source's top-level tabs (Mintlify `navigation.tabs`, a top-level product/section switcher) map to these header tabs — keep them as tabs; don't flatten them into a single global `navigation.sidebar`.** Blume picks the active tab by **URL prefix** (longest tab `path` that prefixes the route), so every page in a tab must live under that tab's single `path`; a source tab that mixes arbitrary routes isn't portable as-is — either move its pages under one prefix (route change → add `redirects`) or accept the closest shape, and say which in the report (details in `references/mintlify.md`). The filtering runs both ways: on a route **under** a tab's `path`, the sidebar shows **only** that tab's folder (a tab also highlights when the current route is under it); on a **root or untabbed** route (or a tab whose `path` is `/`), the tab folders are **hidden** and the sidebar shows only the loose pages that belong to no tab (full tree as a fallback, so it's never blank). Consequence for migrations: once you add tabs, the landing sidebar automatically drops the sectioned content — that's intended, not lost pages; don't hand-build excludes for it.\n- **`navigation.selectors`** (`{ kind, label, items: [{ label, path, icon?, description?, tag? }] }`, `kind` = `dropdown`/`product`/`version`/`language`) partition a whole site (products, versions) via a header dropdown keyed on the current route.\n- **`navigation.actions`** (`[{ label, href }]`) puts plain links in the **header**, left of the icon buttons, and **`navigation.cta`** (`{ label, href }`, singular) is the header's one filled call-to-action button. This is the home for a source's header bar — a \"Log in\"/\"Status\" link goes in `actions`, a \"Sign up\"/\"Get started\" button in `cta`. An `http(s)` href opens in a new tab; an internal route is validated against your pages at build time, so a route served by another app on the same host must be written as an absolute URL. Both hide on phones (below `sm`), except `cta` on a page with no navigation toggle; a link that must survive on a phone on docs pages belongs in `featured`.\n- **`navigation.featured`** (`{ label, href, icon? }`) pins links to the **top of the sidebar, above every section** — a blog, changelog, or support page that should always be one click away. These are the **exception to tab scoping**: unlike the generated tree, featured links show on **every** route and breakpoint. `href` points anywhere — an external URL opens in a new tab, an internal route (`/contact`) is validated against your pages at build time. `icon` is a Lucide name (or image path/URL/inline SVG), as everywhere else. This is the home for a source's always-visible header/utility links (Mintlify anchors, Blog/Contact links) — see `references/mintlify.md`.\n\n### Routes and pathing\n\n- A route is the content path relative to `content.root`, with **numeric prefixes stripped** (`01-intro.mdx` → `/intro`; a version or a name that starts with a date, `YYYY-MM-DD`, `D-M-YYYY`/`M-D-YYYY`, or `YYYY-MM`, stays whole: `12-05-2022.mdx` → `/12-05-2022`; pin `slug` for any other digit-led name the old site kept whole) and **`(group)/` folders adding no segment**. An `index` file maps to its folder's route. Frontmatter `slug` overrides the generated route. A `README.md` is an ordinary page at `/README`, not its folder's index: rename it `index.md` (Docsify, MkDocs, GitBook, and VuePress sources all use README as the index).\n\n### `blume.config.ts` shape\n\n`defineConfig({...})` — every field optional, all with defaults:\n\n- **Site:** `title`, `description`, `logo` (string SVG, or `{ image: string | { light, dark, alt }, text, href }`), `banner` (a string, or `{ content, link: { href, text }, dismissible, id }` — no color/type). A logo renders beside `title` in the header, so a **wordmark logo doubles the brand** (\"Acme Acme\") — set `text: \"\"` to render the mark alone. **Prefer the string form over `{ light, dark }`:** if you have the logo SVG locally and it's monochrome (solid black or white), rewrite its `fill`/`stroke` to `currentColor` and use `logo: \"/logo.svg\"` — it then inherits the theme's text color and adapts to light/dark automatically, so you don't need separate light/dark files.\n- **`theme`:** `accent` (a color string for both modes, or `{ light, dark }` per mode), `action` (color), `mode` (`light`/`dark`/`system`), `radius`, `fonts` (`{ body, display, mono }` — each a curated Google-font slug, a `{ name, provider?, weights? }` object for any Google/Fontsource/Bunny/Fontshare family, or `{ name, variants: [{ src, weight?, style? }] }` for local font files), `background` and `backgroundImage` (each a string, or `{ light, dark }` per mode). The old `accentDark`/`backgroundDark`/`backgroundImageDark` fields were **merged into these per-mode objects** — a bare string still applies to both modes, so only reach for `{ light, dark }` when the two modes differ. Each color must be a CSS color or an accent preset (a source's bare `\"3b82f6\"` needs its `#`), or `BLUME_THEME_COLOR_INVALID` warns and browsers ignore it. There is **no** `theme.strict` and **no** `theme.css` config field — custom CSS goes in a project-root **`theme.css` file** (auto-picked-up), and a source's \"strict appearance\" flags drop.\n- **`content`:** `root` (default `\"docs\"`, relative to the project dir where `blume` runs), `include`/`exclude` (arrays of globs **relative to `content.root`**; defaults `[\"**/*.{md,mdx}\"]` / `[\"**/_*\", \"**/.*\"]` — a set `exclude` **adds to** those defaults, so partials and dot-folders stay unpublished; to publish `_`-prefixed or dot-files on purpose, list the default with a `!`: `exclude: [\"!**/_*\"]`), `sources` (an array of **adapters imported from `blume/sources`**: `filesystem({ root, include, exclude })`, `obsidian({ vault })`, `githubReleases({ owner, repo })`, `notion({ database })`, `sanity({ projectId, dataset, query })`, `contentful({ space, contentType })`, `payload({ url, collection })`, `strapi({ url, contentType })`, `mdxRemote({ github })`, `custom(source)`; every factory with an options object also takes `prefix` and `pollInterval`, while `custom(source)` takes a `ContentSource` instance that sets its own `prefix`. The 1.x `{ type: \"…\" }` objects were removed — rename `type` to the factory call and pass the other fields as its options — except `{ type: \"custom\", source }`, which becomes `custom(source)` with the instance as the only argument. `root`/`include`/`exclude` are shorthand for a single `filesystem()` and are **rejected beside `sources`** — move them into the `filesystem()` entry. OpenAPI/AsyncAPI/GraphQL are **not** among these; they're adapters in the top-level `reference` list), `pages` (custom `.astro` dir), `defaultType`. When docs sit directly under the project dir (no `docs/` subfolder), set `root` there and **scope `include` to the real content folders** instead of scanning everything — `references/monorepo.md` §1.\n- **`basePath`** (top-level): a site-wide mount point (e.g. `\"/docs\"`) prepended to **every** route while staying invisible to the sidebar (no wrapper group). This is the right target for a source that served all docs under a prefix (Docusaurus `routeBasePath`, a Fumadocs `baseUrl` of `/docs`) — distinct from a per-source `prefix` (which adds a nav group) and from `deployment.base` (host subdirectory).\n- **`navigation`:** `tabs`, `selectors`, `actions` and `cta` (header links and the one filled button), `featured` (links pinned above the sidebar on every route), `sidebar` (`{ display, items }` — `display` is the global render mode above; `items` is an explicit tree), `repo` (`true`/`false`, or an absolute GitHub URL for the footer's GitHub link when the docs repo is private and `github` must stay unset). **Avoid an explicit `navigation.sidebar` unless you have to** — lean on the filesystem-derived sidebar. It only works when the file tree roughly matches the intended sidebar layout, so reshape folders to match first; reach for `sidebar.items` only for a shape files genuinely can't express (see \"Config-declared nesting\" above).\n- **`search`** — an adapter imported from `blume/search`: `orama()` (default, so omit `search` entirely for it), `flexsearch()`, `pagefind()`, `algolia({ appId, apiKey, indexName })`, `oramaCloud({ endpoint, apiKey, indexId? })`, `typesense({ host, collection, apiKey })`, `mixedbread({ storeId })`, or `false` to disable. Pass the adapter directly (`search: algolia({…})`) or as `search: { provider, popular, indexing }` when you also set curated links or indexing options. **Blume 1.x's `search.provider` string and its `search.algolia`/`oramaCloud`/`typesense`/`mixedbread` credential blocks are gone** — when a source config (or an older `blume.config.ts`) has `provider: \"algolia\", algolia: { appId, indexName, searchApiKey }`, rewrite it as `search: algolia({ appId, indexName, apiKey: searchApiKey })` (the search-only key is now `apiKey` in every adapter that takes one; admin keys stay in env vars). **`ai`** (the assistant, Open in chat — `ai.assistant.provider` takes an **adapter descriptor** imported from `blume/ai`: `gateway({ model })` (the default, `openai/gpt-5.5`), `openai({ model })` (or `openai({ baseUrl, name, model, apiKeyEnv })` for any OpenAI-compatible endpoint), `anthropic({ model })`, `gemini({ model })`, `grok({ model })`, `openrouter({ model, reasoning })`, `llmgateway({ model })`, or `inkeep({ model })`. Every adapter takes `model`, `apiKeyEnv`, `headers`, and a verbatim `providerOptions` passthrough (`headers` values are written into the generated route source as-is, so they are for non-secret static headers only — a bearer token or any other credential belongs in the env var `apiKeyEnv` names, never in `headers`). Every adapter except `inkeep()` also takes `reasoning`: Inkeep runs its own answer pipeline, so `inkeep({ reasoning })` fails validation with an unrecognized key — drop a source's reasoning setting there and report it. There are **no** flat `provider`/`model`/`apiKeyEnv`/`baseUrl`/`headers`/`reasoning` fields on `ai.assistant` — a source that configured an AI assistant that way (Blume < 2.0 included) maps onto one adapter call. `enabled`, `instructions`, `retrieval`, `suggestions`, `cors`, and `endpoint` sit on `ai.assistant` itself; there is **no** `ai.ask` — Blume 2.0.0 and earlier used that name, so an older `blume.config.ts` moves the whole block to `ai.assistant`), **`agents`** (llms.txt, the JSON API, the MCP server, published skills, discovery manifests, robots content signals), **`reference`** (a list of adapters imported from `blume/reference` — `openapi({ spec | sources, route, … })`, `asyncapi({ … })`, `graphql({ spec, endpoint, … })` — never the 1.x `openapi`/`asyncapi`/`graphql` blocks), **`redirects`**, **`seo`**, **`markdown`**, **`analytics`** (a list of adapters imported from `blume/analytics` — one factory per provider (`posthog({ key, host })`, `googleAnalytics({ id })`, `plausible({ domain, host })`, `mixpanel({ token, region })`, `segment({ key })`, …; the docs page lists them all), `vercel()`, and `script({ src | content, strategy, attributes })` for anything without one — never an object keyed by provider), **`deployment`**, **`i18n`**, **`toc`**, **`lastModified`**, **`github`** (`{ owner, repo, branch?, dir?, host?, api? }` — set `host` whenever the source's edit URL is on a GitHub Enterprise origin rather than `github.com`).\n- **`analytics`** — adapters from `blume/analytics`, including `script()` for a source's custom head scripts. A known analytics snippet in the source's head scripts (the gtag loader plus `gtag('config')` pair, GTM, Plausible, …) becomes that provider's factory, not `script()`. Adapters load **only in production builds and wait for `consent`** when it's configured, so a script a page needs to work (a support widget, a form embed) goes in a `PageFooter` layout slot component instead (`defineComponents`).\n- **`deployment`** is a host adapter from `blume/deploy` — `vercel()`, `netlify()`, `cloudflare()`, or `node()` — or a plain `{ site, base }` for a static build on any host (the default is a static build). Naming a host adapter switches the build to **server output** on that host (pass `output: \"static\"` to stay static there); `site`, `base`, and `output` are the named options, and anything else is forwarded verbatim to the underlying `@astrojs/*` adapter. There is **no** `deployment.adapter` string and **no** `deployment.output` field: a source that needs server rendering (the assistant, the MCP server, Mixedbread search, the API playground proxy) gets `import { vercel } from \"blume/deploy\"` and `deployment: vercel()`; a static source gets nothing — unless it served its docs under a subpath, which becomes `deployment: { base: \"/docs\" }` (see below for when to add `site`). Note that `cloudflare` and `vercel` are also exported from `blume/analytics` — alias one (`import { cloudflare as cloudflareDeploy } from \"blume/deploy\"`) when a config uses both.\n- **Keep the source's site URL as `deployment.site` unless the target host is one Blume auto-detects.** Blume fills `site` in from the platform's build environment only on **Vercel and Netlify** (their stable production domain), and uses the dev server's `localhost` URL during `blume dev`; on those two hosts leave it unset and let detection pick the deployed URL. Everywhere else — Cloudflare Pages (it exposes only the per-deploy `CF_PAGES_URL`), GitHub Pages, S3 or another static host, a custom CDN, Cloudflare Workers, a `node()` server — nothing detects it, and an unset `site` silently drops the sitemap, OG images, RSS feeds, the AI catalog, and absolute canonical URLs. So when the source config had a `url`/`site` field and the target isn't one of those two hosts, carry it over: `deployment: { site: \"https://…\" }` for a static build, or the `site` option of a host adapter (`node({ site })`). If you can't tell where the site will deploy, keep it and say so in the report.\n- **Favicon is a filename convention, not config.** Drop `icon.{svg,png,ico}` or `favicon.{svg,png,ico}` (and `apple-icon.png` or `apple-touch-icon.png`) in the project root or `public/` — Blume auto-detects it. There is **no** `favicon` config field. A source favicon given as `{ light, dark }` maps to a filename pair: copy the light file to a conventional name (e.g. `public/icon.png`) and the dark file to its `-dark` sibling — same directory and extension, `-dark` before the extension (`public/icon-dark.png`). If the two files have different formats, convert one so the extensions match; only an exact sibling of the resolved icon is picked up.\n\nThe schema is exported from `blume/schema`; the full field reference is in the `docs/configuration/` directory of the installed `blume` package (see \"Full documentation\" below for how to locate it).\n\n### Icons are Lucide, period\n\nBlume resolves **bare kebab-case [Lucide](https://lucide.dev) names** everywhere an icon is accepted — frontmatter `icon`, `sidebar.icon`, `meta.ts` `icon`, `navigation.tabs`/`selectors` icons, and `Card`/`Step`/`Icon`/etc. props. There is **no** FontAwesome or Tabler support and **no** `iconType` prop. Names must be **kebab-case** (`book-open`, not `BookOpen`) — a PascalCase React-component name (common in Fumadocs/lucide-react sources) does not resolve and renders nothing. When migrating a source that uses another icon set (Mintlify and Fern use FontAwesome), **map each name to its closest Lucide equivalent**; where none exists, drop the icon and report it. Verify a name exists at [lucide.dev/icons](https://lucide.dev/icons) before writing it.\n\n### Page frontmatter (strict — unknown keys are build errors)\n\n```yaml\n---\ntitle: Install # renders as the page H1 — remove any duplicate H1 in the body\ndescription: Install Blume and scaffold your first project.\ntype: doc # doc (default); blog and changelog drive feeds, other values only mean something under content.types\nsidebar:\n label: Install # overrides title in the sidebar\n order: 2\n icon: download\n badge: New\n hidden: false\nseo:\n title: …\n description: …\n image: /og/install.png\n canonical: https://…\n noindex: false\nsearch:\n exclude: false\n tags: [api]\nslug: install # override the generated route\ndraft: false\nlastModified: 2026-06-20 # pin the \"last updated\" date\n---\n```\n\nAlso valid: `date`/`authors` (blog/changelog feeds), `changelog` (changelog metadata), `deprecated`, and the top-level shorthands `hidden` (for `sidebar.hidden`) and `noindex` (for `seo.noindex`).\n\n### Authoring features (no imports needed in `.mdx`)\n\n- **The rich features are MDX-only.** Directives, `package-install`, mermaid, and math are wired into the MDX processor; in a plain `.md` file a `:::note` stays **literal text** — and the build stays green, with only a `BLUME_MD_DIRECTIVE` warning at its line. **Rename any `.md` file that uses (or should use) these to `.mdx` during migration.** MDX is stricter prose than Markdown: any `<` followed by a non-space character that doesn't open a tag (`<7`, `<50 ms`, `<= 5`, `List`) and a bare `{` or `}` fail the build, so escape them (`<` or `\\<`, and `\\{`) in any page you rename. With `lastModified: \"git\"`, every page the migration edits shows the migration commit's date, so say so in the report when the site shows dates; a page it only renames or moves keeps its date (Blume follows renames). This bites hardest on Docusaurus/Starlight sources, whose `.md` content is full of `:::` admonitions. Plain Markdown (headings, tables, fenced code with titles/highlighting) is fine in `.md`.\n- **Callouts as directives:** `:::note`, `:::tip`, `:::warning`, `:::danger`, `:::info`, `:::success`, with an optional title in brackets, which renders its inline Markdown: `:::warning[Heads up]`. Aliases `caution`→warning, `error`→danger, `important`→note, `warn`→warning. A callout that needs its own icon or tint is `` (a Lucide `icon`, any CSS `color`), which a directive can't set. **markdown-it sources (VitePress, VuePress, Docusaurus v2) write `::: tip Title`: with a space after the colons it's never a directive, even in `.mdx`, and renders as literal text (`.mdx` warns `BLUME_DIRECTIVE_SPACED_NAME` only for a callout name); inside an open `:::` container it closes that container and its text is dropped (`BLUME_DIRECTIVE_CLOSING_TEXT`); a title after the name (`:::tip Title`) is dropped too (`BLUME_DIRECTIVE_OPENING_TEXT`).** Normalize to `:::tip[Title]`. MDC's two-colon blocks (Docus, any Nuxt Content site: `::note` … `::`) are leaf directives to Blume and print as text (`BLUME_MDC_SYNTAX`), and MDC `[text]{.class}` spans fail the MDX build (`BLUME_MDX_ATTRIBUTE_LIST` names the line). GitHub alerts (`> [!NOTE]`, any of GitHub's five, `[!CAUTION]` as danger) render as callouts in `.mdx`, text after the marker as the title; in `.md` they stay quotes that show the marker (`BLUME_MD_GITHUB_ALERT`), so rename those pages to `.mdx`.\n- **No-import MDX components:** `Callout`, `Card`/`CardGroup`, `Columns`/`Column`, `Steps`/`Step`, `Tabs`/`Tab`, `Accordion`/`AccordionItem`, `Expandable`, `FileTree`, `Tree`/`Tree.Folder`/`Tree.File`, `CodeGroup`, `Frame`, `Panel`, `Tooltip`, `Tile`, `Badge`, `Icon`, `TypeTable`/`AutoTypeTable`, `Color`, `YouTube`, `Visibility`, `GithubInfo`, `Component`, `CodeBlock`, `Diff`, `Prompt`, `Math`, `Changelog`, and the hand-written endpoint fields `ParamField`/`ResponseField`/`RequestExample`/`ResponseExample` (Mintlify's semantics: `` names the field by its location; see `docs/references/api-pages.mdx`). (**Not** shipped — convert away: ``/``/``/``/``/`` → the matching `:::` directive, and `RequestField`. A `` with no `code` prop, used as a wrapper around a fence as Fern and Mintlify do, renders the fence as written but ignores its own `title`: unwrap the fence and put the title in its meta. A component that shows its children, used with none and another tool's props (``), renders empty and warns `BLUME_UNKNOWN_PROP`: put the content between the tags. See the reference files for targets.)\n- **Fenced-code superpowers:** ` ```package-install ` → package-manager tabs; ` ```mermaid ` → a rendered diagram; code-block titles (` ```ts server.ts `), line numbers (`lineNumbers`), and highlighting (`{1,4-5}`, `// [!code ++]`).\n- **Fences and titles that trip migrations:** a fence language Shiki doesn't know renders as plain text and warns `BLUME_UNKNOWN_CODE_LANGUAGE` (case doesn't matter: `JSON` highlights like `json`): fix the id, or write `text` for plain text. A language glued to attributes with a comma (` ```rust,ignore `) is one of those; with a space instead, rustdoc's and mdBook's keywords (`ignore`, `no_run`, `should_panic`, `edition2021`, `editable`, …) warn `BLUME_CODE_FENCE_OPTION` and stay out of the title, but any other second word becomes the block's title: keep only the language. Other tools' fence options (`hl_lines=\"2 3\"`, `linenums=\"1\"`, `showLineNumbers`, Mintlify's `lines`, `wordWrap`, `filename=\"…\"`) do nothing, stay out of the title, and warn `BLUME_CODE_FENCE_OPTION` with the Blume spelling (`{2,3}`, `lineNumbers`, `wrap`, `title=\"…\"`). A fence with options but no language needs one (` ```text title=\"x\" lineNumbers `), or the first option is read as the language. A title is every word after the language, and a bracketed one (` ```ts [file.ts] `, from VitePress and MDC) drops its brackets, with a range glued after them (`[file.ts]{2}`) highlighting its lines. `Expandable`, `AccordionItem`, and callout titles render inline Markdown (code, emphasis, links); a `Step` title is a plain string that shows Markdown as written and has no anchor, so keep an anchored heading as the first line inside ``. Raw HTML `` and `` are never optimized: a relative one naming a file beside the page publishes that file with the page (as `[spec](./spec.pdf)` and `` do), a root path gains `deployment.base` like a Markdown link, and `blume validate` checks both, but a relative `` to a page resolves against the page's URL, not its folder. Convert images to Markdown so they're optimized, and page links to Markdown links or root routes.\n- **Math:** `$$…$$` renders in `.mdx` with **no conf\n\n",".agents/skills/blume-migrate/references/docsify.md":"# Docsify → Blume\n\nDocsify 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:\n\n- **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).\n- **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`.\n- **Pages have no frontmatter.** The title is usually the first `# H1`, but not always.\n- **Navigation is a Markdown list** (`_sidebar.md`), and its groups usually sit flat in one folder.\n- **Heading ids differ from Blume's**, and old deep links carry them as `?id=`.\n\n**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.\n\n## Detect\n\n- 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.\n- `_sidebar.md`, `_navbar.md`, `_coverpage.md`, and `.nojekyll` beside it, with `README.md` as the home page.\n- `docsify-cli` or `docsify` in `package.json`. Without either, the source has to be named: `npx blume migrate docsify`.\n- A GitHub wiki has `_Sidebar.md` and `Home.md` but no `index.html`. It isn't Docsify.\n\n**Where the Blume project goes.** Put `blume.config.ts` beside the `package.json` that runs `docsify serve ` (usually the repo root), so the default `content.root: \"docs\"` matches. With no manifest, scaffold one there.\n\nRead the whole `index.html`: the `$docsify` object (it can be a function), every `