blume 2.1.1 → 2.1.3

package/docs/discoverability/structured-data.mdx

@@ -1,6 +1,6 @@
 ---
 title: Structured data
-description: The schema.org JSON-LD every page carries — WebSite, article, and breadcrumb nodes — plus the optional Organization and SoftwareApplication blocks that tell search engines and agents who you are.
+description: The schema.org JSON-LD every page carries — WebSite, page, and breadcrumb nodes — plus the optional Organization and SoftwareApplication blocks that tell search engines and agents who you are.
 ---
 
 Blume emits [schema.org](https://schema.org) JSON-LD in every page's `<head>` so search engines understand your content. On by default:
@@ -14,10 +14,12 @@ seo: {
 Each page includes:
 
 - a **WebSite** node for site identity,
-- the page as an **article** — `BlogPosting` for blog posts, `TechArticle` for changelog and docs — with its description and publish date,
-- a **BreadcrumbList** built from the navigation trail.
+- the page itself, with its description, language, and publish date: a **WebPage** on the homepage, and an **article** everywhere else — `BlogPosting` for blog posts, `TechArticle` for changelog and docs,
+- on an article, a **BreadcrumbList** built from the navigation trail.
 
-URLs are absolute when [`deployment.site`](/docs/deployment) is set. Pages marked [`seo.noindex`](/docs/discoverability/metadata#per-page-overrides) are skipped. When [`lastModified`](/docs/configuration#last-modified) is on, each page's date is also emitted as `dateModified`.
+The homepage is the root of the navigation, so each locale's home (`/fr`) and the root of a [`basePath`](/docs/deployment#mount-the-docs-under-a-path) are WebPages too.
+
+URLs are absolute when [`deployment.site`](/docs/deployment) is set. Without it they're route-relative, and the WebSite node, which needs an absolute identifier, is left out. Pages marked [`seo.noindex`](/docs/discoverability/metadata#per-page-overrides) are skipped. When [`lastModified`](/docs/configuration#last-modified) is on, each page's date is also emitted as `dateModified`, and the visible "Last updated" date is marked up as a `<time datetime>`, so search engines read that date rather than some other date on the page.
 
 ## Site identity
 
@@ -42,10 +44,10 @@ seo: {
 }
 ```
 
-`organization` adds an **Organization** node to every page — the WebSite and article nodes cite it as `publisher` — with the email and telephone as a `ContactPoint` (`contactType` defaults to `"customer support"`) and the address as a `PostalAddress`, the two fields business-verification checks look for. `name` and `url` default to the site's; a root-relative `logo` is absolutized like any page URL.
+`organization` adds an **Organization** node to every page — the WebSite and page nodes cite it as `publisher` — with the email and telephone as a `ContactPoint` (`contactType` defaults to `"customer support"`) and the address as a `PostalAddress`, the two fields business-verification checks look for. `name` and `url` default to the site's; a root-relative `logo` is absolutized like any page URL.
 
 `software` adds a **SoftwareApplication** node to the homepage: the product's name and description (defaulting to the site's), `applicationCategory` (default `"DeveloperApplication"`), operating system, license, an `Offer` when `price` is set, and the registry or repository URLs in `sameAs`. Pass `software: true` to take every default. The organization, when configured, is cited as its `publisher`.
 
 ## Custom pages
 
-A custom [`.astro` page](/docs/advanced/custom-pages) rendered through `PageLayout` emits the same `WebSite` graph, so a marketing home page isn't the one URL without structured data. Pass `structuredDataEnabled={config.structuredData}` to keep it in sync with this setting, or `structuredDataEnabled={false}` to turn it off for that page alone.
+A custom [`.astro` page](/docs/advanced/custom-pages) rendered through `PageLayout` emits the same graph, so a marketing home page isn't the one URL without structured data. A custom page has no content file to date, so pass `lastModified` to give it a `dateModified`. Pass `structuredDataEnabled={config.structuredData}` to keep it in sync with this setting, or `structuredDataEnabled={false}` to turn it off for that page alone.

package/docs/references/asyncapi.mdx

@@ -22,6 +22,8 @@ navigation: {
 }
 ```
 
+[Document Kafka events with AsyncAPI](/guides/asyncapi-kafka-documentation) walks through it for Kafka topics, with producer and consumer code beside the reference.
+
 ## Spec versions
 
 AsyncAPI **2.x specs are normalized to 3.x automatically** with the official AsyncAPI converter, so `publish`/`subscribe` channels map onto `send`/`receive` operation pages with stable URLs — later upgrading the spec file itself through the converter moves nothing. The converter is an optional peer dependency, so a site with a 1.x or 2.x spec installs it (`npm install @asyncapi/converter`); without it the build fails with that install command. A 3.x spec needs nothing extra. Operations group by tag; untagged operations group under their channel address.

package/docs/references/graphql.mdx

@@ -38,6 +38,8 @@ navigation: {
 }
 ```
 
+[Generate GraphQL docs from your schema](/guides/graphql-documentation-website) walks through it from a schema to a deployed site, with a Try it panel that queries a sandbox.
+
 ## Generated examples
 
 Every operation page carries a complete, valid example operation — one variable per argument, typed off the schema, with a bounded-depth selection set over the return type — plus matching example variables and an example response that mirrors the same selection. A variable whose argument declares a default starts at that default, and the selection leaves deprecated fields out. Code samples show the exact HTTP request (a JSON `POST` of `{ query, variables }`) in each configured language. The same [languages](/docs/references/openapi#code-samples-and-schemas) as `openapi()` are available, and `codeSamples: false` shows none:

package/docs/references/openapi.mdx

@@ -20,6 +20,8 @@ export default defineConfig({
 
 That mounts the reference at `/reference` (an overview page) with each operation at `/reference/<tag>/<operation>`. The `spec` is either an `http(s)` URL or a path to a local file in your project. Blume parses it with [Scalar's OpenAPI parser](https://github.com/scalar/scalar) — Swagger 2.0 and OpenAPI 3.0 specs are upgraded to 3.1 automatically, and 3.1 and [3.2](#openapi-32) specs are read as written. An adapter is a plain description of the reference — not a parsed spec — so Blume can validate it up front and inline it into the generated site; leaving `reference` out (or empty) renders no reference at all. Documenting an event-driven or GraphQL API instead? See [AsyncAPI](/docs/references/asyncapi) and [GraphQL](/docs/references/graphql).
 
+To go from your framework's generated spec to a deployed reference, follow the guide for [FastAPI](/guides/fastapi-documentation-website), [Django REST Framework](/guides/django-rest-framework-api-documentation), [NestJS](/guides/nestjs-api-documentation-website), [Spring Boot](/guides/spring-boot-api-documentation), [Hono](/guides/hono-zod-api-documentation), [Fastify](/guides/fastify-api-documentation), [Elysia](/guides/elysia-api-documentation), or [oRPC](/guides/orpc-openapi-documentation). [Generate API docs from an OpenAPI spec](/guides/openapi-documentation-website) starts from any spec file.
+
 The reference doesn't add a header tab on its own. To surface it, point a [navigation tab](/docs/content/navigation#tabs) at its route — this also scopes the operations sidebar for the native renderer:
 
 ```ts blume.config.ts
@@ -139,6 +141,8 @@ paths:
             $ref: ./code_samples/go/list_plants.go
 ```
 
+[Add SDK examples to generated API documentation](/guides/openapi-sdk-code-samples) walks through samples for a TypeScript and a Python SDK, with a check that catches samples an SDK release broke.
+
 ## Try it playground
 
 Operation pages rendered natively ship an interactive **Try it** panel by default. Blume generates the form from the operation itself: an input per path, query, and header parameter, a body editor built from the request-body schema, everything prefilled from the spec's examples. Values go on the wire the way the spec describes them: array and object parameters follow their `style` and `explode` (`tags=dog&tags=cat` in a query, `1,2` in a path, `filter[color]=red` for `deepObject`), and an `application/x-www-form-urlencoded` or `multipart/form-data` body is sent as form fields rather than JSON. A server picker lists the operation's servers (its own `servers`, else its path's, else the spec's, with each `{variable}` at its `default`), with a free-text field for any other base URL, and auth inputs match the operation's [resolved security](#authorization) — bearer token, API key, and basic credentials, with OAuth2 as a token paste field (bring an access token; Blume doesn't run the flow).
@@ -174,6 +178,8 @@ reference: [
 
 The built-in proxy only forwards requests to the origins your specs declare in `servers` (at the document, path, or operation level, with variables at their defaults) — including across redirects — so a public docs deployment can't be aimed at other hosts on its network. A **Custom base URL** typed into the panel isn't a documented server: with the proxy enabled, requests to it are refused with a 403. It forwards only the headers the panel sets itself — the credentials and header parameters filled in, and the body's `Content-Type` — so cookies, credentials the browser attaches for the docs site (HTTP Basic auth on a password-protected preview, say), and headers your host adds (`X-Forwarded-For`, `CF-*`, `X-Vercel-*`) never reach the API. It reads a request body only up to 4 MB (anything larger gets a `413`), and every response it relays carries `Content-Security-Policy: sandbox`, `X-Content-Type-Options: nosniff`, and `Cross-Origin-Resource-Policy: same-origin` — plus `Content-Disposition: attachment` for HTML or SVG — so an API error page that echoes its input can't run script on the docs origin. The proxy is also [rate limited](/docs/configuration/rate-limiting) per reader, like every server route a reader can call.
 
+When a Try it request is blocked, [Fix CORS errors in an API documentation playground](/guides/api-documentation-cors-errors) reproduces it, reads the preflight the browser sends, and fixes it with a CORS policy on your API or the built-in proxy.
+
 ## Multiple specs
 
 Use `sources` to publish more than one spec from one adapter. Each source gets its own overview route and operation pages, and shares the adapter's display options. Give each a `label`, which names its group in the sidebar as written and derives its route, or set an explicit `route`:
@@ -191,6 +197,8 @@ reference: [
 
 `spec` is shorthand for a single-entry `sources`, so you only reach for `sources` when you have more than one. When two specs need different display options — a different code-sample set, say — list two `openapi()` adapters instead, each with its own `route`. An embedded [Scalar](/docs/references/scalar) reference beside native pages is its own `scalar()` adapter in the list. Sources are resolved in list order, and when two resolve to the same route the first one wins (the build warns about the one it dropped).
 
+[Combine multiple OpenAPI specifications in one docs site](/guides/multiple-openapi-specs-documentation) builds an API portal this way, with each service's spec on its own route and tab.
+
 ### Per-source indexing
 
 Generated pages participate in search, `llms.txt`, and crawler indexing by default. A secondary or overlapping spec can opt out of any surface without hiding its pages or removing it from navigation:
@@ -259,6 +267,8 @@ Each action's `target` is a [JSONPath](https://www.rfc-editor.org/rfc/rfc9535) e
 
 Overlays apply to the spec as written, before Blume upgrades it to OpenAPI 3.1, so an overlay targets the version you wrote the spec in. Everything built from the spec sees the result: the operation pages, the sidebar, search, `llms.txt`, and the MCP server. With `sources`, give each source its own `overlays`. An overlay that doesn't apply fails the reference the way an unreadable spec does, so a broken overlay can't publish what it was meant to hide.
 
+[Remove internal endpoints from public API docs](/guides/openapi-overlays-public-docs) walks through an overlay that strips internal operations from a generated spec on every build.
+
 ## Authorization
 
 Operations that declare [security requirements](https://spec.openapis.org/oas/v3.1.0#security-requirement-object) render an **Authorization** section above their parameters, and the generated code samples send a placeholder credential (`Authorization: Bearer YOUR_TOKEN`, an API-key header, or a query key — whatever the scheme calls for). There's nothing to configure: Blume reads `security` from the spec, so the reference always matches what the API actually enforces.
@@ -295,6 +305,8 @@ An operation's [`callbacks`](https://spec.openapis.org/oas/v3.1.0#callback-objec
 
 Webhook pages are real pages: they're in search, `llms.txt`, and the MCP server, and their Markdown tells agents it's a request the API sends, so an agent won't try to call it.
 
+[Write webhook documentation with OpenAPI 3.1](/guides/openapi-webhook-documentation) adds signature headers and acknowledgments to the webhook pages, plus a receiving guide with a working Node.js receiver.
+
 ## Spec warnings
 
 Blume doesn't validate a spec against the OpenAPI schema: run a linter such as [Spectral](https://github.com/stoplightio/spectral) or [oasdiff](https://github.com/oasdiff/oasdiff) in CI for that. It does warn, in `blume dev`, `blume build`, and `blume check`, about mistakes that would otherwise render wrong without any sign, and about parts of a spec it leaves out. Each warning names the spec, and the rest of the reference still builds:
@@ -309,6 +321,8 @@ Blume doesn't validate a spec against the OpenAPI schema: run a linter such as [
 | `BLUME_OPENAPI_X_WEBHOOKS` | A 3.1 or later spec keeps its webhooks under `x-webhooks`, the extension 3.0 tools read, and has no `webhooks`, so none of them render. Rename the field to `webhooks`. |
 | `BLUME_OPENAPI_REF_PATH_ITEM` | A path or webhook is a `$ref` to a shared path item, such as one under `components.pathItems`. Blume doesn't resolve these, so its operations are missing from the reference. Inline the path item under `paths` or `webhooks`; its schemas, parameters, and responses can stay `$ref`s. |
 
+[Keep API documentation in sync with backend changes in CI](/guides/openapi-documentation-ci) runs those checks in GitHub Actions: it exports the spec from the backend, fails when the spec is stale, invalid, or breaking, and rebuilds the reference from it.
+
 ## Embedding Scalar instead
 
 `openapi()` always renders Blume's own pages. To embed [Scalar](https://scalar.com)'s self-contained API reference UI on a single route instead — its own sidebar, search, theme, and request client — list a `scalar()` adapter from `blume/reference` in place of (or beside) this one. The [Scalar](/docs/references/scalar) page covers what the embed does and doesn't do, and how to pass Scalar's own options through.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "The open-source docs framework for humans and agents.",
   "keywords": [
     "agents",
@@ -113,19 +113,19 @@
   "dependencies": {
     "@astrojs/check": "^0.9.10",
     "@astrojs/markdown-satteri": "^0.4.1",
-    "@astrojs/mdx": "^8.0.1",
-    "@astrojs/node": "^11.1.5",
+    "@astrojs/mdx": "^8.0.2",
+    "@astrojs/node": "^11.1.6",
     "@astrojs/react": "^7.0.0",
     "@astrojs/vercel": "^11.0.11",
     "@clack/prompts": "^1.8.0",
-    "@iconify-json/lucide": "^1.2.131",
+    "@iconify-json/lucide": "^1.2.140",
     "@iconify/types": "^2.0.0",
     "@iconify/utils": "^3.1.7",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@orama/orama": "^3.1.18",
     "@pierre/diffs": "^1.5.1",
     "@scalar/astro": "^0.4.26",
-    "@scalar/openapi-parser": "^0.29.1",
+    "@scalar/openapi-parser": "^0.29.11",
     "@scalar/openapi-types": "^0.9.5",
     "@shikijs/transformers": "^4.4.3",
     "@shikijs/twoslash": "^4.4.3",
@@ -134,6 +134,7 @@
     "@types/mdast": "^4.0.4",
     "@types/node": "^22.20.2",
     "@vercel/analytics": "^2.0.1",
+    "@vitejs/plugin-react": "6.1.1",
     "ai": "^7.0.99",
     "astro": "^7.3.2",
     "chokidar": "^5.0.0",
@@ -141,7 +142,7 @@
     "consola": "^3.4.2",
     "cross-spawn": "^7.0.6",
     "dompurify": "^3.4.16",
-    "dotenv": "^17.4.2",
+    "dotenv": "^18.0.5",
     "epub-gen-memory": "^1.1.2",
     "es-module-lexer": "^3.0.2",
     "fast-xml-parser": "^5.11.1",

package/skills/blume/SKILL.md

@@ -68,7 +68,7 @@ Every build publishes a generated agent skill for the site at `/skill.md` (`agen
 - **Components** — callouts, cards, steps, tabs, accordions, badges, file trees, and parameter tables, usable in MDX with no imports.
 - **Local search** — Orama in dev and production, with no hosted index; Pagefind, Algolia, and other backends are one adapter away (`search: pagefind()` from `blume/search`).
 - **AI** — `llms.txt`, raw Markdown URLs, a JSON docs API with an OpenAPI description, Copy as Markdown, Open in chat, an in-page assistant, and an MCP server endpoint served by the docs site itself.
-- **Narration** — a "Listen to this page" player (`narration: true` for browser voices, or `narration: { provider: gateway({ … }) }` from `blume/ai` for voices generated at build).
+- **Narration** — a "Listen to this page" player (`narration: true` for browser voices, or `narration: { provider: gateway({ … }) }` from `blume/ai` for voices generated at build; `openai({ model, voice })` uses OpenAI's speech models instead, and with a `baseUrl` a self-hosted OpenAI-compatible speech server, and needs `@ai-sdk/openai` installed).
 - **Navigation** — inferred from files, refined with `meta.ts` or config.
 - **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD.
 - **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.

package/skills/blume-migrate/SKILL.md

@@ -32,7 +32,7 @@ Throughout this skill (including the `references/` files), **`<skill>` means the
 3. **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: "…" })`.
 4. **Restructure content.** 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.** 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.
 5. **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 `<include>` statements or inline them (Blume has no import-based includes: `import Snippet from "…"` plus `<Snippet />` has to become one or the other); 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); **add a `redirects` entry for every route you moved** in step 4; **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 `##`). **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 <skill>/scripts/mintlify-codemod.mjs --write <content-dir>` 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`).
-6. **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. **Always regenerate the lockfile in the same change:** after editing deps run a plain `pnpm install` (from the workspace root) and commit `pnpm-lock.yaml` alongside `package.json` — CI/Vercel use `--frozen-lockfile`, so a stale lockfile fails the build before it starts. **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.67.0.patch` and register it under `patchedDependencies` — see `references/monorepo.md` §6. See `references/monorepo.md` §2–3.
+6. **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. **Always regenerate the lockfile in the same change:** after editing deps run a plain `pnpm install` (from the workspace root) and commit `pnpm-lock.yaml` alongside `package.json` — CI/Vercel use `--frozen-lockfile`, so a stale lockfile fails the build before it starts. **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.
 7. **Wire up the host repo & deploy (non-trivial repos).** For a monorepo on Vercel, emit the root-aware install/build recipe and `apps/docs/vercel.json`, and tell the user the two settings you can't commit (Vercel Root Directory, Node 22). 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.
 8. **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 invalid pages) and `blume validate --strict` (internal links, heading anchors, assets — 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).
 

package/skills/blume-migrate/assets/{oxfmt@0.67.0.patch → oxfmt@0.71.0.patch}

@@ -1,12 +1,12 @@
-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) {
+diff --git a/dist/markdown-gizI1LFO.js b/dist/markdown-gizI1LFO.js
+index 95a638402fa6f73b29ebb8d7a7ef229bee68a690..e2e2ea5b443fe10698c49c2ef3dc3d5909335915 100644
+--- a/dist/markdown-gizI1LFO.js
++++ b/dist/markdown-gizI1LFO.js
+@@ -4898,7 +4898,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 } = e, u = a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !RE(e) && !(t.proseWrap === "preserve" && ME(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
@@ -43,7 +43,7 @@ index bc9037f6c0de5516b139d8cdb195b1e25cd33bc0..a02c284e28bb535f9964a8a086ebb654
 +				}
 +				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;
++			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(a) ? "preserve" : a && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(a.value) && !RE(e) && !(t.proseWrap === "preserve" && ME(e)) ? "never" : t.proseWrap;
  			return ou(e, n.value, u, !1, t);
  		}
  		case "emphasis": {

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

@@ -190,13 +190,13 @@ This is a **manual step — do not fabricate the patch contents.** Leave the use
 
 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.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:
+The fix is a committed **pnpm patch** (`patches/oxfmt@0.71.0.patch`), shipped with this skill at `assets/oxfmt@0.71.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.67.0.patch" patches/oxfmt@0.67.0.patch
+cp "<skill>/assets/oxfmt@0.71.0.patch" patches/oxfmt@0.71.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.67.0: patches/oxfmt@0.67.0.patch
+  oxfmt@0.71.0: patches/oxfmt@0.71.0.patch
 ```
 
 Commit **both** the patch file and the `patchedDependencies` entry, then re-run `pnpm install`.
 
-- **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.
+- **The patch is pinned to `oxfmt@0.71.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.71.0` as a direct dev dependency (Ultracite accepts any `oxfmt` ≥ 0.59 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.67.0.patch` + registered it under `patchedDependencies` so formatting doesn't mangle `:::` directives.
+- [ ] Uses Ultracite/oxfmt? Shipped `patches/oxfmt@0.71.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/src/ai/ask.ts

@@ -110,7 +110,8 @@ export interface AssistantGatewayOptions extends AssistantAdapterOptions {
    * How much the model reasons before answering. Sent as the AI SDK's
    * top-level `reasoning` option, which the gateway maps to the model's own
    * control (OpenAI's `reasoning_effort`, for example); the model has to
-   * offer the level you pick. Omitted keeps the model's default.
+   * offer the level you pick. Omitted keeps the model's default. Assistant
+   * only.
    */
   reasoning?: AssistantReasoning;
   /** Narration only: the speech model's voice. Defaults to `alloy`. */
@@ -153,32 +154,47 @@ export const gateway = (
 // openai()
 // ---------------------------------------------------------------------------
 
-const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
+export const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
 
 /** Options for {@link openai}. */
 export interface AssistantOpenAIOptions extends AssistantAdapterOptions {
+  /**
+   * Name of the env var holding the key. Defaults to `OPENAI_API_KEY`, except
+   * for narration with a `baseUrl`, which sends only a key named here.
+   */
+  apiKeyEnv?: string;
   /**
    * An OpenAI-compatible endpoint to call instead of OpenAI
    * (`https://llm.internal.example.com/v1`): a self-hosted model or an
    * internal gateway. The route then talks Chat Completions through
    * `@ai-sdk/openai-compatible`, and the docs tools are off unless
    * `ai.assistant.tools` turns them on, since the model may not call tools.
+   * For narration, a server with OpenAI's speech API (`/audio/speech`),
+   * called through `@ai-sdk/openai` and sent only the key `apiKeyEnv` names,
+   * if any.
    */
   baseUrl?: string;
-  /** The model id (`gpt-5.5`). */
+  /**
+   * Narration only: how the voice should sound, for speech models that take
+   * instructions ("Read calmly, like a teacher").
+   */
+  instructions?: string;
+  /** The model id (`gpt-5.5`, or a speech model like `gpt-4o-mini-tts`). */
   model: string;
   /**
    * The provider name the AI SDK reports, which a custom endpoint also reads
    * its `providerOptions` under. Defaults to `openai`, or `openai-compatible`
-   * with a `baseUrl`.
+   * with a `baseUrl`. Assistant only.
    */
   name?: string;
   /**
    * How much the model reasons before answering, sent as `reasoning_effort`;
    * with a `baseUrl`, the endpoint has to accept that parameter. Omitted
-   * keeps the model's default.
+   * keeps the model's default. Assistant only.
    */
   reasoning?: AssistantReasoning;
+  /** Narration only: the speech model's voice. Defaults to `alloy`. */
+  voice?: string;
 }
 
 const openaiOptionsSchema = z.strictObject({
@@ -203,7 +219,9 @@ export const openaiAdapterSchema = adapterDescriptorSchema(
  * Route the assistant to OpenAI, or to any OpenAI-compatible endpoint with
  * `baseUrl`. Reads `OPENAI_API_KEY` and needs `@ai-sdk/openai` installed; a
  * custom endpoint needs `@ai-sdk/openai-compatible` instead, since most
- * don't serve OpenAI's Responses API.
+ * don't serve OpenAI's Responses API. Narration generates audio with it
+ * through `@ai-sdk/openai` either way, and with a `baseUrl` sends only the key
+ * `apiKeyEnv` names.
  */
 export const openai = (
   options: AssistantOpenAIOptions

package/src/analytics/clics.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+
+/** The browser tracker in Clics' installation guide. */
+export const CLICS_SCRIPT_SRC = "https://clics.dev/tracker.js";
+
+/** Public project ID and optional tracker flags. */
+export interface ClicsOptions {
+  /** Project ID from Configure → Tracking in the Clics dashboard. */
+  projectId: string;
+  /** Include localhost and 127.0.0.1 in a production build's reports. */
+  allowLocalhost?: boolean;
+  /** Turn off automatic outbound-link events. */
+  disableOutboundLinks?: boolean;
+}
+
+export const clicsOptionsSchema = z.strictObject({
+  allowLocalhost: z.boolean().optional(),
+  disableOutboundLinks: z.boolean().optional(),
+  projectId: z.string().min(1),
+});
+
+export type ClicsAdapter = AdapterDescriptor<"clics", ClicsOptions>;
+
+export const clicsAdapterSchema = adapterDescriptorSchema(
+  "clics",
+  clicsOptionsSchema
+);
+
+/** Clics website analytics. The project ID is public in the tracker tag. */
+export const clics = (options: ClicsOptions): ClicsAdapter => ({
+  kind: "clics",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * The documented deferred tracker tag. Clics reads these attributes from
+ * `document.currentScript` and tracks history changes without a Blume hook.
+ */
+export const clicsHead = (options: ClicsOptions): HeadScript[] => {
+  const attributes: HeadScript["attributes"] = {
+    "data-project-id": options.projectId,
+    defer: true,
+    src: CLICS_SCRIPT_SRC,
+  };
+  if (options.allowLocalhost) {
+    attributes["data-allow-localhost"] = true;
+  }
+  if (options.disableOutboundLinks) {
+    attributes["data-disable-outbound-links"] = true;
+  }
+  return [{ attributes, content: null }];
+};

package/src/analytics/head.ts

@@ -2,6 +2,7 @@ import { adobeHead } from "./adobe.ts";
 import { amplitudeHead } from "./amplitude.ts";
 import { clarityHead } from "./clarity.ts";
 import { clearbitHead } from "./clearbit.ts";
+import { clicsHead } from "./clics.ts";
 import { cloudflareHead } from "./cloudflare.ts";
 import { databuddyHead } from "./databuddy.ts";
 import { fathomHead } from "./fathom.ts";
@@ -47,6 +48,7 @@ export type HeadNode =
  * the one place that branches on `kind`. A provider whose install snippet is
  * two tags (an SDK plus its init call) emits two.
  */
+// oxlint-disable-next-line complexity -- each adapter has one exhaustive, type-narrowed dispatch case
 const adapterScripts = (
   adapter: Exclude<AnalyticsAdapter, { kind: "vercel" }>
 ): HeadScript[] => {
@@ -63,6 +65,9 @@ const adapterScripts = (
     case "clearbit": {
       return clearbitHead(adapter.options);
     }
+    case "clics": {
+      return clicsHead(adapter.options);
+    }
     case "cloudflare": {
       return cloudflareHead(adapter.options);
     }

package/src/analytics/index.ts

@@ -28,6 +28,8 @@ export { clarity } from "./clarity.ts";
 export type { ClarityAdapter, ClarityOptions } from "./clarity.ts";
 export { clearbit } from "./clearbit.ts";
 export type { ClearbitAdapter, ClearbitOptions } from "./clearbit.ts";
+export { clics } from "./clics.ts";
+export type { ClicsAdapter, ClicsOptions } from "./clics.ts";
 export { cloudflare } from "./cloudflare.ts";
 export type { CloudflareAdapter, CloudflareOptions } from "./cloudflare.ts";
 export { databuddy } from "./databuddy.ts";

package/src/analytics/schema.ts

@@ -4,6 +4,7 @@ import { adobeAdapterSchema } from "./adobe.ts";
 import { amplitudeAdapterSchema } from "./amplitude.ts";
 import { clarityAdapterSchema } from "./clarity.ts";
 import { clearbitAdapterSchema } from "./clearbit.ts";
+import { clicsAdapterSchema } from "./clics.ts";
 import { cloudflareAdapterSchema } from "./cloudflare.ts";
 import { databuddyAdapterSchema } from "./databuddy.ts";
 import { fathomAdapterSchema } from "./fathom.ts";
@@ -28,6 +29,7 @@ export const analyticsAdapterSchema = z.discriminatedUnion("kind", [
   amplitudeAdapterSchema,
   clarityAdapterSchema,
   clearbitAdapterSchema,
+  clicsAdapterSchema,
   cloudflareAdapterSchema,
   databuddyAdapterSchema,
   fathomAdapterSchema,

package/src/astro/generate.ts

@@ -1818,21 +1818,26 @@ export const diagnosticWarning = (diagnostic: Diagnostic): string =>
 
 /**
  * Missing-dependency preflight: the search provider's SDK, content source
- * SDKs, the assistant backend's provider SDK, the deployment adapter's package,
- * and — since React ships with Blume while Vue/Svelte don't — any island
- * framework's Astro integration. A build fails here, before anything is
- * written, with the install command for the project's package manager —
- * otherwise Vite dies later on an opaque unresolved import from the hidden
- * runtime. Dev warns and keeps serving: only the pages and routes that import
- * the package break, and installing it is picked up on the next restart.
+ * SDKs, the assistant backend's and narration provider's SDKs, the deployment
+ * adapter's package, and — since React ships with Blume while Vue/Svelte
+ * don't — any island framework's Astro integration. A build fails here,
+ * before anything is written, with the install command for the project's
+ * package manager — otherwise Vite dies later on an opaque unresolved import
+ * from the hidden runtime. Dev warns and keeps serving: only the pages and
+ * routes that import the package break, and installing it is picked up on
+ * the next restart. Dev leaves narration's SDK out, since only a build
+ * generates the clips.
  */
 const dependencyPreflight = async (
   project: BlumeProject,
   frameworks: Set<string>
 ): Promise<string[]> => {
   const build = project.mode === "build";
+  const { config } = project;
   const diagnostic = await missingDependencyDiagnostic(
-    project.config,
+    build
+      ? config
+      : { ...config, narration: { ...config.narration, provider: null } },
     project.context.root,
     build ? "error" : "warning",
     frameworks

package/src/astro/integration.ts

@@ -7,6 +7,7 @@ import { join, relative, resolve } from "pathe";
 import { loadEnvFiles } from "../cli/env.ts";
 import type { CustomPageRoute } from "../core/custom-pages.ts";
 import { enrichDiagnostic } from "../core/diagnostics.ts";
+import { POWERED_BY_HEADERS } from "../core/powered-by.ts";
 import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import {
@@ -146,23 +147,33 @@ export const publishBuildProject = (project: BlumeProject | null): void => {
  * the Astro root recorded on `astro:config:done`. Scan diagnostics surface as
  * warnings — there is no `--strict` to honor here, and the build itself has
  * already succeeded. `null` when nothing asked for a scan.
+ *
+ * The app's runtime settings were baked in at eject, `poweredBy` among them
+ * (the integration option that registers the runtime middleware), so the
+ * artifacts follow that option rather than the config file: one switch puts
+ * `X-Powered-By` on the server-rendered responses and in `_headers` alike.
  */
 const scanForArtifacts = async (
   astroRoot: URL | null,
-  artifactsRoot: string | undefined,
+  options: Pick<BlumeIntegrationOptions, "buildArtifactsRoot" | "poweredBy">,
   logger: ArtifactLogger
 ): Promise<BlumeProject | null> => {
-  if (!(astroRoot && artifactsRoot)) {
+  if (!(astroRoot && options.buildArtifactsRoot)) {
     return null;
   }
-  const root = resolve(fileURLToPath(astroRoot), artifactsRoot);
+  const root = resolve(fileURLToPath(astroRoot), options.buildArtifactsRoot);
   // Remote sources read their tokens from the environment during the scan.
   loadEnvFiles(root);
   const project = await scanProject(root, { mode: "build" });
   for (const diagnostic of project.diagnostics) {
     logger.warn(`[${diagnostic.code}] ${diagnostic.message}`);
   }
-  return project;
+  return options.poweredBy === undefined
+    ? project
+    : {
+        ...project,
+        config: { ...project.config, poweredBy: options.poweredBy },
+      };
 };
 
 /**
@@ -317,6 +328,12 @@ export type BlumePageRoute = CustomPageRoute;
 
 export interface BlumeIntegrationOptions {
   pages: BlumePageRoute[];
+  /**
+   * Whether responses name Blume in `X-Powered-By` (see
+   * `core/powered-by.ts`): the dev server's, and the server-rendered ones of
+   * a build, through the runtime middleware. Defaults to `true`.
+   */
+  poweredBy?: boolean;
   /**
    * Page routes that have a raw-Markdown variant (the content manifest). The
    * hidden runtime leaves this out: the CLI publishes the live set through
@@ -429,6 +446,24 @@ const answerRedirects =
     res.end();
   };
 
+/**
+ * Name Blume in `X-Powered-By` on every dev response, as the deployed site
+ * does. It goes on the Node response before anything answers, so the
+ * redirects, the `public/` files Vite serves, and the rendered pages all
+ * carry it, and a page or project middleware that sets its own value
+ * replaces it.
+ */
+const identifyBlume = (
+  _req: IncomingMessage,
+  res: ServerResponse,
+  next: () => void
+): void => {
+  for (const [name, value] of Object.entries(POWERED_BY_HEADERS)) {
+    res.setHeader(name, value);
+  }
+  next();
+};
+
 /** The `.d.ts` the integration injects for the `blume:*` virtual modules. */
 const MODULE_TYPES_FILE = "modules.d.ts";
 
@@ -462,11 +497,7 @@ export const blumeIntegration = (
       "astro:build:done": async ({ dir, logger }) => {
         const project =
           registry().buildProject ??
-          (await scanForArtifacts(
-            astroRoot,
-            options.buildArtifactsRoot,
-            logger
-          ));
+          (await scanForArtifacts(astroRoot, options, logger));
         if (!project) {
           return;
         }
@@ -505,6 +536,15 @@ export const blumeIntegration = (
           entrypoint: "blume/components/icon-sprite-middleware.ts",
           order: "post",
         });
+        // Names Blume on the responses Astro renders (see
+        // components/powered-by-middleware.ts). Innermost too, so a header
+        // the project's own middleware sets wins.
+        if (options.poweredBy !== false) {
+          addMiddleware({
+            entrypoint: "blume/components/powered-by-middleware.ts",
+            order: "post",
+          });
+        }
         for (const page of options.pages) {
           injectRoute({
             entrypoint: page.entrypoint,
@@ -540,6 +580,13 @@ export const blumeIntegration = (
             route: "",
           });
         }
+        // Ahead of the redirects, so their answers carry it too.
+        if (options.poweredBy !== false) {
+          server.middlewares.stack.unshift({
+            handle: identifyBlume,
+            route: "",
+          });
+        }
       },
     },
     name: "blume",