blume 0.5.4 → 0.6.0

package/docs/configuration/ai.mdx

@@ -62,6 +62,25 @@ ai: {
 }
 ```
 
+### Suggested questions
+
+Seed the empty state with a few starter prompts. Each renders as a clickable suggestion — click one to send it — with an optional [Lucide icon](/docs/content/components#icon) beside the label:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    suggestions: [
+      { label: "What is Blume?", icon: "rocket" },
+      { label: "How do I write a docs page?", icon: "file-text" },
+      { label: "How do I configure the theme?", icon: "settings" },
+    ],
+  },
+}
+```
+
+`label` is the question that gets asked; `icon` is optional. Leave `suggestions` unset (or empty) and the panel opens to a plain input.
+
 ### Grounding
 
 Ask AI is **grounded in your docs**. For each question it retrieves the most relevant pages — using the same lexical [Orama](/docs/configuration/search) index that powers on-page search — and injects them into the model's system prompt, so answers come from your content instead of the model's own knowledge. The assistant is told to answer only from the retrieved pages, to say when something isn't covered, and to cite the pages it drew from.
@@ -175,6 +194,43 @@ A static build with `mcp.enabled` fails fast with a message telling you to set `
 claude mcp add --transport http my-docs https://docs.example.com/mcp
 ```
 
+## 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. Unlike the features above, it's on by default:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  agentReadability: true,
+}
+```
+
+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:
+
+```json agent-readability.json
+{
+  "artifacts": {
+    "markdown": {
+      "contentNegotiation": "text/markdown",
+      "pattern": "https://docs.example.com/{route}.md"
+    },
+    "llmsFullTxt": "https://docs.example.com/llms-full.txt",
+    "llmsTxt": "https://docs.example.com/llms.txt",
+    "mcp": {
+      "discovery": "https://docs.example.com/.well-known/mcp.json",
+      "url": "https://docs.example.com/mcp"
+    }
+  },
+  "description": "Docs for the Acme API.",
+  "generator": "blume@1.0.0",
+  "name": "Acme Docs",
+  "site": "https://docs.example.com",
+  "contentUsage": { "search": true, "ai-input": true, "ai-train": true },
+  "repository": "https://github.com/acme/docs"
+}
+```
+
+Set `seo.agentReadability` to `false` to skip it, or ship your own `public/agent-readability.json` to take over — Blume never overwrites a file you place in `public/`.
+
 ## Agent skill
 
 Building a Blume site with the help of a coding agent? Install the Blume [agent skill](https://docs.claude.com/en/docs/claude-code/skills) so it knows how Blume works without you explaining it:

package/docs/configuration/seo.mdx

@@ -154,7 +154,7 @@ Ship your own `public/sitemap.xml` to take over — Blume never overwrites a fil
 
 ## Robots
 
-Blume writes a `robots.txt` that allows all crawlers and adds a `Sitemap:` line pointing to the sitemap when one is available. On by default:
+Blume writes a `robots.txt` that allows all crawlers, declares your [content signals](#content-signals), and adds a `Sitemap:` line pointing to the sitemap when one is available. On by default:
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -164,9 +164,67 @@ seo: {
 
 ```txt robots.txt
 User-agent: *
+Content-Signal: search=yes, ai-input=yes, ai-train=yes
 Allow: /
 
 Sitemap: https://docs.example.com/sitemap.xml
 ```
 
+### Content signals
+
+The `Content-Signal` line — the emerging content-usage convention — declares how AI crawlers may reuse your docs. Blume emits it **on by default with every signal set to `yes`**, matching its stance that docs are open to humans and agents alike:
+
+- `search` — traditional and AI search indexing
+- `aiInput` — grounding / RAG at answer time
+- `aiTrain` — model training
+
+Restrict any signal by setting it to `false`; the ones you leave out stay `yes`:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  contentSignals: {
+    aiTrain: false, // opt out of training, keep search + grounding
+  },
+}
+```
+
+```txt robots.txt
+User-agent: *
+Content-Signal: search=yes, ai-input=yes, ai-train=no
+Allow: /
+```
+
+Set `contentSignals: false` to drop the declaration entirely:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  contentSignals: false,
+}
+```
+
+<TypeTable
+  type={{
+    "seo.contentSignals": {
+      type: "boolean | object",
+      description:
+        "Content-Signal declaration. true or omitted emits all signals as yes; false drops the line; an object sets signals individually.",
+    },
+    "contentSignals.search": {
+      type: "boolean",
+      description: "Allow use for search indexing (search). Default true.",
+    },
+    "contentSignals.aiInput": {
+      type: "boolean",
+      description:
+        "Allow use for AI grounding / RAG at answer time (ai-input). Default true.",
+    },
+    "contentSignals.aiTrain": {
+      type: "boolean",
+      description: "Allow use for AI model training (ai-train). Default true.",
+    },
+  }}
+/>
+
+Content signals express a preference, not access control: they tell well-behaved crawlers how you'd like your content used, and it's on the crawler to honour them.
+
 Ship your own `public/robots.txt` to take over.

package/docs/configuration/theming.mdx

@@ -34,6 +34,8 @@ theme: {
 
 Named presets: `blue` (default), `green`, `orange`, `pink`, `purple`, `red`, and `teal`.
 
+A string applies to both color modes; pass an object for [a different accent per mode](#dark-mode-colors).
+
 ### Radius
 
 `radius` sets the corner rounding shared by cards, code blocks, callouts, and inputs — `none`, `sm`, `md` (default), or `lg`.
@@ -89,18 +91,19 @@ Need a font that isn't listed, or want to drop back to the system stack? Overrid
 
 ### Dark-mode colors
 
-By default light and dark share one `accent`. Set `accentDark` for a different accent in dark mode, and `background` / `backgroundDark` to override the page background per mode:
+`accent` and `background` follow one rule: a string applies to both color modes, and a `{ light, dark }` object sets each mode individually:
 
 ```ts blume.config.ts lineNumbers
 theme: {
-  accent: "blue",
-  accentDark: "teal",        // a different accent in dark mode
-  background: "#ffffff",     // light-mode page background
-  backgroundDark: "#0a0a0a", // dark-mode page background
+  accent: { light: "blue", dark: "teal" },
+  background: {
+    light: "#ffffff",
+    dark: "#0a0a0a",
+  },
 }
 ```
 
-Each takes a named preset or any CSS color, exactly like `accent`.
+Each color takes a named preset or any CSS color. For `background` (and `backgroundImage`) either key can be omitted to override a single mode — `background: { dark: "#0a0a0a" }` keeps the default light background.
 
 ### Action color
 
@@ -114,12 +117,14 @@ theme: {
 
 ### Background image
 
-Set a background image behind your content with `backgroundImage` (and `backgroundImageDark` for a dark variant) — a URL or a path under `public/`:
+Set a background image behind your content with `backgroundImage` — a URL or a path under `public/`. Like the colors, a string applies to both modes and a `{ light, dark }` object sets each mode's image:
 
 ```ts blume.config.ts lineNumbers
 theme: {
-  backgroundImage: "/bg-light.svg",
-  backgroundImageDark: "/bg-dark.svg",
+  backgroundImage: {
+    light: "/bg-light.svg",
+    dark: "/bg-dark.svg",
+  },
 }
 ```
 

package/docs/content/meta.mdx

@@ -1,6 +1,6 @@
 ---
 title: Folder meta
-description: Configure a sidebar group — its title, icon, order, display mode, and page order — with a meta.ts file.
+description: Configure a sidebar group — its title, icon, order, and page order — with a meta.ts file.
 ---
 
 Every folder in your content tree becomes a sidebar group. Drop a `meta.ts` beside its pages to control how that group looks and how its children are ordered. It's entirely optional: without one, the group's label is the humanized folder name and its pages sort by [index, numeric prefix, then alphabetically](/docs/content/navigation#ordering).
@@ -16,7 +16,6 @@ export default defineMeta({
   title: "Guides",
   icon: "book-open",
   order: 2,
-  display: "flat",
   collapsed: false,
   pages: ["configuration", "theming", "deployment"],
 });
@@ -31,25 +30,12 @@ Every field is optional — set only what you want to override.
 | `title` | `string` | The group's label. Defaults to the humanized folder name. |
 | `icon` | `string` | Icon shown next to the label. |
 | `order` | `number` | Position among sibling groups and pages. Lower numbers sort first. |
-| `display` | `"flat" \| "group" \| "page"` | How the group renders in the sidebar. Defaults to `flat`. See [below](#display-modes). |
-| `collapsed` | `boolean` | For `display: "group"`, whether the group starts collapsed. |
+| `collapsed` | `boolean` | Under the [`group` display mode](/docs/content/navigation#display-modes), whether the group starts collapsed. |
 | `pages` | `string[]` | Explicit order for the group's children, by slug. |
 
 The `pages` array lists children by slug — the folder or file name with its numeric prefix and any parentheses stripped (so `01-quickstart.mdx` is `"quickstart"`). Children you leave out still appear, after the listed ones.
 
-## Display modes
-
-`display` controls how a group and its items appear in the sidebar:
-
-- **`flat`** (default) — a non-collapsible header with its pages listed beneath.
-- **`group`** — a collapsible `<details>` disclosure. Pair it with `collapsed` to set the initial state; a group containing the current page always starts open.
-- **`page`** — a single row that, when clicked, slides the sidebar into a sub-panel showing only that group's items, with a back arrow at the top. The panel is route-aware, so landing directly on a page inside the group opens straight to it.
-
-:::tip
-`page` mode keeps deep sections tidy — reach for it when a group has many children and you'd rather drill into it than scroll past it.
-:::
-
-`display` works the same on a group in an [explicit sidebar](/docs/content/navigation#explicit-sidebar) config.
+How groups render — flat headers, collapsible disclosures, or drill-in panels — is a sidebar-wide setting, not per folder: see [display modes](/docs/content/navigation#display-modes).
 
 ## Computed meta
 

package/docs/content/navigation.mdx

@@ -31,7 +31,7 @@ See [Frontmatter](/docs/reference/frontmatter) for the full page schema.
 
 ## Folder groups
 
-Each folder becomes a sidebar group. Drop a [`meta.ts`](/docs/content/meta) beside its pages to set the group's title, icon, order, [display mode](/docs/content/meta#display-modes), and the order of its children:
+Each folder becomes a sidebar group. Drop a [`meta.ts`](/docs/content/meta) beside its pages to set the group's title, icon, order, and the order of its children:
 
 ```ts meta.ts
 import { defineMeta } from "blume";
@@ -43,10 +43,32 @@ export default defineMeta({
 });
 ```
 
-See [Folder meta](/docs/content/meta) for every field, the three display modes, and computing meta at scan time.
+See [Folder meta](/docs/content/meta) for every field and computing meta at scan time.
 
 To group pages _without_ adding a URL segment, use a parenthesized folder name — see [Pages](/docs/content#group-folders).
 
+## Display modes
+
+`navigation.sidebar.display` sets how every sidebar group renders:
+
+```ts blume.config.ts lineNumbers
+navigation: {
+  sidebar: {
+    display: "flat", // "flat" | "group" | "page"
+  },
+}
+```
+
+- **`flat`** (default) — a non-collapsible header with its pages listed beneath. Pages that aren't in any group always list first, above the group sections, so they can't be mistaken for a group's children.
+- **`group`** — a collapsible `<details>` disclosure per group. Pair it with `collapsed` in [folder meta](/docs/content/meta) to set the initial state; a group containing the current page always starts open.
+- **`page`** — each group is a single row that, when clicked, slides the sidebar into a sub-panel showing only that group's items, with a back arrow at the top. The panel is route-aware, so landing directly on a page inside the group opens straight to it.
+
+:::tip
+`page` mode keeps deep sections tidy — reach for it when groups have many children and you'd rather drill into them than scroll past them.
+:::
+
+A group in an [explicit sidebar](#explicit-sidebar) can override the global mode with its own `display`.
+
 ## Ordering
 
 When the sidebar is generated, order is resolved highest priority first:
@@ -112,9 +134,24 @@ navigation: {
 
 Each item takes a `label`, a `path`, and optional `icon`, `description`, and `tag`. `kind` (`dropdown`, `product`, `version`, or `language`) is a hint for how the selector is used; all render the same dropdown.
 
+## Featured links
+
+Pin links to the top of the sidebar, above every section — a blog, a changelog, a contact or support page that should always be one click away. Unlike the generated tree, featured links are **not scoped by tab**: they show on every route, on every breakpoint.
+
+```ts blume.config.ts lineNumbers
+navigation: {
+  featured: [
+    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
+    { label: "Contact", href: "/contact", icon: "headphones" },
+  ],
+}
+```
+
+Each link takes a `label`, an `href`, and an optional `icon` (a [built-in icon](/docs/configuration/customization) name, image path/URL, or inline SVG — the same as anywhere else). An `href` may point anywhere: an external URL opens in a new tab, while an internal route (`/contact`) is validated against your pages at build time, warning you if nothing matches.
+
 ## Explicit sidebar
 
-For full control, define `navigation.sidebar` in config. When it's set, Blume uses it verbatim and skips file-system generation:
+For full control, list explicit items in `navigation.sidebar` — a bare array is shorthand for `sidebar.items`, and the object form combines them with a global [`display`](#display-modes). When items are set, Blume uses them verbatim and skips file-system generation:
 
 ```ts blume.config.ts lineNumbers
 navigation: {
@@ -130,7 +167,7 @@ navigation: {
 }
 ```
 
-Each item is a page route (a string), a group (`label` + `items`), or a link (`label` + `href`). Groups can nest, take a [`display` mode](/docs/content/meta#display-modes), and start `collapsed`.
+Each item is a page route (a string), a group (`label` + `items`), or a link (`label` + `href`). Groups can nest, override the global [`display` mode](#display-modes), and start `collapsed`.
 
 ## Repository link
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -92,12 +92,14 @@
     "citty": "^0.1.6",
     "consola": "^3.4.0",
     "deepmerge": "^4.3.1",
+    "dompurify": "^3.4.11",
     "epub-gen-memory": "^1.1.2",
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "jiti": "^2.4.0",
     "js-yaml": "^4.1.0",
     "katex": "^0.17.0",
+    "marked": "^18.0.5",
     "mermaid": "^11.15.0",
     "pagefind": "^1.3.0",
     "pathe": "^2.0.0",

package/src/ai/agent-readability.ts

@@ -0,0 +1,97 @@
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
+import { buildRssFeeds } from "../deploy/rss.ts";
+
+/** Token map for the machine-readable content-usage echo. */
+const USAGE_TOKENS: [keyof ContentSignalPolicy, string][] = [
+  ["search", "search"],
+  ["aiInput", "ai-input"],
+  ["aiTrain", "ai-train"],
+];
+
+/**
+ * The configured usage preferences as a `{ token: allowed }` object, or null
+ * when the declaration is disabled (`contentSignals: false`). Mirrors the
+ * robots.txt `Content-Signal` line so an agent that reads the manifest instead
+ * of robots.txt sees the same policy.
+ */
+const usagePolicy = (
+  signals: ContentSignals
+): Record<string, boolean> | null => {
+  if (!signals) {
+    return null;
+  }
+  return Object.fromEntries(
+    USAGE_TOKENS.map(([key, token]) => [token, signals[key]] as const)
+  );
+};
+
+/**
+ * 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
+ * scraping HTML. URLs are absolute when a `site` is configured and root-relative
+ * otherwise. Returns null when the manifest is disabled.
+ */
+export const buildAgentReadability = (
+  project: BlumeProject
+): Record<string, unknown> | null => {
+  const { config } = project;
+  if (!config.seo.agentReadability) {
+    return null;
+  }
+
+  const site = config.deployment.site ?? null;
+  // Concatenate rather than `new URL()` so a subpath deployment's base is kept.
+  const abs = (path: string): string =>
+    site ? `${site.replace(/\/+$/u, "")}${path}` : path;
+
+  const artifacts: Record<string, unknown> = {
+    markdown: {
+      contentNegotiation: "text/markdown",
+      pattern: abs("/{route}.md"),
+    },
+  };
+  if (config.ai.llmsTxt) {
+    artifacts.llmsFullTxt = abs("/llms-full.txt");
+    artifacts.llmsTxt = abs("/llms.txt");
+  }
+  if (config.mcp.enabled) {
+    artifacts.mcp = {
+      discovery: abs("/.well-known/mcp.json"),
+      url: abs(config.mcp.route),
+    };
+  }
+  if (config.ai.ask?.enabled) {
+    artifacts.askApi = abs("/api/ask");
+  }
+  if (site && config.seo.sitemap) {
+    artifacts.sitemap = abs("/sitemap.xml");
+  }
+  const feeds =
+    site && config.seo.rss.enabled
+      ? buildRssFeeds(project).map((feed) => abs(feed.path))
+      : [];
+  if (feeds.length > 0) {
+    artifacts.feeds = feeds;
+  }
+
+  const version = project.manifest?.blumeVersion;
+  const manifest: Record<string, unknown> = {
+    artifacts,
+    description: config.description,
+    generator: version ? `blume@${version}` : undefined,
+    name: config.mcp.name ?? config.title,
+    site,
+  };
+
+  const usage = usagePolicy(config.seo.contentSignals);
+  if (usage) {
+    manifest.contentUsage = usage;
+  }
+  if (config.github) {
+    manifest.repository = `https://github.com/${config.github.owner}/${config.github.repo}`;
+  }
+
+  return manifest;
+};

package/src/ai/ask-context.ts

@@ -26,16 +26,77 @@ export interface AskData {
 /** Documents retrieved per question and injected into the system prompt. */
 const MAX_RESULTS = 6;
 /** Characters kept per injected excerpt. */
-const EXCERPT_CHARS = 1500;
+const EXCERPT_CHARS = 2000;
 /** Overall cap on injected documentation characters. */
-const CONTEXT_BUDGET = 8000;
+const CONTEXT_BUDGET = 10_000;
+/** Chars of lead-in kept before the matched region, for heading/sentence context. */
+const EXCERPT_LEAD = 160;
+
+/**
+ * Common words dropped from the retrieval query before locating the relevant
+ * excerpt region, so short filler ("how does…", "what is…") doesn't drag the
+ * window toward incidental matches instead of the meaningful terms.
+ */
+const STOPWORDS = new Set([
+  "about",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "but",
+  "by",
+  "can",
+  "do",
+  "does",
+  "for",
+  "from",
+  "how",
+  "in",
+  "into",
+  "is",
+  "it",
+  "its",
+  "my",
+  "of",
+  "on",
+  "or",
+  "our",
+  "that",
+  "the",
+  "these",
+  "this",
+  "those",
+  "to",
+  "use",
+  "used",
+  "using",
+  "was",
+  "were",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "why",
+  "with",
+  "you",
+  "your",
+]);
+
+/** Distinct, meaningful lowercase terms from a query (drops stopwords). */
+const queryTerms = (query: string): string[] =>
+  [...new Set(query.toLowerCase().match(/[a-z0-9]+/gu))].filter(
+    (term) => term.length >= 2 && !STOPWORDS.has(term)
+  );
 
 /**
  * The grounding preamble. The model is told to answer strictly from the injected
- * excerpts and to cite the pages it used, so answers stay tied to the docs.
+ * excerpts and to cite the pages it used as Markdown links (each excerpt is
+ * headed by `## Title (/route)`), so citations render as real links in the panel.
  */
 const BASE_INSTRUCTION =
-  "You are a helpful documentation assistant for this project. Answer the user's question using ONLY the documentation excerpts below. If the answer is not covered by them, say you don't know and suggest where in the docs to look — do not invent details. Cite the page titles you drew from.";
+  "You are a helpful documentation assistant for this project. Answer the user's question using ONLY the documentation excerpts below. Each excerpt is headed by its page as `## Page Title (/route)`. If the answer is not covered by the excerpts, say you don't know and suggest where in the docs to look — do not invent details. Always cite the pages you drew from, and write every citation as a Markdown link to that page using its route, e.g. [Page Title](/route).";
 
 /** Normalize a page path to a document `route` (`/`, `/a/b`, no trailing slash). */
 const normalizeRoute = (input: string): string => {
@@ -55,10 +116,68 @@ const lastUserMessage = (messages: AskMessage[]): string => {
   return "";
 };
 
-/** Trim a document body to `max` characters, marking truncation with an ellipsis. */
-const excerpt = (content: string, max: number): string => {
+/**
+ * Excerpt the region of `content` most relevant to `query`, not just its head.
+ *
+ * Pages are indexed whole (one document each), so a naive head slice of a long
+ * page returns its intro and misses sections below the fold — the exact failure
+ * where "How does Ask AI work?" retrieves the right page but only sees its
+ * opening paragraph. This centers the window on the densest cluster of query
+ * terms so the injected text is the part that actually answers the question.
+ */
+const relevantExcerpt = (
+  content: string,
+  query: string,
+  max: number
+): string => {
   const trimmed = content.trim();
-  return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed;
+  if (trimmed.length <= max) {
+    return trimmed;
+  }
+  const withEllipsis = (start: number): string => {
+    const slice = trimmed.slice(start, start + max).trim();
+    const prefix = start > 0 ? "…" : "";
+    const suffix = start + max < trimmed.length ? "…" : "";
+    return `${prefix}${slice}${suffix}`;
+  };
+
+  const lower = trimmed.toLowerCase();
+  const positions: number[] = [];
+  for (const term of queryTerms(query)) {
+    let idx = lower.indexOf(term);
+    while (idx !== -1) {
+      positions.push(idx);
+      idx = lower.indexOf(term, idx + term.length);
+    }
+  }
+  // No query terms hit this doc — nothing to center on, so keep the head.
+  if (positions.length === 0) {
+    return withEllipsis(0);
+  }
+
+  // Pick the term hit whose following `max`-char window covers the most hits.
+  // `positions` is non-empty here, so the first window (count ≥ 1) always wins
+  // over the initial 0 and assigns a real offset to `best`.
+  positions.sort((a, b) => a - b);
+  let best = 0;
+  let bestCount = 0;
+  for (const start of positions) {
+    const end = start + max;
+    let count = 0;
+    for (const pos of positions) {
+      if (pos >= end) {
+        break;
+      }
+      if (pos >= start) {
+        count += 1;
+      }
+    }
+    if (count > bestCount) {
+      bestCount = count;
+      best = start;
+    }
+  }
+  return withEllipsis(Math.max(0, best - EXCERPT_LEAD));
 };
 
 /**
@@ -111,7 +230,11 @@ export const createAskContext = (
         return;
       }
       seen.add(doc.route);
-      const body = excerpt(doc.content, Math.min(EXCERPT_CHARS, budget));
+      const body = relevantExcerpt(
+        doc.content,
+        query,
+        Math.min(EXCERPT_CHARS, budget)
+      );
       budget -= body.length;
       sections.push(`## ${doc.title} (${doc.route})${label}\n${body}`);
     };

package/src/ai/ask-data.ts

@@ -6,10 +6,13 @@ import type { AskData } from "./ask-context.ts";
  * Build the grounding snapshot the Ask AI endpoint serves. Like the MCP server,
  * Ask AI is independent of on-page search, so documents are indexed even when the
  * search provider is `none` (`includeWhenDisabled`). `locale` is kept (unlike the
- * MCP snapshot) so retrieval can be filtered to the current page's language.
+ * MCP snapshot) so retrieval can be filtered to the current page's language, and
+ * content is kept as Markdown so grounding sees fenced code examples — the model
+ * answers "what does the config look like?" from the docs instead of declining.
  */
 export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
   const documents = await buildSearchDocuments(project, {
+    content: "markdown",
     includeWhenDisabled: true,
   });
   return {

package/src/astro/generate.ts

@@ -620,6 +620,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
           code,
           withReferenceTabs(
             graph.navigationByLocale[code] ?? {
+              featured: [],
               selectors: [],
               sidebar: [],
               tabs: [],
@@ -633,6 +634,9 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     config: {
       analytics: config.analytics ?? null,
       appleIcon: resolveAppleIcon(project),
+      ask: config.ai.ask?.enabled
+        ? { suggestions: config.ai.ask.suggestions }
+        : null,
       banner: resolveBanner(config),
       codeWrap: config.markdown.code.wrap,
       description: config.description,