blume 0.5.3 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -28,7 +28,8 @@
     "dist",
     "src",
     "bin",
-    "docs"
+    "docs",
+    "skills"
   ],
   "type": "module",
   "types": "./dist/types/index.d.ts",
@@ -70,11 +71,7 @@
     "@astrojs/node": "^11.0.0",
     "@astrojs/react": "^6.0.0",
     "@astrojs/vercel": "^11.0.0",
-    "@iconify-json/fa6-brands": "^1.2.6",
-    "@iconify-json/fa6-regular": "^1.2.4",
-    "@iconify-json/fa6-solid": "^1.2.4",
     "@iconify-json/lucide": "^1.2.115",
-    "@iconify-json/tabler": "^1.2.35",
     "@iconify/types": "^2.0.0",
     "@iconify/utils": "^3.1.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -95,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",
@@ -111,6 +110,7 @@
     "tailwindcss": "^4",
     "tinyglobby": "^0.2.10",
     "typescript": "^5.7.0",
+    "undici": "^8.6.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {

package/skills/blume/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: blume
+description: Build and maintain documentation sites with Blume, the markdown-first docs framework on Astro and Vite. Use when working in a project that depends on `blume`, when scaffolding or configuring a docs site, writing Markdown/MDX content, tuning navigation/search/theming/SEO/AI features, running the `blume` CLI (init, dev, build, eject), or editing `blume.config.ts` and `meta.ts` files.
+---
+
+# Blume
+
+Blume is an open-source, **markdown-first** documentation framework built on Astro and Vite. Drop Markdown or MDX into a folder, run `blume dev`, and get a production-grade docs site — navigation, search, theming, Open Graph images, and a rich component library — with no app boilerplate to write or maintain.
+
+The core idea: **the framework _is_ the template.** There's no starter to clone and no project to own before you've written a word. The only thing you touch is your content. When you outgrow the defaults, you add configuration one file at a time — and you can `blume eject` to a plain Astro project the day you want full control.
+
+## 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.
+- **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.
+
+## Quickstart
+
+Blume needs **Node.js 22 or newer**. From an empty or existing project:
+
+```bash
+npm i blume      # install the package
+blume init       # scaffold: docs/index.mdx + blume.config.ts
+blume dev        # dev server with hot reload
+blume build      # static HTML to dist/, with a local search index
+```
+
+Blume works with any package manager and never requires you to set up Astro or Tailwind yourself.
+
+### Writing a page
+
+Every page is Markdown or MDX with a little frontmatter. The `title` and `description` render as the page heading and intro automatically; built-in components (callouts, cards, tabs, steps, and more) need **no imports**.
+
+```mdx
+---
+title: Introduction
+description: Welcome to my docs.
+---
+
+Welcome! Use **Markdown** and built-in components — no imports required:
+
+:::note Blume ships callouts, cards, tabs, steps, and more. :::
+```
+
+Navigation, search, and page metadata are inferred from your files as you add them.
+
+## What's included
+
+- **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 a hosted MCP server.
+- **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`.
+- **Eject** — `blume eject` produces a standalone Astro project that still uses the `blume` package.
+
+## How it works
+
+The Blume CLI discovers your content, builds a content graph, and generates a hidden Astro project under `.blume/` that it drives for dev and build. The generated runtime is an implementation detail — you write Markdown, Blume handles the rest — until you choose to eject and own it.
+
+## Full documentation
+
+This is a high-level overview. For complete, authoritative docs — configuration reference, every CLI command and flag, component APIs, content authoring, navigation, search, SEO, AI features, theming, and deployment — read the bundled docs in the installed package:
+
+```
+node_modules/blume/docs
+```
+
+Start with `node_modules/blume/docs/index.mdx` (Introduction) and `node_modules/blume/docs/01-quickstart.mdx`, then browse the `configuration/`, `content/`, `reference/`, and `advanced/` sections for specifics.

package/skills/blume-update-docs/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: blume-update-docs
+description: Keep a Blume docs site in sync with the product it documents. Audit recently merged pull requests, changelogs, config schemas, CLI help, and public APIs against the docs content, update only pages that are factually stale, verify the docs build, and open (or update) a maintenance pull request — or report a clean no-op. Use when asked to check docs for drift, refresh stale documentation, run a scheduled docs audit, or keep docs current after a release.
+---
+
+# Update Blume Docs
+
+Blume is a **markdown-first** documentation framework on Astro/Vite: content lives as Markdown/MDX under a content root (default `docs/`), navigation derives from the file tree plus optional `meta.ts` files, and `blume build` validates links, anchors, frontmatter, and routes.
+
+Your job is **docs maintenance, not docs authorship**: find where shipped, user-facing behavior has drifted from what the docs claim, fix exactly that, prove the site still builds, and deliver the result as a pull request. A run that finds nothing actionable ends with a short report and **no branch, no commit, no PR** — prefer a no-op over a noisy PR.
+
+## Ground rules
+
+- **Only document what shipped.** Never invent features, timelines, pricing, APIs, or compatibility claims. Work behind a feature flag is not ready for docs unless the flag is enabled for the documented audience or the repo explicitly documents unreleased behavior.
+- **Facts over polish.** Edit when a command, option, default, route, prop, or workflow is wrong or missing. Skip subjective rewording, marketing polish, restructuring, and formatting-only churn.
+- **Smallest correct diff.** Touch the fewest pages that remove the drift. Preserve the site's voice, frontmatter style, component usage, and `meta.ts` navigation patterns.
+- **Exact source-of-truth wording** for commands, flags, config keys, environment variables, routes, and version numbers — copy them from code, don't paraphrase from memory.
+- **Respect the repo.** Follow `AGENTS.md`/`CLAUDE.md` conventions, don't touch generated output (`.blume/`, `dist/`), and never overwrite unrelated local changes.
+
+## Workflow
+
+1. **Establish context.**
+   - Read the repo's agent/contributor instructions (`AGENTS.md`, `CLAUDE.md`, contribution docs) and honor them.
+   - Locate the docs app and content root: `blume.config.ts` (`content.root`), the directory of `.md`/`.mdx` pages, `meta.ts` files, and the package manager + docs build command.
+   - If this run was configured with a trigger, lookback window, docs path, target branch, or PR policy, honor those. Use the defaults below only where the prompt is silent.
+
+2. **Reuse or create a maintenance branch.**
+   - If an open docs-maintenance PR from a previous run exists (head branch starting with `blume/`), check out and update that branch instead of opening a duplicate.
+   - Otherwise branch from the default branch as `blume/docs-refresh-YYYY-MM-DD`. Create the branch only once you know an edit is needed.
+
+3. **Find drift.** Read `references/audit-checklist.md` for the full source list and change criteria, then:
+   - Review PRs merged into the default branch within the lookback window (default: the last 7 days) and extract the user-facing changes.
+   - Compare those changes — plus changelogs, release notes, config schemas, exported APIs, CLI help, and examples — against the docs content.
+   - Check external links only when a checked page depends on them; prefer official docs and release notes over secondary sources.
+   - Keep notes: what you checked, what changed upstream, and why each edit is (or isn't) needed.
+
+4. **Update the docs.**
+   - Fix the stale pages. Add, rename, or remove `meta.ts` entries when pages are added, renamed, or deleted.
+   - Match the surrounding pages: frontmatter shape, Blume components already in use, code-fence style, root-relative internal links.
+
+5. **Verify.**
+   - Run the docs build (`blume build` or the repo's documented docs QA) — it validates links, anchors, frontmatter, and duplicate routes.
+   - Run lint/format/typecheck when the repo's conventions call for them on docs changes.
+   - Fix failures your edits caused; report pre-existing failures separately instead of fixing them in this PR.
+
+6. **Deliver.**
+   - **Changes made:** commit only the maintenance edits, push the `blume/*` branch, and open or update a PR against the default branch titled like `blume: refresh docs for YYYY-MM-DD`. In the body list sources checked, docs changed, verification commands and results, skipped checks, and residual risk.
+   - **No changes needed:** report the PRs and docs areas checked and the no-op result. Do not create a branch, commit, or PR.
+
+## Resources
+
+- `references/audit-checklist.md` — the source checklist, edit/skip criteria, and Blume-specific editing guidance. Read it before making docs changes.

package/skills/blume-update-docs/references/audit-checklist.md

@@ -0,0 +1,46 @@
+# Audit checklist
+
+Use this checklist to decide whether a docs-maintenance run should make changes.
+
+## Sources to check
+
+- **Repo instructions:** `AGENTS.md`, `CLAUDE.md`, contribution docs, release docs, PR templates, and package scripts.
+- **Blume config:** `blume.config.ts` — `content.root`, navigation (`meta.ts` files, tabs, selectors), site settings, AI/MCP settings, search, OpenAPI/AsyncAPI sources, theme, and export settings.
+- **Public surface area:** exported package entrypoints, config schemas, component props, CLI commands and help text, route handlers, environment variables, and registry items.
+- **User workflows:** quickstarts, examples, migration guides, deployment guides, screenshots, sample projects, and README snippets.
+- **Recent merge signals:** PRs merged within the lookback window (default 7 days), changelogs, release notes, changesets, tags, and package version bumps.
+- **Docs content:** every `.md`/`.mdx` page under the configured content root, plus custom pages and blog/changelog entries.
+- **External dependencies:** official provider docs and release notes for linked integrations — only when the docs mention them or the dependency changed.
+- **Generated docs surfaces:** `llms.txt`, raw Markdown URLs, MCP tools, OpenAPI pages, search, sitemap, robots, RSS, and OG behavior when relevant.
+
+## Change criteria
+
+Make a docs edit when at least one condition is true:
+
+- A command, config option, environment variable, route, CLI flag, component prop, or default value changed.
+- A documented workflow no longer works or misses a required step.
+- A page promises a feature, provider, adapter, or integration the code no longer supports.
+- A new user-facing capability shipped but is absent from the appropriate docs page.
+- A link points at moved, removed, or outdated primary documentation.
+- A changelog or release page needs an entry for shipped user-facing behavior.
+
+Skip the edit when the only available change is subjective polish, wording preference, duplicated information, speculative future work, or behavior still hidden behind a feature flag.
+
+## Blume editing guidance
+
+- Keep frontmatter short and factual; use `title` and `description` consistently with nearby pages. Blume's frontmatter schema is **strict** — unknown keys are build errors.
+- Preserve existing page order and `defineMeta` style; update `pages` arrays when adding, renaming, or removing pages.
+- Use the Blume components already present in the docs (callout directives, steps, cards) instead of inventing new markup patterns.
+- Match nearby code fences: filenames, language tags, and line numbers where the surrounding docs use them.
+- Keep internal links root-relative (`/docs/...`).
+- Do not edit generated `.blume/` or `dist/` output.
+
+## PR notes
+
+Include these sections in the PR body or no-op summary:
+
+- Sources checked
+- Docs changed
+- Verification run (commands and results)
+- Skipped checks, with reasons
+- Remaining risk or follow-up

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

@@ -432,11 +432,16 @@ const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
   if (!logo) {
     return null;
   }
-  const config = typeof logo === "string" ? { light: logo } : logo;
-  const light = config.light ?? config.dark;
-  const dark = config.dark ?? config.light;
-  const alt = config.alt ?? "";
-  const href = config.href ?? "/";
+  const config = typeof logo === "string" ? { image: logo } : logo;
+  // `text` is passed through verbatim: `undefined` lets the brand fall back to
+  // the site title, `""` renders the mark alone (a logo with the wordmark baked
+  // in).
+  const { href, image: source, text } = config;
+  const image = typeof source === "string" ? { light: source } : source;
+  const light = image?.light ?? image?.dark;
+  const dark = image?.dark ?? image?.light;
+  const alt = image?.alt ?? "";
+  const brandHref = href ?? "/";
 
   if (light && light === dark && light.toLowerCase().endsWith(".svg")) {
     const rel = light.replace(/^\//u, "");
@@ -445,10 +450,10 @@ const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
       join(project.context.root, rel),
     ].find((path) => existsSync(path));
     if (file) {
-      return { alt, href, svg: readFileSync(file, "utf-8") };
+      return { alt, href: brandHref, svg: readFileSync(file, "utf-8"), text };
     }
   }
-  return { alt, dark, href, light };
+  return { alt, dark, href: brandHref, light, text };
 };
 
 /**
@@ -615,7 +620,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
           code,
           withReferenceTabs(
             graph.navigationByLocale[code] ?? {
-              chromeVariants: [],
+              featured: [],
               selectors: [],
               sidebar: [],
               tabs: [],
@@ -629,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,
@@ -648,7 +656,6 @@ export const buildRuntimeData = (project: BlumeProject): string => {
             })),
           }
         : null,
-      icons: config.icons,
       imageZoom: config.markdown.imageZoom,
       logo: resolveLogo(project),
       mcp: config.mcp.enabled
@@ -974,9 +981,9 @@ export const generateRuntime = async (
   const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
   // Only emit a project-scanning `docs` collection when a filesystem source
-  // actually feeds it. Bridge mode has just the staged Mintlify source, so the
-  // `docs` glob would otherwise scan (and watch) the whole project root for
-  // nothing — see contentConfigTemplate.
+  // actually feeds it. An all-staged project (openapi/notion/…) has only staged
+  // sources, so the `docs` glob would otherwise scan (and watch) the whole
+  // project root for nothing — see contentConfigTemplate.
   const hasFilesystemSource = project.sources.some((source) => !source.staged);
 
   const structural = await Promise.all([

package/src/astro/integration.ts

@@ -1,13 +1,10 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { fileURLToPath } from "node:url";
 
 import type { AstroIntegration } from "astro";
 
-import type { AssetMount } from "../core/assets.ts";
 import { enrichDiagnostic } from "../core/diagnostics.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
-import { copyAssetMounts, serveAssetMounts } from "./static-assets.ts";
 
 /** The dev server's HMR channel — either `.ws` (Vite ≤5) or `.hot` (Vite 6+). */
 interface OverlayChannel {
@@ -77,11 +74,6 @@ export interface BlumeIntegrationOptions {
   contentRoutes: string[];
   /** Configured `deployment.base`, stripped from dev URLs before matching. */
   base?: string;
-  /**
-   * `content.assets` mounts: top-level dirs served at the site root in dev and
-   * copied into the build output, so root-served assets need no relocation.
-   */
-  assets?: AssetMount[];
 }
 
 /**
@@ -118,12 +110,6 @@ export const blumeIntegration = (
   options: BlumeIntegrationOptions
 ): AstroIntegration => ({
   hooks: {
-    "astro:build:done": async ({ dir }) => {
-      // Copy in-place asset mounts into the build output, mirroring publicDir.
-      if (options.assets?.length) {
-        await copyAssetMounts(options.assets, fileURLToPath(dir));
-      }
-    },
     "astro:config:setup": ({ injectRoute }) => {
       for (const page of options.pages) {
         injectRoute({
@@ -143,13 +129,6 @@ export const blumeIntegration = (
         handle: negotiateMarkdown(new Set(options.contentRoutes), options.base),
         route: "",
       });
-      // Serve `content.assets` mounts (Astro only serves publicDir in dev).
-      if (options.assets?.length) {
-        server.middlewares.stack.unshift({
-          handle: serveAssetMounts(options.assets),
-          route: "",
-        });
-      }
     },
   },
   name: "blume",