blume 1.6.1 → 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

@@ -143,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;
     };

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

@@ -79,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>;
@@ -192,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>;
@@ -500,6 +501,7 @@ declare const graphqlSourceSchema: z.ZodObject<{
 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>;

package/docs/advanced/custom-pages.mdx

@@ -274,7 +274,7 @@ import data from "blume:data";
 
 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` with the same recovery links (absolute URLs once [`deployment.site`](/docs/deployment) is set). 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 that Markdown body with the `404` status instead of the HTML shell — so an agent never has to parse a page of chrome to learn where to go next.
+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/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
 
@@ -364,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:
@@ -374,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
 {
@@ -383,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": {
@@ -408,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:
 
@@ -431,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
 {
@@ -443,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": [
@@ -459,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/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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/skills/blume/SKILL.md

@@ -12,7 +12,7 @@ The core idea: **the framework _is_ the template.** There's no starter to clone
 ## What makes it different
 
 - **Fast by default** — Static HTML on Astro/Vite. The core theme ships no client framework JS so pages score well on Core Web Vitals out of the box. You opt into server features only when you need them.
-- **AI-ready out of the box** — Emits `llms.txt`/`llms-full.txt`, serves any page's raw Markdown by appending `.md` to its URL, offers **Copy as Markdown** and **Open in chat** on every page, and can host an optional **Ask AI** assistant or an **MCP server** so coding agents read your docs directly.
+- **AI-ready out of the box** — Emits `llms.txt`/`llms-full.txt`, serves any page's raw Markdown by appending `.md` to its URL, publishes a JSON docs API (`/api/docs/…`) described by an OpenAPI document at `/openapi.json`, offers **Copy as Markdown** and **Open in chat** on every page, and can host an optional **Ask AI** assistant or an **MCP server** so coding agents read your docs directly.
 - **Zero configuration — even the template** — A folder of docs is a complete project. Navigation is inferred from files, search works in dev and production with no hosted service, and theming is a handful of tokens.
 - **Type-safe to the core** — `blume.config.ts` and every `meta.ts` are real TypeScript, validated by a schema and authored with `defineConfig` and `defineMeta`. Your editor autocompletes options and catches mistakes before a build.
 
@@ -52,7 +52,7 @@ Navigation, search, and page metadata are inferred from your files as you add th
 
 - **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; 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 an MCP server endpoint served by the docs site itself.
+- **AI** — `llms.txt`, raw Markdown URLs, a JSON docs API with an OpenAPI description, Copy as Markdown, Open in chat, an Ask AI assistant, and an MCP server endpoint served by the docs site itself.
 - **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/src/ai/agent-readability.ts

@@ -5,6 +5,7 @@ import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
 import { absoluteUrl } from "../core/site-url.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
 import { hasApiCatalog } from "./api-catalog.ts";
+import { API_PAGES_PATH, API_SEARCH_PATH, OPENAPI_PATH } from "./api/paths.ts";
 
 /** Token map for the machine-readable content-usage echo. */
 const USAGE_TOKENS: [keyof ContentSignalPolicy, string][] = [
@@ -55,9 +56,17 @@ interface WellKnownArtifacts {
   agentSkills?: string;
 }
 
+/** The JSON docs API's entry points; `search` exists on server output only. */
+interface ApiArtifact {
+  openapi: string;
+  pages: string;
+  search?: string;
+}
+
 /** The agent-facing artifact index the manifest publishes. */
 interface AgentArtifacts extends WellKnownArtifacts {
   markdown: { contentNegotiation?: string; pattern: string };
+  api?: ApiArtifact;
   llmsFullTxt?: string;
   llmsTxt?: string;
   mcp?: { discovery: string; url: string };
@@ -77,6 +86,47 @@ export interface AgentReadabilityManifest {
   repository?: string;
 }
 
+/**
+ * The raw-Markdown mirror pattern. `Accept: text/markdown` negotiation is
+ * advertised only where the deployed site actually honors it — a Vercel
+ * server build, whose routing config gets the rewrite rules (see
+ * `deploy/vercel-negotiation.ts`), and a Cloudflare server build, whose
+ * deploy bundle gets a wrapper Worker (see `deploy/cloudflare-negotiation.ts`).
+ * Static builds and other adapters serve prerendered pages from a static
+ * layer with no request-time hook, so agents there should fetch the `.md`
+ * pattern directly.
+ */
+const markdownArtifact = (
+  config: BlumeProject["config"],
+  abs: (path: string) => string
+): AgentArtifacts["markdown"] => {
+  const negotiates =
+    config.deployment.output === "server" &&
+    (config.deployment.adapter === "vercel" ||
+      config.deployment.adapter === "cloudflare");
+  return negotiates
+    ? { contentNegotiation: "text/markdown", pattern: abs("/{route}.md") }
+    : { pattern: abs("/{route}.md") };
+};
+
+/** The JSON docs API's entry points, or null when the API is off. */
+const apiArtifact = (
+  config: BlumeProject["config"],
+  abs: (path: string) => string
+): ApiArtifact | null => {
+  if (!config.ai.api) {
+    return null;
+  }
+  const api: ApiArtifact = {
+    openapi: abs(OPENAPI_PATH),
+    pages: abs(API_PAGES_PATH),
+  };
+  if (config.deployment.output === "server") {
+    api.search = abs(API_SEARCH_PATH);
+  }
+  return api;
+};
+
 /** The `.well-known` discovery artifacts the site publishes, if any. */
 const wellKnownArtifacts = (
   config: BlumeProject["config"],
@@ -99,8 +149,9 @@ const wellKnownArtifacts = (
 
 /**
  * Build `agent-readability.json`: a root manifest that indexes the project's
- * agent-facing surface — llms.txt, the raw-Markdown mirrors, the MCP server,
- * Ask AI, sitemap, and feeds — so agents can discover and cite the docs without
+ * agent-facing surface — llms.txt, the raw-Markdown mirrors, the JSON docs
+ * API and its OpenAPI description, the MCP server, Ask AI, sitemap, and feeds
+ * — so agents can discover and cite the docs without
  * scraping HTML. URLs are absolute when a `site` is configured and root-relative
  * (still under `deployment.base`) otherwise. Returns null when the manifest is
  * disabled.
@@ -122,21 +173,13 @@ export const buildAgentReadability = (
     return site ? absoluteUrl(site, based) : based;
   };
 
-  // Advertise `Accept: text/markdown` negotiation only where the deployed site
-  // actually honors it — a Vercel server build, whose routing config gets the
-  // rewrite rules (see `deploy/vercel-negotiation.ts`), and a Cloudflare server
-  // build, whose deploy bundle gets a wrapper Worker (see
-  // `deploy/cloudflare-negotiation.ts`). Static builds and other adapters serve
-  // prerendered pages from a static layer with no request-time hook, so agents
-  // there should fetch the `.md` pattern directly.
-  const negotiates =
-    config.deployment.output === "server" &&
-    (config.deployment.adapter === "vercel" ||
-      config.deployment.adapter === "cloudflare");
-  const markdown: AgentArtifacts["markdown"] = negotiates
-    ? { contentNegotiation: "text/markdown", pattern: abs("/{route}.md") }
-    : { pattern: abs("/{route}.md") };
-  const artifacts: AgentArtifacts = { markdown };
+  const artifacts: AgentArtifacts = {
+    markdown: markdownArtifact(config, abs),
+  };
+  const api = apiArtifact(config, abs);
+  if (api) {
+    artifacts.api = api;
+  }
   if (config.ai.llmsTxt.enabled) {
     artifacts.llmsFullTxt = abs("/llms-full.txt");
     artifacts.llmsTxt = abs("/llms.txt");

package/src/ai/api/handlers.ts

@@ -0,0 +1,273 @@
+import { withBasePath } from "../../core/base-path.ts";
+import { absoluteUrl } from "../../core/site-url.ts";
+import type { Navigation } from "../../core/types.ts";
+import type { McpData, McpRoute } from "../mcp/data.ts";
+import {
+  createIndexProvider,
+  getPageMarkdown,
+  searchDocs,
+  TOOL_INPUTS,
+  urlFor,
+} from "../mcp/query.ts";
+import type { SearchHitPayload } from "../mcp/query.ts";
+import {
+  API_BASE,
+  API_PAGES_PATH,
+  API_SEARCH_PATH,
+  OPENAPI_PATH,
+} from "./paths.ts";
+import { problemResponse } from "./problem.ts";
+
+/**
+ * The JSON docs API: the REST twin of the MCP tools, over the same snapshot
+ * and the same operations (`mcp/query.ts`). The page index, per-page JSON,
+ * and navigation are prerendered, so a static site serves them from files;
+ * search is a live endpoint and exists on server output only. Errors are RFC
+ * 9457 problem details (`problem.ts`). The generated endpoints under
+ * `.blume/src/pages/api/docs/` are thin wrappers around these.
+ */
+
+/** One page in the index; `version` only appears on versioned sites. */
+export interface ApiPageSummary {
+  contentType: string;
+  description?: string;
+  facets?: Record<string, string>;
+  /** The page's JSON representation (this API's `getPage`). */
+  json: string;
+  lastModified: string | null;
+  locale: string;
+  /** The page's raw-Markdown mirror (`{route}.md`). */
+  markdownUrl: string;
+  route: string;
+  title: string;
+  /** Where the rendered page is served. */
+  url: string;
+  version?: string;
+}
+
+/** The `pages.json` document. */
+export interface ApiPagesIndex {
+  count: number;
+  generator: string;
+  pages: ApiPageSummary[];
+  site: string | null;
+}
+
+/** A page's JSON representation: its index entry plus the agent Markdown. */
+export interface ApiPage extends ApiPageSummary {
+  markdown: string;
+}
+
+/** The search endpoint's document. */
+export interface ApiSearchResponse {
+  count: number;
+  query: string;
+  results: SearchHitPayload[];
+}
+
+/** The site + base an endpoint needs to build absolute URLs. */
+export interface ApiSiteContext {
+  base: string;
+  site: string | null;
+}
+
+/** What the API serializes: one of its documents, or the navigation tree. */
+export type ApiPayload =
+  | ApiPage
+  | ApiPagesIndex
+  | ApiSearchResponse
+  | Navigation;
+
+/** A `Response` carrying JSON, pretty-printed for the humans who curl it. */
+export const jsonResponse = (payload: ApiPayload, status = 200): Response =>
+  new Response(`${JSON.stringify(payload, null, 2)}\n`, {
+    headers: { "Content-Type": "application/json; charset=utf-8" },
+    status,
+  });
+
+/** The `pages/{route}.json` path segment for a route (`index` for home). */
+export const pageParam = (route: string): string =>
+  route === "/" ? "index" : route.slice(1);
+
+/** The absolute (or root-relative) URL for a base-less path. */
+const siteUrl = (path: string, context: ApiSiteContext): string => {
+  const based = withBasePath(context.base, path);
+  return context.site ? absoluteUrl(context.site, based) : based;
+};
+
+const summarize = (route: McpRoute, data: McpData): ApiPageSummary => {
+  const summary: ApiPageSummary = {
+    contentType: route.contentType,
+    json: siteUrl(`${API_BASE}/pages/${pageParam(route.route)}.json`, data),
+    lastModified: route.lastModified,
+    locale: route.locale,
+    markdownUrl: siteUrl(`/${pageParam(route.route)}.md`, data),
+    route: route.route,
+    title: route.title,
+    url: urlFor(route.route, data),
+  };
+  if (route.description !== undefined) {
+    summary.description = route.description;
+  }
+  if (route.facets) {
+    summary.facets = route.facets;
+  }
+  if (data.archivedVersions) {
+    summary.version = route.version;
+  }
+  return summary;
+};
+
+/** Every non-hidden page, in manifest order; the index is unfiltered. */
+export const buildPagesIndex = (data: McpData): ApiPagesIndex => {
+  const pages = data.routes.map((route) => summarize(route, data));
+  return {
+    count: pages.length,
+    generator: `blume@${data.version}`,
+    pages,
+    site: data.site,
+  };
+};
+
+export const pagesIndexResponse = (data: McpData): Response =>
+  jsonResponse(buildPagesIndex(data));
+
+/**
+ * `getStaticPaths` entries for the per-page endpoint: one per route that has
+ * agent Markdown to serve (a landing page without a mirror has no JSON twin
+ * either).
+ */
+export const pageParams = (
+  data: McpData
+): { params: { route: string }; props: { route: string } }[] =>
+  data.routes
+    .filter((route) => getPageMarkdown(data, route.route) !== undefined)
+    .map((route) => ({
+      params: { route: pageParam(route.route) },
+      props: { route: route.route },
+    }));
+
+/** A page's JSON document, or null when no page has the route. */
+export const buildPage = (data: McpData, route: string): ApiPage | null => {
+  const entry = data.routes.find((candidate) => candidate.route === route);
+  const markdown = getPageMarkdown(data, route);
+  if (!entry || markdown === undefined) {
+    return null;
+  }
+  return { ...summarize(entry, data), markdown };
+};
+
+export const pageResponse = (data: McpData, route: string): Response => {
+  const page = buildPage(data, route);
+  if (!page) {
+    return problemResponse({
+      code: "PAGE_NOT_FOUND",
+      detail: `No documentation page has the route "${route}".`,
+      instance: siteUrl(`${API_BASE}/pages/${pageParam(route)}.json`, data),
+      resolution: `List every page at ${siteUrl(API_PAGES_PATH, data)}, or discover the API through ${siteUrl(OPENAPI_PATH, data)}.`,
+      status: 404,
+      title: "Page not found",
+    });
+  }
+  return jsonResponse(page);
+};
+
+/** The default navigation tree (default locale, current docs). */
+export const buildNavigation = (data: McpData): Navigation => data.navigation;
+
+export const navigationResponse = (data: McpData): Response =>
+  jsonResponse(buildNavigation(data));
+
+/** Repeated and comma-separated values of a list query parameter. */
+const listParam = (
+  params: URLSearchParams,
+  key: string
+): string[] | undefined => {
+  const values = params
+    .getAll(key)
+    .flatMap((value) => value.split(","))
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+  return values.length > 0 ? values : undefined;
+};
+
+const FILTER_PARAM = /^filters\[(?<key>.+)\]$/u;
+
+/** The `filters[key]=value` (OpenAPI deepObject) facet filters. */
+const filtersParam = (
+  params: URLSearchParams
+): Record<string, string> | undefined => {
+  const entries: [string, string][] = [];
+  for (const [key, value] of params) {
+    const facet = FILTER_PARAM.exec(key)?.groups?.key;
+    if (facet) {
+      entries.push([facet, value]);
+    }
+  }
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+};
+
+/**
+ * The live search endpoint: `GET /api/docs/search?q=…`. Runs the same query
+ * `search_docs` runs, over an index built once per snapshot and shared across
+ * requests. A missing or blank `q` is a 400 problem.
+ */
+export const createSearchHandler = (
+  data: McpData
+): ((request: Request) => Promise<Response>) => {
+  const index = createIndexProvider(data.documents, data.defaultLocale);
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const params = url.searchParams;
+    const query = (params.get("q") ?? "").trim();
+    if (!query) {
+      return problemResponse({
+        code: "MISSING_QUERY",
+        detail: 'The "q" query parameter is required and must not be blank.',
+        instance: url.pathname,
+        resolution: `Repeat the request with ?q=<search terms>, e.g. ${siteUrl(API_SEARCH_PATH, data)}?q=install.`,
+        status: 400,
+        title: "Missing search query",
+      });
+    }
+    const input = TOOL_INPUTS.search_docs.parse({
+      contentTypes: listParam(params, "contentTypes"),
+      filters: filtersParam(params),
+      limit: params.get("limit") ?? undefined,
+      locale: params.get("locale") ?? undefined,
+      query,
+      version: params.get("version") ?? undefined,
+    });
+    const results = await searchDocs(data, index, input);
+    const payload: ApiSearchResponse = {
+      count: results.length,
+      query,
+      results,
+    };
+    return jsonResponse(payload);
+  };
+};
+
+/**
+ * The 404 for anything under `/api/` that no endpoint answers — the catch-all
+ * behind every live route on server output, so an agent probing the API
+ * namespace gets a problem document instead of the HTML not-found page.
+ */
+export const apiNotFoundResponse = (
+  request: Request,
+  context: ApiSiteContext
+): Response => {
+  const { pathname } = new URL(request.url);
+  return problemResponse({
+    code: "API_ROUTE_NOT_FOUND",
+    detail: `No API route exists at ${pathname}.`,
+    instance: pathname,
+    links: [
+      { href: siteUrl(OPENAPI_PATH, context), label: "OpenAPI description" },
+      { href: siteUrl(API_PAGES_PATH, context), label: "Page index" },
+    ],
+    resolution: `Discover the available operations through the OpenAPI description at ${siteUrl(OPENAPI_PATH, context)}, or list every page at ${siteUrl(API_PAGES_PATH, context)}.`,
+    status: 404,
+    title: "API route not found",
+  });
+};