blume 0.2.0 → 0.4.0

package/docs/advanced/custom-pages.mdx

@@ -3,10 +3,7 @@ title: Custom Pages
 description: Mount fully custom .astro routes alongside your docs and read your site's config, navigation, and content from the blume:data module.
 ---
 
-Most of a Blume site is Markdown, but sometimes you need a route that _isn't_ a
-doc — a landing page, a pricing page, a hand-built blog or changelog index, or an
-interactive dashboard. Drop an `.astro` file under your **pages** folder and
-Blume mounts it as a real route, right alongside your content.
+Most of a Blume site is Markdown, but sometimes you need a route that _isn't_ a doc — a landing page, a pricing page, a hand-built blog or changelog index, or an interactive dashboard. Drop an `.astro` file under your **pages** folder and Blume mounts it as a real route, right alongside your content.
 
 ## Add a page
 
@@ -20,19 +17,13 @@ import data from "blume:data";
 <h1>Pricing for {data.config.title}</h1>
 ```
 
-`blume dev` picks it up immediately and `blume build` prerenders it to static
-HTML. The folder name is configurable with [`content.pages`](/docs/configuration#content)
-(default `"pages"`).
+`blume dev` picks it up immediately and `blume build` prerenders it to static HTML. The folder name is configurable with [`content.pages`](/docs/configuration#content) (default `"pages"`).
 
-Custom pages keep their original location on disk, so relative imports, component
-imports, and [`getStaticPaths`](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths)
-all work exactly as they do in a plain Astro project — Blume mounts each file
-where it sits rather than copying it.
+Custom pages keep their original location on disk, so relative imports, component imports, and [`getStaticPaths`](https://docs.astro.build/en/reference/routing-reference/#getstaticpaths) all work exactly as they do in a plain Astro project — Blume mounts each file where it sits rather than copying it.
 
 ## Files and routes
 
-Each file's path under the pages folder becomes its route. `index` maps to the
-parent folder, and dynamic `[param]` segments are preserved:
+Each file's path under the pages folder becomes its route. `index` maps to the parent folder, and dynamic `[param]` segments are preserved:
 
 | File                      | Route         |
 | ------------------------- | ------------- |
@@ -41,14 +32,11 @@ parent folder, and dynamic `[param]` segments are preserved:
 | `pages/blog/[slug].astro` | `/blog/:slug` |
 | `pages/changelog.astro`   | `/changelog`  |
 
-A custom page **wins** over a generated route at the same path. Adding
-`pages/changelog.astro`, for example, replaces Blume's
-[generated changelog timeline](/docs/advanced/changelog) with your own.
+A custom page **wins** over a generated route at the same path. Adding `pages/changelog.astro`, for example, replaces Blume's [generated changelog timeline](/docs/advanced/changelog) with your own.
 
 ## Reading site data
 
-Import `blume:data` to read the same resolved config, navigation, routes, and
-feeds the rest of the site uses:
+Import `blume:data` to read the same resolved config, navigation, routes, and feeds the rest of the site uses:
 
 ```astro pages/all-pages.astro lineNumbers
 ---
@@ -69,9 +57,7 @@ import data from "blume:data";
 </ul>
 ```
 
-Inside a Blume project the module is typed automatically. You can also pull the
-shape in explicitly — for typed helpers, props, or your own tsconfig — with
-`import type { BlumeData } from "blume"`:
+Inside a Blume project the module is typed automatically. You can also pull the shape in explicitly — for typed helpers, props, or your own tsconfig — with `import type { BlumeData } from "blume"`:
 
 ```ts
 import type { BlumeData, BlumeRoute } from "blume";
@@ -134,9 +120,7 @@ The module exposes:
   }}
 />
 
-`routes` carries page metadata but not frontmatter like `type` or `date`. To
-build a list filtered by content type — a blog or changelog index — pair it with
-Astro's `docs` content collection, which holds the frontmatter:
+`routes` carries page metadata but not frontmatter like `type` or `date`. To build a list filtered by content type — a blog or changelog index — pair it with Astro's `docs` content collection, which holds the frontmatter:
 
 ```astro pages/blog/index.astro lineNumbers
 ---
@@ -167,14 +151,46 @@ const posts = (await getCollection("docs"))
 </ul>
 ```
 
+## Runtime helpers
+
+`blume/runtime` bundles the common data patterns so you don't reach into `blume:data` internals.
+
+**`getBlumeCollection(data, query?)`** selects content routes — filtered by collection, locale, or path prefix, with drafts and hidden pages excluded and the result sorted by path — which is exactly what a custom index needs:
+
+```astro pages/blog/index.astro lineNumbers
+---
+import data from "blume:data";
+import { getBlumeCollection } from "blume/runtime";
+
+const posts = getBlumeCollection(data, { prefix: "/blog" });
+---
+
+<ul>
+  {posts.map((post) => (
+    <li><a href={post.path}>{post.title}</a></li>
+  ))}
+</ul>
+```
+
+**`<BlumePage>`** renders a content entry's body inside a custom page, with Blume's built-in MDX components (callouts, cards, steps…) already wired in — for featuring a doc on a landing page or building a bespoke index that shows real content:
+
+```astro pages/index.astro lineNumbers
+---
+import BlumePage from "blume/components/BlumePage.astro";
+import data from "blume:data";
+import { getBlumeCollection } from "blume/runtime";
+
+const [intro] = getBlumeCollection(data, { prefix: "/docs" });
+---
+
+{intro && <BlumePage id={intro.entryId} />}
+```
+
+Pass `components` to add your own overrides or islands (which live in the generated runtime and aren't imported by default), and `collection` to read from a collection other than `"docs"`.
+
 ## Using the site layout
 
-`RootLayout` gives a custom page the full docs chrome — header, sidebar, search,
-TOC, and theme — by wrapping it in the same 3-column grid the generated pages
-use. For a landing or marketing page that grid is in the way, so reach for
-**`PageLayout`** instead: it provides the document shell, header, theme, and
-fonts, then a single full-width `<slot />` (no sidebar, no prose, no TOC). An
-optional `footer` slot renders after `<main>`:
+`RootLayout` gives a custom page the full docs chrome — header, sidebar, search, TOC, and theme — by wrapping it in the same 3-column grid the generated pages use. For a landing or marketing page that grid is in the way, so reach for **`PageLayout`** instead: it provides the document shell, header, theme, and fonts, then a single full-width `<slot />` (no sidebar, no prose, no TOC). An optional `footer` slot renders after `<main>`:
 
 ```astro pages/index.astro lineNumbers
 ---
@@ -206,17 +222,22 @@ const { config } = data;
 </PageLayout>
 ```
 
-Passing `siteUrl` (and `ogEnabled`) derives the page's `canonical` and a
-generated `og:image` automatically: Blume renders an Open Graph card for every
-static custom page — the home included, the most-shared URL — served at
-`/og/<route>.png` (`/og/index.png` for `/`). The home card uses the site title
-with the description as its eyebrow; a deeper page is titled from its last path
-segment. Set `ogImage` or `canonical` explicitly to override.
+Passing `siteUrl` (and `ogEnabled`) derives the page's `canonical` and a generated `og:image` automatically: Blume renders an Open Graph card for every static custom page — the home included, the most-shared URL — served at `/og/<route>.png` (`/og/index.png` for `/`). The home card uses the site title with the description as its eyebrow; a deeper page is titled from its last path segment. Set `ogImage` or `canonical` explicitly to override either. `ogImage` takes a root-relative path — a file in `public/`, resolved against [`deployment.site`](/docs/deployment) to the absolute URL crawlers need — or an external URL, which passes through untouched:
+
+```astro pages/index.astro lineNumbers
+<PageLayout
+  siteUrl={config.site}
+  ogEnabled={config.og.enabled}
+  ogImage="/opengraph-image.png"
+  page={{ title: config.title }}
+>
+  <!-- page content -->
+</PageLayout>
+```
+
+Only this page changes — every other route keeps its generated card — so it's how you give the home page alone a bespoke share image.
 
-`page.title` is used verbatim as the document title (no `- siteTitle` suffix),
-since marketing pages usually set their own. To give a custom page the full docs
-chrome instead — sidebar, TOC, and all — wrap it in `RootLayout`, the layout the
-generated pages use. Pull the required props straight from `blume:data`:
+`page.title` is used verbatim as the document title (no `- siteTitle` suffix), since marketing pages usually set their own. To give a custom page the full docs chrome instead — sidebar, TOC, and all — wrap it in `RootLayout`, the layout the generated pages use. Pull the required props straight from `blume:data`:
 
 ```astro pages/pricing.astro lineNumbers
 ---
@@ -239,24 +260,13 @@ import data from "blume:data";
 </RootLayout>
 ```
 
-:::note
-`RootLayout` is part of the generated runtime, so its props can change between
-releases. When you want a layout that's fully yours,
-[`blume eject`](/docs/configuration/customization#eject) turns `.blume/` into a
-standard Astro project you own outright.
-:::
+:::note `RootLayout` is part of the generated runtime, so its props can change between releases. When you want a layout that's fully yours, [`blume eject`](/docs/configuration/customization#eject) turns `.blume/` into a standard Astro project you own outright. :::
 
 ## 404 page
 
-Blume ships a default **not found** page out of the box: a centered "404" message
-wrapped in the site chrome (header, search, theme), served for any unmatched URL.
-`blume build` writes it to `404.html`, which static hosts serve automatically, and
-`blume dev` shows it for unknown routes.
+Blume ships a default **not found** page out of the box: a centered "404" message wrapped in the site chrome (header, search, theme), served for any unmatched URL. `blume build` writes it to `404.html`, which static hosts serve automatically, and `blume dev` shows it for unknown routes.
 
-To replace it with your own, add a `pages/404.astro`. It owns the `/404` route the
-same way `pages/changelog.astro` takes over the changelog — your page wins and the
-default is dropped. Build it like any other custom page, in `PageLayout` or
-`RootLayout`:
+To replace it with your own, add a `pages/404.astro`. It owns the `/404` route the same way `pages/changelog.astro` takes over the changelog — your page wins and the default is dropped. Build it like any other custom page, in `PageLayout` or `RootLayout`:
 
 ```astro pages/404.astro lineNumbers
 ---
@@ -280,16 +290,11 @@ import data from "blume:data";
 </PageLayout>
 ```
 
-To keep the default design but change its wording — including for other languages
-— override the `notFound` [UI strings](/docs/content/i18n) (`title`, `description`,
-`home`) via `i18n.ui`.
+To keep the default design but change its wording — including for other languages — override the `notFound` [UI strings](/docs/content/i18n) (`title`, `description`, `home`) via `i18n.ui`.
 
 ## Interactive pages
 
-Custom pages are ordinary Astro, so you can drop in React (or any framework)
-[islands](/docs/configuration/customization#react-islands) with a hydration directive.
-React switches on automatically the moment your project contains a `.tsx` or
-`.jsx` file.
+Custom pages are ordinary Astro, so you can drop in React (or any framework) [islands](/docs/configuration/customization#interactive-islands) with a hydration directive. React switches on automatically the moment your project contains a `.tsx` or `.jsx` file.
 
 <CardGroup cols={2}>
   <Card

package/docs/configuration/ai.mdx

@@ -3,15 +3,11 @@ title: AI
 description: Machine-readable docs with llms.txt and an optional in-page Ask AI assistant.
 ---
 
-Blume has several opt-in AI features: machine-readable docs for external tools
-(`llms.txt`), an in-page **Ask AI** assistant, and a hosted **MCP server** for
-coding agents. Everything is off by default, and static docs stay fully static
-until you turn a feature on.
+Blume has several opt-in AI features: machine-readable docs for external tools (`llms.txt`), an in-page **Ask AI** assistant, and a hosted **MCP server** for coding agents. Everything is off by default, and static docs stay fully static until you turn a feature on.
 
 ## llms.txt
 
-Emit machine-readable versions of your docs that coding agents and chat
-assistants can consume:
+Emit machine-readable versions of your docs that coding agents and chat assistants can consume:
 
 ```ts blume.config.ts lineNumbers
 ai: {
@@ -21,19 +17,14 @@ ai: {
 
 With this on, `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-full.txt`** — the entire corpus: each page's full Markdown body, with
-  its source URL, in one file.
+- **`/llms.txt`** — a compact index: your site title and description, then a linked list of every page with its summary.
+- **`/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.
+Draft pages are excluded. Set [`deployment.site`](/docs/deployment) so the links and source URLs resolve to absolute addresses.
 
 ## 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.
+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                 |
 | ----------------- | ----------------------- |
@@ -41,38 +32,25 @@ for every page, in dev and production, with no configuration.
 | `/quickstart.md`  | The raw Markdown source |
 | `/quickstart.mdx` | The raw Markdown source |
 
-Nested routes work the same way (`/content/syntax.md`), and the home page is
-served at `/index.md`.
+Nested routes work the same way (`/content/syntax.md`), and the home page is served at `/index.md`.
 
 ## 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.
+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.
 
 ## Open in chat
 
-The **Open in chat** action opens the current page in an AI assistant — v0,
-ChatGPT, Claude, T3 Chat, Scira, or Cursor — pre-filled with a prompt that points
-it at the page's raw Markdown so it can answer questions about what you're
-reading:
+The **Open in chat** action opens the current page in an AI assistant — v0, ChatGPT, Claude, T3 Chat, Scira, or Cursor — pre-filled with a prompt that points it at the page's raw Markdown so it can answer questions about what you're reading:
 
-> Read `https://your-site/this-page.md` so I can ask you questions about this
-> page.
+> Read `https://your-site/this-page.md` so I can ask you questions about this page.
 
-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.
+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 labelled row with a **Copy prompt** button and an optional open-in-Cursor link.
 
 ## Ask AI
 
-Add an assistant that answers reader questions in an in-page chat panel, backed
-by a streaming server endpoint and the [AI SDK](https://ai-sdk.dev):
+Add an assistant that answers reader questions in an in-page chat panel, backed by a streaming server endpoint and the [AI SDK](https://ai-sdk.dev):
 
 ```ts blume.config.ts lineNumbers
 ai: {
@@ -84,10 +62,17 @@ ai: {
 }
 ```
 
+### 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.
+
+The page the reader is currently on is added to the context first and used to scope retrieval to that page's language, so answers stay relevant to where they are in the docs. Retrieval runs at request time from a snapshot baked into the build, so it works regardless of your [search](/docs/configuration/search) provider — even when search is set to `none` — and needs no configuration.
+
+Grounding is on for every backend except **[Inkeep](#backends)**, which runs its own retrieval over the content you've indexed in its dashboard.
+
 ### Server output required
 
-Ask AI is a server route (`POST /api/ask`), so it can't run on a static build.
-Switch to server output and pick an adapter:
+Ask AI is a server route (`POST /api/ask`), so it can't run on a static build. Switch to server output and pick an adapter:
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -96,28 +81,21 @@ deployment: {
 }
 ```
 
-A static build with Ask AI enabled fails fast with a message telling you to set
-`deployment.output` to `server`. See [Deployment](/docs/deployment) for the adapters.
+A static build with Ask AI enabled fails fast with a message telling you to set `deployment.output` to `server`. See [Deployment](/docs/deployment) for the adapters.
 
 ### Backends
 
-By default Ask AI routes through the **Vercel AI Gateway**: `model` is a
-`provider/model` string, so you switch models by changing it (`openai/gpt-5.5`,
-`anthropic/claude-sonnet-4-5`, and so on) with no provider SDK to install. The
-gateway reads `AI_GATEWAY_API_KEY` from your environment and is wired up
-automatically when you deploy on Vercel.
+By default Ask AI routes through the **Vercel AI Gateway**: `model` is a `provider/model` string, so you switch models by changing it (`openai/gpt-5.5`, `anthropic/claude-sonnet-4-5`, and so on) with no provider SDK to install. The gateway reads `AI_GATEWAY_API_KEY` from your environment and is wired up automatically when you deploy on Vercel.
 
-Set `provider` to point Ask AI somewhere else. Each backend reads its API key
-from an environment variable, and the matching provider SDK is added to your
-project's runtime automatically when you build — only the one you use:
+Set `provider` to point Ask AI somewhere else. Each backend reads its API key from an environment variable, and the matching provider SDK is added to your project's runtime automatically when you build — only the one you use:
 
-| `provider`          | `model`                                       | API key env var      |
-| ------------------- | --------------------------------------------- | -------------------- |
-| `gateway` (default) | a `provider/model` string via the AI Gateway  | `AI_GATEWAY_API_KEY` |
-| `openrouter`        | any [OpenRouter](https://openrouter.ai) model | `OPENROUTER_API_KEY` |
-| `llmgateway`        | any [LLMGateway](https://llmgateway.io) model | `LLMGATEWAY_API_KEY` |
-| `inkeep`            | an [Inkeep](https://inkeep.com) QA model      | `INKEEP_API_KEY`     |
-| `openai-compatible` | whatever your endpoint serves                 | set with `apiKeyEnv` |
+| `provider` | `model` | API key env var |
+| --- | --- | --- |
+| `gateway` (default) | a `provider/model` string via the AI Gateway | `AI_GATEWAY_API_KEY` |
+| `openrouter` | any [OpenRouter](https://openrouter.ai) model | `OPENROUTER_API_KEY` |
+| `llmgateway` | any [LLMGateway](https://llmgateway.io) model | `LLMGATEWAY_API_KEY` |
+| `inkeep` | an [Inkeep](https://inkeep.com) QA model | `INKEEP_API_KEY` |
+| `openai-compatible` | whatever your endpoint serves | set with `apiKeyEnv` |
 
 For example, to use OpenRouter:
 
@@ -131,8 +109,7 @@ ai: {
 }
 ```
 
-Any OpenAI-compatible endpoint works through `openai-compatible` — supply the
-`baseUrl` and the env var holding its key:
+Any OpenAI-compatible endpoint works through `openai-compatible` — supply the `baseUrl` and the env var holding its key:
 
 ```ts blume.config.ts lineNumbers
 ai: {
@@ -146,27 +123,19 @@ ai: {
 }
 ```
 
-Set `apiKeyEnv` (and, for the named providers, `baseUrl`) on any backend to point
-at a different env var or proxy.
+Set `apiKeyEnv` (and, for the named providers, `baseUrl`) on any backend to point at a different env var or proxy.
+
+:::note **Inkeep** answers from the content you've indexed in the Inkeep dashboard — it runs its own retrieval — so Blume leaves it ungrounded. Every other backend is [grounded](#grounding) in this site's pages. :::
+
+Keys are read with `process.env`, which covers the Node, Vercel, and Netlify adapters. On Cloudflare, expose the key through the platform's [runtime binding](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets). Enabling Ask AI also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).
 
-:::note
-**Inkeep** answers from the content you've indexed in the Inkeep dashboard — it
-runs its own retrieval — rather than from this site's pages. The other backends
-are plain model passthroughs: the endpoint streams the reader's messages straight
-to the model.
-:::
+### Rate limiting
 
-Keys are read with `process.env`, which covers the Node, Vercel, and Netlify
-adapters. On Cloudflare, expose the key through the platform's [runtime
-binding](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets).
-Enabling Ask AI also turns on React for the in-page island — see
-[Customization](/docs/configuration/customization#react-islands).
+The `POST /api/ask` endpoint is **unauthenticated** — it has to be, so the in-page assistant can call it. Blume validates each request (rejecting malformed bodies and capping it to 1–40 messages) to bound how much a single call can spend against your model, but it can't stop someone from calling the endpoint repeatedly. If cost abuse is a concern, put the route behind a rate limiter — your host's (e.g. Vercel's) edge rate limiting, a middleware, or your model provider's per-key spend limits.
 
 ## MCP server
 
-Host a [Model Context Protocol](https://modelcontextprotocol.io) server so coding
-agents (Claude Code, Cursor, VS Code, claude.ai connectors) can search and read
-your docs directly — no scraping:
+Host a [Model Context Protocol](https://modelcontextprotocol.io) server so coding agents (Claude Code, Cursor, VS Code, claude.ai connectors) can search and read your docs directly — no scraping:
 
 ```ts blume.config.ts lineNumbers
 mcp: {
@@ -182,20 +151,13 @@ 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 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).
 
-`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.
+`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.
 
 ### Server output required
 
-The MCP server is a live endpoint (`/mcp`), so it can't run on a static build.
-Switch to server output and pick an adapter:
+The MCP server is a live endpoint (`/mcp`), so it can't run on a static build. Switch to server output and pick an adapter:
 
 ```ts blume.config.ts lineNumbers
 deployment: {
@@ -205,9 +167,7 @@ deployment: {
 }
 ```
 
-A static build with `mcp.enabled` fails fast with a message telling you to set
-`deployment.output` to `server`. See [Deployment](/docs/deployment) for the
-adapters. Once deployed, connect from Claude Code with:
+A static build with `mcp.enabled` fails fast with a message telling you to set `deployment.output` to `server`. See [Deployment](/docs/deployment) for the adapters. Once deployed, connect from Claude Code with:
 
 ```bash
 claude mcp add --transport http my-docs https://docs.example.com/mcp
@@ -215,14 +175,10 @@ claude mcp add --transport http my-docs https://docs.example.com/mcp
 
 ## 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:
+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:
 
 ```bash
 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`).
+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`).

package/docs/configuration/analytics.mdx

@@ -3,24 +3,15 @@ title: Analytics
 description: First-party web analytics — Vercel Web Analytics, PostHog, or any custom script — wired up from blume.config.ts.
 ---
 
-Blume injects analytics for you from a single `analytics` block in
-`blume.config.ts`. Vercel Web Analytics and PostHog are first-class, and a
-`scripts` escape hatch covers every other provider — Plausible, Fathom, Google
-Analytics, Umami, and the rest.
+Blume injects analytics for you from a single `analytics` block in `blume.config.ts`. Vercel Web Analytics and PostHog are first-class, and a `scripts` escape hatch covers every other provider — Plausible, Fathom, Google Analytics, Umami, and the rest.
 
-Analytics loads in **production builds only**. The scripts are emitted by
-`blume build`, never by `blume dev`, so local traffic never reaches your
-dashboards and you don't need a separate "development" project.
+Analytics loads in **production builds only**. The scripts are emitted by `blume build`, never by `blume dev`, so local traffic never reaches your dashboards and you don't need a separate "development" project.
 
-:::note
-Analytics is opt-in. With no `analytics` block, Blume injects nothing.
-:::
+:::note Analytics is opt-in. With no `analytics` block, Blume injects nothing. :::
 
 ## Vercel Web Analytics
 
-Set `vercel: true` to add [Vercel Web Analytics](https://vercel.com/docs/analytics).
-Blume injects Vercel's first-party script, which is served from your own domain
-once Web Analytics is enabled for the project in the Vercel dashboard.
+Set `vercel: true` to add [Vercel Web Analytics](https://vercel.com/docs/analytics). Blume injects Vercel's first-party script, which is served from your own domain once Web Analytics is enabled for the project in the Vercel dashboard.
 
 ```ts blume.config.ts lineNumbers
 analytics: {
@@ -28,15 +19,11 @@ analytics: {
 }
 ```
 
-No keys are needed — the script reports to the project it's deployed under. This
-only collects data on Vercel deployments, where the `/_vercel/insights` endpoint
-exists.
+No keys are needed — the script reports to the project it's deployed under. This only collects data on Vercel deployments, where the `/_vercel/insights` endpoint exists.
 
 ## PostHog
 
-Provide your **project API key** to add [PostHog](https://posthog.com). The host
-defaults to PostHog Cloud US; set `host` for EU Cloud
-(`https://eu.i.posthog.com`) or a self-hosted instance.
+Provide your **project API key** to add [PostHog](https://posthog.com). The host defaults to PostHog Cloud US; set `host` for EU Cloud (`https://eu.i.posthog.com`) or a self-hosted instance.
 
 ```ts blume.config.ts lineNumbers
 analytics: {
@@ -47,14 +34,11 @@ analytics: {
 }
 ```
 
-The project API key is safe to ship to the browser — it's a public,
-write-only key.
+The project API key is safe to ship to the browser — it's a public, write-only key.
 
 ## Custom scripts
 
-Use `scripts` to load any other analytics provider. Each entry renders one
-`<script>` tag and must set **exactly one** of `src` (external) or `content`
-(inline).
+Use `scripts` to load any other analytics provider. Each entry renders one `<script>` tag and must set **exactly one** of `src` (external) or `content` (inline).
 
 ```ts blume.config.ts lineNumbers
 analytics: {
@@ -79,20 +63,18 @@ analytics: {
 }
 ```
 
-`attributes` is a map of extra HTML attributes (`data-*`, `id`, …) spread onto
-the tag, and `strategy` adds `async` or `defer` to external scripts.
+`attributes` is a map of extra HTML attributes (`data-*`, `id`, …) spread onto the tag, and `strategy` adds `async` or `defer` to external scripts.
 
 ## Options
 
-| Option                 | Default                    | Description                                             |
-| ---------------------- | -------------------------- | ------------------------------------------------------- |
-| `vercel`               | `false`                    | Add Vercel Web Analytics (Vercel deployments only).     |
-| `posthog.key`          | —                          | PostHog project API key. Enables PostHog when set.      |
-| `posthog.host`         | `https://us.i.posthog.com` | PostHog ingestion host (EU Cloud or self-hosted).       |
-| `scripts[].src`        | —                          | External script URL. Mutually exclusive with `content`. |
-| `scripts[].content`    | —                          | Inline script body. Mutually exclusive with `src`.      |
-| `scripts[].strategy`   | —                          | `async` or `defer` for an external script.              |
-| `scripts[].attributes` | —                          | Extra HTML attributes spread onto the `<script>` tag.   |
-
-All three can be combined — enable Vercel, PostHog, and custom scripts together.
-For deploying your built site, see [Deployment](/docs/deployment).
+| Option | Default | Description |
+| --- | --- | --- |
+| `vercel` | `false` | Add Vercel Web Analytics (Vercel deployments only). |
+| `posthog.key` | — | PostHog project API key. Enables PostHog when set. |
+| `posthog.host` | `https://us.i.posthog.com` | PostHog ingestion host (EU Cloud or self-hosted). |
+| `scripts[].src` | — | External script URL. Mutually exclusive with `content`. |
+| `scripts[].content` | — | Inline script body. Mutually exclusive with `src`. |
+| `scripts[].strategy` | — | `async` or `defer` for an external script. |
+| `scripts[].attributes` | — | Extra HTML attributes spread onto the `<script>` tag. |
+
+All three can be combined — enable Vercel, PostHog, and custom scripts together. For deploying your built site, see [Deployment](/docs/deployment).