blume 1.7.3 → 2.0.0

package/docs/advanced/api-reference.mdx

@@ -1,240 +0,0 @@
----
-title: OpenAPI / AsyncAPI
-description: Drop in an OpenAPI or AsyncAPI spec and get a native API reference — one real page per operation, in your sidebar and search.
----
-
-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, generated code samples, and an interactive [Try it](#try-it-playground) panel. 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. The config below points Blume at the public Petstore spec as an example.
-
-```ts blume.config.ts lineNumbers
-openapi: {
-  enabled: true,
-  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
-}
-```
-
-That mounts the reference at `/reference` (an overview page) with each operation at `/reference/<tag>/<operation>`. 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. Documenting a GraphQL API instead? See the [GraphQL reference](/docs/advanced/graphql).
-
-The reference doesn't add a header tab on its own. To surface it, point a [navigation tab](/docs/content/navigation#tabs) at its route — this also scopes the operations sidebar for the native renderer:
-
-```ts blume.config.ts
-navigation: {
-  tabs: [{ label: "API", path: "/reference" }],
-}
-```
-
-:::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 read at build time. Both JSON and YAML work:
-
-```ts blume.config.ts lineNumbers
-openapi: {
-  enabled: true,
-  spec: "./openapi.yaml",
-}
-```
-
-## Route
-
-`route` controls where the reference mounts — the overview page and the prefix for every operation route (and the route you point a navigation tab at):
-
-```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,
-  spec: "./openapi.yaml",
-  codeSamples: ["curl", "js"],
-  expandSchemas: true,
-}
-```
-
-## Try it playground
-
-Operation pages rendered natively ship an interactive **Try it** panel by default. Blume generates the form from the operation itself: an input per path, query, and header parameter, a body editor built from the request-body schema, everything prefilled from the spec's examples. A server picker lists the spec's `servers`, with a free-text field for any other base URL, and auth inputs match the operation's [resolved security](#authorization) — bearer token, API key, and basic credentials, with OAuth2 as a token paste field (bring an access token; Blume doesn't run the flow).
-
-The panel and the code samples stay in lockstep: values typed into the form update the generated samples live, so a copied curl command always matches exactly what **Send** would do. And it stays out of the way — the panel is server-rendered collapsed, and its JavaScript loads only when a reader first opens it. Readers who never touch it download none of it.
-
-`playground: false` is the entire off switch:
-
-```ts blume.config.ts lineNumbers
-openapi: {
-  enabled: true,
-  spec: "./openapi.yaml",
-  playground: false,
-}
-```
-
-### Credentials
-
-Credentials typed into the auth inputs stay in memory and vanish on reload. Checking **Remember on this device** persists them in `localStorage`, scoped to the docs origin — they're never sent anywhere except the API being called. Code samples keep showing placeholders (`YOUR_TOKEN` and friends) whatever's typed, unless the reader toggles **Include my values in samples**.
-
-### CORS and the proxy
-
-As with the [Scalar renderer](#the-scalar-renderer), requests go **directly from the browser** to the target API, so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). For APIs that can't, set `playground.proxy`: a URL routes requests through a proxy you host, and `true` enables the built-in `/_api-proxy` route — which needs a server build, so it requires [`deployment.output: "server"`](/docs/deployment#server-rendering):
-
-```ts blume.config.ts lineNumbers
-openapi: {
-  enabled: true,
-  spec: "./openapi.yaml",
-  playground: {
-    proxy: true,   // or a URL of your own
-  },
-}
-```
-
-The built-in proxy only forwards requests to the origins your specs declare in `servers` — including across redirects — so a public docs deployment can't be aimed at other hosts on its network. A **Custom base URL** typed into the panel isn't a documented server: with the proxy enabled, requests to it are refused with a 403.
-
-## Multiple specs
-
-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: {
-  enabled: true,
-  sources: [
-    { label: "Public API", spec: "./public.json" },   // → /reference/public-api
-    { label: "Admin API", route: "/admin", spec: "./admin.json" },
-  ],
-}
-```
-
-`spec` is shorthand for a single-entry `sources`, so you only reach for `sources` when you have more than one.
-
-### Per-source indexing
-
-Generated pages participate in search, `llms.txt`, and crawler indexing by default. A secondary or overlapping spec can opt out of any surface without hiding its pages or removing it from navigation:
-
-```ts blume.config.ts lineNumbers
-openapi: {
-  enabled: true,
-  sources: [
-    { label: "Public API", route: "/api", spec: "./public.json" },
-    {
-      label: "Platform API",
-      route: "/platform",
-      spec: "./platform.json",
-      includeInSearch: false,
-      includeInLlms: false,
-      noindex: true,
-    },
-  ],
-}
-```
-
-- `includeInSearch: false` keeps the source's overview and operations out of site search.
-- `includeInLlms: false` keeps them out of both `llms.txt` files.
-- `noindex: true` adds crawler noindex metadata and removes the pages from the sitemap.
-
-Each operation page's meta description is the operation's own `description` (or `summary`), followed by a generated sentence naming the endpoint — "Reference for the `GET /pets` endpoint in the Petstore API." — so a spec of terse one-line summaries still ships a distinct, snippet-length description per page. That sentence is English. On a site whose spec prose is written in another language, set `seoDescriptionSuffix: false` on the source to drop it and describe each page with the authored prose alone; an operation with neither a `description` nor a `summary` falls back to its title (`GET /pets`), so no page ships an empty description:
-
-```ts blume.config.ts lineNumbers
-openapi: {
-  enabled: true,
-  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
-}
-```
-
-With the [Scalar renderer](#the-scalar-renderer), only `noindex` applies — a Scalar-rendered reference already sits outside Blume's search and `llms.txt`, so the two `include*` settings have nothing to act on there.
-
-## Authorization
-
-Operations that declare [security requirements](https://spec.openapis.org/oas/v3.1.0#security-requirement-object) render an **Authorization** section above their parameters, and the generated code samples send a placeholder credential (`Authorization: Bearer YOUR_TOKEN`, an API-key header, or a query key — whatever the scheme calls for). There's nothing to configure: Blume reads `security` from the spec, so the reference always matches what the API actually enforces.
-
-The OpenAPI semantics carry over as written:
-
-- An operation's own `security` overrides the document's root default; `security: []` marks it **public** and renders no Authorization section.
-- Multiple requirement entries are alternatives — rendered as "or" groups; every scheme inside one entry is required together. The first alternative feeds the code samples.
-- An empty `{}` entry means auth is **optional** for that operation, and the section says so.
-- OAuth2 scopes are listed per scheme; scheme `description`s from `components.securitySchemes` render inline.
-
-## The Scalar renderer
-
-The native renderer is the default — operation pages, search integration, and the [Try it playground](#try-it-playground) above are all its work. If you'd rather embed [Scalar](https://scalar.com)'s self-contained API reference UI — its own sidebar, search, theme, and request client on a single route — set `renderer: "scalar"`:
-
-```ts blume.config.ts lineNumbers
-openapi: {
-  enabled: true,
-  renderer: "scalar",
-  spec: "./openapi.yaml",
-  theme: "purple",   // a Scalar theme name (Scalar renderer only)
-}
-```
-
-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`, and Blume's [`playground`](#try-it-playground) config doesn't apply to it. It does follow Blume's light/dark toggle: the embed is pinned to the page's theme when it mounts and switches with it, so Scalar's own theme switch is hidden (set `scalar.forceDarkModeState` or `scalar.darkMode` to hand color mode back to Scalar). Scalar brings its own request client, which calls your **target API directly from the browser** (the `playground.proxy` route isn't available here), so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). `theme` applies to the Scalar renderer only.
-
-### Passing Scalar options
-
-`theme` is a shorthand for the one option most people reach for, but Scalar supports many more. A `scalar` object forwards any [Scalar configuration](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) straight to the embedded reference — Blume doesn't gate the keys, so anything Scalar accepts flows through:
-
-```ts blume.config.ts lineNumbers
-openapi: {
-  enabled: true,
-  renderer: "scalar",
-  spec: "./openapi.yaml",
-  scalar: {
-    localization: { locale: "es" },   // translate Scalar's own UI
-    agent: { disabled: true },         // disable the Scalar Agent
-    hideTestRequestButton: true,
-    orderSchemaPropertiesBy: "preserve",
-  },
-}
-```
-
-Blume's own [`i18n`](/docs/content/i18n) translates the docs chrome, but Scalar has a separate localization system — set `scalar.localization.locale` to translate the embedded reference too. Options in the `scalar` object win over Blume's derived config, so anything set here (including `theme`, `customCss`, or the spec `content`/`url`) overrides Blume's defaults. The same `scalar` block works on the `asyncapi` reference.
-
-## AsyncAPI
-
-Event-driven APIs use a sibling `asyncapi` block with the same shape — and the same native renderer. Each `send`/`receive` operation becomes a real page with message payload and header schema tables, channel parameters, protocol bindings, an Authorization section derived from the spec's `securitySchemes` (server-level and operation-level, alternatives as "or" groups), and a [Try it](#try-it-for-events) message composer. Only the default route differs (`/events`):
-
-```ts blume.config.ts lineNumbers
-asyncapi: {
-  enabled: true,
-  spec: "./asyncapi.yaml",
-}
-```
-
-AsyncAPI **2.x specs are normalized to 3.x automatically** with the official AsyncAPI converter, so `publish`/`subscribe` channels map onto `send`/`receive` operation pages with stable URLs — later upgrading the spec file itself through the converter moves nothing. Operations group by tag; untagged operations group under their channel address.
-
-Code samples are **protocol-aware**, keyed off the operation's binding (or its servers' protocol): `wscat` and a browser `WebSocket` snippet for WebSockets, `kcat` for Kafka, `mosquitto_pub`/`mosquitto_sub` for MQTT. `codeSamples` filters that set, the same way it picks languages on the `openapi` block; a protocol without a supported tool renders the message payload example alone rather than a fabricated client.
-
-Everything documented above carries over, [`playground`](#try-it-for-events) included: `route`, `sources` with `label`/`route`, `expandSchemas`, the [per-source indexing](#per-source-indexing) flags (`seoDescriptionSuffix` too — the generated sentence names the channel and action instead of an endpoint), and search indexing by operation summary and tag.
-
-Setting `renderer: "scalar"` opts back into the embedded Scalar SPA, where — as with OpenAPI — only `noindex` applies. Scalar has no AsyncAPI playground of its own; its embed auto-detects the document type and renders channels, operations, messages, and a Models section, so that swap trades the composer away.
-
-### Try it for events
-
-Operation pages rendered natively ship a **Try it** panel here too, on the same terms as the [OpenAPI panel](#try-it-playground): server-rendered collapsed, with its JavaScript loaded only when a reader first opens it.
-
-Whatever the protocol, the panel opens with a payload editor prefilled from the message's `examples` — or, when the message declares none, from a value sampled out of the payload schema — validated against the message payload schema as you type. Under it sit an input per channel parameter and a server picker fed by the channel's `servers`, with a free-text field for any other URL. The protocol-aware code samples stay in lockstep with the form exactly as curl, js, and python do on an HTTP operation: the channel address template is filled in with the parameter values you type, so a copied `wscat`, `WebSocket`, `kcat`, or `mosquitto_pub` snippet matches what the form says.
-
-Live connect is WebSocket-only. On a `ws` or `wss` binding the panel connects to the resolved channel URL, shows the connection state, and logs every frame with a timestamp. AsyncAPI 3 states an action from the API's side, and the panel follows it: a `receive` operation is one the API receives from you, so it gets a **Send** button that publishes the composed payload; a `send` operation only streams messages at you, so it connects and logs. There's no reconnect logic — once a socket closes, it stays closed until you connect again. Kafka, MQTT, AMQP, and every other protocol get the composer and the copyable CLI samples, and the panel says as much on the page: Blume doesn't fake broker connectivity from a browser tab.
-
-`asyncapi.playground` mirrors `openapi.playground` — on by default with the native renderer, and `false` is the entire off switch:
-
-```ts blume.config.ts lineNumbers
-asyncapi: {
-  enabled: true,
-  spec: "./asyncapi.yaml",
-  playground: false,
-}
-```
-
-:::note
-`playground.proxy` doesn't apply to event operations. It forwards HTTP requests, and a WebSocket connect goes straight from the browser to the server named in the URL, so there's nothing for a proxy to sit in front of.
-:::
-
-The event composer collects no broker credentials. Each operation page's **Authorization** section documents what the broker expects, and a WebSocket connect carries only what's already in the URL. Nothing is persisted for event operations.

package/docs/reference/cli.mdx

@@ -1,197 +0,0 @@
----
-title: CLI
-description: Every Blume command and flag explained in one place, along with the options each one accepts.
----
-
-```bash
-blume <command> [options]
-```
-
-## Commands
-
-| Command | Description |
-| --- | --- |
-| `blume init [dir]` | Scaffold a project (interactive by default). |
-| `blume dev` | Start the dev server with hot reload. |
-| `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 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`. |
-| `blume doctor` | Diagnose config and content problems. |
-| `blume validate` | Validate links across your content. |
-| `blume audit` | Audit the built site for SEO and health issues. |
-| `blume eval` | Test the docs: an agent answers your questions using only the documentation. |
-| `blume translate` | Translate docs into the configured locales with a local agent CLI. |
-| `blume version [id]` | Freeze the current docs as an [archived version](/docs/content/versioning) (no id lists configured versions). |
-
-## Common flags
-
-- `blume init` — in a terminal, walks you through a few questions (where to create the project, site name, template, content sources); each flag below pre-answers its question.
-- `blume init --yes` — skip the prompts and scaffold with defaults (also the behavior in CI or when stdin isn't a terminal).
-- `blume init --content-dir <dir>` — set the content folder (default `docs`).
-- `blume init --template docs|api|sdk|changelog` — scaffold from a starter (API reference, SDK, or changelog instead of the plain docs seed).
-- `blume init --package-manager npm|pnpm|yarn|bun` — tailor the printed next-steps to your package manager.
-- `blume init --eject` — scaffold, then eject to a standalone Astro project (falls back to guiding you through `blume eject` when dependencies aren't installed yet).
-- `blume dev --host --port <n> --open`
-- `blume dev --content-dir <dir>` — scan a different content folder without editing `blume.config.ts`.
-- `blume dev --debug` — verbose Astro/Vite logging for troubleshooting.
-- `blume dev --preview` / `blume build --preview` — include drafts and unpublished CMS content.
-- `blume build --no-strict` — build despite diagnostic errors. By default `blume build` fails (exit 1) on any error diagnostic, because pages that fail frontmatter validation are dropped from the output; with `--no-strict` the build succeeds and reports how many pages are missing. `blume dev --strict` opts dev into the same fail-fast behavior.
-- `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.
-- `blume audit --fail-on error|warning|info` — the CI gate; defaults to `error`. `--strict` is an alias for `--fail-on warning`.
-- `blume audit --url <origin>` — also probe a live deployment for status codes, response headers, and redirect chains.
-- `blume audit --external` — probe outbound links over the network.
-- `blume audit --only <check|category>` / `--skip <check|category>` — narrow the report while you work through it (comma-separated).
-- `blume audit --list-checks` — print every check the audit can report.
-- `blume audit --verbose` — list every affected page with each finding's full detail, such as which link target is broken.
-- `blume audit --json` — emit the report as JSON on stdout.
-- `blume audit --claude` / `--codex` — hand the findings to Claude Code or Codex to fix interactively.
-- `blume eval` — run the questions in `evals.yaml` through an agent that reads only your docs; see [Evals](/docs/reference/eval).
-- `blume eval init` — have the agent draft a starter `evals.yaml` from your docs.
-- `blume eval --agent claude|codex --threshold <0..1> --timeout <seconds> --json --fix --verbose` — see [Evals](/docs/reference/eval) for each flag.
-- `blume translate --claude` / `--codex` — translate missing and outdated pages into your configured locales; see [Translate](/docs/reference/translate).
-- `blume translate --check` — report translation drift and exit non-zero (the CI gate), without running an agent.
-- `blume translate --locale <codes> --concurrency <n> --force --timeout <seconds> --json` — see [Translate](/docs/reference/translate) for each flag.
-
-## 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 at http://localhost:3000; building would
-corrupt its .blume runtime. Reuse that server, stop it first, 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. `--analyze` and the `--budget-js`/`--budget-css` gates still run, measured against the isolated output. 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:
-
-```json title="package.json"
-{
-  "scripts": {
-    "typecheck": "blume check"
-  }
-}
-```
-
-Add a `tsconfig.json` extending Astro's config to your project root so authored pages resolve `blume/*` imports and virtual modules like `blume:data`:
-
-```json title="tsconfig.json"
-{
-  "extends": "astro/tsconfigs/strict",
-  "include": [".blume/.astro/types.d.ts", "**/*"]
-}
-```
-
-Without a project `tsconfig.json`, only the generated runtime is checked.
-
-## Validating links
-
-`blume validate` checks every link discovered in your content:
-
-- **Internal page links** (`/guides/intro`, `./sibling`) must resolve to a real page — broken ones are reported as errors.
-- **Anchor links** (`#section`, `/guides/intro#setup`) must match an anchor on the target page — a heading's id (generated or [pinned](/docs/content/syntax#custom-anchors)) or a raw HTML element's `id` attribute — with misses reported as warnings. Ids inside code blocks, inline code, HTML comments, and `<Prompt>` blocks don't count.
-
-- **Asset links** are checked where the file lives: an absolute path (`/logo.png`) against the `public/` directory, a relative image embed (`![](./diagram.png)`) against the page's own folder. A plain link to a relative path still resolves as a site route — only image embeds go through the image pipeline.
-- **External links** are only checked with `--external` (off by default since it requires the network); dead links (404/410/unreachable) are errors, while rate-limited or transient responses (403/429/5xx/timeout) are warnings.
-
-## Auditing the built site
-
-`blume validate` reads your _content_; `blume audit` reads the _built site_. It crawls the HTML in `dist/` after a build and reports SEO and site-health issues — titles, meta descriptions, canonicals, Open Graph and X cards, headings, hreflang, images, the sitemap, `robots.txt`, and structured data.
-
-Because Blume built the site, every finding names the source file **and the front matter line** that fixes it, not just the URL a crawler would see:
-
-```
-⚠ Meta description too long or too short   5 pages
-    /docs/configuration/export    content/docs/configuration/export.mdx:3
-    fix: Rewrite `description` in the frontmatter to fit the length range.
-```
-
-Run it after a build:
-
-```bash
-blume build
-blume audit
-```
-
-Findings are grouped by check rather than listed per page, so the report reads as a to-do list. Use `--verbose` to expand every affected page with its full detail, and `--only`/`--skip` to work through one category at a time. `blume audit --list-checks` prints the full catalog.
-
-### Failing CI
-
-The exit code is the contract. By default `blume audit` fails only on errors — things that are definitely broken, like a link to a page that was never built, a redirect loop, or an invalid sitemap. Advisory findings (a short description, a duplicate title) are warnings and do not fail the build:
-
-```bash
-blume audit                      # fails on errors
-blume audit --fail-on warning    # also fails on warnings
-```
-
-### Checking a live deployment
-
-Some things only the real server can tell you: whether a page that exists in `dist/` actually 404s behind a bad rewrite, whether responses are compressed, and whether an `X-Robots-Tag` header is quietly deindexing a page whose HTML looks perfectly fine. Point the audit at a deployment to add those checks:
-
-```bash
-blume audit --url https://docs.example.com
-blume audit --url https://docs.example.com --external   # also probe outbound links
-```
-
-Outbound links are graded rather than flatly failed: a 404 is a broken link you can fix, while a 403 or 5xx is usually rate limiting or someone else's outage and is reported as a warning.
-
-### Fixing the findings with an agent
-
-If you use [Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex/cli), the audit can hand its findings straight to it:
-
-```bash
-blume audit --claude   # or --codex
-```
-
-This writes the complete JSON report — every affected page, not the terminal's three-page preview — to a file and opens the agent interactively with a prompt that walks it through the findings: edit the source file each finding names, apply its suggested fix, then run `blume build` and `blume audit` again until the report is clean. The session is interactive by design: you review the edits through the agent's own permission flow, and the agent is told never to fix a finding by deleting content.
-
-`--only` and `--skip` narrow the handoff the same way they narrow the report, so you can send one category at a time.
-
-### What it does and doesn't check
-
-The check set is deliberately narrower than a general-purpose SEO crawler's. Much of what such a crawler reports cannot happen to a Blume site — it never emits `rel=nofollow`, and Vite's content-hashed bundles are never missing or redirecting — and reporting those as permanent zeroes would just teach you to ignore the report.
-
-Two limits worth stating plainly:
-
-- **Structured data** is validated for well-formedness (valid JSON, a `@context`, a `@type` on every node). Blume does not validate against the full schema.org vocabulary or Google's rich-results rules.
-- **Core Web Vitals** are not checked. They need a real browser, and a flag that quietly measured nothing would be worse than not having one — so `blume audit` reports the layout-shift causes it _can_ see offline (images with no `width`/`height`, oversized assets) and leaves the rest alone for now.
-
-Anything the audit did not run is reported as skipped rather than silently passing:
-
-```
-⊘ network      skipped — pass --url <origin> (11 checks)
-⊘ external     skipped — pass --external (2 checks)
-```

package/skills/blume-migrate/assets/oxfmt@0.55.0.patch

@@ -1,20 +0,0 @@
-diff --git a/dist/markdown-Bowe09rB.js b/dist/markdown-Bowe09rB.js
-index 0fe63ff712e07c9c2188711fa0940f7a7d8f7d74..44435d91a2f5a6711512981c9bcaddedc1760be4 100644
---- a/dist/markdown-Bowe09rB.js
-+++ b/dist/markdown-Bowe09rB.js
-@@ -1141,7 +1141,14 @@ function Yf(e, r, t) {
- 		case "sentence": return Yi(e, t);
- 		case "word": return Li(e);
- 		case "whitespace": {
--			let { next: i } = e, u = i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/u.test(i.value) ? "never" : r.proseWrap;
-+			let { next: i, previous: oxfmtFencePrev } = e;
-+			// Preserve line breaks that sit directly against a `:::` container
-+			// directive fence, so `proseWrap: "never"` keeps the opening/closing
-+			// fence on their own lines instead of joining them into the prose (which
-+			// breaks the directive). Ordinary prose still wraps per proseWrap.
-+			// See prettier/prettier#19040.
-+			let oxfmtIsFence = (w) => w != null && typeof w.value === "string" && w.value.startsWith(":::");
-+			let u = oxfmtIsFence(oxfmtFencePrev) || oxfmtIsFence(i) ? "preserve" : i && /^>|^(?:[*+-]|#{1,6}|\d+[).])$/u.test(i.value) ? "never" : r.proseWrap;
- 			return qt(e, n.value, u);
- 		}
- 		case "emphasis": {

package/src/components/content/changelog-element.ts

@@ -1,69 +0,0 @@
-/**
- * Client behavior for the `<blume-changelog>` custom element wrapping the
- * generated changelog timeline when its releases are semver-versioned. The
- * newest major line stays visible; every older major is collapsed into a group
- * revealed one major at a time by the "Show N.x releases" button at the bottom.
- *
- * Pure progressive enhancement: the server renders every release in document
- * order, and this element hides the older-major groups on connect — so a no-JS
- * visitor (or a crawler) still sees the complete history, and the button does
- * nothing until the script upgrades it.
- *
- * Imported for its side effect (registers the element) from the changelog page.
- */
-
-class BlumeChangelog extends HTMLElement {
-  connectedCallback() {
-    const groups = [
-      ...this.querySelectorAll<HTMLElement>("[data-changelog-major]"),
-    ];
-    const button = this.querySelector<HTMLButtonElement>(
-      "[data-changelog-more]"
-    );
-    if (groups.length === 0 || !button) {
-      return;
-    }
-
-    // Localized button template from the generated page markup (the
-    // data-attribute channel); `{version}` is replaced with the major line.
-    const template = this.dataset.i18nMore || "Show {version} releases";
-
-    for (const group of groups) {
-      group.hidden = true;
-      // Focusable only programmatically, so revealing a group can move focus to
-      // it for keyboard and screen-reader users without adding a tab stop.
-      group.tabIndex = -1;
-    }
-
-    let revealed = 0;
-    const sync = () => {
-      const next = groups[revealed];
-      if (next) {
-        button.textContent = template.replace(
-          "{version}",
-          next.dataset.changelogLabel ?? ""
-        );
-        button.hidden = false;
-      } else {
-        button.hidden = true;
-      }
-    };
-
-    button.addEventListener("click", () => {
-      const next = groups[revealed];
-      if (!next) {
-        return;
-      }
-      next.hidden = false;
-      revealed += 1;
-      sync();
-      next.focus();
-    });
-
-    sync();
-  }
-}
-
-if (!customElements.get("blume-changelog")) {
-  customElements.define("blume-changelog", BlumeChangelog);
-}

package/src/search/providers.ts

@@ -1,91 +0,0 @@
-import type { SearchProvider } from "../core/schema.ts";
-
-/**
- * How a search provider integrates with the generated runtime.
- *
- * - `static` providers ship a client-side index (`blume-search.json`) that the
- *   browser loads and queries — `orama`, `flexsearch`.
- * - `pagefind` builds its own index from the rendered HTML after the Astro build.
- * - `hosted` providers are queried directly from the browser against an external
- *   service, with a build-time sync uploading the index — `algolia`,
- *   `orama-cloud`, `typesense`.
- * - `server` providers proxy queries through a generated `/api/search` endpoint
- *   that holds a secret key, so they require server output — `mixedbread`.
- */
-export type SearchProviderKind =
-  | "static"
-  | "pagefind"
-  | "hosted"
-  | "server"
-  | "none";
-
-export interface SearchProviderMeta {
-  kind: SearchProviderKind;
-  /** Extra packages the generated `.blume/package.json` must declare. */
-  runtimeDeps: string[];
-  /** Whether the provider needs `deployment.output: "server"`. */
-  requiresServer: boolean;
-  /** Whether a build-time sync uploads the index to an external service. */
-  syncs: boolean;
-}
-
-export const SEARCH_PROVIDERS = {
-  algolia: {
-    kind: "hosted",
-    requiresServer: false,
-    runtimeDeps: ["algoliasearch"],
-    syncs: true,
-  },
-  flexsearch: {
-    kind: "static",
-    requiresServer: false,
-    runtimeDeps: ["flexsearch"],
-    syncs: false,
-  },
-  mixedbread: {
-    // Content is synced to the store out-of-band via the `mxbai` CLI, not by an
-    // in-process build step.
-    kind: "server",
-    requiresServer: true,
-    runtimeDeps: ["@mixedbread/sdk"],
-    syncs: false,
-  },
-  none: {
-    kind: "none",
-    requiresServer: false,
-    runtimeDeps: [],
-    syncs: false,
-  },
-  orama: {
-    kind: "static",
-    requiresServer: false,
-    runtimeDeps: ["@orama/orama"],
-    syncs: false,
-  },
-  "orama-cloud": {
-    kind: "hosted",
-    requiresServer: false,
-    runtimeDeps: ["@oramacloud/client"],
-    syncs: true,
-  },
-  pagefind: {
-    kind: "pagefind",
-    requiresServer: false,
-    runtimeDeps: [],
-    syncs: false,
-  },
-  typesense: {
-    kind: "hosted",
-    requiresServer: false,
-    runtimeDeps: ["typesense"],
-    syncs: true,
-  },
-} satisfies Record<SearchProvider, SearchProviderMeta>;
-
-export const searchProviderMeta = (
-  provider: SearchProvider
-): SearchProviderMeta => SEARCH_PROVIDERS[provider];
-
-/** Whether a provider ships a client-loaded `blume-search.json` index. */
-export const servesStaticIndex = (provider: SearchProvider): boolean =>
-  SEARCH_PROVIDERS[provider].kind === "static";