blume 2.0.3 → 2.1.1

package/docs/discoverability/mcp.mdx

@@ -29,6 +29,8 @@ The server exposes read-only tools — `search_docs`, `get_page`, `list_pages`,
 
 `search_docs` runs its own full-text index, so it works regardless of your [search](/docs/configuration/search) provider — and even with `search: false`. The MCP server is a separate feature from on-page search.
 
+[Hidden pages](/docs/content/navigation#hidden-pages) stay out of `list_pages` and `resources/list`, and out of `search_docs` unless [`search.indexing.includeHiddenPages`](/docs/configuration/search#excluding-pages) is on, as they stay out of site search and `llms.txt`. `get_page` and `resources/read` still return a hidden page by its route: hidden isn't private, and the page is still served at its URL and as Markdown.
+
 The same tools are available over plain HTTP as the [JSON API](/docs/discoverability/json-api), for frameworks that don't speak MCP.
 
 The endpoint reads a request body only up to 64 KB and answers anything larger with `413`. A call to a tool that doesn't exist, or with `arguments` that aren't an object, gets the JSON-RPC Invalid params error (`-32602`).
@@ -49,6 +51,8 @@ Both tools also accept a `filters` object matching against the facets a site dec
 
 Every `filters` entry must match (results carry their facet values, and `list_pages` shows each page's), so a knowledge base can drive progressive-disclosure agent workflows — enumerate the enforced standards, search only within them — without any server of its own.
 
+A value matches exactly, case included, as `list_pages` shows it: `"enforced"` doesn't match a page whose `status` is `Enforced`. Facet values are strings, so a number or boolean in `filters` matches its string form (`{"priority": 1}` finds `priority: 1`), and a value of any other shape, such as a list, is ignored rather than filtering.
+
 ## Server output required
 
 The MCP server is a live endpoint (`/mcp`), so it can't run on a static build. Name a host adapter from `blume/deploy` to switch to server output:

package/docs/discoverability/metadata.mdx

@@ -34,6 +34,23 @@ seo:
 ---
 ```
 
+## Your own tags
+
+For anything Blume has no setting for, add tags under `seo.metatags` and every page carries them, custom pages and API references included. It suits site-verification tokens from Google, Bing, or Facebook, a `theme-color`, or an app banner:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  metatags: {
+    "google-site-verification": "abc123",
+    "msvalidate.01": "def456",
+    "theme-color": "#0b5fff",
+    "apple-itunes-app": "app-id=123456789",
+  },
+}
+```
+
+Each key is the tag's name and each value its content. Open Graph families (`og:`, `fb:`, `article:`, and the rest) render with `property`, as the protocol names them, and everything else with `name`. The tags Blume writes itself, listed at the top of this page, can't be set here, so a page never carries two values for one tag. The build names the setting that controls each: `og:image` comes from [`seo.og`](/docs/discoverability/open-graph) or a page's `seo.image`, and `robots` from a page's `seo.noindex`.
+
 ## Per-page overrides
 
 Override any of the other tags per page with `seo` frontmatter:

package/docs/discoverability/sitemap-and-robots.mdx

@@ -7,7 +7,7 @@ Search crawlers and AI crawlers both start from the same two files at your site
 
 ## Sitemap
 
-Blume writes a `sitemap.xml` of every indexable page at build time. It needs an absolute [`deployment.site`](/docs/deployment) and lists every page except drafts, hidden, and [`noindex`](/docs/discoverability/metadata#per-page-overrides) pages. On a [versioned](/docs/content/versioning) site, archived pages whose canonical points at their live equivalent are left out too — the live page is the one to index. On by default:
+Blume writes a `sitemap.xml` of every indexable page at build time. It needs an absolute [`deployment.site`](/docs/deployment) and lists every page except drafts, hidden, and [`noindex`](/docs/discoverability/metadata#per-page-overrides) pages, and pages whose `seo.canonical` names another URL. On a [versioned](/docs/content/versioning) site, archived pages whose canonical points at their live equivalent are left out too — the live page is the one to index. On by default:
 
 ```ts blume.config.ts lineNumbers
 seo: {

package/docs/references/api-pages.mdx

@@ -0,0 +1,74 @@
+---
+title: Hand-written API pages
+description: Document an endpoint in MDX, without a spec, and still get the method and path, a Try it panel, request samples, and pinned examples.
+---
+
+Not every API has an OpenAPI spec, and some endpoints read better written by hand. A page with `api` frontmatter documents one endpoint: its [fields](/docs/content/components#api-fields) describe the request and response, and Blume builds the rest of an [OpenAPI reference](/docs/references/openapi) page from them: the method and path at the top, a Try it panel and request samples in a column beside the content, and any [request and response examples](/docs/content/components#request-and-response-examples) pinned under them.
+
+````mdx docs/users/create.mdx lineNumbers
+---
+title: Create a user
+api: POST /workspaces/{workspaceId}/users
+---
+
+Creates a user and sends them an invite.
+
+<ParamField path="workspaceId" type="string" required>
+  The workspace to add the user to.
+</ParamField>
+
+<ParamField body="email" type="string" required placeholder="ada@example.com">
+  The user's email address.
+</ParamField>
+
+<ParamField body="role" type="string" default="member">
+  One of `owner`, `admin`, or `member`.
+</ParamField>
+
+<ResponseField name="id" type="string" required>
+  The new user's ID.
+</ResponseField>
+
+<ResponseExample>
+
+```json 201
+{ "id": "usr_8f2k", "status": "invited" }
+```
+
+</ResponseExample>
+````
+
+`api` takes an HTTP method and a path or a full URL. Path parameters are written in braces, `{workspaceId}`, and filled from the matching `path` field. A full URL, like `GET https://api.acme.com/v1/users`, is sent to as written; a path joins the site's [`api.server`](#site-defaults).
+
+## The playground and samples
+
+The page's `ParamField`s become the Try it panel's inputs, the way an operation's parameters do in a spec: `path`, `query`, and `header` fields are parameters, and `body` fields make up a JSON body, with a field's nested fields (inside its [`Expandable`](/docs/content/components#expandable)) as the properties of an object. A `type` of `string[]` is an array, and one that isn't a JSON type, such as `enum<string>`, is sent as a string. A field's `default` fills the body, and its `placeholder` is the example value the samples show. An optional body field with neither starts empty and stays out of the request until the reader fills it in.
+
+Beside the panel, the page gets request samples in cURL, JavaScript, and Python. A page with its own `RequestExample` shows that in their place.
+
+Two more frontmatter keys tune the page:
+
+- `authMethod` sets how the endpoint authenticates: `bearer`, `basic`, `key` (an API key in a header), or `none`. It overrides the site's [`api.auth`](#site-defaults).
+- `playground` sets what the page shows: `interactive` (the default) for the Try it panel and samples, `simple` for the samples only, or `none` for neither. The method, path, and any examples stay.
+
+## Site defaults
+
+`api` in `blume.config.ts` sets what every endpoint page shares:
+
+```ts blume.config.ts lineNumbers
+export default defineConfig({
+  api: {
+    server: "https://api.acme.com/v1",
+    auth: { method: "key", name: "x-api-key" },
+    playground: { proxy: true },
+  },
+});
+```
+
+- `server` is the base URL an `api` path joins.
+- `auth` is how requests authenticate unless a page sets `authMethod`: `method` is `bearer`, `basic`, `key`, or `none`, and `name` is the header an API key goes in (`x-api-key` by default). Without `auth`, pages send no credentials.
+- `playground` takes the same values as an OpenAPI reference's [playground option](/docs/references/openapi#try-it-playground): `false` hides the Try it panel on every page, and `proxy` sends its requests through a CORS proxy, a URL of your own or `true` for Blume's built-in one. The built-in proxy needs [server output](/docs/deployment#server-rendering), and only forwards to `server`'s origin and the origins of any full URLs in `api` frontmatter.
+
+The page's layout, fields, and examples are the same components as elsewhere, so the [Markdown copy](/docs/discoverability/llms-txt) of the page lists each field, and search indexes the page like any other.
+
+The frontmatter keys and component props match Mintlify's, so pages written for it keep working as they are.

package/docs/references/asyncapi.mdx

@@ -3,7 +3,7 @@ title: AsyncAPI
 description: Drop in an AsyncAPI spec and get a native event reference — one real page per send and receive operation, in your sidebar and search.
 ---
 
-Event-driven APIs use the `asyncapi()` adapter from `blume/reference`, listed under `reference` beside any [OpenAPI](/docs/references/openapi) or [GraphQL](/docs/references/graphql) adapters. It takes the same options as `openapi()` and renders with the same native renderer. Each `send`/`receive` operation becomes a real page with message payload and header schema tables, channel parameters, protocol bindings, an Authorization section derived from the spec's `securitySchemes` (server-level and operation-level, alternatives as "or" groups), and a [Try it](#try-it-for-events) message composer. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc.
+Event-driven APIs use the `asyncapi()` adapter from `blume/reference`, listed under `reference` beside any [OpenAPI](/docs/references/openapi) or [GraphQL](/docs/references/graphql) adapters. It takes the same options as `openapi()` and renders with the same native renderer. Each `send`/`receive` operation becomes a real page with message payload and header schema tables, channel parameters, protocol bindings, an Authorization section derived from the spec's `securitySchemes` (server-level and operation-level, alternatives as "or" groups, and when a channel's servers differ, which servers each scheme applies to), and a [Try it](#try-it-for-events) message composer. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc.
 
 ```ts blume.config.ts lineNumbers
 import { defineConfig } from "blume";
@@ -28,7 +28,9 @@ AsyncAPI **2.x specs are normalized to 3.x automatically** with the official Asy
 
 ## Code samples
 
-Code samples are **protocol-aware**, keyed off the operation's binding (or its servers' protocol): `wscat` and a browser `WebSocket` snippet for WebSockets, `kcat` for Kafka, `mosquitto_pub`/`mosquitto_sub` for MQTT. `codeSamples` filters that set, the same way it picks languages on `openapi()`; a protocol without a supported tool renders the message payload example alone rather than a fabricated client.
+Code samples are **protocol-aware**, keyed off the operation's binding (or its servers' protocol): `wscat` and a browser `WebSocket` snippet for WebSockets, `kcat` for Kafka, `mosquitto_pub`/`mosquitto_sub` for MQTT. `codeSamples` filters that set, the same way it picks languages on `openapi()`, and `codeSamples: false` shows none. A protocol without a supported tool renders the message payload example alone rather than a fabricated client.
+
+The `kcat` sample reads the Kafka bindings too. A channel binding's `topic` replaces the channel address as the topic name. A message binding's `key` keys the message: the sample produces `key|payload` lines with `-K '|'`, and consumes with the same flag so each key prints before its message. The key value comes from the key schema like a payload's does, so give the schema an `examples` entry. When the server declares a SASL scheme (`plain`, `scramSha256`, `scramSha512`, or `gssapi`), the sample adds the `-X` settings librdkafka needs, reading the username and password from `$KAFKA_USERNAME` and `$KAFKA_PASSWORD`. A `kafka-secure` server adds TLS.
 
 ## Shared options
 

package/docs/references/graphql.mdx

@@ -40,13 +40,13 @@ navigation: {
 
 ## 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. Code samples show the exact HTTP request (a JSON `POST` of `{ query, variables }`) in each configured language:
+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:
 
 ```ts blume.config.ts lineNumbers
 reference: [
   graphql({
     spec: "./schema.graphql",
-    codeSamples: ["curl", "js"],   // built in: curl, js, python
+    codeSamples: ["curl", "js"],   // any language openapi() offers
   }),
 ],
 ```
@@ -82,6 +82,18 @@ reference: [
 
 Query and mutation pages render an interactive panel: edit the request body (the query and variables), point it at your endpoint or a custom URL, and send — the code samples update live so what you copy is byte-for-byte what was sent. Disable it with `playground: false`. Subscription pages show the generated operation and an example event instead: subscriptions run over a stateful transport (WebSocket or SSE) that the playground's single HTTP `POST` can't speak.
 
+A schema doesn't say how its API authenticates, so the panel sends no credentials until `auth` does. It takes the same shape as [`api.auth`](/docs/references/api-pages#site-defaults) for hand-written endpoint pages: `method` is `bearer`, `basic`, `key` (an API key in a header), or `none`, and `name` is the header an API key goes in (`x-api-key` by default). Every operation page then gets an **Authorization** section, the panel a credential field that works like the [OpenAPI one](/docs/references/openapi#credentials), and the code samples a placeholder credential. A per-source `auth` overrides the adapter's:
+
+```ts blume.config.ts lineNumbers
+reference: [
+  graphql({
+    spec: "./schema.graphql",
+    endpoint: "https://api.example.com/graphql",
+    auth: { method: "bearer" },
+  }),
+],
+```
+
 If your GraphQL API doesn't allow cross-origin requests from the docs site, route sends through a CORS proxy — a URL of your own, or `true` for the built-in `/_api-proxy` endpoint (under your `basePath`, if you set one; it needs [server output](/docs/deployment#server-rendering): a host adapter such as `deployment: vercel()` from `blume/deploy`). The built-in proxy only forwards to origins your documented specs declare — each configured GraphQL `endpoint`, plus any absolute `servers[].url` from a documented [OpenAPI spec](/docs/references/openapi) — so a public docs deployment can't be aimed at other hosts. That makes `endpoint` required for a working proxy: without one, the proxy has no origin to allow for this reference and refuses every send (the build warns about this). The same body limit, header forwarding, and response headers apply as for the [OpenAPI proxy](/docs/references/openapi#try-it-playground).
 
 ```ts blume.config.ts lineNumbers

package/docs/references/meta.ts

@@ -2,6 +2,6 @@ import { defineMeta } from "blume";
 
 export default defineMeta({
   order: 7,
-  pages: ["openapi", "asyncapi", "graphql", "scalar"],
+  pages: ["openapi", "asyncapi", "graphql", "scalar", "api-pages"],
   title: "References",
 });

package/docs/references/openapi.mdx

@@ -18,7 +18,7 @@ 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. 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).
+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).
 
 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:
 
@@ -28,18 +28,30 @@ navigation: {
 }
 ```
 
+The sidebar's tag groups and the overview page's sections follow the same order: the order of the spec's top-level `tags` list, then any tag it doesn't declare, in the order operations first use it.
+
 :::note
-Operations are indexed for search by their **summary, description, tag, and endpoint** (`GET /pets/{id}`). The rendered schema tables and code samples aren't full-text indexed; search matches an operation's title, prose, section, and path, then links to its own page.
+Operations are indexed for search by their **summary, description, tag, and endpoint** (`GET /pets/{id}`). The rendered schema tables and generated code samples aren't full-text indexed; search matches an operation's title, prose, section, and path, then links to its own page. [Your own samples](#your-own-samples) are indexed like any code block, only with [`search.indexing.includeCodeBlocks`](/docs/configuration/search).
 :::
 
 ## A local spec
 
-A relative path is resolved from your project root and read at build time. Both JSON and YAML work:
+A relative path is resolved from your project root and read at build time. Both JSON and YAML work, and `blume dev` watches the file, along with any local [overlays](#overlays), so the reference updates when you save the spec:
 
 ```ts blume.config.ts lineNumbers
 reference: [openapi({ spec: "./openapi.yaml" })],
 ```
 
+## OpenAPI 3.2
+
+OpenAPI 3.2 specs render as written. A `query` operation, for the HTTP `QUERY` method (a safe request that carries a body), gets a page, Try it, and code samples like any other method. Fields 3.2 adds that Blume doesn't show, such as a tag's or a response's `summary`, are ignored rather than rejected. Some 3.2 additions don't render yet:
+
+- `additionalOperations`, for methods a path item doesn't name directly (like `COPY`): those operations are left out, with a `BLUME_OPENAPI_UNSUPPORTED` [warning](#spec-warnings).
+- `in: querystring` parameters: they get no row in the parameter table, no Try it input, and no place in the code samples, with the same warning.
+- `itemSchema`, the schema of each item in a streamed body (`text/event-stream`, `application/jsonl`): the page shows no schema for that body unless `schema` is set beside it.
+- Examples written with `dataValue` or `serializedValue` in place of `value`: the page doesn't show them.
+- Nested tags (`parent`) and tag `kind`: tags stay one flat list in the sidebar and the overview.
+
 ## Route
 
 `route` controls where the reference mounts — the overview page and the prefix for every operation route (and the route you point a navigation tab at):
@@ -55,18 +67,78 @@ reference: [
 
 ## Code samples and schemas
 
-`codeSamples` picks which languages render per operation (built in: `curl`, `js`, `python`); `expandSchemas` starts nested schema rows expanded rather than collapsed:
+`codeSamples` picks which languages render per operation, in the order you list them. It defaults to `["curl", "js", "python"]`, and `false` or an empty list shows none. `expandSchemas` starts nested schema rows expanded rather than collapsed:
 
 ```ts blume.config.ts lineNumbers
 reference: [
   openapi({
     spec: "./openapi.yaml",
-    codeSamples: ["curl", "js"],
+    codeSamples: ["curl", "python", "go", "java", "csharp"],
     expandSchemas: true,
   }),
 ],
 ```
 
+Every sample is plain, copy-pasteable code for the request, written with the language's standard or most common HTTP client:
+
+| Id           | Language   | Client              | Also accepts          |
+| ------------ | ---------- | ------------------- | --------------------- |
+| `curl`       | cURL       | `curl`              | `bash`, `sh`, `shell` |
+| `python`     | Python     | `requests`          | `py`                  |
+| `js`         | JavaScript | `fetch`             | `javascript`          |
+| `node`       | Node.js    | `axios`             | `nodejs`, `node.js`   |
+| `typescript` | TypeScript | `fetch`             | `ts`                  |
+| `php`        | PHP        | the curl extension  |                       |
+| `go`         | Go         | `net/http`          | `golang`              |
+| `java`       | Java       | `java.net.http`     |                       |
+| `ruby`       | Ruby       | `net/http`          | `rb`                  |
+| `powershell` | PowerShell | `Invoke-RestMethod` | `ps1`                 |
+| `swift`      | Swift      | `URLSession`        |                       |
+| `csharp`     | C#         | `HttpClient`        | `c#`, `cs`            |
+| `dotnet`     | .NET       | RestSharp           | `.net`, `dot-net`     |
+| `c`          | C          | libcurl             |                       |
+| `cpp`        | C++        | cpr                 | `c++`                 |
+| `kotlin`     | Kotlin     | OkHttp              | `kt`                  |
+| `rust`       | Rust       | reqwest             | `rs`                  |
+| `dart`       | Dart       | `package:http`      | `flutter`             |
+
+Each value is quoted by its own language's rules, so a header like `If-Match: "33a64df5"` or a body with a `$` in it reaches the API as written.
+
+Schema tables follow the way the data travels, as the examples do: a request body leaves out `readOnly` properties, which the server sets, and a response leaves out `writeOnly` ones, which it never returns. A [webhook or callback](#webhooks-and-callbacks) body is a request your API sends, so it reads like a response.
+
+### Your own samples
+
+To show your SDK instead of a raw HTTP call, add `x-codeSamples` to an operation in the spec. It's the extension Redocly defined, and Speakeasy and Stainless can write it for you. Each entry takes a `lang`, the `source`, and an optional `label`:
+
+```yaml openapi.yaml lineNumbers
+paths:
+  /plants:
+    get:
+      x-codeSamples:
+        - lang: typescript
+          label: SDK
+          source: |
+            const plants = await planter.plants.list();
+        - lang: bash
+          label: CLI
+          source: |
+            planter list
+```
+
+These samples render as their own tabs, ahead of the generated ones, and stay as written when readers change the [Try it](#try-it-playground) form. The older `x-code-samples` spelling works too. To show only your own samples, set `codeSamples: false`. Unlike the generated samples, they're also in the operation page's Markdown copy, so `llms-full.txt`, the MCP server, and the assistant see your SDK calls.
+
+A `source` can also be a `$ref` to a file that holds the sample's code, the way Redocly describes keeping samples in files of their own. Blume reads the file relative to the spec, fetching it when the spec is a URL. A `$ref` it can't read, or one that points inside a document (`#/…`), leaves that sample out with a [`BLUME_OPENAPI_CODE_SAMPLE_REF`](#spec-warnings) warning:
+
+```yaml openapi.yaml lineNumbers
+paths:
+  /plants:
+    get:
+      x-codeSamples:
+        - lang: go
+          source:
+            $ref: ./code_samples/go/list_plants.go
+```
+
 ## 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).
@@ -100,11 +172,11 @@ 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 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.
 
 ## 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` (used for the sidebar and to derive its route), or set an explicit `route`:
+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`:
 
 ```ts blume.config.ts lineNumbers
 reference: [
@@ -157,6 +229,36 @@ reference: [
 
 A [`scalar()`](/docs/references/scalar) embed takes only `noindex` of these — it already sits outside Blume's search and `llms.txt`, so the two `include*` settings have nothing to act on there.
 
+## Overlays
+
+When the spec is generated by another tool or owned by another team, keep your docs changes out of it with an [OpenAPI Overlay](https://spec.openapis.org/overlay/latest.html): a separate file that lists changes to make to the spec, such as clearer descriptions, a public server URL, or internal operations removed. List overlays beside `spec`. Each is a local path or an `http(s)` URL, and they apply in order:
+
+```ts blume.config.ts lineNumbers
+reference: [
+  openapi({
+    spec: "./openapi.json",
+    overlays: ["./overlays/public.yaml"],
+  }),
+],
+```
+
+```yaml overlays/public.yaml lineNumbers
+overlay: 1.1.0
+info:
+  title: Public docs
+  version: 1.0.0
+actions:
+  - target: $.paths.*[?@['x-internal'] == true]
+    remove: true
+  - target: $.info
+    update:
+      description: The public Acme API.
+```
+
+Each action's `target` is a [JSONPath](https://www.rfc-editor.org/rfc/rfc9535) expression. `update` merges into every node it selects: objects merge key by key, arrays gain the new items, and other values are replaced. `copy` merges in a node from elsewhere in the spec (Overlay 1.1), and `remove: true` deletes the targets. Overlay Specification 1.0 and 1.1 are both supported.
+
+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.
+
 ## 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.
@@ -168,6 +270,45 @@ The OpenAPI semantics carry over as written:
 - An empty `{}` entry means auth is **optional** for that operation, and the section says so.
 - OAuth2 scopes are listed per scheme; scheme `description`s from `components.securitySchemes` render inline.
 
+## Webhooks and callbacks
+
+Your API's outgoing requests get documented too. Each [webhook](https://spec.openapis.org/oas/v3.1.0#oas-webhooks) in the spec's top-level `webhooks` gets its own page, like an operation: filed under its first tag, or a **Webhooks** group when it has none. The page shows the payload's schema and the responses your endpoint should send back. In place of the Try it panel and code samples, the rail shows an example payload, since your API sends this request rather than serving it. A webhook page lists only the `security` the webhook declares itself: the spec's root `security` guards calls to your API, so it doesn't apply to requests the API sends. A webhook that's a `$ref` to a shared path item is left out, with a [`BLUME_OPENAPI_REF_PATH_ITEM`](#spec-warnings) warning.
+
+```yaml openapi.yaml lineNumbers
+webhooks:
+  newPet:
+    post:
+      summary: New pet added
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Pet"
+      responses:
+        "200":
+          description: Return a 200 to acknowledge the event.
+```
+
+A 3.0 spec's webhooks under the `x-webhooks` extension become `webhooks` when Blume upgrades the spec to 3.1. A spec already at 3.1 or later isn't upgraded, so webhooks it still keeps under `x-webhooks` render nothing, with a [`BLUME_OPENAPI_X_WEBHOOKS`](#spec-warnings) warning: rename the field to `webhooks`.
+
+An operation's [`callbacks`](https://spec.openapis.org/oas/v3.1.0#callback-object), the requests your API makes back to a URL the caller supplied, render in a **Callbacks** section on that operation's page. Each shows the URL expression (`{$request.body#/callbackUrl}`), its method, its parameters (a signature header, say), its request body, and its expected responses. Callbacks declared under `components.callbacks` and referenced with `$ref` work the same way.
+
+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.
+
+## 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:
+
+| Code | What's wrong |
+| --- | --- |
+| `BLUME_OPENAPI_PATH_PARAMETER_MISSING` | A `{name}` in an operation's path has no `in: path` parameter of that name, so the page has no input for it, and Try it and the code samples send the placeholder as literal text. |
+| `BLUME_OPENAPI_PATH_PARAMETER_UNUSED` | An `in: path` parameter has no `{name}` in the path, so the value Try it asks for never reaches the URL. |
+| `BLUME_OPENAPI_UNKNOWN_SECURITY_SCHEME` | A `security` requirement names a scheme that `components.securitySchemes` doesn't define, so the [Authorization](#authorization) section can't describe it and requests send no credential for it. |
+| `BLUME_OPENAPI_UNSUPPORTED` | The spec uses an [OpenAPI 3.2](#openapi-32) feature Blume doesn't render yet: `additionalOperations`, which leaves those operations out, or an `in: querystring` parameter, which leaves the query string out of the page, Try it, and the code samples. |
+| `BLUME_OPENAPI_CODE_SAMPLE_REF` | An `x-codeSamples` entry's `source` is a `$ref` Blume can't read, or one that points inside a document, so that [sample](#your-own-samples) is left out. |
+| `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. |
+
 ## 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/docs/references/scalar.mdx

@@ -33,6 +33,8 @@ reference: [
 ],
 ```
 
+[Overlays](/docs/references/openapi#overlays) work here too: list `overlays` beside `spec`, or on each source. The embed then inlines the spec with the overlays applied, so a remote spec with overlays is fetched at build time rather than from the browser. If an overlay doesn't apply, the build warns and leaves that page out rather than embed the spec without it.
+
 A Scalar embed and native pages can sit side by side in the list — an `openapi()` adapter for the current API and a `scalar()` adapter for a legacy one, say — as long as their routes differ. Like every reference, the embed doesn't add a header tab on its own; point a [navigation tab](/docs/content/navigation#tabs) at its route to surface it.
 
 ## What the embed doesn't do
@@ -43,7 +45,7 @@ The embed does follow Blume's light/dark toggle: it's pinned to the page's theme
 
 ## Passing Scalar options
 
-`theme` is the one option most people reach for, but Scalar supports many more. Every key you pass to `scalar()` beyond `spec`, `sources`, `route`, and `theme` is forwarded verbatim as [Scalar configuration](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) to the embedded reference — Blume doesn't gate the keys, so anything Scalar accepts flows through (JSON values only, since the configuration is inlined into the generated page):
+`theme` is the one option most people reach for, but Scalar supports many more. Every key you pass to `scalar()` beyond `spec`, `overlays`, `sources`, `route`, and `theme` is forwarded verbatim as [Scalar configuration](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) to the embedded reference — Blume doesn't gate the keys, so anything Scalar accepts flows through (JSON values only, since the configuration is inlined into the generated page):
 
 ```ts blume.config.ts lineNumbers
 reference: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "2.0.3",
+  "version": "2.1.1",
   "description": "The open-source docs framework for humans and agents.",
   "keywords": [
     "agents",
@@ -54,10 +54,24 @@
       "types": "./dist/types/analytics/index.d.ts",
       "default": "./src/analytics/index.ts"
     },
+    "./captcha": {
+      "types": "./dist/types/captcha/index.d.ts",
+      "default": "./src/captcha/index.ts"
+    },
+    "./captcha/*": "./src/captcha/*",
+    "./consent": {
+      "types": "./dist/types/consent/index.d.ts",
+      "default": "./src/consent/index.ts"
+    },
     "./deploy": {
       "types": "./dist/types/deploy/adapters/index.d.ts",
       "default": "./src/deploy/adapters/index.ts"
     },
+    "./ratelimit": {
+      "types": "./dist/types/ratelimit/index.d.ts",
+      "default": "./src/ratelimit/index.ts"
+    },
+    "./ratelimit/*": "./src/ratelimit/*",
     "./reference": {
       "types": "./dist/types/reference/index.d.ts",
       "default": "./src/reference/index.ts"
@@ -101,16 +115,16 @@
     "@astrojs/markdown-satteri": "^0.4.1",
     "@astrojs/mdx": "^8.0.1",
     "@astrojs/node": "^11.1.5",
-    "@astrojs/react": "^6.0.5",
-    "@astrojs/vercel": "^11.0.10",
+    "@astrojs/react": "^7.0.0",
+    "@astrojs/vercel": "^11.0.11",
     "@clack/prompts": "^1.8.0",
     "@iconify-json/lucide": "^1.2.131",
     "@iconify/types": "^2.0.0",
     "@iconify/utils": "^3.1.7",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@orama/orama": "^3.1.18",
-    "@pierre/diffs": "^1.4.2",
-    "@scalar/astro": "^0.4.21",
+    "@pierre/diffs": "^1.5.1",
+    "@scalar/astro": "^0.4.26",
     "@scalar/openapi-parser": "^0.29.1",
     "@scalar/openapi-types": "^0.9.5",
     "@shikijs/transformers": "^4.4.3",
@@ -122,12 +136,11 @@
     "@vercel/analytics": "^2.0.1",
     "ai": "^7.0.99",
     "astro": "^7.3.2",
-    "babel-plugin-react-compiler": "^1.0.0",
     "chokidar": "^5.0.0",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "cross-spawn": "^7.0.6",
-    "dompurify": "^3.4.15",
+    "dompurify": "^3.4.16",
     "dotenv": "^17.4.2",
     "epub-gen-memory": "^1.1.2",
     "es-module-lexer": "^3.0.2",
@@ -137,7 +150,8 @@
     "gray-matter": "^4.0.3",
     "html-escaper": "^3.0.3",
     "jiti": "^2.7.0",
-    "js-yaml": "^5.4.1",
+    "js-yaml": "^5.4.2",
+    "jsonpath-rfc9535": "^1.3.0",
     "katex": "^0.18.7",
     "markdown-table": "^3.0.4",
     "marked": "^18.0.12",
@@ -150,6 +164,7 @@
     "nanotar": "^0.3.0",
     "node-html-parser": "^9.0.4",
     "openapi-sampler": "^1.7.5",
+    "oxc-transform-react": "^0.145.0",
     "p-limit": "^7.3.2",
     "p-map": "^7.0.7",
     "p-retry": "^8.0.1",
@@ -179,7 +194,11 @@
     "zod": "^4.6.2"
   },
   "devDependencies": {
+    "@ai-sdk/anthropic": "^4.0.68",
+    "@ai-sdk/google": "^4.0.82",
+    "@ai-sdk/openai": "^4.0.78",
     "@ai-sdk/openai-compatible": "^3.0.48",
+    "@ai-sdk/xai": "^5.0.10",
     "@asyncapi/converter": "^2.0.2",
     "@mixedbread/sdk": "^0.77.0",
     "@notionhq/client": "^5.26.0",
@@ -201,7 +220,11 @@
     "typesense": "^3.0.6"
   },
   "peerDependencies": {
+    "@ai-sdk/anthropic": "^4.0.0",
+    "@ai-sdk/google": "^4.0.0",
+    "@ai-sdk/openai": "^4.0.0",
     "@ai-sdk/openai-compatible": "^3.0.0",
+    "@ai-sdk/xai": "^5.0.0",
     "@astrojs/cloudflare": "^14.0.0",
     "@astrojs/netlify": "^8.0.0",
     "@astrojs/svelte": "^9.0.0",
@@ -217,9 +240,21 @@
     "typesense": "^3.0.0"
   },
   "peerDependenciesMeta": {
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/google": {
+      "optional": true
+    },
+    "@ai-sdk/openai": {
+      "optional": true
+    },
     "@ai-sdk/openai-compatible": {
       "optional": true
     },
+    "@ai-sdk/xai": {
+      "optional": true
+    },
     "@astrojs/cloudflare": {
       "optional": true
     },

package/skills/blume/SKILL.md

@@ -61,11 +61,14 @@ It bumps `blume` in `package.json`, installs, and lists every config change stil
 
 To move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume, the user runs `npx blume migrate [source] --codex` (or `--claude`) from that project, which opens an agent on the `blume-migrate` skill. When you are that agent, or the user asks you to migrate directly, follow `skills/blume-migrate/SKILL.md` in the installed package instead of this file.
 
+Every build publishes a generated agent skill for the site at `/skill.md` (`agents.skillMd`). To write a richer one from the docs, the user runs `blume skill --codex` (or `--claude`), which opens an agent on the `blume-write-skill` skill. When you are that agent, or the user asks you to write the site's skill directly, follow `skills/blume-write-skill/SKILL.md` in the installed package.
+
 ## What's included
 
 - **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).
 - **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`.