blume 0.4.0 → 0.5.1

package/docs/advanced/bridge.mdx

@@ -0,0 +1,76 @@
+---
+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/custom-pages.mdx

@@ -260,7 +260,9 @@ import data from "blume:data";
 </RootLayout>
 ```
 
-:::note `RootLayout` is part of the generated runtime, so its props can change between releases. When you want a layout that's fully yours, [`blume eject`](/docs/configuration/customization#eject) turns `.blume/` into a standard Astro project you own outright. :::
+:::note
+`RootLayout` is part of the generated runtime, so its props can change between releases. When you want a layout that's fully yours, [`blume eject`](/docs/configuration/customization#eject) turns `.blume/` into a standard Astro project you own outright.
+:::
 
 ## 404 page
 

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",
 });

package/docs/advanced/migrate.mdx

@@ -0,0 +1,123 @@
+---
+title: Migrate
+description: Convert a Mintlify, Fumadocs, Nextra, or Starlight project to Blume in one command — config, content, navigation, and assets translated to idiomatic Blume.
+---
+
+Already have a docs site somewhere else? `blume migrate` is a one-shot codemod that converts a project from another docs framework into Blume — translating the config, rewriting each page to idiomatic Blume MDX, converting navigation files, and relocating assets, all in place. When it finishes you have a `blume.config.ts` and a tree that `blume dev` can serve.
+
+```bash
+npx blume migrate <tool>
+```
+
+The `<tool>` is the framework you're coming from:
+
+| Tool | Detects | Command |
+| --- | --- | --- |
+| [Mintlify](#mintlify) | `docs.json` / `mint.json` | `blume migrate mintlify` |
+| [Fumadocs](#fumadocs) | `content/docs` + `meta.json` | `blume migrate fumadocs` |
+| [Nextra](#nextra) | `content/` or `pages/` + `_meta` | `blume migrate nextra` |
+| [Starlight](#starlight) | `src/content/docs` + `astro.config.*` | `blume migrate starlight` |
+
+:::warning
+A migration **rewrites files in place** — pages, config, navigation, and assets. Commit (or stash) your work first so you can review the diff and roll back cleanly.
+:::
+
+## What a migration does
+
+Every migrator runs the same shape of work, tuned to the source framework:
+
+<Steps>
+  <Step title="Translate the config">
+    The framework's config — `docs.json`, a `starlight({...})` block, and so on — becomes a `blume.config.ts` at your project root, with navigation, theme, and site chrome mapped across.
+  </Step>
+  <Step title="Rewrite every page">
+    Each `.md`/`.mdx` file is rewritten to idiomatic Blume markup: framework callouts become [`:::` directives](/docs/content/syntax), components are renamed or converted, and frontmatter is mapped to Blume's [page schema](/docs/reference/frontmatter). Keys Blume doesn't recognize are dropped and reported.
+  </Step>
+  <Step title="Convert navigation">
+    Navigation files (`_meta.{js,ts,json}`, `meta.json`) become typed [`meta.ts`](/docs/content/meta) files, preserving order and titles.
+  </Step>
+  <Step title="Relocate assets and scripts">
+    Referenced asset folders are kept in place and served via [`content.assets`](/docs/content/sources); loose top-level files move under `public/`. Your `dev`/`build`/`start` npm scripts are repointed at the matching `blume` commands.
+  </Step>
+</Steps>
+
+When it's done the CLI prints how many files it touched, a list of **warnings** — anything that needs a human eye, like a component with no Blume equivalent or a dropped frontmatter key — and a reminder to review the generated config:
+
+```txt
+✔ Migrated 42 content file(s).
+⚠ Components without a Blume equivalent need manual review: <Frame>.
+⚠ Dropped unsupported page frontmatter keys: mode, "og:image".
+▶ Review blume.config.ts and run `blume dev`.
+```
+
+## Tools
+
+### Mintlify
+
+Reads `docs.json` (or legacy `mint.json`) and rewrites every page **in place** — content stays at the project root (`content.root` is `"."`).
+
+- Snippets under `/snippets` are inlined as includes; component snippets (e.g. `.jsx`) are kept and their imports rewritten to relative paths.
+- A Mintlify `openapi` spec — declared top-level or on a nav group (a path, URL, or `{ source, directory }`) — maps to Blume's [native OpenAPI reference](/docs/advanced/api-reference) (`openapi.sources`), which renders one real page per operation. A group's `directory` becomes the reference's route; endpoint refs like `GET /users` are dropped since Blume generates them from the spec.
+- `docs.json` `variables` are inlined into content — Blume has no runtime `{{variable}}` substitution.
+- Multi-language projects map to [`i18n.locales`](/docs/content/i18n); the language nav selector is dropped in favor of Blume's locale switching.
+- Icons resolve against the real bundled libraries — Font Awesome (free), Lucide, and Tabler. The migrator sets [`icons.library: fontawesome`](/docs/content/components#default-library) (Mintlify's default), so Font Awesome names (`shield-halved`, `gauge-high`, `layer-group`, …) and `iconType` styles render unchanged. Pro-only FA styles (`light`/`thin`/`duotone`/`sharp-solid`) fall back to solid.
+- Fonts map to [`theme.fonts`](/docs/configuration/theming) when the family is one of Blume's curated Google Fonts (`fonts.family`, or a `heading`/`body` split); a family outside that set is warned about, not guessed. Header links (`navbar.links`/`navbar.primary`) and footer socials (`footer.socials`) have no `blume.config` equivalent yet, so they're reported as warnings rather than dropped silently — re-add them with [`navigation.tabs`](/docs/content/navigation) or a Header/Footer [layout override](/docs/advanced/custom-pages). The contextual page menu and last-updated timestamp are already Blume defaults.
+- Field components — [`<ParamField>`, `<ResponseField>`, `<RequestField>`](/docs/content/components#api-fields) — render natively via Blume's compat components, so hand-written CLI/SDK/endpoint field docs carry over unchanged. Any remaining component with no Blume equivalent (e.g. `<Update>`) is flagged for manual review.
+
+:::tip
+Want to preview Blume against a Mintlify codebase **without** rewriting anything? Run `blume dev` with no config and Blume serves `docs.json` as-is in [Bridge mode](/docs/advanced/bridge). Migrate when you're ready to commit.
+:::
+
+### Fumadocs
+
+Reads `content/docs` + `meta.json`. Moves pages into `docs/`, preserving the `/docs` route prefix, and rewrites Fumadocs MDX to Blume markup: callouts, `<Cards>`/`<Accordions>`/`<Files>`, `<Tabs items>`, and `<include>` directives are all converted. Each `meta.json` becomes a typed `meta.ts`.
+
+### Nextra
+
+Reads `content/` or `pages/` plus `_meta` files. Moves pages into `docs/`, rewrites `<Callout>`s to [directives](/docs/content/syntax), and converts every `_meta.{js,ts,json}` into a typed `meta.ts` — navigation order and titles preserved.
+
+### Starlight
+
+Reads `src/content/docs` + your `astro.config.*`. Translates the `starlight({...})` options into `blume.config.ts` and rewrites each page **in place** (content stays under `src/content/docs`): asides become directives, components are renamed, and frontmatter is mapped across.
+
+## After migrating
+
+<Steps>
+  <Step title="Review the config">
+    Open `blume.config.ts` and check the mapped navigation, theme, and site
+    settings. The migrator is thorough but conservative — some source options
+    have no Blume equivalent and are left out.
+  </Step>
+  <Step title="Read the warnings">
+    Each warning points at something the codemod couldn't fully translate. Work
+    through them before shipping.
+  </Step>
+  <Step title="Run the dev server">
+    Serve the migrated site. Blume [validates your content](/docs/reference/cli#validating-links) as it serves it, so broken links, missing anchors, and schema errors surface immediately.
+
+    ```bash
+    blume dev
+    ```
+
+  </Step>
+  <Step title="Delete leftovers">
+    Old framework files (lockfile entries, `astro.config`, `theme.config`,
+    framework dependencies) are left untouched so nothing is lost. Remove them
+    by hand once you've confirmed the site builds.
+  </Step>
+</Steps>
+
+<CardGroup cols={2}>
+  <Card title="Bridge mode" href="/docs/advanced/bridge" icon="cable">
+    Serve a Mintlify project with `blume dev` — no migration, no file changes.
+  </Card>
+  <Card title="CLI reference" href="/docs/reference/cli" icon="terminal">
+    Every command and flag, including `blume migrate`.
+  </Card>
+  <Card title="Content sources" href="/docs/content/sources" icon="folder-tree">
+    How Blume scans content, assets, and remote sources into a site.
+  </Card>
+  <Card title="Frontmatter" href="/docs/reference/frontmatter" icon="file-text">
+    The page schema your migrated frontmatter is mapped onto.
+  </Card>
+</CardGroup>

package/docs/configuration/ai.mdx

@@ -125,7 +125,9 @@ ai: {
 
 Set `apiKeyEnv` (and, for the named providers, `baseUrl`) on any backend to point at a different env var or proxy.
 
-:::note **Inkeep** answers from the content you've indexed in the Inkeep dashboard — it runs its own retrieval — so Blume leaves it ungrounded. Every other backend is [grounded](#grounding) in this site's pages. :::
+:::note
+**Inkeep** answers from the content you've indexed in the Inkeep dashboard — it runs its own retrieval — so Blume leaves it ungrounded. Every other backend is [grounded](#grounding) in this site's pages.
+:::
 
 Keys are read with `process.env`, which covers the Node, Vercel, and Netlify adapters. On Cloudflare, expose the key through the platform's [runtime binding](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets). Enabling Ask AI also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).
 

package/docs/configuration/analytics.mdx

@@ -7,7 +7,9 @@ Blume injects analytics for you from a single `analytics` block in `blume.config
 
 Analytics loads in **production builds only**. The scripts are emitted by `blume build`, never by `blume dev`, so local traffic never reaches your dashboards and you don't need a separate "development" project.
 
-:::note Analytics is opt-in. With no `analytics` block, Blume injects nothing. :::
+:::note
+Analytics is opt-in. With no `analytics` block, Blume injects nothing.
+:::
 
 ## Vercel Web Analytics
 

package/docs/configuration/export.mdx

@@ -30,7 +30,9 @@ Any format you omit (or set to `false`) is left out of the menu. With both off
 
 Because it prints the live, fully-styled page, the result keeps crisp, selectable text, real fonts, and syntax-highlighted code. It needs no dependencies and works the same in dev, in production, and on static hosts.
 
-:::note PDF export goes through the browser's native print dialog, so the exact "Save as PDF" wording and options depend on the browser. Enable **Background graphics** in the dialog to keep code-block and callout backgrounds. :::
+:::note
+PDF export goes through the browser's native print dialog, so the exact "Save as PDF" wording and options depend on the browser. Enable **Background graphics** in the dialog to keep code-block and callout backgrounds.
+:::
 
 ## EPUB
 
@@ -42,4 +44,6 @@ To keep the file readable on a device with no stylesheet or JavaScript of its ow
 
 Both formats export the **single page** a reader is viewing — not the whole site — which matches where the action lives, beneath that page's table of contents.
 
-:::note In an EPUB there's no JavaScript to switch tabs, so tabbed content — like [package-install](/docs/content/syntax) blocks and code groups — is expanded to show every panel at once. Client-rendered embeds such as Mermaid diagrams aren't included. :::
+:::note
+In an EPUB there's no JavaScript to switch tabs, so tabbed content — like [package-install](/docs/content/syntax) blocks and code groups — is expanded to show every panel at once. Client-rendered embeds such as Mermaid diagrams aren't included.
+:::

package/docs/configuration/index.mdx

@@ -187,7 +187,7 @@ content: {
 }
 ```
 
-This is mainly useful after migrating from a tool that serves assets from the project root (like Mintlify), so references such as `![](/images/create.png)` keep resolving without relocating every file.
+This is mainly useful after [migrating](/docs/advanced/migrate) from a tool that serves assets from the project root (like Mintlify), so references such as `![](/images/create.png)` keep resolving without relocating every file. [Bridge mode](/docs/advanced/bridge) uses the same mechanism to serve a Mintlify project's assets in place, untouched.
 
 ## Last modified
 

package/docs/configuration/seo.mdx

@@ -94,7 +94,9 @@ 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. :::
+:::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.
+:::
 
 `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`.
 

package/docs/content/components.mdx

@@ -125,7 +125,7 @@ A negative or breaking state, such as a deprecation.
 
 ## Icon
 
-Render an icon from Blume's built-in set by name — the same set the `icon` props on cards, tiles, tabs, and sidebar entries draw from. Names are lowercase and kebab-cased (`rocket`, `book-open`, `chevron-right`).
+Render an icon by name — the same `icon` props power cards, steps, tiles, tabs, and sidebar entries. Names come from three bundled libraries: [Lucide](https://lucide.dev) (the default), [Font Awesome](https://fontawesome.com/icons) (its free set), and [Tabler](https://tabler.io/icons). Names are lowercase and kebab-cased (`rocket`, `gauge-high`, `book-open`).
 
 <Icon icon="rocket" size={20} />
 
@@ -133,7 +133,26 @@ Render an icon from Blume's built-in set by name — the same set the `icon` pro
 <Icon icon="rocket" size={20} />
 ```
 
-`icon` is the icon name; `size` sets the pixel size (default `16`) and `color` tints it (any CSS color; defaults to `currentColor`). Pass a raw `<svg>` string, an image URL, or a local image path in place of a name to render your own art, and add a `label` to expose it to assistive tech — without one, the icon is decorative.
+A bare name resolves against your project's [`icons.library`](#default-library) (Lucide unless you change it). Two ways to reach another library for a single icon:
+
+- **`iconType`** selects a Font Awesome style — `solid` (default), `regular`, or `brands`: `<Icon icon="github" iconType="brands" />`. Font Awesome Pro styles (`light`, `thin`, `duotone`, `sharp-solid`) aren't in the bundled free data and fall back to solid.
+- **A `library:name` prefix** overrides the default per icon: `fa6-solid:gauge-high`, `fa6-brands:github`, `lucide:rocket`, `tabler:heart`.
+
+`size` sets the pixel size (default `16`) and `color` tints it (any CSS color; defaults to `currentColor`). Pass a raw `<svg>` string, an image URL, or a local image path in place of a name to render your own art, and add a `label` to expose it to assistive tech — without one, the icon is decorative.
+
+Icons resolve at build time and inline as zero-JS SVG — nothing is fetched at runtime.
+
+### Default library
+
+Set which library bare icon names resolve against:
+
+```ts title="blume.config.ts"
+export default defineConfig({
+  icons: { library: "fontawesome" }, // "lucide" (default) | "fontawesome" | "tabler"
+});
+```
+
+A `library:name` prefix always wins over this, so you can mix libraries on any default. Migrating from Mintlify sets this to `fontawesome` for you (Mintlify's default), so your existing icon names keep working.
 
 ## File tree
 
@@ -438,6 +457,40 @@ Show or hide content by audience. `for="web"` renders only on the site; `for="ag
 <Visibility for="agents">Shown only in the generated Markdown.</Visibility>
 ```
 
+## API fields
+
+Document a single request/response field — a CLI flag, an SDK argument, an endpoint parameter — with its name, type, and description. `ParamField`, `ResponseField`, and `RequestField` are Mintlify-compatible, so a migrated site's field markup renders unchanged. Each takes a `type`, plus `required`, `deprecated`, and `default`; the description is the element's body and may hold rich MDX, including a nested [Expandable](#expandable) for sub-properties.
+
+`ParamField` names the field through the attribute that marks its location — `path`, `query`, `header`, or `body` (or a plain `name`); the location shows as a small label.
+
+<ParamField path="userId" type="string" required>
+  The unique identifier of the user.
+</ParamField>
+
+<ParamField query="limit" type="integer" default="20">
+  Maximum number of results to return per page.
+</ParamField>
+
+<ResponseField name="createdAt" type="string">
+  ISO 8601 timestamp for when the record was created.
+</ResponseField>
+
+```mdx
+<ParamField path="userId" type="string" required>
+  The unique identifier of the user.
+</ParamField>
+
+<ParamField query="limit" type="integer" default="20">
+  Maximum number of results to return per page.
+</ParamField>
+
+<ResponseField name="createdAt" type="string">
+  ISO 8601 timestamp for when the record was created.
+</ResponseField>
+```
+
+For a full spec-driven API reference — one page per operation with generated schemas — use the [OpenAPI reference](/docs/advanced/api-reference) instead.
+
 ## Type tables
 
 Tables for documenting an object's properties — its props, types, and defaults. Write the rows by hand with `TypeTable`, or generate them straight from a TypeScript interface or type alias with `AutoTypeTable`.

package/docs/content/i18n.mdx

@@ -22,7 +22,9 @@ i18n: {
 
 Each locale has a `code` (used in URLs), a `label` (shown in the language switcher), and an optional `dir` for right-to-left scripts (`"ltr"` by default).
 
-:::tip Migrating from Mintlify? `blume migrate mintlify` reads `navigation.languages[]` and writes the `i18n` block for you — the `default: true` language becomes `defaultLocale`, and translated folders already match Blume's layout. :::
+:::tip
+Migrating from Mintlify? [`blume migrate mintlify`](/docs/advanced/migrate) reads `navigation.languages[]` and writes the `i18n` block for you — the `default: true` language becomes `defaultLocale`, and translated folders already match Blume's layout.
+:::
 
 ## Organize translated content
 
@@ -98,7 +100,9 @@ i18n: {
 
 Fallback pages are excluded from the search index and aren't advertised as real translations in `hreflang`, so untranslated content doesn't compete for ranking. They still appear in that locale's sidebar, so navigation stays complete — a reader can reach every page in any language.
 
-:::tip Start by translating your most important pages — the homepage, quickstart, and top guides — and let the rest fall back. You can fill in translations over time without breaking any links. :::
+:::tip
+Start by translating your most important pages — the homepage, quickstart, and top guides — and let the rest fall back. You can fill in translations over time without breaking any links.
+:::
 
 ## The language switcher
 

package/docs/content/islands.mdx

@@ -24,7 +24,9 @@ Here's a live counter: <Counter />
 
 The filename is the component name, so it **must be a PascalCase identifier** — letters, digits, and underscores only (`Counter.tsx` → `<Counter />`). Lowercase filenames, names with dashes/dots/spaces (like `Time-Picker.tsx`), and two islands that resolve to the same name are skipped with a build warning.
 
-:::note Islands are for **interactive** UI. For a static component you reuse across pages (a styled callout, a pricing table), use an [MDX override](/docs/configuration/customization) instead — it ships no JavaScript. :::
+:::note
+Islands are for **interactive** UI. For a static component you reuse across pages (a styled callout, a pricing table), use an [MDX override](/docs/configuration/customization) instead — it ships no JavaScript.
+:::
 
 ## Registering islands in `components.ts`
 
@@ -98,7 +100,9 @@ const on = ref(false);
 
 Props you pass in MDX (`<Counter start={5} />`) are forwarded to the component, and children (`<Counter>label</Counter>`) arrive as the default slot.
 
-:::tip Islands hydrate on the client, so anything you pass as a prop must be serializable — strings, numbers, plain objects, not functions. :::
+:::tip
+Islands hydrate on the client, so anything you pass as a prop must be serializable — strings, numbers, plain objects, not functions.
+:::
 
 ## Hooks
 

package/docs/content/meta.mdx

@@ -45,7 +45,9 @@ The `pages` array lists children by slug — the folder or file name with its nu
 - **`group`** — a collapsible `<details>` disclosure. Pair it with `collapsed` to set the initial state; a group containing the current page always starts open.
 - **`page`** — a single row that, when clicked, slides the sidebar into a sub-panel showing only that group's items, with a back arrow at the top. The panel is route-aware, so landing directly on a page inside the group opens straight to it.
 
-:::tip `page` mode keeps deep sections tidy — reach for it when a group has many children and you'd rather drill into it than scroll past it. :::
+:::tip
+`page` mode keeps deep sections tidy — reach for it when a group has many children and you'd rather drill into it than scroll past it.
+:::
 
 `display` works the same on a group in an [explicit sidebar](/docs/content/navigation#explicit-sidebar) config.
 

package/docs/content/syntax.mdx

@@ -242,7 +242,9 @@ config.title;
 ```
 ````
 
-:::note Hide the language icons or wrap long lines instead of scrolling with `markdown: { code: { icons: false, wrap: true } }` in `blume.config.ts`. :::
+:::note
+Hide the language icons or wrap long lines instead of scrolling with `markdown: { code: { icons: false, wrap: true } }` in `blume.config.ts`.
+:::
 
 ## Package install
 
@@ -288,60 +290,82 @@ Callouts pull a reader's attention to context, advice, or risk. Write them as `:
 
 Neutral, supporting context the reader should keep in mind.
 
-:::note Blume regenerates `.blume/` on every run — never edit it by hand. :::
+:::note
+Blume regenerates `.blume/` on every run — never edit it by hand.
+:::
 
 ```md
-:::note Blume regenerates `.blume/` on every run — never edit it by hand. :::
+:::note
+Blume regenerates `.blume/` on every run — never edit it by hand.
+:::
 ```
 
 ### Tip
 
 A helpful shortcut or best practice that isn't required but makes life easier.
 
-:::tip Set `deployment.site` so sitemaps and Open Graph images use absolute URLs. :::
+:::tip
+Set `deployment.site` so sitemaps and Open Graph images use absolute URLs.
+:::
 
 ```md
-:::tip Set `deployment.site` so sitemaps and Open Graph images use absolute URLs. :::
+:::tip
+Set `deployment.site` so sitemaps and Open Graph images use absolute URLs.
+:::
 ```
 
 ### Success
 
 Confirm a positive outcome or that a step completed as expected.
 
-:::success Your docs built successfully and are ready to deploy. :::
+:::success
+Your docs built successfully and are ready to deploy.
+:::
 
 ```md
-:::success Your docs built successfully and are ready to deploy. :::
+:::success
+Your docs built successfully and are ready to deploy.
+:::
 ```
 
 ### Warning
 
 Flag something that needs care to avoid a mistake or surprising behavior.
 
-:::warning[Heads up] Switching to `output: "server"` requires an adapter before you can deploy. :::
+:::warning[Heads up] Switching to `output: "server"` requires an adapter before you can deploy.
+:::
 
 ```md
-:::warning[Heads up] Switching to `output: "server"` requires an adapter before you can deploy. :::
+:::warning[Heads up] Switching to `output: "server"` requires an adapter before you can deploy.
+:::
 ```
 
 ### Danger
 
 Call out a destructive or breaking action that can't easily be undone.
 
-:::danger `blume eject` is a one-way step — the generated Astro project becomes yours. :::
+:::danger
+`blume eject` is a one-way step — the generated Astro project becomes yours.
+:::
 
 ```md
-:::danger `blume eject` is a one-way step — the generated Astro project becomes yours. :::
+:::danger
+`blume eject` is a one-way step — the generated Astro project becomes yours.
+:::
 ```
 
 ### Info
 
 An informational aside; an alias-friendly default that reads as neutral.
 
-:::info The core theme ships zero client JavaScript. :::
+:::info
+The core theme ships no client framework JS.
+:::
 
 ```md
-:::info The core theme ships zero client JavaScript. :::
+:::info
+The core theme ships no client framework JS.
+:::
 ```
 
 The names `caution`, `error`, `important`, and `warn` are accepted as aliases for `warning`, `danger`, `note`, and `warning` respectively.
@@ -364,7 +388,9 @@ $$
 $$
 ```
 
-:::note Math is opt-in because `$` is common in prose and code. Enable it with `markdown: { math: true }` in `blume.config.ts`. :::
+:::note
+Math is opt-in because `$` is common in prose and code. Enable it with `markdown: { math: true }` in `blume.config.ts`.
+:::
 
 ## Smart punctuation
 

package/docs/index.mdx

@@ -27,7 +27,7 @@ Blume takes the best of both worlds. The framework is the template, so the only
 
 ### Fast by default
 
-Blume builds on Astro and Vite and renders static HTML by default — fast, cacheable, and cheap to host. The core theme is React-free and ships **zero client JavaScript**, so pages score well on Core Web Vitals out of the box. Dev startup and hot reload feel Vite-native, and you opt into server features only when you need them.
+Blume builds on Astro and Vite and renders static HTML by default — fast, cacheable, and cheap to host. The core theme ships no client framework JS so pages score well on Core Web Vitals out of the box. Dev startup and hot reload feel Vite-native, and you opt into server features only when you need them.
 
 ### AI-ready out of the box
 
@@ -49,7 +49,7 @@ Your [`blume.config.ts`](/docs/configuration) and every [`meta.ts`](/docs/conten
 - **Navigation** — inferred from files, refined with `meta.ts` or config.
 - **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD, [built in](/docs/configuration/seo).
 - **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.
-- **Migration** — `blume migrate mintlify | starlight | nextra | fumadocs`.
+- **Migration** — [`blume migrate mintlify | starlight | nextra | fumadocs`](/docs/advanced/migrate), or run `blume dev` on a Mintlify project as-is with [bridge mode](/docs/advanced/bridge).
 - **Eject** — `blume eject` produces a standalone Astro project that still uses the `blume` package.
 
 ## How it works

package/docs/reference/cli.mdx

@@ -16,7 +16,7 @@ blume <command> [options]
 | `blume build` | Build the static (or server) site. |
 | `blume preview` | Preview the last build. |
 | `blume add <item>` | Install a source component from the registry. |
-| `blume migrate <tool>` | Migrate from Mintlify, Starlight, Nextra, or Fumadocs. |
+| [`blume migrate <tool>`](/docs/advanced/migrate) | Migrate from Mintlify, Starlight, Nextra, or Fumadocs. |
 | `blume sync` | Re-fetch remote content sources and regenerate. |
 | `blume eject` | Promote the runtime into a standalone Astro app. |
 | `blume check` | Type-check the site with `astro check`. |
@@ -37,16 +37,44 @@ blume <command> [options]
 - `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — override the deployment output, adapter, and base path from `blume.config.ts`.
 - `blume build --analyze` — print the client JavaScript bundle sizes (largest first) after the build.
 - `blume build --budget-js <kb> --budget-css <kb>` — fail the build when total client JavaScript/CSS exceeds the budget, turning a performance target into a CI gate.
+- `blume build --isolated` — build into a throwaway `.blume-verify/` runtime (and its own `dist/`) instead of `.blume/`, so a running `blume dev` server and your real `dist/` are left untouched. See [Verifying while the dev server runs](#verifying-while-the-dev-server-runs).
 - `blume preview --host --port <n>` — bind the preview server.
 - `blume sync --force` — re-fetch remote sources, dropping the cached snapshot first.
 - `blume add <item> --force` — overwrite files that already exist.
 - `blume check --preview` — include drafts and unpublished CMS content when checking.
 - `blume check --strict` — fail on content diagnostics as well as type errors.
+- `blume check --isolated` — type-check in a throwaway `.blume-verify/` runtime so a running `blume dev` server is left untouched. See [Verifying while the dev server runs](#verifying-while-the-dev-server-runs).
 - `blume eject --yes` — skip the confirmation prompt.
 - `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.
 
+## Verifying while the dev server runs
+
+`blume dev` serves a live Astro server rooted at the generated `.blume/` runtime and regenerates it on every change. `blume build` and `blume check` regenerate the _same_ `.blume/`, so running either while the dev server is live would corrupt it — both refuse with an error and exit non-zero:
+
+```
+A `blume dev` server is running against .blume; building would corrupt it.
+Stop the dev server, or re-run with --isolated to build/verify against
+.blume-verify without touching it.
+```
+
+The `--isolated` flag is the escape hatch. It relocates the entire generated runtime (and, for `build`, its output `dist/`) to a sibling `.blume-verify/` directory, so the verification never writes anything the dev server — or your real `dist/` — depends on:
+
+```bash
+# In a second terminal, while `blume dev` is running:
+blume check --isolated   # fast: type-check the .astro/config changes
+blume build --isolated   # thorough: full production render into .blume-verify/dist
+```
+
+`check --isolated` is the quick path (Astro type + template diagnostics, no `dist/`); `build --isolated` is the heavier one that also catches runtime render errors. Isolated builds skip the deploy post-steps (search index, hosted-provider sync, `llms.txt`, sitemap/robots, redirects) — a verify only needs to confirm the site compiles and renders, not publish it. Blume adds `.blume-verify/` to your `.gitignore` automatically.
+
+This is especially useful when a coding agent needs to verify changes while you keep the dev server open. To make plain `blume build`/`blume check` isolate without the flag — for example in an agent's shell — set `BLUME_RUNTIME_DIR` to the runtime directory to use:
+
+```bash
+export BLUME_RUNTIME_DIR=.blume-verify
+```
+
 ## Type-checking
 
 `blume check` runs [`astro check`](https://docs.astro.build/en/reference/cli-reference/#astro-check) over your project. It regenerates the `.blume` runtime, syncs Astro's content types, then reports any TypeScript errors — in your `blume.config.ts`, in custom `.astro` pages, and in the components they import. It exits non-zero when there are errors, so it works as a `typecheck` step in CI:

package/docs/reference/frontmatter.mdx

@@ -18,6 +18,11 @@ Every page accepts the following frontmatter. All fields are optional.
       type: "string",
       description: "Publish date for blog/changelog feeds (ISO or YAML date).",
     },
+    authors: {
+      type: "string | string[] | object[]",
+      description:
+        "Post author(s) for blog/changelog content — a name, or objects with a name plus optional avatar/url and any extra fields. Preserved as-is.",
+    },
     slug: { type: "string", description: "Override the generated slug." },
     draft: {
       type: "boolean",