blume 1.7.3 → 2.0.0

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) · Claude Code
 
   ✔ install-node-version         pass  1.00  14.2s  $0.14
+  ✔ custom-domain                pass  0.92  21.3s  $0.19
   ✖ deploy-vercel                fail  0.40  38.9s  $0.31
-      missing: the adapter is auto-detected
+      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 · $0.64
 ```
 
 ## 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 — [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. With `--agent 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

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 Claude Code or Codex. |
+| [`blume upgrade`](/docs/upgrading) | Move to a new major: bump `blume`, then list the config changes left or hand them to Claude Code or Codex. |
+
+## 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

@@ -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
 

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.