blume 1.7.2 → 1.7.3

package/dist/cli/{chunk-xhtpx3ff.js → chunk-rqy0s5wh.js}

@@ -2,28 +2,28 @@
 import {
   ensureGitignore
 } from "./chunk-yzhm0j9q.js";
-import"./chunk-61j18dwk.js";
+import"./chunk-7s8hm3b6.js";
 import {
   commandMeta,
   logger
 } from "./index.js";
 import {
   refuseIfDevRunning
-} from "./chunk-exeeb35e.js";
-import"./chunk-tqa1s0k8.js";
-import"./chunk-88by27n5.js";
-import"./chunk-5n7t497w.js";
-import"./chunk-wjt80jps.js";
-import"./chunk-hdm2dkd2.js";
-import"./chunk-450a7rcr.js";
+} from "./chunk-vacwm2hv.js";
+import"./chunk-ct47dqpx.js";
+import"./chunk-0qymqwzz.js";
+import"./chunk-1jefwnfs.js";
+import"./chunk-k79xp7av.js";
+import"./chunk-js7saxwm.js";
+import"./chunk-bf6bt1xt.js";
 import"./chunk-jq5n4avg.js";
-import"./chunk-ejjx8znq.js";
-import"./chunk-688e0dde.js";
+import"./chunk-ps4m1xh4.js";
+import"./chunk-nn13znc2.js";
 import"./chunk-vrfp10qk.js";
 import {
   prepareProject
-} from "./chunk-vkrsvbr5.js";
-import"./chunk-jbj4qhfw.js";
+} from "./chunk-esphfr8p.js";
+import"./chunk-garjf5z9.js";
 
 // src/cli/commands/check.ts
 import { existsSync } from "node:fs";
@@ -84,4 +84,4 @@ export {
 };
 
 //# debugId=785FB9FFBD7A7B1164756E2164756E21
-//# sourceMappingURL=chunk-xhtpx3ff.js.map
+//# sourceMappingURL=chunk-rqy0s5wh.js.map

package/dist/cli/{chunk-30e87n55.js → chunk-rz9jmfhz.js}

@@ -9,13 +9,13 @@ import {
   reportDiagnosticsJson,
   reportDiagnostics
 } from "./index.js";
-import"./chunk-61j18dwk.js";
+import"./chunk-7s8hm3b6.js";
 import {
   scanProject
-} from "./chunk-hdm2dkd2.js";
+} from "./chunk-1jefwnfs.js";
 import {
   serverFeatures
-} from "./chunk-jbj4qhfw.js";
+} from "./chunk-garjf5z9.js";
 
 // src/cli/commands/doctor.ts
 import { readFileSync } from "node:fs";
@@ -105,4 +105,4 @@ export {
 };
 
 //# debugId=8F001C9B0DBCC9F964756E2164756E21
-//# sourceMappingURL=chunk-30e87n55.js.map
+//# sourceMappingURL=chunk-rz9jmfhz.js.map

package/dist/cli/{chunk-exeeb35e.js → chunk-vacwm2hv.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   resolveRuntimeDir
-} from "./chunk-61j18dwk.js";
+} from "./chunk-7s8hm3b6.js";
 import {
   logger
 } from "./index.js";
@@ -133,4 +133,4 @@ var refuseIfDevRunning = (root, action, options = {}) => {
 export { readDevLock, DevLockHeldError, acquireDevLock, updateDevLockPort, describeDevLock, refuseIfDevRunning };
 
 //# debugId=1007843429DAE30664756E2164756E21
-//# sourceMappingURL=chunk-exeeb35e.js.map
+//# sourceMappingURL=chunk-vacwm2hv.js.map

package/dist/cli/{chunk-8cd8tj54.js → chunk-yg63d42r.js}

@@ -17,24 +17,24 @@ import {
   writeAgentReport,
   fixPrompt,
   launchAgent
-} from "./chunk-9bkjd11x.js";
+} from "./chunk-0xjyb285.js";
 import {
   deployStaticDir,
   examplesRouteBase
-} from "./chunk-ejjx8znq.js";
+} from "./chunk-ps4m1xh4.js";
 import {
   frontmatter_default,
   scanProject
-} from "./chunk-hdm2dkd2.js";
+} from "./chunk-1jefwnfs.js";
 import {
   SITE_INFERRING_ADAPTERS
-} from "./chunk-61j18dwk.js";
+} from "./chunk-7s8hm3b6.js";
 import {
   gradeExternal,
   probeAll
 } from "./chunk-vh9w1sgp.js";
-import"./chunk-88by27n5.js";
-import"./chunk-tqa1s0k8.js";
+import"./chunk-ct47dqpx.js";
+import"./chunk-0qymqwzz.js";
 import {
   normalizeBasePath,
   normalizePath,
@@ -1957,4 +1957,4 @@ export {
 };
 
 //# debugId=59B0974018DD3C3464756E2164756E21
-//# sourceMappingURL=chunk-8cd8tj54.js.map
+//# sourceMappingURL=chunk-yg63d42r.js.map

package/dist/cli/index.js

@@ -400,21 +400,21 @@ var main = defineCommand({
     version: getBlumeVersion()
   },
   subCommands: {
-    add: lazyCommand(commandMeta.add, () => import("./chunk-3w7b2vcx.js"), "addCommand"),
-    audit: lazyCommand(commandMeta.audit, () => import("./chunk-8cd8tj54.js"), "auditCommand"),
-    build: lazyCommand(commandMeta.build, () => import("./chunk-fmceyezb.js"), "buildCommand"),
-    check: lazyCommand(commandMeta.check, () => import("./chunk-xhtpx3ff.js"), "checkCommand"),
-    dev: lazyCommand(commandMeta.dev, () => import("./chunk-12dxjqk7.js"), "devCommand"),
-    doctor: lazyCommand(commandMeta.doctor, () => import("./chunk-30e87n55.js"), "doctorCommand"),
-    eject: lazyCommand(commandMeta.eject, () => import("./chunk-mqb2ka8m.js"), "ejectCommand"),
-    eval: lazyCommand(commandMeta.eval, () => import("./chunk-t3tj0dgr.js"), "evalCommand"),
-    init: lazyCommand(commandMeta.init, () => import("./chunk-mt76t7dj.js"), "initCommand"),
-    "mcp-stdio": lazyCommand(commandMeta["mcp-stdio"], () => import("./chunk-n9sra6sy.js"), "mcpStdioCommand"),
-    preview: lazyCommand(commandMeta.preview, () => import("./chunk-hs3gbh8p.js"), "previewCommand"),
-    sync: lazyCommand(commandMeta.sync, () => import("./chunk-eevwt1sc.js"), "syncCommand"),
-    translate: lazyCommand(commandMeta.translate, () => import("./chunk-9he6crym.js"), "translateCommand"),
-    validate: lazyCommand(commandMeta.validate, () => import("./chunk-aztttvb3.js"), "validateCommand"),
-    version: lazyCommand(commandMeta.version, () => import("./chunk-cvky9gb2.js"), "versionCommand")
+    add: lazyCommand(commandMeta.add, () => import("./chunk-e7f42gdj.js"), "addCommand"),
+    audit: lazyCommand(commandMeta.audit, () => import("./chunk-yg63d42r.js"), "auditCommand"),
+    build: lazyCommand(commandMeta.build, () => import("./chunk-ex56aa81.js"), "buildCommand"),
+    check: lazyCommand(commandMeta.check, () => import("./chunk-rqy0s5wh.js"), "checkCommand"),
+    dev: lazyCommand(commandMeta.dev, () => import("./chunk-cjtn640a.js"), "devCommand"),
+    doctor: lazyCommand(commandMeta.doctor, () => import("./chunk-rz9jmfhz.js"), "doctorCommand"),
+    eject: lazyCommand(commandMeta.eject, () => import("./chunk-5093q3n7.js"), "ejectCommand"),
+    eval: lazyCommand(commandMeta.eval, () => import("./chunk-ahnw3kxw.js"), "evalCommand"),
+    init: lazyCommand(commandMeta.init, () => import("./chunk-5qk08vmp.js"), "initCommand"),
+    "mcp-stdio": lazyCommand(commandMeta["mcp-stdio"], () => import("./chunk-3r45185y.js"), "mcpStdioCommand"),
+    preview: lazyCommand(commandMeta.preview, () => import("./chunk-b27xqwn9.js"), "previewCommand"),
+    sync: lazyCommand(commandMeta.sync, () => import("./chunk-bvwwhd84.js"), "syncCommand"),
+    translate: lazyCommand(commandMeta.translate, () => import("./chunk-5g0w1e2c.js"), "translateCommand"),
+    validate: lazyCommand(commandMeta.validate, () => import("./chunk-97r59kpr.js"), "validateCommand"),
+    version: lazyCommand(commandMeta.version, () => import("./chunk-4x36ddpw.js"), "versionCommand")
   }
 });
 loadEnvFiles(process.cwd());

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

@@ -680,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 {
     /**
@@ -734,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

@@ -370,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>;
@@ -622,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>;

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

@@ -235,6 +235,20 @@ ai: {
 
 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.2",
+  "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");
   }