blume 1.5.3 → 1.6.1

package/dist/types/theme/fonts.d.ts

@@ -20,6 +20,11 @@ export interface RemoteFontConfig {
     provider?: RemoteFontProvider;
     /** Weights (or variable ranges like `"100..900"`) to load. Defaults to `[400, 500, 600, 700]`. */
     weights?: (number | string)[];
+    /**
+     * Character subsets to load (`"latin"`, `"vietnamese"`, `"cyrillic"`, …).
+     * Defaults to `latin` plus whatever the site's configured locales need.
+     */
+    subsets?: string[];
     /** Fallback stack category. Defaults to `"mono"` for the mono role, `"sans"` otherwise. */
     fallback?: FontCategory;
 }
@@ -52,6 +57,7 @@ export type FontEntry = {
     cssVariable: string;
     fallbacks: string[];
     name: string;
+    subsets: string[];
     weights: (number | string)[];
 } | {
     kind: "local";
@@ -193,19 +199,43 @@ export type FontSlug = keyof typeof GOOGLE_FONTS;
 export declare const FONT_SLUGS: string[];
 /** Type guard: is `value` a supported font slug? */
 export declare const isFontSlug: (value: string) => value is FontSlug;
+/** The shape of a config's `i18n` block the font builders read. */
+export interface FontLocaleSource {
+    locales: {
+        code: string;
+    }[];
+}
+/** The locale codes an optional `i18n` block declares (none when absent). */
+export declare const fontLocaleCodes: (i18n: FontLocaleSource | undefined) => string[];
+/**
+ * The subsets the site's locales need: `latin` always, plus each locale's
+ * script. A site with no `i18n` block (or only Latin-1 languages) gets just
+ * `latin` — Astro's own default — so its CSS and preloads don't change.
+ */
+export declare const localeFontSubsets: (locales: string[]) => string[];
 /** Kebab-case a family name into a slug (`"Noto Sans JP"` -> `"noto-sans-jp"`). */
 export declare const slugifyFontName: (name: string) => string;
-/** The unique Astro `fonts:` entries for the configured roles (deduped). */
-export declare const buildFontEntries: (fonts: FontsConfig) => FontEntry[];
+/**
+ * The unique Astro `fonts:` entries for the configured roles (deduped).
+ * `locales` are the site's configured locale codes; they pick the subsets a
+ * remote family loads unless its config pins `subsets` itself.
+ */
+export declare const buildFontEntries: (fonts: FontsConfig, locales?: string[]) => FontEntry[];
 /**
  * The config-token CSS that points each role's `--blume-font-<role>-src` at the
  * Astro-populated family variable. Concatenated into the generated entry's
  * config tokens; empty when no fonts are set so defaults stay the system stacks.
  */
 export declare const buildFontsCss: (fonts: FontsConfig) => string;
-/** One `<Font>` render in the head: its CSS variable + weights to preload. */
+/**
+ * One `<Font>` render in the head: its CSS variable + the weights (and, for
+ * providers that split faces by subset, the subsets) to preload. Local and
+ * Fontshare faces carry no subset, so those entries leave `preloadSubsets`
+ * unset and preload by weight alone.
+ */
 export interface FontHead {
     cssVariable: string;
+    preloadSubsets?: string[];
     preloadWeights: number[];
 }
 /**
@@ -213,4 +243,4 @@ export interface FontHead {
  * by CSS variable with preload weights unioned across the roles that share a
  * family (so `display` and `body` both set to Inter preload 400/500/600 once).
  */
-export declare const configuredFonts: (fonts: FontsConfig) => FontHead[];
+export declare const configuredFonts: (fonts: FontsConfig, locales?: string[]) => FontHead[];

package/docs/07-faq.mdx

@@ -87,14 +87,14 @@ We reported it upstream in [oxc-project/oxc#24096](https://github.com/oxc-projec
 
 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.61.0.patch`:
-
-   ```diff patches/oxfmt@0.61.0.patch
-   diff --git a/dist/markdown-ZuiQU4Xe.js b/dist/markdown-ZuiQU4Xe.js
-   index 566b9e6d27f36061d64b93736e238e871e1ee2b2..82d0595acc010807c2939fc4a1717dde887a8555 100644
-   --- a/dist/markdown-ZuiQU4Xe.js
-   +++ b/dist/markdown-ZuiQU4Xe.js
-   @@ -4875,7 +4875,43 @@ function lu(e, t, r) {
+1. Save the patch as `patches/oxfmt@0.66.0.patch`:
+
+   ```diff patches/oxfmt@0.66.0.patch
+   diff --git a/dist/markdown-BgZGxhM2.js b/dist/markdown-BgZGxhM2.js
+   index 859231f9387a50df16419bc22b5268c4e446ddbc..dcc0ffda6f71adb27a03e3918a3db6fc7a58ffe9 100644
+   --- a/dist/markdown-BgZGxhM2.js
+   +++ b/dist/markdown-BgZGxhM2.js
+   @@ -4872,7 +4872,43 @@ function lu(e, t, r) {
     		case "sentence": return Oh(e, r);
     		case "word": return t.parser !== "mdx" ? zh(e, t) : Uh(e);
     		case "whitespace": {
@@ -146,7 +146,7 @@ Patch oxfmt so it preserves the line break that sits directly against a `:::` fe
    ```json package.json
    {
      "patchedDependencies": {
-       "oxfmt@0.61.0": "patches/oxfmt@0.61.0.patch"
+       "oxfmt@0.66.0": "patches/oxfmt@0.66.0.patch"
      }
    }
    ```

package/docs/_snippets/include-demo.mdx

@@ -0,0 +1,7 @@
+---
+title: Ignored by the including page
+---
+
+:::tip
+This callout lives in `_snippets/include-demo.mdx` — it renders here because the page splices it with an `<include>` statement.
+:::

package/docs/advanced/api-reference.mdx

@@ -12,7 +12,7 @@ openapi: {
 }
 ```
 
-That mounts the reference at `/reference` (an overview page) with each operation at `/reference/<tag>/<operation>`. The `spec` is either an `http(s)` URL or a path to a local file in your project. Blume parses it with [Scalar's OpenAPI parser](https://github.com/scalar/scalar) — Swagger 2.0 and OpenAPI 3.0 specs are upgraded to 3.1 automatically.
+That mounts the reference at `/reference` (an overview page) with each operation at `/reference/<tag>/<operation>`. The `spec` is either an `http(s)` URL or a path to a local file in your project. Blume parses it with [Scalar's OpenAPI parser](https://github.com/scalar/scalar) — Swagger 2.0 and OpenAPI 3.0 specs are upgraded to 3.1 automatically. Documenting a GraphQL API instead? See the [GraphQL reference](/docs/advanced/graphql).
 
 The reference doesn't add a header tab on its own. To surface it, point a [navigation tab](/docs/content/navigation#tabs) at its route — this also scopes the operations sidebar for the native renderer:
 
@@ -139,6 +139,15 @@ openapi: {
 - `includeInLlms: false` keeps them out of both `llms.txt` files.
 - `noindex: true` adds crawler noindex metadata and removes the pages from the sitemap.
 
+Each operation page's meta description is the operation's own `description` (or `summary`), followed by a generated sentence naming the endpoint — "Reference for the `GET /pets` endpoint in the Petstore API." — so a spec of terse one-line summaries still ships a distinct, snippet-length description per page. That sentence is English. On a site whose spec prose is written in another language, set `seoDescriptionSuffix: false` on the source to drop it and describe each page with the authored prose alone; an operation with neither a `description` nor a `summary` falls back to its title (`GET /pets`), so no page ships an empty description:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
+}
+```
+
 With the [Scalar renderer](#the-scalar-renderer), only `noindex` applies — a Scalar-rendered reference already sits outside Blume's search and `llms.txt`, so the two `include*` settings have nothing to act on there.
 
 ## Authorization
@@ -165,7 +174,7 @@ openapi: {
 }
 ```
 
-A Scalar-rendered reference is a self-contained embed on its own route — it doesn't weave into Blume's sidebar, search, or `llms.txt`, and Blume's [`playground`](#try-it-playground) config doesn't apply to it. Scalar brings its own request client, which calls your **target API directly from the browser** (the `playground.proxy` route isn't available here), so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). `theme` applies to the Scalar renderer only.
+A Scalar-rendered reference is a self-contained embed on its own route — it doesn't weave into Blume's sidebar, search, or `llms.txt`, and Blume's [`playground`](#try-it-playground) config doesn't apply to it. It does follow Blume's light/dark toggle: the embed is pinned to the page's theme when it mounts and switches with it, so Scalar's own theme switch is hidden (set `scalar.forceDarkModeState` or `scalar.darkMode` to hand color mode back to Scalar). Scalar brings its own request client, which calls your **target API directly from the browser** (the `playground.proxy` route isn't available here), so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). `theme` applies to the Scalar renderer only.
 
 ### Passing Scalar options
 
@@ -202,7 +211,7 @@ AsyncAPI **2.x specs are normalized to 3.x automatically** with the official Asy
 
 Code samples are **protocol-aware**, keyed off the operation's binding (or its servers' protocol): `wscat` and a browser `WebSocket` snippet for WebSockets, `kcat` for Kafka, `mosquitto_pub`/`mosquitto_sub` for MQTT. `codeSamples` filters that set, the same way it picks languages on the `openapi` block; a protocol without a supported tool renders the message payload example alone rather than a fabricated client.
 
-Everything documented above carries over, [`playground`](#try-it-for-events) included: `route`, `sources` with `label`/`route`, `expandSchemas`, the [per-source indexing](#per-source-indexing) flags, and search indexing by operation summary and tag.
+Everything documented above carries over, [`playground`](#try-it-for-events) included: `route`, `sources` with `label`/`route`, `expandSchemas`, the [per-source indexing](#per-source-indexing) flags (`seoDescriptionSuffix` too — the generated sentence names the channel and action instead of an endpoint), and search indexing by operation summary and tag.
 
 Setting `renderer: "scalar"` opts back into the embedded Scalar SPA, where — as with OpenAPI — only `noindex` applies. Scalar has no AsyncAPI playground of its own; its embed auto-detects the document type and renders channels, operations, messages, and a Models section, so that swap trades the composer away.
 
@@ -225,7 +234,7 @@ asyncapi: {
 ```
 
 :::note
-`playground.proxy` is OpenAPI-only. It forwards HTTP requests, and a WebSocket connect goes straight from the browser to the server named in the URL, so there's nothing for a proxy to sit in front of.
+`playground.proxy` doesn't apply to event operations. It forwards HTTP requests, and a WebSocket connect goes straight from the browser to the server named in the URL, so there's nothing for a proxy to sit in front of.
 :::
 
 The event composer collects no broker credentials. Each operation page's **Authorization** section documents what the broker expects, and a WebSocket connect carries only what's already in the URL. Nothing is persisted for event operations.

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, ask, og, analytics, feedback, structuredData, toc, codeThemes, codeWrap, and imageZoom.",
+        "Resolved site settings: title, description, logo, favicon, appleIcon, banner, theme, site, repoUrl, github (owner, repo, host, and the REST api base — null when unset), search, i18n, mcp, ask, og, analytics, feedback, structuredData, toc, codeThemes, codeWrap, and imageZoom.",
     },
     navigation: {
       type: "Navigation",
@@ -272,7 +272,9 @@ import data from "blume:data";
 
 ## 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. Under the message, a **Where to look next** list links every top-level section plus the `sitemap.xml` and [`llms.txt`](/docs/configuration/ai#llmstxt) indexes when they exist, so a reader — or an agent that followed a stale URL — has a way back.
+
+The page also has a Markdown twin at `/404.md` with the same recovery links (absolute URLs once [`deployment.site`](/docs/deployment) is set). On a [Vercel server build](/docs/deployment#server-rendering), a request for a missing page that sends [`Accept: text/markdown`](/docs/configuration/ai#content-negotiation), or asks for a `.md` URL no page backs, gets that Markdown body with the `404` status instead of the HTML shell — so an agent never has to parse a page of chrome to learn where to go next.
 
 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`:
 

package/docs/advanced/graphql.mdx

@@ -0,0 +1,84 @@
+---
+title: GraphQL
+description: Drop in a GraphQL schema and get a native API reference — one real page per operation and per type, in your sidebar and search.
+---
+
+Point Blume at a GraphQL schema and it generates a native API reference: one **real page per root field** — queries, mutations, and subscriptions — plus one **page per named type** (objects, input objects, enums, interfaces, unions, and custom scalars). Every page shows arguments, defaults, deprecations, and usage backlinks, alongside a generated example operation, code samples, and an interactive [Try it](#try-it-playground) panel. Because each page is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc.
+
+```ts blume.config.ts lineNumbers
+graphql: {
+  enabled: true,
+  spec: "./schema.graphql",
+  endpoint: "https://api.example.com/graphql",
+}
+```
+
+That mounts the reference at `/graphql` (an overview page), with root fields at `/graphql/queries/<field>`, `/graphql/mutations/<field>`, and `/graphql/subscriptions/<field>`, and types grouped by kind at `/graphql/objects/<type>`, `/graphql/enums/<type>`, and so on.
+
+The `spec` is either a path to a local file in your project or an `http(s)` URL, and accepts two formats:
+
+- **SDL text** — a `.graphql` file with type definitions.
+- **An introspection result** — the JSON produced by running the standard introspection query, either the raw `{ "__schema": … }` shape or the full `{ "data": { "__schema": … } }` response envelope.
+
+The `endpoint` is the live GraphQL API URL. A schema, unlike an OpenAPI document, names no server — so the endpoint is what the Try it panel and the generated code samples target. Leave it off and the samples render with a placeholder URL readers replace.
+
+The reference doesn't add a header tab on its own. To surface it, point a [navigation tab](/docs/content/navigation#tabs) at its route — this also scopes the reference sidebar:
+
+```ts blume.config.ts
+navigation: {
+  tabs: [{ label: "GraphQL", path: "/graphql" }],
+}
+```
+
+## Generated examples
+
+Every operation page carries a complete, valid example operation — one variable per argument, typed off the schema, with a bounded-depth selection set over the return type — plus matching example variables and an example response that mirrors the same selection. Code samples show the exact HTTP request (a JSON `POST` of `{ query, variables }`) in each configured language:
+
+```ts blume.config.ts lineNumbers
+graphql: {
+  enabled: true,
+  spec: "./schema.graphql",
+  codeSamples: ["curl", "js"],   // built in: curl, js, python
+}
+```
+
+## Type pages
+
+Named types get their own deep-linkable pages, grouped by kind in the sidebar: fields and input fields with their types linked, enum values, union members, interface implementations, and a **Used by** section listing the operations that return or accept the type and the other types that reference it. Spec-defined scalars (`String`, `Int`, …) don't get pages; custom scalars do, including their `specifiedBy` URL.
+
+## Multiple schemas
+
+Each entry in `sources` renders one schema on its own route. A per-source `endpoint` overrides the block-level one:
+
+```ts blume.config.ts lineNumbers
+graphql: {
+  enabled: true,
+  endpoint: "https://api.example.com/graphql",
+  sources: [
+    { label: "Public API", spec: "./schema.graphql" },
+    {
+      label: "Admin API",
+      route: "/graphql-admin",
+      spec: "./admin.graphql",
+      endpoint: "https://admin.example.com/graphql",
+    },
+  ],
+}
+```
+
+Each source takes the same [per-source controls](/docs/advanced/api-reference#per-source-indexing) as the OpenAPI block: `includeInSearch`, `includeInLlms`, `noindex`, and `seoDescriptionSuffix` (here the generated sentence names the query, mutation, or type — "Reference for the `pets` query in the GraphQL API.").
+
+## Try it playground
+
+Query and mutation pages render an interactive panel: edit the request body (the query and variables), point it at your endpoint or a custom URL, and send — the code samples update live so what you copy is byte-for-byte what was sent. Disable it with `playground: false`. Subscription pages show the generated operation and an example event instead: subscriptions run over a stateful transport (WebSocket or SSE) that the playground's single HTTP `POST` can't speak.
+
+If your GraphQL API doesn't allow cross-origin requests from the docs site, route sends through a CORS proxy — a URL of your own, or `true` for the built-in `/_api-proxy` endpoint (which requires `deployment.output: "server"`). The built-in proxy only forwards to origins your documented specs declare — each configured GraphQL `endpoint`, plus any absolute `servers[].url` from a documented [OpenAPI spec](/docs/advanced/api-reference) — so a public docs deployment can't be aimed at other hosts. That makes `endpoint` required for a working proxy: without one, the proxy has no origin to allow for this reference and refuses every send (the build warns about this).
+
+```ts blume.config.ts lineNumbers
+graphql: {
+  enabled: true,
+  spec: "./schema.graphql",
+  endpoint: "https://api.example.com/graphql",
+  playground: { proxy: true },
+}
+```

package/docs/advanced/meta.ts

@@ -2,6 +2,13 @@ import { defineMeta } from "blume";
 
 export default defineMeta({
   order: 5,
-  pages: ["skills", "custom-pages", "changelog", "blog", "api-reference"],
+  pages: [
+    "skills",
+    "custom-pages",
+    "changelog",
+    "blog",
+    "api-reference",
+    "graphql",
+  ],
   title: "Advanced",
 });

package/docs/configuration/ai.mdx

@@ -33,6 +33,22 @@ ai: {
 }
 ```
 
+The object form also takes `details`: Markdown placed right after the title and summary in `llms.txt`, before the page sections — the [llms.txt spec](https://llmstxt.org)'s free-form "details" block. It's the place to tell agents _when_ to reach for your product and how to call it, which readiness scanners look for explicitly; an install command and the package name belong here too:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  llmsTxt: {
+    details: [
+      "## When to use Acme",
+      "",
+      "Reach for Acme when a project needs hosted feature flags. Install the CLI with `npm install -g acme`; the API reference below covers every endpoint.",
+    ].join("\n"),
+  },
+}
+```
+
+`llms.txt` closes with two generated sections that need no configuration. **Agent skills** lists each skill published through [`ai.skills`](#skills-discovery) with its description (where a skill says when to use it). **Agent resources** links every machine-readable artifact the build emits — `llms-full.txt`, the per-page [raw Markdown](#raw-markdown) mirror, the [MCP server](#mcp-server) and its discovery document, the skills index, the [API catalog](#api-catalog), [`agent-readability.json`](#agent-readability), and the [sitemap](/docs/configuration/seo#sitemap) — each only when it exists, so an agent that reads nothing but `llms.txt` still finds the whole surface.
+
 To keep an individual page out of both files, set `ai.exclude` in its frontmatter:
 
 ```mdx
@@ -59,12 +75,14 @@ Append `.md` or `.mdx` to any page's URL to fetch its raw Markdown source — pe
 
 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. Props are evaluated with the page's `frontmatter` in scope, so a prop like `title={frontmatter.status}` resolves to the same value the rendered page shows. 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.
+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, `<Card>` its title as a link over its body (and `<CardGroup>` the cards it holds), and `<YouTube>` a link. Props are evaluated with the page's `frontmatter` in scope, so a prop like `title={frontmatter.status}` resolves to the same value the rendered page shows. 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.
 
 ### Content negotiation
 
 Agents don't need to know the `.md` convention: requesting a page's own URL with an [`Accept: text/markdown`](https://acceptmarkdown.com) header serves the Markdown variant at the same address, with `Vary: Accept` so caches keep the two apart. The dev server honors the header out of the box, and a [Vercel or Cloudflare server build](/docs/deployment#server-rendering) wires the same negotiation into the deploy automatically — routing rules on Vercel, a generated Worker on Cloudflare — no configuration needed. The homepage always negotiates, even when it's a custom landing page rather than a content page: its Markdown mirror falls back to the [`llms.txt`](#llmstxt) index, so an agent asking the site root for Markdown gets the machine-readable map of the site. Markdown responses also carry an `x-markdown-tokens` header — an estimated token count (~4 characters per token), following the convention of [Cloudflare's Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/) — on every surface where Blume controls response headers: the dev server, server-rendered responses, and the negotiated homepage on Vercel and Cloudflare. Other deploy targets serve prerendered pages from a static layer with no request-time hook, so agents there fetch the `.md` URL directly; the [agent readability manifest](#agent-readability) advertises `contentNegotiation` only on deployments that honor the header.
 
+Missing pages negotiate too. Every build emits a Markdown [404 page](/docs/advanced/custom-pages#404-page) at `/404.md` — the not-found message followed by recovery links to every top-level section, the sitemap, and `llms.txt` — and on Vercel a request for a nonexistent URL that prefers Markdown, or any `.md` URL with no page behind it, gets that body with a real `404` status rather than the HTML shell.
+
 ### 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, with the page's `frontmatter` in scope), its `children` (already downleveled to Markdown), and the page's `frontmatter` data, and returns the replacement — or `null` to leave the JSX as-is:
@@ -85,7 +103,7 @@ export default defineConfig({
 });
 ```
 
-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.
+For container components, `childComponents("Name")` extracts direct children by tag — the same way the built-in `<Steps>` serializer collects its `<Step>` items — and `childBlocks()` returns every direct child in order, components and prose alike, each already downleveled to a block of Markdown (the built-in `<CardGroup>` serializer is just those blocks joined by blank lines). 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.
 
@@ -93,6 +111,8 @@ Serializers live in `blume.config.ts`, not `components.tsx`: the config file is
 
 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.
 
+Where the Clipboard API is unavailable or the browser denies it — in-app browsers, WebViews, insecure origins — the action falls back to the legacy copy command, and if nothing lands on the clipboard the button reports **Copy failed** (localized via `actions.copyFailed`) rather than staying silent. The same fallback backs every copy button Blume renders.
+
 ## 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:
@@ -101,6 +121,8 @@ 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.
 
+The prompt is part of the [UI dictionary](/docs/content/i18n#translated-ui) (`actions.openInChatPrompt`), so localized sites send it in their language, and `i18n.ui` can override the wording — keep the `{url}` placeholder, which is replaced with the page's raw-Markdown URL.
+
 To tailor the action, set `ai.openInChat`. `false` hides it entirely, and an array of provider keys — `"v0"`, `"chatgpt"`, `"claude"`, `"t3"`, `"scira"`, `"cursor"` — shows just those providers, in the order you list them:
 
 ```ts blume.config.ts lineNumbers
@@ -306,7 +328,7 @@ ai: {
 | `name`         | title   | Server name shown to clients (defaults to title). |
 | `instructions` | —       | Optional system hint passed to connecting agents. |
 
-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`. The server card follows the [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) Server Card extension schema (reverse-DNS `name`, `remotes` transport endpoints), with initialize-shaped compat fields (`serverInfo`, `capabilities`, `transports`) for scanners built against the proposal's earlier revision. 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).
+The server exposes read-only tools — `search_docs`, `get_page`, `list_pages`, and `get_navigation` — and every page as an MCP resource (`resources/list` enumerates the pages at their served URLs with a `text/markdown` type; `resources/read` returns the page's agent Markdown, the same output as `get_page`), so clients that attach context by URI can browse the docs without calling a tool. It publishes discovery documents at `/.well-known/mcp.json` and `/.well-known/mcp/server-card.json`. The server card follows the [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) Server Card extension schema (reverse-DNS `name`, `remotes` transport endpoints), with initialize-shaped compat fields (`serverInfo`, `capabilities`, `transports`) for scanners built against the proposal's earlier revision. 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.
 

package/docs/configuration/index.mdx

@@ -285,6 +285,30 @@ github: {
 | `repo` | — | Repository name. |
 | `branch` | `"main"` | Branch that edit links point at. |
 | `dir` | — | Path from the repo root to the project root (for monorepos). |
+| `host` | `"https://github.com"` | Origin of the GitHub instance, for Enterprise installations. Must be HTTP(S); normalized to its origin. |
+| `api` | derived from `host` | REST API base, for `<GithubInfo>` against an Enterprise instance. Must be HTTP(S); normalized to an origin and path. |
+
+### GitHub Enterprise
+
+Docs whose repository lives on a GitHub Enterprise instance set `host`, and every repo-derived link — the header mark, edit links, the agent manifest — points at that instance instead of the public site:
+
+```ts blume.config.ts lineNumbers
+github: {
+  host: "https://github.acme.com",
+  owner: "acme",
+  repo: "docs",
+}
+```
+
+The REST API base that [`<GithubInfo>`](/docs/content/components) queries is derived from `host`: an Enterprise Cloud tenant with data residency (`acme.ghe.com`) is served from its `api.` subdomain, and any other host is treated as Enterprise Server (`/api/v3`). Set `api` explicitly when your instance sits somewhere else.
+
+:::warning
+An instance reachable only over plain HTTP still renders its counts, but `GITHUB_TOKEN` is withheld from the request rather than sent in cleartext — so a private repo's card comes back without them.
+:::
+
+:::note
+`host` covers links Blume derives from `github`. To point only the header mark somewhere else — an organization, say, when the docs repo itself is private — use [`navigation.repo`](/docs/content/navigation#repository-link) with an absolute URL.
+:::
 
 ## Last modified
 

package/docs/configuration/search.mdx

@@ -40,7 +40,19 @@ Write `href` as if the site were mounted at the root — a `basePath` is applied
 
 ## What's indexed
 
-For every indexable page, Blume indexes its title, description, and body reduced to plain text — code blocks, images, and markup are stripped, so results stay relevant. The index is built from your source files, so it's identical in dev and production.
+For Orama, FlexSearch, Algolia, Orama Cloud, and Typesense — and the MCP server's `search_docs` tool — Blume indexes each page's title, description, and body reduced to plain text: code blocks, images, and markup are stripped, so results stay relevant. These indexes are built from your source files, so they're identical in dev and production. Pagefind indexes the built HTML instead, and Mixedbread syncs your raw Markdown, so both always search code.
+
+If your docs rely on code examples for searchable terms like options, methods, or error names, opt fenced code into the source-built indexes:
+
+```ts blume.config.ts lineNumbers
+search: {
+  indexing: {
+    includeCodeBlocks: true,
+  },
+},
+```
+
+Each fence's body and title (`blume.config.ts` above) become searchable; the language and fence markers don't. On `.mdx` pages the index reads components as the text they show — a Card's title, a Tab's label, a TypeTable's descriptions — using the same serializers as the [agent surfaces](/docs/configuration/ai), so an `ai.markdownComponents` entry covers your own components too. The option has no effect on Pagefind or Mixedbread. Expect the index to grow with your fenced content — the client index ships to every reader, hosted providers cap record size (Algolia rejects the sync batch when one page's record exceeds its plan's limit, leaving the previous index live), and a hit inside a fence shows flattened code in the result excerpt.
 
 On a [versioned](/docs/content/versioning) site, results default to the version being viewed, with an "All versions" toggle in the dialog footer (remembered per reader). Cross-version hits name their version on the row. Orama, FlexSearch, Algolia, and Typesense honor the scoping — hosted records carry a `version` facet, with the current docs uploaded as `"current"` — while Pagefind stays unscoped, matching its locale behavior.
 

package/docs/configuration/seo.mdx

@@ -125,7 +125,7 @@ seo: {
 }
 ```
 
-By default, each card is derived from your content and theme — the **page title** as the headline, your **site title** as the eyebrow, and your theme **accent** for the mark. Images are served at `/og/<slug>.png`, mirroring each route, and are prerendered as static files even in server mode:
+By default, each card is derived from your content and theme — the **page title** as the headline, the **page description** as the subtitle (the same text as its `og:description`, so `seo.description` wins over `description`), your **site title** as the eyebrow, and your theme **accent** for the mark. Images are served at `/og/<slug>.png`, mirroring each route, and are prerendered as static files even in server mode:
 
 | Page route          | Image URL                  |
 | ------------------- | -------------------------- |
@@ -151,13 +151,13 @@ Emoji in a page title or site title render as [Twemoji](https://github.com/jdeck
 
 ### Show, hide, or override card layers
 
-Beyond the headline, the card carries three optional layers: the **brand mark** in the top-left (your logo, or an accent tile with the site title's initial), the **subtitle** under the headline (your site `description`), and a **footer** with your repo slug (from `github`) and the site's URL — the deployment site's host plus [`deployment.base`](/docs/deployment#subpath-deploys), so a GitHub Pages project site reads `user.github.io/repo`. Override any of them with a string of your own, or hide one with `false`:
+Beyond the headline, the card carries three optional layers: the **brand mark** in the top-left (your logo, or an accent tile with the site title's initial), the **subtitle** under the headline (the page `description`, or your site `description` for pages without one), and a **footer** with your repo slug (from `github`) and the site's URL — the deployment site's host plus [`deployment.base`](/docs/deployment#subpath-deploys), so a GitHub Pages project site reads `user.github.io/repo`. Override any of them with a string of your own, or hide one with `false`:
 
 ```ts blume.config.ts lineNumbers
 seo: {
   og: {
     site: "docs.acme.com", // footer URL text, or false to hide it
-    description: false, // hide the subtitle; a string overrides it
+    description: false, // hide the subtitle on every card; a string replaces the site fallback
     logo: false, // no brand mark at all — not even the initial tile
   },
 }
@@ -247,6 +247,33 @@ Each page includes:
 
 URLs are absolute when `deployment.site` is set. Pages marked `seo.noindex` are skipped.
 
+### Site identity
+
+The WebSite node says a site exists; it doesn't say _what_ it is or _who_ runs it — which is what AI agents read JSON-LD for before they recommend or cite you. Two optional blocks fill that in, both needing `deployment.site` (the nodes carry absolute identifiers):
+
+```ts blume.config.ts lineNumbers
+seo: {
+  organization: {
+    name: "Acme", // defaults to the site title
+    email: "hello@acme.com",
+    telephone: "+1 555 0100",
+    address: { addressLocality: "Sydney", addressCountry: "AU" },
+    logo: "/logo.svg",
+    sameAs: ["https://github.com/acme", "https://x.com/acme"],
+  },
+  software: {
+    license: "MIT",
+    operatingSystem: "Node.js 22+",
+    price: 0, // emitted as an Offer; 0 marks it free
+    sameAs: ["https://www.npmjs.com/package/acme"],
+  },
+}
+```
+
+`organization` adds an **Organization** node to every page — the WebSite and article nodes cite it as `publisher` — with the email and telephone as a `ContactPoint` (`contactType` defaults to `"customer support"`) and the address as a `PostalAddress`, the two fields business-verification checks look for. `name` and `url` default to the site's; a root-relative `logo` is absolutized like any page URL.
+
+`software` adds a **SoftwareApplication** node to the homepage: the product's name and description (defaulting to the site's), `applicationCategory` (default `"DeveloperApplication"`), operating system, license, an `Offer` when `price` is set, and the registry or repository URLs in `sameAs`. Pass `software: true` to take every default. The organization, when configured, is cited as its `publisher`.
+
 ## Sitemap
 
 Blume writes a `sitemap.xml` of every indexable page at build time. It needs an absolute [`deployment.site`](/docs/deployment) and lists every page except drafts, hidden, and `noindex` pages. On a [versioned](/docs/content/versioning) site, archived pages whose canonical points at their live equivalent are left out too — the live page is the one to index. On by default:

package/docs/configuration/theming.mdx

@@ -105,8 +105,25 @@ theme: {
 - **`name`** — the family name exactly as the provider lists it.
 - **`provider`** — where the family comes from: `google` (default), `fontsource`, `bunny`, or `fontshare`.
 - **`weights`** — the weights to load, as numbers or a variable range like `"100..900"`. Defaults to `[400, 500, 600, 700]`.
+- **`subsets`** — the character subsets to load, by the provider's names (`latin`, `latin-ext`, `vietnamese`, `cyrillic`, `greek`, …). Defaults to `latin` plus whatever your configured locales need — see below.
 - **`fallback`** — the system stack shown while the font loads and for missing glyphs: `sans`, `serif`, or `mono`. Defaults to `mono` for the mono role and `sans` otherwise.
 
+#### Subsets and locales
+
+Google, Bunny, and Fontsource split each family into per-script subsets, and only the subsets you load get a `@font-face`. Blume derives the list from your [`i18n.locales`](/docs/content/i18n): a site with Vietnamese, Polish, Russian, or Greek locales loads `vietnamese`, `latin-ext`, `cyrillic`, or `greek` alongside `latin`, so diacritics and non-Latin letters render in your chosen font instead of the system fallback. Sites without an `i18n` block, or with only Latin-1 languages, load `latin` alone. Browsers download a subset only when a page uses its characters, and preloads follow the same list.
+
+Set `subsets` on a family to override the derived list — say, for a single-locale site whose content still needs a script its locale doesn't imply:
+
+```ts blume.config.ts lineNumbers
+theme: {
+  fonts: {
+    body: { name: "Be Vietnam Pro", subsets: ["latin", "vietnamese"] },
+  },
+}
+```
+
+Curated slugs like `inter` follow the locale-derived list; use the object form to pin subsets for those families too.
+
 #### Local font files
 
 For a font you own (or one no provider serves), point a role at font files in your project. Each variant becomes one `@font-face`:
@@ -189,6 +206,12 @@ Drop a `theme.css` in your project root to override any design token. It's the l
 
 Set a token under `:root` for light mode and under `:root[data-theme="dark"]` for dark mode. Color tokens have distinct built-in dark values declared at the dark selector's higher specificity, so a `:root`-only override of `--blume-accent`, `--blume-background`, and friends applies to light mode only — declare the dark block too when both modes should change.
 
+`theme.css` is inlined into the site's Tailwind entry, so Tailwind directives work in it too. The one to know for a monorepo is `@source`: Blume scans your project for utility classes, and a page that imports components from a sibling workspace package needs that package scanned as well. Point at it relative to `theme.css` — the standard Tailwind rule — and Blume carries the path into the generated sheet:
+
+```css theme.css lineNumbers
+@source "../../packages/ui/src";
+```
+
 ### Design tokens
 
 | Token                       | Controls                                  |

package/docs/content/components.mdx

@@ -71,6 +71,8 @@ Switch between equivalent content in place — language variants, OS-specific co
 
 Add `inline` to render borderless — a tab strip on a full-width rule with the content flowing beneath as prose — instead of the bordered box. Add `param` to sync the active tab to a URL query param instead of the hash, which makes the selection shareable: a link ending in `?install=windows` opens on the Windows tab. Each group syncs to its own `param`, so you can use several independent, deep-linkable groups on one page.
 
+Groups with same-titled tabs switch together — pick "macOS" in one and every group with a macOS tab follows. Add `syncKey` to scope that syncing: only groups sharing the same key switch together, so unrelated groups that happen to share a tab title stay independent.
+
 <Tabs inline param="install">
   <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
   <Tab title="Windows">Use winget to install the toolchain.</Tab>
@@ -546,6 +548,8 @@ export interface ButtonProps {
 
 A card linking to a GitHub repository with its live star and fork counts. Counts are fetched at build time — no client JavaScript — and the card still renders if the API is unreachable. Pass `owner` and `repo`, or omit them to use the repository from your `blume.config`. Set a `GITHUB_TOKEN` environment variable to lift the API rate limit.
 
+The card reads the instance from [`github.host`](/docs/configuration#github-enterprise), so on an Enterprise-hosted site explicit `owner`/`repo` address that instance too. Pass `host` to point one card somewhere else — a public project from an Enterprise site, say; the REST base is derived from it the same way it is from `github.host`.
+
 <GithubInfo owner="haydenbleasel" repo="blume" />
 
 ```astro lineNumbers
@@ -554,13 +558,16 @@ A card linking to a GitHub repository with its live star and fork counts. Counts
 
 <!-- Or point it at any repository -->
 <GithubInfo owner="haydenbleasel" repo="blume" />
+
+<!-- Or at a repository on another instance -->
+<GithubInfo host="https://github.com" owner="haydenbleasel" repo="blume" />
 ```
 
 ## Component
 
 `Component` renders an example file from your project's `examples/` directory as a live preview alongside its highlighted source, in tabs. Point it at a file with `path` — its location under `examples/`, without the extension (so `examples/counter.tsx` is `path="counter"`). React, Vue, Svelte, and Astro examples are all supported; framework examples hydrate, Astro ones render statically. It keeps the preview and the code in sync from a single file.
 
-The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your example files and anything they import), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live. The pane sizes itself to the rendered example — and keeps tracking it if the example grows or shrinks after load — with the Preview and Code tabs sharing one height so toggling them never shifts the page.
+The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your project and your examples directory), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live. The pane sizes itself to the rendered example — and keeps tracking it if the example grows or shrinks after load — with the Preview and Code tabs sharing one height so toggling them never shifts the page.
 
 To style previews with your own design system — say, shadcn variables — point `examples.css` at a stylesheet. It's injected into every preview frame after Blume's defaults, so your tokens win. Don't `@import "tailwindcss"` in it; the frame already provides Tailwind. Both `.dark` and `[data-theme="dark"]` work for dark-mode overrides:
 
@@ -616,6 +623,13 @@ export default defineConfig({
 <Component path="file-list/examples/basic" />
 ```
 
+In a monorepo, the components your examples import usually live in a sibling workspace package. Tailwind's `@source` scans files, not imports: Blume scans your project and the `examples` directory (wherever `source` points, even outside the project), so a class used only inside that sibling package isn't generated until you add the package to the scan. Do that with an `@source` directive in `examples.css` (for the preview frames) or `theme.css` (for the site), written relative to the file it sits in — the standard Tailwind rule — and Blume carries it into the generated sheet:
+
+```css
+/* examples/theme.css */
+@source "../../../packages/ui/src";
+```
+
 <Component path="counter" />
 
 ```astro