blume 0.7.0 → 0.8.0

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export type { ComponentMarkdown, ComponentMarkdownChild, ComponentMarkdownContext, } from "./ai/component-markdown.ts";
 export { defineConfig } from "./core/config.ts";
 export type { BlumeBanner, BlumeData, BlumeDataConfig, BlumeDataI18n, BlumeDataLocale, BlumeFavicon, BlumeFeed, BlumeLogo, BlumeRoute, } from "./core/data.ts";
 export { defineComponents } from "./core/define-components.ts";

package/dist/types/openapi/references.d.ts

@@ -0,0 +1,60 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { NavTab } from "../core/types.ts";
+/**
+ * Pure resolution of the configured API reference blocks into concrete routes,
+ * labels, and a renderer choice — no file IO, so the content source, the nav
+ * tabs, the Scalar page generator, and the `blume:openapi` data module all share
+ * one source of truth. Kept free of any Astro/template imports so `core` can
+ * depend on it without a cycle.
+ */
+export type ReferenceKind = "openapi" | "asyncapi";
+/** Who renders a reference: Blume's own UI, or the embedded Scalar SPA. */
+export type ReferenceRenderer = "blume" | "scalar";
+/** Per-block display options for the Blume renderer. */
+export interface ReferenceDisplay {
+    /** Code-sample languages shown per operation. */
+    codeSamples: string[];
+    /** Whether nested schema rows start expanded. */
+    expandSchemas: boolean;
+}
+/** A spec source resolved to a concrete route, label, and renderer. */
+export interface ReferenceSource {
+    kind: ReferenceKind;
+    renderer: ReferenceRenderer;
+    /** Unique token derived from the route; the `<Operation source>` / data key. */
+    slug: string;
+    /** Normalized route the reference mounts at, e.g. `/reference`. */
+    route: string;
+    /**
+     * Site-wide `basePath` the rendered pages are mounted under (`""` when
+     * none). Kept separate from `route` — the content pipeline applies it to
+     * staged entries itself — so consumers prefix only the URLs they emit.
+     */
+    basePath: string;
+    label: string;
+    /** Local path or `http(s)` URL, verbatim from config. */
+    spec: string;
+    /** Per-block Scalar theme name override, if any (Scalar renderer only). */
+    theme?: string;
+    /** Display options carried through to the Blume renderer. */
+    display: ReferenceDisplay;
+    /**
+     * Warnings recorded while deduping — another source's route collided with
+     * this one and was dropped. Surfaced as diagnostics when the source loads.
+     */
+    collisions?: string[];
+}
+export declare const slugify: (text: string) => string;
+/** Normalize a configured route to a single leading slash, no trailing slash. */
+export declare const normalizeRoute: (route: string) => string;
+/**
+ * Resolve every enabled reference. OpenAPI honors its `renderer` (Blume's own UI
+ * by default); AsyncAPI is always rendered by Scalar for now.
+ */
+export declare const resolveReferences: (config: ResolvedConfig) => ReferenceSource[];
+/** Nav tabs (header links) for every reference, regardless of renderer. */
+export declare const referenceTabs: (config: ResolvedConfig) => NavTab[];
+/** Blume-rendered OpenAPI references, deduped by route (first wins). */
+export declare const blumeReferences: (config: ResolvedConfig) => ReferenceSource[];
+/** Whether any reference is Scalar-rendered (gates the `@scalar/astro` dep + pages). */
+export declare const hasScalarReferences: (config: ResolvedConfig) => boolean;

package/docs/01-quickstart.mdx

@@ -6,7 +6,7 @@ sidebar:
   order: 1
 ---
 
-Go from an empty folder to a running docs site in a few commands. Blume needs **Node.js 22 or newer** and a `docs/` folder with at least one `.md` or `.mdx` file — there's nothing else to set up.
+Go from an empty folder to a running docs site in a few commands. Blume needs **Node.js 22.12 or newer** and a `docs/` folder with at least one `.md` or `.mdx` file — there's nothing else to set up.
 
 ## Install and run
 
@@ -20,7 +20,10 @@ Go from an empty folder to a running docs site in a few commands. Blume needs **
 
   </Step>
   <Step title="Scaffold a project">
-    `blume init` creates the minimum surface: a content folder and a config file.
+    `blume init` asks a few questions — where to create the project, what your
+    docs site is called, which template, and where your content lives — then
+    scaffolds the minimum surface: a content folder and a config file. Pass
+    `--yes` to skip the prompts and take the defaults.
 
     ```bash
     blume init

package/docs/02-deployment.mdx

@@ -10,11 +10,11 @@ sidebar:
 
 `blume build` compiles your docs to plain HTML, CSS, and a local search index in `dist/`. There's no server to run — point any static host at the folder.
 
-| Setting          | Value         |
-| ---------------- | ------------- |
-| Build command    | `blume build` |
-| Output directory | `dist`        |
-| Node version     | 22 or newer   |
+| Setting          | Value          |
+| ---------------- | -------------- |
+| Build command    | `blume build`  |
+| Output directory | `dist`         |
+| Node version     | 22.12 or newer |
 
 These settings work on Vercel, Netlify, Cloudflare Pages, GitHub Pages, Amazon S3 + CloudFront, or any bucket or CDN. Make sure `blume` is a dependency so the host can run the build.
 
@@ -88,7 +88,7 @@ deployment: {
 }
 ```
 
-Choosing an adapter pulls in the matching Astro adapter automatically:
+The `vercel` and `node` adapters ship with Blume — choosing one just works. The `netlify` and `cloudflare` adapters must be installed in your project (e.g. `bun add -d @astrojs/netlify`); the CLI warns you if the package is missing:
 
 | Adapter      | Package               | Use for                              |
 | ------------ | --------------------- | ------------------------------------ |
@@ -97,7 +97,7 @@ Choosing an adapter pulls in the matching Astro adapter automatically:
 | `node`       | `@astrojs/node`       | Self-hosted Node servers, containers |
 | `cloudflare` | `@astrojs/cloudflare` | Cloudflare Workers and Pages         |
 
-On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching adapter automatically for server output — set `output: "server"` and deploy. Set `adapter` explicitly to override the detected value, or when self-hosting with `node`.
+On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching adapter automatically for server output — set `output: "server"` and deploy (on Netlify and Cloudflare, install the adapter package too). Set `adapter` explicitly to override the detected value, or when self-hosting with `node`.
 
 A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The `node` adapter produces a standalone server you can run directly.
 
@@ -126,7 +126,7 @@ When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it'
 | Feature | Variable |
 | --- | --- |
 | Ask AI (AI Gateway) | `AI_GATEWAY_API_KEY` (or Vercel OIDC) |
-| Ask AI (OpenRouter / OpenAI-compatible) | the provider's `apiKeyEnv` |
+| Ask AI (other providers) | the provider's default key env var (`OPENROUTER_API_KEY`, `LLMGATEWAY_API_KEY`, `INKEEP_API_KEY`), or your configured `apiKeyEnv` |
 | Mixedbread search | `MIXEDBREAD_API_KEY` |
 
 Set them in `.env.local` for local dev and in your host's environment for production. Build-time secrets for search-index sync (Algolia, Orama Cloud, Typesense) are warned about separately during the sync step.

package/docs/03-faq.mdx

@@ -79,26 +79,26 @@ Once the opening `:::note` fence is joined to the prose, it's no longer a direct
 
 ### Why it happens
 
-This is a bug in oxfmt's Markdown formatter (inherited from Prettier's Markdown printer — see [prettier/prettier#19040](https://github.com/prettier/prettier/pull/19040)). When it wraps prose, it treats the `:::` fence lines as ordinary text and joins them with the adjacent line, breaking the directive. It affects every container directive — `:::note`, `:::tip`, `:::warning`, `:::danger`, `:::success`.
+This is a bug in oxfmt's Markdown formatter (inherited from Prettier's Markdown printer — see [prettier/prettier#19040](https://github.com/prettier/prettier/pull/19040)). When it wraps prose, it treats the `:::` fence lines as ordinary text and joins them with the adjacent line, breaking the directive. It affects every container directive type — `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger`, `:::success`.
 
 We reported it upstream in [oxc-project/oxc#24096](https://github.com/oxc-project/oxc/issues/24096); until it's fixed there, the patch below is the workaround.
 
 ### The fix
 
-Patch oxfmt so it preserves the line break that sits directly against a `:::` fence. Blume ships exactly this patch in its own repo, and you can apply the same one in any project.
+Patch oxfmt so it preserves the line break that sits directly against a `:::` fence. Blume ships the same fix in its own repo, and you can apply it in any project.
 
-1. Save the patch as `patches/oxfmt@0.57.0.patch`:
+1. Save the patch as `patches/oxfmt@0.58.0.patch`:
 
-   ```diff patches/oxfmt@0.57.0.patch
-   diff --git a/dist/markdown-B5hFVJKQ.js b/dist/markdown-B5hFVJKQ.js
-   index 58322b247b263f87975c2a97eecfe0b97d7143c4..0f39f1901603026a391c6d343cb838dfaccbfd03 100644
-   --- a/dist/markdown-B5hFVJKQ.js
-   +++ b/dist/markdown-B5hFVJKQ.js
-   @@ -1141,7 +1141,14 @@ function Yf(e, r, t) {
-    		case "sentence": return Yi(e, t);
-    		case "word": return Li(e);
+   ```diff patches/oxfmt@0.58.0.patch
+   diff --git a/dist/markdown-BjyDFyaO.js b/dist/markdown-BjyDFyaO.js
+   index 1905aa7563e612808426e26f1ed28bebbef3456f..42bb9f66829068676c5697fc9fc39279bf937f3e 100644
+   --- a/dist/markdown-BjyDFyaO.js
+   +++ b/dist/markdown-BjyDFyaO.js
+   @@ -4830,7 +4830,43 @@ function lu(e, t, r) {
+    		case "sentence": return Mh(e, r);
+    		case "word": return t.parser !== "mdx" ? Vh(e, t) : Gh(e);
     		case "whitespace": {
-   -			let { next: i } = e, u = i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/u.test(i.value) ? "never" : r.proseWrap;
+   -			let { next: i } = e, u = i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(i.value) && !ME(e) && !(t.proseWrap === "preserve" && zE(e)) ? "never" : t.proseWrap;
    +			let { next: i, previous: oxfmtFencePrev } = e;
    +			// Preserve line breaks that sit directly against a `:::` container
    +			// directive fence, so `proseWrap: "never"` keeps the opening/closing
@@ -106,8 +106,37 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    +			// breaks the directive). Ordinary prose still wraps per proseWrap.
    +			// See prettier/prettier#19040.
    +			let oxfmtIsFence = (w) => w != null && typeof w.value === "string" && w.value.startsWith(":::");
-   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtIsFence(i) ? "preserve" : i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/u.test(i.value) ? "never" : r.proseWrap;
-    			return qt(e, n.value, u);
+   +			// A titled directive (`:::warning[Heads up]`) parses its `[title]` as a
+   +			// linkReference between two sentence nodes at the paragraph level: the
+   +			// fence word ends the sentence before the reference, and the body's
+   +			// leading newline opens the sentence after it. So when this whitespace
+   +			// starts its sentence, climb to the paragraph and check whether the two
+   +			// preceding siblings are a (link) reference and a sentence ending in a
+   +			// `:::` fence word.
+   +			let oxfmtPrevIsTitledFence = !1;
+   +			if (oxfmtFencePrev == null && e.index === 0 && e.grandparent != null && Array.isArray(e.grandparent.children)) {
+   +				let oxfmtSibs = e.grandparent.children, oxfmtSentIdx = oxfmtSibs.indexOf(e.parent);
+   +				if (oxfmtSentIdx >= 2) {
+   +					let oxfmtLink = oxfmtSibs[oxfmtSentIdx - 1], oxfmtBefore = oxfmtSibs[oxfmtSentIdx - 2];
+   +					let oxfmtLastWord = oxfmtBefore && oxfmtBefore.type === "sentence" && Array.isArray(oxfmtBefore.children) ? oxfmtBefore.children[oxfmtBefore.children.length - 1] : null;
+   +					oxfmtPrevIsTitledFence = oxfmtLink != null && (oxfmtLink.type === "linkReference" || oxfmtLink.type === "link") && oxfmtIsFence(oxfmtLastWord);
+   +				}
+   +			}
+   +			// The plain-markdown parser keeps a titled fence's `[title]` as literal
+   +			// words, so the whole directive is one sentence. For a newline
+   +			// whitespace, walk back to the start of its visual line within the
+   +			// sentence; a line led by a `:::` word is a fence whose break must stay.
+   +			if (!oxfmtPrevIsTitledFence && e.node.value.includes("\n") && e.parent != null && Array.isArray(e.parent.children)) {
+   +				let oxfmtLineFirst = null;
+   +				for (let oxfmtJ = e.index - 1; oxfmtJ >= 0; oxfmtJ--) {
+   +					let oxfmtSib = e.parent.children[oxfmtJ];
+   +					if (oxfmtSib.type === "whitespace" && typeof oxfmtSib.value === "string" && oxfmtSib.value.includes("\n")) break;
+   +					oxfmtLineFirst = oxfmtSib;
+   +				}
+   +				oxfmtPrevIsTitledFence = oxfmtIsFence(oxfmtLineFirst);
+   +			}
+   +			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtPrevIsTitledFence || oxfmtIsFence(i) ? "preserve" : i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/.test(i.value) && !ME(e) && !(t.proseWrap === "preserve" && zE(e)) ? "never" : t.proseWrap;
+    			return ou(e, n.value, u, !1, t);
     		}
     		case "emphasis": {
    ```
@@ -117,7 +146,7 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    ```json package.json
    {
      "patchedDependencies": {
-       "oxfmt@0.57.0": "patches/oxfmt@0.57.0.patch"
+       "oxfmt@0.58.0": "patches/oxfmt@0.58.0.patch"
      }
    }
    ```
@@ -128,5 +157,6 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    bun install
    ```
 
-:::warning[Version-pinned] The patch targets oxfmt `0.57.0` — its diff references a file hashed to that build (`dist/markdown-B5hFVJKQ.js`). When you bump oxfmt, regenerate the patch (e.g. `bun patch oxfmt`) or check whether the upstream fix has landed and the patch is no longer needed.
+:::warning[Version-pinned]
+The patch targets a specific oxfmt build — its diff references a file whose name is hashed per release (`dist/markdown-*.js`). When you bump oxfmt, regenerate the patch (e.g. `bun patch oxfmt`) or check whether the upstream fix has landed and the patch is no longer needed.
 :::

package/docs/advanced/custom-pages.mdx

@@ -74,7 +74,7 @@ The module exposes:
       type: "BlumeDataConfig",
       required: true,
       description:
-        "Resolved site settings: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, search, i18n, mcp, og, analytics, feedback, structuredData, codeWrap, and imageZoom.",
+        "Resolved site settings: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, search, i18n, mcp, ask, og, analytics, feedback, structuredData, toc, codeThemes, codeWrap, and imageZoom.",
     },
     navigation: {
       type: "Navigation",

package/docs/advanced/skills.mdx

@@ -18,7 +18,7 @@ npx skills add haydenbleasel/blume
 `blume-update-docs` keeps your docs in sync with the product they document. On each run — typically from a schedule you configure in your agent runner — it audits recently merged PRs, changelogs, config schemas, and CLI help against the docs content, updates only pages that are factually stale (feature-flagged work is ignored), verifies with `blume build`, and opens or updates a `blume/*` pull request. If nothing drifted, it reports a clean no-op instead of opening a noisy PR.
 
 ```bash
-npx skills use haydenbleasel/blume@blume-update-docs
+npx skills add haydenbleasel/blume --skill blume-update-docs
 ```
 
 Blume doesn't host the automation — wire the skill into a scheduled task in Claude Code, a Codex or Cursor automation, or plain cron, with permission to read repo history and open PRs. A typical weekly prompt:

package/docs/configuration/ai.mdx

@@ -17,23 +17,62 @@ ai: {
 
 While enabled, `blume build` writes two files to the root of your site:
 
-- **`/llms.txt`** — a compact index: your site title and description, then a linked list of every page with its summary.
+- **`/llms.txt`** — a compact index: your site title and description, then a linked list of every page with its summary, organized into sections that mirror your sidebar — folders and groups become headings, so an agent sees the docs' structure, not one flat blob.
 - **`/llms-full.txt`** — the entire corpus: each page's full Markdown body, with its source URL, in one file.
 
 Draft pages are excluded. Set [`deployment.site`](/docs/deployment) so the links and source URLs resolve to absolute addresses.
 
+`llmsTxt` also takes an object form with knobs for what the files include. If your [API reference](/docs/advanced/api-reference) documents a placeholder or example spec, set `openapi: false` to keep its generated pages out of both files:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  llmsTxt: {
+    enabled: true, // default
+    openapi: false, // exclude generated API reference pages
+  },
+}
+```
+
+To take full control of either file, add your own `llms.txt` or `llms-full.txt` to your `public/` folder. Like a custom favicon, it's picked up automatically and ships in place of the generated file — override one and Blume still generates the other.
+
 ## Raw Markdown
 
 Append `.md` or `.mdx` to any page's URL to fetch its raw Markdown source — perfect for LLMs, coding agents, and "copy as Markdown" workflows. It's available for every page, in dev and production, with no configuration.
 
-| URL               | Returns                 |
-| ----------------- | ----------------------- |
-| `/quickstart`     | The rendered page       |
-| `/quickstart.md`  | The raw Markdown source |
-| `/quickstart.mdx` | The raw Markdown source |
+| URL               | Returns                                   |
+| ----------------- | ----------------------------------------- |
+| `/quickstart`     | The rendered page                         |
+| `/quickstart.md`  | Plain Markdown, with components converted |
+| `/quickstart.mdx` | The raw MDX source, exactly as written    |
 
 Nested routes work the same way (`/content/syntax.md`), and the home page is served at `/index.md`.
 
+The `.md` variant _downlevels_ components to plain Markdown for consumers that can't interpret JSX: `<TypeTable>` becomes a Markdown table, `<Callout>` a labeled blockquote, `<Steps>` an ordered list, `<Tabs>` bold-labeled sections, and `<YouTube>` a link. Anything that can't be converted faithfully — a custom component, or a prop computed from an import — is left as-is, and component markup inside fenced code blocks is never touched. The same conversion applies to `llms-full.txt` and the MCP server's `get_page` tool, so every agent-facing surface reads clean Markdown. When you want the untransformed source, use the `.mdx` variant.
+
+### Custom component serializers
+
+Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes) and its `children` (already downleveled to Markdown), and returns the replacement — or `null` to leave the JSX as-is:
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+import type { ComponentMarkdown } from "blume";
+
+const chart: ComponentMarkdown = ({ props }) =>
+  `![${props.title}](/charts/${props.slug}.png)`;
+
+export default defineConfig({
+  ai: {
+    markdownComponents: {
+      Chart: chart,
+    },
+  },
+});
+```
+
+For container components, `childComponents("Name")` extracts direct children by tag — the same way the built-in `<Steps>` serializer collects its `<Step>` items. A same-name entry replaces a built-in serializer, so you can restyle how `<Callout>` downlevels — or return `null` to opt one out entirely.
+
+Serializers live in `blume.config.ts`, not `components.tsx`: the config file is executed at build time, while the components file is only statically analyzed (it may import `.astro` files, which can't run outside the site build). Your components themselves stay registered in `components.tsx` exactly as before — `markdownComponents` only adds their agent-facing Markdown form.
+
 ## Copy as Markdown
 
 Every page carries a **Copy as Markdown** action — in the [page actions](/docs/content/navigation#page-actions) beneath the table of contents — that copies the page's raw Markdown to the clipboard. It's the same source served at the [`.md` URL](#raw-markdown) above, ready to paste into an LLM, an issue, or your notes. It's available on every page, in dev and production, with no configuration.
@@ -46,7 +85,7 @@ The **Open in chat** action opens the current page in an AI assistant — v0, Ch
 
 Like Copy as Markdown, it needs no setup. The assistant fetches the page over its public URL, so it works as soon as the page is deployed.
 
-To embed a ready-to-copy prompt inline in your content — rather than a whole-page action — use the [Prompt component](/docs/content/components#prompt), which renders a labelled row with a **Copy prompt** button and an optional open-in-Cursor link.
+To embed a ready-to-copy prompt inline in your content — rather than a whole-page action — use the [Prompt component](/docs/content/components#prompt), which renders a labeled row with a **Copy prompt** button and an optional open-in-Cursor link.
 
 ## Ask AI
 
@@ -172,7 +211,7 @@ mcp: {
 | `name`         | title   | Server name shown to clients (defaults to title). |
 | `instructions` | —       | Optional system hint passed to connecting agents. |
 
-The server exposes four read-only tools — `search_docs`, `get_page`, `list_pages`, and `get_navigation` — and publishes discovery documents at `/.well-known/mcp.json` and `/.well-known/mcp/server-card.json`. Each page's **Connect to MCP** menu offers copy-and-go install for Claude Code, Cursor, and VS Code (shown once [`deployment.site`](/docs/deployment) is set).
+The server exposes read-only tools — `search_docs`, `get_page`, `list_pages`, and `get_navigation` — and publishes discovery documents at `/.well-known/mcp.json` and `/.well-known/mcp/server-card.json`. Each page's **Connect to MCP** menu offers copy-and-go install for Claude Code, Cursor, VS Code, and Codex (shown once [`deployment.site`](/docs/deployment) is set).
 
 `search_docs` runs its own full-text index, so it works regardless of your [search](/docs/configuration/search) provider — and even when search is set to `none`. The MCP server is a separate feature from on-page search.
 
@@ -196,7 +235,7 @@ 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:
+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. Like `llms.txt`, it's on by default:
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -241,4 +280,4 @@ npx skills add haydenbleasel/blume
 
 The skill teaches the agent what Blume is and how to scaffold, write, and configure a site, and points it at the full docs bundled in the installed package (`node_modules/blume/docs`).
 
-It's one of the [agent skills Blume ships](/docs/advanced/skills), alongside skills for migrating an existing docs site to Blume and keeping docs in sync with your product from a scheduled agent run.
+It's one of the [agent skills Blume ships](/docs/advanced/skills), alongside a skill for keeping docs in sync with your product from a scheduled agent run.

package/docs/configuration/customization.mdx

@@ -154,3 +154,14 @@ blume eject --yes
 ```
 
 Eject is a one-way step: the hidden `.blume/` runtime becomes a normal Astro app you own and can modify directly. The `blume` package stays importable, so you keep its components, theme, and Markdown processors.
+
+### What eject leaves behind
+
+After ejecting, your `build` script runs plain `astro build` — the site itself builds the same, but the artifacts `blume build` layered on top are no longer produced. The eject command warns about the ones your config actually uses. To keep them:
+
+- **Pagefind search index** — with `search.provider: "pagefind"`, the search UI loads the index from the built site, so search breaks in production until you index it yourself. Install `pagefind` as a devDependency and index after each build: `"build": "astro build && pagefind --site dist"`.
+- **Hosted search sync** — a hosted provider's index is no longer pushed on build; re-upload your search records after each build with the provider's API or CLI.
+- **sitemap.xml** — recreate it with the standard [@astrojs/sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/) integration.
+- **robots.txt** — ship your own as `public/robots.txt`.
+- **llms.txt / llms-full.txt and agent-readability.json** — write them by hand (or generate them in a build step of your own) and serve them from `public/`.
+- **Platform redirect files** — `_redirects` and `vercel.json` are no longer emitted for static builds. Your redirects still work as Astro-generated meta-refresh pages, or you can move them into your host's own config.

package/docs/configuration/index.mdx

@@ -189,6 +189,24 @@ content: {
 
 Static assets live in `public/` — a file at `public/logo.png` is served at `/logo.png`, so a reference like `![](/images/create.png)` resolves against `public/images/create.png`.
 
+## GitHub
+
+Point Blume at your repository with `github`. It powers the header [repository link](/docs/content/navigation#repository-link) and the **Edit on GitHub** and **Give feedback** [page actions](/docs/content/navigation#page-actions):
+
+```ts blume.config.ts lineNumbers
+github: {
+  owner: "acme",
+  repo: "docs",
+}
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `owner` | — | GitHub account or organization that owns the repository. |
+| `repo` | — | Repository name. |
+| `branch` | `"main"` | Branch that edit links point at. |
+| `dir` | — | Path from the repo root to the project root (for monorepos). |
+
 ## Last modified
 
 Show a "Last updated on …" line at the bottom of each page. Off by default; set `lastModified` to `true` to derive each page's date from its git history:
@@ -248,7 +266,13 @@ The on-this-page outline is on by default and lists `H2`–`H3` headings. Turn i
 ```ts blume.config.ts
 export default defineConfig({
   toc: false, // hide it everywhere
-  // …or narrow the range:
+});
+```
+
+Or narrow the heading range instead:
+
+```ts blume.config.ts
+export default defineConfig({
   toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
 });
 ```
@@ -261,8 +285,8 @@ Each of these has its own guide. The config field is the entry point:
 | --- | --- | --- |
 | `theme` | Accent color, corner radius, fonts, light/dark mode | [Theming](/docs/configuration/theming) |
 | `navigation` | Explicit sidebar and header tabs | [Navigation](/docs/content/navigation) |
-| `search` | Provider (Orama or Pagefind) and indexing | [Search](/docs/configuration/search) |
-| `markdown` | Opt-in Markdown features like math | [Syntax](/docs/content/syntax) |
+| `search` | Provider (Orama, Pagefind, Algolia, and more) and indexing | [Search](/docs/configuration/search) |
+| `markdown` | Markdown rendering options — code blocks, heading anchors, image zoom | [Syntax](/docs/content/syntax) |
 | `ai` | `llms.txt`, Ask AI, and the MCP server | [AI](/docs/configuration/ai) |
 | `mcp` | Hosted MCP server for coding agents | [AI](/docs/configuration/ai#mcp-server) |
 | `analytics` | Vercel, PostHog, and custom scripts | [Analytics](/docs/configuration/analytics) |

package/docs/configuration/seo.mdx

@@ -5,7 +5,7 @@ sidebar:
   label: SEO
 ---
 
-Blume handles the discoverability layer for you: page metadata, social share images, feeds, and structured data. The three configurable features live under the `seo` key in `blume.config.ts`; metadata is driven by your content.
+Blume handles the discoverability layer for you: page metadata, social share images, feeds, and structured data. The configurable features live under the `seo` key in `blume.config.ts`; metadata is driven by your content.
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -225,6 +225,6 @@ seo: {
   }}
 />
 
-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.
+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 honor them.
 
 Ship your own `public/robots.txt` to take over.

package/docs/content/components.mdx

@@ -428,7 +428,7 @@ A single row with a label and a copy button. The `description` (Markdown) is the
 
 ## Visibility
 
-Show or hide content by audience. `for="web"` renders only on the site; `for="agents"` targets the generated Markdown (`llms.txt`) that AI agents read.
+Show or hide content by audience. `for="web"` renders only on the site; `for="agents"` targets the agent-facing Markdown that AI agents read (`llms-full.txt` and each page's `.md` mirror).
 
 <Visibility for="web">
   This note appears on the website but is omitted from the agent-facing

package/docs/content/i18n.mdx

@@ -108,7 +108,7 @@ When i18n is on, a language switcher appears in the header automatically, genera
 
 Blume ships built-in translations for its own interface chrome — “On this page”, “Search”, “Edit on GitHub”, and the rest — so a locale with a built-in pack gets translated UI out of the box. **You only translate your content.**
 
-Packs ship for 36 languages — Arabic, Bengali, Bulgarian, Catalan, Chinese (Simplified and Traditional), Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian, Persian, Polish, Portuguese (and Brazilian Portuguese), Romanian, Russian, Serbian, Slovak, Spanish, Swedish, Thai, Turkish, Ukrainian, and Vietnamese. They're community-maintained — open a PR to add a locale or sharpen a translation.
+Packs ship for over 30 languages — Arabic, Bengali, Bulgarian, Catalan, Chinese (Simplified and Traditional), Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian, Persian, Polish, Portuguese (and Brazilian Portuguese), Romanian, Russian, Serbian, Slovak, Spanish, Swedish, Thai, Turkish, Ukrainian, and Vietnamese. They're community-maintained — open a PR to add a locale or sharpen a translation.
 
 Missing or unshipped strings fall back to the default locale, then to English. To override a string or supply your own language, set `i18n.ui`, keyed by locale:
 

package/docs/content/navigation.mdx

@@ -147,7 +147,7 @@ navigation: {
 }
 ```
 
-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.
+Each link takes a `label`, an `href`, and an optional `icon` (a [built-in icon](/docs/content/components#icon) 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
 
@@ -196,10 +196,10 @@ A right-rail outline is generated automatically from each page's `##` and `###`
 
 Below the table of contents, every page shows a set of quick actions:
 
-- **Edit this page on GitHub** — links straight to the source file. Appears once you set [`github`](/docs/configuration) in your config.
+- **Edit on GitHub** — links straight to the source file. Appears once you set [`github`](/docs/configuration) in your config.
 - **Scroll to top** — smoothly returns to the top of long pages.
 - **Give feedback** — opens a prefilled GitHub issue with an optional reaction and note (also requires `github`).
 
-Three more hand the page to AI tools — **Copy as Markdown**, **Open in chat**, and **Ask AI about this page** — covered in [AI](/docs/configuration/ai#copy-as-markdown).
+Others hand the page to AI tools — **Copy as Markdown** and **Open in chat** — covered in [AI](/docs/configuration/ai#copy-as-markdown).
 
 With [`export`](/docs/configuration/export) on, an **Export** action also lets readers download the page as a PDF or EPUB.

package/docs/content/sources.mdx

@@ -159,7 +159,7 @@ Two flags control how remote content is fetched and what's included:
 blume dev --preview      # author workflow: see drafts live
 blume build --preview    # render a full preview build
 blume sync               # refresh remote content now
-blume sync --force        # ...ignoring any cached snapshot
+blume sync --force       # ...ignoring any cached snapshot
 ```
 
 ## Custom sources

package/docs/content/syntax.mdx

@@ -345,11 +345,13 @@ Your docs built successfully and are ready to deploy.
 
 Flag something that needs care to avoid a mistake or surprising behavior.
 
-:::warning[Heads up] Switching to `output: "server"` requires an adapter before you can deploy.
+:::warning[Heads up]
+Switching to `output: "server"` requires an adapter before you can deploy.
 :::
 
 ```md
-:::warning[Heads up] Switching to `output: "server"` requires an adapter before you can deploy.
+:::warning[Heads up]
+Switching to `output: "server"` requires an adapter before you can deploy.
 :::
 ```
 

package/docs/index.mdx

@@ -19,9 +19,9 @@ Drop Markdown or MDX into a folder, run `blume dev`, and get a production-grade
 
 ## Why Blume exists
 
-Docs should be fast, AI-ready and require zero configuration — down to not needing a starter template at all. Some docs tools hand you an entire codebase to maintain before you've written a word. Others build the template around your content, but lock you in to their managed service.
+Docs should be fast, AI-ready, and zero-config — down to not needing a starter template at all. Some docs tools hand you an entire codebase to maintain before you've written a word. Others build the template around your content, but lock you in to their managed service.
 
-Blume takes the best of both worlds. The framework is the template, so the only thing you ever touch is your content. When you want to customize, you can start replacing the built-in components, modifying the single configuration file or even ejecting if you want the Astro site directly.
+Blume takes the best of both worlds. The framework is the template, so the only thing you ever touch is your content. When you want to customize, you can start by replacing the built-in components, modifying the single configuration file, or even ejecting if you want the Astro site directly.
 
 ## What makes Blume different
 

package/docs/reference/cli.mdx

@@ -11,7 +11,7 @@ blume <command> [options]
 
 | Command            | Description                                      |
 | ------------------ | ------------------------------------------------ |
-| `blume init`       | Scaffold a minimal project.                      |
+| `blume init [dir]` | Scaffold a project (interactive by default).     |
 | `blume dev`        | Start the dev server with hot reload.            |
 | `blume build`      | Build the static (or server) site.               |
 | `blume preview`    | Preview the last build.                          |
@@ -24,7 +24,9 @@ blume <command> [options]
 
 ## Common flags
 
-- `blume init --content-dir <dir> --yes` — set the content folder (default `docs`) and skip prompts.
+- `blume init` — in a terminal, walks you through a few questions (where to create the project, site name, template, content sources); each flag below pre-answers its question.
+- `blume init --yes` — skip the prompts and scaffold with defaults (also the behavior in CI or when stdin isn't a terminal).
+- `blume init --content-dir <dir>` — set the content folder (default `docs`).
 - `blume init --template docs|api|sdk|changelog` — scaffold from a starter (API reference, SDK, or changelog instead of the plain docs seed).
 - `blume init --package-manager npm|pnpm|yarn|bun` — tailor the printed next-steps to your package manager.
 - `blume init --eject` — scaffold, then eject to a standalone Astro project (falls back to guiding you through `blume eject` when dependencies aren't installed yet).
@@ -53,9 +55,9 @@ blume <command> [options]
 `blume dev` serves a live Astro server rooted at the generated `.blume/` runtime and regenerates it on every change. `blume build` and `blume check` regenerate the _same_ `.blume/`, so running either while the dev server is live would corrupt it — both refuse with an error and exit non-zero:
 
 ```
-A `blume dev` server is running against .blume; building would corrupt it.
-Stop the dev server, or re-run with --isolated to build/verify against
-.blume-verify without touching it.
+A `blume dev` server is running at http://localhost:3000; building would
+corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
+--isolated to build/verify against .blume-verify without touching it.
 ```
 
 The `--isolated` flag is the escape hatch. It relocates the entire generated runtime (and, for `build`, its output `dist/`) to a sibling `.blume-verify/` directory, so the verification never writes anything the dev server — or your real `dist/` — depends on:
@@ -66,7 +68,7 @@ blume check --isolated   # fast: type-check the .astro/config changes
 blume build --isolated   # thorough: full production render into .blume-verify/dist
 ```
 
-`check --isolated` is the quick path (Astro type + template diagnostics, no `dist/`); `build --isolated` is the heavier one that also catches runtime render errors. Isolated builds skip the deploy post-steps (search index, hosted-provider sync, `llms.txt`, sitemap/robots, redirects) — a verify only needs to confirm the site compiles and renders, not publish it. Blume adds `.blume-verify/` to your `.gitignore` automatically.
+`check --isolated` is the quick path (Astro type + template diagnostics, no `dist/`); `build --isolated` is the heavier one that also catches runtime render errors. Isolated builds skip the deploy post-steps (search index, hosted-provider sync, `llms.txt`, sitemap/robots, redirects) — a verify only needs to confirm the site compiles and renders, not publish it. `--analyze` and the `--budget-js`/`--budget-css` gates still run, measured against the isolated output. Blume adds `.blume-verify/` to your `.gitignore` automatically.
 
 This is especially useful when a coding agent needs to verify changes while you keep the dev server open. To make plain `blume build`/`blume check` isolate without the flag — for example in an agent's shell — set `BLUME_RUNTIME_DIR` to the runtime directory to use: