blume 1.6.0 → 1.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -66,107 +66,107 @@
     "typecheck": "tsgo --noEmit && tsgo -p test/tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@astrojs/check": "^0.9.0",
-    "@astrojs/markdown-satteri": "^0.3.2",
-    "@astrojs/mdx": "^7.0.0",
-    "@astrojs/node": "^11.0.0",
-    "@astrojs/react": "^6.0.0",
-    "@astrojs/vercel": "^11.0.3",
+    "@astrojs/check": "^0.9.10",
+    "@astrojs/markdown-satteri": "^0.4.0",
+    "@astrojs/mdx": "^8.0.0",
+    "@astrojs/node": "^11.1.5",
+    "@astrojs/react": "^6.0.5",
+    "@astrojs/vercel": "^11.0.10",
     "@asyncapi/converter": "^2.0.2",
     "@clack/prompts": "^1.7.0",
-    "@iconify-json/lucide": "^1.2.115",
+    "@iconify-json/lucide": "^1.2.129",
     "@iconify/types": "^2.0.0",
-    "@iconify/utils": "^3.1.3",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@iconify/utils": "^3.1.5",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@orama/orama": "^3.1.18",
-    "@pierre/diffs": "^1.2.11",
-    "@scalar/astro": "^0.4.5",
+    "@pierre/diffs": "^1.4.1",
+    "@scalar/astro": "^0.4.17",
     "@scalar/openapi-parser": "^0.29.0",
-    "@scalar/openapi-types": "^0.9.1",
-    "@shikijs/transformers": "^4.2.0",
-    "@shikijs/twoslash": "^4.2.0",
+    "@scalar/openapi-types": "^0.9.5",
+    "@shikijs/transformers": "^4.4.3",
+    "@shikijs/twoslash": "^4.4.3",
     "@tailwindcss/typography": "^0.5.20",
-    "@tailwindcss/vite": "^4",
+    "@tailwindcss/vite": "^4.3.3",
     "@types/mdast": "^4.0.4",
     "@vercel/analytics": "^2.0.1",
-    "ai": "^7.0.42",
-    "astro": "^7.2.3",
+    "ai": "^7.0.93",
+    "astro": "^7.3.1",
     "babel-plugin-react-compiler": "^1.0.0",
     "chokidar": "^5.0.0",
-    "citty": "^0.1.6",
-    "consola": "^3.4.0",
+    "citty": "^0.2.2",
+    "consola": "^3.4.2",
     "cross-spawn": "^7.0.6",
-    "dompurify": "^3.4.13",
+    "dompurify": "^3.4.14",
     "dotenv": "^17.4.2",
     "epub-gen-memory": "^1.1.2",
-    "fast-xml-parser": "^5.10.1",
+    "fast-xml-parser": "^5.11.1",
     "github-slugger": "^2.0.0",
     "graphql": "^17.0.2",
     "gray-matter": "^4.0.3",
     "html-escaper": "^3.0.3",
     "image-size": "^2.0.2",
-    "jiti": "^2.4.0",
+    "jiti": "^2.7.0",
     "js-yaml": "^5.4.1",
-    "katex": "^0.18.1",
+    "katex": "^0.18.6",
     "markdown-table": "^3.0.4",
-    "marked": "^18.0.5",
+    "marked": "^18.0.11",
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-gfm": "^3.1.0",
     "mdast-util-to-string": "^4.0.0",
     "medium-zoom": "^1.1.0",
-    "mermaid": "^11.16.1",
+    "mermaid": "^11.17.2",
     "micromark-extension-gfm": "^3.0.0",
     "nanotar": "^0.3.0",
-    "node-html-parser": "^9.0.0",
-    "openapi-sampler": "^1.7.4",
-    "p-limit": "^7.3.1",
-    "p-map": "^7.0.6",
-    "p-retry": "^8.0.0",
+    "node-html-parser": "^9.0.3",
+    "openapi-sampler": "^1.7.5",
+    "p-limit": "^7.3.2",
+    "p-map": "^7.0.7",
+    "p-retry": "^8.0.1",
     "package-manager-detector": "^1.8.0",
-    "pagefind": "^1.3.0",
-    "pathe": "^2.0.0",
+    "pagefind": "^1.5.2",
+    "pathe": "^2.0.3",
     "perfect-debounce": "^2.1.0",
-    "picomatch": "^4.0.5",
+    "picomatch": "^4.0.7",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "robots-parser": "^3.0.1",
     "satteri": "^0.10.5",
     "semver": "^7.8.5",
-    "sharp": "^0.35.3",
-    "shiki": "^4.2.0",
+    "sharp": "^0.35.4",
+    "shiki": "^4.4.3",
     "simple-icons": "^16.29.0",
-    "string-width": "^8.1.0",
+    "string-width": "^8.2.2",
     "sucrase": "^3.35.1",
     "tailwindcss": "^4.3.3",
-    "takumi-js": "^2.2.1",
-    "tinyglobby": "^0.2.10",
+    "takumi-js": "^2.13.6",
+    "tinyglobby": "^0.2.17",
     "twoslash": "^0.3.9",
     "typescript": "^6.0.3",
     "ufo": "^1.6.4",
-    "undici": "^8.9.0",
+    "undici": "^8.10.2",
     "write-file-atomic": "^8.0.0",
-    "zod": "^4.3.6"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@ai-sdk/openai-compatible": "^3.0.0",
-    "@mixedbread/sdk": "^0.76.0",
+    "@ai-sdk/openai-compatible": "^3.0.44",
+    "@mixedbread/sdk": "^0.77.0",
     "@notionhq/client": "^5.26.0",
     "@openrouter/ai-sdk-provider": "^3.0.0",
-    "@oramacloud/client": "^2.1.0",
-    "@sanity/client": "^8.4.0",
+    "@oramacloud/client": "^2.1.4",
+    "@sanity/client": "^8.5.0",
     "@types/cross-spawn": "^6.0.6",
     "@types/html-escaper": "^3.0.4",
-    "@types/node": "^22.10.0",
+    "@types/node": "^22.20.1",
     "@types/picomatch": "^4.0.3",
     "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.0.0",
+    "@types/react-dom": "^19.2.7",
     "@types/semver": "^7.8.0",
     "@types/write-file-atomic": "^4.0.3",
-    "@typescript/native-preview": "^7.0.0-dev.20260626.1",
-    "algoliasearch": "^5.55.0",
-    "bun-types": "^1.3.14",
-    "flexsearch": "^0.8.0",
-    "typesense": "^3.0.0"
+    "@typescript/native-preview": "^7.0.0-dev.20260707.2",
+    "algoliasearch": "^5.57.0",
+    "bun-types": "^1.4.2",
+    "flexsearch": "^0.8.212",
+    "typesense": "^3.0.6"
   },
   "peerDependencies": {
     "@ai-sdk/openai-compatible": "^3.0.0",
@@ -174,7 +174,7 @@
     "@astrojs/netlify": "^8.0.0",
     "@astrojs/svelte": "^9.0.0",
     "@astrojs/vue": "^7.0.0",
-    "@mixedbread/sdk": "^0.76.0",
+    "@mixedbread/sdk": "^0.77.0",
     "@notionhq/client": "^5.0.0",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "@oramacloud/client": "^2.1.0",

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",
+  });
+};

package/src/ai/api/paths.ts

@@ -0,0 +1,14 @@
+/**
+ * Where the JSON docs API and its OpenAPI description are served. Base-less
+ * (like every route Blume emits); callers layer `deployment.base` on top.
+ * Under `/api/` alongside the Ask AI endpoint (`/api/ask`) so the namespace a
+ * Blume site reserves for live endpoints stays one prefix, and under its own
+ * `docs` segment so a search provider's proxy at `/api/search` never collides.
+ */
+
+export const OPENAPI_PATH = "/openapi.json";
+export const API_BASE = "/api/docs";
+export const API_PAGES_PATH = `${API_BASE}/pages.json`;
+export const API_PAGE_PATH = `${API_BASE}/pages/{route}.json`;
+export const API_NAVIGATION_PATH = `${API_BASE}/navigation.json`;
+export const API_SEARCH_PATH = `${API_BASE}/search`;

package/src/ai/api/problem.ts

@@ -0,0 +1,63 @@
+/**
+ * RFC 9457 problem details — the one error shape every Blume JSON endpoint
+ * returns, so an agent that hits a missing page, a bad query, or an unknown
+ * API route always gets a stable machine-readable `code`, a human-readable
+ * `detail`, and a `resolution` telling it where to go next.
+ */
+
+export const PROBLEM_TYPE = "application/problem+json";
+
+/** A recovery link carried on a problem (the 404's "where to look next"). */
+export interface ProblemLink {
+  href: string;
+  label: string;
+}
+
+export interface Problem {
+  /** Stable, screaming-snake error code for programmatic handling. */
+  code: string;
+  /** Human-readable explanation specific to this occurrence. */
+  detail: string;
+  /** The request path the problem occurred on, when known. */
+  instance?: string;
+  /** Recovery links, when the problem has somewhere useful to send the caller. */
+  links?: ProblemLink[];
+  /** What to do next — the hint agents act on. */
+  resolution: string;
+  status: number;
+  title: string;
+  /** Problem type URI; `about:blank` when the status code says it all. */
+  type: string;
+}
+
+/** The problem's members, with `type` defaulting to `about:blank`. */
+export const problem = (
+  input: Omit<Problem, "type"> & { type?: string }
+): Problem => {
+  const body: Problem = {
+    code: input.code,
+    detail: input.detail,
+    resolution: input.resolution,
+    status: input.status,
+    title: input.title,
+    type: input.type ?? "about:blank",
+  };
+  if (input.instance !== undefined) {
+    body.instance = input.instance;
+  }
+  if (input.links !== undefined) {
+    body.links = input.links;
+  }
+  return body;
+};
+
+/** A `Response` carrying the problem as `application/problem+json`. */
+export const problemResponse = (
+  input: Omit<Problem, "type"> & { type?: string }
+): Response => {
+  const body = problem(input);
+  return new Response(`${JSON.stringify(body, null, 2)}\n`, {
+    headers: { "Content-Type": `${PROBLEM_TYPE}; charset=utf-8` },
+    status: body.status,
+  });
+};