blume 2.0.1 → 2.0.2

package/skills/blume-migrate/references/docusaurus.md

@@ -23,7 +23,7 @@ Read `themeConfig`, `presets`, and `plugins`:
 | `themeConfig.colorMode.defaultMode` | `theme.mode` (`respectPrefersColorScheme: true` → `"system"`) |
 | `themeConfig.prism.theme` / `.darkTheme` | `markdown.code.theme: { light, dark }` (map Prism theme names to Shiki themes, e.g. `github`/`github-dark`) |
 | `themeConfig.metadata` / `themeConfig.image` | per-page `seo` frontmatter / `seo.og`; report what doesn't fit |
-| `url` + `baseUrl` | **`url` → drop** (the deployment's `site` is auto-detected); `baseUrl` (when not `/`) → `deployment: { base: "/…" }`, or the `base` option of a host adapter (`vercel({ base })`) when the site also needs one |
+| `url` + `baseUrl` | **`url` → `deployment.site`**, unless the target host is Vercel, Netlify, or Cloudflare Pages, which Blume auto-detects (see SKILL.md — GitHub Pages, a common Docusaurus host, is not one of them); `baseUrl` (when not `/`) → `deployment: { base: "/…" }`, or the `base` option of a host adapter (`vercel({ base })`) when the site also needs one |
 | preset `docs.routeBasePath` — **including the default!** | Docusaurus serves docs at **`/docs/…` by default**; the "map only declared fields" rule does **not** apply here because the _URLs_ are load-bearing. Either keep them with top-level **`basePath: "/docs"`** (invisible to the sidebar), or intentionally move to root and emit a `redirects` entry per page. Decide explicitly and say which. (`routeBasePath: '/'` = docs-only mode — nothing to do.) |
 | preset `docs.editUrl` | `github` (owner/repo/branch; a path after the branch → `github.dir`; **an origin other than `https://github.com` → `github.host`** — a GitHub Enterprise repo's edit links and header mark point at the public site without it) |
 | `themeConfig.footer` | drop → Footer override (`defineComponents` layout slot) |
@@ -50,18 +50,18 @@ Every Docusaurus repo serves **`static/`** at the site root (`static/img/foo.png
 
 ## Versioned docs
 
-Docusaurus `versioned_docs/version-X/` + `versions.json` (+ `versioned_sidebars/`) → **recommend migrating the latest released version only**. Mind the URL scheme: by default the **latest release** serves at `/docs/` and the work-in-progress `docs/` folder serves at `/docs/next` (`lastVersion: 'current'` flips this) — pick the folder that matches what users see at `/docs/`. If older versions must stay, put each under its own folder and wire a `navigation.selectors` entry of `kind: "version"`.
+Docusaurus `versioned_docs/version-X/` + `versions.json` (+ `versioned_sidebars/`) → **recommend migrating the latest released version only**. Mind the URL scheme: by default the **latest release** serves at `/docs/` and the work-in-progress `docs/` folder serves at `/docs/next` (`lastVersion: 'current'` flips this) — pick the folder that matches what users see at `/docs/`. If older versions must stay, use Blume's native versioning rather than a hand-built `navigation.selectors` dropdown: move each `versioned_docs/version-X/` into a top-level folder under `content.root` named for its id, and list that id in `versions.archived` (newest first), with `versions.current` labeling the live tree. Ids must start with a letter, so `version-1.0/` becomes `v1.0/`. Blume then adds the version switcher, the old-version notice, version-scoped search, and canonicals to the latest itself. A version-shaped folder left out of `versions.archived` only warns (`BLUME_VERSIONS_UNCONFIGURED_VERSION`) and publishes as ordinary current content. Snapshot routes become `/<id>/…`, so rewrite root-absolute links inside each snapshot to stay in it (`/guides/x` → `/v1.0/guides/x`) and add `redirects` from the old version URLs. Full reference: `docs/content/versioning.mdx` in the installed package.
 
 ## Blog
 
-A Docusaurus `blog/` → Blume `type: blog` pages. **Dates come from filenames/folders** (`2024-01-31-foo.md`) — extract each into `date` frontmatter and strip the date from the filename (the old dated URLs `/blog/2024/01/31/foo` need `redirects`). Strip `<!-- truncate -->` / `{/* truncate */}` markers. `authors.yml` refs → inline author objects in each post's `authors` frontmatter. RSS stays at `/blog/rss.xml` on both sides.
+A Docusaurus `blog/` → Blume `type: blog` pages. **Dates come from filenames/folders** (`2024-01-31-foo.md`) — extract each into `date` frontmatter and strip the date from the filename (the old dated URLs `/blog/2024/01/31/foo` need `redirects`). Strip `<!-- truncate -->` / `{/* truncate */}` markers. `authors.yml` refs → inline author objects in each post's `authors` frontmatter. RSS stays at `/blog/rss.xml` on both sides. Blume generates **no** blog index, tag, author, or archive pages: write a `blog/index.mdx` whose `CardGroup` links each post (see `docs/advanced/blog.mdx` in the installed package), and report the tag, author, and archive pages as dropped.
 
 ## Content & components
 
 - **`.md` vs `.mdx` — both majors need renames, for opposite reasons.** Blume parses `.md` as plain Markdown: no directives, no JSX, no `$$` math, no mermaid/package-install fences. **v3** treats `.md` as MDX (so a `.md` with imports/JSX/`{}` renders them as literal text in Blume); **v2** content is looser MDX v1. Rule: **rename any `.md` that contains admonitions, JSX, imports, or math to `.mdx`** — for typical Docusaurus repos that is most files.
 - **Admonitions are directives — but check the version.** v3: `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger` pass through; `:::caution` → `:::warning` (or rely on Blume's alias); titles `:::note[Title]` work. **v2:** titles are space-separated (`:::note Your Title`) — rewrite to brackets or the title is silently lost; and v2's `:::warning` rendered **red/danger** — audit whether it should become `:::danger`.
 - **Tabs:** `<Tabs>`/`<TabItem label="…" value="…">` → `<Tabs>`/`<Tab title="…">`. Drop `groupId`/`queryString`/`value`; strip the `@theme/Tabs` imports.
-- **Theme JSX in content:** `<DocCardList/>` (standard on category index pages) → hand-write `Card`/`CardGroup` links or delete (a Blume group page lists its children); `<TOCInline/>` → drop (report); `<CodeBlock>` JSX → a fenced code block; `<Admonition>` → the matching directive; `<details>`/`<summary>` → `<Accordion>`/`<AccordionItem>` or leave as raw HTML.
+- **Theme JSX in content:** `<DocCardList/>` (standard on category index pages) → a `CardGroup` of `Card` links to the folder's pages, one per child (nothing in Blume lists a folder's children on its index page, so deleting it leaves the page empty); `<TOCInline/>` → drop (report); `<CodeBlock>` JSX → a fenced code block; `<Admonition>` → the matching directive; `<details>`/`<summary>` → `<Accordion>`/`<AccordionItem>` or leave as raw HTML.
 - **`@theme/*` / `@site/*` imports** — strip `@theme/*` (Blume injects components globally); rewrite `@site/` asset/module paths to `/public` URLs or inline. **MDX partials** (`_partial.mdx` imports) → inline the partial's body (Blume's default `**/_*` exclude already hides the partial files themselves).
 - **Code blocks:** `title="file.js"` → works as-is; `showLineNumbers` → `lineNumbers`; **magic comments** (`// highlight-next-line`, `highlight-start`/`end`) → `{ranges}` or `// [!code highlight]` — unconverted they ship as literal comments in every sample; ` ```bash npm2yarn ` → ` ```package-install `.
 - **MDX v1 (v2 sources) pitfalls:** unescaped `<`/`{` in prose, HTML comments `<!-- -->` (→ `{/* */}`), string `style="…"` attributes (→ objects). Fix as build errors surface.
@@ -72,7 +72,7 @@ A Docusaurus `blog/` → Blume `type: blog` pages. **Dates come from filenames/f
 | --- | --- |
 | `title` / `description` | pass through |
 | `id` | usually drop (routing is filesystem-based); use `slug` to pin a route |
-| `slug` | `slug` |
+| `slug` | `slug` as a **full path from the content root**: Blume's `slug` replaces the page's whole route, while Docusaurus resolves a relative slug (no leading `/`) against the doc's folder. So `guides/intro.md` with `slug: start` → `slug: guides/start`; an absolute slug (`/start`) is already a full path |
 | `sidebar_label` | `sidebar.label` |
 | `sidebar_position` | `sidebar.order` |
 | `unlisted` | `hidden: true` + `noindex: true` |
@@ -95,4 +95,4 @@ Remove `@docusaurus/*` and Algolia deps; delete `docusaurus.config.*`, `sidebars
 
 ## Dropped — report these
 
-Custom/swizzled theme components (layout slots or `blume eject`), footer columns, Algolia config, `sidebar_custom_props` and the other dropped frontmatter keys, `createRedirects` functions (→ host rules), React pages under `src/pages/`, `<TOCInline>`, per-category `className`/`customProps`, and any `@theme/*` component with no Blume equivalent.
+Custom/swizzled theme components (layout slots or `blume eject`), footer columns, the blog's generated tag, author, and archive pages, Algolia config, `sidebar_custom_props` and the other dropped frontmatter keys, `createRedirects` functions (→ host rules), React pages under `src/pages/`, `<TOCInline>`, per-category `className`/`customProps`, and any `@theme/*` component with no Blume equivalent.

package/skills/blume-migrate/references/mintlify.md

@@ -92,7 +92,7 @@ The codemod touches **only frontmatter**. Icons in MDX **body** (`<Icon icon="
 | `life-ring` | `life-buoy` |  | `shield-halved` | `shield` |
 | `rocket`/`book`/`book-open`/`code`/`terminal`/`key`/`lock`/`user`/`users`/`database`/`server`/`cloud`/`bell`/`calendar`/`star`/`heart`/`tag`/`folder`/`globe`/`link`/`download`/`upload`/`check`/`copy`/`play`/`filter` | _(same name — verify)_ |
 
-**Rules:** verify each Lucide name exists at [lucide.dev/icons](https://lucide.dev/icons) before writing it. **Brand icons** (`fa6-brands:*` — github, discord, x, slack, linkedin…) mostly have **no** Lucide equivalent: for GitHub use the `github` config (renders the header repo link); for other socials, drop the icon and report it (or add via a Footer override after `blume eject`). Where no Lucide counterpart exists, **drop the icon and report it** — an unknown icon name is a build error.
+**Rules:** verify each Lucide name exists at [lucide.dev/icons](https://lucide.dev/icons) before writing it. **Brand icons** (`fa6-brands:*` — github, discord, x, slack, linkedin…) mostly have **no** Lucide equivalent: for GitHub use the `github` config (renders the header repo link); for other socials, drop the icon and report it (or add via a Footer override after `blume eject`). Where no Lucide counterpart exists, **drop the icon and report it**. The build won't catch a wrong name for you: an unknown icon renders nothing, and it's only a warning (`BLUME_UNKNOWN_ICON`) for navigation icons — an icon prop on a component like `<Card>` fails silently — so check every name.
 
 ## Navigation: `docs.json` `navigation` → filesystem + tabs
 
@@ -143,7 +143,7 @@ Mintlify page frontmatter → Blume's strict schema. **`scripts/mintlify-codemod
 | `canonical` | `seo.canonical` | renames |
 | `og:image` | `seo.image` | renames |
 | `hidden: true` | valid top-level in Blume — **kept as-is**; add `noindex: true` yourself if the page must also leave the search index | left (do by hand) |
-| `openapi`/`asyncapi`/`api` | usually an endpoint stub → **delete the page** (Blume generates operation pages); else `type: api` | **flags** for review — never auto-deletes a page |
+| `openapi`/`asyncapi`/`api` | usually an endpoint stub → **delete the page** (Blume generates operation pages); else drop the key and keep it as a normal page (there's no built-in `api` page type) | **flags** for review — never auto-deletes a page |
 | `mode`, `public`, `rss`, `groups`, `keywords`, `hideApiMarker`, `hideFooterPagination`, `iconType` | **drop** (report) | drops |
 
 The codemod leaves the source key in place and reports a conflict rather than clobbering data when a rename target already exists (e.g. a page already has `sidebar.label`) or the value is too structured to move safely — resolve those by hand. Remove any duplicate H1 in the body — `title` renders the H1. (The codemod only edits frontmatter; it never touches the body.)
@@ -153,7 +153,7 @@ The codemod leaves the source key in place and reports a conflict rather than cl
 Top-level `openapi`, `api.openapi`, or a per-group/per-tab `openapi` → `reference: [openapi({ sources: [{ spec, label?, route? }] })]`, with `openapi` imported from `blume/reference` (`spec` alone is the single-source shorthand; several per-tab specs become several sources, or several `openapi()` entries when they need different routes; a spec the source embedded with Scalar becomes a `scalar({ spec })` entry). A Mintlify `{ source, directory }` object: `directory` → the source's `route`. An `asyncapi` field maps the same way to `asyncapi({ … })` in the list. **Delete every per-endpoint stub page** (frontmatter `openapi: "GET /path"` or a `"GET /path"` nav entry) — Blume's native renderer generates one real page per operation. **Add a `navigation.tabs` entry pointing at the reference `route` yourself** (Mintlify's API tab maps to it); the reference does not create a header tab automatically.
 
 - **Vendor the spec.** Mintlify usually points at a spec **URL**. Copying that straight into `spec:` makes every build fetch it at build time — a single point of failure in CI/offline/behind a proxy, and a failed fetch silently drops the reference (leaving the tab pointing at a route that 404s). Prefer downloading it into the repo (`curl … -o openapi/<name>.json`) and pointing `spec` at that local path. If you keep the URL, report the dependency and consider a `prebuild` refresh-with-fallback.
-- **Fix endpoint links.** Blume operation routes are `<route>/<slugified-tag>/<slugified-operationId>` (tag `Models` + id `listModels` → `/api-reference/models/listmodels`) — this differs from Mintlify's endpoint URLs, so **rewrite every inbound link to an operation**. `blume validate` resolves operation pages like any other route and flags the ones you miss.
+- **Fix endpoint links.** Blume operation routes are `<route>/<slugified-tag>/<slugified-operationId>` (tag `Models` + id `listModels` → `/api-reference/models/list-models`: a camelCase id is split into kebab-case, not just lowercased — see SKILL.md "OpenAPI") — this differs from Mintlify's endpoint URLs, so **rewrite every inbound link to an operation**. `blume validate` resolves operation pages like any other route and flags the ones you miss.
 - **Keep the "Introduction" page.** Mintlify commonly has a written intro/auth page in an "Introduction" group beside the "Endpoints" (openapi) group in the same tab. Keep it: a normal content page placed under the `openapi()` adapter's `route` (e.g. `<root>/api-reference/introduction.mdx`) merges into the reference tab's sidebar alongside the generated operations. Delete only the per-endpoint stubs, not the conceptual pages.
 
 ## Assets

package/skills/blume-migrate/references/monorepo.md

@@ -112,7 +112,7 @@ This is a **copyable template**, not prose. Three pieces:
     "preview": "blume preview"
   },
   "dependencies": {
-    "blume": "^1"
+    "blume": "^2"
   }
 }
 ```

package/skills/blume-migrate/references/nextra.md

@@ -56,7 +56,7 @@ Most Nextra pages have **no frontmatter**; the title falls back `_meta` title
 
 ## Code fences
 
-Nextra's fence meta differs from Blume's — rewrite it: `filename="app.js"` → a space-separated title (` ```js app.js `); `showLineNumbers` → `lineNumbers`; line highlighting `{1,4-5}` carries over unchanged; **drop** word-highlight `/word/`, `copy`/`copy=false`, and inline-code `{:lang}` suffixes. ` ```sh npm2yarn ` fences → ` ```package-install `.
+Nextra's fence meta differs from Blume's — rewrite it: `filename="app.js"` → a space-separated title (` ```js app.js `); `showLineNumbers` → `lineNumbers`; line highlighting `{1,4-5}` carries over unchanged; **drop** word-highlight `/word/` and `copy`/`copy=false`. **Keep** inline-code `{:lang}` suffixes (`` `useState(){:js}` ``) — Blume highlights them natively. ` ```sh npm2yarn ` fences → ` ```package-install `.
 
 ## Math
 

package/skills/blume-migrate/references/starlight.md

@@ -12,7 +12,7 @@ Keep content where it is — set `content.root: "src/content/docs"`.
 
 ## Config: `starlight({…})` → `blume.config.ts`
 
-**Harvest the surrounding `astro.config.*` too, not just the `starlight()` call:** top-level Astro `redirects` → Blume `redirects`; `site` → leave unset (Blume auto-detects); other integrations → report.
+**Harvest the surrounding `astro.config.*` too, not just the `starlight()` call:** top-level Astro `redirects` → Blume `redirects`; `site` → `deployment.site`, unless the target host is Vercel, Netlify, or Cloudflare Pages, which Blume auto-detects (see SKILL.md); other integrations → report.
 
 | Starlight option | Blume |
 | --- | --- |
@@ -70,7 +70,7 @@ Starlight's primary callout syntax is the `:::note`/`:::tip`/`:::caution`/`:::da
 
 ## Components
 
-- **Renames:** `<CardGrid>` → `<CardGroup>`; `<LinkCard>` → `<Card>` (its `description` prop drops — fold into the body); `<TabItem label="…">` → `<Tab title="…">`. `<Tabs>` and `<Card>` stay; a `<Tabs syncKey="…">` → strip the prop (Blume tabs sync by default).
+- **Renames:** `<CardGrid>` → `<CardGroup>`; `<LinkCard>` → `<Card>` (its `description` prop drops — fold into the body); `<TabItem label="…">` → `<Tab title="…">`. `<Tabs>` and `<Card>` stay; **keep** a `<Tabs syncKey="…">` prop as is — Blume's `Tabs` takes `syncKey` with the same scoping (only groups sharing the key switch together). One difference: Blume groups without a key also sync, page-wide, by tab title, where Starlight leaves them independent — add `sync={false}` to a keyless group whose same-titled tabs must stay unlinked.
 - **`<Badge>` needs conversion, not pass-through:** Starlight puts content in a `text` prop and uses variants `note`/`tip`/`caution`/`danger`/`success`/`default` with sizes `small`/`medium`/`large`. Blume's `<Badge>` renders **children** with variants `default`/`accent`/`success`/`warning`/`danger` and sizes `xs`/`sm`/`md`/`lg`. Move `text` into the children; remap variant (`note`→`default`, `tip`→`accent`, `caution`→`warning`, `danger`→`danger`, `success`→`success`) and size (`small`→`sm`, `medium`→`md`, `large`→`lg`).
 - **Convert yourself:** `<Steps>` → Blume `<Steps>`/`<Step>`; `<FileTree>` → Blume `<FileTree>`; `<Code code={…}>` → a fenced code block; `<LinkButton>` → a Markdown link or `<Card>`.
 - Strip `import … from "@astrojs/starlight/*"` and `astro:assets` lines.
@@ -88,8 +88,8 @@ Starlight content is full of Expressive Code fence meta; Blume understands some
 ## Plugins — map, don't drop
 
 - `starlight-openapi` → an `openapi({ sources })` entry in Blume's `reference` list, imported from `blume/reference` (delete any generated pages; add the `navigation.tabs` entry).
-- `starlight-blog` → `type: blog` pages.
-- `starlight-versions` → `navigation.selectors` with `kind: "version"`.
+- `starlight-blog` → `type: blog` pages (RSS at `/blog/rss.xml`). Blume generates **no** blog index, tag, or author pages: write a `blog/index.mdx` whose `CardGroup` links each post (see `docs/advanced/blog.mdx` in the installed package), and report the tag and author pages as dropped.
+- `starlight-versions` → Blume's native versioning, not a `navigation.selectors` dropdown: each archived version's content goes in a top-level folder under `content.root` named for its id, listed in `versions.archived` (newest first), and Blume adds the switcher, the old-version notice, and version-scoped search. Ids must start with a letter (`1.0/` → `v1.0/`, with `redirects` from the old URLs), and a version-shaped folder left out of `versions.archived` only warns (`BLUME_VERSIONS_UNCONFIGURED_VERSION`) and publishes as current content. Full reference: `docs/content/versioning.mdx` in the installed package.
 - `starlight-image-zoom` → delete (Blume zooms content images by default).
 - `starlight-links-validator` → delete (`blume validate` covers it).
 - Anything else → report.
@@ -113,4 +113,4 @@ Remove `@astrojs/starlight` (and plugin deps) from deps, delete the Starlight bi
 
 ## Dropped — report these
 
-Non-GitHub socials, badge variants, sidebar/item `attrs` + `translations`, `customCss` beyond `theme.css`, `head` entries, `routeMiddleware`, splash/hero pages (rebuild as custom pages), aside custom icons, EC frames/collapse/text markers, prev/next toggles, unmapped plugins, any `<Icon>` name with no Lucide equivalent.
+Non-GitHub socials, badge variants, sidebar/item `attrs` + `translations`, `customCss` beyond `theme.css`, `head` entries, `routeMiddleware`, splash/hero pages (rebuild as custom pages), starlight-blog's tag and author pages, aside custom icons, EC frames/collapse/text markers, prev/next toggles, unmapped plugins, any `<Icon>` name with no Lucide equivalent.

package/skills/blume-migrate/scripts/mintlify-codemod.mjs

@@ -177,8 +177,8 @@ const RENAME = {
 };
 
 // Keys we deliberately do NOT auto-transform — they usually mean the page is an
-// OpenAPI endpoint stub that should be deleted (Blume generates operation pages)
-// or converted to `type: api`. Flag for the human; never guess.
+// OpenAPI endpoint stub that should be deleted (Blume generates operation pages),
+// or else a normal page that just loses the key. Flag for the human; never guess.
 const FLAG = new Set(["api", "asyncapi", "openapi"]);
 
 // Which change kinds actually edit the file. Report-only kinds (flags,

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

@@ -32,7 +32,7 @@ Skip the edit when the only available change is subjective polish, wording prefe
 - 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/...`).
+- Keep internal links root-relative (`/guides/setup`), in the form nearby pages already use.
 - Do not edit generated `.blume/` or `dist/` output.
 
 ## PR notes

package/src/ai/agent-surface.ts

@@ -0,0 +1,56 @@
+import { routeIsTaken } from "../astro/pages.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import type { ResolvedConfig } from "../core/schema.ts";
+
+/**
+ * What a build actually serves of the agent surfaces whose config flag alone
+ * doesn't guarantee them.
+ */
+export interface EmittedAgentSurface {
+  /** The MCP server was generated (see {@link servesMcp}). */
+  mcp: boolean;
+  /**
+   * A skills discovery index is served: generated from `agents.skills` (at
+   * least one valid skill), or shipped by the user in `public/`.
+   */
+  skills: boolean;
+}
+
+/**
+ * Whether the build generates the MCP server: it is enabled and no content
+ * or custom page owns its route. When one does, the generator skips the
+ * server with a warning rather than collide with the page (`planMcp`).
+ */
+export const servesMcp = (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): boolean =>
+  project.config.agents.mcp.enabled &&
+  !routeIsTaken(
+    userPages,
+    project.graph.pages,
+    project.config.agents.mcp.route
+  );
+
+/**
+ * The config the discovery documents are built from: `agents.mcp` and
+ * `agents.skills` switched off when the build didn't emit them, so llms.txt,
+ * agent-readability.json, the catalogs, and the header rules only point at
+ * what is there. A config flag says what was asked for; the MCP server is
+ * skipped when a page owns its route, and skills publish nothing when their
+ * directory is missing or holds no valid skill.
+ */
+export const advertisedConfig = (
+  config: ResolvedConfig,
+  emitted: EmittedAgentSurface
+): ResolvedConfig => ({
+  ...config,
+  agents: {
+    ...config.agents,
+    mcp: {
+      ...config.agents.mcp,
+      enabled: config.agents.mcp.enabled && emitted.mcp,
+    },
+    skills: emitted.skills ? config.agents.skills : undefined,
+  },
+});

package/src/ai/api/spec.ts

@@ -113,6 +113,7 @@ export interface ApiSpecDocument {
 }
 
 const JSON_TYPE = "application/json";
+const EVENT_STREAM_TYPE = "text/event-stream";
 const MARKDOWN_TYPE = "text/markdown";
 const TEXT_TYPE = "text/plain";
 
@@ -623,14 +624,26 @@ export const buildApiSpec = (input: ApiSpecInput): ApiSpecDocument => {
       {
         post: {
           description:
-            "The Model Context Protocol server (Streamable HTTP, stateless, JSON responses). Tools: `search_docs`, `get_page`, `list_pages`, `get_navigation` — the same operations this API exposes — plus every page as a `text/markdown` resource. Discovery document at `/.well-known/mcp.json`.",
+            "The Model Context Protocol server (Streamable HTTP, stateless, JSON responses). Send `Accept: application/json, text/event-stream`: the Streamable HTTP transport requires a client to accept both and answers `406` otherwise, though this server always replies with JSON. Tools: `search_docs`, `get_page`, `list_pages`, `get_navigation` — the same operations this API exposes — plus every page as a `text/markdown` resource. Discovery document at `/.well-known/mcp.json`.",
           operationId: "mcp",
           requestBody: {
             content: { [JSON_TYPE]: { schema: ref("JsonRpcRequest") } },
             required: true,
           },
           responses: {
-            "200": jsonResponse("The JSON-RPC response.", "JsonRpcResponse"),
+            // Both media types, so a generated client sends the Accept header
+            // the transport requires; OpenAPI ignores an `Accept` parameter.
+            "200": {
+              content: {
+                [JSON_TYPE]: { schema: ref("JsonRpcResponse") },
+                [EVENT_STREAM_TYPE]: { schema: { type: "string" } },
+              },
+              description: "The JSON-RPC response.",
+            },
+            "406": jsonResponse(
+              "The request's `Accept` header doesn't list both `application/json` and `text/event-stream`.",
+              "JsonRpcResponse"
+            ),
           },
           summary: "Call the MCP server",
           tags: ["MCP"],

package/src/ai/api-catalog.ts

@@ -17,7 +17,13 @@ import { API_BASE, OPENAPI_PATH } from "./api/paths.ts";
  */
 
 export const API_CATALOG_PATH = "/.well-known/api-catalog";
-export const API_CATALOG_TYPE = "application/linkset+json";
+/** The profile URI RFC 9727 registers for an API catalog linkset. */
+export const API_CATALOG_PROFILE = "https://www.rfc-editor.org/info/rfc9727";
+/**
+ * The catalog's media type: a linkset carrying the RFC 9727 profile
+ * parameter, which the RFC says an API catalog SHOULD be served with.
+ */
+export const API_CATALOG_TYPE = `application/linkset+json; profile="${API_CATALOG_PROFILE}"`;
 
 /** An RFC 9264 linkset entry, restricted to the relations Blume emits. */
 interface LinksetEntry {

package/src/ai/ask-context.ts

@@ -30,6 +30,13 @@ export interface AskData {
   defaultLocale?: string;
   documents: OramaDoc[];
   site: string | null;
+  /**
+   * Present on a versioned site, whose documents then carry their `version`
+   * (`""` for the current docs): retrieval keeps to the version the reader
+   * is viewing — the current docs unless they're on an archived page — as
+   * the search dialog does.
+   */
+  versioned?: boolean;
 }
 
 /** Documents retrieved per question and injected into the system prompt. */
@@ -644,12 +651,17 @@ export const createAskContext = (
     // which part of each page is quoted.
     const [query = ""] = queries;
 
-    // The current page anchors retrieval to its locale and is injected first.
+    // The current page anchors retrieval to its locale and docs version, and
+    // is injected first. Without one, a versioned site grounds in the
+    // current docs rather than every archived copy of each page.
     const current = page?.path
       ? byRoute.get(normalizeRoute(page.path))
       : undefined;
     const db = await index();
-    const filters = { locale: current?.locale || undefined };
+    const filters = {
+      locale: current?.locale || undefined,
+      version: data.versioned ? (current?.version ?? "") : undefined,
+    };
     const hits = interleave(
       await Promise.all(
         queries.map((text) => queryOramaIndex(db, text, maxResults, filters))

package/src/ai/ask-data.ts

@@ -1,14 +1,17 @@
 import type { BlumeProject } from "../core/project-graph.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
+import type { OramaDoc } from "../search/orama-index.ts";
 import type { AskData } from "./ask-context.ts";
 
 /**
  * Build the grounding snapshot the assistant endpoint serves. Like the MCP server,
  * the assistant 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, 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.
+ * search provider is `none` (`includeWhenDisabled`). `locale` is kept so
+ * retrieval can be filtered to the current page's language, and on a
+ * versioned site `version` too, so archived snapshots don't crowd the docs
+ * being read out of the answer. 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.
  * The reader is an AI agent, so `<Visibility>` resolves for the agents audience
  * (web-only content removed, agents-only unwrapped) and components downlevel to
  * Markdown, both matching llms-full.txt.
@@ -19,15 +22,26 @@ export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
     content: "markdown",
     includeWhenDisabled: true,
   });
-  return {
+  const versioned = Boolean(project.config.versions);
+  const data: AskData = {
     defaultLocale: project.config.i18n?.defaultLocale,
-    documents: documents.map((doc) => ({
-      content: doc.content,
-      description: doc.description,
-      locale: doc.locale,
-      route: doc.route,
-      title: doc.title,
-    })),
+    documents: documents.map((doc) => {
+      const document: OramaDoc = {
+        content: doc.content,
+        description: doc.description,
+        locale: doc.locale,
+        route: doc.route,
+        title: doc.title,
+      };
+      if (versioned) {
+        document.version = doc.version;
+      }
+      return document;
+    }),
     site: project.config.deployment.options.site ?? null,
   };
+  if (versioned) {
+    data.versioned = true;
+  }
+  return data;
 };

package/src/ai/component-markdown.ts

@@ -4,6 +4,7 @@ import { mdxToMdast } from "satteri";
 import { parseYouTubeId } from "../components/content/youtube.ts";
 import type { ExampleLookup } from "../core/types.ts";
 import { MDX_FEATURES } from "../markdown/features.ts";
+import { readStaticExpression } from "./static-expression.ts";
 
 /**
  * Downlevel Blume's MDX components to plain Markdown for agent-facing output
@@ -44,11 +45,19 @@ interface MdxAttribute {
 
 /** A single source replacement: `[start, end)` byte range → `text`. */
 interface Splice {
+  /**
+   * The range is a flow (block-level) element, so the line after it must
+   * start a block of its own.
+   */
+  block: boolean;
   end: number;
   start: number;
   text: string;
 }
 
+/** Text that continues on the very next line, with no blank line between. */
+const NEXT_LINE_TEXT = /^[\t ]*\n[\t ]*\S/u;
+
 /**
  * A statically-recovered data value. Parsed front matter and evaluated
  * attribute literals are both plain data — scalars, dates, arrays, and
@@ -135,33 +144,13 @@ export type ComponentMarkdown = (
 ) => string | null;
 
 /**
- * Statically evaluate an MDX attribute expression (`prop={...}`). Component
- * data props are object/array/number literals in practice; evaluation runs at
- * build time over the author's own content — the same trust level as the MDX
- * itself, which Astro compiles and executes. The page's `frontmatter` is in
- * scope, mirroring what Astro provides an MDX body at render time, so
- * `prop={frontmatter.status}` resolves; expressions that reference imports or
- * other scope throw and report as not evaluable.
+ * Read an element's attributes into a plain props object. An expression
+ * attribute (`prop={...}`) is read as literal data and never executed (see
+ * `static-expression.ts`): the downleveler also runs over plain `.md` pages
+ * and remote content, which nothing else executes. `prop={frontmatter.status}`
+ * resolves against the page's front matter, as it does when Astro renders
+ * the page; anything else — a call, an import — marks the props lossy.
  */
-const evaluateExpression = (
-  raw: string,
-  frontmatter: Record<string, EvaluatedValue> | undefined
-) => {
-  try {
-    // Build-time eval of the author's own attribute literals; a throw falls
-    // back to leaving the JSX verbatim.
-    // oxlint-disable-next-line no-new-func
-    const value: EvaluatedValue = new Function(
-      "frontmatter",
-      `"use strict"; return (${raw});`
-    )(frontmatter);
-    return { ok: true, value };
-  } catch {
-    return { ok: false, value: undefined };
-  }
-};
-
-/** Evaluate an element's attributes into a plain props object. */
 const readProps = (
   node: MdastNode,
   frontmatter: Record<string, EvaluatedValue> | undefined
@@ -180,7 +169,7 @@ const readProps = (
     } else if (isString(attribute.value)) {
       props[attribute.name] = attribute.value;
     } else {
-      const result = evaluateExpression(attribute.value.value, frontmatter);
+      const result = readStaticExpression(attribute.value.value, frontmatter);
       if (result.ok) {
         props[attribute.name] = result.value;
       } else {
@@ -208,14 +197,24 @@ const applySplices = (text: string, splices: Splice[]): string => {
     const lineStart = result.lastIndexOf("\n", splice.start - 1) + 1;
     const prefix = result.slice(lineStart, splice.start);
     const indent = /^[\t ]+$/u.test(prefix) ? prefix : "";
+    // The JSX's closing tag ended its block; the Markdown standing in for it
+    // doesn't. Text on the very next line would read as a lazy continuation
+    // of a blockquote or list item (`> Body` then `Next.` joins the quote),
+    // so a blank line keeps it out.
+    const spliced =
+      splice.block &&
+      splice.text !== "" &&
+      NEXT_LINE_TEXT.test(result.slice(splice.end))
+        ? `${splice.text}\n`
+        : splice.text;
     const replacement = indent
-      ? splice.text
+      ? spliced
           .split("\n")
           .map((line, index) =>
             index === 0 || line === "" ? line : `${indent}${line}`
           )
           .join("\n")
-      : splice.text;
+      : spliced;
     result =
       result.slice(0, splice.start) + replacement + result.slice(splice.end);
   }
@@ -888,15 +887,21 @@ const renderSlice = (
   const splices: Splice[] = [];
   // oxlint-disable-next-line no-use-before-define
   collectSplices(walk, nodes, splices);
+  // Start the slice at its line's indent, so a component that opens the
+  // slice is indented like the lines after it once replaced (see
+  // `applySplices`) and dedents with them; the final trim drops that indent
+  // from the first line again.
+  const indent = indentAt(walk.source, start);
+  const from = start - (indent ?? 0);
   const spliced = applySplices(
-    walk.source.slice(start, end),
+    walk.source.slice(from, end),
     splices.map((splice) => ({
       ...splice,
-      end: splice.end - start,
-      start: splice.start - start,
+      end: splice.end - from,
+      start: splice.start - from,
     }))
   );
-  return dedent(spliced, indentAt(walk.source, start)).trim();
+  return dedent(spliced, indent).trim();
 };
 
 /** The element's body as Markdown: the slice covering all of its children. */
@@ -996,6 +1001,7 @@ const collectSplices = (
     const text = hasOffsets(node) ? downlevelComponentNode(node, walk) : null;
     if (text !== null && hasOffsets(node)) {
       out.push({
+        block: node.type === "mdxJsxFlowElement",
         end: node.position.end.offset,
         start: node.position.start.offset,
         text,
@@ -1015,10 +1021,10 @@ const collectSplices = (
  * over the built-ins: a same-name entry replaces the built-in serializer, and
  * one that always returns `null` effectively opts that component out.
  *
- * `frontmatter` is the page's parsed front-matter data. It is put in scope
- * when evaluating attribute expressions — so `prop={frontmatter.status}`
- * resolves the way it does when Astro renders the page — and handed to
- * serializers on their context.
+ * `frontmatter` is the page's parsed front-matter data. Attribute
+ * expressions that reference it — `prop={frontmatter.status}` — resolve the
+ * way they do when Astro renders the page, and it is handed to serializers on
+ * their context. Expressions are read as literal data, never executed.
  */
 export const downlevelComponents = (
   source: string,

package/src/ai/link-headers.ts

@@ -5,7 +5,11 @@ import {
   AI_CATALOG_TYPE,
   hasAiCatalog,
 } from "./ai-catalog.ts";
-import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
+import {
+  API_CATALOG_PATH,
+  API_CATALOG_TYPE,
+  hasApiCatalog,
+} from "./api-catalog.ts";
 import { OPENAPI_PATH } from "./api/paths.ts";
 
 /**
@@ -37,10 +41,11 @@ export const buildHomeLinkHeader = (
   const deployBase = normalizeBasePath(config.deployment.options.base);
   const links: string[] = [];
   // RFC 9727 §3: the api-catalog relation is how a homepage advertises the
-  // well-known catalog.
+  // well-known catalog. Its type carries the RFC 9727 profile, whose quotes
+  // are escaped inside the quoted `type` value (RFC 8288 quoted-string).
   if (hasApiCatalog(config)) {
     links.push(
-      `<${deployBase}${API_CATALOG_PATH}>; rel="api-catalog"; type="application/linkset+json"`
+      `<${deployBase}${API_CATALOG_PATH}>; rel="api-catalog"; type="${API_CATALOG_TYPE.replaceAll('"', String.raw`\"`)}"`
     );
   }
   // The ai-catalog spec's own relation for its well-known document, the

package/src/ai/llms.ts

@@ -312,10 +312,11 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
           source: raw,
           sourcePath: page.sourcePath,
         });
-        // Relative page links too: a reader of one flat file has no page URL
-        // to resolve `./install` against.
-        raw = rewriteLinks(raw, page);
       }
+      // Page links too: a reader of one flat file has no page URL to resolve
+      // `./install` against, and `/install` needs the base the site is
+      // served under.
+      raw = rewriteLinks(raw, page);
       // Resolve `<Visibility>` audiences (web-only content omitted from the
       // agent-facing output, agents-only unwrapped), then downlevel supported
       // components to plain Markdown.

package/src/ai/markdown.ts

@@ -8,6 +8,7 @@ import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
+import { advertisedConfig, servesMcp } from "./agent-surface.ts";
 import { buildChangelogIndexMarkdown } from "./changelog-markdown.ts";
 import { downlevelComponents } from "./component-markdown.ts";
 import { buildLlmsIndex } from "./llms.ts";
@@ -80,13 +81,14 @@ export const buildRawMarkdown = async (
           source: text,
           sourcePath: route.sourcePath,
         });
-        // `./install` means the page's sibling, not whatever the `.md` URL
-        // an agent fetched resolves it to.
-        text = rewriteLinks(text, {
-          route: route.path,
-          sourcePath: route.sourcePath,
-        });
       }
+      // `./install` means the page's sibling, not whatever the `.md` URL an
+      // agent fetched resolves it to, and `/install` gains the base and the
+      // page's locale the rendered link has — remote content included.
+      text = rewriteLinks(text, {
+        route: route.path,
+        sourcePath: route.sourcePath,
+      });
       const source = applyAgentVisibility(text);
       // The `.md` variant keeps the front-matter block in the output, but its
       // data must also be in scope for `prop={frontmatter.*}` expressions.
@@ -97,19 +99,29 @@ export const buildRawMarkdown = async (
     })
   );
   const map = Object.fromEntries(entries);
+  const userPages = project.context.pagesRoot
+    ? await discoverPages(project.context.pagesRoot)
+    : [];
   // A landing-page homepage (user `.astro` page, or no home route at all) has
   // no Markdown source, but agents negotiating `Accept: text/markdown` on `/`
   // still expect a Markdown answer. The llms.txt index — the machine-readable
   // representation of the site a landing page fronts — becomes its mirror, so
-  // `/index.md` always exists (see `markdownRoutePaths`).
+  // `/index.md` always exists (see `markdownRoutePaths`). Like llms.txt, it
+  // leaves out an MCP server a page's route kept from being generated.
   if (!map["/"]) {
-    map["/"] = { mdx: buildLlmsIndex(project) };
+    map["/"] = {
+      mdx: buildLlmsIndex({
+        ...project,
+        config: advertisedConfig(project.config, {
+          mcp: servesMcp(project, userPages),
+          // Skills are collected at the end of the build, after this runs.
+          skills: Boolean(project.config.agents.skills),
+        }),
+      }),
+    };
   }
   // The generated changelog index has no source either; its release list is
   // its mirror, so `/changelog.md` and `get_page` answer as the page does.
-  const userPages = project.context.pagesRoot
-    ? await discoverPages(project.context.pagesRoot)
-    : [];
   if (hasGeneratedChangelog(project, userPages)) {
     map[CHANGELOG_INDEX_ROUTE] = { mdx: buildChangelogIndexMarkdown(project) };
   }