blume 1.0.4 → 1.1.1

package/docs/configuration/ai.mdx

@@ -1,6 +1,6 @@
 ---
 title: AI
-description: Machine-readable docs with llms.txt and an optional in-page Ask AI assistant.
+description: Make your docs machine-readable with llms.txt, add an optional in-page Ask AI assistant, and expose a hosted MCP server for coding agents.
 ---
 
 Blume has a few AI features: machine-readable docs for external tools (`llms.txt`, on by default), an in-page **Ask AI** assistant, and a hosted **MCP server** for coding agents. Ask AI and MCP are opt-in, and static docs stay fully static until you turn a feature on.
@@ -47,11 +47,11 @@ Append `.md` or `.mdx` to any page's URL to fetch its raw Markdown source — pe
 
 Nested routes work the same way (`/content/syntax.md`), and the home page is served at `/index.md`.
 
-The `.md` variant _downlevels_ components to plain Markdown for consumers that can't interpret JSX: `<TypeTable>` becomes a Markdown table, `<Callout>` a labeled blockquote, `<Steps>` an ordered list, `<Tabs>` bold-labeled sections, and `<YouTube>` a link. Anything that can't be converted faithfully — a custom component, or a prop computed from an import — is left as-is, and component markup inside fenced code blocks is never touched. The same conversion applies to `llms-full.txt` and the MCP server's `get_page` tool, so every agent-facing surface reads clean Markdown. When you want the untransformed source, use the `.mdx` variant.
+The `.md` variant _downlevels_ components to plain Markdown for consumers that can't interpret JSX: `<TypeTable>` becomes a Markdown table, `<Callout>` a labeled blockquote, `<Steps>` an ordered list, `<Tabs>` bold-labeled sections, and `<YouTube>` a link. Props are evaluated with the page's `frontmatter` in scope, so a prop like `title={frontmatter.status}` resolves to the same value the rendered page shows. Anything that can't be converted faithfully — a custom component, or a prop computed from an import — is left as-is, and component markup inside fenced code blocks is never touched. The same conversion applies to `llms-full.txt` and the MCP server's `get_page` tool, so every agent-facing surface reads clean Markdown. When you want the untransformed source, use the `.mdx` variant.
 
 ### Custom component serializers
 
-Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes) and its `children` (already downleveled to Markdown), and returns the replacement — or `null` to leave the JSX as-is:
+Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes, with the page's `frontmatter` in scope), its `children` (already downleveled to Markdown), and the page's `frontmatter` data, and returns the replacement — or `null` to leave the JSX as-is:
 
 ```ts blume.config.ts lineNumbers
 import { defineConfig } from "blume";

package/docs/configuration/customization.mdx

@@ -1,6 +1,6 @@
 ---
 title: Customization
-description: Override components, add interactive islands, mount custom pages, install registry components, or eject.
+description: Override components, add interactive islands, mount custom pages, install registry components, or eject entirely when you need full control.
 ---
 
 ## Component overrides

package/docs/configuration/export.mdx

@@ -1,6 +1,6 @@
 ---
 title: Export
-description: Let readers download any page as a PDF or EPUB — client-side, so static builds stay static.
+description: Let readers download any page as a PDF or EPUB — rendered client-side, so your static builds stay static and need no server infrastructure.
 ---
 
 Blume can add an **Export** action to the [page actions](/docs/content/navigation#page-actions) beneath the table of contents, letting readers save the page they're on as a **PDF** or an **EPUB**. It's off by default and entirely client-side — no server, and [static](/docs/deployment) builds stay static.

package/docs/configuration/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Configuration file
-description: Every option in blume.config.ts — site metadata, content, and links to each feature guide.
+description: Every option in blume.config.ts, from site metadata and content sources to the links that lead into each individual feature configuration guide.
 sidebar:
   label: blume.config.ts
 ---
@@ -188,6 +188,26 @@ content: {
 
 Static assets live in `public/` — a file at `public/logo.png` is served at `/logo.png`, so a reference like `![](/images/create.png)` resolves against `public/images/create.png`.
 
+## Frontmatter
+
+Page frontmatter is strictly validated — an unknown key fails the build, so typos are caught early. To carry project-specific metadata (an owner, a review date), declare the extra keys under `frontmatter.extend`, each mapped to a schema you supply:
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+import { z } from "zod";
+
+export default defineConfig({
+  frontmatter: {
+    extend: {
+      owner: z.string(),
+      reviewedAt: z.coerce.date().optional(),
+    },
+  },
+});
+```
+
+Any [Standard Schema](https://standardschema.dev) library works — Zod (whichever version your project installs), Valibot, ArkType. Keys outside the extension stay strictly validated, so typo-catching is unchanged. See [Custom keys](/docs/reference/frontmatter#custom-keys) for the validation semantics.
+
 ## GitHub
 
 Point Blume at your repository with `github`. It powers the header [repository link](/docs/content/navigation#repository-link) and the **Edit on GitHub** and **Give feedback** [page actions](/docs/content/navigation#page-actions):

package/docs/configuration/search.mdx

@@ -1,6 +1,6 @@
 ---
 title: Search
-description: Client-side search out of the box, with optional hosted and semantic backends.
+description: Client-side search that works out of the box with no API keys, plus optional hosted and semantic backends you can switch to as your docs grow.
 ---
 
 Blume ships local search with no hosted infrastructure and no API keys. It runs in the browser, works in both `blume dev` and `blume build`, and indexes only your real content — navigation chrome and excluded pages are skipped. When you outgrow it, you can switch to a hosted or semantic backend without changing how search looks or behaves — only the `search.provider` you configure changes.
@@ -13,6 +13,33 @@ Open search with <Badge variant="accent">⌘K</Badge> (or `Ctrl K`), or press `/
 
 Queries match page **titles**, **descriptions**, and **body text**, with title matches ranked highest and descriptions above body.
 
+## Popular pages
+
+Before a reader types a query, the search dialog shows a **Popular** list. By default it is the first six sidebar pages — which on multi-tab sites often surfaces the wrong section. Pin the links you want instead:
+
+```ts blume.config.ts lineNumbers
+search: {
+  popular: [
+    { href: "/guides/getting-started", icon: "rocket", label: "Getting started" },
+    { href: "/guides/install", icon: "download", label: "Install" },
+    { href: "/concepts/overview", label: "Overview" },
+  ],
+},
+```
+
+Each entry takes an `href` (internal route or external URL) and a `label`, plus an optional `icon` — a built-in icon name shown beside the label, defaulting to a file glyph. Omit `popular` or leave it empty to keep the sidebar fallback.
+
+Unlike icons elsewhere in Blume, `icon` here must be a built-in name: these rows render in a client island, so an image path or inline SVG isn't supported and falls back to the file glyph.
+
+Write `href` as if the site were mounted at the root — a `basePath` is applied for you, the same as `navigation.featured`. External URLs pass through untouched.
+
+<Callout type="warning">
+  A curated list is a single set of links shared by every language. On a site
+  with `i18n` configured, the sidebar fallback follows the reader's locale, but
+  `popular` entries point wherever their `href` says — so pin locale-prefixed
+  routes only if you want every reader sent to that one language.
+</Callout>
+
 ## What's indexed
 
 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.

package/docs/configuration/seo.mdx

@@ -108,7 +108,7 @@ seo: {
 
 ### Brand the generated card
 
-Set a local SVG and hex palette to match the generated card to your brand. The logo can live in `public/` or at the project root. Omit any palette value to keep its default.
+Set a local SVG and color palette to match the generated card to your brand. The logo can live in `public/` or at the project root. Omit any palette value to keep its default.
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -144,9 +144,44 @@ seo:
 ```
 
 :::note
-OG rendering uses hex internally, so an `oklch` custom accent falls back to the default. Use a named accent (`blue`, `teal`, …) or a hex value for custom cards.
+Every palette color accepts any CSS color — hex, `oklch(…)`, `rgb(…)`, and so on. The accent also accepts a named preset (`blue`, `teal`, …), matching [`theme.accent`](/docs/configuration/theming#accent). A color the renderer can't parse fails the build rather than silently shipping a default-colored card.
 :::
 
+Emoji in a page title or site title render as [Twemoji](https://github.com/jdecked/twemoji) glyphs, fetched from a CDN while the card renders — so a build whose titles contain emoji needs network access. Each glyph is fetched once per build, however many pages use it.
+
+### Non-Latin titles
+
+The card's built-in font covers only Latin glyphs, so a title in another script (Japanese, Chinese, Korean, Arabic, …) renders as tofu — empty boxes. List one or more [Google Fonts](https://fonts.google.com) families in `og.fonts` that cover your script, by name:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: {
+    fonts: [
+      "Noto Sans JP",
+      { name: "Inter", weight: [400, 700] },
+    ],
+  },
+}
+```
+
+Each entry is a family name, or an object pinning its `weight` (a number, a list, or a variable range like `"100..900"`) and `style` (`"normal"`, `"italic"`, or both). The families are fetched from Google Fonts at build — so a build that uses them needs network access — and the renderer only pulls the glyph subsets each title actually uses. Fallback is per-glyph, so adding a family only affects glyphs the built-in font can't draw; Latin text renders exactly as before.
+
+### Custom page titles
+
+A custom [`.astro` page](/docs/advanced/custom-pages) has no frontmatter to read, so its generated card is titled by humanizing the last URL segment of its route — `/getting-started` becomes "Getting Started", but `/cli` becomes "Cli". Name those cards explicitly with `og.titles`, keyed by route (`"/"` addresses the home, whose card otherwise carries the site title):
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: {
+    titles: {
+      "/cli": "CLI",
+    },
+  },
+}
+```
+
+Entries only apply to custom pages — a content page's card always takes its headline from the page title, so retitle those in frontmatter instead.
+
 `seo.image` is frontmatter, so it only covers Markdown and MDX content. To give a custom [`.astro` page](/docs/advanced/custom-pages) its own social image — a marketing home or landing page, and the way to give the home page alone a bespoke share image — pass the `ogImage` prop to `PageLayout`.
 
 ## RSS feeds

package/docs/configuration/theming.mdx

@@ -1,6 +1,6 @@
 ---
 title: Theming
-description: Tune the look with config tokens, override any CSS variable in theme.css, or use Tailwind utilities.
+description: Tune the look with a handful of config tokens, override any CSS variable in theme.css, or drop down to Tailwind utilities for custom components.
 ---
 
 Blume's theme is token-driven and works in light and dark mode out of the box. Reach for as little or as much as you need: a few config tokens for the common cases, a `theme.css` to override any design token, or Tailwind utilities for custom components.

package/docs/content/components.mdx

@@ -69,6 +69,20 @@ Switch between equivalent content in place — language variants, OS-specific co
 </Tabs>
 ```
 
+Add `inline` to render borderless — a tab strip on a full-width rule with the content flowing beneath as prose — instead of the bordered box. Add `param` to sync the active tab to a URL query param instead of the hash, which makes the selection shareable: a link ending in `?install=windows` opens on the Windows tab. Each group syncs to its own `param`, so you can use several independent, deep-linkable groups on one page.
+
+<Tabs inline param="install">
+  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
+  <Tab title="Windows">Use winget to install the toolchain.</Tab>
+</Tabs>
+
+```astro lineNumbers
+<Tabs inline param="install">
+  <Tab title="macOS">Use Homebrew to install the toolchain.</Tab>
+  <Tab title="Windows">Use winget to install the toolchain.</Tab>
+</Tabs>
+```
+
 ## Badge
 
 A small inline label for status or metadata — version tags, “new” or “beta” markers, stability levels. The `variant` tunes the color to the meaning.

package/docs/content/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Pages
-description: How files in your content folder become pages, and how to organize them.
+description: How the files in your content folder become pages, and how to organize and name them so routing and navigation are inferred automatically.
 ---
 
 Your docs are just a folder of Markdown and MDX files. Blume turns each file into a page — routing, navigation, and metadata are inferred from the file system, so there's no manifest to keep in sync.

package/docs/content/meta.mdx

@@ -1,6 +1,6 @@
 ---
 title: Folder meta
-description: Configure a sidebar group — its title, icon, order, and page order — with a meta.ts file.
+description: Configure a sidebar group with a meta.ts file beside its pages — set the group's title, icon, order, and the order of the pages nested inside.
 ---
 
 Every folder in your content tree becomes a sidebar group. Drop a `meta.ts` beside its pages to control how that group looks and how its children are ordered. It's entirely optional: without one, the group's label is the humanized folder name and its pages sort by [index, numeric prefix, then alphabetically](/docs/content/navigation#ordering).

package/docs/content/navigation.mdx

@@ -1,6 +1,6 @@
 ---
 title: Navigation
-description: Build the sidebar from your files, then refine it with frontmatter, folder meta, or config.
+description: Blume builds the sidebar from your files, then lets you refine it with frontmatter, folder meta, or config — breadcrumbs and outlines follow along.
 ---
 
 Blume builds your sidebar from the file system, then lets you refine it as much — or as little — as you want: page by page, folder by folder, or with one explicit config. Breadcrumbs, previous/next links, and the on-page outline all follow from the same model, with nothing to wire up.
@@ -45,6 +45,8 @@ export default defineMeta({
 
 See [Folder meta](/docs/content/meta) for every field and computing meta at scan time.
 
+A folder's `meta.title` and its own `index` page's frontmatter `title` are resolved independently — translating one under i18n and forgetting the other renders a correct sidebar with a stale `<title>`/heading on the landing page itself. Blume reports a `BLUME_NAV_INDEX_TITLE_MISMATCH` warning when they diverge. Untranslated pages filled in from the fallback locale are exempt — their title belongs to the fallback locale, and the fix is translating the page, not editing its frontmatter.
+
 To group pages _without_ adding a URL segment, use a parenthesized folder name — see [Pages](/docs/content#group-folders).
 
 ## Display modes
@@ -86,6 +88,8 @@ When the sidebar is generated, order is resolved highest priority first:
   </Step>
 </Steps>
 
+Two siblings that land on the same explicit or numeric order fall back to alphabetical order between themselves — Blume reports a `BLUME_DUPLICATE_SIDEBAR_ORDER` warning so the tie doesn't go unnoticed.
+
 ## Hidden pages
 
 Hide a page from the sidebar — and from previous/next pagination — while keeping it built and reachable by its URL:

package/docs/content/sources.mdx

@@ -1,6 +1,6 @@
 ---
 title: Content sources
-description: Pull docs from local files, a remote repo, or any custom backend — and mix several sources into one site.
+description: Pull docs from local files, a remote repository, or any custom backend — and mix several sources into one static-first site read at build time.
 ---
 
 By default Blume reads a folder of `.md`/`.mdx` files. **Content sources** let you pull pages from somewhere else — a remote repository, a CMS, or any custom backend — and mix several sources into a single site. Sources are read at build time; Blume stays static-first.

package/docs/reference/cli.mdx

@@ -1,6 +1,6 @@
 ---
 title: CLI
-description: Every Blume command and flag — init, dev, build, preview, add, sync, and eject.
+description: Every Blume command and flag explained in one place — init, dev, build, preview, add, sync, and eject — along with the options each one accepts.
 ---
 
 ```bash
@@ -21,6 +21,7 @@ blume <command> [options]
 | `blume check`      | Type-check the site with `astro check`.          |
 | `blume doctor`     | Diagnose config and content problems.            |
 | `blume validate`   | Validate links across your content.              |
+| `blume audit`      | Audit the built site for SEO and health issues.  |
 
 ## Common flags
 
@@ -34,7 +35,7 @@ blume <command> [options]
 - `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 --strict` — fail the build on diagnostic errors (also works on `blume dev`).
+- `blume build --no-strict` — build despite diagnostic errors. By default `blume build` fails (exit 1) on any error diagnostic, because pages that fail frontmatter validation are dropped from the output; with `--no-strict` the build succeeds and reports how many pages are missing. `blume dev --strict` opts dev into the same fail-fast behavior.
 - `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — override the deployment output, adapter, and base path from `blume.config.ts`.
 - `blume build --analyze` — print the client JavaScript bundle sizes (largest first) after the build.
 - `blume build --budget-js <kb> --budget-css <kb>` — fail the build when total client JavaScript/CSS exceeds the budget, turning a performance target into a CI gate.
@@ -49,6 +50,14 @@ blume <command> [options]
 - `blume validate --external` — also check external links over the network.
 - `blume validate --strict` — exit non-zero on warnings too.
 - `blume validate --json` / `blume doctor --json` — emit diagnostics as JSON on stdout (with `code`, `severity`, `file`, `line`/`column`, and `docsUrl`) for CI and editor integrations.
+- `blume audit --fail-on error|warning|info` — the CI gate; defaults to `error`. `--strict` is an alias for `--fail-on warning`.
+- `blume audit --url <origin>` — also probe a live deployment for status codes, response headers, and redirect chains.
+- `blume audit --external` — probe outbound links over the network.
+- `blume audit --only <check|category>` / `--skip <check|category>` — narrow the report while you work through it (comma-separated).
+- `blume audit --list-checks` — print every check the audit can report.
+- `blume audit --verbose` — list every affected page instead of the first few.
+- `blume audit --json` — emit the report as JSON on stdout.
+- `blume audit --claude` / `--codex` — hand the findings to Claude Code or Codex to fix interactively.
 
 ## Verifying while the dev server runs
 
@@ -107,3 +116,72 @@ Without a project `tsconfig.json`, only the generated runtime is checked.
 - **Anchor links** (`#section`, `/guides/intro#setup`) must match a heading on the target page — misses are warnings.
 - **Asset links** (`/logo.png`) are checked against the `public/` directory.
 - **External links** are only checked with `--external` (off by default since it requires the network); dead links (404/410/unreachable) are errors, while rate-limited or transient responses (403/429/5xx/timeout) are warnings.
+
+## Auditing the built site
+
+`blume validate` reads your _content_; `blume audit` reads the _built site_. It crawls the HTML in `dist/` after a build and reports SEO and site-health issues — titles, meta descriptions, canonicals, Open Graph and X cards, headings, hreflang, images, the sitemap, `robots.txt`, and structured data.
+
+Because Blume built the site, every finding names the source file **and the front matter line** that fixes it, not just the URL a crawler would see:
+
+```
+⚠ Meta description too long or too short   5 pages
+    /docs/configuration/export    content/docs/configuration/export.mdx:3
+    fix: Rewrite `description` in the frontmatter to fit the length range.
+```
+
+Run it after a build:
+
+```bash
+blume build
+blume audit
+```
+
+Findings are grouped by check rather than listed per page, so the report reads as a to-do list. Use `--verbose` to expand every affected page, and `--only`/`--skip` to work through one category at a time. `blume audit --list-checks` prints the full catalog.
+
+### Failing CI
+
+The exit code is the contract. By default `blume audit` fails only on errors — things that are definitely broken, like a link to a page that was never built, a redirect loop, or an invalid sitemap. Advisory findings (a short description, a duplicate title) are warnings and do not fail the build:
+
+```bash
+blume audit                      # fails on errors
+blume audit --fail-on warning    # also fails on warnings
+```
+
+### Checking a live deployment
+
+Some things only the real server can tell you: whether a page that exists in `dist/` actually 404s behind a bad rewrite, whether responses are compressed, and whether an `X-Robots-Tag` header is quietly deindexing a page whose HTML looks perfectly fine. Point the audit at a deployment to add those checks:
+
+```bash
+blume audit --url https://docs.example.com
+blume audit --url https://docs.example.com --external   # also probe outbound links
+```
+
+Outbound links are graded rather than flatly failed: a 404 is a broken link you can fix, while a 403 or 5xx is usually rate limiting or someone else's outage and is reported as a warning.
+
+### Fixing the findings with an agent
+
+If you use [Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex/cli), the audit can hand its findings straight to it:
+
+```bash
+blume audit --claude   # or --codex
+```
+
+This writes the complete JSON report — every affected page, not the terminal's three-page preview — to a file and opens the agent interactively with a prompt that walks it through the findings: edit the source file each finding names, apply its suggested fix, then run `blume build` and `blume audit` again until the report is clean. The session is interactive by design: you review the edits through the agent's own permission flow, and the agent is told never to fix a finding by deleting content.
+
+`--only` and `--skip` narrow the handoff the same way they narrow the report, so you can send one category at a time.
+
+### What it does and doesn't check
+
+The check set is deliberately narrower than a general-purpose SEO crawler's. Much of what such a crawler reports cannot happen to a Blume site — it never emits `rel=nofollow`, and Vite's content-hashed bundles are never missing or redirecting — and reporting those as permanent zeroes would just teach you to ignore the report.
+
+Two limits worth stating plainly:
+
+- **Structured data** is validated for well-formedness (valid JSON, a `@context`, a `@type` on every node). Blume does not validate against the full schema.org vocabulary or Google's rich-results rules.
+- **Core Web Vitals** are not checked. They need a real browser, and a flag that quietly measured nothing would be worse than not having one — so `blume audit` reports the layout-shift causes it _can_ see offline (images with no `width`/`height`, oversized assets) and leaves the rest alone for now.
+
+Anything the audit did not run is reported as skipped rather than silently passing:
+
+```
+⊘ network      skipped — pass --url <origin> (9 checks)
+⊘ external     skipped — pass --external (2 checks)
+```

package/docs/reference/frontmatter.mdx

@@ -1,6 +1,6 @@
 ---
 title: Frontmatter
-description: Every frontmatter field a page accepts — title, description, sidebar, SEO, search, and more.
+description: Every frontmatter field a page accepts, all optional — title, description, sidebar, SEO, search, and the rest, with what each one controls.
 ---
 
 Every page accepts the following frontmatter. All fields are optional.
@@ -81,4 +81,34 @@ changelog:
 
 `date` may live here or at the top level — both feed the [changelog RSS feed](/docs/content#feeds). See [Changelog](/docs/advanced/changelog) for the generated timeline page and feed.
 
+## Custom keys
+
+Any key outside this reference fails the build, so typos are caught early. Projects that carry their own metadata can opt extra keys in via [`frontmatter.extend`](/docs/configuration#frontmatter) in `blume.config.ts`, each validated by a schema the project supplies:
+
+```ts blume.config.ts lineNumbers
+import { defineConfig } from "blume";
+import { z } from "zod";
+
+export default defineConfig({
+  frontmatter: {
+    extend: {
+      owner: z.string(),
+      reviewedAt: z.coerce.date().optional(),
+    },
+  },
+});
+```
+
+```yaml page.mdx
+---
+title: Install
+owner: "@sam"
+reviewedAt: 2026-06-20
+---
+```
+
+Schemas are accepted through the [Standard Schema](https://standardschema.dev) interface, so Zod (whichever version your project installs), Valibot, and ArkType all work. Every declared key is validated on every page — absent ones included — so a required schema enforces the key site-wide; mark it `.optional()` to validate only where present. All other keys stay strictly validated, and built-in fields can't be redeclared.
+
+A page that fails validation fails `blume build` with a diagnostic naming the file and key. With [`--no-strict`](/docs/reference/cli#common-flags), the build succeeds anyway and the failing pages are dropped from the output — the build summary reports how many.
+
 Schemas are exported from `blume/schema` for editor and migration tooling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -86,8 +86,6 @@
     "@shikijs/twoslash": "^4.2.0",
     "@tailwindcss/typography": "^0.5.20",
     "@tailwindcss/vite": "^4",
-    "@takumi-rs/core": "^1.8.7",
-    "@takumi-rs/helpers": "^1.8.7",
     "@vercel/analytics": "^2.0.1",
     "ai": "^5.0.0",
     "astro": "^7.0.2",
@@ -103,6 +101,7 @@
     "katex": "^0.17.0",
     "marked": "^18.0.5",
     "mermaid": "^11.15.0",
+    "node-html-parser": "^9.0.0",
     "pagefind": "^1.3.0",
     "pathe": "^2.0.0",
     "react": "^19.0.0",
@@ -111,7 +110,9 @@
     "shiki": "^4.2.0",
     "simple-icons": "^13.0.0",
     "tailwindcss": "^4",
+    "takumi-js": "^2.2.1",
     "tinyglobby": "^0.2.10",
+    "twoslash": "^0.3.9",
     "typescript": "^6.0.3",
     "undici": "^8.6.0",
     "zod": "^3.24.0"

package/skills/blume-migrate/SKILL.md

@@ -66,7 +66,7 @@ The single biggest shift for most sources — especially Mintlify — is that **
 - **`content`:** `root` (default `"docs"`, relative to the project dir where `blume` runs), `include`/`exclude` (arrays of globs **relative to `content.root`**; defaults `["**/*.{md,mdx}"]` / `["**/_*", "**/.*"]`), `sources` (staged sources: `filesystem`, `github-releases`, `notion`, `sanity`, `mdx-remote`, `custom` — OpenAPI is **not** one of these; it's the top-level `openapi` field), `pages` (custom `.astro` dir), `defaultType`. When docs sit directly under the project dir (no `docs/` subfolder), set `root` there and **scope `include` to the real content folders** instead of scanning everything — `references/monorepo.md` §1.
 - **`basePath`** (top-level): a site-wide mount point (e.g. `"/docs"`) prepended to **every** route while staying invisible to the sidebar (no wrapper group). This is the right target for a source that served all docs under a prefix (Docusaurus `routeBasePath`, a Fumadocs `baseUrl` of `/docs`) — distinct from a per-source `prefix` (which adds a nav group) and from `deployment.base` (host subdirectory).
 - **`navigation`:** `tabs`, `selectors`, `featured` (links pinned above the sidebar on every route), `sidebar` (`{ display, items }` — `display` is the global render mode above; `items` is an explicit tree), `repo`. **Avoid an explicit `navigation.sidebar` unless you have to** — lean on the filesystem-derived sidebar. It only works when the file tree roughly matches the intended sidebar layout, so reshape folders to match first; reach for `sidebar.items` only for a shape files genuinely can't express (see "Config-declared nesting" above).
-- **`search`** (Orama default, Pagefind opt-in), **`ai`** (llms.txt, Ask AI), **`mcp`**, **`openapi`**, **`redirects`**, **`seo`**, **`markdown`**, **`analytics`**, **`deployment`**, **`i18n`**, **`toc`**, **`lastModified`**, **`github`**.
+- **`search`** (Orama default, Pagefind opt-in), **`ai`** (llms.txt, Ask AI, the MCP server), **`openapi`**, **`redirects`**, **`seo`**, **`markdown`**, **`analytics`**, **`deployment`**, **`i18n`**, **`toc`**, **`lastModified`**, **`github`**.
 - **Don't set `deployment.site`.** Blume auto-fills it: the dev server's `localhost` URL in dev, and the deployment URL (`VERCEL_PROJECT_PRODUCTION_URL`/`VERCEL_URL`) on Vercel. Hardcoding it in `blume.config.ts` overrides that auto-detection and pins the wrong absolute URL (canonical links, sitemap, OG, llms.txt) everywhere but the one host you typed — so leave it unset even when a source config had a `url`/`site` field. (Sitemap still generates in production because the deploy URL is present there.)
 - **Favicon is a filename convention, not config.** Drop `icon`/`favicon.{svg,png,ico}` (and `apple-icon.png`) in the project root or `public/` — Blume auto-detects it. There is **no** `favicon` config field. A source favicon given as `{ light, dark }` **collapses to one** — pick a single file and report the loss.
 

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

@@ -37,7 +37,7 @@ Resolve `$ref` includes first (Mintlify splits config across files). Map only wh
 | `variables` (`{{name}}`) | **inline into content** | Blume has no runtime `{{var}}` substitution — replace each `{{name}}` with its value in the pages |
 | `integrations.posthog` (`{ apiKey, apiHost }`) | `analytics.posthog` (`{ key, host }`) | preserve the host verbatim (e.g. `us.posthog.com` — Blume's default is `us.i.posthog.com`) |
 | `integrations` (GA, Plausible, Fathom, …) | `analytics.scripts` / `analytics.vercel` | one `scripts[]` entry per provider (`{ src, strategy, attributes }`); no first-class mapping beyond PostHog/Vercel |
-| `contextual` (`["copy","chatgpt","claude",…]`) | **mostly free** | Copy-as-Markdown and Open-in-chat are default page actions; `mcp` needs `mcp.enabled` + server output (report as a follow-up) |
+| `contextual` (`["copy","chatgpt","claude",…]`) | **mostly free** | Copy-as-Markdown and Open-in-chat are default page actions; `mcp` needs `ai.mcp.enabled` + server output (report as a follow-up) |
 | `redirects` | `redirects: [{ from, to }]` | static only — see below |
 | `navigation.languages` | `i18n` | see i18n below |
 
@@ -107,7 +107,8 @@ Rewrite each page's MDX:
 - **Callouts → directives** (directives are **MDX-only** — Mintlify content is already `.mdx`, so this just works; never rename a page to `.md`): `<Note>`→`:::note`, `<Tip>`→`:::tip`, `<Warning>`→`:::warning`, `<Info>`→`:::info`, `<Check>`→`:::success`, `<Danger>`/`<Error>`→`:::danger`. `<Callout type="x">` maps by type (`caution`→warning, `check`→success). A `title` attr → `:::type[Title]`. Drop `icon`/color props.
 - **Accordions — container/item inversion!** Mintlify nests `<Accordion title="…">` inside `<AccordionGroup>`. Blume inverts: `<AccordionGroup>`→`<Accordion>` (container), and each Mintlify `<Accordion title="…">`→`<AccordionItem title="…">` (item).
 - **`<RequestExample>`/`<ResponseExample>`** → `<CodeGroup>` (titled-fence tabs).
-- **These pass through — Blume ships them natively:** `<Columns>`/`<Column>`, `<Expandable>`, `<Tooltip>`, `<Frame>`, `<Panel>`, `<Card>`/`<CardGroup>`, `<Tabs>`/`<Tab>`, `<Steps>`/`<Step>`. Keep them as-is.
+- **`<Tabs>` → `<Tabs inline>`.** Mintlify renders tabs **borderless** — a strip on a full-width rule with the content flowing beneath as prose — while Blume's `<Tabs>` defaults to a bordered box. Add `inline` to each `<Tabs>` to preserve Mintlify's appearance; every child `<Tab title="…">` is unchanged. Don't add `param` — Mintlify tabs switch in place and don't deep-link to the URL, so plain `inline` is the faithful mapping.
+- **These pass through — Blume ships them natively:** `<Columns>`/`<Column>`, `<Expandable>`, `<Tooltip>`, `<Frame>`, `<Panel>`, `<Card>`/`<CardGroup>`, `<Tab>`, `<Steps>`/`<Step>`. Keep them as-is.
 - **API fields → `TypeTable`.** Blume does **not** ship `<ParamField>`/`<ResponseField>`/`<RequestField>`. Convert a cluster of fields into one `<TypeTable>` (rows keyed by field name, each `{ type, required?, default?, description }`). For a fully spec'd API, prefer deleting the hand-written fields and using the [OpenAPI reference](#openapi) instead.
 - **`<Update>`** (a Mintlify changelog entry) has no component form → convert to a `type: changelog` page, or use the `github-releases` source.
 - **Snippets are inlined, not imported.** Blume has no `/snippets` import mechanism. For each `import X from "/snippets/x.mdx"` + `<X prop="v" />`, inline the snippet's body (substituting `{prop}` placeholders), then delete the import and the `/snippets` file. Named string imports (`import { foo } from "/snippets/vars.mdx"`) → inline the value at each `{foo}`.

package/skills/blume-migrate/scripts/mintlify-codemod.mjs

@@ -277,7 +277,8 @@ const remapIcons = (fm) => {
       continue;
     }
     if (lucide !== raw) {
-      fm[i] = `${m.groups.indent}icon: ${lucide}`;
+      const comment = m.groups.comment ? ` ${m.groups.comment}` : "";
+      fm[i] = `${m.groups.indent}icon: ${lucide}${comment}`;
       changes.push({ detail: `${raw} → ${lucide}`, kind: "icon-remap" });
     }
     i += 1;
@@ -301,11 +302,12 @@ const setNested = (fm, parent, child, value) => {
       return { ok: false, reason: "child-exists" };
     }
     fm.splice(start + 1, 0, `  ${child}: ${value}`);
-    return { ok: true };
+    return { index: start + 1, ok: true };
   }
   // No parent block — append one at the end of the frontmatter.
+  const index = fm.length;
   fm.push(`${parent}:`, `  ${child}: ${value}`);
-  return { ok: true };
+  return { index, ok: true };
 };
 
 // Drop unsupported keys, rename Mintlify-only keys, flag ambiguous ones.
@@ -341,14 +343,24 @@ const rewriteFields = (fm) => {
       });
       continue;
     }
+    // Remove the source line before inserting: setNested splices into the
+    // parent block, and when that block sits above the source key the insert
+    // would otherwise shift `start` onto the wrong line. Failure paths don't
+    // mutate `fm`, so the line can be restored as-is on conflict.
+    const [removed] = fm.splice(start, 1);
     const placed = setNested(fm, parent, child, tk.value);
     if (placed.ok) {
-      fm.splice(start, 1);
+      if (placed.index < start) {
+        // The insert above the cursor pushed the unvisited lines down one
+        // slot; revisit the current index so none of them get skipped.
+        i += 1;
+      }
       changes.push({
         detail: `${tk.key} → ${parent}.${child}`,
         kind: "rename",
       });
     } else {
+      fm.splice(start, 0, removed);
       // Target already set, or parent is a scalar — leave the source in place so
       // no data is lost, and report it for manual resolution.
       changes.push({