blume 1.4.3 → 1.5.0

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/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/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.3",
+  "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",
@@ -134,6 +135,7 @@
     "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",

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).

package/src/ai/agent-readability.ts

@@ -47,12 +47,41 @@ const askApiUrl = (
     : endpoint;
 };
 
+/** The `.well-known` discovery URLs a site can publish. */
+interface WellKnownArtifacts {
+  httpMessageSignaturesDirectory?: string;
+  apiCatalog?: string;
+  agentSkills?: string;
+}
+
+/** The agent-facing artifact index the manifest publishes. */
+interface AgentArtifacts extends WellKnownArtifacts {
+  markdown: { contentNegotiation?: string; pattern: string };
+  llmsFullTxt?: string;
+  llmsTxt?: string;
+  mcp?: { discovery: string; url: string };
+  askApi?: string;
+  sitemap?: string;
+  feeds?: string[];
+}
+
+/** The published `agent-readability.json` document. */
+export interface AgentReadabilityManifest {
+  artifacts: AgentArtifacts;
+  description?: string;
+  generator?: string;
+  name: string;
+  site: string | null;
+  contentUsage?: Record<string, boolean>;
+  repository?: string;
+}
+
 /** The `.well-known` discovery artifacts the site publishes, if any. */
 const wellKnownArtifacts = (
   config: BlumeProject["config"],
   abs: (path: string) => string
-): Record<string, string> => {
-  const artifacts: Record<string, string> = {};
+): WellKnownArtifacts => {
+  const artifacts: WellKnownArtifacts = {};
   if (config.ai.webBotAuth.keys.length > 0) {
     artifacts.httpMessageSignaturesDirectory = abs(
       "/.well-known/http-message-signatures-directory"
@@ -77,7 +106,7 @@ const wellKnownArtifacts = (
  */
 export const buildAgentReadability = (
   project: BlumeProject
-): Record<string, unknown> | null => {
+): AgentReadabilityManifest | null => {
   const { config } = project;
   if (!config.seo.agentReadability) {
     return null;
@@ -103,12 +132,10 @@ export const buildAgentReadability = (
     config.deployment.output === "server" &&
     (config.deployment.adapter === "vercel" ||
       config.deployment.adapter === "cloudflare");
-  const artifacts: Record<string, unknown> = {
-    markdown: {
-      ...(negotiates ? { contentNegotiation: "text/markdown" } : {}),
-      pattern: abs("/{route}.md"),
-    },
-  };
+  const markdown: AgentArtifacts["markdown"] = negotiates
+    ? { contentNegotiation: "text/markdown", pattern: abs("/{route}.md") }
+    : { pattern: abs("/{route}.md") };
+  const artifacts: AgentArtifacts = { markdown };
   if (config.ai.llmsTxt.enabled) {
     artifacts.llmsFullTxt = abs("/llms-full.txt");
     artifacts.llmsTxt = abs("/llms.txt");
@@ -135,7 +162,7 @@ export const buildAgentReadability = (
   }
 
   const version = project.manifest?.blumeVersion;
-  const manifest: Record<string, unknown> = {
+  const manifest: AgentReadabilityManifest = {
     artifacts,
     description: config.description,
     generator: version ? `blume@${version}` : undefined,

package/src/ai/ask-context.ts

@@ -102,9 +102,13 @@ const TERM = /[\p{L}\p{M}\p{N}]+/gu;
  * window silently degrades to the head of the page. The regex fallback covers
  * runtimes without the segmenter and still handles spaced scripts correctly.
  */
+const hasSegmenter = (
+  segmenter: typeof Intl.Segmenter | undefined
+): segmenter is typeof Intl.Segmenter => typeof segmenter === "function";
+
 const segmentQuery = (query: string): string[] => {
   const lowered = query.normalize("NFC").toLowerCase();
-  if (typeof Intl.Segmenter !== "function") {
+  if (!hasSegmenter(Intl.Segmenter)) {
     return lowered.match(TERM) ?? [];
   }
   const pieces: string[] = [];

package/src/ai/ask.ts

@@ -35,7 +35,16 @@ const OPENAI_COMPATIBLE = "openai-compatible";
 /** The AI SDK provider package the OpenAI-compatible providers install. */
 const OPENAI_COMPATIBLE_DEP = "@ai-sdk/openai-compatible";
 
-const ASK_PRESETS: Record<string, AskPreset> = {
+/**
+ * Connection presets keyed by provider name. Open-keyed on purpose: lookups
+ * use the configured `ai.ask.provider`, which includes values with no preset
+ * (the generic `openai-compatible`).
+ */
+interface AskPresetRegistry {
+  [provider: string]: AskPreset;
+}
+
+const ASK_PRESETS: AskPresetRegistry = {
   inkeep: {
     apiKeyEnv: "INKEEP_API_KEY",
     baseUrl: "https://api.inkeep.com/v1",