blume 1.4.2 → 1.5.0

package/dist/types/core/types.d.ts

@@ -114,9 +114,24 @@ export interface PageRecord {
     locale: string;
     /**
      * Locale-agnostic logical route shared by every translation (e.g.
-     * `/guides/x`). Pages with the same key are translations of each other.
+     * `/guides/x`, or `/v1.0/guides/x` under versioning — the key is
+     * version-specific, so translations group within their version).
+     * Pages with the same key are translations of each other.
      */
     translationKey: string;
+    /**
+     * Resolved docs version: an archived id (`v1.0`) for snapshot pages, `""`
+     * for the current (unprefixed) docs — including every page of an
+     * unversioned project.
+     */
+    version: string;
+    /**
+     * Version- and locale-agnostic logical route (e.g. `/guides/x` for
+     * `/v1.0/guides/x`). Pages with the same key and locale are the same
+     * logical page across versions — this drives the switcher's same-page
+     * navigation and the canonical-to-latest lookup.
+     */
+    versionKey: string;
     /**
      * True for entries filled in from the fallback locale to pad a locale's
      * navigation for pages it hasn't translated yet. The record's content —
@@ -170,7 +185,12 @@ export type NavNode = {
     label: string;
     badge?: string;
     directory?: DirectoryMode;
-    display?: SidebarDisplay;
+    /**
+     * The group's resolved render mode. Always stamped by both builders
+     * (generated and explicit-config sidebars), so the renderer can rely
+     * on it per node.
+     */
+    display: SidebarDisplay;
     icon?: string;
     route?: string;
     /**
@@ -249,6 +269,12 @@ export interface ContentGraph {
     navigation: Navigation;
     /** Navigation per locale; one entry per configured locale under i18n. */
     navigationByLocale: Record<string, Navigation>;
+    /**
+     * Navigation per archived version, keyed by version id and then locale code
+     * (`""` on a single-locale site). The current version's trees are
+     * `navigation`/`navigationByLocale`; empty when versioning is off.
+     */
+    navigationByVersion: Record<string, Record<string, Navigation>>;
     /** Map of route -> pageId for fast lookup and duplicate detection. */
     routes: Map<string, string>;
     diagnostics: Diagnostic[];
@@ -269,6 +295,12 @@ export interface LocaleSwitchOption {
     /** True when this locale has no real translation (renders fallback content). */
     untranslated: boolean;
 }
+/** A docs version a logical page exists in, for the switcher and canonicals. */
+export interface VersionAlternate {
+    /** Version id; `""` for the current (unprefixed) docs. */
+    version: string;
+    path: string;
+}
 /** A route entry written to `blume.manifest.json`. */
 export interface RouteManifestEntry {
     id: string;
@@ -296,6 +328,15 @@ export interface RouteManifestEntry {
     locale: string;
     /** Locales this logical page is genuinely translated into (excludes fallbacks). */
     alternates: RouteAlternate[];
+    /** Resolved docs version (`""` for the current docs; see `PageRecord.version`). */
+    version: string;
+    /**
+     * Versions this logical page exists in within this route's locale — the
+     * current version first, then archived versions in configured order. Drives
+     * the switcher's same-page navigation and the canonical-to-latest lookup.
+     * Empty when versioning is off.
+     */
+    versionAlternates: VersionAlternate[];
     /** True when this route renders fallback content for a missing translation. */
     fallback?: boolean;
     /** Resolved "last updated" ISO date, when the feature is enabled. */

package/dist/types/core/ui-packs/index.d.ts

@@ -10,4 +10,12 @@ import type { UIStringsOverride } from "../i18n-ui.ts";
  * `zh-TW`). A locale's pack is merged onto English by {@link resolveUIStrings},
  * so a pack only needs the keys it translates.
  */
-export declare const UI_PACKS: Record<string, UIStringsOverride>;
+/**
+ * Starter packs keyed by locale code. Open-keyed on purpose: resolvers look
+ * packs up by whatever locale a project configures, not only the codes here.
+ */
+interface UiPackRegistry {
+    [locale: string]: UIStringsOverride;
+}
+export declare const UI_PACKS: UiPackRegistry;
+export {};

package/dist/types/openapi/references.d.ts

@@ -1,4 +1,5 @@
 import type { ResolvedConfig } from "../core/schema.ts";
+export { normalizeRoute } from "../core/base-path.ts";
 /**
  * Pure resolution of the configured API reference blocks into concrete routes,
  * labels, and a renderer choice — no file IO, so the content source, the
@@ -43,9 +44,10 @@ export interface ReferenceSource {
     theme?: string;
     /**
      * Arbitrary Scalar config forwarded to `<ScalarComponent>` (Scalar renderer
-     * only). Takes precedence over Blume's derived spec/theme config.
+     * only). Takes precedence over Blume's derived spec/theme config. Typed off
+     * the config schema so the two can never drift.
      */
-    scalar?: Record<string, unknown>;
+    scalar?: ResolvedConfig["openapi"]["scalar"];
     /** Display options carried through to the Blume renderer. */
     display: ReferenceDisplay;
     /**
@@ -54,12 +56,17 @@ export interface ReferenceSource {
      */
     collisions?: string[];
 }
+/**
+ * Lowercase, hyphen-separated slug: `Add a Pet!` -> `add-a-pet`. Unicode
+ * letters are kept (`Größe` -> `größe`), NFC-normalized so canonically
+ * equivalent spellings (NFD input from macOS tooling) land on one slug.
+ * Non-ASCII slugs rely on the emitter percent-encoding the URL where a raw
+ * URI is required (sitemap, canonical).
+ */
 export declare const slugify: (text: string) => string;
-/** Normalize a configured route to a single leading slash, no trailing slash. */
-export declare const normalizeRoute: (route: string) => string;
 /**
- * Resolve every enabled reference. OpenAPI honors its `renderer` (Blume's own UI
- * by default); AsyncAPI is always rendered by Scalar for now.
+ * Resolve every enabled reference. Both blocks honor their `renderer` —
+ * Blume's own UI by default, with the embedded Scalar SPA as the opt-out.
  */
 export declare const resolveReferences: (config: ResolvedConfig) => ReferenceSource[];
 /**
@@ -70,7 +77,7 @@ export declare const resolveReferences: (config: ResolvedConfig) => ReferenceSou
  * targets so such a tab doesn't read as a broken link.
  */
 export declare const referenceRoutes: (config: ResolvedConfig) => string[];
-/** Blume-rendered OpenAPI references, deduped by route (first wins). */
+/** Blume-rendered references (both kinds), deduped by route (first wins). */
 export declare const blumeReferences: (config: ResolvedConfig) => ReferenceSource[];
 /** Whether any reference is Scalar-rendered (gates the `@scalar/astro` dep + pages). */
 export declare const hasScalarReferences: (config: ResolvedConfig) => boolean;

package/dist/types/seo/x-handle.d.ts

@@ -7,6 +7,7 @@
  * Astro's collections carry no schema here, so a page's `seo.x.creator` reaches
  * them as raw frontmatter, and the schema's own transform never runs on it.
  * (Blume's page pipeline does reject a non-string `creator` before the page is
- * built, so `unknown` is defense in depth rather than the expected path.)
+ * built, so the string guard is defense in depth rather than the expected
+ * path.)
  */
-export declare const normalizeXHandle: (value: unknown) => string | undefined;
+export declare const normalizeXHandle: <Value>(value: Value) => string | undefined;

package/docs/advanced/api-reference.mdx

@@ -1,9 +1,9 @@
 ---
 title: OpenAPI / AsyncAPI
-description: Drop in an OpenAPI spec and get a native API reference — one real page per operation, in your sidebar and search.
+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, and generated code samples. 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.
+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, and generated code samples. 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. Event-driven APIs get the [same treatment from an AsyncAPI spec](#asyncapi). The config below points Blume at the public Petstore spec as an example.
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -153,7 +153,7 @@ Blume's own [`i18n`](/docs/content/i18n) translates the docs chrome, but Scalar
 
 ## AsyncAPI
 
-Event-driven APIs use a sibling `asyncapi` block with the same shape. AsyncAPI is rendered by Scalar (the native renderer is OpenAPI-only for now); only the default route differs (`/events`):
+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, and an Authorization section derived from the spec's `securitySchemes` (server-level and operation-level, alternatives as "or" groups). Only the default route differs (`/events`):
 
 ```ts blume.config.ts lineNumbers
 asyncapi: {
@@ -162,6 +162,8 @@ asyncapi: {
 }
 ```
 
-:::warning
-Scalar's AsyncAPI support is still a work in progress — it renders channels, operations, messages, and a Models section, but there's **no interactive playground** for events yet. It improves upstream over time.
-:::
+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 unchanged: `route`, `sources` with `label`/`route`, `expandSchemas`, the [per-source indexing](#per-source-indexing) flags, and search indexing by operation summary and tag. Setting `renderer: "scalar"` opts back into the embedded Scalar SPA — Scalar auto-detects the document type and renders channels, operations, messages, and a Models section (no interactive playground for events) — where, as with OpenAPI, only `noindex` applies.

package/docs/configuration/ai.mdx

@@ -136,6 +136,22 @@ ai: {
 
 `label` is the question that gets asked; `icon` is optional. Leave `suggestions` unset (or empty) and the panel opens to a plain input.
 
+### Custom instructions
+
+Add your own system-prompt text with `instructions` — identity, language, tone, or anything else the assistant should keep in mind:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    instructions:
+      "You are Bloomy, the Acme docs assistant. Answer in the language the question was asked in, and keep answers under three paragraphs.",
+  },
+}
+```
+
+Your text is **appended to** the built-in instructions rather than replacing them: the built-in part carries the [grounding](#grounding) contract — answer only from the retrieved pages, cite them as Markdown links — that the chat panel's citations depend on, so it stays intact whatever you add.
+
 ### Grounding
 
 Ask AI is **grounded in your docs**. For each question it retrieves the most relevant pages — using the same lexical [Orama](/docs/configuration/search) index that powers on-page search — and injects them into the model's system prompt, so answers come from your content instead of the model's own knowledge. The assistant is told to answer only from the retrieved pages, to say when something isn't covered, and to cite the pages it drew from.
@@ -185,15 +201,17 @@ A static build with Ask AI enabled and no external `endpoint` fails fast with a
 
 By default Ask AI routes through the **Vercel AI Gateway**: `model` is a `provider/model` string, so you switch models by changing it (`openai/gpt-5.5`, `anthropic/claude-sonnet-4-5`, and so on) with no provider SDK to install. The gateway reads `AI_GATEWAY_API_KEY` from your environment and is wired up automatically when you deploy on Vercel.
 
-Set `provider` to point Ask AI somewhere else. Each backend reads its API key from an environment variable, and the matching provider SDK is added to your project's runtime automatically when you build — only the one you use:
+Set `provider` to point Ask AI somewhere else. Each backend reads its API key from an environment variable and streams through a provider SDK you install in your project — only the one you use:
+
+| `provider` | `model` | API key env var | SDK to install |
+| --- | --- | --- | --- |
+| `gateway` (default) | a `provider/model` string via the AI Gateway | `AI_GATEWAY_API_KEY` | none — ships with Blume |
+| `openrouter` | any [OpenRouter](https://openrouter.ai) model | `OPENROUTER_API_KEY` | `@openrouter/ai-sdk-provider` |
+| `llmgateway` | any [LLMGateway](https://llmgateway.io) model | `LLMGATEWAY_API_KEY` | `@ai-sdk/openai-compatible` |
+| `inkeep` | an [Inkeep](https://inkeep.com) QA model | `INKEEP_API_KEY` | `@ai-sdk/openai-compatible` |
+| `openai-compatible` | whatever your endpoint serves | set with `apiKeyEnv` | `@ai-sdk/openai-compatible` |
 
-| `provider` | `model` | API key env var |
-| --- | --- | --- |
-| `gateway` (default) | a `provider/model` string via the AI Gateway | `AI_GATEWAY_API_KEY` |
-| `openrouter` | any [OpenRouter](https://openrouter.ai) model | `OPENROUTER_API_KEY` |
-| `llmgateway` | any [LLMGateway](https://llmgateway.io) model | `LLMGATEWAY_API_KEY` |
-| `inkeep` | an [Inkeep](https://inkeep.com) QA model | `INKEEP_API_KEY` |
-| `openai-compatible` | whatever your endpoint serves | set with `apiKeyEnv` |
+The SDKs are optional peer dependencies, so add the one your backend needs to your project (e.g. `npm install @openrouter/ai-sdk-provider`). If it's missing, the build warns with the exact package name before Vite would fail to resolve the import.
 
 For example, to use OpenRouter:
 

package/docs/configuration/search.mdx

@@ -42,6 +42,8 @@ Write `href` as if the site were mounted at the root — a `basePath` is applied
 
 For every indexable page, Blume indexes its title, description, and body reduced to plain text — code blocks, images, and markup are stripped, so results stay relevant. The index is built from your source files, so it's identical in dev and production.
 
+On a [versioned](/docs/content/versioning) site, results default to the version being viewed, with an "All versions" toggle in the dialog footer (remembered per reader). Cross-version hits name their version on the row. Orama, FlexSearch, Algolia, and Typesense honor the scoping — hosted records carry a `version` facet, with the current docs uploaded as `"current"` — while Pagefind stays unscoped, matching its locale behavior.
+
 ## Tags
 
 Add `search.tags` to a page's frontmatter to group it under a filter in the search dialog — readers can narrow results to a tag with a click. Tags also become a facet on the hosted providers.

package/docs/configuration/seo.mdx

@@ -249,7 +249,7 @@ URLs are absolute when `deployment.site` is set. Pages marked `seo.noindex` are
 
 ## Sitemap
 
-Blume writes a `sitemap.xml` of every indexable page at build time. It needs an absolute [`deployment.site`](/docs/deployment) and lists every page except drafts, hidden, and `noindex` pages. On by default:
+Blume writes a `sitemap.xml` of every indexable page at build time. It needs an absolute [`deployment.site`](/docs/deployment) and lists every page except drafts, hidden, and `noindex` pages. On a [versioned](/docs/content/versioning) site, archived pages whose canonical points at their live equivalent are left out too — the live page is the one to index. On by default:
 
 ```ts blume.config.ts lineNumbers
 seo: {

package/docs/content/i18n.mdx

@@ -3,7 +3,7 @@ title: Internationalization
 description: Serve your docs in multiple languages with locale-aware routing, per-language navigation, translated UI, and SEO — all convention-first.
 ---
 
-Blume serves one project in many languages. Drop translated files into the right place and Blume wires up routing, the language switcher, per-locale navigation, and SEO for you — there's no separate routing layer to maintain. It's opt-in: without an `i18n` block, your site stays single-language exactly as before.
+Blume serves one project in many languages. Drop translated files into the right place and Blume wires up routing, the language switcher, per-locale navigation, and SEO for you — there's no separate routing layer to maintain. It's opt-in: without an `i18n` block, your site stays single-language exactly as before. It also composes with [versioning](/docs/content/versioning) — a frozen snapshot keeps its translations, and locale fallback works within each version.
 
 ## Enable it
 

package/docs/content/meta.mdx

@@ -31,11 +31,12 @@ Every field is optional — set only what you want to override.
 | `icon` | `string` | Icon shown next to the label. |
 | `order` | `number` | Position among sibling groups and pages. Lower numbers sort first. |
 | `collapsed` | `boolean` | Under the [`group` display mode](/docs/content/navigation#display-modes), whether the group starts collapsed. |
+| `display` | `"flat" \| "group" \| "page"` | Render mode for this group; overrides the global [`navigation.sidebar.display`](/docs/content/navigation#display-modes). |
 | `pages` | `string[]` | Explicit order for the group's children, by slug. |
 
 The `pages` array lists children by slug — the folder or file name with its numeric prefix and any parentheses stripped (so `01-quickstart.mdx` is `"quickstart"`). Children you leave out still appear, after the listed ones.
 
-How groups render — flat headers, collapsible disclosures, or drill-in panels — is a sidebar-wide setting, not per folder: see [display modes](/docs/content/navigation#display-modes).
+How groups render — flat headers, collapsible disclosures, or drill-in panels — defaults to the sidebar-wide `navigation.sidebar.display`; set `display` here to override it for this group alone. A folder's `index` page can also set it from frontmatter, which wins over `meta.ts` — see [per-group overrides](/docs/content/navigation#per-group-overrides).
 
 ## Computed meta
 

package/docs/content/meta.ts

@@ -10,6 +10,7 @@ export default defineMeta({
     "islands",
     "sources",
     "i18n",
+    "versioning",
   ],
   title: "Content",
 });

package/docs/content/navigation.mdx

@@ -69,7 +69,39 @@ navigation: {
 `page` mode keeps deep sections tidy — reach for it when groups have many children and you'd rather drill into them than scroll past them.
 :::
 
-A group in an [explicit sidebar](#explicit-sidebar) can override the global mode with its own `display`.
+### Per-group overrides
+
+Any generated group can opt out of the global mode — no explicit sidebar required. Set `display` in the folder's [`meta.ts`](/docs/content/meta), or — when the folder has an `index` page — under `sidebar` in that page's frontmatter, and only that group changes:
+
+```ts meta.ts
+import { defineMeta } from "blume";
+
+export default defineMeta({
+  title: "Client SDKs",
+  display: "page",
+});
+```
+
+```yaml index.mdx
+---
+title: Client SDKs
+sidebar:
+  display: page
+---
+```
+
+A generated group's effective mode resolves highest priority first:
+
+1. `sidebar.display` in the group's own `index` page frontmatter
+2. `display` in the folder's `meta.ts`
+3. The global `navigation.sidebar.display`
+4. The Blume default (`flat`)
+
+A group's `display` applies to that group only — nested subgroups resolve their own value through the same chain. A `page`-mode group with an index page still drills into its sub-panel: the index page lists as the panel's first item, and landing on its URL opens the panel directly.
+
+`sidebar.display` means nothing anywhere else — on a non-index page, on the content root's own `index` page (the root isn't a group; use `navigation.sidebar.display`), or on any page when an [explicit sidebar](#explicit-sidebar) is configured (its items own each group's mode) — so Blume reports a `BLUME_SIDEBAR_DISPLAY_IGNORED` warning instead of silently dropping it. `collapsed` remains specific to `group` mode; it's inert when a group resolves to `flat` or `page`.
+
+A group in an [explicit sidebar](#explicit-sidebar) overrides the global mode with its own `display`, exactly as before.
 
 ## Ordering
 
@@ -171,6 +203,8 @@ navigation: {
 
 Each item takes a `label`, a `path`, and optional `icon`, `description`, and `tag`. `kind` (`dropdown`, `product`, `version`, or `language`) is a hint for how the selector is used; all render the same dropdown.
 
+With [versioning](/docs/content/versioning) configured, Blume renders a version selector automatically — declaring your own `kind: "version"` selector here replaces the automatic one, so hand-rolled setups keep working.
+
 ## Featured links
 
 Pin links to the top of the sidebar, above every section — a blog, a changelog, a contact or support page that should always be one click away. Unlike the generated tree, featured links are **not scoped by tab**: they show on every route, on every breakpoint.

package/docs/content/sources.mdx

@@ -146,7 +146,7 @@ export default defineConfig({
 });
 ```
 
-The integration token comes from the `NOTION_TOKEN` environment variable (share the database with your integration). By default every page is imported; set `publishedValue` to make the `Status` property a publish gate — any other value then maps to `draft: true`, which production builds drop. **Notion image URLs are signed and expire**, so the adapter downloads them at build time into the site's assets and rewrites the references — a CMS image never rots a static build.
+The integration token comes from the `NOTION_TOKEN` environment variable (share the database with your integration). By default every page is imported; set `publishedValue` to make the `Status` property a publish gate — any other value then maps to `draft: true`, which production builds drop. **Notion image URLs are signed and expire**, so the adapter downloads them at build time into the site's assets and rewrites the references — a CMS image never rots a static build. API calls are paced through a small request pool (3 at a time, matching Notion's per-integration rate limit) so databases with hundreds of pages import without tripping `429` responses; set `concurrency` on the source to tune it.
 
 ## Preview and sync
 

package/docs/content/versioning.mdx

@@ -0,0 +1,106 @@
+---
+title: Versioning
+description: Freeze snapshots of your docs per release with a version switcher, canonical-to-latest SEO, version-scoped search, and a version-aware agent surface.
+---
+
+Blume versions your docs the way releases actually work: the latest documentation lives at your content root with clean, unprefixed URLs, and each past version is a frozen snapshot in its own folder. Cut a snapshot when you ship, and Blume wires up the switcher, the "old version" notice, search scoping, SEO, and the agent surface for you. It's opt-in: without a `versions` block, nothing changes.
+
+## Enable it
+
+Add a `versions` block naming the current docs and any archived snapshots:
+
+```ts blume.config.ts lineNumbers
+versions: {
+  current: { label: "v2.0", badge: "Latest" },
+  archived: [
+    { id: "v1.0" },
+    { id: "v0.9", label: "0.9 (legacy)" },
+  ],
+}
+```
+
+`current` labels the unprefixed tree in the switcher (with an optional `badge`). Each archived entry's `id` is both the snapshot's directory name and its URL segment — ids must start with a letter (`v1.0`, not `1.0`) so they can never collide with [numeric ordering prefixes](/docs/content/navigation#ordering). List archived versions newest first; that order is the switcher order.
+
+## Cut a version
+
+When you release, freeze the current docs with one command:
+
+```bash
+blume version v1.0
+```
+
+This copies your content tree into `docs/v1.0/` (existing snapshots excluded), rewrites root-absolute links inside the copy so they stay within the snapshot (`/guides/x` becomes `/v1.0/guides/x`, fenced and inline code untouched), and registers the id in `blume.config.ts` — or prints the entry to paste when your config is shaped in a way it won't touch. Links to pages that aren't part of the copied tree — generated API references, remote sources like a changelog — keep pointing at the live pages, since the snapshot has no copy of them. Run `blume version` with no id to list the configured versions.
+
+Review and commit the new directory like any other content. Restart `blume dev` to pick it up.
+
+```txt
+docs/
+  index.mdx               ->  /              (latest)
+  guides/quickstart.mdx   ->  /guides/quickstart
+  v1.0/
+    index.mdx             ->  /v1.0          (frozen)
+    guides/quickstart.mdx ->  /v1.0/guides/quickstart
+```
+
+**Archived means frozen.** Future edits belong in the live tree; a snapshot is the docs as they were. Blume leans on that: snapshots keep their own folder meta and translations, [`blume translate`](/docs/reference/translate) never retranslates them, and a configured explicit sidebar applies only to the current docs — a snapshot's sidebar always comes from its own files.
+
+## The switcher and the notice
+
+With versions configured, the header grows a version dropdown automatically. Switching lands on the same page in the target version when it exists, and on that version's root when it doesn't (set `switcher.redirect: "root"` to always land on the root). If you declare your own `kind: "version"` selector in [`navigation.selectors`](/docs/content/navigation#selectors), it replaces the automatic one.
+
+Every archived page also shows a non-dismissible notice with a "Go to latest" link pointing at the page's live equivalent. Customize or disable it per version:
+
+```ts blume.config.ts
+archived: [
+  { id: "v1.0", banner: "These docs cover the 1.x SDK." },
+  { id: "v0.9", banner: false },
+];
+```
+
+## SEO
+
+Old docs are search engines' favorite trap: the stale page outranks the live one, or both compete. Blume defaults to the answer SEO guides recommend and no other docs framework automates — archived pages stay indexable but declare the **latest equivalent as their canonical**, so the live page is authoritative while version-only content (a page that no longer exists in the latest docs) remains findable with a self-canonical.
+
+Per version you can pick a different treatment:
+
+```ts blume.config.ts
+archived: [
+  { id: "v1.0" }, // canonical → latest (default)
+  { id: "v0.9", canonical: "self" }, // every page authoritative
+  { id: "v0.8", noindex: true }, // deindexed entirely
+];
+```
+
+The sitemap follows suit: archived pages whose canonical points at a live equivalent are left out, `noindex` versions are left out wholesale, and version-only pages stay listed. A page's own `seo.canonical` frontmatter always wins.
+
+## Search
+
+The search dialog scopes results to the version being viewed, with an "All versions" toggle (remembered per reader) beside the language one. Cross-version hits name their version on the result row. Orama (the default), FlexSearch, Algolia, and Typesense all honor the scoping — hosted records carry a `version` facet, with the current docs uploaded as `"current"` — while Pagefind stays unscoped, matching its locale behavior.
+
+## Agents
+
+The agent surface is version-aware — something no other docs framework does:
+
+- The MCP `search_docs` and `list_pages` tools default to the current docs and accept `version`: an archived id (`"v1.0"`) or `"all"`. `get_navigation` returns an archived snapshot's tree on request.
+- `llms.txt` sections archived versions after the current docs, labeled `1.0 (archived)`, so an agent reading the index knows which docs are frozen.
+- `llms-full.txt` stays current-only — the flat dump never interleaves frozen copies of the same page.
+- Raw Markdown mirrors (`.md` URLs) exist for every version's pages, as for any route.
+
+## With i18n
+
+Versioning composes with [internationalization](/docs/content/i18n). On disk the version folder is outermost — a snapshot naturally contains its locale folders — while in URLs the locale stays outermost, matching the rest of the site:
+
+```txt
+docs/
+  guides/x.mdx            ->  /guides/x
+  fr/guides/x.mdx         ->  /fr/guides/x
+  v1.0/
+    guides/x.mdx          ->  /v1.0/guides/x
+    fr/guides/x.mdx       ->  /fr/v1.0/guides/x
+```
+
+Locale fallback works within each version: an untranslated snapshot page renders the fallback locale's content at the localized URL, and `hreflang` alternates group per version. A version id may not collide with a configured locale code — Blume rejects that config outright.
+
+## What stays unversioned
+
+Versioning covers the docs content tree. The blog, changelog, API references generated from OpenAPI specs, and custom pages are always current. Two more behaviors worth knowing: header tabs are defined against the current docs, so inside an archived tree the sidebar renders unscoped by tabs; and large sites should note each snapshot is a full copy — content, search index entries, and navigation data all grow per version.

package/docs/reference/cli.mdx

@@ -24,6 +24,7 @@ blume <command> [options]
 | `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
 

package/docs/reference/frontmatter.mdx

@@ -46,8 +46,11 @@ sidebar:
   icon: download
   badge: New
   hidden: false
+  display: page
 ```
 
+`display` sets the render mode of the page's folder group ([per-group overrides](/docs/content/navigation#per-group-overrides)) and is only meaningful on a folder's `index` page under the generated sidebar — anywhere else (a non-index page, the content root's own `index` page, or any page under an explicit `navigation.sidebar`) it has no group to configure, and Blume warns with `BLUME_SIDEBAR_DISPLAY_IGNORED`.
+
 ## SEO
 
 ```yaml lineNumbers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -72,6 +72,7 @@
     "@astrojs/node": "^11.0.0",
     "@astrojs/react": "^6.0.0",
     "@astrojs/vercel": "^11.0.3",
+    "@asyncapi/converter": "^2.0.2",
     "@clack/prompts": "^1.7.0",
     "@iconify-json/lucide": "^1.2.115",
     "@iconify/types": "^2.0.0",
@@ -86,6 +87,7 @@
     "@shikijs/twoslash": "^4.2.0",
     "@tailwindcss/typography": "^0.5.20",
     "@tailwindcss/vite": "^4",
+    "@types/mdast": "^4.0.4",
     "@vercel/analytics": "^2.0.1",
     "ai": "^7.0.42",
     "astro": "^7.1.0",
@@ -93,6 +95,7 @@
     "chokidar": "^5.0.0",
     "citty": "^0.1.6",
     "consola": "^3.4.0",
+    "cross-spawn": "^7.0.6",
     "dompurify": "^3.4.13",
     "dotenv": "^17.4.2",
     "epub-gen-memory": "^1.1.2",
@@ -113,10 +116,16 @@
     "medium-zoom": "^1.1.0",
     "mermaid": "^11.16.1",
     "micromark-extension-gfm": "^3.0.0",
+    "nanotar": "^0.3.0",
     "node-html-parser": "^9.0.0",
     "openapi-sampler": "^1.7.4",
+    "p-limit": "^7.3.1",
+    "p-map": "^7.0.6",
+    "p-retry": "^8.0.0",
+    "package-manager-detector": "^1.8.0",
     "pagefind": "^1.3.0",
     "pathe": "^2.0.0",
+    "perfect-debounce": "^2.1.0",
     "picomatch": "^4.0.5",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -126,16 +135,19 @@
     "sharp": "^0.35.3",
     "shiki": "^4.2.0",
     "simple-icons": "^13.0.0",
+    "string-width": "^8.1.0",
     "tailwindcss": "^4.3.3",
     "takumi-js": "^2.2.1",
     "tinyglobby": "^0.2.10",
     "twoslash": "^0.3.9",
     "typescript": "^6.0.3",
+    "ufo": "^1.6.4",
     "undici": "^8.9.0",
     "write-file-atomic": "^8.0.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
     "@types/html-escaper": "^3.0.4",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.0",

package/skills/blume-migrate/SKILL.md

@@ -44,8 +44,8 @@ The single biggest shift for most sources — especially Mintlify — is that **
 
 - **Folders become groups, files become pages.** A page's sidebar label is its frontmatter `title`; a group's label is the humanized folder name.
 - **Ordering resolves highest-priority-first:** an explicit `navigation.sidebar` (replaces the whole tree) → a folder's `meta.ts` `pages` array → a page's frontmatter `sidebar.order` → the filesystem (`index` first, then numeric filename prefix like `01-`, then alphabetical).
-- **`meta.ts` refines one folder** (`defineMeta({ title, icon, order, collapsed, pages })`). The `pages` array lists children by slug (numeric prefix and parentheses stripped); children you omit fall back to their own `sidebar.order`, then filesystem order (`index` still sorts first) — so a partial `pages` list is safe, but list every child when the source declared a complete order.
-- **Sidebar render mode is global, not per-folder.** `navigation.sidebar.display` in `blume.config.ts` is `"flat"` (default), `"group"` (collapsible), or `"page"` (drill-in sub-panel) and applies to **every** group at once. (It used to live on each folder's `meta.ts` as `display`; that field was **removed** — writing it in a `meta.ts` is now a build error. Set it once in config instead.) An explicit `navigation.sidebar` item may still override its own group's `display`.
+- **`meta.ts` refines one folder** (`defineMeta({ title, icon, order, collapsed, pages, display })`). The `pages` array lists children by slug (numeric prefix and parentheses stripped); children you omit fall back to their own `sidebar.order`, then filesystem order (`index` still sorts first) — so a partial `pages` list is safe, but list every child when the source declared a complete order.
+- **Sidebar render mode: a global default with per-folder overrides.** `navigation.sidebar.display` in `blume.config.ts` is `"flat"` (default), `"group"` (collapsible), or `"page"` (drill-in sub-panel) and sets the mode for every group at once. A folder can override its **own** group: `display` in its `meta.ts`, or — sugar when the folder has an `index` page — `sidebar.display` in that index page's frontmatter. Precedence: index frontmatter → `meta.ts` → global config → `flat`; an override applies to that one group only (nested subgroups resolve their own chain). So a source's per-category collapse/drill-in modes migrate per folder — only reach for the global mode when the whole sidebar changes. Under an explicit `navigation.sidebar`, the config item's own `display` field is the only per-group control (frontmatter/meta `display` is ignored there, with a `BLUME_SIDEBAR_DISPLAY_IGNORED` warning).
 - **An explicit `navigation.sidebar` replaces filesystem generation entirely.** Use it only for a nav shape files can't express. Its items are a page route string, a group (`{ label, items }`), or a link (`{ label, href }`).
 - **Config-declared nesting has no on-disk counterpart — materialize it or it flattens silently.** When a source (Mintlify `groups`, Nextra `_meta`, a Docusaurus sidebar…) declares a nested group, its pages usually sit **flat in one folder** and the grouping lives only in config. Filesystem-derived nav sees the flat folder and drops the inner group. To keep the nesting you must **either** move those pages into a real subfolder (`meta.ts` for label/`collapsed`) — which changes their URLs, so add `redirects` — **or** declare the group in an explicit `navigation.sidebar`, which nests the existing routes without moving a file. Walk config `pages`/nav arrays **recursively** during inventory and record where config nesting depth exceeds on-disk depth; that gap is exactly what gets lost.
 

package/skills/blume-migrate/references/docusaurus.md

@@ -41,7 +41,7 @@ Every Docusaurus repo serves **`static/`** at the site root (`static/img/foo.png
 ## Navigation: `sidebars.js` + `_category_.json`
 
 - **Autogenerated sidebar** (`{ type: 'autogenerated', dirName: '...' }`) → Blume's default filesystem navigation. Docusaurus strips numeric prefixes (`01-`) exactly like Blume, so the convention round-trips; no config needed.
-- **Explicit sidebar** (arrays of doc IDs, categories, links) → restructure into folders where possible; use `navigation.sidebar` only for shapes files can't express. A category `{ type: 'category', label, items }` → a folder (label → `meta.ts` `title`); `collapsed` → `meta.ts` `collapsed` (**no `display` field in `meta.ts`** — if collapse matters, set the global `navigation.sidebar.display: "group"` once in config).
+- **Explicit sidebar** (arrays of doc IDs, categories, links) → restructure into folders where possible; use `navigation.sidebar` only for shapes files can't express. A category `{ type: 'category', label, items }` → a folder (label → `meta.ts` `title`); `collapsed` → `meta.ts` `collapsed`, and collapsible rendering → that folder's `meta.ts` `display: "group"` (or `navigation.sidebar.display: "group"` once in config when every category collapses).
 - **`_category_.json`** (also `.yml`) (`{ label, position, collapsed, collapsible, link, className, customProps }`) → a folder `meta.ts`: `label`→`title`, `position`→`order`, `collapsed`→`collapsed`. `link.type: 'generated-index'` → an `index` page in the folder — **and the old URL was `/docs/category/<slug>`**, so add a redirect and rewrite inbound links. `link.type: 'doc'` → make that doc the folder's `index`. `collapsible`/`className`/`customProps` → drop (report).
 - **`src/pages/` — inventory, don't nuke.** Nearly every repo has a React landing page (`src/pages/index.tsx`) and often extra Markdown pages. Markdown pages → content pages; the React home page → rebuild as a docs index or a custom `.astro` page under `content.pages` — report either way.
 

package/skills/blume-migrate/references/fumadocs.md

@@ -39,7 +39,7 @@ Everything else is `defineConfig({ title })`.
 | `description` | **drop** (folders have no description) |
 | `collapsible: false` | **drop** (report — no per-folder equivalent) |
 
-`meta.ts` accepts **only** `title`, `icon`, `order`, `collapsed`, `pages` — there is **no `display` field** (writing one is a build error). Collapse rendering is global: when any folder needs collapsing, set `navigation.sidebar.display: "group"` once in `blume.config.ts`.
+`meta.ts` accepts **only** `title`, `icon`, `order`, `collapsed`, `pages`, `display`. Render mode is per-folder or global: a folder that needs collapsible rendering sets its own `meta.ts` `display: "group"` (drill-in is `"page"`); when the whole sidebar should collapse, set `navigation.sidebar.display: "group"` once in `blume.config.ts` instead of repeating it per folder.
 
 **`root: true` folders are Fumadocs' tab mechanism** — Fumadocs UI renders them as layout tabs and scopes the sidebar to the active one. That is exactly Blume's `navigation.tabs`: add `{ label, path, icon? }` per root folder (label/icon from its `meta.json`), pointing at the folder's route. Blume then scopes the sidebar by URL prefix the same way. Don't try to model root folders inside `meta.ts`.
 

package/skills/blume-migrate/references/mintlify.md

@@ -83,7 +83,7 @@ The codemod touches **only frontmatter**. Icons in MDX **body** (`<Icon icon="
 
 Mintlify's `navigation` object (`tabs`/`anchors`/`dropdowns`/`products`/`versions`/`languages`/`groups`/`pages`) is fully config-declared. **Prefer restructuring content into folders**, not porting the config verbatim:
 
-- **`groups`** (`{ group, pages: [...] }`) → a folder per group. The `group` name → the folder's humanized name or a `meta.ts` `title`. Nested groups → nested folders. `expanded: false` → `meta.ts` `collapsed: true` (inverted). `tag` → the folder/page `sidebar.badge`. **Folder metadata is a `meta.ts` module** (`export default defineMeta({ title, icon, order, collapsed, pages })`), a TypeScript file — **not** JSON. Blume does not read a `meta.json`, so any folder-level config you carry over from the source (or hand-write to preserve a group's label/order/collapse) must be authored as `meta.ts`. (Render mode — flat/group/page — is **not** a `meta.ts` field; it's the global `navigation.sidebar.display` in `blume.config.ts`.)
+- **`groups`** (`{ group, pages: [...] }`) → a folder per group. The `group` name → the folder's humanized name or a `meta.ts` `title`. Nested groups → nested folders. `expanded: false` → `meta.ts` `collapsed: true` (inverted). `tag` → the folder/page `sidebar.badge`. **Folder metadata is a `meta.ts` module** (`export default defineMeta({ title, icon, order, collapsed, pages, display })`), a TypeScript file — **not** JSON. Blume does not read a `meta.json`, so any folder-level config you carry over from the source (or hand-write to preserve a group's label/order/collapse) must be authored as `meta.ts`. (Render mode — flat/group/page — defaults to the global `navigation.sidebar.display` in `blume.config.ts`; a folder overrides its own group with `meta.ts` `display`, or `sidebar.display` in its `index` page's frontmatter.)
 - **Config-only nested groups don't exist on disk — you must materialize them, or they flatten silently.** A nested `{ group, pages }` almost never has a matching subfolder: its pages sit **flat in the parent directory** (e.g. `platform/analytics/getting-started.mdx`, `…/quick-reference.mdx`) and the grouping lives **only** in the `docs.json` `pages` array. If you leave the files where they are, filesystem-derived nav sees one flat folder and the inner group vanishes — Mintlify's `Analytics → Reference → {…}` becomes a flat `Analytics → {…}`. To preserve it you must **either** move those pages into a real subfolder (`platform/analytics/reference/`, with a `meta.ts` for the label/`collapsed`), **or** declare the shape in an explicit `navigation.sidebar`. Walk **every** `pages` array recursively and treat any nested `group` object as a folder-move to plan, not files already in place. When inventorying the nav (workflow step 2), record the config nesting depth separately from the on-disk depth — they diverge exactly here.
 - **This is the canonical case for `navigation.sidebar` over folders.** Materializing a purely-presentational nested group as a subfolder changes URLs (`/platform/analytics/getting-started` → `/platform/analytics/reference/getting-started`) for no reason other than a visual grouping, forcing a `redirects` entry per page. When you want to keep the nesting **and** the URLs, an explicit `navigation.sidebar` group (`{ label, items }`) is the better trade — it nests the existing routes without moving any file. Pick per group; don't reflexively flatten.
 - **`pages`** entries are page refs (paths without extension) → files at the corresponding path. An entry that's `"GET /path"` is an OpenAPI endpoint stub → **delete it** (Blume generates these; see OpenAPI).