blume 1.0.4 → 1.1.0

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

@@ -0,0 +1,41 @@
+/**
+ * The Standard Schema interface (https://standardschema.dev), the minimal
+ * `~standard` surface shared by Zod 3.24+, Zod 4, Valibot, ArkType, and
+ * friends. Blume accepts user-supplied validation schemas (e.g.
+ * `frontmatter.extend`) through this interface instead of Zod's own types:
+ * `blume.config.ts` imports zod from the *consumer's* node_modules, which may
+ * be a different major version than the zod Blume bundles, and calling Zod
+ * methods (`.extend()`, `.safeParse()`) across instances is unsupported. The
+ * `~standard.validate` contract is version- and library-agnostic.
+ */
+/** One validation failure, with an optional path into the checked value. */
+export interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+        readonly key: PropertyKey;
+    })[] | undefined;
+}
+/** A passing validation: the (possibly transformed) output value. */
+export interface StandardSchemaSuccess<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+}
+/** A failing validation: one or more issues. */
+export interface StandardSchemaFailure {
+    readonly issues: readonly StandardSchemaIssue[];
+}
+export type StandardSchemaResult<Output> = StandardSchemaSuccess<Output> | StandardSchemaFailure;
+/** A validation schema exposing the Standard Schema `~standard` contract. */
+export interface StandardSchema<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+/** Whether a config-supplied value implements the `~standard` contract. */
+export declare const isStandardSchema: (value: unknown) => value is StandardSchema;

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

@@ -12,6 +12,13 @@ export interface Diagnostic {
     file?: string;
     line?: number;
     column?: number;
+    /**
+     * The built URL this diagnostic is about, for findings that are a property of
+     * the output rather than of a source file (`blume audit`). Set alongside
+     * `file`/`line` where the page maps back to authored content, so a finding can
+     * name both the URL that's wrong and the frontmatter line that fixes it.
+     */
+    url?: string;
     schemaPath?: string;
     suggestion?: string;
     docsUrl?: string;
@@ -110,6 +117,12 @@ export interface PageRecord {
     description?: string;
     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?: Record<string, unknown>;
     headings: Heading[];
     /** Whether the file is `.md`/`.mdx`. */
     format: "md" | "mdx";

package/dist/types/og/card.d.ts

@@ -0,0 +1,63 @@
+import type { RenderOptions } from "takumi-js";
+/**
+ * A Google Font family to load into the OG card renderer. A bare string is the
+ * family name (weight 400, normal style); the object form pins weight and style.
+ * Handed straight to Takumi's `googleFonts` helper, which fetches the family
+ * from Google Fonts at build and returns per-glyph coverage subsets.
+ */
+export type OgFont = string | {
+    /** Google Fonts family name, e.g. `"Noto Sans JP"`. */
+    name: string;
+    /** `400`, `[400, 700]`, or a variable range like `"100..900"`. */
+    weight?: number | number[] | string;
+    /** `"normal"`, `"italic"`, or both. */
+    style?: "normal" | "italic" | ("normal" | "italic")[];
+};
+export interface OgCardPalette {
+    accent?: string;
+    background?: string;
+    border?: string;
+    foreground?: string;
+    muted?: string;
+}
+export interface OgCardOptions {
+    /** Large headline — the page title. */
+    title: string;
+    /** Accent color (named preset or any CSS color) for the fallback brand mark. */
+    accent?: string;
+    /** Brand/site name shown in the top-left lockup. */
+    brand?: string;
+    /** Muted subtitle under the headline (usually the site description). */
+    description?: string;
+    /**
+     * Inlined SVG markup of the configured logo, painted into
+     * the brand lockup. Falls back to an accent mark when absent.
+     */
+    logo?: string;
+    /** Optional colors for the generated card. */
+    palette?: OgCardPalette;
+    /** Footer-left repository slug, e.g. `owner/repo`. */
+    repo?: string;
+    /** Footer-right site host, e.g. `docs.acme.com`. */
+    site?: string;
+    /**
+     * Pre-fetched image entries, or a group controlling how remote images (and
+     * emoji glyphs) are fetched. Blume merges in a shared glyph cache; see
+     * {@link resolveImages}.
+     */
+    images?: RenderOptions["images"];
+    /**
+     * Google Font families for non-Latin titles. Takumi's built-in font covers
+     * only Latin, so a CJK (etc.) title renders as tofu without a family that
+     * covers its script — see {@link loadFonts}.
+     */
+    fonts?: OgFont[];
+}
+/**
+ * Truncate to `max` code points with an ellipsis. Slices by code points, not
+ * UTF-16 units, so cutting mid-emoji doesn't leave a lone surrogate (a broken
+ * glyph) before the ellipsis.
+ */
+export declare const truncate: (value: string, max: number) => string;
+/** Render a 1200x630 Open Graph card to a PNG buffer. */
+export declare const renderOgImage: (options: OgCardOptions) => Promise<Uint8Array>;

package/dist/types/og/dimensions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Dimensions of a generated OG card, shared by the renderer (`card.ts`) and the
+ * layouts that declare them as `og:image:width`/`og:image:height` so a crawler
+ * can lay out the card without fetching the PNG first.
+ *
+ * This lives apart from `card.ts` because that module imports the Takumi native
+ * binding at load; a layout importing it would drag the renderer into every
+ * page render (and into the prerender/SSR bundles that externalize it).
+ */
+export declare const OG_IMAGE_WIDTH = 1200;
+export declare const OG_IMAGE_HEIGHT = 630;
+export declare const OG_IMAGE_TYPE = "image/png";

package/docs/01-quickstart.mdx

@@ -1,6 +1,6 @@
 ---
 title: Quickstart
-description: Install Blume, scaffold a project, and ship your first page in minutes.
+description: Install Blume, scaffold a new project, and ship your first documentation page in minutes — then grow it into a full site at your own pace.
 sidebar:
   label: Quickstart
   order: 1

package/docs/02-deployment.mdx

@@ -1,6 +1,6 @@
 ---
 title: Deployment
-description: Deploy static docs to any host, or switch to server rendering with an adapter.
+description: Deploy static docs to any host with zero configuration, or switch to server-side rendering with an adapter when you need dynamic behavior.
 sidebar:
   label: Deployment
   order: 2
@@ -119,6 +119,14 @@ redirects: [{ from: "/old", to: "/new", status: 301 }];
 `from` is matched as an exact path — wildcards and pattern matching (e.g. `/blog/:slug` or `/old/*`) aren't supported. If you need pattern-based rules, handle them in an infrastructure file like `vercel.json` (which supports wildcard `source` patterns) or your host's redirect config instead. A `vercel.json` you ship in `public/` is preserved as-is.
 :::
 
+:::note
+Write both `from` and `to` as if mounted at root — under [`deployment.base`](#subpath-deploys) and [`basePath`](#mount-the-docs-under-a-path) alike, Blume rewrites both sides for you, so a redirect lands inside the base. A base you've already written into `to` by hand is preserved rather than doubled.
+:::
+
+## Content types
+
+A static build also emits a `_headers` file that pins `charset=utf-8` onto the raw AI-ready endpoints — `/<route>.md`, `/<route>.mdx`, and the `.txt` files (`llms.txt`, `llms-full.txt`). Those responses are valid UTF-8, but many static hosts serve them as `text/markdown` / `text/plain` with **no** charset, and browsers then fall back to Windows-1252 — so non-ASCII docs (Japanese, accented Latin, …) render as mojibake when the raw URL is opened directly. HTML pages are unaffected because they carry `<meta charset>`. Netlify and Cloudflare (Pages/Workers static assets) read `_headers`; hosts that don't (Vercel, S3) ignore the file harmlessly. A `_headers` you ship in `public/` is left untouched.
+
 ## Environment variables
 
 When a feature needs a runtime secret, Blume warns at `blume dev`/`build` if it's missing — so the problem surfaces early instead of at the first request:

package/docs/advanced/api-reference.mdx

@@ -78,6 +78,17 @@ openapi: {
 
 `spec` is shorthand for a single-entry `sources`, so you only reach for `sources` when you have more than one.
 
+## Authorization
+
+Operations that declare [security requirements](https://spec.openapis.org/oas/v3.1.0#security-requirement-object) render an **Authorization** section above their parameters, and the generated code samples send a placeholder credential (`Authorization: Bearer YOUR_TOKEN`, an API-key header, or a query key — whatever the scheme calls for). There's nothing to configure: Blume reads `security` from the spec, so the reference always matches what the API actually enforces.
+
+The OpenAPI semantics carry over as written:
+
+- An operation's own `security` overrides the document's root default; `security: []` marks it **public** and renders no Authorization section.
+- Multiple requirement entries are alternatives — rendered as "or" groups; every scheme inside one entry is required together. The first alternative feeds the code samples.
+- An empty `{}` entry means auth is **optional** for that operation, and the section says so.
+- OAuth2 scopes are listed per scheme; scheme `description`s from `components.securitySchemes` render inline.
+
 ## The Scalar renderer
 
 The native renderer is the default. If you'd rather embed [Scalar](https://scalar.com)'s self-contained API reference — its own sidebar, search, theme, and "Try it" playground on a single route — set `renderer: "scalar"`:

package/docs/advanced/changelog.mdx

@@ -1,6 +1,6 @@
 ---
 title: Changelog
-description: Author release notes as content, and Blume builds a timeline page and an RSS feed automatically.
+description: Author release notes as ordinary content files or source them from GitHub Releases, and Blume builds a timeline page and an RSS feed automatically.
 ---
 
 Blume ships a changelog out of the box. Write each release as a normal content file, mark it `type: changelog`, and Blume collects every entry into a generated timeline page and an RSS feed — no layout to build, no list to maintain. Or skip the files entirely and [source your changelog from GitHub Releases](#from-github-releases).

package/docs/advanced/skills.mdx

@@ -1,6 +1,6 @@
 ---
 title: Skills
-description: The agent skills Blume ships — playbooks that teach a coding agent to build and maintain a Blume docs site.
+description: The agent skills Blume ships — playbooks that teach a coding agent like Claude Code, Codex, or Cursor to build and maintain a Blume docs site.
 ---
 
 Blume ships [agent skills](https://docs.claude.com/en/docs/claude-code/skills) — playbooks that teach a coding agent (Claude Code, Codex, Cursor) how to do a Blume-shaped job without you explaining it. They live on GitHub in the repo's `skills/` folder and are bundled in the package at `node_modules/blume/skills/` once Blume is installed, so any agent can be pointed at a `SKILL.md` directly.

package/docs/configuration/ai.mdx

@@ -1,6 +1,6 @@
 ---
 title: AI
-description: Machine-readable docs with llms.txt and an optional in-page Ask AI assistant.
+description: Make your docs machine-readable with llms.txt, add an optional in-page Ask AI assistant, and expose a hosted MCP server for coding agents.
 ---
 
 Blume has a few AI features: machine-readable docs for external tools (`llms.txt`, on by default), an in-page **Ask AI** assistant, and a hosted **MCP server** for coding agents. Ask AI and MCP are opt-in, and static docs stay fully static until you turn a feature on.

package/docs/configuration/customization.mdx

@@ -1,6 +1,6 @@
 ---
 title: Customization
-description: Override components, add interactive islands, mount custom pages, install registry components, or eject.
+description: Override components, add interactive islands, mount custom pages, install registry components, or eject entirely when you need full control.
 ---
 
 ## Component overrides

package/docs/configuration/export.mdx

@@ -1,6 +1,6 @@
 ---
 title: Export
-description: Let readers download any page as a PDF or EPUB — client-side, so static builds stay static.
+description: Let readers download any page as a PDF or EPUB — rendered client-side, so your static builds stay static and need no server infrastructure.
 ---
 
 Blume can add an **Export** action to the [page actions](/docs/content/navigation#page-actions) beneath the table of contents, letting readers save the page they're on as a **PDF** or an **EPUB**. It's off by default and entirely client-side — no server, and [static](/docs/deployment) builds stay static.

package/docs/configuration/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Configuration file
-description: Every option in blume.config.ts — site metadata, content, and links to each feature guide.
+description: Every option in blume.config.ts, from site metadata and content sources to the links that lead into each individual feature configuration guide.
 sidebar:
   label: blume.config.ts
 ---
@@ -188,6 +188,26 @@ content: {
 
 Static assets live in `public/` — a file at `public/logo.png` is served at `/logo.png`, so a reference like `![](/images/create.png)` resolves against `public/images/create.png`.
 
+## Frontmatter
+
+Page frontmatter is strictly validated — an unknown key fails the build, so typos are caught early. To carry project-specific metadata (an owner, a review date), declare the extra keys under `frontmatter.extend`, each mapped to a schema you supply:
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+import { z } from "zod";
+
+export default defineConfig({
+  frontmatter: {
+    extend: {
+      owner: z.string(),
+      reviewedAt: z.coerce.date().optional(),
+    },
+  },
+});
+```
+
+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.
+
 ## 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

@@ -1,6 +1,6 @@
 ---
 title: Search
-description: Client-side search out of the box, with optional hosted and semantic backends.
+description: Client-side search that works out of the box with no API keys, plus optional hosted and semantic backends you can switch to as your docs grow.
 ---
 
 Blume ships local search with no hosted infrastructure and no API keys. It runs in the browser, works in both `blume dev` and `blume build`, and indexes only your real content — navigation chrome and excluded pages are skipped. When you outgrow it, you can switch to a hosted or semantic backend without changing how search looks or behaves — only the `search.provider` you configure changes.
@@ -13,6 +13,33 @@ Open search with <Badge variant="accent">⌘K</Badge> (or `Ctrl K`), or press `/
 
 Queries match page **titles**, **descriptions**, and **body text**, with title matches ranked highest and descriptions above body.
 
+## Popular pages
+
+Before a reader types a query, the search dialog shows a **Popular** list. By default it is the first six sidebar pages — which on multi-tab sites often surfaces the wrong section. Pin the links you want instead:
+
+```ts blume.config.ts lineNumbers
+search: {
+  popular: [
+    { href: "/guides/getting-started", icon: "rocket", label: "Getting started" },
+    { href: "/guides/install", icon: "download", label: "Install" },
+    { href: "/concepts/overview", label: "Overview" },
+  ],
+},
+```
+
+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.
+
+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.
+
+<Callout type="warning">
+  A curated list is a single set of links shared by every language. On a site
+  with `i18n` configured, the sidebar fallback follows the reader's locale, but
+  `popular` entries point wherever their `href` says — so pin locale-prefixed
+  routes only if you want every reader sent to that one language.
+</Callout>
+
 ## 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.

package/docs/configuration/seo.mdx

@@ -108,7 +108,7 @@ seo: {
 
 ### Brand the generated card
 
-Set a local SVG and hex palette to match the generated card to your brand. The logo can live in `public/` or at the project root. Omit any palette value to keep its default.
+Set a local SVG and color palette to match the generated card to your brand. The logo can live in `public/` or at the project root. Omit any palette value to keep its default.
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -144,9 +144,28 @@ seo:
 ```
 
 :::note
-OG rendering uses hex internally, so an `oklch` custom accent falls back to the default. Use a named accent (`blue`, `teal`, …) or a hex value for custom cards.
+Every palette color accepts any CSS color — hex, `oklch(…)`, `rgb(…)`, and so on. The accent also accepts a named preset (`blue`, `teal`, …), matching [`theme.accent`](/docs/configuration/theming#accent). A color the renderer can't parse fails the build rather than silently shipping a default-colored card.
 :::
 
+Emoji in a page title or site title render as [Twemoji](https://github.com/jdecked/twemoji) glyphs, fetched from a CDN while the card renders — so a build whose titles contain emoji needs network access. Each glyph is fetched once per build, however many pages use it.
+
+### Non-Latin titles
+
+The card's built-in font covers only Latin glyphs, so a title in another script (Japanese, Chinese, Korean, Arabic, …) renders as tofu — empty boxes. List one or more [Google Fonts](https://fonts.google.com) families in `og.fonts` that cover your script, by name:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: {
+    fonts: [
+      "Noto Sans JP",
+      { name: "Inter", weight: [400, 700] },
+    ],
+  },
+}
+```
+
+Each entry is a family name, or an object pinning its `weight` (a number, a list, or a variable range like `"100..900"`) and `style` (`"normal"`, `"italic"`, or both). The families are fetched from Google Fonts at build — so a build that uses them needs network access — and the renderer only pulls the glyph subsets each title actually uses. Fallback is per-glyph, so adding a family only affects glyphs the built-in font can't draw; Latin text renders exactly as before.
+
 `seo.image` is frontmatter, so it only covers Markdown and MDX content. To give a custom [`.astro` page](/docs/advanced/custom-pages) its own social image — a marketing home or landing page, and the way to give the home page alone a bespoke share image — pass the `ogImage` prop to `PageLayout`.
 
 ## RSS feeds

package/docs/configuration/theming.mdx

@@ -1,6 +1,6 @@
 ---
 title: Theming
-description: Tune the look with config tokens, override any CSS variable in theme.css, or use Tailwind utilities.
+description: Tune the look with a handful of config tokens, override any CSS variable in theme.css, or drop down to Tailwind utilities for custom components.
 ---
 
 Blume's theme is token-driven and works in light and dark mode out of the box. Reach for as little or as much as you need: a few config tokens for the common cases, a `theme.css` to override any design token, or Tailwind utilities for custom components.

package/docs/content/components.mdx

@@ -69,6 +69,20 @@ Switch between equivalent content in place — language variants, OS-specific co
 </Tabs>
 ```
 
+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.
+
+<Tabs inline param="install">
+  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
+  <Tab title="Windows">Use winget to install the toolchain.</Tab>
+</Tabs>
+
+```astro lineNumbers
+<Tabs inline param="install">
+  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
+  <Tab title="Windows">Use winget to install the toolchain.</Tab>
+</Tabs>
+```
+
 ## Badge
 
 A small inline label for status or metadata — version tags, “new” or “beta” markers, stability levels. The `variant` tunes the color to the meaning.

package/docs/content/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Pages
-description: How files in your content folder become pages, and how to organize them.
+description: How the files in your content folder become pages, and how to organize and name them so routing and navigation are inferred automatically.
 ---
 
 Your docs are just a folder of Markdown and MDX files. Blume turns each file into a page — routing, navigation, and metadata are inferred from the file system, so there's no manifest to keep in sync.

package/docs/content/meta.mdx

@@ -1,6 +1,6 @@
 ---
 title: Folder meta
-description: Configure a sidebar group — its title, icon, order, and page order — with a meta.ts file.
+description: Configure a sidebar group with a meta.ts file beside its pages — set the group's title, icon, order, and the order of the pages nested inside.
 ---
 
 Every folder in your content tree becomes a sidebar group. Drop a `meta.ts` beside its pages to control how that group looks and how its children are ordered. It's entirely optional: without one, the group's label is the humanized folder name and its pages sort by [index, numeric prefix, then alphabetically](/docs/content/navigation#ordering).

package/docs/content/navigation.mdx

@@ -1,6 +1,6 @@
 ---
 title: Navigation
-description: Build the sidebar from your files, then refine it with frontmatter, folder meta, or config.
+description: Blume builds the sidebar from your files, then lets you refine it with frontmatter, folder meta, or config — breadcrumbs and outlines follow along.
 ---
 
 Blume builds your sidebar from the file system, then lets you refine it as much — or as little — as you want: page by page, folder by folder, or with one explicit config. Breadcrumbs, previous/next links, and the on-page outline all follow from the same model, with nothing to wire up.

package/docs/content/sources.mdx

@@ -1,6 +1,6 @@
 ---
 title: Content sources
-description: Pull docs from local files, a remote repo, or any custom backend — and mix several sources into one site.
+description: Pull docs from local files, a remote repository, or any custom backend — and mix several sources into one static-first site read at build time.
 ---
 
 By default Blume reads a folder of `.md`/`.mdx` files. **Content sources** let you pull pages from somewhere else — a remote repository, a CMS, or any custom backend — and mix several sources into a single site. Sources are read at build time; Blume stays static-first.

package/docs/reference/cli.mdx

@@ -1,6 +1,6 @@
 ---
 title: CLI
-description: Every Blume command and flag — init, dev, build, preview, add, sync, and eject.
+description: Every Blume command and flag explained in one place — init, dev, build, preview, add, sync, and eject — along with the options each one accepts.
 ---
 
 ```bash
@@ -21,6 +21,7 @@ blume <command> [options]
 | `blume check`      | Type-check the site with `astro check`.          |
 | `blume doctor`     | Diagnose config and content problems.            |
 | `blume validate`   | Validate links across your content.              |
+| `blume audit`      | Audit the built site for SEO and health issues.  |
 
 ## Common flags
 
@@ -49,6 +50,14 @@ blume <command> [options]
 - `blume validate --external` — also check external links over the network.
 - `blume validate --strict` — exit non-zero on warnings too.
 - `blume validate --json` / `blume doctor --json` — emit diagnostics as JSON on stdout (with `code`, `severity`, `file`, `line`/`column`, and `docsUrl`) for CI and editor integrations.
+- `blume audit --fail-on error|warning|info` — the CI gate; defaults to `error`. `--strict` is an alias for `--fail-on warning`.
+- `blume audit --url <origin>` — also probe a live deployment for status codes, response headers, and redirect chains.
+- `blume audit --external` — probe outbound links over the network.
+- `blume audit --only <check|category>` / `--skip <check|category>` — narrow the report while you work through it (comma-separated).
+- `blume audit --list-checks` — print every check the audit can report.
+- `blume audit --verbose` — list every affected page instead of the first few.
+- `blume audit --json` — emit the report as JSON on stdout.
+- `blume audit --claude` / `--codex` — hand the findings to Claude Code or Codex to fix interactively.
 
 ## Verifying while the dev server runs
 
@@ -107,3 +116,72 @@ Without a project `tsconfig.json`, only the generated runtime is checked.
 - **Anchor links** (`#section`, `/guides/intro#setup`) must match a heading on the target page — misses are warnings.
 - **Asset links** (`/logo.png`) are checked against the `public/` directory.
 - **External links** are only checked with `--external` (off by default since it requires the network); dead links (404/410/unreachable) are errors, while rate-limited or transient responses (403/429/5xx/timeout) are warnings.
+
+## Auditing the built site
+
+`blume validate` reads your _content_; `blume audit` reads the _built site_. It crawls the HTML in `dist/` after a build and reports SEO and site-health issues — titles, meta descriptions, canonicals, Open Graph and X cards, headings, hreflang, images, the sitemap, `robots.txt`, and structured data.
+
+Because Blume built the site, every finding names the source file **and the front matter line** that fixes it, not just the URL a crawler would see:
+
+```
+⚠ Meta description too long or too short   5 pages
+    /docs/configuration/export    content/docs/configuration/export.mdx:3
+    fix: Rewrite `description` in the frontmatter to fit the length range.
+```
+
+Run it after a build:
+
+```bash
+blume build
+blume audit
+```
+
+Findings are grouped by check rather than listed per page, so the report reads as a to-do list. Use `--verbose` to expand every affected page, and `--only`/`--skip` to work through one category at a time. `blume audit --list-checks` prints the full catalog.
+
+### Failing CI
+
+The exit code is the contract. By default `blume audit` fails only on errors — things that are definitely broken, like a link to a page that was never built, a redirect loop, or an invalid sitemap. Advisory findings (a short description, a duplicate title) are warnings and do not fail the build:
+
+```bash
+blume audit                      # fails on errors
+blume audit --fail-on warning    # also fails on warnings
+```
+
+### Checking a live deployment
+
+Some things only the real server can tell you: whether a page that exists in `dist/` actually 404s behind a bad rewrite, whether responses are compressed, and whether an `X-Robots-Tag` header is quietly deindexing a page whose HTML looks perfectly fine. Point the audit at a deployment to add those checks:
+
+```bash
+blume audit --url https://docs.example.com
+blume audit --url https://docs.example.com --external   # also probe outbound links
+```
+
+Outbound links are graded rather than flatly failed: a 404 is a broken link you can fix, while a 403 or 5xx is usually rate limiting or someone else's outage and is reported as a warning.
+
+### Fixing the findings with an agent
+
+If you use [Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex/cli), the audit can hand its findings straight to it:
+
+```bash
+blume audit --claude   # or --codex
+```
+
+This writes the complete JSON report — every affected page, not the terminal's three-page preview — to a file and opens the agent interactively with a prompt that walks it through the findings: edit the source file each finding names, apply its suggested fix, then run `blume build` and `blume audit` again until the report is clean. The session is interactive by design: you review the edits through the agent's own permission flow, and the agent is told never to fix a finding by deleting content.
+
+`--only` and `--skip` narrow the handoff the same way they narrow the report, so you can send one category at a time.
+
+### What it does and doesn't check
+
+The check set is deliberately narrower than a general-purpose SEO crawler's. Much of what such a crawler reports cannot happen to a Blume site — it never emits `rel=nofollow`, and Vite's content-hashed bundles are never missing or redirecting — and reporting those as permanent zeroes would just teach you to ignore the report.
+
+Two limits worth stating plainly:
+
+- **Structured data** is validated for well-formedness (valid JSON, a `@context`, a `@type` on every node). Blume does not validate against the full schema.org vocabulary or Google's rich-results rules.
+- **Core Web Vitals** are not checked. They need a real browser, and a flag that quietly measured nothing would be worse than not having one — so `blume audit` reports the layout-shift causes it _can_ see offline (images with no `width`/`height`, oversized assets) and leaves the rest alone for now.
+
+Anything the audit did not run is reported as skipped rather than silently passing:
+
+```
+⊘ network      skipped — pass --url <origin> (9 checks)
+⊘ external     skipped — pass --external (2 checks)
+```

package/docs/reference/frontmatter.mdx

@@ -1,6 +1,6 @@
 ---
 title: Frontmatter
-description: Every frontmatter field a page accepts — title, description, sidebar, SEO, search, and more.
+description: Every frontmatter field a page accepts, all optional — title, description, sidebar, SEO, search, and the rest, with what each one controls.
 ---
 
 Every page accepts the following frontmatter. All fields are optional.
@@ -81,4 +81,32 @@ changelog:
 
 `date` may live here or at the top level — both feed the [changelog RSS feed](/docs/content#feeds). See [Changelog](/docs/advanced/changelog) for the generated timeline page and feed.
 
+## Custom keys
+
+Any key outside this reference fails the build, so typos are caught early. Projects that carry their own metadata can opt extra keys in via [`frontmatter.extend`](/docs/configuration#frontmatter) in `blume.config.ts`, each validated by a schema the project supplies:
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+import { z } from "zod";
+
+export default defineConfig({
+  frontmatter: {
+    extend: {
+      owner: z.string(),
+      reviewedAt: z.coerce.date().optional(),
+    },
+  },
+});
+```
+
+```yaml page.mdx
+---
+title: Install
+owner: "@sam"
+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.
+
 Schemas are exported from `blume/schema` for editor and migration tooling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -86,8 +86,6 @@
     "@shikijs/twoslash": "^4.2.0",
     "@tailwindcss/typography": "^0.5.20",
     "@tailwindcss/vite": "^4",
-    "@takumi-rs/core": "^1.8.7",
-    "@takumi-rs/helpers": "^1.8.7",
     "@vercel/analytics": "^2.0.1",
     "ai": "^5.0.0",
     "astro": "^7.0.2",
@@ -103,6 +101,7 @@
     "katex": "^0.17.0",
     "marked": "^18.0.5",
     "mermaid": "^11.15.0",
+    "node-html-parser": "^9.0.0",
     "pagefind": "^1.3.0",
     "pathe": "^2.0.0",
     "react": "^19.0.0",
@@ -111,6 +110,7 @@
     "shiki": "^4.2.0",
     "simple-icons": "^13.0.0",
     "tailwindcss": "^4",
+    "takumi-js": "^2.2.1",
     "tinyglobby": "^0.2.10",
     "typescript": "^6.0.3",
     "undici": "^8.6.0",

package/skills/blume-migrate/SKILL.md

@@ -66,7 +66,7 @@ The single biggest shift for most sources — especially Mintlify — is that **
 - **`content`:** `root` (default `"docs"`, relative to the project dir where `blume` runs), `include`/`exclude` (arrays of globs **relative to `content.root`**; defaults `["**/*.{md,mdx}"]` / `["**/_*", "**/.*"]`), `sources` (staged sources: `filesystem`, `github-releases`, `notion`, `sanity`, `mdx-remote`, `custom` — OpenAPI is **not** one of these; it's the top-level `openapi` field), `pages` (custom `.astro` dir), `defaultType`. When docs sit directly under the project dir (no `docs/` subfolder), set `root` there and **scope `include` to the real content folders** instead of scanning everything — `references/monorepo.md` §1.
 - **`basePath`** (top-level): a site-wide mount point (e.g. `"/docs"`) prepended to **every** route while staying invisible to the sidebar (no wrapper group). This is the right target for a source that served all docs under a prefix (Docusaurus `routeBasePath`, a Fumadocs `baseUrl` of `/docs`) — distinct from a per-source `prefix` (which adds a nav group) and from `deployment.base` (host subdirectory).
 - **`navigation`:** `tabs`, `selectors`, `featured` (links pinned above the sidebar on every route), `sidebar` (`{ display, items }` — `display` is the global render mode above; `items` is an explicit tree), `repo`. **Avoid an explicit `navigation.sidebar` unless you have to** — lean on the filesystem-derived sidebar. It only works when the file tree roughly matches the intended sidebar layout, so reshape folders to match first; reach for `sidebar.items` only for a shape files genuinely can't express (see "Config-declared nesting" above).
-- **`search`** (Orama default, Pagefind opt-in), **`ai`** (llms.txt, Ask AI), **`mcp`**, **`openapi`**, **`redirects`**, **`seo`**, **`markdown`**, **`analytics`**, **`deployment`**, **`i18n`**, **`toc`**, **`lastModified`**, **`github`**.
+- **`search`** (Orama default, Pagefind opt-in), **`ai`** (llms.txt, Ask AI, the MCP server), **`openapi`**, **`redirects`**, **`seo`**, **`markdown`**, **`analytics`**, **`deployment`**, **`i18n`**, **`toc`**, **`lastModified`**, **`github`**.
 - **Don't set `deployment.site`.** Blume auto-fills it: the dev server's `localhost` URL in dev, and the deployment URL (`VERCEL_PROJECT_PRODUCTION_URL`/`VERCEL_URL`) on Vercel. Hardcoding it in `blume.config.ts` overrides that auto-detection and pins the wrong absolute URL (canonical links, sitemap, OG, llms.txt) everywhere but the one host you typed — so leave it unset even when a source config had a `url`/`site` field. (Sitemap still generates in production because the deploy URL is present there.)
 - **Favicon is a filename convention, not config.** Drop `icon`/`favicon.{svg,png,ico}` (and `apple-icon.png`) in the project root or `public/` — Blume auto-detects it. There is **no** `favicon` config field. A source favicon given as `{ light, dark }` **collapses to one** — pick a single file and report the loss.