blume 0.4.0 → 0.5.0

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

@@ -87,6 +87,8 @@ export interface BlumeDataConfig {
     favicon: BlumeFavicon;
     feedback: boolean;
     i18n: BlumeDataI18n | null;
+    /** Default icon library for bare `icon` names. */
+    icons: ResolvedConfig["icons"];
     /** `markdown.imageZoom`: click-to-zoom content images. */
     imageZoom: boolean;
     logo: BlumeLogo | null;

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

@@ -2,8 +2,18 @@ import type { ResolvedConfig } from "./schema.ts";
 import type { ProjectContext } from "./types.ts";
 /** Locate the Blume config file for a project root, if any. */
 export declare const findConfigFile: (root: string) => string | null;
+/**
+ * Resolve the generated runtime directory for a project. Defaults to
+ * `<root>/.blume`; an override (e.g. `.blume-verify` for an isolated build that
+ * runs alongside a live `blume dev`) may be relative to the root or absolute.
+ */
+export declare const resolveRuntimeDir: (root: string, runtimeDir?: string) => string;
 /**
  * Resolve every path Blume needs from a project root and its resolved config.
- * Paths are absolute and normalized.
+ * Paths are absolute and normalized. `options.runtimeDir` relocates the whole
+ * generated runtime (and its build output) so a verify build/check can run
+ * without touching a live dev server's `.blume/` or the real `dist/`.
  */
-export declare const resolveProjectContext: (root: string, config: ResolvedConfig) => ProjectContext;
+export declare const resolveProjectContext: (root: string, config: ResolvedConfig, options?: {
+    runtimeDir?: string;
+}) => ProjectContext;

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

@@ -4,6 +4,38 @@ declare const hydrationMode: z.ZodEnum<["load", "idle", "visible", "media", "onl
 export type HydrationMode = z.infer<typeof hydrationMode>;
 /** Frontmatter accepted on any content page. */
 declare const pageMetaBaseSchema: z.ZodObject<{
+    /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
+    authors: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>]>, "many">]>>;
     changelog: z.ZodOptional<z.ZodObject<{
         category: z.ZodOptional<z.ZodString>;
         date: z.ZodOptional<z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodDate]>, string, string | Date>>;
@@ -58,14 +90,14 @@ declare const pageMetaBaseSchema: z.ZodObject<{
         noindex: boolean;
         title?: string | undefined;
         description?: string | undefined;
-        canonical?: string | undefined;
         image?: string | undefined;
+        canonical?: string | undefined;
     }, {
         title?: string | undefined;
         description?: string | undefined;
+        image?: string | undefined;
         noindex?: boolean | undefined;
         canonical?: string | undefined;
-        image?: string | undefined;
     }>>;
     sidebar: z.ZodDefault<z.ZodObject<{
         badge: z.ZodOptional<z.ZodString>;
@@ -107,8 +139,8 @@ declare const pageMetaBaseSchema: z.ZodObject<{
         noindex: boolean;
         title?: string | undefined;
         description?: string | undefined;
-        canonical?: string | undefined;
         image?: string | undefined;
+        canonical?: string | undefined;
     };
     sidebar: {
         hidden: boolean;
@@ -120,6 +152,17 @@ declare const pageMetaBaseSchema: z.ZodObject<{
     date?: string | undefined;
     title?: string | undefined;
     description?: string | undefined;
+    authors?: string | z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | (string | z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">)[] | undefined;
     changelog?: {
         date?: string | undefined;
         category?: string | undefined;
@@ -147,6 +190,17 @@ declare const pageMetaBaseSchema: z.ZodObject<{
         tags?: string[] | undefined;
     } | undefined;
     description?: string | undefined;
+    authors?: string | z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | (string | z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">)[] | undefined;
     changelog?: {
         date?: string | Date | undefined;
         category?: string | undefined;
@@ -169,9 +223,9 @@ declare const pageMetaBaseSchema: z.ZodObject<{
     seo?: {
         title?: string | undefined;
         description?: string | undefined;
+        image?: string | undefined;
         noindex?: boolean | undefined;
         canonical?: string | undefined;
-        image?: string | undefined;
     } | undefined;
     sidebar?: {
         label?: string | undefined;
@@ -185,6 +239,38 @@ declare const pageMetaBaseSchema: z.ZodObject<{
     tag?: string | undefined;
 }>;
 export declare const pageMetaSchema: z.ZodObject<{
+    /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
+    authors: z.ZodOptional<z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>]>, "many">]>>;
     changelog: z.ZodOptional<z.ZodObject<{
         category: z.ZodOptional<z.ZodString>;
         date: z.ZodOptional<z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodDate]>, string, string | Date>>;
@@ -239,14 +325,14 @@ export declare const pageMetaSchema: z.ZodObject<{
         noindex: boolean;
         title?: string | undefined;
         description?: string | undefined;
-        canonical?: string | undefined;
         image?: string | undefined;
+        canonical?: string | undefined;
     }, {
         title?: string | undefined;
         description?: string | undefined;
+        image?: string | undefined;
         noindex?: boolean | undefined;
         canonical?: string | undefined;
-        image?: string | undefined;
     }>>;
     sidebar: z.ZodDefault<z.ZodObject<{
         badge: z.ZodOptional<z.ZodString>;
@@ -288,8 +374,8 @@ export declare const pageMetaSchema: z.ZodObject<{
         noindex: boolean;
         title?: string | undefined;
         description?: string | undefined;
-        canonical?: string | undefined;
         image?: string | undefined;
+        canonical?: string | undefined;
     };
     sidebar: {
         hidden: boolean;
@@ -301,6 +387,17 @@ export declare const pageMetaSchema: z.ZodObject<{
     date?: string | undefined;
     title?: string | undefined;
     description?: string | undefined;
+    authors?: string | z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | (string | z.objectOutputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">)[] | undefined;
     changelog?: {
         date?: string | undefined;
         category?: string | undefined;
@@ -328,6 +425,17 @@ export declare const pageMetaSchema: z.ZodObject<{
         tags?: string[] | undefined;
     } | undefined;
     description?: string | undefined;
+    authors?: string | z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | (string | z.objectInputType<{
+        avatar: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">)[] | undefined;
     changelog?: {
         date?: string | Date | undefined;
         category?: string | undefined;
@@ -350,9 +458,9 @@ export declare const pageMetaSchema: z.ZodObject<{
     seo?: {
         title?: string | undefined;
         description?: string | undefined;
+        image?: string | undefined;
         noindex?: boolean | undefined;
         canonical?: string | undefined;
-        image?: string | undefined;
     } | undefined;
     sidebar?: {
         label?: string | undefined;
@@ -827,8 +935,8 @@ declare const i18nConfigSchema: z.ZodEffects<z.ZodObject<{
     ui?: Record<string, Record<string, Record<string, string>>> | undefined;
 }>;
 /**
- * A single spec rendered by the API reference (Scalar). `spec` is a local path
- * or an `http(s)` URL; Scalar auto-detects OpenAPI vs AsyncAPI documents.
+ * A single spec rendered by the API reference. `spec` is a local path or an
+ * `http(s)` URL (OpenAPI for the Blume renderer; OpenAPI or AsyncAPI for Scalar).
  */
 declare const openapiSourceSchema: z.ZodObject<{
     /** Nav/section label for this source. */
@@ -1643,6 +1751,13 @@ export declare const blumeConfigSchema: z.ZodObject<{
         parser?: "dir" | "dot" | undefined;
         ui?: Record<string, Record<string, Record<string, string>>> | undefined;
     }>>;
+    icons: z.ZodDefault<z.ZodObject<{
+        library: z.ZodDefault<z.ZodEnum<["lucide", "fontawesome", "tabler"]>>;
+    }, "strict", z.ZodTypeAny, {
+        library: "lucide" | "fontawesome" | "tabler";
+    }, {
+        library?: "lucide" | "fontawesome" | "tabler" | undefined;
+    }>>;
     lastModified: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodObject<{
         type: z.ZodDefault<z.ZodEnum<["git", "frontmatter"]>>;
     }, "strict", z.ZodTypeAny, {
@@ -1773,13 +1888,13 @@ export declare const blumeConfigSchema: z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         enabled: boolean;
         route: string;
-        instructions?: string | undefined;
         name?: string | undefined;
+        instructions?: string | undefined;
     }, {
+        name?: string | undefined;
         enabled?: boolean | undefined;
         route?: string | undefined;
         instructions?: string | undefined;
-        name?: string | undefined;
     }>>;
     navigation: z.ZodDefault<z.ZodObject<{
         chromeVariants: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -2078,7 +2193,13 @@ export declare const blumeConfigSchema: z.ZodObject<{
         }[] | undefined;
     }>>;
     openapi: z.ZodDefault<z.ZodObject<{
+        /** Code-sample languages shown per operation (Blume renderer). */
+        codeSamples: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
+        expandSchemas: z.ZodDefault<z.ZodBoolean>;
+        /** Who renders the reference: Blume's own UI, or the embedded Scalar SPA. */
+        renderer: z.ZodDefault<z.ZodEnum<["blume", "scalar"]>>;
         /** Where the reference mounts. */
         route: z.ZodDefault<z.ZodString>;
         /** One or more specs; each renders on its own route by default. */
@@ -2100,7 +2221,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
         }>, "many">>;
         /** Shorthand for a single source: `sources: [{ spec }]`. */
         spec: z.ZodOptional<z.ZodString>;
-        /** Scalar theme name; defaults to a Blume-derived accent override. */
+        /** Scalar theme name (Scalar renderer only). */
         theme: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         enabled: boolean;
@@ -2110,6 +2231,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label?: string | undefined;
             route?: string | undefined;
         }[];
+        codeSamples: string[];
+        expandSchemas: boolean;
+        renderer: "blume" | "scalar";
         spec?: string | undefined;
         theme?: string | undefined;
     }, {
@@ -2122,6 +2246,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
             route?: string | undefined;
         }[] | undefined;
         theme?: string | undefined;
+        codeSamples?: string[] | undefined;
+        expandSchemas?: boolean | undefined;
+        renderer?: "blume" | "scalar" | undefined;
     }>>;
     redirects: z.ZodDefault<z.ZodArray<z.ZodObject<{
         from: z.ZodString;
@@ -2629,6 +2756,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
         epub: boolean;
         pdf: boolean;
     };
+    icons: {
+        library: "lucide" | "fontawesome" | "tabler";
+    };
     markdown: {
         code: {
             icons: boolean;
@@ -2648,8 +2778,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
     mcp: {
         enabled: boolean;
         route: string;
-        instructions?: string | undefined;
         name?: string | undefined;
+        instructions?: string | undefined;
     };
     navigation: {
         repo: boolean;
@@ -2707,6 +2837,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label?: string | undefined;
             route?: string | undefined;
         }[];
+        codeSamples: string[];
+        expandSchemas: boolean;
+        renderer: "blume" | "scalar";
         spec?: string | undefined;
         theme?: string | undefined;
     };
@@ -3000,6 +3133,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
         parser?: "dir" | "dot" | undefined;
         ui?: Record<string, Record<string, Record<string, string>>> | undefined;
     } | undefined;
+    icons?: {
+        library?: "lucide" | "fontawesome" | "tabler" | undefined;
+    } | undefined;
     logo?: string | {
         dark?: string | undefined;
         light?: string | undefined;
@@ -3023,10 +3159,10 @@ export declare const blumeConfigSchema: z.ZodObject<{
         math?: boolean | undefined;
     } | undefined;
     mcp?: {
+        name?: string | undefined;
         enabled?: boolean | undefined;
         route?: string | undefined;
         instructions?: string | undefined;
-        name?: string | undefined;
     } | undefined;
     navigation?: {
         sidebar?: SidebarItemConfig[] | undefined;
@@ -3086,6 +3222,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
             route?: string | undefined;
         }[] | undefined;
         theme?: string | undefined;
+        codeSamples?: string[] | undefined;
+        expandSchemas?: boolean | undefined;
+        renderer?: "blume" | "scalar" | undefined;
     } | undefined;
     redirects?: {
         from: string;

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

@@ -44,6 +44,13 @@ export interface ProjectContext {
     pagesRoot: string | null;
     /** Absolute path to the generated runtime (`<root>/.blume`). */
     outDir: string;
+    /**
+     * Absolute path to the Astro build output. `<root>/dist` normally; for a
+     * relocated runtime (isolated verify build) it lives under the runtime dir so
+     * it never empties the real `dist/`. Optional so hand-built test contexts and
+     * older callers still typecheck; `resolveProjectContext` always sets it.
+     */
+    distDir?: string;
     /** Absolute path to the user `theme.css`, if present. */
     themeFile: string | null;
     /** Absolute path to the user `components.ts`/`.tsx`, if present. */

package/docs/advanced/api-reference.mdx

@@ -1,9 +1,9 @@
 ---
 title: OpenAPI / AsyncAPI
-description: Drop in an OpenAPI or AsyncAPI spec and get an interactive reference, rendered by Scalar.
+description: Drop in an OpenAPI spec and get a native API reference — one real page per operation, in your sidebar and search.
 ---
 
-Point Blume at an OpenAPI or AsyncAPI spec and it generates an interactive API reference — schemas, authentication, examples, and a request playground — on its own route. The reference is rendered by [Scalar](https://scalar.com), not by Blume: API reference isn't core to Blume, so the whole surface is delegated to a tool that has already solved its large edge-case space.
+Point Blume at an OpenAPI spec and it generates a native API reference: one **real page per operation**, grouped by tag in a tab-scoped sidebar, with schema tables, request/response examples, and generated code samples. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc.
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -12,13 +12,13 @@ openapi: {
 }
 ```
 
-That mounts the reference at `/reference` and adds a header link to it. The `spec` is either an `http(s)` URL or a path to a local file in your project.
+That mounts the reference at `/reference` (an overview page) with each operation at `/reference/<tag>/<operation>`, and adds a header tab. The `spec` is either an `http(s)` URL or a path to a local file in your project. Blume parses it with [Scalar's OpenAPI parser](https://github.com/scalar/scalar) — Swagger 2.0 and OpenAPI 3.0 specs are upgraded to 3.1 automatically.
 
-:::note The reference mounts inside Blume's shell — your navbar stays on top — but the body is a **self-contained Scalar embed** with its own sidebar, search, and theme. By design it doesn't weave into Blume's content sidebar, site search, or `llms.txt`. :::
+:::note Operations are indexed for search by their **summary and tag**. The rendered schema tables and code samples aren't full-text indexed; search matches an operation's title and section, then links to its own page. :::
 
 ## A local spec
 
-A relative path is resolved from your project root and inlined at build time, so nothing is copied into your source tree and the page works offline:
+A relative path is resolved from your project root and read at build time. Both JSON and YAML work:
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -27,23 +27,34 @@ openapi: {
 }
 ```
 
-Both JSON and YAML specs work; Scalar auto-detects the format.
-
 ## Route
 
-`route` controls where the reference mounts (and the header link's target):
+`route` controls where the reference mounts — the overview page and the prefix for every operation route (and the header tab's target):
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
+  spec: "./openapi.yaml",
+}
+```
+
+## Code samples and schemas
+
+`codeSamples` picks which languages render per operation (built in: `curl`, `js`, `python`); `expandSchemas` starts nested schema rows expanded rather than collapsed:
 
 ```ts blume.config.ts lineNumbers
 openapi: {
   enabled: true,
-  route: "/api",
   spec: "./openapi.yaml",
+  codeSamples: ["curl", "js"],
+  expandSchemas: true,
 }
 ```
 
 ## Multiple specs
 
-Use `sources` to publish more than one spec. Each source gets its own route and header link. Give each a `label` (used for the link and to derive its route), or set an explicit `route`:
+Use `sources` to publish more than one spec. Each source gets its own overview route, operation pages, and header tab. Give each a `label` (used for the tab and to derive its route), or set an explicit `route`:
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -57,31 +68,30 @@ openapi: {
 
 `spec` is shorthand for a single-entry `sources`, so you only reach for `sources` when you have more than one.
 
-## AsyncAPI
+## The Scalar renderer
 
-Event-driven APIs use a sibling `asyncapi` block with the **same shape** — Scalar renders AsyncAPI through the same component. Only the default route differs (`/events`):
+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"`:
 
 ```ts blume.config.ts lineNumbers
-asyncapi: {
+openapi: {
   enabled: true,
-  spec: "./asyncapi.yaml",
+  renderer: "scalar",
+  spec: "./openapi.yaml",
+  theme: "purple",   // a Scalar theme name (Scalar renderer only)
 }
 ```
 
-:::warning Scalar's AsyncAPI support is still a work in progress — it renders channels, operations, messages, and a Models section, but there's **no interactive playground** for events yet. It improves upstream over time. :::
+A Scalar-rendered reference is a self-contained embed on its own route — it doesn't weave into Blume's sidebar, search, or `llms.txt`. Its "Try it" playground calls your **target API directly from the browser** (Blume doesn't proxy), so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). `theme` and the playground apply to the Scalar renderer only.
 
-## Theming
+## AsyncAPI
 
-By default Blume layers your [accent and radius](/docs/configuration/theming) onto Scalar's theme so the reference doesn't feel jarring. It's best-effort, not pixel-identical — Scalar carries its own design system. To pick a specific [Scalar theme](https://github.com/scalar/scalar) instead, set `theme`:
+Event-driven APIs use a sibling `asyncapi` block with the same shape. AsyncAPI is rendered by Scalar (the native renderer is OpenAPI-only for now); only the default route differs (`/events`):
 
 ```ts blume.config.ts lineNumbers
-openapi: {
+asyncapi: {
   enabled: true,
-  spec: "./openapi.yaml",
-  theme: "purple",
+  spec: "./asyncapi.yaml",
 }
 ```
 
-## The playground and CORS
-
-Scalar's "Try it" playground calls your **target API directly from the browser** — Blume doesn't proxy the request. For it to succeed, the API must allow cross-origin requests from the docs site (send the appropriate `Access-Control-Allow-Origin` headers). This is a property of the API being documented, not of Blume.
+:::warning Scalar's AsyncAPI support is still a work in progress — it renders channels, operations, messages, and a Models section, but there's **no interactive playground** for events yet. It improves upstream over time. :::

package/docs/advanced/bridge.mdx

@@ -0,0 +1,74 @@
+---
+title: Bridge
+description: Run blume dev directly on a Mintlify codebase — no config, no migration, no file changes. Blume detects docs.json and serves it in place.
+---
+
+Bridge mode lets you point Blume at a **Mintlify** project and run it as-is. There's no config to write and no migration to commit: drop `blume dev` into a directory that has a `docs.json` (or legacy `mint.json`) and Blume detects it, synthesizes an equivalent config in memory, and serves your existing MDX — transformed to Blume idiom on the fly, on disk untouched.
+
+```bash
+cd my-mintlify-docs
+npx blume dev
+```
+
+```txt
+ℹ Detected docs.json — running in Mintlify bridge mode (no migration).
+  Run "blume migrate mintlify" to convert permanently.
+```
+
+It's the zero-commitment way to see what your docs look like on Blume — you can keep running `mintlify dev` in one terminal and `blume dev` in another, side by side, and decide later.
+
+## When it activates
+
+Bridge mode is entirely automatic, gated on two conditions:
+
+- **No Blume config.** There's no `blume.config.{ts,js,mjs}` at the project root. An explicit Blume config always wins — the moment one exists, Blume runs a normal project and bridge mode never triggers.
+- **A Mintlify config is present.** A `docs.json` or `mint.json` sits at the root.
+
+With both true, Blume treats the Mintlify config as its source of truth for that run.
+
+:::note Bridge mode applies to `blume build` too, not just `blume dev` — you can produce a static site from an unconverted Mintlify project. Only `blume dev` prints the detection notice. :::
+
+## What happens under the hood
+
+Bridge mode is the **read-only twin** of [`blume migrate mintlify`](/docs/advanced/migrate#mintlify): the same translation, without writing anything back.
+
+- **Config is synthesized in memory.** `docs.json` is translated to a Blume config — navigation, theme, and chrome mapped across — exactly as the migrator would, but nothing is written to disk.
+- **Content is served through a Mintlify source.** The config's content block is rewired to a single [`mintlify` content source](/docs/content/sources) rooted at the project. Each MDX page is transformed to Blume markup **at scan time** as it's read, so your files never change.
+- **Variables are inlined at scan time.** `docs.json` `variables` (`{{name}}`) are substituted into content as it's scanned — Blume has no runtime substitution.
+- **Assets are served in place.** Referenced folders like `images/` are served through [`content.assets`](/docs/content/sources) rather than moved to `public/`, so nothing is relocated.
+- **Languages map to i18n.** A multi-language `docs.json` maps to Blume's [`i18n`](/docs/content/i18n), with the language switch handled by Blume's locale routing instead of a nav selector.
+
+Because it reads the same `docs.json` and runs the same transforms, what you see in bridge mode is what you'd get from a full migration.
+
+## Bridge vs. migrate
+
+<CardGroup cols={2}>
+  <Card title="Bridge mode" icon="cable">
+    **Try Blume with zero changes.** Nothing is written; your Mintlify project
+    stays exactly as it is. Ideal for evaluating Blume, running both dev servers
+    side by side, or a reversible spike.
+  </Card>
+  <Card title="Migrate" href="/docs/advanced/migrate" icon="arrow-right">
+    **Convert for good.** [`blume migrate mintlify`](/docs/advanced/migrate)
+    rewrites your pages, config, and assets in place so Blume becomes the source
+    of truth. Do this once you've decided to switch.
+  </Card>
+</CardGroup>
+
+Everything you can do in bridge mode, you can do permanently by migrating — bridge is the preview, migrate is the commit.
+
+## Limitations
+
+- **Mintlify only.** Bridge detection is Mintlify-specific. The other frameworks — Fumadocs, Nextra, Starlight — need a [one-shot migration](/docs/advanced/migrate).
+- **Same idiom gaps as the migrator.** Components without a Blume equivalent are transformed on a best-effort basis; when you hit one, [migrate](/docs/advanced/migrate) and address the warnings, or switch that page to a Blume-native equivalent such as the [OpenAPI reference](/docs/advanced/api-reference).
+- **No runtime variables.** As with a migration, `{{variable}}` values are inlined at scan time rather than substituted at runtime.
+
+<CardGroup cols={2}>
+  <Card title="Migrate" href="/docs/advanced/migrate" icon="arrow-right">
+    Convert a Mintlify, Fumadocs, Nextra, or Starlight project permanently.
+  </Card>
+  <Card title="Content sources" href="/docs/content/sources" icon="folder-tree">
+    How the `mintlify` source and `content.assets` fit into Blume's content
+    graph.
+  </Card>
+</CardGroup>

package/docs/advanced/meta.ts

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