blume 1.0.4 → 1.1.1

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

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import type { ContentSource } from "./sources/types.ts";
+import type { StandardSchema } from "./standard-schema.ts";
 declare const hydrationMode: z.ZodEnum<["load", "idle", "visible", "media", "only"]>;
 export type HydrationMode = z.infer<typeof hydrationMode>;
 /** Frontmatter accepted on any content page. */
@@ -1759,6 +1760,14 @@ export declare const blumeConfigSchema: z.ZodObject<{
         pdf?: boolean | undefined;
     }>>;
     feedback: z.ZodDefault<z.ZodBoolean>;
+    /** Opt-in custom frontmatter keys, validated by user-supplied schemas. */
+    frontmatter: z.ZodDefault<z.ZodObject<{
+        extend: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<StandardSchema<unknown, unknown>, z.ZodTypeDef, StandardSchema<unknown, unknown>>>>, Record<string, StandardSchema<unknown, unknown>>, Record<string, StandardSchema<unknown, unknown>> | undefined>;
+    }, "strict", z.ZodTypeAny, {
+        extend: Record<string, StandardSchema<unknown, unknown>>;
+    }, {
+        extend?: Record<string, StandardSchema<unknown, unknown>> | undefined;
+    }>>;
     github: z.ZodOptional<z.ZodObject<{
         branch: z.ZodDefault<z.ZodString>;
         /** Path from the repo root to the project root (for monorepos). */
@@ -1848,9 +1857,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
     lastModified: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodObject<{
         type: z.ZodDefault<z.ZodEnum<["git", "frontmatter"]>>;
     }, "strict", z.ZodTypeAny, {
-        type: "git" | "frontmatter";
+        type: "frontmatter" | "git";
     }, {
-        type?: "git" | "frontmatter" | undefined;
+        type?: "frontmatter" | "git" | undefined;
     }>]>>;
     logo: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodObject<{
         href: z.ZodOptional<z.ZodString>;
@@ -2288,6 +2297,20 @@ export declare const blumeConfigSchema: z.ZodObject<{
             endpoint: string;
             indexId?: string | undefined;
         }>>;
+        /** Curated links for the Cmd+K empty state; defaults to the first sidebar pages. */
+        popular: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            href: z.ZodString;
+            icon: z.ZodOptional<z.ZodString>;
+            label: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            label: string;
+            href: string;
+            icon?: string | undefined;
+        }, {
+            label: string;
+            href: string;
+            icon?: string | undefined;
+        }>, "many">>;
         provider: z.ZodDefault<z.ZodEnum<["orama", "pagefind", "flexsearch", "algolia", "orama-cloud", "typesense", "mixedbread", "none"]>>;
         typesense: z.ZodOptional<z.ZodObject<{
             collection: z.ZodString;
@@ -2313,6 +2336,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
         indexing: {
             includeHiddenPages: boolean;
         };
+        popular: {
+            label: string;
+            href: string;
+            icon?: string | undefined;
+        }[];
         algolia?: {
             appId: string;
             indexName: string;
@@ -2351,6 +2379,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
             endpoint: string;
             indexId?: string | undefined;
         } | undefined;
+        popular?: {
+            label: string;
+            href: string;
+            icon?: string | undefined;
+        }[] | undefined;
         typesense?: {
             host: string;
             searchApiKey: string;
@@ -2363,6 +2396,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
         indexing: {
             includeHiddenPages: boolean;
         };
+        popular: {
+            label: string;
+            href: string;
+            icon?: string | undefined;
+        }[];
         algolia?: {
             appId: string;
             indexName: string;
@@ -2401,6 +2439,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
             endpoint: string;
             indexId?: string | undefined;
         } | undefined;
+        popular?: {
+            label: string;
+            href: string;
+            icon?: string | undefined;
+        }[] | undefined;
         typesense?: {
             host: string;
             searchApiKey: string;
@@ -2446,6 +2489,24 @@ export declare const blumeConfigSchema: z.ZodObject<{
              * `loadConfig`. An explicit value here always wins.
              */
             enabled: z.ZodOptional<z.ZodBoolean>;
+            /**
+             * Google Font families for the generated card, extending Takumi's Latin-only
+             * default so non-Latin titles (CJK, and so on) render instead of tofu.
+             * Fetched from Google Fonts at build.
+             */
+            fonts: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+                name: z.ZodString;
+                style: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["normal", "italic"]>, z.ZodArray<z.ZodEnum<["normal", "italic"]>, "many">]>>;
+                weight: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodArray<z.ZodNumber, "many">, z.ZodString]>>;
+            }, "strict", z.ZodTypeAny, {
+                name: string;
+                style?: "normal" | "italic" | ("normal" | "italic")[] | undefined;
+                weight?: string | number | number[] | undefined;
+            }, {
+                name: string;
+                style?: "normal" | "italic" | ("normal" | "italic")[] | undefined;
+                weight?: string | number | number[] | undefined;
+            }>]>, "many">>;
             /** Local SVG used in the generated card instead of the site logo. */
             logo: z.ZodOptional<z.ZodString>;
             /** Optional generated-card colors. */
@@ -2468,9 +2529,21 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             }>>;
+            /**
+             * Card headlines for custom `.astro` pages, keyed by route (`"/"`, `"/cli"`).
+             * A custom page has no frontmatter to read, so its card is otherwise titled
+             * by humanizing its last URL segment (`/cli` → "Cli"); an entry here wins.
+             * Content pages always take their card headline from the page title.
+             */
+            titles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, "strict", z.ZodTypeAny, {
             enabled?: boolean | undefined;
             logo?: string | undefined;
+            fonts?: (string | {
+                name: string;
+                style?: "normal" | "italic" | ("normal" | "italic")[] | undefined;
+                weight?: string | number | number[] | undefined;
+            })[] | undefined;
             palette?: {
                 accent?: string | undefined;
                 background?: string | undefined;
@@ -2478,9 +2551,15 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         }, {
             enabled?: boolean | undefined;
             logo?: string | undefined;
+            fonts?: (string | {
+                name: string;
+                style?: "normal" | "italic" | ("normal" | "italic")[] | undefined;
+                weight?: string | number | number[] | undefined;
+            })[] | undefined;
             palette?: {
                 accent?: string | undefined;
                 background?: string | undefined;
@@ -2488,6 +2567,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         }>>;
         /** Generate robots.txt (with a Sitemap reference when available). */
         robots: z.ZodDefault<z.ZodBoolean>;
@@ -2533,6 +2613,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
         og: {
             enabled?: boolean | undefined;
             logo?: string | undefined;
+            fonts?: (string | {
+                name: string;
+                style?: "normal" | "italic" | ("normal" | "italic")[] | undefined;
+                weight?: string | number | number[] | undefined;
+            })[] | undefined;
             palette?: {
                 accent?: string | undefined;
                 background?: string | undefined;
@@ -2540,6 +2625,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         };
         robots: boolean;
         rss: {
@@ -2563,6 +2649,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
         og?: {
             enabled?: boolean | undefined;
             logo?: string | undefined;
+            fonts?: (string | {
+                name: string;
+                style?: "normal" | "italic" | ("normal" | "italic")[] | undefined;
+                weight?: string | number | number[] | undefined;
+            })[] | undefined;
             palette?: {
                 accent?: string | undefined;
                 background?: string | undefined;
@@ -2570,6 +2661,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         } | undefined;
         robots?: boolean | undefined;
         rss?: {
@@ -2651,15 +2743,15 @@ export declare const blumeConfigSchema: z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<["system", "light", "dark"]>>;
         radius: z.ZodDefault<z.ZodEnum<["none", "sm", "md", "lg"]>>;
     }, "strict", z.ZodTypeAny, {
-        accent: {
-            dark: string;
-            light: string;
-        };
         fonts: {
             mono: string;
             display: string;
             body: string;
         };
+        accent: {
+            dark: string;
+            light: string;
+        };
         layout: "sidebar";
         mode: "dark" | "light" | "system";
         radius: "none" | "sm" | "md" | "lg";
@@ -2673,6 +2765,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
             light?: string | undefined;
         } | undefined;
     }, {
+        fonts?: {
+            mono?: string | undefined;
+            display?: string | undefined;
+            body?: string | undefined;
+        } | undefined;
         accent?: string | {
             dark: string;
             light: string;
@@ -2686,11 +2783,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
             dark?: string | undefined;
             light?: string | undefined;
         } | undefined;
-        fonts?: {
-            mono?: string | undefined;
-            display?: string | undefined;
-            body?: string | undefined;
-        } | undefined;
         layout?: "sidebar" | undefined;
         mode?: "dark" | "light" | "system" | undefined;
         radius?: "none" | "sm" | "md" | "lg" | undefined;
@@ -2722,6 +2814,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
     } | undefined>;
 }, "strict", z.ZodTypeAny, {
     title: string;
+    frontmatter: {
+        extend: Record<string, StandardSchema<unknown, unknown>>;
+    };
     openapi: {
         enabled: boolean;
         route: string;
@@ -2839,15 +2934,15 @@ export declare const blumeConfigSchema: z.ZodObject<{
         })[] | undefined;
     };
     theme: {
-        accent: {
-            dark: string;
-            light: string;
-        };
         fonts: {
             mono: string;
             display: string;
             body: string;
         };
+        accent: {
+            dark: string;
+            light: string;
+        };
         layout: "sidebar";
         mode: "dark" | "light" | "system";
         radius: "none" | "sm" | "md" | "lg";
@@ -2863,7 +2958,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
     };
     basePath: string;
     lastModified: boolean | {
-        type: "git" | "frontmatter";
+        type: "frontmatter" | "git";
     };
     deployment: {
         adapter: "vercel" | "node" | "netlify" | "cloudflare" | null;
@@ -2942,6 +3037,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
         indexing: {
             includeHiddenPages: boolean;
         };
+        popular: {
+            label: string;
+            href: string;
+            icon?: string | undefined;
+        }[];
         algolia?: {
             appId: string;
             indexName: string;
@@ -2973,6 +3073,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
         og: {
             enabled?: boolean | undefined;
             logo?: string | undefined;
+            fonts?: (string | {
+                name: string;
+                style?: "normal" | "italic" | ("normal" | "italic")[] | undefined;
+                weight?: string | number | number[] | undefined;
+            })[] | undefined;
             palette?: {
                 accent?: string | undefined;
                 background?: string | undefined;
@@ -2980,6 +3085,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         };
         robots: boolean;
         rss: {
@@ -3051,6 +3157,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
     } | undefined;
 }, {
     title?: string | undefined;
+    frontmatter?: {
+        extend?: Record<string, StandardSchema<unknown, unknown>> | undefined;
+    } | undefined;
     openapi?: {
         enabled?: boolean | undefined;
         route?: string | undefined;
@@ -3181,6 +3290,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
         vercel?: boolean | undefined;
     } | undefined;
     theme?: {
+        fonts?: {
+            mono?: string | undefined;
+            display?: string | undefined;
+            body?: string | undefined;
+        } | undefined;
         accent?: string | {
             dark: string;
             light: string;
@@ -3194,11 +3308,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
             dark?: string | undefined;
             light?: string | undefined;
         } | undefined;
-        fonts?: {
-            mono?: string | undefined;
-            display?: string | undefined;
-            body?: string | undefined;
-        } | undefined;
         layout?: "sidebar" | undefined;
         mode?: "dark" | "light" | "system" | undefined;
         radius?: "none" | "sm" | "md" | "lg" | undefined;
@@ -3221,7 +3330,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
     } | undefined;
     description?: string | undefined;
     lastModified?: boolean | {
-        type?: "git" | "frontmatter" | undefined;
+        type?: "frontmatter" | "git" | undefined;
     } | undefined;
     deployment?: {
         adapter?: "vercel" | "node" | "netlify" | "cloudflare" | null | undefined;
@@ -3334,6 +3443,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
             endpoint: string;
             indexId?: string | undefined;
         } | undefined;
+        popular?: {
+            label: string;
+            href: string;
+            icon?: string | undefined;
+        }[] | undefined;
         typesense?: {
             host: string;
             searchApiKey: string;
@@ -3352,6 +3466,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
         og?: {
             enabled?: boolean | undefined;
             logo?: string | undefined;
+            fonts?: (string | {
+                name: string;
+                style?: "normal" | "italic" | ("normal" | "italic")[] | undefined;
+                weight?: string | number | number[] | undefined;
+            })[] | undefined;
             palette?: {
                 accent?: string | undefined;
                 background?: string | undefined;
@@ -3359,6 +3478,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         } | undefined;
         robots?: boolean | undefined;
         rss?: {
@@ -3380,6 +3500,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
 }>;
 /** Resolved config: every field present after defaults are applied. */
 export type ResolvedConfig = z.infer<typeof blumeConfigSchema>;
+/** Resolved `frontmatter.extend`: custom key → user-supplied schema. */
+export type FrontmatterExtend = Record<string, StandardSchema>;
 /** Resolved i18n block (present only when the project opts into i18n). */
 export type ResolvedI18nConfig = z.infer<typeof i18nConfigSchema>;
 /** A configured locale with display metadata. */

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

@@ -1,4 +1,4 @@
-import type { ResolvedI18nConfig } from "../schema.ts";
+import type { FrontmatterExtend, ResolvedI18nConfig } from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 /**
  * A single content item, normalized by a source adapter. Adapters lower their
@@ -111,5 +111,7 @@ export interface NormalizeContext {
     /** Site-wide route mount point (`""` or `/seg`), prepended to every route. */
     basePath?: string;
     defaultType: string;
+    /** Opt-in custom frontmatter keys (`frontmatter.extend`), schema per key. */
+    frontmatterExtend?: FrontmatterExtend;
     i18n?: ResolvedI18nConfig;
 }

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;
@@ -96,6 +103,13 @@ export interface PageRecord {
      * `/guides/x`). Pages with the same key are translations of each other.
      */
     translationKey: string;
+    /**
+     * True for entries filled in from the fallback locale to pad a locale's
+     * navigation for pages it hasn't translated yet. The record's content —
+     * title included — belongs to the fallback locale, so per-locale content
+     * checks skip these.
+     */
+    fallback?: boolean;
     /**
      * Content-relative path with the leading locale directory stripped, used for
      * sidebar grouping so the locale dir is not surfaced as a nav group. Equals
@@ -110,6 +124,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).
@@ -87,7 +87,7 @@ content: {
 }
 ```
 
-The release name becomes the title, its tag becomes `changelog.version`, and its published date sorts the timeline. A private repo authenticates with the `GITHUB_TOKEN` environment variable. See [Content sources](/docs/content/sources#github-releases) for every option.
+The release name becomes the title, its tag becomes `changelog.version`, and its published date sorts the timeline. Each release page also gets a unique meta description summarized from its notes — markdown stripped, section headings and changeset commit-hash prefixes dropped, trimmed to the search-snippet length [`blume audit`](/docs/reference/cli#auditing-the-built-site) checks for — instead of falling back to the site description. A private repo authenticates with the `GITHUB_TOKEN` environment variable. See [Content sources](/docs/content/sources#github-releases) for every option.
 
 ## The RSS feed
 

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.