blume 1.3.1 → 1.4.0

package/dist/types/core/base-path.d.ts

@@ -17,6 +17,11 @@
  * bare `/` normalizes to `""`, so an unset/`"/"` base is a clean no-op.
  */
 export declare const normalizeBasePath: (input?: string) => string;
+/**
+ * Normalize a served path for comparison: drop the trailing slash (Astro serves
+ * `/docs` and `/docs/` as the same page) and collapse an empty path to `/`.
+ */
+export declare const normalizePath: (path: string) => string;
 /**
  * Whether a link target is a root-relative internal path (`/x`) — the only
  * shape a base path applies to. Protocol-relative (`//host`), absolute URLs,

package/dist/types/core/config-input.d.ts

@@ -226,15 +226,81 @@ export interface ContentConfig {
      * Releases, Sanity, Notion, or a custom `ContentSource`.
      */
     sources?: ContentSourceInput[];
+    /**
+     * Per-type content definitions, keyed by the frontmatter `type` they apply
+     * to (including `defaultType`, for pages that set none):
+     *
+     * ```ts
+     * import { z } from "zod";
+     *
+     * content: {
+     *   types: {
+     *     rfc: {
+     *       frontmatter: {
+     *         domain: z.string(),
+     *         status: z.enum(["draft", "enforced"]),
+     *       },
+     *     },
+     *   },
+     * },
+     * ```
+     */
+    types?: Record<string, ContentTypeConfig>;
+}
+/**
+ * A per-type content definition: configuration that applies only to pages
+ * whose resolved frontmatter `type` matches the map key.
+ */
+export interface ContentTypeConfig {
+    /**
+     * Custom frontmatter keys whose values become filterable facets for pages
+     * of this type. Faceted values ride along on search documents
+     * (`blume-search.json` and the MCP index), and the MCP `search_docs` and
+     * `list_pages` tools accept a `filters` input matching against them:
+     *
+     * ```ts
+     * content: {
+     *   types: {
+     *     rfc: {
+     *       facets: ["domain", "status"],
+     *       frontmatter: { domain: z.string(), status: z.string() },
+     *     },
+     *   },
+     * },
+     * ```
+     *
+     * Each name must be a custom key declared for the type — in its
+     * `frontmatter` map or the site-wide `frontmatter.extend`. String values
+     * facet as-is; numbers and booleans are stringified; anything else
+     * (objects, arrays, transformed dates) does not facet.
+     */
+    facets?: string[];
+    /**
+     * Custom frontmatter keys for pages of this type, layered on top of the
+     * site-wide `frontmatter.extend` (a key can be declared in one or the
+     * other, not both). Schemas follow the same rules as `extend`: any
+     * Standard Schema library works, every declared key is validated on every
+     * page of the type — absent ones included — so a required schema enforces
+     * the key type-wide (mark it `.optional()` to validate only when present),
+     * and validated values land on the page record's `custom` field. Built-in
+     * frontmatter fields cannot be redeclared.
+     */
+    frontmatter?: Record<string, StandardSchema>;
 }
+/**
+ * A header label, optionally per locale: a plain string, or a map of locale
+ * code to label (`{ en: "Docs", ja: "ドキュメント" }`). The active locale's
+ * entry wins, then the default locale's, then the map's first entry.
+ */
+export type LocalizableLabel = string | Record<string, string>;
 /** A single item inside a header tab's dropdown. */
 export interface NavTabItem {
     /** Secondary line under the label. */
     description?: string;
     /** Lucide icon name shown beside the label. */
     icon?: string;
-    /** Item label. */
-    label: string;
+    /** Item label, optionally per locale. */
+    label: LocalizableLabel;
     /** Route the item links to. */
     path: string;
     /** Short tag/pill (e.g. `New`, `Beta`). */
@@ -255,8 +321,8 @@ export interface NavTab {
     icon?: string;
     /** Dropdown items; omit for a plain link tab. */
     items?: NavTabItem[];
-    /** Tab label. */
-    label: string;
+    /** Tab label, optionally per locale. */
+    label: LocalizableLabel;
     /** Route the tab links to. */
     path: string;
 }
@@ -434,7 +500,10 @@ export interface MixedbreadSearch {
 export interface SearchPopularLink {
     /** Internal route or external URL. */
     href: string;
-    /** Built-in icon name shown beside the label; defaults to the file glyph. */
+    /**
+     * Icon shown beside the label — a built-in name, image path/URL, or inline
+     * SVG (same as nav icons). Defaults to the file glyph.
+     */
     icon?: string;
     /** Link label shown in the dialog. */
     label: string;
@@ -627,6 +696,12 @@ export interface LocaleConfigInput {
     dir?: "ltr" | "rtl";
     /** Human-readable name shown in the switcher. */
     label: string;
+    /**
+     * Freeform style guidance for `blume translate`, e.g. "Brazilian
+     * Portuguese, informal você". Pins register and dialect from the first
+     * translation and wins over an existing translation's style on reruns.
+     */
+    style?: string;
 }
 /**
  * Internationalization. Opt-in: when omitted, Blume is single-locale. The
@@ -991,7 +1066,8 @@ export interface FrontmatterConfig {
      * so a required schema enforces the key site-wide; mark it `.optional()`
      * to validate only when present. Validated values are preserved on each
      * page record's `custom` field. Built-in frontmatter fields cannot be
-     * redeclared.
+     * redeclared. To scope a key to one content type instead, declare it under
+     * `content.types.<type>.frontmatter`.
      */
     extend?: Record<string, StandardSchema>;
 }

package/dist/types/core/i18n-ui.d.ts

@@ -24,6 +24,7 @@ declare const uiStringsObject: z.ZodObject<{
         exportEpub: z.ZodDefault<z.ZodString>;
         exportPdf: z.ZodDefault<z.ZodString>;
         generating: z.ZodDefault<z.ZodString>;
+        openIn: z.ZodDefault<z.ZodString>;
         openInChat: z.ZodDefault<z.ZodString>;
         scrollToTop: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
@@ -125,6 +126,7 @@ export declare const uiStringsSchema: z.ZodPrefault<z.ZodObject<{
         exportEpub: z.ZodDefault<z.ZodString>;
         exportPdf: z.ZodDefault<z.ZodString>;
         generating: z.ZodDefault<z.ZodString>;
+        openIn: z.ZodDefault<z.ZodString>;
         openInChat: z.ZodDefault<z.ZodString>;
         scrollToTop: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;

package/dist/types/core/schema.d.ts

@@ -207,6 +207,16 @@ declare const contentSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "type">;
 /** A resolved content-source config entry (post-defaults). */
 export type ContentSourceConfig = z.infer<typeof contentSourceSchema>;
+/**
+ * A header label that may localize: a plain string, or a map of locale code to
+ * label (`{ en: "Docs", ja: "ドキュメント" }`). Resolved when each locale's
+ * navigation is built — the active locale's entry wins, then the default
+ * locale's, then the map's first entry — so a single-locale site can keep
+ * plain strings and an i18n site can translate its header without forking the
+ * config.
+ */
+declare const localizableLabelSchema: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+export type LocalizableLabel = z.infer<typeof localizableLabelSchema>;
 declare const directoryModeSchema: z.ZodEnum<{
     none: "none";
     accordion: "accordion";
@@ -280,6 +290,7 @@ declare const localeSchema: z.ZodObject<{
         rtl: "rtl";
     }>>;
     label: z.ZodString;
+    style: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /**
  * Internationalization. Opt-in: when absent, Blume is single-locale and behaves
@@ -297,6 +308,7 @@ declare const i18nConfigSchema: z.ZodObject<{
             rtl: "rtl";
         }>>;
         label: z.ZodString;
+        style: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     parser: z.ZodDefault<z.ZodEnum<{
         dir: "dir";
@@ -531,6 +543,10 @@ export declare const blumeConfigSchema: z.ZodObject<{
             source: z.ZodCustom<ContentSource, ContentSource>;
             type: z.ZodLiteral<"custom">;
         }, z.core.$strip>], "type">>>;
+        types: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            facets: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            frontmatter: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodCustom<StandardSchema<unknown, unknown>, StandardSchema<unknown, unknown>>>>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>>;
     dateFormat: z.ZodDefault<z.ZodObject<{
         calendar: z.ZodOptional<z.ZodString>;
@@ -624,6 +640,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 rtl: "rtl";
             }>>;
             label: z.ZodString;
+            style: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
         parser: z.ZodDefault<z.ZodEnum<{
             dir: "dir";
@@ -713,11 +730,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
             items: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 description: z.ZodOptional<z.ZodString>;
                 icon: z.ZodOptional<z.ZodString>;
-                label: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
                 path: z.ZodString;
                 tag: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>>;
-            label: z.ZodString;
+            label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
             path: z.ZodString;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;

package/dist/types/core/sources/types.d.ts

@@ -114,4 +114,9 @@ export interface NormalizeContext {
     /** Opt-in custom frontmatter keys (`frontmatter.extend`), schema per key. */
     frontmatterExtend?: FrontmatterExtend;
     i18n?: ResolvedI18nConfig;
+    /**
+     * Per-type custom frontmatter keys (`content.types.<type>.frontmatter`),
+     * applied to a page only when its resolved `type` matches.
+     */
+    typeFrontmatter?: Record<string, FrontmatterExtend>;
 }

package/dist/types/core/types.d.ts

@@ -139,9 +139,10 @@ export interface PageRecord {
     contentType: string;
     meta: PageMeta;
     /**
-     * Custom frontmatter values declared via `frontmatter.extend`, validated by
-     * the user-supplied schemas (schema output, so transforms apply). Present
-     * only when the project opts in and the page carries at least one value.
+     * Custom frontmatter values declared via `frontmatter.extend` or the page
+     * type's `content.types.<type>.frontmatter`, validated by the user-supplied
+     * schemas (schema output, so transforms apply). Present only when the
+     * project opts in and the page carries at least one value.
      */
     custom?: Record<string, unknown>;
     headings: Heading[];

package/docs/02-deployment.mdx

@@ -101,7 +101,7 @@ On **Vercel**, **Netlify**, and **Cloudflare Pages**, Blume picks the matching a
 
 A server build includes everything a static build does, plus any Astro endpoints or middleware you add. The `node` adapter produces a standalone server you can run directly.
 
-On Vercel, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/configuration/ai#content-negotiation): Blume splices header-conditional rewrites into the deploy's routing config, so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL.
+On Vercel and Cloudflare, a server build also turns on [`Accept: text/markdown` content negotiation](/docs/configuration/ai#content-negotiation), so an agent requesting any content page with that header receives its raw-Markdown mirror at the same URL. On Vercel, Blume splices header-conditional rewrites into the deploy's routing config; on Cloudflare, it generates a small Worker in front of the Astro one and scopes `assets.run_worker_first` to the content routes, since the platform would otherwise serve the prerendered pages before any server code runs — other assets keep their zero-Worker fast path.
 
 :::note
 Server features have their own configuration — for example, Ask AI needs a model API key. See the [AI guide](/docs/configuration/ai) for setup.

package/docs/configuration/ai.mdx

@@ -63,7 +63,7 @@ The `.md` variant _downlevels_ components to plain Markdown for consumers that c
 
 ### 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 server build](/docs/deployment#server-rendering) wires the same negotiation into the deploy's routing rules automatically — 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. 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.
+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.
 
 ### Custom component serializers
 
@@ -257,6 +257,20 @@ The server exposes read-only tools — `search_docs`, `get_page`, `list_pages`,
 
 `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` and `list_pages` both accept an optional `contentTypes` filter, narrowing results to pages of the given frontmatter [`type`s](/docs/reference/frontmatter) — `["rfc"]`, `["blog", "changelog"]` — so an agent working against a site that mixes docs with RFCs, runbooks, or policies can scope retrieval to the kind of page it needs. Every result names its content type, and `list_pages` output shows the types in use.
+
+Both tools also accept a `filters` object matching against the facets a site declares per content type ([`content.types.<type>.facets`](/docs/configuration#frontmatter)) — custom frontmatter keys whose values become filterable metadata:
+
+```json
+{
+  "query": "OpenAPI request schemas",
+  "contentTypes": ["rfc"],
+  "filters": { "domain": "architecture", "status": "enforced" }
+}
+```
+
+Every `filters` entry must match (results carry their facet values, and `list_pages` shows each page's), so a knowledge base can drive progressive-disclosure agent workflows — enumerate the enforced standards, search only within them — without any server of its own.
+
 ### 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:

package/docs/configuration/index.mdx

@@ -189,6 +189,7 @@ content: {
 | `exclude` | `["**/_*", "**/.*"]` | Globs to ignore (underscore- and dot-files). |
 | `pages` | `"pages"` | Folder for custom `.astro` pages. |
 | `defaultType` | `"doc"` | Page `type` used when frontmatter omits it. |
+| `types` | `{}` | Per-type content definitions — custom frontmatter keys scoped to pages of one `type`. See [Frontmatter](#frontmatter). |
 
 Static assets live in `public/` — a file at `public/logo.png` is served at `/logo.png`, so a reference like `![](/images/create.png)` resolves against `public/images/create.png`. Images referenced by **relative path** (`![](./diagram.png)`) live next to your content instead, and are [optimized at build time](/docs/content/syntax#links-and-images).
 
@@ -230,6 +231,31 @@ export default defineConfig({
 
 Any [Standard Schema](https://standardschema.dev) library works — Zod (whichever version your project installs), Valibot, ArkType. Keys outside the extension stay strictly validated, so typo-catching is unchanged. See [Custom keys](/docs/reference/frontmatter#custom-keys) for the validation semantics.
 
+Keys under `extend` apply site-wide. To require keys only on pages of one content type — an RFC's `status`, a runbook's `service` — declare them per type under `content.types` instead:
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+import { z } from "zod";
+
+export default defineConfig({
+  content: {
+    types: {
+      rfc: {
+        facets: ["domain", "status"],
+        frontmatter: {
+          domain: z.string(),
+          status: z.enum(["draft", "review", "enforced"]),
+        },
+      },
+    },
+  },
+});
+```
+
+A key can be declared site-wide or per-type, not both. See [Per-type keys](/docs/reference/frontmatter#per-type-keys) for how the scoping resolves.
+
+`facets` names the custom keys whose values become filterable metadata: they ride along on search documents (`blume-search.json` and the MCP index), and the [MCP tools](/docs/configuration/ai#mcp-server) accept a `filters` input matching against them, so an agent can retrieve, say, only `enforced` RFCs in the `architecture` domain. Each facet must be a declared custom key — per-type or site-wide — and only string (or stringified number/boolean) values facet.
+
 ## GitHub
 
 Point Blume at your repository with `github`. It powers the header [repository link](/docs/content/navigation#repository-link) and the **Edit on GitHub** and **Give feedback** [page actions](/docs/content/navigation#page-actions):

package/docs/configuration/search.mdx

@@ -27,9 +27,7 @@ search: {
 },
 ```
 
-Each entry takes an `href` (internal route or external URL) and a `label`, plus an optional `icon` — a built-in icon name shown beside the label, defaulting to a file glyph. Omit `popular` or leave it empty to keep the sidebar fallback.
-
-Unlike icons elsewhere in Blume, `icon` here must be a built-in name: these rows render in a client island, so an image path or inline SVG isn't supported and falls back to the file glyph.
+Each entry takes an `href` (internal route or external URL) and a `label`, plus an optional `icon` — a [built-in icon](/docs/content/components#icon) name, image path/URL, or inline SVG (same _inputs_ as nav icons), defaulting to a file glyph. Omit `popular` or leave it empty to keep the sidebar fallback.
 
 Write `href` as if the site were mounted at the root — a `basePath` is applied for you, the same as `navigation.featured`. External URLs pass through untouched.
 

package/docs/content/i18n.mdx

@@ -20,7 +20,7 @@ i18n: {
 }
 ```
 
-Each locale has a `code` (used in URLs), a `label` (shown in the language switcher), and an optional `dir` for right-to-left scripts (`"ltr"` by default).
+Each locale has a `code` (used in URLs), a `label` (shown in the language switcher), and an optional `dir` for right-to-left scripts (`"ltr"` by default). An optional `style` gives [`blume translate`](/docs/reference/translate) freeform guidance for the locale — register, dialect, terminology, e.g. `"Brazilian Portuguese, informal você"` — so the choice is pinned from the very first translation instead of decided by the agent.
 
 ## Organize translated content
 
@@ -83,6 +83,8 @@ i18n: {
 
 Each language gets its own sidebar, built from that locale's files — so translations can diverge in structure, ordering, or labels. Folder [`meta.ts`](/docs/content/meta) files resolve per locale, too: under the default `dir` parser, put a `meta.ts` under `fr/guides/` to order the French group independently. Under the `dot` parser translations sit next to the originals, so a folder's `meta.ts` applies to every locale. Everything else about [navigation](/docs/content/navigation) works the same, per language.
 
+Header tabs are configured, not derived from content, so their labels localize in `blume.config.ts`: a tab `label` accepts a per-locale map (`{ en: "Docs", fr: "Documentation" }`) alongside the plain-string form, falling back to the default locale's entry for locales you haven't filled in. See [Tabs](/docs/content/navigation#tabs).
+
 ## Fallbacks
 
 When a page isn't translated yet, Blume renders the fallback locale's content at the localized URL — so the link works, the page is fully pre-rendered, and search engines aren't sent to a dead end. The fallback defaults to your `defaultLocale`:
@@ -100,6 +102,16 @@ Fallback pages are excluded from the search index and aren't advertised as real
 Start by translating your most important pages — the homepage, quickstart, and top guides — and let the rest fall back. You can fill in translations over time without breaking any links.
 :::
 
+## Translating with an agent
+
+You don't have to fill in the locales by hand. [`blume translate`](/docs/reference/translate) finds every page that's missing or outdated in each locale and translates it with a local agent CLI ([Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex/cli)):
+
+```bash
+blume translate --claude
+```
+
+Blume validates each result's structure — frontmatter, code fences, links — and writes the files itself; the agent only translates text. A committed ledger (`blume.translations.json`) tracks which source revision each translation came from, so reruns only touch what changed, and translations you wrote by hand are adopted as-is, never overwritten. In CI, `blume translate --check` fails when a source page has drifted ahead of its translations.
+
 ## The language switcher
 
 When i18n is on, a language switcher appears in the header automatically, generated from your `locales`. For each page it links the matching translation in every language; where a translation is missing it links the fallback page and marks it as not translated. There's nothing to configure.

package/docs/content/navigation.mdx

@@ -135,6 +135,17 @@ navigation: {
 
 This matters for routes that aren't part of the content tree, since the fallback can't see them: the generated [changelog](/docs/advanced/changelog) index, or a [custom page](/docs/advanced/custom-pages) you added under `pages/`. Without `href`, a `/changelog` tab lands on the newest entry rather than the index. Tabs that don't set `href` are unaffected.
 
+On an [i18n](/docs/content/i18n) site, a tab's `label` (and a dropdown item's) can be a per-locale map instead of a string — the active locale's entry wins, then the default locale's:
+
+```ts blume.config.ts
+navigation: {
+  tabs: [
+    { label: { en: "Docs", fr: "Documentation" }, path: "/docs" },
+    { label: "CLI", path: "/cli" }, // a plain string renders as-is everywhere
+  ],
+}
+```
+
 Tabs also **scope the sidebar**: when the current route falls under a tab's `path`, the sidebar shows only that section's pages — so `/adapters/*` lists the adapters and nothing else. The folder at a tab's `path` becomes the section, so this needs no extra config beyond the tabs themselves; structure your content into a folder per tab and point each tab at it.
 
 On a route under no tab (or a tab whose `path` is `/`), the sidebar shows the pages that _don't_ belong to a tab — each tab's folder is hidden from it, since that section already has its own tab in the header. So a root landing page lists your loose top-level pages while the sectioned content stays behind its tab, mirroring Fumadocs' root folders. If a route has no pages of its own to show this way, the full tree is shown instead, so the sidebar is never left blank.

package/docs/reference/cli.mdx

@@ -23,6 +23,7 @@ blume <command> [options]
 | `blume validate` | Validate links across your content. |
 | `blume audit` | Audit the built site for SEO and health issues. |
 | `blume eval` | Test the docs: an agent answers your questions using only the documentation. |
+| `blume translate` | Translate docs into the configured locales with a local agent CLI. |
 
 ## Common flags
 
@@ -62,6 +63,9 @@ blume <command> [options]
 - `blume eval` — run the questions in `evals.yaml` through an agent that reads only your docs; see [Evals](/docs/reference/eval).
 - `blume eval init` — have the agent draft a starter `evals.yaml` from your docs.
 - `blume eval --agent claude|codex --threshold <0..1> --timeout <seconds> --json --fix --verbose` — see [Evals](/docs/reference/eval) for each flag.
+- `blume translate --claude` / `--codex` — translate missing and outdated pages into your configured locales; see [Translate](/docs/reference/translate).
+- `blume translate --check` — report translation drift and exit non-zero (the CI gate), without running an agent.
+- `blume translate --locale <codes> --concurrency <n> --force --timeout <seconds> --json` — see [Translate](/docs/reference/translate) for each flag.
 
 ## Verifying while the dev server runs
 

package/docs/reference/frontmatter.mdx

@@ -109,6 +109,39 @@ reviewedAt: 2026-06-20
 
 Schemas are accepted through the [Standard Schema](https://standardschema.dev) interface, so Zod (whichever version your project installs), Valibot, and ArkType all work. Every declared key is validated on every page — absent ones included — so a required schema enforces the key site-wide; mark it `.optional()` to validate only where present. All other keys stay strictly validated, and built-in fields can't be redeclared.
 
+### Per-type keys
+
+To require keys only on one content type — an RFC's `status`, an incident report's `severity` — declare them under [`content.types`](/docs/configuration#content) instead, keyed by the frontmatter `type` they apply to:
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+import { z } from "zod";
+
+export default defineConfig({
+  content: {
+    types: {
+      rfc: {
+        frontmatter: {
+          domain: z.string(),
+          status: z.enum(["draft", "review", "enforced"]),
+        },
+      },
+    },
+  },
+});
+```
+
+```yaml rfcs/openapi-request-schemas.mdx
+---
+title: OpenAPI request schemas
+type: rfc
+domain: architecture
+status: enforced
+---
+```
+
+Per-type keys follow the same validation rules as `extend`, scoped to pages whose resolved `type` matches — including pages that set no `type`, when the declaration is for [`content.defaultType`](/docs/configuration#content). A key belongs to one declaration, site-wide or per-type, not both. And a key declared only for another type stays unknown elsewhere, so a stray `status` on a plain doc page still fails the build.
+
 A page that fails validation fails `blume build` with a diagnostic naming the file and key. With [`--no-strict`](/docs/reference/cli#common-flags), the build succeeds anyway and the failing pages are dropped from the output — the build summary reports how many.
 
 Schemas are exported from `blume/schema` for editor and migration tooling.

package/docs/reference/meta.ts

@@ -2,6 +2,6 @@ import { defineMeta } from "blume";
 
 export default defineMeta({
   order: 6,
-  pages: ["frontmatter", "cli", "eval"],
+  pages: ["frontmatter", "cli", "eval", "translate"],
   title: "Reference",
 });

package/docs/reference/translate.mdx

@@ -0,0 +1,80 @@
+---
+title: Translate
+description: blume translate fills in your locales with an AI agent — it finds the pages that are missing or outdated in each language, translates them with the agent CLI you already have, and gives CI a gate that fails when translations drift.
+---
+
+Once [i18n](/docs/content/i18n) is on, every edit to a source page quietly outdates its translations. `blume translate` closes that loop: it computes exactly which pages are missing or stale in each locale, translates them headlessly with a local agent CLI, and records what it did in a committed ledger so the next run — and CI — knows what's current.
+
+```bash
+blume translate --claude
+```
+
+```
+blume translate  3 item(s) · 2 locale(s) · Claude Code
+
+  ✔ docs/guides/install.mdx → fr 24.2s $0.11
+  ✔ docs/guides/install.mdx → de 22.8s $0.10
+  ✔ meta titles (2) → de 4.1s $0.01
+
+  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s · $0.22
+```
+
+## How it works
+
+Blume owns the pipeline; the agent only translates text. For each file that needs work, Blume builds a translation prompt, runs the agent CLI headlessly with its file, shell, and web tools disabled, validates the reply's structure, and writes the target file itself — [Claude Code](https://claude.com/claude-code) with `--claude`, or [Codex](https://developers.openai.com/codex/cli) with `--codex`. Blume holds no API keys and calls no model itself.
+
+Every validated write is recorded in `blume.translations.json` at the project root: for each source file and locale, a hash of the source at the moment it was translated. **Commit this file.** It's how a rerun knows the difference between "already translated" and "translated, but the source changed since" — and it's what makes the CI gate possible.
+
+The ledger is flushed after every finished file, so stopping a long run (Ctrl+C) loses at most the translations that were in flight — the next run picks up where you left off. Files run 4 at a time by default; raise it with `--concurrency` if your machine and the agent's rate limits allow.
+
+Reruns are incremental: a source that hasn't changed since its last translation is skipped, so running `blume translate` after editing one page translates one page per locale. When a stale page is retranslated, the agent is shown the existing translation and told to match its register, dialect, and terminology — a one-paragraph source edit produces a one-paragraph translation diff, not a from-scratch rewrite.
+
+A first translation has no precedent to match, so pin the choice up front with [`style` on the locale](/docs/content/i18n) (`{ code: "pt", label: "Português", style: "Brazilian Portuguese, informal você" }`). The guidance rides along in every translation prompt, and where an existing translation disagrees with it, `style` wins — so a retranslation also nudges older pages toward the configured style.
+
+## What gets translated
+
+- **Pages** — `.md`/`.mdx` files in the default locale. The agent translates the prose and only the human-visible frontmatter values (`title`, `description`, `sidebar.label`, `sidebar.badge`, `seo.title`, `seo.description`). Targets follow your parser: `fr/guides/install.mdx` under `dir`, `guides/install.fr.mdx` under `dot`.
+- **Folder navigation titles** — under the `dir` parser, each locale's needed [`meta.ts`](/docs/content/meta) titles are translated in one batched call, and the generated per-locale `meta.ts` copies every other key (`order`, `pages`, `icon`, `collapsed`) verbatim so the locale's sidebar keeps its ordering.
+
+Translations you wrote by hand are **adopted, never overwritten**: a translation that exists but has no ledger entry is stamped as current and left alone. Only `--force` retranslates it.
+
+## Validation
+
+The agent is never trusted with structure. Before writing, Blume checks each reply and rebuilds the file from the source:
+
+- The frontmatter is reconstructed from the source file's data, with only the six translatable values overlaid — keys the agent invented are dropped, keys it deleted are restored, and `slug`, `icon`, `order`, and dates are source-verbatim by construction.
+- The number of code fences must match the source, the body must be non-empty, and the frontmatter must parse.
+
+A reply that fails validation writes nothing — the item is reported as failed and the run moves on. Everything that succeeded stays stamped in the ledger, so a rerun retries only the failures.
+
+## Failing CI
+
+`blume translate --check` is the read-only gate: it reports every missing and stale pair and exits non-zero when there's drift, without running an agent or writing anything.
+
+```bash
+blume translate --check           # exit 1 when translations are missing or stale
+blume translate --check --json    # machine-readable drift report on stdout
+```
+
+```yaml .github/workflows/translations.yml
+- run: npx blume translate --check
+```
+
+The JSON report carries the same `diagnostics` + `summary` shape as `blume validate --json`, `blume audit --json`, and `blume eval --json`, with the drift grouped per locale. Hand-authored (untracked) translations never fail the gate.
+
+## Limitations
+
+- Meta title translation is `dir`-parser only — the `dot` parser has no per-locale `meta.ts` mechanism. A `meta.ts` that default-exports a function is skipped with a warning; author that locale's copy by hand.
+- Remote and CMS-backed sources are skipped: there is no local file to write the translation to.
+- Header tab labels live in `blume.config.ts`, not content — localize them there with [per-locale label maps](/docs/content/navigation#tabs).
+- Translation quality is the agent's. Review the output like any other contribution — the ledger only guarantees freshness, not fluency.
+
+## Flags
+
+- `--claude` / `--codex` — which agent CLI translates. Exactly one is required (except with `--check`).
+- `--check` — report drift and exit non-zero, without writing anything.
+- `--concurrency <n>` — parallel agent sessions. Defaults to `4`, max `16`.
+- `--locale <codes>` — comma-separated target locales (defaults to every non-default locale).
+- `--force` — retranslate everything, up-to-date and hand-authored files included.
+- `--timeout <seconds>` — agent time limit per file. Defaults to `600`; the ceiling exists to catch hung agents, so large pages have room to finish.
+- `--json` — emit the report as JSON on stdout, in both modes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/ai/agent-readability.ts

@@ -93,12 +93,15 @@ export const buildAgentReadability = (
 
   // Advertise `Accept: text/markdown` negotiation only where the deployed site
   // actually honors it — a Vercel server build, whose routing config gets the
-  // rewrite rules (see `deploy/vercel-negotiation.ts`). Static builds and other
-  // adapters serve prerendered pages from a static layer with no request-time
-  // hook, so agents there should fetch the `.md` pattern directly.
+  // rewrite rules (see `deploy/vercel-negotiation.ts`), and a Cloudflare server
+  // build, whose deploy bundle gets a wrapper Worker (see
+  // `deploy/cloudflare-negotiation.ts`). Static builds and other adapters serve
+  // prerendered pages from a static layer with no request-time hook, so agents
+  // there should fetch the `.md` pattern directly.
   const negotiates =
     config.deployment.output === "server" &&
-    config.deployment.adapter === "vercel";
+    (config.deployment.adapter === "vercel" ||
+      config.deployment.adapter === "cloudflare");
   const artifacts: Record<string, unknown> = {
     markdown: {
       ...(negotiates ? { contentNegotiation: "text/markdown" } : {}),

package/src/ai/ask-context.ts

@@ -226,12 +226,9 @@ export const createAskContext = (
       ? byRoute.get(normalizeRoute(page.path))
       : undefined;
     const db = await index();
-    const hits = await queryOramaIndex(
-      db,
-      query,
-      MAX_RESULTS,
-      current?.locale || undefined
-    );
+    const hits = await queryOramaIndex(db, query, MAX_RESULTS, {
+      locale: current?.locale || undefined,
+    });
 
     const seen = new Set<string>();
     const sections: string[] = [];