blume 1.7.3 → 2.0.1

package/docs/{reference/eval.mdx → cli/evals.mdx}

@@ -10,21 +10,22 @@ blume eval
 ```
 
 ```
-blume eval  3 question(s) · Claude Code
+blume eval  4 question(s) · Codex
 
-  ✔ install-node-version         pass  1.00  14.2s  $0.14
-  ✖ deploy-vercel                fail  0.40  38.9s  $0.31
-      missing: the adapter is auto-detected
+  ✔ install-node-version         pass  1.00  14.2s
+  ✔ custom-domain                pass  0.92  21.3s
+  ✖ deploy-vercel                fail  0.40  38.9s
+      missing: deployment: vercel() from blume/deploy
   ⊘ search-providers             skipped
 
-  fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: the adapter is auto-detected
+  fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: deployment: vercel() from blume/deploy
 
-  2 passed · 1 failed · 1 skipped · 1m 42s · $0.45
+  2 passed · 1 failed · 1 skipped · 1m 42s
 ```
 
 ## How it works
 
-Each question runs through two agent sessions, using an agent CLI you already have installed — [Claude Code](https://claude.com/claude-code) by default, or [Codex](https://developers.openai.com/codex/cli) with `--agent codex`. Blume holds no API keys and calls no model itself.
+Each question runs through two agent sessions, using an agent CLI you already have installed — [Codex](https://developers.openai.com/codex/cli) by default, or [Claude Code](https://claude.com/claude-code) with `--agent claude`. Blume holds no API keys and calls no model itself. With Codex, both sessions also run without Codex's shell, command, and image tools, and inherit none of your environment variables.
 
 1. **The reader** answers the question using _only_ your documentation. It runs in an empty directory with its file, shell, and web tools disabled, connected to a private [MCP server](/docs/discoverability/mcp) that serves your docs — the same `search_docs`/`get_page` tools a real agent uses against your deployed site. It cannot read your repo, so it experiences the docs exactly like a fresh user: what isn't written doesn't exist.
 2. **The judge** grades the answer against the facts you listed, with no tools at all. Paraphrase passes; a missing or contradicted fact fails — and so does "the documentation doesn't say."
@@ -54,13 +55,13 @@ questions:
     question: How do I deploy to Vercel?
     expected:
       - run blume build
-      - the output directory is dist
+      - "server features need deployment: vercel() from blume/deploy"
     routes:
       - /docs/deployment
   - id: search-providers
     question: Which search providers are supported?
     expected:
-      - pagefind is the default
+      - Orama is the default, with no hosted service
     severity: warning # a miss warns instead of failing CI
     skip: true # temporarily excluded, reported as skipped
 ```
@@ -73,7 +74,7 @@ Write questions your users actually ask — the ones from support threads, GitHu
 
 ## Failing CI
 
-The exit code is the contract: any failed question exits non-zero. `--threshold` relaxes the gate to a passing fraction when you're digging out of a backlog:
+The exit code is the contract: any failed question exits non-zero. When the agent run itself fails — the reader or judge errors out rather than grading an answer — the report says `run failed:` and points at the question in your evals file instead of naming a docs page to fix, since the docs weren't graded. `--threshold` relaxes the gate to a passing fraction when you're digging out of a backlog:
 
 ```bash
 blume eval                    # every question must pass
@@ -97,7 +98,7 @@ This writes the full JSON report to a file and opens the agent interactively wit
 
 ## Flags
 
-- `--agent claude|codex` — which agent CLI runs the reader and judge. Defaults to `claude`.
+- `--agent codex|claude` — which agent CLI runs the reader and judge. Defaults to `codex`.
 - `--file <path>` — the evals file. Defaults to `evals.yaml`.
 - `--threshold <0..1>` — minimum passing fraction before the run exits non-zero. Defaults to `1`.
 - `--timeout <seconds>` — reader time limit per question. Defaults to `180`.

package/docs/cli/index.mdx

@@ -0,0 +1,105 @@
+---
+title: Overview
+description: Every Blume command in one place, the flags each one accepts, and how to verify a site while the dev server keeps running.
+---
+
+```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`](/docs/cli/doctor) | Diagnose config and content problems. |
+| [`blume validate`](/docs/cli/validate) | Validate links across your content. |
+| [`blume audit`](/docs/cli/audit) | Audit the built site for SEO and health issues. |
+| [`blume eval`](/docs/cli/evals) | Test the docs: an agent answers your questions using only the documentation. |
+| [`blume translate`](/docs/cli/translate) | Translate docs into the configured locales with a local agent CLI. |
+| [`blume version [id]`](/docs/cli/version) | Freeze the current docs as an archived version (no id lists configured versions). |
+| [`blume migrate [source]`](/docs/migrating) | Move a Mintlify, Fumadocs, Docusaurus, Starlight, or Nextra site to Blume with Codex or Claude Code. |
+| [`blume upgrade`](/docs/upgrading) | Move to a new major: bump `blume`, then list the config changes left or hand them to Codex or Claude Code. |
+
+## 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` — install with, and print next-steps for, a specific package manager (default: whichever ran `blume init`).
+- `blume init --no-install` — write the files but skip the dependency install, for CI or custom dependency workflows. By default `blume init` runs the package manager's install so the project is ready to run; if the install fails, the scaffold is kept, the retry command is printed, and the exit code is non-zero.
+- `blume init --eject` — scaffold, then eject to a standalone Astro project (with `--no-install`, falls back to guiding you through `blume eject` once dependencies are installed).
+- `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 --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.
+
+The commands with a page of their own list every flag there: [`blume doctor`](/docs/cli/doctor), [`blume validate`](/docs/cli/validate), [`blume audit`](/docs/cli/audit), [`blume eval`](/docs/cli/evals), [`blume translate`](/docs/cli/translate), and [`blume version`](/docs/cli/version). `blume validate`, `blume doctor`, `blume audit`, `blume eval`, and `blume translate` take `--json` to print machine-readable results on stdout for CI and editor integrations (see [Validate](/docs/cli/validate#json-output) for the diagnostics shape); `build`, `check`, and `dev` report to the terminal only. Every command rejects a flag it doesn't take, suggesting the closest match and listing the flags it accepts, so a typo like `--isolatd` fails instead of being ignored.
+
+## 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:4321; 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.

package/docs/cli/meta.ts

@@ -0,0 +1,7 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({
+  order: 9,
+  pages: ["doctor", "validate", "audit", "evals", "translate", "version"],
+  title: "CLI",
+});

package/docs/{reference → cli}/translate.mdx

@@ -6,22 +6,22 @@ description: blume translate fills in your locales with an AI agent — it finds
 Once [i18n](/docs/content/i18n) is on, every edit to a source page quietly outdates its translations. `blume translate` closes that loop: it computes exactly which pages are missing or stale in each locale, translates them headlessly with a local agent CLI, and records what it did in a committed ledger so the next run — and CI — knows what's current.
 
 ```bash
-blume translate --claude
+blume translate --codex
 ```
 
 ```
-blume translate  3 item(s) · 2 locale(s) · Claude Code
+blume translate  3 item(s) · 2 locale(s) · Codex
 
-  ✔ docs/guides/install.mdx → fr 24.2s $0.11
-  ✔ docs/guides/install.mdx → de 22.8s $0.10
-  ✔ meta titles (2) → de 4.1s $0.01
+  ✔ docs/guides/install.mdx → fr 24.2s
+  ✔ docs/guides/install.mdx → de 22.8s
+  ✔ meta titles (2) → de 4.1s
 
-  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s · $0.22
+  Translated 3 files into 2 locales · 1 adopted · 14 already up to date · 51.1s
 ```
 
 ## How it works
 
-Blume owns the pipeline; the agent only translates text. For each file that needs work, Blume builds a translation prompt, runs the agent CLI headlessly with its file, shell, and web tools disabled, validates the reply's structure, and writes the target file itself — [Claude Code](https://claude.com/claude-code) with `--claude`, or [Codex](https://developers.openai.com/codex/cli) with `--codex`. Blume holds no API keys and calls no model itself.
+Blume owns the pipeline; the agent only translates text. For each file that needs work, Blume builds a translation prompt, runs the agent CLI headlessly with its file, shell, and web tools disabled, validates the reply's structure, and writes the target file itself — [Codex](https://developers.openai.com/codex/cli) with `--codex`, or [Claude Code](https://claude.com/claude-code) with `--claude`. Blume holds no API keys and calls no model itself.
 
 Every validated write is recorded in `blume.translations.json` at the project root: for each source file and locale, a hash of the source at the moment it was translated. **Commit this file.** It's how a rerun knows the difference between "already translated" and "translated, but the source changed since" — and it's what makes the CI gate possible.
 
@@ -61,7 +61,7 @@ blume translate --check --json    # machine-readable drift report on stdout
 - run: npx blume translate --check
 ```
 
-The JSON report carries the same `diagnostics` + `summary` shape as `blume validate --json`, `blume audit --json`, and `blume eval --json`, with the drift grouped per locale. Hand-authored (untracked) translations never fail the gate.
+The JSON report carries the same `diagnostics` + `summary` shape as `blume validate --json`, `blume audit --json`, and `blume eval --json`, with the drift grouped per locale. Each missing or stale translation is an error diagnostic (`BLUME_TRANSLATE_MISSING`, `BLUME_TRANSLATE_STALE`), so `summary.error` matches the exit code. Hand-authored (untracked) translations never fail the gate.
 
 ## Limitations
 
@@ -72,7 +72,7 @@ The JSON report carries the same `diagnostics` + `summary` shape as `blume valid
 
 ## Flags
 
-- `--claude` / `--codex` — which agent CLI translates. Exactly one is required (except with `--check`).
+- `--codex` / `--claude` — which agent CLI translates. Exactly one is required (except with `--check`).
 - `--check` — report drift and exit non-zero, without writing anything.
 - `--concurrency <n>` — parallel agent sessions. Defaults to `4`, max `16`.
 - `--locale <codes>` — comma-separated target locales (defaults to every non-default locale).

package/docs/cli/validate.mdx

@@ -0,0 +1,41 @@
+---
+title: Validate
+description: blume validate checks every link in your content — pages, anchors, assets, and optionally external URLs — and fails CI when one is broken.
+---
+
+`blume validate` reads your content the way a build does and checks every link it finds. It doesn't generate or build anything, so it's the fast gate to put in front of `blume build`:
+
+```bash
+blume validate
+```
+
+- **Internal page links** (`/guides/intro`, `./sibling`) must resolve to a real page — broken ones are reported as errors. A component's string `href` (`<Card href="./install">`) is checked the same way; an `href={…}` expression isn't.
+- **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`](#flags) (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.
+
+## What counts as a page
+
+Links resolve against everything the built site serves, not just Markdown pages: custom [`.astro` pages](/docs/advanced/custom-pages), the generated [changelog](/docs/advanced/changelog) index, every configured [redirect](/docs/deployment#redirects), and, on a [multi-language site](/docs/content/i18n), an untranslated page's fallback URL under each locale. A page that fails to parse is reported alongside the link findings, because a page that never loads is a link-validation blind spot rather than a clean result.
+
+## Flags
+
+- `--external` — also check external `http(s)` links over the network.
+- `--strict` — exit non-zero on warnings too. Info-level notes stay advisory.
+- `--json` — emit the diagnostics as JSON on stdout instead of the terminal report.
+
+## Diagnostics
+
+| Code | Severity | Meaning |
+| --- | --- | --- |
+| `BLUME_BROKEN_LINK` | error | An internal link points at a route no page serves. |
+| `BLUME_BROKEN_ANCHOR` | warning | The page exists but has no anchor matching the fragment. |
+| `BLUME_BROKEN_ASSET` | warning | An absolute path isn't in `public/`, or a relative image embed isn't beside the page. |
+| `BLUME_ASSETS_UNCHECKED` | info | There is no `public/` directory, so absolute asset paths weren't checked. |
+| `BLUME_DEAD_LINK` | error or warning | An external link (with `--external`) returned 404/410 or was unreachable (error), or a transient 403/429/5xx/timeout (warning). |
+
+The exit code is the contract: errors exit non-zero, and `--strict` makes warnings do the same.
+
+## JSON output
+
+With `--json`, `blume validate` (and [`blume doctor`](/docs/cli/doctor)) write one object to stdout: a `diagnostics` list, each entry carrying its `code`, `severity`, `message`, the `file` relative to the project root with `line` and `column` when the finding has a location, a `suggestion`, and a `docsUrl` pointing at the page that explains the code, plus a `summary` of counts per severity. The exit code is unchanged, so the same invocation gates CI and feeds an editor integration.

package/docs/cli/version.mdx

@@ -0,0 +1,40 @@
+---
+title: Version
+description: blume version freezes the current docs as an archived version — copying the tree, rewriting its links, and registering the id in your config.
+---
+
+`blume version` is how you cut a [documentation version](/docs/content/versioning). Give it an id and it freezes the current content tree as a snapshot that keeps serving as the docs were:
+
+```bash
+blume version v1.0
+```
+
+That does four things:
+
+1. **Copies the content tree** into a folder named after the id (`docs/v1.0/`), leaving existing snapshots out of the copy.
+2. **Rewrites root-absolute links inside the copy** so they stay within the snapshot: `/guides/x` becomes `/v1.0/guides/x`. Fenced and inline code are left untouched, and links to pages the snapshot has no copy of — generated API references, remote sources like a changelog — keep pointing at the live pages.
+3. **Registers the id** in `versions.archived` in `blume.config.ts`. The first cut turns versioning on, adding a `versions` block with the id archived and the live docs labeled "Latest". When the config is shaped in a way it won't edit, it warns and prints the entry to paste instead.
+4. **Reports what it did**: the files copied, the pages whose links were rewritten, and a reminder that archived versions are frozen and that `blume dev` needs a restart to pick the snapshot up.
+
+Review and commit the new folder like any other content. Everything about how versions render — the switcher, the notice on archived pages, per-version labels and badges — is configuration, covered on the [Versioning](/docs/content/versioning) page.
+
+## Listing versions
+
+Run it with no id to list the configured versions: the current one with its label and badge, then each archived id and its folder. Before the first cut, when `versions` isn't configured, it tells you how to cut one instead.
+
+```bash
+blume version
+```
+
+## Flags
+
+- `--force` — overwrite a snapshot folder that already exists. Without it, an existing folder is an error, so a stray re-run can't clobber an archived version.
+
+## When it refuses
+
+The command exits non-zero without touching anything when:
+
+- the id doesn't start with a letter or contains characters other than letters, digits, dots, hyphens, and underscores (`v1.0`, not `1.0`, so an id can never collide with a [numeric ordering prefix](/docs/content/navigation#ordering));
+- the project has error diagnostics, since a snapshot of a broken tree would freeze the breakage — fix them first (`blume doctor` lists them);
+- the id is already registered in `versions.archived`;
+- the snapshot folder exists and `--force` wasn't passed.