blume 0.4.0 → 0.5.0

package/docs/advanced/migrate.mdx

@@ -0,0 +1,119 @@
+---
+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/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/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,7 @@ i18n: {
 
 Each locale has a `code` (used in URLs), a `label` (shown in the language switcher), and an optional `dir` for right-to-left scripts (`"ltr"` by default).
 
-:::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
 

package/docs/content/syntax.mdx

@@ -338,10 +338,10 @@ Call out a destructive or breaking action that can't easily be undone.
 
 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.

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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -50,6 +50,7 @@
     "./components": "./src/components/index.ts",
     "./components/*": "./src/components/*",
     "./core/*": "./src/core/*",
+    "./openapi/*": "./src/openapi/*",
     "./sources/*": "./src/core/sources/*",
     "./theme/*": "./src/theme/*",
     "./package.json": "./package.json"
@@ -69,10 +70,19 @@
     "@astrojs/node": "^11.0.0",
     "@astrojs/react": "^6.0.0",
     "@astrojs/vercel": "^11.0.0",
+    "@iconify-json/fa6-brands": "^1.2.6",
+    "@iconify-json/fa6-regular": "^1.2.4",
+    "@iconify-json/fa6-solid": "^1.2.4",
+    "@iconify-json/lucide": "^1.2.115",
+    "@iconify-json/tabler": "^1.2.35",
+    "@iconify/types": "^2.0.0",
+    "@iconify/utils": "^3.1.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@orama/orama": "^3.1.18",
     "@pierre/diffs": "^1.2.11",
     "@scalar/astro": "^0.4.5",
+    "@scalar/openapi-parser": "^0.28.8",
+    "@scalar/openapi-types": "^0.9.1",
     "@shikijs/transformers": "^4.2.0",
     "@shikijs/twoslash": "^4.2.0",
     "@tailwindcss/typography": "^0.5.20",

package/src/astro/generate.ts

@@ -36,11 +36,9 @@ import type { ResolvedConfig } from "../core/schema.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Navigation } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
-import {
-  buildReferenceFiles,
-  hasReferences,
-  referenceTabs,
-} from "../openapi/scalar.ts";
+import { hasScalarReferences, referenceTabs } from "../openapi/references.ts";
+import { buildReferenceFiles } from "../openapi/scalar.ts";
+import { isOpenApiSource } from "../openapi/source.ts";
 import { registry } from "../registry/registry.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
 import { searchProviderMeta, servesStaticIndex } from "../search/providers.ts";
@@ -582,8 +580,9 @@ export const buildRuntimeData = (project: BlumeProject): string => {
 
   const { i18n } = config;
 
-  // API reference routes (Scalar) surface as header tabs alongside the
-  // content-derived ones, so the reference stays discoverable in every locale.
+  // API reference routes surface as header tabs alongside the content-derived
+  // ones (Blume-rendered references also own a tab-scoped sidebar of operations),
+  // so the reference stays discoverable in every locale.
   const withReferenceTabs = (nav: Navigation): Navigation => ({
     ...nav,
     repoUrl: config.navigation.repo && repoUrl ? repoUrl : null,
@@ -650,6 +649,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
             })),
           }
         : null,
+      icons: config.icons,
       imageZoom: config.markdown.imageZoom,
       logo: resolveLogo(project),
       mcp: config.mcp.enabled
@@ -912,6 +912,7 @@ export const generateRuntime = async (
   const themePath = join(srcDir, "generated", "app.css");
   const searchClientPath = join(srcDir, "generated", "search-client.ts");
   const examplesPath = join(srcDir, "generated", "examples.ts");
+  const openapiPath = join(srcDir, "generated", "openapi.json");
 
   // Record every file this pass writes so orphans (from a now-disabled feature)
   // can be pruned afterwards. `write` wraps the atomic writer and tracks paths.
@@ -987,6 +988,7 @@ export const generateRuntime = async (
         needsReact,
         needsSvelte,
         needsVue,
+        openapiPath,
         pages,
         searchClientPath,
         themePath,
@@ -1235,7 +1237,7 @@ export const generateRuntime = async (
   // React ships with Blume; Vue/Svelte islands need their Astro integration
   // installed by the project. Warn early rather than let Vite fail to resolve it.
   warnings.push(...islandFrameworkWarnings(frameworks, context.root));
-  if (hasReferences(config)) {
+  if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,
       contentRoutes: new Set(project.graph.pages.map((page) => page.route)),
@@ -1254,6 +1256,14 @@ export const generateRuntime = async (
     join(srcDir, "generated", "data.json"),
     buildRuntimeData(project)
   );
+  // The parsed OpenAPI specs behind the `blume:openapi` alias. Always written
+  // (even as `{}`) so the alias resolves whether or not a reference is enabled;
+  // the source parsed the specs during the scan, so this is just serialization.
+  const openApiSource = project.sources.find(isOpenApiSource);
+  await write(
+    openapiPath,
+    `${JSON.stringify(openApiSource ? openApiSource.openApiData() : {})}\n`
+  );
   await write(
     join(out, "blume.manifest.json"),
     `${JSON.stringify(project.manifest, null, 2)}\n`

package/src/astro/templates.ts

@@ -7,6 +7,7 @@ import type { AskBackend } from "../ai/ask.ts";
 import { resolveAssetMounts } from "../core/assets.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import type { ProjectContext } from "../core/types.ts";
+import { hasScalarReferences } from "../openapi/references.ts";
 import { searchProviderMeta } from "../search/providers.ts";
 import { buildFontEntries } from "../theme/fonts.ts";
 import type { ExampleSpec } from "./examples.ts";
@@ -99,9 +100,10 @@ export const runtimeDependencies = (options: {
   if (needsSvelte) {
     deps.push("@astrojs/svelte");
   }
-  // The Scalar integration is only declared when an API reference is configured,
-  // so projects that don't use it never pull it into the runtime.
-  if (config.openapi.enabled || config.asyncapi.enabled) {
+  // The Scalar integration is only declared for a Scalar-rendered reference
+  // (the `renderer: "scalar"` fallback, or AsyncAPI). Blume-rendered OpenAPI
+  // parses at generate time and needs no runtime Scalar dependency.
+  if (hasScalarReferences(config)) {
     deps.push("@scalar/astro");
   }
   // Only the configured search provider's SDK is declared, so a project pulls in
@@ -178,6 +180,10 @@ const renderUserAliases = (
     )
     .join("");
 
+/** Astro's build output dir: the runtime's own `distDir`, else `<root>/dist`. */
+const astroOutDir = (context: ProjectContext): string =>
+  context.distDir ?? `${context.root}/dist`;
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -190,6 +196,7 @@ export const astroConfigTemplate = (options: {
   examplesPath: string;
   themePath: string;
   searchClientPath: string;
+  openapiPath: string;
   /** Project tsconfig path aliases (`find` -> absolute dir), e.g. `@` -> src. */
   aliases?: Record<string, string>;
 }): string => {
@@ -199,6 +206,7 @@ export const astroConfigTemplate = (options: {
     examplesPath,
     needsSvelte,
     needsVue,
+    openapiPath,
     searchClientPath,
   } = options;
   const { deployment } = config;
@@ -322,7 +330,7 @@ ${twoslashImport}${reactImport}${vueImport}${svelteImport}${blumeImport}${adapte
 export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
-  outDir: ${JSON.stringify(`${context.root}/dist`)},
+  outDir: ${JSON.stringify(astroOutDir(context))},
   publicDir: ${JSON.stringify(`${context.root}/public`)},
   output: ${JSON.stringify(deployment.output)},${adapterOption}${siteOption}${baseOption}${redirectsOption}${i18nOption}${fontsOption}
   integrations: [${integrations.join(", ")}],
@@ -357,6 +365,7 @@ export default defineConfig({
       alias: {
         "blume:data": ${JSON.stringify(dataPath)},
         "blume:examples": ${JSON.stringify(examplesPath)},
+        "blume:openapi": ${JSON.stringify(openapiPath)},
         "blume:search-client": ${JSON.stringify(searchClientPath)},
         "blume:theme": ${JSON.stringify(themePath)},${userAliasLines}
       },
@@ -913,7 +922,10 @@ import FileTree from "blume/components/content/FileTree.astro";
 import Frame from "blume/components/content/Frame.astro";
 import GithubInfo from "blume/components/content/GithubInfo.astro";
 import Panel from "blume/components/content/Panel.astro";
+import ParamField from "blume/components/content/ParamField.astro";
 import Prompt from "blume/components/content/Prompt.astro";
+import RequestField from "blume/components/content/RequestField.astro";
+import ResponseField from "blume/components/content/ResponseField.astro";
 import Step from "blume/components/content/Step.astro";
 import Steps from "blume/components/content/Steps.astro";
 import Tab from "blume/components/content/Tab.astro";
@@ -927,6 +939,8 @@ import TypeTable from "blume/components/content/TypeTable.astro";
 import Visibility from "blume/components/content/Visibility.astro";
 import YouTube from "blume/components/content/YouTube.astro";
 import Icon from "blume/components/Icon.astro";
+import ApiOverview from "blume/components/openapi/ApiOverview.astro";
+import Operation from "blume/components/openapi/Operation.astro";
 ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../generated/components.ts";
 import { islandComponents } from "../generated/islands.ts";
 import data from "../generated/data.json";
@@ -943,6 +957,7 @@ export const prerender = true;
 const components = {
   Accordion,
   AccordionItem,
+  ApiOverview,
   AutoTypeTable,
   Badge,
   Callout,
@@ -960,8 +975,12 @@ const components = {
   Frame,
   GithubInfo,
   Icon,
+  Operation,
   Panel,
+  ParamField,
   Prompt,
+  RequestField,
+  ResponseField,
   Step,
   Steps,
   Tab,
@@ -1448,6 +1467,11 @@ declare module "blume:data" {
   export default data;
 }
 
+declare module "blume:openapi" {
+  const specs: import("blume/openapi/model.ts").OpenApiData;
+  export default specs;
+}
+
 declare module "blume:search-client" {
   export const createSearch: () =>
     | import("blume/components/layout/search/types.ts").SearchFn