blume 1.6.0 → 1.6.2

package/dist/types/core/config-input.d.ts

@@ -690,6 +690,15 @@ export interface McpConfig {
  * hosted MCP server.
  */
 export interface AiConfig {
+    /**
+     * The JSON docs API — the REST twin of the MCP tools. Serves the page index
+     * (`/api/docs/pages.json`), each page as JSON (`/api/docs/pages/{route}.json`),
+     * and the navigation tree (`/api/docs/navigation.json`) as prerendered
+     * files, plus full-text search (`/api/docs/search?q=`) on server output,
+     * all described by an OpenAPI document at `/openapi.json`. Errors are RFC
+     * 9457 problem details. Defaults to `true`; set `false` to publish none of it.
+     */
+    api?: boolean;
     /** The Ask AI chat assistant. */
     ask?: AskConfig;
     /**

package/dist/types/core/data.d.ts

@@ -82,6 +82,11 @@ export interface BlumeRoute {
     alternates: RouteAlternate[];
     /** Astro collection the entry renders through (`"docs"` | `"staged"`). */
     collection: string;
+    /**
+     * Meta description as the page head renders it (`seo.description` over the
+     * front matter `description`), or `null` when the page declares neither.
+     */
+    description: string | null;
     draft: boolean;
     /** "Edit this page" URL, or `null` when no repo/source provides one. */
     editUrl: string | null;
@@ -138,6 +143,8 @@ export interface BlumeDataConfig {
      */
     discovery: {
         agentReadability: boolean;
+        /** Whether the JSON docs API and its `/openapi.json` are published. */
+        api: boolean;
         llmsTxt: boolean;
         sitemap: boolean;
     };
@@ -176,7 +183,11 @@ export interface BlumeDataConfig {
      * kept out of this snapshot, which pages serialize into HTML.
      */
     og: {
-        /** Card subtitle: `seo.og.description` (`false` omits it) over the site description. */
+        /**
+         * Site-wide card subtitle: `seo.og.description` (`false` omits it) over
+         * the site description. A page with its own description shows that
+         * instead; this is the fallback for pages without one.
+         */
         description?: string;
         enabled: boolean;
         /** Inlined SVG brand mark; `false` renders the card without any mark. */

package/dist/types/core/i18n-ui.d.ts

@@ -17,6 +17,7 @@ declare const uiStringsObject: z.ZodObject<{
         copyClaudeCode: z.ZodDefault<z.ZodString>;
         copyCode: z.ZodDefault<z.ZodString>;
         copyCodex: z.ZodDefault<z.ZodString>;
+        copyFailed: z.ZodDefault<z.ZodString>;
         copyMarkdown: z.ZodDefault<z.ZodString>;
         copyServerUrl: z.ZodDefault<z.ZodString>;
         edit: z.ZodDefault<z.ZodString>;
@@ -78,6 +79,7 @@ declare const uiStringsObject: z.ZodObject<{
         toggleTheme: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     notFound: z.ZodPrefault<z.ZodObject<{
+        api: z.ZodDefault<z.ZodString>;
         description: z.ZodDefault<z.ZodString>;
         home: z.ZodDefault<z.ZodString>;
         llms: z.ZodDefault<z.ZodString>;
@@ -129,6 +131,7 @@ export declare const uiStringsSchema: z.ZodPrefault<z.ZodObject<{
         copyClaudeCode: z.ZodDefault<z.ZodString>;
         copyCode: z.ZodDefault<z.ZodString>;
         copyCodex: z.ZodDefault<z.ZodString>;
+        copyFailed: z.ZodDefault<z.ZodString>;
         copyMarkdown: z.ZodDefault<z.ZodString>;
         copyServerUrl: z.ZodDefault<z.ZodString>;
         edit: z.ZodDefault<z.ZodString>;
@@ -190,6 +193,7 @@ export declare const uiStringsSchema: z.ZodPrefault<z.ZodObject<{
         toggleTheme: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     notFound: z.ZodPrefault<z.ZodObject<{
+        api: z.ZodDefault<z.ZodString>;
         description: z.ZodDefault<z.ZodString>;
         home: z.ZodDefault<z.ZodString>;
         llms: z.ZodDefault<z.ZodString>;

package/dist/types/core/schema.d.ts

@@ -260,6 +260,7 @@ export declare const searchProviders: readonly ["orama", "pagefind", "flexsearch
 /** Ask AI backends. `gateway` (default) routes through the Vercel AI Gateway. */
 export declare const askAiProviders: readonly ["gateway", "openrouter", "llmgateway", "inkeep", "openai-compatible"];
 declare const aiConfigSchema: z.ZodObject<{
+    api: z.ZodDefault<z.ZodBoolean>;
     ask: z.ZodOptional<z.ZodObject<{
         apiKeyEnv: z.ZodOptional<z.ZodString>;
         baseUrl: z.ZodOptional<z.ZodURL>;
@@ -477,6 +478,7 @@ declare const openapiSourceSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     noindex: z.ZodDefault<z.ZodBoolean>;
     route: z.ZodOptional<z.ZodString>;
+    seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
     spec: z.ZodString;
 }, z.core.$strict>;
 export type OpenApiSource = z.input<typeof openapiSourceSchema>;
@@ -492,12 +494,14 @@ declare const graphqlSourceSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     noindex: z.ZodDefault<z.ZodBoolean>;
     route: z.ZodOptional<z.ZodString>;
+    seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
     spec: z.ZodString;
     endpoint: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type GraphqlSource = z.input<typeof graphqlSourceSchema>;
 export declare const blumeConfigSchema: z.ZodObject<{
     ai: z.ZodPrefault<z.ZodObject<{
+        api: z.ZodDefault<z.ZodBoolean>;
         ask: z.ZodOptional<z.ZodObject<{
             apiKeyEnv: z.ZodOptional<z.ZodString>;
             baseUrl: z.ZodOptional<z.ZodURL>;
@@ -598,6 +602,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
             noindex: z.ZodDefault<z.ZodBoolean>;
             route: z.ZodOptional<z.ZodString>;
+            seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
         }, z.core.$strict>>>;
         spec: z.ZodOptional<z.ZodString>;
@@ -795,6 +800,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
             noindex: z.ZodDefault<z.ZodBoolean>;
             route: z.ZodOptional<z.ZodString>;
+            seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
             endpoint: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
@@ -942,6 +948,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
             noindex: z.ZodDefault<z.ZodBoolean>;
             route: z.ZodOptional<z.ZodString>;
+            seoDescriptionSuffix: z.ZodDefault<z.ZodBoolean>;
             spec: z.ZodString;
         }, z.core.$strict>>>;
         spec: z.ZodOptional<z.ZodString>;

package/dist/types/core/types.d.ts

@@ -347,6 +347,12 @@ export interface RouteManifestEntry {
     /** Adapter-supplied "edit this page" URL (non-filesystem sources). */
     editUrl?: string;
     title: string;
+    /**
+     * The page's meta description as the head renders it: `seo.description`
+     * over the front matter `description`. Feeds the generated OG card's
+     * subtitle, so a shared link's image and its `og:description` agree.
+     */
+    description?: string;
     contentType: string;
     hidden: boolean;
     draft: boolean;

package/dist/types/openapi/references.d.ts

@@ -47,6 +47,11 @@ export interface ReferenceSource {
     includeInSearch: boolean;
     /** Whether generated pages emit noindex metadata and stay out of the sitemap. */
     noindex: boolean;
+    /**
+     * Whether operation meta descriptions end with the generated English
+     * "Reference for …" sentence, or carry the spec's own prose alone.
+     */
+    seoDescriptionSuffix: boolean;
     /** Local path or `http(s)` URL, verbatim from config. */
     spec: string;
     /**

package/docs/07-faq.mdx

@@ -87,14 +87,14 @@ We reported it upstream in [oxc-project/oxc#24096](https://github.com/oxc-projec
 
 Patch oxfmt so it preserves the line break that sits directly against a `:::` fence. Blume ships the same fix in its own repo, and you can apply it in any project.
 
-1. Save the patch as `patches/oxfmt@0.61.0.patch`:
-
-   ```diff patches/oxfmt@0.61.0.patch
-   diff --git a/dist/markdown-ZuiQU4Xe.js b/dist/markdown-ZuiQU4Xe.js
-   index 566b9e6d27f36061d64b93736e238e871e1ee2b2..82d0595acc010807c2939fc4a1717dde887a8555 100644
-   --- a/dist/markdown-ZuiQU4Xe.js
-   +++ b/dist/markdown-ZuiQU4Xe.js
-   @@ -4875,7 +4875,43 @@ function lu(e, t, r) {
+1. Save the patch as `patches/oxfmt@0.66.0.patch`:
+
+   ```diff patches/oxfmt@0.66.0.patch
+   diff --git a/dist/markdown-BgZGxhM2.js b/dist/markdown-BgZGxhM2.js
+   index 859231f9387a50df16419bc22b5268c4e446ddbc..dcc0ffda6f71adb27a03e3918a3db6fc7a58ffe9 100644
+   --- a/dist/markdown-BgZGxhM2.js
+   +++ b/dist/markdown-BgZGxhM2.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": {
@@ -146,7 +146,7 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    ```json package.json
    {
      "patchedDependencies": {
-       "oxfmt@0.61.0": "patches/oxfmt@0.61.0.patch"
+       "oxfmt@0.66.0": "patches/oxfmt@0.66.0.patch"
      }
    }
    ```

package/docs/advanced/api-reference.mdx

@@ -139,6 +139,15 @@ openapi: {
 - `includeInLlms: false` keeps them out of both `llms.txt` files.
 - `noindex: true` adds crawler noindex metadata and removes the pages from the sitemap.
 
+Each operation page's meta description is the operation's own `description` (or `summary`), followed by a generated sentence naming the endpoint — "Reference for the `GET /pets` endpoint in the Petstore API." — so a spec of terse one-line summaries still ships a distinct, snippet-length description per page. That sentence is English. On a site whose spec prose is written in another language, set `seoDescriptionSuffix: false` on the source to drop it and describe each page with the authored prose alone; an operation with neither a `description` nor a `summary` falls back to its title (`GET /pets`), so no page ships an empty description:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
+}
+```
+
 With the [Scalar renderer](#the-scalar-renderer), only `noindex` applies — a Scalar-rendered reference already sits outside Blume's search and `llms.txt`, so the two `include*` settings have nothing to act on there.
 
 ## Authorization
@@ -202,7 +211,7 @@ AsyncAPI **2.x specs are normalized to 3.x automatically** with the official Asy
 
 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 the `openapi` block; a protocol without a supported tool renders the message payload example alone rather than a fabricated client.
 
-Everything documented above carries over, [`playground`](#try-it-for-events) included: `route`, `sources` with `label`/`route`, `expandSchemas`, the [per-source indexing](#per-source-indexing) flags, and search indexing by operation summary and tag.
+Everything documented above carries over, [`playground`](#try-it-for-events) included: `route`, `sources` with `label`/`route`, `expandSchemas`, the [per-source indexing](#per-source-indexing) flags (`seoDescriptionSuffix` too — the generated sentence names the channel and action instead of an endpoint), and search indexing by operation summary and tag.
 
 Setting `renderer: "scalar"` opts back into the embedded Scalar SPA, where — as with OpenAPI — only `noindex` applies. Scalar has no AsyncAPI playground of its own; its embed auto-detects the document type and renders channels, operations, messages, and a Models section, so that swap trades the composer away.
 

package/docs/advanced/custom-pages.mdx

@@ -272,7 +272,9 @@ import data from "blume:data";
 
 ## 404 page
 
-Blume ships a default **not found** page out of the box: a centered "404" message wrapped in the site chrome (header, search, theme), served for any unmatched URL. `blume build` writes it to `404.html`, which static hosts serve automatically, and `blume dev` shows it for unknown routes.
+Blume ships a default **not found** page out of the box: a centered "404" message wrapped in the site chrome (header, search, theme), served for any unmatched URL. `blume build` writes it to `404.html`, which static hosts serve automatically, and `blume dev` shows it for unknown routes. Under the message, a **Where to look next** list links every top-level section plus the `sitemap.xml` and [`llms.txt`](/docs/configuration/ai#llmstxt) indexes when they exist, so a reader — or an agent that followed a stale URL — has a way back.
+
+The page also has a Markdown twin at `/404.md` and a JSON twin at `/404.json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details) with the same recovery links (absolute URLs once [`deployment.site`](/docs/deployment) is set), plus the [`openapi.json`](/docs/configuration/ai#json-api) description when the JSON API is on. On a [Vercel server build](/docs/deployment#server-rendering), a request for a missing page that sends [`Accept: text/markdown`](/docs/configuration/ai#content-negotiation), or asks for a `.md` URL no page backs, gets the Markdown body with the `404` status instead of the HTML shell; one that sends `Accept: application/json`, or asks for a `.json` URL no file backs, gets the problem document — so an agent never has to parse a page of chrome to learn where to go next.
 
 To replace it with your own, add a `pages/404.astro`. It owns the `/404` route the same way `pages/changelog.astro` takes over the changelog — your page wins and the default is dropped. Build it like any other custom page, in `PageLayout` or `RootLayout`:
 

package/docs/advanced/graphql.mdx

@@ -66,7 +66,7 @@ graphql: {
 }
 ```
 
-Each source takes the same per-source controls as the [OpenAPI block](/docs/advanced/api-reference): `includeInSearch`, `includeInLlms`, and `noindex`.
+Each source takes the same [per-source controls](/docs/advanced/api-reference#per-source-indexing) as the OpenAPI block: `includeInSearch`, `includeInLlms`, `noindex`, and `seoDescriptionSuffix` (here the generated sentence names the query, mutation, or type — "Reference for the `pets` query in the GraphQL API.").
 
 ## Try it playground
 

package/docs/configuration/ai.mdx

@@ -1,9 +1,9 @@
 ---
 title: AI
-description: Make your docs machine-readable with llms.txt, add an optional in-page Ask AI assistant, and expose a hosted MCP server for coding agents.
+description: Make your docs machine-readable with llms.txt and a JSON API described by OpenAPI, add an optional in-page Ask AI assistant, and expose a hosted MCP server for coding agents.
 ---
 
-Blume has a few AI features: machine-readable docs for external tools (`llms.txt`, on by default), an in-page **Ask AI** assistant, and a hosted **MCP server** for coding agents. Ask AI and MCP are opt-in, and static docs stay fully static until you turn a feature on.
+Blume has a few AI features: machine-readable docs for external tools (`llms.txt` and a [JSON API](#json-api) with an OpenAPI description, both on by default), an in-page **Ask AI** assistant, and a hosted **MCP server** for coding agents. Ask AI and MCP are opt-in, and static docs stay fully static until you turn a feature on.
 
 ## llms.txt
 
@@ -81,6 +81,8 @@ The `.md` variant _downlevels_ components to plain Markdown for consumers that c
 
 Agents don't need to know the `.md` convention: requesting a page's own URL with an [`Accept: text/markdown`](https://acceptmarkdown.com) header serves the Markdown variant at the same address, with `Vary: Accept` so caches keep the two apart. The dev server honors the header out of the box, and a [Vercel or Cloudflare server build](/docs/deployment#server-rendering) wires the same negotiation into the deploy automatically — routing rules on Vercel, a generated Worker on Cloudflare — no configuration needed. The homepage always negotiates, even when it's a custom landing page rather than a content page: its Markdown mirror falls back to the [`llms.txt`](#llmstxt) index, so an agent asking the site root for Markdown gets the machine-readable map of the site. Markdown responses also carry an `x-markdown-tokens` header — an estimated token count (~4 characters per token), following the convention of [Cloudflare's Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) — on every surface where Blume controls response headers: the dev server, server-rendered responses, and the negotiated homepage on Vercel and Cloudflare. Other deploy targets serve prerendered pages from a static layer with no request-time hook, so agents there fetch the `.md` URL directly; the [agent readability manifest](#agent-readability) advertises `contentNegotiation` only on deployments that honor the header.
 
+Missing pages negotiate too. Every build emits a Markdown [404 page](/docs/advanced/custom-pages#404-page) at `/404.md` — the not-found message followed by recovery links to every top-level section, the sitemap, and `llms.txt` — and on Vercel a request for a nonexistent URL that prefers Markdown, or any `.md` URL with no page behind it, gets that body with a real `404` status rather than the HTML shell.
+
 ### Custom component serializers
 
 Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes, with the page's `frontmatter` in scope), its `children` (already downleveled to Markdown), and the page's `frontmatter` data, and returns the replacement — or `null` to leave the JSX as-is:
@@ -109,6 +111,8 @@ Serializers live in `blume.config.ts`, not `components.tsx`: the config file is
 
 Every page carries a **Copy as Markdown** action — in the [page actions](/docs/content/navigation#page-actions) beneath the table of contents — that copies the page's raw Markdown to the clipboard. It's the same source served at the [`.md` URL](#raw-markdown) above, ready to paste into an LLM, an issue, or your notes. It's available on every page, in dev and production, with no configuration.
 
+Where the Clipboard API is unavailable or the browser denies it — in-app browsers, WebViews, insecure origins — the action falls back to the legacy copy command, and if nothing lands on the clipboard the button reports **Copy failed** (localized via `actions.copyFailed`) rather than staying silent. The same fallback backs every copy button Blume renders.
+
 ## Open in chat
 
 The **Open in chat** action opens the current page in an AI assistant — v0, ChatGPT, Claude, T3 Chat, Scira, or Cursor — pre-filled with a prompt that points it at the page's raw Markdown so it can answer questions about what you're reading:
@@ -360,6 +364,52 @@ A static build with `ai.mcp.enabled` fails fast with a message telling you to se
 claude mcp add --transport http my-docs https://docs.example.com/mcp
 ```
 
+## JSON API
+
+Every Blume site also serves its docs as a small read-only **JSON API** — the REST twin of the [MCP server](#mcp-server)'s tools, over the same page snapshot, for agents and function-calling frameworks that speak plain HTTP rather than MCP. It's on by default and needs no configuration:
+
+| Endpoint | Returns |
+| --- | --- |
+| `/api/docs/pages.json` | Every page with its route, title, description, content type, locale, facets, and the URLs of its rendered, Markdown, and JSON forms. |
+| `/api/docs/pages/{route}.json` | One page: its index entry plus the agent Markdown (the same body `get_page` returns). `{route}` is the page route without the leading slash, `index` for home. |
+| `/api/docs/navigation.json` | The navigation tree — header tabs and the sidebar hierarchy. |
+| `/api/docs/search?q=` | Full-text search, with the same `limit`, `contentTypes`, `locale`, `version`, and `filters[key]` scoping as `search_docs`. Server output only. |
+| `/openapi.json` | The OpenAPI 3.1 description of the whole machine-readable surface. |
+
+The page index, per-page documents, and navigation are prerendered, so a static site serves them as files from any host. Search is a live endpoint and exists only under [server output](/docs/deployment#server-rendering), where it runs the same index `search_docs` does. Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details (`application/problem+json`) with a stable `code`, a `detail`, and a `resolution` hint telling the agent where to go next — a missing page, a blank search query, or on server output any `/api/…` URL no endpoint answers:
+
+```json
+{
+  "code": "API_ROUTE_NOT_FOUND",
+  "detail": "No API route exists at /api/nope.",
+  "instance": "/api/nope",
+  "links": [
+    {
+      "href": "https://docs.example.com/openapi.json",
+      "label": "OpenAPI description"
+    },
+    {
+      "href": "https://docs.example.com/api/docs/pages.json",
+      "label": "Page index"
+    }
+  ],
+  "resolution": "Discover the available operations through the OpenAPI description at https://docs.example.com/openapi.json, or list every page at https://docs.example.com/api/docs/pages.json.",
+  "status": 404,
+  "title": "API route not found",
+  "type": "about:blank"
+}
+```
+
+The **OpenAPI document** at `/openapi.json` is generated per build from your config, so it describes only what the deployed site serves: every JSON endpoint with a unique `operationId`, typed parameters, and response schemas, plus the text surfaces alongside — the [`.md` mirrors](#raw-markdown), [`llms.txt`](#llmstxt) and `llms-full.txt`, [`agent-readability.json`](#agent-readability) — and the [MCP endpoint](#mcp-server) when it's enabled. Frameworks that build tools from an OpenAPI description get the same reach an MCP client has. The document is linked from the [API catalog](#api-catalog), the [readability manifest](#agent-readability), the homepage `Link` header as `rel="service-desc"`, and `llms.txt`.
+
+None of this touches your own [API reference](/docs/advanced/api-reference): a documented spec is rendered into pages, never served at `/openapi.json`, and the catalog lists both. A `public/openapi.json` you ship yourself takes over that route (the JSON endpoints stay). The `/api/…` catch-all steps aside when a docs section is served from the `/api` namespace (`content/api/overview.md`) or a custom page owns a rest route under `/api/`, so those pages keep winning. Set `ai.api` to `false` to publish none of it:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  api: false,
+}
+```
+
 ## Agent readability
 
 Blume writes an **`/agent-readability.json`** manifest at your site root that indexes the agent-facing surface described on this page — so an agent can discover it in a single fetch instead of guessing at conventions or scraping HTML. Like `llms.txt`, it's on by default:
@@ -370,7 +420,7 @@ seo: {
 }
 ```
 
-The manifest lists only what you've enabled — the [raw Markdown](#raw-markdown) mirror pattern, [`llms.txt`](#llmstxt) and `llms-full.txt`, the [MCP server](#mcp-server) and its discovery document, the [Ask AI](#ask-ai) endpoint, the [sitemap](/docs/configuration/seo#sitemap), and [RSS feeds](/docs/configuration/seo#rss-feeds) — alongside your site name, description, source repository, and the [content-signal](/docs/configuration/seo#content-signals) usage policy. URLs are absolute when [`deployment.site`](/docs/deployment) is set and root-relative otherwise:
+The manifest lists only what you've enabled — the [raw Markdown](#raw-markdown) mirror pattern, the [JSON API](#json-api) and its OpenAPI description, [`llms.txt`](#llmstxt) and `llms-full.txt`, the [MCP server](#mcp-server) and its discovery document, the [Ask AI](#ask-ai) endpoint, the [sitemap](/docs/configuration/seo#sitemap), and [RSS feeds](/docs/configuration/seo#rss-feeds) — alongside your site name, description, source repository, and the [content-signal](/docs/configuration/seo#content-signals) usage policy. URLs are absolute when [`deployment.site`](/docs/deployment) is set and root-relative otherwise:
 
 ```json agent-readability.json
 {
@@ -379,6 +429,11 @@ The manifest lists only what you've enabled — the [raw Markdown](#raw-markdown
       "contentNegotiation": "text/markdown",
       "pattern": "https://docs.example.com/{route}.md"
     },
+    "api": {
+      "openapi": "https://docs.example.com/openapi.json",
+      "pages": "https://docs.example.com/api/docs/pages.json",
+      "search": "https://docs.example.com/api/docs/search"
+    },
     "llmsFullTxt": "https://docs.example.com/llms-full.txt",
     "llmsTxt": "https://docs.example.com/llms.txt",
     "mcp": {
@@ -404,12 +459,14 @@ Set `seo.agentReadability` to `false` to skip it, or ship your own `public/agent
 Agents that probe a site don't know to look for the manifest — so Blume also advertises it in an [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) `Link` response header on the homepage, using IANA-registered relation types:
 
 ```http
-Link: </agent-readability.json>; rel="describedby"; type="application/json",
+Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
+  </openapi.json>; rel="service-desc"; type="application/json",
+  </agent-readability.json>; rel="describedby"; type="application/json",
   </llms.txt>; rel="describedby"; type="text/plain",
   </index.md>; rel="alternate"; type="text/markdown"
 ```
 
-Each entry appears only when its feature is on. The `alternate` link points at the homepage's Markdown mirror — the page's own [raw Markdown](#raw-markdown) when the home route is a content page, or the synthesized `llms.txt` fallback when it's a landing page. Sites that publish APIs also get a `rel="api-catalog"` entry pointing at the [generated API catalog](#api-catalog). The header rides on every surface Blume controls: the dev server (check it with `curl -I localhost:4321`), static builds via the emitted `_headers` file (Netlify and Cloudflare), and Vercel server builds via the deploy's routing rules.
+Each entry appears only when its feature is on. The `alternate` link points at the homepage's Markdown mirror — the page's own [raw Markdown](#raw-markdown) when the home route is a content page, or the synthesized `llms.txt` fallback when it's a landing page. The `service-desc` link ([RFC 8631](https://www.rfc-editor.org/rfc/rfc8631)) points at the [JSON API](#json-api)'s OpenAPI description, and `api-catalog` at the [generated API catalog](#api-catalog). The header rides on every surface Blume controls: the dev server (check it with `curl -I localhost:4321`), static builds via the emitted `_headers` file (Netlify and Cloudflare), and Vercel server builds via the deploy's routing rules.
 
 Not every agent enters through the root, though — one following a search result or a shared link lands on a deep page and never sees the homepage header. So every rendered page also carries the same discovery links in its HTML `<head>`, using the same IANA-registered relations:
 
@@ -427,7 +484,7 @@ Here the `alternate` link points at _that page's own_ [raw-Markdown mirror](#raw
 
 ### API catalog
 
-When the site publishes APIs, Blume generates an [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) API catalog at `/.well-known/api-catalog` — a [linkset](https://www.rfc-editor.org/rfc/rfc9264) that lets agents enumerate your APIs from the domain alone, served with its registered `application/linkset+json` media type on every build surface. There's nothing to configure: the catalog is derived from what's already in `blume.config.ts`. Each [OpenAPI or AsyncAPI reference](/docs/advanced/api-reference) becomes an entry anchored at its rendered docs route, with `service-doc` pointing at those docs and `service-desc` at the spec when it lives at a fetchable URL; the [MCP server](#mcp-server) becomes an entry with its discovery document as the service description:
+When the site publishes APIs, Blume generates an [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) API catalog at `/.well-known/api-catalog` — a [linkset](https://www.rfc-editor.org/rfc/rfc9264) that lets agents enumerate your APIs from the domain alone, served with its registered `application/linkset+json` media type on every build surface. There's nothing to configure: the catalog is derived from what's already in `blume.config.ts`. Each [OpenAPI or AsyncAPI reference](/docs/advanced/api-reference) becomes an entry anchored at its rendered docs route, with `service-doc` pointing at those docs and `service-desc` at the spec when it lives at a fetchable URL; the site's own [JSON API](#json-api) becomes an entry described by its `/openapi.json`; and the [MCP server](#mcp-server) becomes an entry with its discovery document as the service description:
 
 ```json .well-known/api-catalog
 {
@@ -439,6 +496,18 @@ When the site publishes APIs, Blume generates an [RFC 9727](https://www.rfc-edit
       ],
       "service-desc": [{ "href": "https://api.example.com/openapi.json" }]
     },
+    {
+      "anchor": "https://docs.example.com/api/docs",
+      "service-desc": [
+        {
+          "href": "https://docs.example.com/openapi.json",
+          "type": "application/json"
+        }
+      ],
+      "service-doc": [
+        { "href": "https://docs.example.com/", "type": "text/html" }
+      ]
+    },
     {
       "anchor": "https://docs.example.com/mcp",
       "service-desc": [
@@ -455,7 +524,7 @@ When the site publishes APIs, Blume generates an [RFC 9727](https://www.rfc-edit
 }
 ```
 
-A site with no API references and no MCP server emits no catalog — there'd be nothing in it. As everywhere, a `public/.well-known/api-catalog` file you ship yourself wins over the generated one.
+A site with no API references, no MCP server, and the [JSON API](#json-api) turned off emits no catalog — there'd be nothing in it. As everywhere, a `public/.well-known/api-catalog` file you ship yourself wins over the generated one.
 
 ### WebMCP
 

package/docs/configuration/seo.mdx

@@ -125,7 +125,7 @@ seo: {
 }
 ```
 
-By default, each card is derived from your content and theme — the **page title** as the headline, your **site title** as the eyebrow, and your theme **accent** for the mark. Images are served at `/og/<slug>.png`, mirroring each route, and are prerendered as static files even in server mode:
+By default, each card is derived from your content and theme — the **page title** as the headline, the **page description** as the subtitle (the same text as its `og:description`, so `seo.description` wins over `description`), your **site title** as the eyebrow, and your theme **accent** for the mark. Images are served at `/og/<slug>.png`, mirroring each route, and are prerendered as static files even in server mode:
 
 | Page route          | Image URL                  |
 | ------------------- | -------------------------- |
@@ -151,13 +151,13 @@ Emoji in a page title or site title render as [Twemoji](https://github.com/jdeck
 
 ### Show, hide, or override card layers
 
-Beyond the headline, the card carries three optional layers: the **brand mark** in the top-left (your logo, or an accent tile with the site title's initial), the **subtitle** under the headline (your site `description`), and a **footer** with your repo slug (from `github`) and the site's URL — the deployment site's host plus [`deployment.base`](/docs/deployment#subpath-deploys), so a GitHub Pages project site reads `user.github.io/repo`. Override any of them with a string of your own, or hide one with `false`:
+Beyond the headline, the card carries three optional layers: the **brand mark** in the top-left (your logo, or an accent tile with the site title's initial), the **subtitle** under the headline (the page `description`, or your site `description` for pages without one), and a **footer** with your repo slug (from `github`) and the site's URL — the deployment site's host plus [`deployment.base`](/docs/deployment#subpath-deploys), so a GitHub Pages project site reads `user.github.io/repo`. Override any of them with a string of your own, or hide one with `false`:
 
 ```ts blume.config.ts lineNumbers
 seo: {
   og: {
     site: "docs.acme.com", // footer URL text, or false to hide it
-    description: false, // hide the subtitle; a string overrides it
+    description: false, // hide the subtitle on every card; a string replaces the site fallback
     logo: false, // no brand mark at all — not even the initial tile
   },
 }

package/docs/configuration/theming.mdx

@@ -206,6 +206,12 @@ Drop a `theme.css` in your project root to override any design token. It's the l
 
 Set a token under `:root` for light mode and under `:root[data-theme="dark"]` for dark mode. Color tokens have distinct built-in dark values declared at the dark selector's higher specificity, so a `:root`-only override of `--blume-accent`, `--blume-background`, and friends applies to light mode only — declare the dark block too when both modes should change.
 
+`theme.css` is inlined into the site's Tailwind entry, so Tailwind directives work in it too. The one to know for a monorepo is `@source`: Blume scans your project for utility classes, and a page that imports components from a sibling workspace package needs that package scanned as well. Point at it relative to `theme.css` — the standard Tailwind rule — and Blume carries the path into the generated sheet:
+
+```css theme.css lineNumbers
+@source "../../packages/ui/src";
+```
+
 ### Design tokens
 
 | Token                       | Controls                                  |

package/docs/content/components.mdx

@@ -567,7 +567,7 @@ The card reads the instance from [`github.host`](/docs/configuration#github-ente
 
 `Component` renders an example file from your project's `examples/` directory as a live preview alongside its highlighted source, in tabs. Point it at a file with `path` — its location under `examples/`, without the extension (so `examples/counter.tsx` is `path="counter"`). React, Vue, Svelte, and Astro examples are all supported; framework examples hydrate, Astro ones render statically. It keeps the preview and the code in sync from a single file.
 
-The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your example files and anything they import), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live. The pane sizes itself to the rendered example — and keeps tracking it if the example grows or shrinks after load — with the Preview and Code tabs sharing one height so toggling them never shifts the page.
+The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your project and your examples directory), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live. The pane sizes itself to the rendered example — and keeps tracking it if the example grows or shrinks after load — with the Preview and Code tabs sharing one height so toggling them never shifts the page.
 
 To style previews with your own design system — say, shadcn variables — point `examples.css` at a stylesheet. It's injected into every preview frame after Blume's defaults, so your tokens win. Don't `@import "tailwindcss"` in it; the frame already provides Tailwind. Both `.dark` and `[data-theme="dark"]` work for dark-mode overrides:
 
@@ -623,6 +623,13 @@ export default defineConfig({
 <Component path="file-list/examples/basic" />
 ```
 
+In a monorepo, the components your examples import usually live in a sibling workspace package. Tailwind's `@source` scans files, not imports: Blume scans your project and the `examples` directory (wherever `source` points, even outside the project), so a class used only inside that sibling package isn't generated until you add the package to the scan. Do that with an `@source` directive in `examples.css` (for the preview frames) or `theme.css` (for the site), written relative to the file it sits in — the standard Tailwind rule — and Blume carries it into the generated sheet:
+
+```css
+/* examples/theme.css */
+@source "../../../packages/ui/src";
+```
+
 <Component path="counter" />
 
 ```astro

package/docs/index.mdx

@@ -31,7 +31,7 @@ Blume builds on Astro and Vite and renders static HTML by default — fast, cach
 
 ### AI-ready out of the box
 
-Every Blume site speaks fluent machine. It emits [`llms.txt` and `llms-full.txt`](/docs/configuration/ai), serves any page's raw Markdown by appending `.md` to its URL, and gives readers **Copy as Markdown** and **Open in chat** actions on every page. Add an optional in-page **Ask AI** assistant, or host an [**MCP server**](/docs/configuration/ai#mcp-server) so coding agents like Claude Code and Cursor can search and read your docs directly — no scraping, no hosted service. Your Markdown is the source of truth for both humans and models.
+Every Blume site speaks fluent machine. It emits [`llms.txt` and `llms-full.txt`](/docs/configuration/ai), serves any page's raw Markdown by appending `.md` to its URL, exposes a [JSON API described by OpenAPI](/docs/configuration/ai#json-api), and gives readers **Copy as Markdown** and **Open in chat** actions on every page. Add an optional in-page **Ask AI** assistant, or host an [**MCP server**](/docs/configuration/ai#mcp-server) so coding agents like Claude Code and Cursor can search and read your docs directly — no scraping, no hosted service. Your Markdown is the source of truth for both humans and models.
 
 ### Zero configuration — even the template
 
@@ -45,7 +45,7 @@ Your [`blume.config.ts`](/docs/configuration) and every [`meta.ts`](/docs/conten
 
 - **Components** — callouts, cards, steps, tabs, accordions, badges, file trees, and parameter tables, usable in MDX with [no imports](/docs/content/components).
 - **Local search** — Orama works in dev and production; Pagefind is one flag away for large sites. No hosted index.
-- **AI** — [`llms.txt`, raw Markdown URLs, Copy as Markdown, Open in chat, an Ask AI assistant, and a hosted MCP server](/docs/configuration/ai).
+- **AI** — [`llms.txt`, raw Markdown URLs, a JSON API with an OpenAPI description, Copy as Markdown, Open in chat, an Ask AI assistant, and a hosted MCP server](/docs/configuration/ai).
 - **Navigation** — inferred from files, refined with `meta.ts` or config.
 - **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD, [built in](/docs/configuration/seo).
 - **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.