blume 1.7.3 → 2.0.0

package/skills/blume-migrate/assets/oxfmt@0.67.0.patch

@@ -0,0 +1,49 @@
+diff --git a/dist/markdown-BMigo7Hm.js b/dist/markdown-BMigo7Hm.js
+index bc9037f6c0de5516b139d8cdb195b1e25cd33bc0..a02c284e28bb535f9964a8a086ebb6549657e416 100644
+--- a/dist/markdown-BMigo7Hm.js
++++ b/dist/markdown-BMigo7Hm.js
+@@ -4872,7 +4872,43 @@ function lu(e, t, r) {
+ 		case "sentence": return Oh(e, r);
+ 		case "word": return t.parser !== "mdx" ? zh(e, t) : Uh(e);
+ 		case "whitespace": {
+-			let { next: a } = e, u = a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
++			let { next: a, previous: oxfmtFencePrev } = e;
++			// Preserve line breaks that sit directly against a `:::` container
++			// directive fence, so `proseWrap: "never"` keeps the opening/closing
++			// fence on their own lines instead of joining them into the prose (which
++			// breaks the directive). Ordinary prose still wraps per proseWrap.
++			// See prettier/prettier#19040.
++			let oxfmtIsFence = (w) => w != null && typeof w.value === "string" && w.value.startsWith(":::");
++			// A titled directive (`:::warning[Heads up]`) parses its `[title]` as a
++			// linkReference between two sentence nodes at the paragraph level: the
++			// fence word ends the sentence before the reference, and the body's
++			// leading newline opens the sentence after it. So when this whitespace
++			// starts its sentence, climb to the paragraph and check whether the two
++			// preceding siblings are a (link) reference and a sentence ending in a
++			// `:::` fence word.
++			let oxfmtPrevIsTitledFence = !1;
++			if (oxfmtFencePrev == null && e.index === 0 && e.grandparent != null && Array.isArray(e.grandparent.children)) {
++				let oxfmtSibs = e.grandparent.children, oxfmtSentIdx = oxfmtSibs.indexOf(e.parent);
++				if (oxfmtSentIdx >= 2) {
++					let oxfmtLink = oxfmtSibs[oxfmtSentIdx - 1], oxfmtBefore = oxfmtSibs[oxfmtSentIdx - 2];
++					let oxfmtLastWord = oxfmtBefore && oxfmtBefore.type === "sentence" && Array.isArray(oxfmtBefore.children) ? oxfmtBefore.children[oxfmtBefore.children.length - 1] : null;
++					oxfmtPrevIsTitledFence = oxfmtLink != null && (oxfmtLink.type === "linkReference" || oxfmtLink.type === "link") && oxfmtIsFence(oxfmtLastWord);
++				}
++			}
++			// The plain-markdown parser keeps a titled fence's `[title]` as literal
++			// words, so the whole directive is one sentence. For a newline
++			// whitespace, walk back to the start of its visual line within the
++			// sentence; a line led by a `:::` word is a fence whose break must stay.
++			if (!oxfmtPrevIsTitledFence && e.node.value.includes("\n") && e.parent != null && Array.isArray(e.parent.children)) {
++				let oxfmtLineFirst = null;
++				for (let oxfmtJ = e.index - 1; oxfmtJ >= 0; oxfmtJ--) {
++					let oxfmtSib = e.parent.children[oxfmtJ];
++					if (oxfmtSib.type === "whitespace" && typeof oxfmtSib.value === "string" && oxfmtSib.value.includes("\n")) break;
++					oxfmtLineFirst = oxfmtSib;
++				}
++				oxfmtPrevIsTitledFence = oxfmtIsFence(oxfmtLineFirst);
++			}
++			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(a) ? "preserve" : a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !NE(e) && !(t.proseWrap === "preserve" && RE(e)) ? "never" : t.proseWrap;
+ 			return ou(e, n.value, u, !1, t);
+ 		}
+ 		case "emphasis": {

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

@@ -21,18 +21,19 @@ Read `themeConfig`, `presets`, and `plugins`:
 | `themeConfig.navbar.items` (external/utility links — Blog, Discord…) | **`navigation.actions`** (`[{ label, href }]`, plain header links) to keep them in the header, or **`navigation.featured`** (`{ label, href, icon? }`, pinned above the sidebar on every route) if they should survive on phones; the GitHub link → the `github` config instead |
 | `themeConfig.navbar.items` (a `className`-styled button — "Get started", "Sign up") | **`navigation.cta`** (`{ label, href }`, the header's one filled button; a route the docs don't serve must be an absolute URL) |
 | `themeConfig.colorMode.defaultMode` | `theme.mode` (`respectPrefersColorScheme: true` → `"system"`) |
-| `themeConfig.prism.theme` / `.darkTheme` | `markdown.codeBlocks.theme: { light, dark }` (map Prism theme names to Shiki themes, e.g. `github`/`github-dark`) |
+| `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` → drop** (`deployment.site` auto-detects); `baseUrl` (when not `/`) → `deployment.base` |
+| `url` + `baseUrl` | **`url` → drop** (the deployment's `site` is auto-detected); `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` | drop → 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 |
+| `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) |
 | `@docusaurus/plugin-client-redirects` | **static `redirects: [{from, to}]` arrays convert 1:1** to Blume `redirects` (a `from` array = one entry per item); only `createRedirects` functions are truly dynamic → host rules |
 | `@docusaurus/theme-mermaid` | delete the dep — ` ```mermaid ` renders natively (in `.mdx`) |
-| GraphQL doc generators (`@graphql-markdown/docusaurus`, `@edno/docusaurus2-graphql-doc-generator`) | delete the plugin **and its generated pages** — point the top-level `graphql: { enabled: true, spec, endpoint }` at the schema instead (see SKILL.md "GraphQL") |
+| OpenAPI doc plugins (`docusaurus-plugin-openapi-docs`, `redocusaurus`) | delete the plugin **and its generated pages** — add `openapi({ spec })` (from `blume/reference`) to the top-level `reference` list; `redocusaurus` `specs[].route` → the adapter's `route`, one `openapi()` entry (or source) per spec (see SKILL.md "OpenAPI") |
+| GraphQL doc generators (`@graphql-markdown/docusaurus`, `@edno/docusaurus2-graphql-doc-generator`) | delete the plugin **and its generated pages** — add `graphql({ spec, endpoint })` (from `blume/reference`) to the top-level `reference` list instead (see SKILL.md "GraphQL") |
 | `remark-math` + `rehype-katex` | delete — block `$$…$$` renders in `.mdx` with no config (no `markdown.math` field exists); **inline `$…$` is not supported** — convert or drop (report) |
 | Multi-instance docs plugins (`plugin-content-docs` with `id`) | one folder (and usually one `navigation.tabs` entry) per instance |
 

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

@@ -68,8 +68,8 @@ Fumadocs icons are strings resolved by the repo's own `icon` handler in `loader(
 - **File trees:** `<Files>` → **`<Tree>`** (the JSX container for `Tree.*` children — _not_ `<FileTree>`, which wraps a Markdown list); `<Folder>` → `<Tree.Folder>` (`defaultOpen` carries over); `<File>` → `<Tree.File>`. Or convert the whole block to a list-driven `<FileTree>`.
 - **Tabs:** Fumadocs declares labels on the parent (`<Tabs items={['npm','pnpm']}>`) and selects with `<Tab value="npm">`. Blume's `<Tab>` carries its own `title`. Strip `items={[…]}` from `<Tabs>` and give each child `<Tab>` a `title` (from its `value`, or the positional `items` entry).
 - **Pass through unchanged:** `<Steps>`/`<Step>`, `<TypeTable>` (Blume's was modeled on Fumadocs' — identical `type` record shape), `<GithubInfo>`.
-- **`<Banner>`** (layout-mounted, not per-page) → the `banner` config field (`{ content, link, dismissible, id }`).
-- **`<include>./partial.mdx</include>`** — Blume has no runtime include. **Inline** the partial's body (strip its frontmatter) at migration time; resolve nested includes recursively.
+- **`<Banner>`** (layout-mounted, not per-page) → the `banner` config field (`{ content, link: { href, text }, dismissible, id }`).
+- **`<include>./partial.mdx</include>`** — Blume uses the same include syntax. **Pass through unchanged**: paths resolve relative to the including file, a leading `/` resolves from the content root, and nested includes work. Keep partials in `_`-prefixed files or folders so they stay out of routing and the sidebar.
 - **No equivalent — report:** `<DynamicCodeBlock>`, `<ImageZoom>` (Blume zooms content images by default), `<InlineTOC>`.
 - **Strip or convert every import** — not just `fumadocs-*`: `lucide-react` imports (icon JSX → string names), `next/image`/`next/link` (→ Markdown image/link), and local components. **Inventory `mdx-components.tsx` before deleting it** — components registered there are used import-free in MDX bodies; port or inline each usage first.
 
@@ -84,11 +84,11 @@ Trailing heading markers — `[#custom-id]` (pinned anchor), `[!toc]` (hide from
 
 ## OpenAPI
 
-`fumadocs-openapi` writes **generated MDX stubs into the content tree** (`generateFiles()` output: pages containing `<APIPage>`/`<OpenAPIPage>` with `_openapi` frontmatter), plus `lib/openapi.ts` (`createOpenAPI`) and a generate script. Treat these exactly like Mintlify endpoint stubs: **delete the generated pages**, point `openapi: { enabled: true, sources: [{ spec }] }` at the spec (vendor it locally), add a `navigation.tabs` entry for the reference route, and remove `fumadocs-openapi`, `lib/openapi.ts`, and the generate script. Keep hand-written conceptual pages (intro/auth) under the reference route.
+`fumadocs-openapi` writes **generated MDX stubs into the content tree** (`generateFiles()` output: pages containing `<APIPage>`/`<OpenAPIPage>` with `_openapi` frontmatter), plus `lib/openapi.ts` (`createOpenAPI`) and a generate script. Treat these exactly like Mintlify endpoint stubs: **delete the generated pages**, add `openapi({ spec })` (from `blume/reference`) to the top-level `reference` list (vendor the spec locally), add a `navigation.tabs` entry for the reference route, and remove `fumadocs-openapi`, `lib/openapi.ts`, and the generate script. Keep hand-written conceptual pages (intro/auth) under the reference route.
 
 ## GraphQL
 
-`@fumadocs/graphql` works differently from the OpenAPI flow: **no stub files** — pages are virtual, served through the Loader API. The artifacts to harvest and tear down: `lib/graphql.ts` (`createGraphQL()` — read its `input` for the schema and any per-source routes/labels), the `graphql.staticSource()`/`graphql.loaderPlugin()` wiring in the source config, the `GraphQLPage` component (`createGraphQLPage()`, usually `components/api-page.tsx` — read its playground `endpoint`), and the `@fumadocs/graphql/css/preset.css` import. Map to the top-level `graphql: { enabled: true, spec, endpoint }` block (see SKILL.md "GraphQL"): SDL files/text and introspection results carry over as `spec` (vendor a URL input locally); a programmatic `GraphQLSchema` instance must be printed to SDL and committed (report); the `createGraphQLPage` playground endpoint becomes `endpoint`. When `createGraphQL()` takes several inputs, or sources carry their own routes, labels, or endpoints, map each one to an entry in `graphql.sources` (`{ spec, route, label, endpoint }`) instead of the single block-level `spec` — otherwise a schema is dropped or mounted on the wrong route. Blume groups routes the same way (`<route>/queries/<field>`, `<route>/objects/<type>`), but slugs are re-derived — rewrite inbound links and let `blume validate` catch strays. Then remove `@fumadocs/graphql`, the two lib/component files, and the CSS import. Since there are no generated pages, there is nothing to delete from the content tree — but keep any hand-written conceptual pages under the reference route.
+`@fumadocs/graphql` works differently from the OpenAPI flow: **no stub files** — pages are virtual, served through the Loader API. The artifacts to harvest and tear down: `lib/graphql.ts` (`createGraphQL()` — read its `input` for the schema and any per-source routes/labels), the `graphql.staticSource()`/`graphql.loaderPlugin()` wiring in the source config, the `GraphQLPage` component (`createGraphQLPage()`, usually `components/api-page.tsx` — read its playground `endpoint`), and the `@fumadocs/graphql/css/preset.css` import. Map to a `graphql({ spec, endpoint })` entry in the top-level `reference` list (see SKILL.md "GraphQL"): SDL files/text and introspection results carry over as `spec` (vendor a URL input locally); a programmatic `GraphQLSchema` instance must be printed to SDL and committed (report); the `createGraphQLPage` playground endpoint becomes `endpoint`. When `createGraphQL()` takes several inputs, or sources carry their own routes, labels, or endpoints, map each one to an entry in the adapter's `sources` (`{ spec, route, label, endpoint }`) instead of the single `spec` shorthand — otherwise a schema is dropped or mounted on the wrong route. Blume groups routes the same way (`<route>/queries/<field>`, `<route>/objects/<type>`), but slugs are re-derived — rewrite inbound links and let `blume validate` catch strays. Then remove `@fumadocs/graphql`, the two lib/component files, and the CSS import. Since there are no generated pages, there is nothing to delete from the content tree — but keep any hand-written conceptual pages under the reference route.
 
 ## i18n
 

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

@@ -28,16 +28,31 @@ Resolve `$ref` includes first (Mintlify splits config across files). Map only wh
 | `background.image` | `theme.backgroundImage` (`{ light, dark }`) | same per-mode shape as `background` |
 | `background.decoration` | **drop** | no Blume equivalent |
 | `fonts.family` / `fonts.{heading,body}.family` | `theme.fonts.{display,body}` | a curated slug (kebab-case, e.g. `space-grotesk`) maps directly; any other Google family maps to the object form `{ name: "Family Name" }`; a self-hosted font (`fonts.*.src` URLs) maps to `{ name, variants: [{ src, weight }] }` after downloading the files into the project |
-| `banner` | `banner` (`{ content, dismissible, id, link }`) | **only** those keys — drop `banner.color`/`banner.type` |
+| `banner` | `banner` (`{ content, dismissible, id, link: { href, text } }`) | **only** those keys — drop `banner.color`/`banner.type` |
 | `styling.latex: true` | **drop the field** — block math `$$…$$` renders in `.mdx` with no config | there is **no** `markdown.math` field; inline `$…$` is **not** supported — convert inline math to `$$…$$` or drop it (report) |
-| `styling.codeblocks.theme` | `markdown.codeBlocks.theme` (`{ light, dark }`) |  |
+| `styling.codeblocks.theme` | `markdown.code.theme` (`{ light, dark }`) |  |
 | `search.prompt` | **drop** | no equivalent |
 | `seo.metatags` | **drop** | no equivalent; use per-page `seo` frontmatter |
 | `seo.indexing: "all"` | `search.indexing.includeHiddenPages: true` |  |
 | `variables` (`{{name}}`) | **inline into content** | Blume has no runtime `{{var}}` substitution — replace each `{{name}}` with its value in the pages |
-| `integrations.posthog` (`{ apiKey, apiHost }`) | `analytics.posthog` (`{ key, host }`) | preserve the host verbatim (e.g. `us.posthog.com` — Blume's default is `us.i.posthog.com`) |
-| `integrations` (GA, Plausible, Fathom, …) | `analytics.scripts` / `analytics.vercel` | one `scripts[]` entry per provider (`{ src, strategy, attributes }`); no first-class mapping beyond PostHog/Vercel |
-| `contextual` (`["copy","chatgpt","claude",…]`) | **mostly free** | Copy-as-Markdown and Open-in-chat are default page actions; `mcp` needs `ai.mcp.enabled` + server output (report as a follow-up) |
+| `integrations.posthog` (`{ apiKey, apiHost, sessionRecording }`) | `posthog({ key, host })` in the `analytics` list | preserve the host verbatim (e.g. `us.posthog.com` — Blume's default is `us.i.posthog.com`); `sessionRecording: false` → `disable_session_recording: true`; every adapter is imported from `blume/analytics` |
+| `integrations.ga4` (`{ measurementId }`) | `googleAnalytics({ id })` |  |
+| `integrations.gtm` (`{ tagId }`) | `googleTagManager({ id })` |  |
+| `integrations.plausible` (`{ domain, server }`) | `plausible({ domain, host })` | `server` is a bare hostname; `host` is an origin — prepend `https://` |
+| `integrations.fathom` (`{ siteId }`) | `fathom({ site })` |  |
+| `integrations.pirsch` (`{ id }`) | `pirsch({ code })` |  |
+| `integrations.mixpanel` (`{ projectToken, region }`) | `mixpanel({ token, region })` |  |
+| `integrations.amplitude` (`{ apiKey }`) | `amplitude({ key })` |  |
+| `integrations.segment` (`{ key, cdnUrl }`) | `segment({ key, cdn })` |  |
+| `integrations.hightouch` (`{ writeKey, apiHost }`) | `hightouch({ key, host })` |  |
+| `integrations.heap` (`{ appId }`) | `heap({ id })` |  |
+| `integrations.hotjar` (`{ hjid, hjsv }`) | `hotjar({ id, version })` | both numbers |
+| `integrations.clarity` (`{ projectId }`) | `clarity({ id })` |  |
+| `integrations.logrocket` (`{ apiKey }`) | `logrocket({ id })` |  |
+| `integrations.clearbit` (`{ publicApiKey }`) | `clearbit({ key })` |  |
+| `integrations.adobe` (`{ launchUrl }`) | `adobe({ url })` |  |
+| any other `integrations` script | `script({ src, strategy, attributes })` / `vercel()` in the `analytics` list | one `script()` adapter per provider without a factory |
+| `contextual` (`["copy","chatgpt","claude",…]`) | **mostly free** | Copy-as-Markdown and Open-in-chat are default page actions; `mcp` needs `agents.mcp.enabled` + server output (report as a follow-up) |
 | `redirects` | `redirects: [{ from, to }]` | static only — see below |
 | `navigation.languages` | `i18n` | see i18n below |
 
@@ -112,7 +127,7 @@ Rewrite each page's MDX:
 - **`<Tabs>` → `<Tabs inline>`.** Mintlify renders tabs **borderless** — a strip on a full-width rule with the content flowing beneath as prose — while Blume's `<Tabs>` defaults to a bordered box. Add `inline` to each `<Tabs>` to preserve Mintlify's appearance; every child `<Tab title="…">` is unchanged. Don't add `param` — Mintlify tabs switch in place and don't deep-link to the URL, so plain `inline` is the faithful mapping.
 - **These pass through — Blume ships them natively:** `<Columns>`/`<Column>`, `<Expandable>`, `<Tooltip>`, `<Frame>`, `<Panel>`, `<Card>`/`<CardGroup>`, `<Tab>`, `<Steps>`/`<Step>`. Keep them as-is.
 - **API fields → `TypeTable`.** Blume does **not** ship `<ParamField>`/`<ResponseField>`/`<RequestField>`. Convert a cluster of fields into one `<TypeTable>` (rows keyed by field name, each `{ type, required?, default?, description }`). For a fully spec'd API, prefer deleting the hand-written fields and using the [OpenAPI reference](#openapi) instead.
-- **`<Update>`** (a Mintlify changelog entry) has no component form → convert to a `type: changelog` page, or use the `github-releases` source.
+- **`<Update>`** (a Mintlify changelog entry) has no component form → convert to a `type: changelog` page, or use the `githubReleases()` source.
 - **Snippets are inlined, not imported.** Blume has no `/snippets` import mechanism. For each `import X from "/snippets/x.mdx"` + `<X prop="v" />`, inline the snippet's body (substituting `{prop}` placeholders), then delete the import and the `/snippets` file. Named string imports (`import { foo } from "/snippets/vars.mdx"`) → inline the value at each `{foo}`.
 
 ## Frontmatter
@@ -135,11 +150,11 @@ The codemod leaves the source key in place and reports a conflict rather than cl
 
 ## OpenAPI
 
-Top-level `openapi`, `api.openapi`, or a per-group/per-tab `openapi` → `openapi: { enabled: true, sources: [{ spec, label?, route? }] }`. A Mintlify `{ source, directory }` object: `directory` → the source's `route`. **Delete every per-endpoint stub page** (frontmatter `openapi: "GET /path"` or a `"GET /path"` nav entry) — Blume's native renderer generates one real page per operation. **Add a `navigation.tabs` entry pointing at the reference `route` yourself** (Mintlify's API tab maps to it); the reference does not create a header tab automatically.
+Top-level `openapi`, `api.openapi`, or a per-group/per-tab `openapi` → `reference: [openapi({ sources: [{ spec, label?, route? }] })]`, with `openapi` imported from `blume/reference` (`spec` alone is the single-source shorthand; several per-tab specs become several sources, or several `openapi()` entries when they need different routes; a spec the source embedded with Scalar becomes a `scalar({ spec })` entry). A Mintlify `{ source, directory }` object: `directory` → the source's `route`. An `asyncapi` field maps the same way to `asyncapi({ … })` in the list. **Delete every per-endpoint stub page** (frontmatter `openapi: "GET /path"` or a `"GET /path"` nav entry) — Blume's native renderer generates one real page per operation. **Add a `navigation.tabs` entry pointing at the reference `route` yourself** (Mintlify's API tab maps to it); the reference does not create a header tab automatically.
 
 - **Vendor the spec.** Mintlify usually points at a spec **URL**. Copying that straight into `spec:` makes every build fetch it at build time — a single point of failure in CI/offline/behind a proxy, and a failed fetch silently drops the reference (leaving the tab pointing at a route that 404s). Prefer downloading it into the repo (`curl … -o openapi/<name>.json`) and pointing `spec` at that local path. If you keep the URL, report the dependency and consider a `prebuild` refresh-with-fallback.
 - **Fix endpoint links.** Blume operation routes are `<route>/<slugified-tag>/<slugified-operationId>` (tag `Models` + id `listModels` → `/api-reference/models/listmodels`) — this differs from Mintlify's endpoint URLs, so **rewrite every inbound link to an operation**. `blume validate` resolves operation pages like any other route and flags the ones you miss.
-- **Keep the "Introduction" page.** Mintlify commonly has a written intro/auth page in an "Introduction" group beside the "Endpoints" (openapi) group in the same tab. Keep it: a normal content page placed under the openapi `route` (e.g. `<root>/api-reference/introduction.mdx`) merges into the reference tab's sidebar alongside the generated operations. Delete only the per-endpoint stubs, not the conceptual pages.
+- **Keep the "Introduction" page.** Mintlify commonly has a written intro/auth page in an "Introduction" group beside the "Endpoints" (openapi) group in the same tab. Keep it: a normal content page placed under the `openapi()` adapter's `route` (e.g. `<root>/api-reference/introduction.mdx`) merges into the reference tab's sidebar alongside the generated operations. Delete only the per-endpoint stubs, not the conceptual pages.
 
 ## Assets
 

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

@@ -188,15 +188,15 @@ This is a **manual step — do not fabricate the patch contents.** Leave the use
 
 ## 6. Ultracite / oxfmt formatting → oxfmt patch (ship the bundled patch)
 
-If the repo uses (or the user wants to adopt) **[Ultracite](https://www.ultracite.ai)** for formatting — an `ultracite check` / `ultracite fix` script, an `ultracite` dev dep, or oxlint/oxfmt in the toolchain — it will format the migrated `.md`/`.mdx` **and break Blume's `:::` directives.** Ultracite's formatter is **oxfmt**, and under `proseWrap` oxfmt joins the opening/closing `:::` fence line into the surrounding prose, which invalidates the directive (`:::note` … `:::` callouts, tabs, steps — the exact syntax you convert callouts _into_ in step 5). Blume's own repo hits this and pins a patched oxfmt; a migrated repo needs the same patch or every directive silently degrades to literal text on the next `ultracite fix`.
+If the repo uses (or the user wants to adopt) **[Ultracite](https://www.ultracite.ai)** for formatting — an `ultracite check` / `ultracite fix` script, an `ultracite` dev dep, or oxlint/oxfmt in the toolchain — it will format the migrated `.md`/`.mdx` **and break Blume's `:::` directives.** Ultracite's formatter is **oxfmt**, and under `proseWrap` oxfmt joins the opening/closing `:::` fence line into the surrounding prose, which invalidates the directive (`:::note` … `:::` callouts, titled fences like `:::warning[Heads up]`, tabs, steps — the exact syntax you convert callouts _into_ in step 5). Blume's own repo hits this and pins a patched oxfmt; a migrated repo needs the same patch or every directive silently degrades to literal text on the next `ultracite fix`.
 
-The fix is a committed **pnpm patch** (`patches/oxfmt@0.55.0.patch`), shipped with this skill at `assets/oxfmt@0.55.0.patch`. Unlike the Astro/Vite patch, this one is a **known, deterministic diff** — copy it in, don't regenerate it:
+The fix is a committed **pnpm patch** (`patches/oxfmt@0.67.0.patch`), shipped with this skill at `assets/oxfmt@0.67.0.patch` — the same diff Blume's own repo applies, covering titled fences as well as bare ones. Unlike the Astro/Vite patch, this one is a **known, deterministic diff** — copy it in, don't regenerate it:
 
 ```bash
 # 1. Copy the shipped patch into the target repo's patches/ dir (keep the exact filename;
 #    <skill> = this skill's directory, the one containing SKILL.md):
 mkdir -p patches
-cp "<skill>/assets/oxfmt@0.55.0.patch" patches/oxfmt@0.55.0.patch
+cp "<skill>/assets/oxfmt@0.67.0.patch" patches/oxfmt@0.67.0.patch
 ```
 
 Then register it under `patchedDependencies` — `pnpm-workspace.yaml` on pnpm 10+, or root `package.json` (`pnpm.patchedDependencies`) on pnpm 9:
@@ -204,12 +204,12 @@ Then register it under `patchedDependencies` — `pnpm-workspace.yaml` on pnpm 1
 ```yaml
 # pnpm-workspace.yaml
 patchedDependencies:
-  oxfmt@0.55.0: patches/oxfmt@0.55.0.patch
+  oxfmt@0.67.0: patches/oxfmt@0.67.0.patch
 ```
 
 Commit **both** the patch file and the `patchedDependencies` entry, then re-run `pnpm install`.
 
-- **The patch is pinned to `oxfmt@0.55.0`** (the version Ultracite 7.8.x resolves). pnpm requires an exact version match — if `pnpm why oxfmt` reports a different version, the patch won't apply. Bump the key to the resolved version (the hunk is a one-line prose-wrap guard and usually still applies cleanly); if it doesn't, tell the user and fall back to keeping directive-heavy files out of the formatter's globs.
+- **The patch is pinned to `oxfmt@0.67.0`** (the version Blume's own repo pins). pnpm requires an exact version match, and the diff targets a file whose name is hashed per oxfmt release (`dist/markdown-*.js`), so it won't apply to any other version. If `pnpm why oxfmt` reports a different one, pin `oxfmt` to `0.67.0` as a direct dev dependency (Ultracite accepts any `oxfmt` ≥ 0.40 as a peer). If the repo can't take that pin, tell the user and fall back to keeping directive-heavy files out of the formatter's globs.
 - **Not on pnpm?** The patch mechanism is pnpm-specific. For npm/yarn, either pin oxfmt and apply the diff with `patch-package`, or exclude `.md`/`.mdx` from Ultracite formatting so it never touches the directives — report whichever you chose.
 
 ---
@@ -221,5 +221,5 @@ Commit **both** the patch file and the `patchedDependencies` entry, then re-run
 - [ ] Ran plain `pnpm install`; committed `pnpm-lock.yaml` with the `package.json` change; verified `pnpm install --frozen-lockfile` is clean.
 - [ ] Wrote `apps/docs/vercel.json` + package scripts; told the user to set Root Directory + Node 22 in the Vercel project.
 - [ ] Checked for a workspace Vite override; if the build crashes inside Astro/Vite, gave the pnpm-patch recipe.
-- [ ] Uses Ultracite/oxfmt? Shipped `patches/oxfmt@0.55.0.patch` + registered it under `patchedDependencies` so formatting doesn't mangle `:::` directives.
+- [ ] Uses Ultracite/oxfmt? Shipped `patches/oxfmt@0.67.0.patch` + registered it under `patchedDependencies` so formatting doesn't mangle `:::` directives.
 - [ ] Reported every repo-specific edit and every manual step left to the user.

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

@@ -26,10 +26,10 @@ Keep content where it is — set `content.root: "src/content/docs"`.
 | `sidebar` (array) | filesystem nav / `navigation.sidebar` (see below) |
 | `tableOfContents` (`false` or `{ minHeadingLevel, maxHeadingLevel }`) | `toc` — identical shape, 1:1 |
 | `markdown.headingLinks: false` | `markdown.headingAnchors: false` |
-| `expressiveCode.themes` | `markdown.codeBlocks.theme: { light, dark }` — EC assigns by theme _type_, so match each theme by its darkness, not by array position |
+| `expressiveCode.themes` | `markdown.code.theme: { light, dark }` — EC assigns by theme _type_, so match each theme by its darkness, not by array position |
 | `expressiveCode.styleOverrides` | drop → restyle via a root `theme.css` file |
-| `head` | **drop and report** (there is no `seo.metatags`); analytics `<script>` entries → the `analytics` config |
-| `lastUpdated: true` | `lastModified: true` |
+| `head` | **drop and report** (there is no `seo.metatags`); analytics `<script>` entries → one `script()` adapter each in the `analytics` list (from `blume/analytics`): `attrs.src` → `src`, an `async`/`defer` attr → `strategy`, every other `attrs` key → `attributes`, and an inline body (`content`) → `content` |
+| `lastUpdated: true` | `lastModified: "git"` |
 | `customCss` | drop → move into a root **`theme.css`** file (auto-picked-up; not a config field) |
 | `components` (overrides) | Blume's layout slots via `defineComponents({ layout: { Header, Search, Sidebar, TableOfContents, Footer, … } })` — a near-1:1 map; reach for `blume eject` only beyond those |
 | `plugins` | **map, don't blanket-drop** — see Plugins below |
@@ -87,7 +87,7 @@ Starlight content is full of Expressive Code fence meta; Blume understands some
 
 ## Plugins — map, don't drop
 
-- `starlight-openapi` → Blume's native `openapi.sources` (delete any generated pages; add the `navigation.tabs` entry).
+- `starlight-openapi` → an `openapi({ sources })` entry in Blume's `reference` list, imported from `blume/reference` (delete any generated pages; add the `navigation.tabs` entry).
 - `starlight-blog` → `type: blog` pages.
 - `starlight-versions` → `navigation.selectors` with `kind: "version"`.
 - `starlight-image-zoom` → delete (Blume zooms content images by default).

package/src/ai/agent-readability.ts

@@ -3,6 +3,7 @@ import { repoUrl } from "../core/github.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
 import { absoluteUrl } from "../core/site-url.ts";
+import { deployPlatform } from "../deploy/platforms/index.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
 import { AI_CATALOG_PATH, hasAiCatalog } from "./ai-catalog.ts";
 import { hasApiCatalog } from "./api-catalog.ts";
@@ -90,22 +91,20 @@ export interface AgentReadabilityManifest {
 
 /**
  * The raw-Markdown mirror pattern. `Accept: text/markdown` negotiation is
- * advertised only where the deployed site actually honors it — a Vercel
- * server build, whose routing config gets the rewrite rules (see
- * `deploy/vercel-negotiation.ts`), and a Cloudflare server build, whose
- * deploy bundle gets a wrapper Worker (see `deploy/cloudflare-negotiation.ts`).
- * Static builds and other adapters serve prerendered pages from a static
- * layer with no request-time hook, so agents there should fetch the `.md`
- * pattern directly.
+ * advertised only where the deployed site actually honors it — a server build
+ * on a platform that declares `negotiatesMarkdown` (Vercel, whose routing
+ * config gets the rewrite rules; Cloudflare, whose deploy bundle gets a
+ * wrapper Worker — see `deploy/platforms/*`). Static builds and other
+ * adapters serve prerendered pages from a static layer with no request-time
+ * hook, so agents there should fetch the `.md` pattern directly.
  */
 const markdownArtifact = (
   config: BlumeProject["config"],
   abs: (path: string) => string
 ): AgentArtifacts["markdown"] => {
   const negotiates =
-    config.deployment.output === "server" &&
-    (config.deployment.adapter === "vercel" ||
-      config.deployment.adapter === "cloudflare");
+    config.deployment.options.output === "server" &&
+    deployPlatform(config.deployment).negotiatesMarkdown;
   return negotiates
     ? { contentNegotiation: "text/markdown", pattern: abs("/{route}.md") }
     : { pattern: abs("/{route}.md") };
@@ -116,14 +115,14 @@ const apiArtifact = (
   config: BlumeProject["config"],
   abs: (path: string) => string
 ): ApiArtifact | null => {
-  if (!config.ai.api) {
+  if (!config.agents.api) {
     return null;
   }
   const api: ApiArtifact = {
     openapi: abs(OPENAPI_PATH),
     pages: abs(API_PAGES_PATH),
   };
-  if (config.deployment.output === "server") {
+  if (config.deployment.options.output === "server") {
     api.search = abs(API_SEARCH_PATH);
   }
   return api;
@@ -135,7 +134,7 @@ const wellKnownArtifacts = (
   abs: (path: string) => string
 ): WellKnownArtifacts => {
   const artifacts: WellKnownArtifacts = {};
-  if (config.ai.webBotAuth.keys.length > 0) {
+  if (config.agents.webBotAuth.keys.length > 0) {
     artifacts.httpMessageSignaturesDirectory = abs(
       "/.well-known/http-message-signatures-directory"
     );
@@ -146,7 +145,7 @@ const wellKnownArtifacts = (
   if (hasApiCatalog(config)) {
     artifacts.apiCatalog = abs("/.well-known/api-catalog");
   }
-  if (config.ai.skills) {
+  if (config.agents.skills) {
     artifacts.agentSkills = abs("/.well-known/agent-skills/index.json");
   }
   return artifacts;
@@ -165,14 +164,14 @@ export const buildAgentReadability = (
   project: BlumeProject
 ): AgentReadabilityManifest | null => {
   const { config } = project;
-  if (!config.seo.agentReadability) {
+  if (!config.agents.agentReadability) {
     return null;
   }
 
-  const site = config.deployment.site ?? null;
+  const site = config.deployment.options.site ?? null;
   // Every artifact is served under `deployment.base` — with or without a
   // `site`; concatenate rather than `new URL()` so the subpath is preserved.
-  const deployBase = normalizeBasePath(config.deployment.base);
+  const deployBase = normalizeBasePath(config.deployment.options.base);
   const abs = (path: string): string => {
     const based = withBasePath(deployBase, path);
     return site ? absoluteUrl(site, based) : based;
@@ -185,14 +184,14 @@ export const buildAgentReadability = (
   if (api) {
     artifacts.api = api;
   }
-  if (config.ai.llmsTxt.enabled) {
+  if (config.agents.llmsTxt.enabled) {
     artifacts.llmsFullTxt = abs("/llms-full.txt");
     artifacts.llmsTxt = abs("/llms.txt");
   }
-  if (config.ai.mcp.enabled) {
+  if (config.agents.mcp.enabled) {
     artifacts.mcp = {
       discovery: abs("/.well-known/mcp.json"),
-      url: abs(config.ai.mcp.route),
+      url: abs(config.agents.mcp.route),
     };
   }
   if (config.ai.ask?.enabled) {
@@ -215,11 +214,11 @@ export const buildAgentReadability = (
     artifacts,
     description: config.description,
     generator: version ? `blume@${version}` : undefined,
-    name: config.ai.mcp.name ?? config.title,
+    name: config.agents.mcp.name ?? config.title,
     site,
   };
 
-  const usage = usagePolicy(config.seo.contentSignals);
+  const usage = usagePolicy(config.agents.contentSignals);
   if (usage) {
     manifest.contentUsage = usage;
   }

package/src/ai/ai-catalog.ts

@@ -1,3 +1,4 @@
+import { apiNamePhrase } from "../core/api-name.ts";
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { absoluteUrl } from "../core/site-url.ts";
@@ -63,6 +64,7 @@ const REFERENCE_KIND_LABEL = {
   asyncapi: "AsyncAPI",
   graphql: "GraphQL",
   openapi: "OpenAPI",
+  scalar: "API",
 } as const;
 
 /** The `urn:air` publisher: the configured site's hostname. */
@@ -75,12 +77,12 @@ const publisherHost = (site: string): string => new URL(site).hostname;
  * header rules, the `Link` header, and the head links read.
  */
 export const hasAiCatalog = (config: ResolvedConfig): boolean =>
-  config.ai.catalog.enabled &&
-  Boolean(config.deployment.site) &&
-  (config.ai.mcp.enabled ||
-    config.ai.api ||
-    config.ai.llmsTxt.enabled ||
-    Boolean(config.ai.skills) ||
+  config.agents.catalog.enabled &&
+  Boolean(config.deployment.options.site) &&
+  (config.agents.mcp.enabled ||
+    config.agents.api ||
+    config.agents.llmsTxt.enabled ||
+    Boolean(config.agents.skills) ||
     resolveReferences(config).length > 0);
 
 /**
@@ -97,33 +99,47 @@ export const crossOriginDiscoveryPaths = (config: ResolvedConfig): string[] => {
   if (hasApiCatalog(config)) {
     paths.push(API_CATALOG_PATH);
   }
-  if (config.ai.mcp.enabled) {
+  if (config.agents.mcp.enabled) {
     paths.push("/.well-known/mcp.json", "/.well-known/mcp/server-card.json");
   }
   return paths;
 };
 
+/** A site title that already names its docs: "Acme Docs", "Acme Documentation". */
+const NAMES_DOCS = /\b(?:docs|documentation)$/iu;
+
+/**
+ * The docs as "the ___" in generated prose: the title followed by `noun`,
+ * unless the title already ends in "Docs" or "Documentation" — so "Acme"
+ * reads "the Acme documentation" and "Acme Docs" reads "the Acme Docs", not
+ * "the Acme Docs docs".
+ */
+const docsPhrase = (title: string, noun: "docs" | "documentation"): string =>
+  NAMES_DOCS.test(title.trim()) ? `the ${title}` : `the ${title} ${noun}`;
+
 const entrySeeds = (
   config: ResolvedConfig,
   skills: readonly SkillArtifact[],
   abs: (path: string) => string
 ): EntrySeed[] => {
   const { title } = config;
+  const documentation = docsPhrase(title, "documentation");
+  const docs = docsPhrase(title, "docs");
   const seeds: EntrySeed[] = [];
 
-  if (config.ai.mcp.enabled) {
-    const name = config.ai.mcp.name ?? title;
+  if (config.agents.mcp.enabled) {
+    const name = config.agents.mcp.name ?? title;
     seeds.push({
       capabilities: ["search_docs", "get_page", "list_pages", "get_navigation"],
       description:
-        config.ai.mcp.instructions ??
-        `Model Context Protocol server over the ${title} documentation: full-text search, page Markdown, the page index, and the navigation tree.`,
+        config.agents.mcp.instructions ??
+        `Model Context Protocol server over ${documentation}: full-text search, page Markdown, the page index, and the navigation tree.`,
       displayName: name,
       key: `mcp:${asciiSlugify(name) || "docs"}`,
       queries: [
-        `search the ${title} documentation`,
-        `get a ${title} docs page as Markdown`,
-        `list every page in the ${title} docs`,
+        `search ${documentation}`,
+        `get a page of ${docs} as Markdown`,
+        `list every page in ${docs}`,
       ],
       type: "application/mcp-server-card+json",
       url: abs("/.well-known/mcp/server-card.json"),
@@ -147,15 +163,17 @@ const entrySeeds = (
     });
   }
 
-  if (config.ai.api) {
+  if (config.agents.api) {
     seeds.push({
-      description: `REST API over the ${title} documentation: the page index, each page as JSON or Markdown, and the navigation tree, described by this OpenAPI document.`,
-      displayName: `${title} docs API`,
+      description: `REST API over ${documentation}: the page index, each page as JSON or Markdown, and the navigation tree, described by this OpenAPI document.`,
+      displayName: NAMES_DOCS.test(title.trim())
+        ? `${title} API`
+        : `${title} docs API`,
       key: "api:docs",
       queries: [
-        `fetch a ${title} docs page as JSON`,
-        `list the pages in the ${title} docs`,
-        `get the ${title} docs navigation tree`,
+        `fetch a page of ${docs} as JSON`,
+        `list the pages in ${docs}`,
+        `get the navigation tree of ${docs}`,
       ],
       type: "application/vnd.oai.openapi+json",
       url: abs(OPENAPI_PATH),
@@ -168,28 +186,28 @@ const entrySeeds = (
     // resource this publisher owns — the spec itself is catalogued by URL in
     // the RFC 9727 linkset.
     const docRoute =
-      reference.renderer === "blume"
-        ? withBasePath(reference.basePath, reference.route)
-        : reference.route;
+      reference.kind === "scalar"
+        ? reference.route
+        : withBasePath(reference.basePath, reference.route);
     seeds.push({
-      description: `${reference.label}: rendered ${REFERENCE_KIND_LABEL[reference.kind]} reference in the ${title} documentation.`,
+      description: `${reference.label}: rendered ${REFERENCE_KIND_LABEL[reference.kind]} reference in ${documentation}.`,
       displayName: reference.label,
       key: `reference:${reference.slug}`,
       queries: [
-        `what operations does the ${reference.label} API expose`,
-        `how do I call the ${reference.label} API`,
+        `what operations does the ${apiNamePhrase(reference.label)} expose`,
+        `how do I call the ${apiNamePhrase(reference.label)}`,
       ],
       type: "text/html",
       url: abs(docRoute),
     });
   }
 
-  if (config.ai.llmsTxt.enabled) {
+  if (config.agents.llmsTxt.enabled) {
     seeds.push({
-      description: `llms.txt index of the ${title} documentation: every page with a one-line summary, plus the agent-facing resources on this site.`,
+      description: `llms.txt index of ${documentation}: every page with a one-line summary, plus the agent-facing resources on this site.`,
       displayName: `${title} llms.txt`,
       key: "docs:llms-txt",
-      queries: [`what is ${title}`, `overview of the ${title} documentation`],
+      queries: [`what is ${title}`, `overview of ${documentation}`],
       type: "text/plain",
       url: abs("/llms.txt"),
     });
@@ -203,11 +221,11 @@ export const buildAiCatalog = (
   config: ResolvedConfig,
   skills: readonly SkillArtifact[]
 ): string | null => {
-  const site = config.deployment.site ?? null;
+  const site = config.deployment.options.site ?? null;
   if (!(site && hasAiCatalog(config))) {
     return null;
   }
-  const deployBase = normalizeBasePath(config.deployment.base);
+  const deployBase = normalizeBasePath(config.deployment.options.base);
   const abs = (path: string): string =>
     absoluteUrl(site, withBasePath(deployBase, path));
   const host = publisherHost(site);
@@ -216,7 +234,7 @@ export const buildAiCatalog = (
       displayName: seed.displayName,
       identifier: `urn:air:${host}:${seed.key}`,
       representativeQueries:
-        config.ai.catalog.queries[seed.key] ?? seed.queries,
+        config.agents.catalog.queries[seed.key] ?? seed.queries,
       type: seed.type,
       url: seed.url,
     };

package/src/ai/api/handlers.ts

@@ -154,19 +154,43 @@ export const buildPage = (data: McpData, route: string): ApiPage | null => {
   return { ...summarize(entry, data), markdown };
 };
 
+/** The 404 for a route no page has, at its per-page JSON path. */
+const pageNotFoundResponse = (
+  route: string,
+  context: ApiSiteContext
+): Response =>
+  problemResponse({
+    code: "PAGE_NOT_FOUND",
+    detail: `No documentation page has the route "${route}".`,
+    instance: siteUrl(pageJsonPath(route), context),
+    resolution: `List every page at ${siteUrl(API_PAGES_PATH, context)}, or discover the API through ${siteUrl(OPENAPI_PATH, context)}.`,
+    status: 404,
+    title: "Page not found",
+  });
+
 export const pageResponse = (data: McpData, route: string): Response => {
   const page = buildPage(data, route);
-  if (!page) {
-    return problemResponse({
-      code: "PAGE_NOT_FOUND",
-      detail: `No documentation page has the route "${route}".`,
-      instance: siteUrl(pageJsonPath(route), data),
-      resolution: `List every page at ${siteUrl(API_PAGES_PATH, data)}, or discover the API through ${siteUrl(OPENAPI_PATH, data)}.`,
-      status: 404,
-      title: "Page not found",
-    });
+  return page ? jsonResponse(page) : pageNotFoundResponse(route, data);
+};
+
+const PAGE_JSON_PATH = /^\/api\/docs\/pages\/(?<param>.+)\.json$/u;
+
+/**
+ * The route a base-less `pages/{route}.json` path asks for (`index` is the
+ * home page), or `undefined` for any other path.
+ */
+const requestedPageRoute = (path: string): string | undefined => {
+  const param = PAGE_JSON_PATH.exec(path)?.groups?.param;
+  if (param === undefined) {
+    return undefined;
+  }
+  let decoded = param;
+  try {
+    decoded = decodeURIComponent(param);
+  } catch {
+    // A malformed escape names no page either; report it as written.
   }
-  return jsonResponse(page);
+  return decoded === "index" ? "/" : `/${decoded}`;
 };
 
 /** The default navigation tree (default locale, current docs). */
@@ -248,13 +272,24 @@ export const createSearchHandler = (
 /**
  * The 404 for anything under `/api/` that no endpoint answers — the catch-all
  * behind every live route on server output, so an agent probing the API
- * namespace gets a problem document instead of the HTML not-found page.
+ * namespace gets a problem document instead of the HTML not-found page. A
+ * `pages/{route}.json` miss gets the per-page `PAGE_NOT_FOUND` problem.
  */
 export const apiNotFoundResponse = (
   request: Request,
   context: ApiSiteContext
 ): Response => {
   const { pathname } = new URL(request.url);
+  // Per-page JSON is prerendered, so a route no page has falls through to
+  // this catch-all on server output; answer it as the page miss it is.
+  const baseless =
+    context.base && pathname.startsWith(`${context.base}/`)
+      ? pathname.slice(context.base.length)
+      : pathname;
+  const route = requestedPageRoute(baseless);
+  if (route !== undefined) {
+    return pageNotFoundResponse(route, context);
+  }
   return problemResponse({
     code: "API_ROUTE_NOT_FOUND",
     detail: `No API route exists at ${pathname}.`,