blume 1.0.2 → 1.0.4

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

@@ -0,0 +1,76 @@
+# Nextra → Blume
+
+Nextra (on Next.js) declares navigation and per-page labels in `_meta` files — and crucially, **a folder's title and its pages' sidebar labels live in the _parent_ `_meta`**. Reconciling that cross-file inheritance is the main task. Nextra 4 was a near-rewrite, so **fingerprint the generation first** — it decides where config lives, where content lives, and what the components are called.
+
+## Detect & fingerprint the generation
+
+- **`_meta.{js,mjs,cjs,ts,jsx,tsx,json}`** files — the strongest fingerprint (v4 also has a single-file `_meta.global.*` variant).
+- **v2/v3 (Pages Router):** content in `pages/`, `_meta.json` (v2) or `_meta.{js,ts}` (v3), a `theme.config.{js,jsx,ts,tsx}`, components from `nextra-theme-docs` (v2) or `nextra/components` (v3).
+- **v4 (App Router):** **no `theme.config`** — config lives as component props in `app/layout.{jsx,tsx}` (`<Layout>`, `<Navbar>`, `<Banner>`, `<Footer>`, `<Search>`). Content is either a **`content/`** directory (with a catch-all `app/[[...mdxPath]]/page.jsx` gateway) **or** Next page files: **`app/**/page.mdx`**.
+- `nextra` + `next` deps; `next.config.*` wrapping `nextra({…})`.
+
+**v4 app-directory repos need a restructure, not a `content.root`.** Pointing `content.root` at `app/` gives every route a trailing `/page` and scans `layout.jsx`/gateway files. Move each `app/foo/page.mdx` → `foo.mdx` (or `foo/index.mdx` when it has children), and exclude the non-MDX app files. The catch-all `page.jsx`, `mdx-components.*`, and `app/layout.*` are teardown artifacts — but **harvest `app/layout.*` first** (see Config).
+
+## Config
+
+None of it maps automatically — read the config surface for the generation by hand and reconstruct in `blume.config.ts`:
+
+- **v2/v3 — `theme.config.*`:** `logo` (JSX — extract text/image) → `logo`; `project.link` → `github` (renders the header repo link); `docsRepositoryBase` → `github` (owner/repo/branch — and any trailing sub-path → `github.dir`); `banner.text`/`banner.key` → `banner.content`/`banner.id` (`dismissible` maps); `primaryHue`/`primarySaturation` → pick an equivalent `theme.accent` color; `footer` → drop (report); `faviconGlyph` → drop (Blume's favicon is a file convention); `useNextSeoProps`/head → per-page `seo` frontmatter or drop.
+- **v4 — `app/layout.*` props:** the same facts moved: `<Navbar logo projectLink>`, `<Layout docsRepositoryBase editLink sidebar={{…}} toc={{…}}>`, `<Banner>`, `<Footer>`. Map them the same way; sidebar/TOC tuning mostly drops (Blume's `toc` config covers min/max heading levels).
+- **`next.config.*`:** harvest **`redirects()`** — static entries become Blume `redirects: [{ from, to }]`; wildcard/dynamic ones move to host config (report). A `latex: true` flag means math is in play (see Math below). Then delete the file.
+- Root `_meta` entries with **`type: "page"`** → `navigation.tabs` (`{ label, path }`, where `path` is `/` for `index`, else `/<slug>`). `type: "page"` only maps at the **root**.
+
+## Navigation: `_meta` → `meta.ts` + frontmatter
+
+**Every `_meta` file must be carried over — always convert it to `meta.ts` + frontmatter, never drop it in favor of filename inference.** `_meta` is Nextra's canonical nav source (ordering, labels, folder titles); the filesystem alone can't reproduce it.
+
+For each `_meta` entry (`key` = slug, value = string title or `{ title, type, display, href, theme }`):
+
+| Nextra `_meta` entry | Blume |
+| --- | --- |
+| ordinary page/folder (string or `{ title }`) | slug → parent `meta.ts` `pages` (ordering). A **page** title → that page's frontmatter `sidebar.label`. A **folder** title → that child folder's `meta.ts` `title` (title lives in the parent!). A JSX title → extract its text. |
+| `display: "hidden"` | frontmatter `sidebar.hidden: true` |
+| `type: "separator"` | drop → recreate as a `(Group)/` folder / `meta.ts` boundary if needed |
+| `type: "menu"` (navbar dropdown) | drop → recreate via `navigation.selectors` if wanted |
+| `href` (external link) | **`navigation.featured`** (`{ label, href, icon? }` — pinned above the sidebar on every route); only drop deep-nested ones (report) |
+| `type: "page"` (subfolder, not root) | drop (only root → tabs) |
+| `theme: { collapsed }` on a folder | `meta.ts` `collapsed` |
+| `theme: { layout: "full" \| sidebar: false \| … }` | drop (report — no per-page layout switches) |
+| `"*"` wildcard entry | apply its value as the default for unlisted siblings, then drop |
+
+Write each folder's `meta.ts` with its `pages` order (from its own `_meta`) and its `title` (inherited from the parent's `_meta`). A v4 **`_meta.global.*`** file holds the whole tree in one place (folder entries carry `items`) — split it into per-folder `meta.ts` files with the same rules.
+
+## Frontmatter & titles — synthesize, don't just pass through
+
+Most Nextra pages have **no frontmatter**; the title falls back `_meta` title → `sidebarTitle` → `title` → **first body H1** → filename. Blume renders frontmatter `title` as the page H1, so for **every page**: set frontmatter `title` (from the `_meta` title, else the body H1, else a humanized filename), **remove the body H1**, and map `sidebarTitle` → `sidebar.label`. `asIndexPage: true` (v4 folder-index marker) → make the file the folder's `index.mdx` and drop the key. Drop any other non-schema key and report it.
+
+## Components
+
+- **Callouts:** `<Callout type="x">` → directive. Types: `default` (the prop default) → `:::note`, `info`→`:::info`, `warning`→`:::warning`, `error`→`:::danger`, `important` (v4) → `:::note`. Bare `<Callout>` → `:::note`. Drop `emoji` (there is no `title` prop to carry — Nextra callouts have none).
+- **v2 flat names:** v2 exported `Tab` and `Card` (flat) from **`nextra-theme-docs`**; v3/v4 use `Tabs.Tab`/`Cards.Card` from `nextra/components`. Handle both: `<Cards>`/`<Cards.Card>`/`<Card>` → `<CardGroup>`/`<Card>`; `<Tabs items={[…]}>` + `<Tabs.Tab>`/`<Tab>` → `<Tabs>`/`<Tab title="…">` (move labels from the parent `items` onto each `<Tab>`). `Cards` `num` → `CardGroup` `cols`.
+- **`<Steps>`:** Nextra's wraps **Markdown headings (h2–h6)**, one step per heading. Convert each heading to a `<Step title="…">` child (Blume `<Steps>`/`<Step>`) and delete the heading — this also keeps step titles out of the TOC, matching Nextra's behavior.
+- **`<FileTree>`/`<FileTree.Folder>`/`<FileTree.File>`** → `<Tree>`/`<Tree.Folder>`/`<Tree.File>` (or a list-driven `<FileTree>`).
+- **`<Bleed>`** (full-bleed) → no equivalent; drop the wrapper and report. **`<Table>`** → a plain Markdown table. **`<Banner>`** (v4, in layout) → the `banner` config.
+- **GitHub alert blockquotes** (v4 renders them): `> [!NOTE]`/`[!TIP]`/`[!WARNING]`/`[!IMPORTANT]`/`[!CAUTION]` → `:::note`/`:::tip`/`:::warning`/`:::note`/`:::warning` directives — Blume renders them as plain blockquotes otherwise.
+- **Strip or convert every import:** `nextra`, `nextra/*`, `nextra-theme-docs`, `nextra-theme-blog`, plus `next/image` (→ Markdown image or `<Frame>`), `next/link` (→ plain link), and local components (port or inline; report).
+
+## Code fences
+
+Nextra's fence meta differs from Blume's — rewrite it: `filename="app.js"` → a space-separated title (` ```js app.js `); `showLineNumbers` → `lineNumbers`; line highlighting `{1,4-5}` carries over unchanged; **drop** word-highlight `/word/`, `copy`/`copy=false`, and inline-code `{:lang}` suffixes. ` ```sh npm2yarn ` fences → ` ```package-install `.
+
+## Math
+
+Nextra enables math via `nextra({ latex: true })` (KaTeX or MathJax). In Blume, block math `$$…$$` renders in `.mdx` with **no config** (there is no `markdown.math` field). Convert Nextra's ` ```math ` fences → `$$…$$` blocks (they render as plain code blocks otherwise). Inline `$…$` is **not** supported — convert to display math or drop (report). MathJax-specific macros → report.
+
+## i18n
+
+- **v2/v3:** locale **file suffixes** (`index.en.mdx`, `index.zh.mdx`) + `i18n` in `next.config` → restructure into locale **folders** (default locale at the content root, others under `<code>/`), then `i18n: { defaultLocale, locales: [{ code, label }] }`.
+- **v4:** `content/<lang>/` dirs already match Blume's `dir` parser — map the locale list, no file moves.
+
+## Package.json & teardown
+
+Repoint `dev`/`build`/`start` scripts to the Blume CLI; remove `next`/`nextra`/`nextra-theme-*` deps and add `blume`. Delete after harvesting: `next.config.*` (redirects first!), `theme.config.*` (v2/v3), `app/layout.*` + the catch-all gateway + `mdx-components.*` (v4).
+
+## Dropped — report these
+
+Footer content; `primaryHue`-style theming beyond an accent color; `faviconGlyph`; `_meta` separators, menus, `newWindow`; per-page `theme` layout switches; `<Bleed>`; MathJax macros; word-highlight/copy fence meta; any icon you can't reconstruct as a Lucide name.

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

@@ -0,0 +1,116 @@
+# Starlight → Blume
+
+Starlight is an Astro integration configured via `starlight({…})` in `astro.config.*`, with content in `src/content/docs`. Both are Astro, so this is a natural fit — content can mostly stay in place, with one big caveat: **most Starlight content is `.md`, and Blume's `:::` directives are MDX-only** (see Asides below).
+
+## Detect
+
+- `astro.config.{mjs,mts,ts,js,cjs}` importing and calling **`starlight({…})`** (`import starlight from "@astrojs/starlight"`).
+- Content under **`src/content/docs/`**; a `src/content.config.ts` (current) or `src/content/config.ts` (pre-Astro-5).
+- `@astrojs/starlight` dep.
+
+Keep content where it is — set `content.root: "src/content/docs"`.
+
+## Config: `starlight({…})` → `blume.config.ts`
+
+**Harvest the surrounding `astro.config.*` too, not just the `starlight()` call:** top-level Astro `redirects` → Blume `redirects`; `site` → leave unset (Blume auto-detects); other integrations → report.
+
+| Starlight option | Blume |
+| --- | --- |
+| `title` | `title` (if per-locale/computed, set manually) |
+| `description` | `description` |
+| `logo` (`{ src }` or `{ light, dark, alt }`) | `logo` — move the referenced file into `public/` |
+| `logo.replacesTitle` | `logo: { text: "" }` (renders the mark alone) |
+| `favicon` | copy the file into `public/` (drop the config field — Blume auto-detects) |
+| `social` (array of `{ label, icon, href }`; pre-0.33 legacy: `{ github: url }` object) | derive **`github: { owner, repo }`** from the GitHub entry; other socials drop (report) |
+| `editLink.baseUrl` (`…/edit/<branch>/<subdir?>`) | `github: { owner, repo, branch }` — **and any repo sub-path after the branch → `github.dir`** (a docs-in-subfolder repo breaks every edit link without it) |
+| `sidebar` (array) | filesystem nav / `navigation.sidebar` (see below) |
+| `tableOfContents` (`false` or `{ minHeadingLevel, maxHeadingLevel }`) | `toc` — identical shape, 1:1 |
+| `markdown.headingLinks: false` | `markdown.headingAnchors: false` |
+| `expressiveCode.themes` | `markdown.codeBlocks.theme: { light, dark }` — EC assigns by theme _type_, so match each theme by its darkness, not by array position |
+| `expressiveCode.styleOverrides` | drop → restyle via a root `theme.css` file |
+| `head` | **drop and report** (there is no `seo.metatags`); analytics `<script>` entries → the `analytics` config |
+| `lastUpdated: true` | `lastModified: true` |
+| `customCss` | drop → move into a root **`theme.css`** file (auto-picked-up; not a config field) |
+| `components` (overrides) | Blume's layout slots via `defineComponents({ layout: { Header, Search, Sidebar, TableOfContents, Footer, … } })` — a near-1:1 map; reach for `blume eject` only beyond those |
+| `plugins` | **map, don't blanket-drop** — see Plugins below |
+| `pagination: false`, `pagefind`/Pagefind options, `titleDelimiter`, `credits`, `disable404Route`, `routeMiddleware` | drop (report) |
+| `locales` / `defaultLocale` | `i18n` (see below) |
+
+## Navigation: `sidebar`
+
+Starlight's `sidebar` array → prefer letting Blume generate from the filesystem; use `navigation.sidebar` only for shapes files can't express:
+
+- `{ label, autogenerate: { directory: "d" } }` → **structure the folder and rely on filesystem nav** (label → the folder's `meta.ts` `title`). Do **not** map it to a sidebar item with `root:` — in an explicit Blume sidebar that renders a single page link, not the directory's children.
+- string `"guides/intro"` → `"/guides/intro"`; `{ label?, slug }` → `/<slug>`.
+- `{ label, items: [...] }` → `{ label, items: [...] }` (recursive) — or better, a real folder.
+- `{ label?, link }` → `{ label, href: link }`.
+- `badge` (string or `{ text, variant }`) → `badge` (text only; variant drops). `collapsed` (bool) → `collapsed`. Item `attrs` and `translations` → drop (report).
+
+## Frontmatter
+
+| Starlight | Blume |
+| --- | --- |
+| `title` / `description` / `draft` / `slug` | pass through |
+| `sidebar.{label,order,hidden}` | pass through |
+| `sidebar.badge` | `sidebar.badge` (text only) |
+| `sidebar.attrs` | **remove** (strict schema — build error if left) |
+| `pagefind: false` | `search.exclude: true` |
+| `lastUpdated` (date/string) | `lastModified` |
+| `lastUpdated: false` (boolean) | **remove** (Blume's `lastModified` takes a date; a boolean is a build error) |
+| `prev` / `next` (booleans or labels) | **drop** (report — no per-page pagination toggle; `hideFooterPagination` does not exist) |
+| `template: splash` / `hero` | **no equivalent** — rebuild as a custom `.astro` page under `content.pages`; a `hero` on a normal page drops (report) |
+| `banner`, `tableOfContents`, `editUrl`, `head` | drop (report) |
+
+## Asides → directives (and the `.md` trap)
+
+Starlight's primary callout syntax is the `:::note`/`:::tip`/`:::caution`/`:::danger` directive **in plain `.md` files**. The directive names map perfectly (Blume aliases `caution`→warning; `error`→danger) and `[Title]` syntax carries over — **but Blume only parses directives in `.mdx`**. In a `.md` file, `:::note` renders as literal text and the build stays green. So: **rename every `.md` file that contains asides (or math, or mermaid/package-install fences) to `.mdx`** — for a typical Starlight repo that's most of the content; renaming everything to `.mdx` is usually simpler and safe.
+
+- `<Aside type="…" title="…">` (the component form) → the same directives; bare `<Aside>` → `:::note`.
+- An aside custom icon (`:::tip{icon="heart"}`) → drop the attr (report).
+
+## Components
+
+- **Renames:** `<CardGrid>` → `<CardGroup>`; `<LinkCard>` → `<Card>` (its `description` prop drops — fold into the body); `<TabItem label="…">` → `<Tab title="…">`. `<Tabs>` and `<Card>` stay; a `<Tabs syncKey="…">` → strip the prop (Blume tabs sync by default).
+- **`<Badge>` needs conversion, not pass-through:** Starlight puts content in a `text` prop and uses variants `note`/`tip`/`caution`/`danger`/`success`/`default` with sizes `small`/`medium`/`large`. Blume's `<Badge>` renders **children** with variants `default`/`accent`/`success`/`warning`/`danger` and sizes `xs`/`sm`/`md`/`lg`. Move `text` into the children; remap variant (`note`→`default`, `tip`→`accent`, `caution`→`warning`, `danger`→`danger`, `success`→`success`) and size (`small`→`sm`, `medium`→`md`, `large`→`lg`).
+- **Convert yourself:** `<Steps>` → Blume `<Steps>`/`<Step>`; `<FileTree>` → Blume `<FileTree>`; `<Code code={…}>` → a fenced code block; `<LinkButton>` → a Markdown link or `<Card>`.
+- Strip `import … from "@astrojs/starlight/*"` and `astro:assets` lines.
+
+## Code blocks: Expressive Code meta → Blume
+
+Starlight content is full of Expressive Code fence meta; Blume understands some of it and **promotes unknown bare tokens into the code-block title**, so unconverted meta produces garbage headers. Convert per fence:
+
+- `title="file.js"` → works as-is (or use the space-title shorthand). Line ranges `{2-3}` → work as-is.
+- `ins=`/`del=` line marks → `// [!code ++]` / `// [!code --]` comments; `mark=` → `{ranges}` or `// [!code highlight]`.
+- `showLineNumbers` → `lineNumbers`.
+- **Drop:** `frame="terminal"`, `collapse=`, `wrap`, `"string"` and `/regex/` text markers (report if they carried meaning).
+- ` ```diff lang="js" ` → a normal ` ```js ` fence with `[!code ++]`/`[!code --]` markers.
+
+## Plugins — map, don't drop
+
+- `starlight-openapi` → Blume's native `openapi.sources` (delete any generated pages; add the `navigation.tabs` entry).
+- `starlight-blog` → `type: blog` pages.
+- `starlight-versions` → `navigation.selectors` with `kind: "version"`.
+- `starlight-image-zoom` → delete (Blume zooms content images by default).
+- `starlight-links-validator` → delete (`blume validate` covers it).
+- Anything else → report.
+
+## Assets
+
+Starlight co-locates images in `src/assets/` with **relative** references (`../../assets/foo.png`) or `astro:assets` imports; Blume serves `public/` at the site root with absolute URLs. Move `src/assets/*` into `public/`, rewrite relative image paths and `~/`/`@/` aliases to absolute `/…` URLs, and replace `<Image>` imports with Markdown images (or `<Frame>`).
+
+## i18n
+
+Starlight has **two** layouts:
+
+- **`root` locale** (default language at `src/content/docs/`, others in `fr/`, `de/`… subdirs) → matches Blume's `dir` parser as-is: `i18n: { defaultLocale, locales: [{ code, label }] }`, no file moves.
+- **No `root` locale** (every language in a subdir, including the default — `en/…`) → Blume expects the default locale **at the content root**, so move the default locale's files up one level. Starlight served them at `/en/…`, so add a `redirects` entry per page.
+
+Don't restate Blume defaults (`hideDefaultLocalePrefix: true`, `parser: "dir"` are already the defaults). Starlight's untranslated-page fallback matches Blume's `fallbackLocale` default.
+
+## Teardown
+
+Remove `@astrojs/starlight` (and plugin deps) from deps, delete the Starlight bits of `astro.config.*` **after harvesting redirects**, delete `src/content.config.ts` / `src/content/config.ts`, repoint scripts to the Blume CLI, add `blume`. A `src/content/docs/404.md` has no direct Blume equivalent — report it (Blume ships its own 404).
+
+## Dropped — report these
+
+Non-GitHub socials, badge variants, sidebar/item `attrs` + `translations`, `customCss` beyond `theme.css`, `head` entries, `routeMiddleware`, splash/hero pages (rebuild as custom pages), aside custom icons, EC frames/collapse/text markers, prev/next toggles, unmapped plugins, any `<Icon>` name with no Lucide equivalent.

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

@@ -0,0 +1,466 @@
+#!/usr/bin/env node
+// mintlify-codemod.mjs — deterministic, idempotent frontmatter codemod for the
+// Mintlify → Blume migration. It rewrites ONLY the YAML frontmatter block of
+// `.md`/`.mdx` files; the body is never touched. Two passes:
+//
+//   1. Icons  — remap Mintlify (FontAwesome) `icon:` names to their closest
+//               Lucide equivalent (Blume is Lucide-only). Brand/no-equivalent
+//               icons are dropped and reported, never faked.
+//   2. Fields — drop frontmatter keys Blume's strict schema rejects, and rename
+//               Mintlify-only keys to their Blume nesting (sidebarTitle →
+//               sidebar.label, tag → sidebar.badge, canonical → seo.canonical,
+//               og:image → seo.image). Ambiguous keys (openapi/asyncapi/api)
+//               are flagged for human review, not transformed.
+//
+// Design constraints:
+//   - ZERO dependencies — safe in a pnpm-strict workspace with no hoisting; runs
+//     with a bare `node`, needs nothing from the target repo's node_modules.
+//   - Deterministic — no Date/Math.random; files processed in sorted order.
+//   - Idempotent — running twice makes no further change. Source keys are gone
+//     after the first pass; remapped icon values are already Lucide (every
+//     mapped value that is also a source key maps to itself); a rename whose
+//     target already exists is reported, not re-applied.
+//   - Surgical — untouched lines keep their exact formatting; only the specific
+//     lines that change are edited, so diffs stay small and reviewable.
+//   - Reports every change per file (and every drop/flag), so nothing is silent.
+//
+// Usage:
+//   node mintlify-codemod.mjs <path...>            # dry run — report only
+//   node mintlify-codemod.mjs --write <path...>    # apply changes in place
+//   node mintlify-codemod.mjs --json <path...>     # machine-readable report
+//   node mintlify-codemod.mjs --help
+//
+// Paths may be files or directories; directories are walked for .md/.mdx.
+
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+// --- Mintlify (FontAwesome) → Lucide icon map ------------------------------
+// Keys are lowercased Mintlify icon names; values are Lucide names. A value of
+// `null` means "no Lucide equivalent" (brand icons, mostly) — the icon line is
+// removed and reported. Every value that is itself a key maps to the same name,
+// which keeps the pass idempotent (a second run finds nothing to change). The
+// FontAwesome `x` (close) maps to Lucide `x`; the X/Twitter brand is
+// `x-twitter` and has no Lucide form.
+const ICONS = {
+  angular: null,
+  apple: null,
+  "arrow-right-from-bracket": "log-out",
+  aws: null,
+  bell: "bell",
+  bolt: "zap",
+  book: "book",
+  "book-open": "book-open",
+  boxes: "boxes",
+  calendar: "calendar",
+  "chart-column": "chart-column",
+  "chart-line": "chart-line",
+  "chart-simple": "chart-column",
+  check: "check",
+  "circle-check": "circle-check",
+  "circle-exclamation": "circle-alert",
+  "circle-info": "info",
+  "circle-question": "circle-help",
+  cloud: "cloud",
+  code: "code",
+  cog: "settings",
+  comments: "messages-square",
+  copy: "copy",
+  cube: "box",
+  cubes: "boxes",
+  database: "database",
+  "diagram-project": "workflow",
+  discord: null,
+  docker: null,
+  download: "download",
+  envelope: "mail",
+  facebook: null,
+  "file-lines": "file-text",
+  filter: "filter",
+  flask: "flask-conical",
+  folder: "folder",
+  gauge: "gauge",
+  "gauge-high": "gauge",
+  gear: "settings",
+  github: null,
+  gitlab: null,
+  globe: "globe",
+  google: null,
+  heart: "heart",
+  house: "house",
+  info: "info",
+  instagram: null,
+  java: null,
+  js: null,
+  key: "key",
+  "layer-group": "layers",
+  layers: "layers",
+  "life-ring": "life-buoy",
+  link: "link",
+  linkedin: null,
+  "location-dot": "map-pin",
+  lock: "lock",
+  magic: "sparkles",
+  "magnifying-glass": "search",
+  "map-marker": "map-pin",
+  medium: null,
+  microsoft: null,
+  node: null,
+  "node-js": null,
+  npm: null,
+  "pen-to-square": "square-pen",
+  php: null,
+  play: "play",
+  puzzle: "puzzle",
+  "puzzle-piece": "puzzle",
+  python: null,
+  question: "circle-help",
+  react: null,
+  "right-to-bracket": "log-in",
+  robot: "bot",
+  rocket: "rocket",
+  rust: null,
+  "screwdriver-wrench": "wrench",
+  search: "search",
+  server: "server",
+  settings: "settings",
+  shield: "shield",
+  "shield-halved": "shield",
+  sitemap: "network",
+  slack: null,
+  sparkles: "sparkles",
+  star: "star",
+  stripe: null,
+  tag: "tag",
+  telegram: null,
+  terminal: "terminal",
+  times: "x",
+  toolbox: "wrench",
+  "trash-can": "trash-2",
+  "triangle-exclamation": "triangle-alert",
+  twitter: null,
+  upload: "upload",
+  user: "user",
+  users: "users",
+  vuejs: null,
+  "wand-magic-sparkles": "sparkles",
+  whatsapp: null,
+  workflow: "workflow",
+  wrench: "wrench",
+  x: "x",
+  "x-twitter": null,
+  xmark: "x",
+  youtube: null,
+  zap: "zap",
+};
+
+// --- Frontmatter field policy ----------------------------------------------
+// Top-level keys Blume's strict schema rejects: delete the whole block, report.
+const DROP = new Set([
+  "groups",
+  "hideApiMarker",
+  "hideFooterPagination",
+  "iconType",
+  "keywords",
+  "mode",
+  "public",
+  "rss",
+]);
+
+// Mintlify-only keys → Blume nested target. `[parent, child]`.
+const RENAME = {
+  canonical: ["seo", "canonical"],
+  "og:image": ["seo", "image"],
+  ogImage: ["seo", "image"],
+  sidebarTitle: ["sidebar", "label"],
+  tag: ["sidebar", "badge"],
+};
+
+// Keys we deliberately do NOT auto-transform — they usually mean the page is an
+// OpenAPI endpoint stub that should be deleted (Blume generates operation pages)
+// or converted to `type: api`. Flag for the human; never guess.
+const FLAG = new Set(["api", "asyncapi", "openapi"]);
+
+// Which change kinds actually edit the file. Report-only kinds (flags,
+// unknowns, conflicts, manual-rename notices) leave the bytes untouched.
+const MUTATING = new Set(["drop", "icon-drop", "icon-remap", "rename"]);
+
+// --- Frontmatter line model -------------------------------------------------
+
+// Split a file into { fm, body, eol } or null when there's no `---` block.
+const splitFrontmatter = (text) => {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const lines = text.split(/\r?\n/u);
+  if (lines[0] !== "---") {
+    return null;
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i] === "---") {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) {
+    return null;
+  }
+  return { body: lines.slice(end + 1), eol, fm: lines.slice(1, end) };
+};
+
+// Match a top-level (column-0) `key:` line, honoring quoted keys. Because the
+// key class allows `:`, backtracking resolves `og:image: x` to key `og:image`.
+const topKey = (line) => {
+  const m = /^(?<q>["']?)(?<key>[^"'\s:][^"']*?)\k<q>\s*:(?<rest>\s.*|)$/u.exec(
+    line
+  );
+  if (!m || /^\s/u.test(line)) {
+    return null;
+  }
+  return { key: m.groups.key, value: (m.groups.rest ?? "").trim() };
+};
+
+// The line index range [start, endExclusive) of a top-level key's block.
+const blockRange = (fm, start) => {
+  let end = start + 1;
+  while (end < fm.length && (fm[end] === "" || /^\s/u.test(fm[end]))) {
+    end += 1;
+  }
+  // Trim trailing blank lines back out so the gap before the next key survives.
+  while (end - 1 > start && fm[end - 1] === "") {
+    end -= 1;
+  }
+  return [start, end];
+};
+
+// Does the block starting at `start` carry a nested child `childKey:`?
+const findChild = (fm, start, endExclusive, childKey) => {
+  for (let i = start + 1; i < endExclusive; i += 1) {
+    const m = /^\s+(?<q>["']?)(?<key>[^"'\s:][^"']*?)\k<q>\s*:/u.exec(fm[i]);
+    if (m && m.groups.key === childKey) {
+      return i;
+    }
+  }
+  return -1;
+};
+
+// --- The two passes ---------------------------------------------------------
+
+// Remap `icon:` values in place. Mutates `fm`; returns change records.
+const remapIcons = (fm) => {
+  const changes = [];
+  let i = 0;
+  while (i < fm.length) {
+    const m =
+      /^(?<indent>\s*)icon:\s*(?<q>["']?)(?<name>[^"'#]*?)\k<q>\s*(?<comment>#.*)?$/u.exec(
+        fm[i]
+      );
+    if (!m) {
+      i += 1;
+      continue;
+    }
+    const raw = m.groups.name.trim();
+    // Empty, an object, or a template ref — leave it for the human.
+    if (raw === "" || raw.startsWith("{") || raw.startsWith("$")) {
+      i += 1;
+      continue;
+    }
+    const key = raw.toLowerCase();
+    if (!(key in ICONS)) {
+      changes.push({ detail: raw, kind: "icon-unknown" });
+      i += 1;
+      continue;
+    }
+    const lucide = ICONS[key];
+    if (lucide === null) {
+      changes.push({ detail: raw, kind: "icon-drop" });
+      fm.splice(i, 1);
+      continue;
+    }
+    if (lucide !== raw) {
+      fm[i] = `${m.groups.indent}icon: ${lucide}`;
+      changes.push({ detail: `${raw} → ${lucide}`, kind: "icon-remap" });
+    }
+    i += 1;
+  }
+  return changes;
+};
+
+// Insert `child: value` under `parent`, creating the parent block if needed.
+const setNested = (fm, parent, child, value) => {
+  for (let i = 0; i < fm.length; i += 1) {
+    const tk = topKey(fm[i]);
+    if (!tk || tk.key !== parent) {
+      continue;
+    }
+    if (tk.value !== "") {
+      // `parent: scalar` — can't nest under a scalar without clobbering it.
+      return { ok: false, reason: "parent-is-scalar" };
+    }
+    const [start, end] = blockRange(fm, i);
+    if (findChild(fm, start, end, child) !== -1) {
+      return { ok: false, reason: "child-exists" };
+    }
+    fm.splice(start + 1, 0, `  ${child}: ${value}`);
+    return { ok: true };
+  }
+  // No parent block — append one at the end of the frontmatter.
+  fm.push(`${parent}:`, `  ${child}: ${value}`);
+  return { ok: true };
+};
+
+// Drop unsupported keys, rename Mintlify-only keys, flag ambiguous ones.
+const rewriteFields = (fm) => {
+  const changes = [];
+  // Walk from the bottom so splices don't shift indices we haven't visited.
+  for (let i = fm.length - 1; i >= 0; i -= 1) {
+    const tk = topKey(fm[i]);
+    if (!tk) {
+      continue;
+    }
+    if (DROP.has(tk.key)) {
+      const [start, end] = blockRange(fm, i);
+      fm.splice(start, end - start);
+      changes.push({ detail: tk.key, kind: "drop" });
+      continue;
+    }
+    if (FLAG.has(tk.key)) {
+      changes.push({ detail: tk.key, kind: "flag" });
+      continue;
+    }
+    const target = RENAME[tk.key];
+    if (!target) {
+      continue;
+    }
+    const [parent, child] = target;
+    const [start, end] = blockRange(fm, i);
+    if (end - start !== 1 || tk.value === "") {
+      // Multi-line or valueless source — too structured to move safely.
+      changes.push({
+        detail: `${tk.key} → ${parent}.${child}`,
+        kind: "rename-manual",
+      });
+      continue;
+    }
+    const placed = setNested(fm, parent, child, tk.value);
+    if (placed.ok) {
+      fm.splice(start, 1);
+      changes.push({
+        detail: `${tk.key} → ${parent}.${child}`,
+        kind: "rename",
+      });
+    } else {
+      // 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({
+        detail: `${tk.key} → ${parent}.${child} (${placed.reason})`,
+        kind: "rename-conflict",
+      });
+    }
+  }
+  return changes.toReversed();
+};
+
+// --- Driver -----------------------------------------------------------------
+
+const transform = (text) => {
+  const split = splitFrontmatter(text);
+  if (!split) {
+    return { changed: false, changes: [], text };
+  }
+  const fm = [...split.fm];
+  const changes = [...remapIcons(fm), ...rewriteFields(fm)];
+  const rebuilt = ["---", ...fm, "---", ...split.body].join(split.eol);
+  const changed = rebuilt !== text && changes.some((c) => MUTATING.has(c.kind));
+  return { changed, changes, text: changed ? rebuilt : text };
+};
+
+const collectFiles = (paths) => {
+  const out = [];
+  const walk = (p) => {
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      for (const name of readdirSync(p).toSorted()) {
+        if (name === "node_modules" || name.startsWith(".")) {
+          continue;
+        }
+        walk(path.join(p, name));
+      }
+    } else if (/\.mdx?$/u.test(p)) {
+      out.push(p);
+    }
+  };
+  for (const p of paths.toSorted()) {
+    walk(p);
+  }
+  return out;
+};
+
+const LABEL = {
+  drop: "dropped",
+  flag: "FLAG (review)",
+  "icon-drop": "icon dropped (no Lucide equivalent)",
+  "icon-remap": "icon",
+  "icon-unknown": "icon unknown (verify at lucide.dev)",
+  rename: "renamed",
+  "rename-conflict": "rename conflict (left in place)",
+  "rename-manual": "rename needs manual edit",
+};
+
+const HELP = [
+  "mintlify-codemod — icon + frontmatter pass for Mintlify → Blume",
+  "",
+  "  node mintlify-codemod.mjs <path...>          dry run (report only)",
+  "  node mintlify-codemod.mjs --write <path...>  apply in place",
+  "  node mintlify-codemod.mjs --json <path...>   JSON report",
+  "",
+].join("\n");
+
+const main = () => {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h") || argv.length === 0) {
+    process.stdout.write(`${HELP}\n`);
+    return;
+  }
+  const write = argv.includes("--write");
+  const asJson = argv.includes("--json");
+  const paths = argv.filter((a) => !a.startsWith("--"));
+  const files = collectFiles(paths);
+
+  const report = [];
+  let changedCount = 0;
+  for (const file of files) {
+    const before = readFileSync(file, "utf-8");
+    const { changed, changes, text } = transform(before);
+    if (changes.length === 0) {
+      continue;
+    }
+    if (changed && write) {
+      writeFileSync(file, text, "utf-8");
+    }
+    if (changed) {
+      changedCount += 1;
+    }
+    report.push({ changes, file: path.relative(process.cwd(), file) });
+  }
+
+  if (asJson) {
+    process.stdout.write(
+      `${JSON.stringify({ files: report, wrote: write }, null, 2)}\n`
+    );
+    return;
+  }
+
+  for (const entry of report) {
+    process.stdout.write(`\n${entry.file}\n`);
+    for (const c of entry.changes) {
+      process.stdout.write(`  ${LABEL[c.kind] ?? c.kind}: ${c.detail}\n`);
+    }
+  }
+  const verb = write ? "changed" : "would change";
+  const hint = write ? "" : " Re-run with --write to apply.";
+  process.stdout.write(
+    `\n${report.length} file(s) with findings, ${changedCount} ${verb}.${hint}\n`
+  );
+};
+
+main();