blume 1.7.1 → 1.7.3

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

@@ -588,6 +588,8 @@ export interface AskSuggestion {
 /** Backends that can route an Ask AI request. */
 type AskProviderGateway = "gateway" | "openrouter" | "llmgateway";
 type AskProvider = AskProviderGateway | "inkeep" | "openai-compatible";
+/** How much the model reasons before answering (`ai.ask.reasoning`). */
+type AskReasoning = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
 /** How much retrieved documentation each Ask AI question carries. */
 export interface AskRetrievalConfig {
     /**
@@ -620,6 +622,18 @@ export interface AskConfig {
      * overrides the built-in preset.
      */
     baseUrl?: string;
+    /**
+     * Origins allowed to call the generated endpoint from another site — a
+     * marketing page that embeds an ask box, for example — or `"*"` to allow
+     * every origin. The route answers preflight requests and names a listed
+     * origin on every response, errors included; every other origin stays
+     * subject to the browser's same-origin rule. Callers must send the body as
+     * JSON with a `content-type: application/json` header, or Astro's cross-site
+     * request check rejects the `POST` before the route runs. Only the generated
+     * route reads this; an external `endpoint` handles its own CORS and can't be
+     * combined with it.
+     */
+    cors?: string[];
     /** Turn Ask AI on. Defaults to `false`. */
     enabled?: boolean;
     /**
@@ -645,6 +659,18 @@ export interface AskConfig {
     model?: string;
     /** Which backend routes the request. Defaults to `gateway`. */
     provider?: AskProvider;
+    /**
+     * How much the model reasons before answering, from `"none"` to `"xhigh"`.
+     * Sent as the backend's own reasoning-effort control: the AI SDK's
+     * `reasoning` option on the gateway, `reasoning.effort` on OpenRouter, and
+     * `reasoning_effort` on OpenAI-compatible endpoints. The model has to
+     * support the level — OpenAI rejects one a model doesn't offer — and the
+     * endpoint has to accept the parameter; Inkeep has no reasoning control,
+     * so the field is rejected there. Omitted keeps the model's default.
+     * `"none"` is the fastest and cheapest for grounded docs Q&A, where the
+     * retrieved excerpts carry the answer.
+     */
+    reasoning?: AskReasoning;
     /**
      * How much documentation each question carries into the model's prompt.
      * Lower values cut time-to-first-token — which dominates on a self-hosted
@@ -654,6 +680,30 @@ export interface AskConfig {
     /** Starter prompts shown before the first question. */
     suggestions?: AskSuggestion[];
 }
+/** What the AI Catalog (ARD) manifest carries. */
+export interface AiCatalogConfig {
+    /** Emit `/.well-known/ai-catalog.json` and `/.well-known/ard.json`. Defaults to `true`. */
+    enabled?: boolean;
+    /**
+     * Representative queries per entry, keyed by the entry's `<namespace>:<name>`
+     * — its identifier minus the `urn:air:<host>:` prefix (`mcp:docs`,
+     * `skill:blume`, `api:docs`, `reference:<slug>`, `docs:llms-txt`). Each
+     * list replaces the generated defaults for that entry: 2–5 short
+     * natural-language questions the resource can answer, which agent
+     * registries embed for semantic search.
+     *
+     * ```ts
+     * ai: {
+     *   catalog: {
+     *     queries: {
+     *       "mcp:acme": ["how do I install Acme", "search the Acme docs"],
+     *     },
+     *   },
+     * }
+     * ```
+     */
+    queries?: Record<string, string[]>;
+}
 /** What the `llms.txt`/`llms-full.txt` files include. */
 export interface LlmsTxtConfig {
     /**
@@ -708,6 +758,15 @@ export interface AiConfig {
     api?: boolean;
     /** The Ask AI chat assistant. */
     ask?: AskConfig;
+    /**
+     * The AI Catalog / ARD manifest (`/.well-known/ai-catalog.json`, mirrored
+     * at `/.well-known/ard.json`): a domain-level index of the agent-facing
+     * resources the site publishes — MCP server, agent skills, the JSON docs
+     * API, API references, llms.txt — for agent registries. Needs a
+     * `deployment.site`. Defaults to `true`; the object form overrides the
+     * generated representative queries per entry.
+     */
+    catalog?: boolean | AiCatalogConfig;
     /**
      * Emit `llms.txt` (an index of the docs for LLMs). Defaults to `true`.
      * The object form adds knobs for what the files include.

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

@@ -143,6 +143,8 @@ export interface BlumeDataConfig {
      */
     discovery: {
         agentReadability: boolean;
+        /** Whether the AI Catalog / ARD manifest is published (`ai.catalog`). */
+        aiCatalog: boolean;
         /** Whether the JSON docs API and its `/openapi.json` are published. */
         api: boolean;
         llmsTxt: boolean;

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

@@ -327,6 +327,11 @@ export type SidebarItemConfig = string | {
     root?: string;
 };
 export declare const searchProviders: readonly ["orama", "pagefind", "flexsearch", "algolia", "orama-cloud", "typesense", "mixedbread", "none"];
+/**
+ * The `ai.ask.reasoning` levels: the AI SDK's top-level `reasoning` values
+ * minus `provider-default`, which is what omitting the field means.
+ */
+export declare const askReasoningLevels: readonly ["none", "minimal", "low", "medium", "high", "xhigh"];
 /** 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<{
@@ -334,6 +339,7 @@ declare const aiConfigSchema: z.ZodObject<{
     ask: z.ZodOptional<z.ZodObject<{
         apiKeyEnv: z.ZodOptional<z.ZodString>;
         baseUrl: z.ZodOptional<z.ZodURL>;
+        cors: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodPipe<z.ZodURL, z.ZodTransform<string, string>>]>>>;
         enabled: z.ZodDefault<z.ZodBoolean>;
         endpoint: z.ZodOptional<z.ZodString>;
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -346,6 +352,14 @@ declare const aiConfigSchema: z.ZodObject<{
             inkeep: "inkeep";
             "openai-compatible": "openai-compatible";
         }>>;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>>;
         retrieval: z.ZodOptional<z.ZodObject<{
             contextBudget: z.ZodOptional<z.ZodNumber>;
             excerptChars: z.ZodOptional<z.ZodNumber>;
@@ -356,6 +370,16 @@ declare const aiConfigSchema: z.ZodObject<{
             label: z.ZodString;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
+    catalog: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        queries: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>]>>, z.ZodTransform<{
+        enabled: boolean;
+        queries: Record<string, string[]>;
+    }, boolean | {
+        enabled: boolean;
+        queries: Record<string, string[]>;
+    }>>;
     llmsTxt: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         details: z.ZodOptional<z.ZodString>;
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -391,6 +415,7 @@ declare const aiConfigSchema: z.ZodObject<{
     webmcp: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>;
 export type AskAiProvider = (typeof askAiProviders)[number];
+export type AskReasoning = (typeof askReasoningLevels)[number];
 export type AskAiConfig = NonNullable<z.infer<typeof aiConfigSchema>["ask"]>;
 export { openInChatProviders } from "./open-in-chat.ts";
 export type { OpenInChatProvider } from "./open-in-chat.ts";
@@ -505,9 +530,9 @@ declare const contentSignalsSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean,
 declare const dateFormatConfigSchema: z.ZodObject<{
     calendar: z.ZodOptional<z.ZodString>;
     dateStyle: z.ZodOptional<z.ZodEnum<{
+        medium: "medium";
         full: "full";
         long: "long";
-        medium: "medium";
         short: "short";
     }>>;
     day: z.ZodOptional<z.ZodEnum<{
@@ -576,6 +601,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
         ask: z.ZodOptional<z.ZodObject<{
             apiKeyEnv: z.ZodOptional<z.ZodString>;
             baseUrl: z.ZodOptional<z.ZodURL>;
+            cors: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodPipe<z.ZodURL, z.ZodTransform<string, string>>]>>>;
             enabled: z.ZodDefault<z.ZodBoolean>;
             endpoint: z.ZodOptional<z.ZodString>;
             headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -588,6 +614,14 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 inkeep: "inkeep";
                 "openai-compatible": "openai-compatible";
             }>>;
+            reasoning: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                minimal: "minimal";
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+            }>>;
             retrieval: z.ZodOptional<z.ZodObject<{
                 contextBudget: z.ZodOptional<z.ZodNumber>;
                 excerptChars: z.ZodOptional<z.ZodNumber>;
@@ -598,6 +632,16 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 label: z.ZodString;
             }, z.core.$strict>>>;
         }, z.core.$strict>>;
+        catalog: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            queries: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+        }, z.core.$strict>]>>, z.ZodTransform<{
+            enabled: boolean;
+            queries: Record<string, string[]>;
+        }, boolean | {
+            enabled: boolean;
+            queries: Record<string, string[]>;
+        }>>;
         llmsTxt: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
             details: z.ZodOptional<z.ZodString>;
             enabled: z.ZodDefault<z.ZodBoolean>;
@@ -773,9 +817,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
     dateFormat: z.ZodDefault<z.ZodObject<{
         calendar: z.ZodOptional<z.ZodString>;
         dateStyle: z.ZodOptional<z.ZodEnum<{
+            medium: "medium";
             full: "full";
             long: "long";
-            medium: "medium";
             short: "short";
         }>>;
         day: z.ZodOptional<z.ZodEnum<{
@@ -1061,6 +1105,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label: z.ZodString;
         }, z.core.$strict>>>;
         provider: z.ZodDefault<z.ZodEnum<{
+            none: "none";
             algolia: "algolia";
             mixedbread: "mixedbread";
             orama: "orama";
@@ -1068,7 +1113,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
             flexsearch: "flexsearch";
             "orama-cloud": "orama-cloud";
             typesense: "typesense";
-            none: "none";
         }>>;
         typesense: z.ZodOptional<z.ZodObject<{
             collection: z.ZodString;

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

@@ -208,6 +208,11 @@ export type NavNode = {
      */
     display: SidebarDisplay;
     icon?: string;
+    /**
+     * The group row's link: an explicit-config group's `root`, or the
+     * generated folder's index page route. Absent when there is no page at
+     * the group's own path, so the row never links to a 404.
+     */
     route?: string;
     /**
      * The group's URL path (its folder route prefix), even when the folder

package/docs/configuration/ask-ai.mdx

@@ -109,6 +109,37 @@ Blume sends the same `POST` body as its built-in route:
 
 Return a successful response whose body is a plain UTF-8 text stream. If the endpoint is on another origin, allow the docs origin with CORS: accept `OPTIONS` and `POST`, permit the `content-type` request header, and return the CORS headers on both the preflight and streamed response. With `endpoint` set, Blume generates the chat UI but no server route, grounding snapshot, provider dependency, or provider-secret warning; your backend owns retrieval, authentication, rate limiting, model access, and citations.
 
+## Cross-origin callers
+
+The generated endpoint answers the in-page assistant on its own origin. To call it from another site as well — a marketing page with an ask box, say — list that site's origin in `cors`:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    cors: ["https://www.example.com"],
+  },
+}
+```
+
+The route then answers the browser's `OPTIONS` preflight and names a listed origin on every response — the streamed answer and the error statuses alike, so the caller can tell a rejected body from a provider failure. Origins that aren't listed get no header and stay subject to the browser's same-origin rule. Each entry is reduced to its origin, so `https://www.example.com/docs/` and `https://www.example.com` mean the same thing. To let any page call the route, list `"*"` instead of origins.
+
+The caller sends the same `POST` body the [external endpoint](#external-endpoint) contract describes and reads back the same text stream. Send it as JSON with a `content-type: application/json` header:
+
+```ts
+const response = await fetch("https://docs.example.com/api/ask", {
+  body: JSON.stringify({
+    messages: [{ role: "user", content: "How do I deploy?" }],
+  }),
+  headers: { "content-type": "application/json" },
+  method: "POST",
+});
+```
+
+The content type matters: Astro's cross-site request check rejects a cross-origin `POST` that has no content type, or a form-like one such as `text/plain`, with a 403 before the route runs, and that response carries no CORS headers, so the browser reports it as a network error rather than a status. The preflight allows whatever request headers the caller asks for, so a fetch wrapper that adds its own headers needs no extra configuration.
+
+`cors` only affects the generated route; with an external `endpoint`, CORS is that backend's job, and setting both is a config error. The endpoint stays unauthenticated either way, so the [rate limiting](#rate-limiting) advice applies to cross-origin traffic too.
+
 ## Server output required
 
 Blume's built-in Ask AI backend is a server route (`POST /api/ask`), so it can't run on a static build. Switch to server output and pick an adapter:
@@ -188,6 +219,36 @@ The values are written into the generated route as-is, so keep secrets in `apiKe
 
 Keys are read through Astro's [`getSecret()`](https://docs.astro.build/en/guides/environment-variables/#retrieving-secrets-programmatically), so each adapter supplies them its own way: environment variables on Node, Vercel, and Netlify, and the Worker's [bindings](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets) on Cloudflare. Enabling Ask AI also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).
 
+## Reasoning
+
+Reasoning models think before they answer, and how much they do so by default varies by model. For grounded docs Q&A the retrieved excerpts carry the answer, so most of that thinking is latency the reader waits through. `reasoning` sets how much the model reasons: `"none"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, or `"xhigh"`:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    model: "openai/gpt-5.5",
+    reasoning: "none",
+  },
+}
+```
+
+The value is sent as the backend's own reasoning-effort control. Through the gateway it travels as the [AI SDK's `reasoning` option](https://ai-sdk.dev/docs/ai-sdk-core/reasoning), which the gateway maps to the model's setting — OpenAI's `reasoning_effort`, for example. On OpenRouter it is sent as `reasoning.effort`, and on LLMGateway or a custom `openai-compatible` endpoint as `reasoning_effort` in the request, so the endpoint has to accept that parameter. The model has to support the level you pick: OpenAI rejects a level a model doesn't offer (`"none"` and `"xhigh"` exist only on some), so check the model's documentation before setting one. Inkeep runs its own QA pipeline and has no reasoning control, so setting `reasoning` with that backend is a config error. Leave it unset to keep the model's default. Like [retrieval size](#retrieval-size), it trades thoroughness for time-to-first-token, and answers stay grounded either way.
+
+## Analytics
+
+With an [analytics provider](/docs/configuration/analytics) configured, the assistant reports its usage through the same `track()` the page feedback widget uses, so questions land next to your pageviews:
+
+| Event | When | Properties |
+| --- | --- | --- |
+| `ask` | A question is sent | `path`, `questionChars` |
+| `ask_answer` | The answer finishes streaming | `path`, `questionChars`, `ms`, `chars` |
+| `ask_error` | The request fails, breaks, or comes back empty | `path`, `questionChars`, `ms`, `status` |
+
+`path` is the page the reader asked from (the served pathname, so it matches the feedback widget and your pageviews under a `base`), `questionChars` the question's length, `ms` the time from sending the question to the last chunk, and `chars` the answer's length. `status` is the HTTP status: `0` when no response arrived at all (offline, DNS, CORS), and `200` when the response was fine but its stream broke mid-answer — how a provider or credential error surfaces, since the backend has already sent its headers — or delivered nothing. Clearing the conversation mid-answer reports neither outcome.
+
+The question's text never reaches a provider: it is free-form reader input (pasted keys, error logs, names) that would breach most providers' terms and per-value size limits. It travels only on the `blume:track` DOM event, as `question` in `detail.props`, so a listener you write can forward it wherever you decide it belongs. A custom chat UI built on `useAskAI` from `blume/hooks` reports the same events. With no provider configured the built-in provider calls are no-ops, but the `blume:track` event still fires, so a custom integration listening for it receives them.
+
 ## Rate limiting
 
 The `POST /api/ask` endpoint is **unauthenticated** — it has to be, so the in-page assistant can call it. Blume validates each request — rejecting malformed bodies, capping it to 1–40 messages, and accepting only `user`/`assistant` roles so a caller can't inject their own system prompt and repurpose the route as a general LLM proxy — to bound how much a single call can spend against your model, but it can't stop someone from calling the endpoint repeatedly. If cost abuse is a concern, put the route behind a rate limiter — your host's (e.g. Vercel's) edge rate limiting, a middleware, or your model provider's per-key spend limits.

package/docs/configuration/index.mdx

@@ -65,9 +65,11 @@ export default defineConfig({
     },
   },
 
-  // AI — llms.txt, MCP; see the Discoverability section
+  // AI — llms.txt, MCP, the AI catalog; see the Discoverability section
   ai: {
     llmsTxt: true,
+    // AI Catalog / ARD manifest at /.well-known/ai-catalog.json (needs deployment.site)
+    catalog: true,
     // MCP server (needs server output)
     mcp: {
       enabled: false,

package/docs/content/navigation.mdx

@@ -12,6 +12,7 @@ By default the sidebar mirrors your content tree:
 - folders become **groups**, files become **pages**
 - a page's label is its frontmatter `title`; a group's label is the humanized folder name
 - items sort by [numeric prefix](/docs/content), then alphabetically, and a folder's `index` page comes first
+- a folder with an `index` page links its group row to that page, so clicking the section name opens the section's landing page
 
 That's enough for many sites — everything below is opt-in.
 
@@ -133,6 +134,8 @@ sidebar:
   hidden: true
 ```
 
+A folder's `index` page appears both as the group row's link and as the first row inside the group. Hide the index page to keep only the linked header: the group row still opens the landing page, and previous/next links still pass through it.
+
 ## Tabs
 
 Render top-level sections as tabs in the header, useful for splitting a large site into distinct areas — say adapters, an API, and AI guides. A tab is highlighted when the current route falls under its `path`:

package/docs/content/syntax.mdx

@@ -59,6 +59,16 @@ Inline formatting for stressing words, marking deletions, and showing code or ke
 **Bold**, _italic_, ~~strikethrough~~, and `inline code`.
 ```
 
+## Keyboard keys
+
+For shortcuts and keystrokes. A `<kbd>` element renders as the same bordered key badge the search dialog uses, in Markdown, MDX, and inside components like `<Steps>` and `<Callout>`.
+
+Press <kbd>⌘</kbd> <kbd>K</kbd> to open search, or <kbd>Esc</kbd> to close it.
+
+```md
+Press <kbd>⌘</kbd> <kbd>K</kbd> to open search, or <kbd>Esc</kbd> to close it.
+```
+
 ## Superscript and subscript
 
 For footnote markers, ordinals, and scientific or chemical notation inline.

package/docs/discoverability/agent-discovery.mdx

@@ -55,13 +55,14 @@ Agents that probe a site don't know to look for the manifest — so Blume also a
 
 ```http
 Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
+  </.well-known/ai-catalog.json>; rel="ai-catalog"; type="application/ai-catalog+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](/docs/discoverability/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](/docs/discoverability/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.
+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](/docs/discoverability/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](/docs/discoverability/json-api)'s OpenAPI description, `api-catalog` at the [generated API catalog](#api-catalog), and `ai-catalog` at the [AI catalog](#ai-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:
 
@@ -72,6 +73,12 @@ Not every agent enters through the root, though — one following a search resul
   type="application/json"
 />
 <link rel="describedby" href="/llms.txt" type="text/plain" />
+<link
+  rel="ai-catalog"
+  href="/.well-known/ai-catalog.json"
+  type="application/ai-catalog+json"
+/>
+<link rel="ard" href="/.well-known/ard.json" type="application/json" />
 <link rel="alternate" href="/docs/example.md" type="text/markdown" />
 ```
 
@@ -121,6 +128,80 @@ When the site publishes APIs, Blume generates an [RFC 9727](https://www.rfc-edit
 
 A site with no API references, no MCP server, and the [JSON API](/docs/discoverability/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.
 
+## AI catalog
+
+The API catalog lists APIs. The **AI catalog** lists everything an agent could pick up from the site — the MCP server, each published skill, the JSON API, each rendered API reference, and `llms.txt` — in the format agent registries index: an [AI Catalog](https://github.com/Agent-Card/ai-catalog) document at `/.well-known/ai-catalog.json`, which is also the manifest [Agentic Resource Discovery (ARD)](https://agenticresourcediscovery.org/) consumers resolve. Each entry carries a domain-anchored `urn:air:<host>:<namespace>:<name>` identifier, a display name, the artifact's media type, its URL, and a handful of `representativeQueries` — sample questions the resource can answer, which registries embed for semantic search:
+
+```json .well-known/ai-catalog.json
+{
+  "specVersion": "1.0",
+  "host": {
+    "displayName": "Acme",
+    "identifier": "did:web:docs.example.com",
+    "documentationUrl": "https://docs.example.com/"
+  },
+  "entries": [
+    {
+      "identifier": "urn:air:docs.example.com:mcp:acme",
+      "displayName": "Acme",
+      "type": "application/mcp-server-card+json",
+      "url": "https://docs.example.com/.well-known/mcp/server-card.json",
+      "capabilities": [
+        "search_docs",
+        "get_page",
+        "list_pages",
+        "get_navigation"
+      ],
+      "representativeQueries": [
+        "search the Acme documentation",
+        "get a Acme docs page as Markdown",
+        "list every page in the Acme docs"
+      ]
+    },
+    {
+      "identifier": "urn:air:docs.example.com:skill:acme",
+      "displayName": "acme",
+      "type": "application/agent-skills+md",
+      "url": "https://docs.example.com/.well-known/agent-skills/acme/SKILL.md",
+      "representativeQueries": [
+        "load the acme agent skill",
+        "how do I use acme"
+      ]
+    },
+    {
+      "identifier": "urn:air:docs.example.com:api:docs",
+      "displayName": "Acme docs API",
+      "type": "application/vnd.oai.openapi+json",
+      "url": "https://docs.example.com/openapi.json",
+      "representativeQueries": [
+        "fetch a Acme docs page as JSON",
+        "list the pages in the Acme docs",
+        "get the Acme docs navigation tree"
+      ]
+    }
+  ]
+}
+```
+
+ARD's current revision reads the manifest from `/.well-known/ard.json` and calls `ai-catalog.json` the predecessor path, so Blume writes the same document to both, advertises it under both link relations (`ai-catalog` and `ard`) in every page's head, and lists it in `llms.txt` and `agent-readability.json`. The catalog and its `.well-known` neighbors (the API catalog, the MCP discovery files) are served with `Access-Control-Allow-Origin: *` on every build surface, so a registry reading them from another origin isn't blocked.
+
+Entry identifiers are anchored on your domain, so the catalog needs a [`deployment.site`](/docs/deployment) — without one nothing is emitted. It's on by default; `ai.catalog: false` turns it off. The generated queries are derived from the site title and each entry's own description. To write your own for an entry, key them by the identifier's tail (`<namespace>:<name>`):
+
+```ts blume.config.ts
+export default defineConfig({
+  ai: {
+    catalog: {
+      queries: {
+        "mcp:acme": ["how do I install Acme", "search the Acme docs"],
+        "skill:acme": ["set up an Acme project", "write an Acme plugin"],
+      },
+    },
+  },
+});
+```
+
+A list replaces the generated queries for that entry; entries you don't name keep theirs. As everywhere, a `public/.well-known/ai-catalog.json` (or `ard.json`) you ship yourself wins over the generated one.
+
 ## WebMCP
 
 [WebMCP](https://webmachinelearning.github.io/webmcp/) is an emerging browser API that lets a page register tools directly with an agentic browser — no separate server connection needed. Every Blume page registers the docs' read-only surface on the page's model context: `search_docs` (site search), `get_page` (a page's [raw Markdown](/docs/discoverability/markdown)), and `list_pages` (the [`llms.txt`](/docs/discoverability/llms-txt) index). The script is tiny, loads no search machinery until a tool is actually called, and silently no-ops in every browser without the API — which today is all of them outside [Chrome's early preview](https://developer.chrome.com/blog/webmcp-epp). It registers on whichever surface the in-flux spec exposes (`navigator.modelContext` or `document.modelContext`), via `provideContext` or per-tool `registerTool`.

package/docs/discoverability/index.mdx

@@ -37,7 +37,7 @@ Most of this is sharper with an absolute site URL — set [`deployment.site`](/d
 | Raw Markdown mirrors, content negotiation, Copy as Markdown, Open in chat | `/<route>.md` | on | [Markdown for agents](/docs/discoverability/markdown) |
 | JSON API and its OpenAPI description | `/api/docs/…`, `/openapi.json` | on | [JSON API](/docs/discoverability/json-api) |
 | MCP server | `/mcp` | opt-in, server output | [MCP server](/docs/discoverability/mcp) |
-| `agent-readability.json`, `Link` headers, API catalog, WebMCP, skills, Web Bot Auth | site root, `/.well-known/…` | on | [Agent discovery](/docs/discoverability/agent-discovery) |
+| `agent-readability.json`, `Link` headers, API catalog, AI catalog (ARD), WebMCP, skills, Web Bot Auth | site root, `/.well-known/…` | on | [Agent discovery](/docs/discoverability/agent-discovery) |
 
 Every generated file yields to one you ship yourself: drop a `robots.txt`, `sitemap.xml`, `llms.txt`, `openapi.json`, or `agent-readability.json` in `public/` and Blume serves yours in its place.
 

package/docs/discoverability/llms-txt.mdx

@@ -47,7 +47,7 @@ ai: {
 
 ## Generated sections
 
-`llms.txt` closes with two generated sections that need no configuration. **Agent skills** lists each skill published through [`ai.skills`](/docs/discoverability/agent-discovery#skills-discovery) with its description (where a skill says when to use it). **Agent resources** links every machine-readable artifact the build emits — `llms-full.txt`, the per-page [raw Markdown](/docs/discoverability/markdown) mirror, the [MCP server](/docs/discoverability/mcp) and its discovery document, the skills index, the [API catalog](/docs/discoverability/agent-discovery#api-catalog), [`agent-readability.json`](/docs/discoverability/agent-discovery#agent-readability), and the [sitemap](/docs/discoverability/sitemap-and-robots#sitemap) — each only when it exists, so an agent that reads nothing but `llms.txt` still finds the whole surface.
+`llms.txt` closes with two generated sections that need no configuration. **Agent skills** lists each skill published through [`ai.skills`](/docs/discoverability/agent-discovery#skills-discovery) with its description (where a skill says when to use it). **Agent resources** links every machine-readable artifact the build emits — `llms-full.txt`, the per-page [raw Markdown](/docs/discoverability/markdown) mirror, the [MCP server](/docs/discoverability/mcp) and its discovery document, the skills index, the [API catalog](/docs/discoverability/agent-discovery#api-catalog), the [AI catalog](/docs/discoverability/agent-discovery#ai-catalog), [`agent-readability.json`](/docs/discoverability/agent-discovery#agent-readability), and the [sitemap](/docs/discoverability/sitemap-and-robots#sitemap) — each only when it exists, so an agent that reads nothing but `llms.txt` still finds the whole surface.
 
 ## Excluding a page
 

package/docs/reference/frontmatter.mdx

@@ -49,6 +49,8 @@ sidebar:
   display: page
 ```
 
+`hidden` removes the page from the sidebar and from previous/next pagination. On a folder's `index` page it removes only the page's own row: the group row keeps linking to the page, and previous/next links still pass through it.
+
 `display` sets the render mode of the page's folder group ([per-group overrides](/docs/content/navigation#per-group-overrides)) and is only meaningful on a folder's `index` page under the generated sidebar — anywhere else (a non-index page, the content root's own `index` page, or any page under an explicit `navigation.sidebar`) it has no group to configure, and Blume warns with `BLUME_SIDEBAR_DISPLAY_IGNORED`.
 
 ## SEO

package/package.json

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

package/src/ai/agent-readability.ts

@@ -4,6 +4,7 @@ import type { BlumeProject } from "../core/project-graph.ts";
 import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
 import { absoluteUrl } from "../core/site-url.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
+import { AI_CATALOG_PATH, hasAiCatalog } from "./ai-catalog.ts";
 import { hasApiCatalog } from "./api-catalog.ts";
 import { API_PAGES_PATH, API_SEARCH_PATH, OPENAPI_PATH } from "./api/paths.ts";
 
@@ -52,6 +53,7 @@ const askApiUrl = (
 /** The `.well-known` discovery URLs a site can publish. */
 interface WellKnownArtifacts {
   httpMessageSignaturesDirectory?: string;
+  aiCatalog?: string;
   apiCatalog?: string;
   agentSkills?: string;
 }
@@ -138,6 +140,9 @@ const wellKnownArtifacts = (
       "/.well-known/http-message-signatures-directory"
     );
   }
+  if (hasAiCatalog(config)) {
+    artifacts.aiCatalog = abs(AI_CATALOG_PATH);
+  }
   if (hasApiCatalog(config)) {
     artifacts.apiCatalog = abs("/.well-known/api-catalog");
   }