blume 2.2.0 → 2.2.2

package/docs/discoverability/mcp.mdx

@@ -1,6 +1,6 @@
 ---
 title: MCP server
-description: Host a Model Context Protocol server so coding agents can search and read your docs directly — tools, resources, discovery documents, content-type and facet filters, and the server output it needs.
+description: Host a Model Context Protocol server so coding agents can search and read your docs directly — tools, resources, discovery documents, content-type and facet filters, the Connect to MCP menu, and the server output it needs.
 ---
 
 Host a [Model Context Protocol](https://modelcontextprotocol.io) server so coding agents (Claude Code, Cursor, VS Code, claude.ai connectors) can search and read your docs directly — no scraping. It's opt-in:
@@ -14,12 +14,13 @@ agents: {
 }
 ```
 
-| Option         | Default | Description                                       |
-| -------------- | ------- | ------------------------------------------------- |
-| `enabled`      | `false` | Generate and host the MCP server.                 |
-| `route`        | `/mcp`  | Path the Streamable-HTTP endpoint is mounted on.  |
-| `name`         | title   | Server name shown to clients (defaults to title). |
-| `instructions` | —       | Optional system hint passed to connecting agents. |
+| Option | Default | Description |
+| --- | --- | --- |
+| `enabled` | `false` | Generate and host the MCP server. |
+| `route` | `/mcp` | Path the Streamable-HTTP endpoint is mounted on. |
+| `name` | title | Server name shown to clients (defaults to title). |
+| `instructions` | — | Optional system hint passed to connecting agents. |
+| `clients` | `true` | Clients the **Connect to MCP** menu installs into. |
 
 If a content or custom page already owns the route, the server isn't generated: the build warns, and `llms.txt` and the other [discovery documents](/docs/discoverability/agent-discovery) leave it out.
 
@@ -27,7 +28,7 @@ If a content or custom page already owns the route, the server isn't generated:
 
 ## Tools and resources
 
-The server exposes read-only tools — `search_docs`, `get_page`, `list_pages`, and `get_navigation` — and every page as an MCP resource (`resources/list` enumerates the pages at their served URLs with a `text/markdown` type, leaving out i18n fallback copies of untranslated pages as `list_pages` does; `resources/read` returns the page's [agent Markdown](/docs/discoverability/markdown), the same output as `get_page`), so clients that attach context by URI can browse the docs without calling a tool. It publishes discovery documents at `/.well-known/mcp.json` and `/.well-known/mcp/server-card.json`. The server card follows the [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) Server Card extension schema (reverse-DNS `name`, `remotes` transport endpoints), with initialize-shaped compat fields (`serverInfo`, `capabilities`, `transports`) for scanners built against the proposal's earlier revision. Each page's **Connect to MCP** menu offers copy-and-go install for Claude Code, Cursor, VS Code, and Codex (shown once [`deployment.site`](/docs/deployment) is set).
+The server exposes read-only tools — `search_docs`, `get_page`, `list_pages`, and `get_navigation` — and every page as an MCP resource (`resources/list` enumerates the pages at their served URLs with a `text/markdown` type, leaving out i18n fallback copies of untranslated pages as `list_pages` does; `resources/read` returns the page's [agent Markdown](/docs/discoverability/markdown), the same output as `get_page`), so clients that attach context by URI can browse the docs without calling a tool. It publishes discovery documents at `/.well-known/mcp.json` and `/.well-known/mcp/server-card.json`. The server card follows the [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) Server Card extension schema (reverse-DNS `name`, `remotes` transport endpoints), with initialize-shaped compat fields (`serverInfo`, `capabilities`, `transports`) for scanners built against the proposal's earlier revision. Each page's **Connect to MCP** menu offers copy-and-go install for Claude Code, Cursor, VS Code, and Codex (shown once [`deployment.site`](/docs/deployment) is set), and you can [choose the clients](#connect-to-mcp-menu) it lists.
 
 `search_docs` runs its own full-text index, so it works regardless of your [search](/docs/configuration/search) provider — and even with `search: false`. The MCP server is a separate feature from on-page search.
 
@@ -55,6 +56,37 @@ Every `filters` entry must match (results carry their facet values, and `list_pa
 
 A value matches exactly, case included, as `list_pages` shows it: `"enforced"` doesn't match a page whose `status` is `Enforced`. Facet values are strings, so a number or boolean in `filters` matches its string form (`{"priority": 1}` finds `priority: 1`), and a value of any other shape, such as a list, is ignored rather than filtering.
 
+## Connect to MCP menu
+
+The **Connect to MCP** page action copies the server's URL, and then lists the clients it installs the server into: commands to copy for Claude Code and Codex, and install links for Cursor and VS Code. `clients` picks them. `true` (the default) lists every built-in client, `false` none, which leaves just **Copy server URL** in the menu, and a list shows the clients you name, in order, with a rule between the commands and the links.
+
+A client Blume doesn't ship is an object with a `label` and the `command` to copy. `{name}` in the command becomes the server's name as an id: `name`, or the site title, lowercased, with each run of characters other than `a`–`z` and `0`–`9` turned into a hyphen and the ends trimmed (`docs` if nothing is left). `{url}` becomes the server's URL. On a [multilingual](/docs/content/i18n#per-locale-navigation) site, the `label` can be a map of locale code to text. `icon` takes a [built-in icon](/docs/content/components#icon) name, image path/URL, or inline SVG, and defaults to `terminal`.
+
+```ts blume.config.ts lineNumbers
+agents: {
+  mcp: {
+    enabled: true,
+    clients: [
+      "claude-code",
+      "codex",
+      {
+        label: "Copy Copilot CLI command",
+        command: "copilot mcp add --transport http {name} {url}",
+      },
+      "cursor",
+      "vscode",
+    ],
+  },
+}
+```
+
+| Key           | Menu row                                             |
+| ------------- | ---------------------------------------------------- |
+| `claude-code` | Copies the `claude mcp add` command for Claude Code. |
+| `codex`       | Copies the `codex mcp add` command for Codex.        |
+| `cursor`      | Opens Cursor's MCP install link.                     |
+| `vscode`      | Opens VS Code's MCP install link.                    |
+
 ## Server output required
 
 The MCP server is a live endpoint (`/mcp`), so it can't run on a static build. Name a host adapter from `blume/deploy` to switch to server output:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "The open-source docs framework for humans and agents.",
   "keywords": [
     "agents",

package/skills/blume-migrate/SKILL.md

@@ -15,7 +15,7 @@ Throughout this skill (including the `references/` files), **`<skill>` means the
 
 - **Target idiomatic Blume, not a mechanical port.** Prefer filesystem-derived navigation over an exhaustive explicit `navigation.sidebar`. Prefer `:::` directives over JSX callouts. Prefer Blume defaults over restating them in config.
 - **Every field has a default; `{}` is a valid config.** Map only what the source _declares_. If the source uses a framework default, don't write it.
-- **Drop chrome that has no Blume equivalent — and say so.** Navbar CTAs, footer copyright text, custom theming, conditional redirects, and unmappable icons get reported to the user, not silently discarded or faked.
+- **Drop chrome that has no Blume equivalent — and say so.** Navbar CTAs, custom theming, conditional redirects, and unmappable icons get reported to the user, not silently discarded or faked.
 - **Convert, don't preserve.** Blume's page frontmatter schema is **strict** — unknown keys are build errors. A source-only frontmatter key must be mapped to a Blume key or removed (and reported), never left to "maybe validate."
 
 ## Migration workflow
@@ -190,7 +190,7 @@ A redirect whose `from` equals a page's route (a generated reference overview in
 
 1. Run **`blume build`** — it validates the frontmatter schema, duplicate routes, and config, and fails on any error diagnostic by default (**don't pass `--no-strict`**: that builds anyway and silently drops pages with invalid front matter or `.mdx` that doesn't parse). Then run **`blume validate --strict`** — links, heading anchors, assets, and redirect targets live here, not in `build` (add `--external` to also check outbound HTTP links). OpenAPI operation pages are real routes to `validate`, so dead links to them are caught too. Iterate until both are clean. Treat every warning `build` (or `blume check`) prints about another tool's syntax left in a page (`BLUME_TEMPLATE_TAG`, `BLUME_MDC_SYNTAX`, `BLUME_WIKILINK_UNSUPPORTED`, `BLUME_MD_*`, `BLUME_CODE_FENCE_OPTION`, `BLUME_MDX_*`, …) as a conversion you missed: each names the file and line and the Blume spelling, and `validate --strict` fails on them. `validate` reads links as the page renders them: a link definition shadowed by an earlier one with the same label isn't checked (it's dead text; delete it), and neither are links in comments. `validate --strict` also fails on OpenAPI spec warnings (`BLUME_OPENAPI_*`, such as an undeclared path parameter, a `localhost` server, or `nullable` in a 3.1 spec), which no content edit clears: fix them with an OpenAPI Overlay in the source's `overlays` so a generated or third-party spec stays untouched, and report them for a fix at the source; a `codeSamples` id Blume has no generator for (`BLUME_OPENAPI_UNKNOWN_CODE_SAMPLE`) is dropped from the config instead. **If you added redirects, run `blume audit --only redirects` after the build**: `validate` warns about a redirect whose `to` leads nowhere (`BLUME_BROKEN_REDIRECT`, at its line in `blume.config.ts`), but accepts a `to` that is another redirect's `from`, so only `audit` follows each one through the build and reports loops and chains. To check every old URL, request them against `blume dev` or `blume preview` (`curl -sL`; both apply every redirect, patterns included, with its status), or check them against `dist/` plus the redirect rules (`dist/blume-redirects.json` when no host adapter is set, else the host's `_redirects` or `vercel.json`). **Old heading anchors:** every source slugs heading ids differently from Blume. After the first build, run `node <skill>/scripts/pin-heading-ids.mjs --old <old site URL or its built-HTML dir>` (`--map dist/blume-redirects.json` when pages moved, built with no host adapter, `--write` to apply, `--only-linked` to pin only linked ids) and rebuild until it reports 0; on a server build it reads `dist/client` itself (skip it for ReadMe and a GitHub wiki: their heading ids already match Blume's, a ReadMe hub rate-limits a crawl, and the script can't read a wiki's pages); any `BLUME_BROKEN_ANCHOR` left was already dead on the old site, so retarget the obvious ones, drop the fragment from the rest, and report them.
 2. Run `blume dev` and review the site visually (`blume dev`/`preview --port N` move to the next free port when N is taken, so read the `Local http://…` line they print before requesting URLs) — nav structure, tabs, theme, rendered components.
-3. **Write a migration summary** covering: what was migrated (config, N pages, nav, API references), what was **dropped** (navbar CTAs, footer copyright text, custom theming, conditional redirects, unmappable icons, unsupported components), and suggested follow-ups (`blume eject` for full control, `blume add` to vendor a component for customization).
+3. **Write a migration summary** covering: what was migrated (config, N pages, nav, API references), what was **dropped** (navbar CTAs, custom theming, conditional redirects, unmappable icons, unsupported components), and suggested follow-ups (`blume eject` for full control, `blume add` to vendor a component for customization).
 
 ## Full documentation
 

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

@@ -26,7 +26,7 @@ Read `themeConfig`, `presets`, and `plugins`:
 | `url` + `baseUrl` | **`url` → `deployment.site`**, unless the target host is Vercel or Netlify, which Blume auto-detects (see SKILL.md — GitHub Pages, a common Docusaurus host, is not one of them); `baseUrl` (when not `/`) → `deployment: { base: "/…" }`, or the `base` option of a host adapter (`vercel({ base })`) when the site also needs one |
 | preset `docs.routeBasePath` — **including the default!** | Docusaurus serves docs at **`/docs/…` by default**; the "map only declared fields" rule does **not** apply here because the _URLs_ are load-bearing. Either keep them with top-level **`basePath: "/docs"`** (invisible to the sidebar), or intentionally move to root and emit a `redirects` entry per page. Decide explicitly and say which. (`routeBasePath: '/'` = docs-only mode — nothing to do.) |
 | preset `docs.editUrl` | `github` (owner/repo/branch; a path after the branch → `github.dir`; **an origin other than `https://github.com` → `github.host`** — a GitHub Enterprise repo's edit links and header mark point at the public site without it) |
-| `themeConfig.footer` | `footer.links`, one row of `{ label, href }`: every column's items flatten into it in order (an item's `to`, a route, is its `href`); column `title`s, `copyright`, `logo`, and `style` drop (report), or keep the whole footer as a Footer override (`defineComponents` layout slot) |
+| `themeConfig.footer` | `footer.links`, one row of `{ label, href }`: every column's items flatten into it in order (an item's `to`, a route, is its `href`); `copyright` (HTML) → `footer.copyright`, plain text: strip the tags, decode entities (`&copy;` → `©`), keep a `${new Date().getFullYear()}` template literal as written, and drop a "Built with Docusaurus." credit; a link inside it loses its URL (report, or add it to `footer.links`); a translated one in `i18n/<locale>/docusaurus-theme-classic/footer.json` → a locale map; column `title`s, `logo`, and `style` drop (report), or keep the whole footer as a Footer override (`defineComponents` layout slot) |
 | `themeConfig.announcementBar` | `banner` (`{ content, dismissible, id }` — `isCloseable` → `dismissible`; colors drop) |
 | `i18n.locales` / `defaultLocale` | `i18n` — translated files live at `i18n/<locale>/docusaurus-plugin-content-docs/current/…`; move them to `<locale>/…` under `content.root` |
 | `themeConfig.algolia` | drop — Blume ships built-in search (Orama); remove the Algolia dep. To keep the index, `search: algolia({ appId, apiKey, indexName })` from `blume/search` (the DocSearch `apiKey` is the search-only key) |
@@ -95,4 +95,4 @@ Remove `@docusaurus/*` and Algolia deps; delete `docusaurus.config.*`, `sidebars
 
 ## Dropped — report these
 
-Custom/swizzled theme components (layout slots or `blume eject`), the footer's copyright, logo, and HTML items, the blog's generated tag, author, and archive pages, Algolia config, `sidebar_custom_props` and the other dropped frontmatter keys, `createRedirects` functions (→ host rules), React pages under `src/pages/`, `<TOCInline>`, per-category `className`/`customProps`, and any `@theme/*` component with no Blume equivalent.
+Custom/swizzled theme components (layout slots or `blume eject`), the footer's logo and HTML items (and any link inside its copyright), the blog's generated tag, author, and archive pages, Algolia config, `sidebar_custom_props` and the other dropped frontmatter keys, `createRedirects` functions (→ host rules), React pages under `src/pages/`, `<TOCInline>`, per-category `className`/`customProps`, and any `@theme/*` component with no Blume equivalent.

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

@@ -35,7 +35,7 @@ Map what step 3 found or the user supplies; leave the rest at Blume's defaults.
 | Theme style, tint and semantic colors, corner, depth, link, and sidebar styles | drop (report); a root `theme.css` if one matters |
 | Header links; a button-styled one | `navigation.actions`; `navigation.cta` |
 | Announcement | `banner` (`{ content, link, dismissible, id }`) |
-| Footer | `footer.links`, flattened into one row; group titles, logo, and copyright drop (report) |
+| Footer | `footer.links`, flattened into one row; copyright → `footer.copyright`; group titles and logo drop (report) |
 | Social accounts | `footer.socials` |
 | Social preview image | `seo.image` on the landing page (Blume renders a card for every other page) |
 | Git Sync repository and branch | `github: { owner, repo, branch }`, plus `dir` or `host` when needed; GitLab has no equivalent (report) |
@@ -264,4 +264,4 @@ The old `gitbook-cli` toolchain and its fork HonKit:
 
 ## Dropped — report these
 
-Site themes and styles beyond accent, fonts, and mode; footer group titles, logo, and copyright; page covers; page and update tags; adaptive content and visitor authentication; GitBook Assistant unless the user adds `ai.assistant`; hint icons you didn't keep; button styles and search/ask buttons; `<mark>` colors; `fullWidth` and column widths; non-YouTube embeds as players; dark card covers and theme-aware images; inline image sizing; `{% openapi-schemas %}` and GitBook `x-*` spec extensions; automatic redirects you couldn't recover; case-insensitive URLs; page-group icons; sidebar positions Blume can't match (parent pages among loose pages, `***` dividers, external links); section groups flattened into tabs; spaces and translations not in the repo; integrations with no adapter; site redirects nobody could export; anything set only in the app that the user didn't supply.
+Site themes and styles beyond accent, fonts, and mode; footer group titles and logo; page covers; page and update tags; adaptive content and visitor authentication; GitBook Assistant unless the user adds `ai.assistant`; hint icons you didn't keep; button styles and search/ask buttons; `<mark>` colors; `fullWidth` and column widths; non-YouTube embeds as players; dark card covers and theme-aware images; inline image sizing; `{% openapi-schemas %}` and GitBook `x-*` spec extensions; automatic redirects you couldn't recover; case-insensitive URLs; page-group icons; sidebar positions Blume can't match (parent pages among loose pages, `***` dividers, external links); section groups flattened into tabs; spaces and translations not in the repo; integrations with no adapter; site redirects nobody could export; anything set only in the app that the user didn't supply.

package/skills/blume-migrate/references/github-wiki.md

@@ -86,7 +86,7 @@ Wikis have no config: map what the repository and the special pages say.
 | An image at the top of `_Sidebar.md` | `logo`, with the file in `public/` |
 | External links in `_Sidebar.md` | `navigation.featured`: `convert` prints the array |
 | `_Footer.md` links | `footer.links` |
-| `_Footer.md` text | drop (report), or a `PageFooter` layout slot (`defineComponents`). A "contribute to this wiki" footer drops with its link: edit links replace it |
+| `_Footer.md` text | a copyright or license line → `footer.copyright`, as plain text (Markdown stripped); other text → drop (report), or a `PageFooter` layout slot (`defineComponents`). A "contribute to this wiki" footer drops with its link: edit links replace it |
 | "edited this page … · N revisions" under each title | drop (report). `lastModified: "git"` would show the migration date on every converted page |
 | Wiki search, the Pages list, the per-page outline, the clone URL box | built in, or drop |
 | Site URL | none existed. Ask where the site deploys and set `deployment` (SKILL.md). GitHub Pages: https://useblume.dev/guides/markdown-docs-github-pages, with `deployment: { site: "https://<owner>.github.io", base: "/<repo>" }` for a project site |
@@ -256,4 +256,4 @@ An alert left in a `.md` page warns `BLUME_MD_GITHUB_ALERT`, and an unknown fenc
 
 ## Dropped — report these
 
-The Pages list and the clone box; footer text and its link; sidebar prose, images, anchor links, and duplicate entries; external sidebar links moved to `navigation.featured`; the per-page "edited … · N revisions" line; image sizes and wiki image options; images that were broken on GitHub; maps and 3D models; theme-aware image pairs; raw HTML GitHub had stripped; links to missing pages (GitHub's create-page links) and links that were already broken; shadowed link definitions; pages left out (mirror files, tests, fixtures, deprecated stubs) and moved notices mapped to their targets; pages GitHub never served (same-name shadows); non-Markdown pages converted with pandoc; wiki-UI links (history, revisions, `_pages`); and every old URL, which stays on github.com: say what you prepared for it (notice, stubs, or neither), which sync workflows must stop first, and that nothing redirects.
+The Pages list and the clone box; footer text other than a copyright line, and its link; sidebar prose, images, anchor links, and duplicate entries; external sidebar links moved to `navigation.featured`; the per-page "edited … · N revisions" line; image sizes and wiki image options; images that were broken on GitHub; maps and 3D models; theme-aware image pairs; raw HTML GitHub had stripped; links to missing pages (GitHub's create-page links) and links that were already broken; shadowed link definitions; pages left out (mirror files, tests, fixtures, deprecated stubs) and moved notices mapped to their targets; pages GitHub never served (same-name shadows); non-Markdown pages converted with pandoc; wiki-UI links (history, revisions, `_pages`); and every old URL, which stays on github.com: say what you prepared for it (notice, stubs, or neither), which sync workflows must stop first, and that nothing redirects.

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

@@ -102,7 +102,7 @@ Apply `defaults:` (front matter defaults) to the pages in each `scope.path` that
 | `ga_tracking` | `googleAnalytics({ id })` from `blume/analytics`, one per `G-` id in the comma list. A `UA-` id no longer collects data: report it |
 | `gh_edit_link` + `gh_edit_repository` + `gh_edit_branch` | `github: { owner, repo, branch }`. `gh_edit_source: docs` → `github.dir: "docs"` when `blume.config.ts` sits there |
 | `last_edit_timestamp` | `lastModified: "frontmatter"` when pages set `last_modified_date` (the codemod maps it), else drop: JTD showed no date without it |
-| `footer_content` / `_includes/footer_custom.html` | links → `footer.links`, social links → `footer.socials`; copyright text → drop (report) or a `Footer` layout slot (`defineComponents`) |
+| `footer_content` / `_includes/footer_custom.html` | links → `footer.links`, social links → `footer.socials`; copyright text → `footer.copyright`, plain text: strip the tags, decode entities (`©` → `©`), and turn a Liquid year (`{{ "now" \| date: "%Y" }}`) into `${new Date().getFullYear()}` in a template literal; other text → drop (report) or a `Footer` layout slot (`defineComponents`) |
 | `callouts`, `heading_anchors`, `enable_copy_code_button`, `back_to_top*`, `nav_sort`, `nav_error_report`, `ga_tracking_anonymize_ip`, `gh_edit_link_text`, `gh_edit_view_mode` | drop (the codemod read `callouts`) |
 
 ## Navigation: front matter → folders and `meta.ts`
@@ -250,4 +250,4 @@ grep -rnE '\{:[ .#a-z:]|\{%|\{\{|^\*\[|^: |markdown="|<i class="fa|\.html[)#"]|\
 
 ## Dropped — report these
 
-Callout title labels that only named the type, unconfigured or malformed callout IALs left plain, the button and label styling the codemod dropped, `nav_external_links` moved above the sidebar, `back_to_top`, `footer_content`/copyright text, theme hooks, custom color schemes beyond the accent, `_sass` rules with no Blume target, content a CSS rule hid, site-wide code line numbers, deeper TOC levels, `UA-` analytics ids, `sitemap: false`, abbreviations, definition-list styling, Liquid logic and `_data` loops now frozen as content, embed widths, page scripts and widgets (sliders, accordions) not rebuilt, icon-font icons with no Lucide match, accidentally published files (`LICENSE`, `.bat`), and every plugin removed without an equivalent.
+Callout title labels that only named the type, unconfigured or malformed callout IALs left plain, the button and label styling the codemod dropped, `nav_external_links` moved above the sidebar, `back_to_top`, other `footer_content` text and links inside the copyright, theme hooks, custom color schemes beyond the accent, `_sass` rules with no Blume target, content a CSS rule hid, site-wide code line numbers, deeper TOC levels, `UA-` analytics ids, `sitemap: false`, abbreviations, definition-list styling, Liquid logic and `_data` loops now frozen as content, embed widths, page scripts and widgets (sliders, accordions) not rebuilt, icon-font icons with no Lucide match, accidentally published files (`LICENSE`, `.bat`), and every plugin removed without an equivalent.

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

@@ -53,7 +53,7 @@ Map only what's set:
 | `edit_uri` / `edit_uri_template` | **`github.branch`** from the segment after `edit/` or `blob/`. Unset with a GitHub `repo_url` means `edit/master/docs/` → `branch: "master"` (Blume defaults to `main`). The path after the branch is `docs_dir`, which Blume adds — **not** `github.dir` (that's only for a project in a repo subfolder). `edit_uri: ""`, or Material without the `content.action.edit` feature, shows no edit button; Blume has no separate switch, so accept edit links or leave `github` unset and set `navigation.repo: "<repo_url>"` (a footer mark) — say which. Leave `github` unset if edit links would point at gitignored generated files |
 | `repo_url` elsewhere (GitLab…) | no edit links; a header link → `navigation.actions` (report) |
 | `repo_name`, `site_author`, `site_dir`, `dev_addr`, `remote_*`, `watch`, `strict`, `validation` | drop |
-| `copyright` | drop (report), or a Footer layout slot (`defineComponents`) |
+| `copyright` | `footer.copyright`, plain text: strip any HTML tags, decode entities (`&copy;` → `©`); a link inside it loses its URL (report, or add it to `footer.links`) |
 | `exclude_docs` | `content.exclude` — the list adds to the default `"**/_*"` and `"**/.*"`; `"!**/_*"` publishes `_` files |
 | `draft_docs` / `not_in_nav` | `draft: true` / `sidebar.hidden: true` on those pages |
 | `extra_css` | a project-root **`theme.css`**: Material's `--md-*` variables and `.md-*` classes don't exist — port only rules that still mean something, and read colors out of it (Theme) |
@@ -233,4 +233,4 @@ grep -rnE '^\s*(!!!|\?\?\?\+?|===[+!]*) |^\s*/{3,} ?[a-z]|--8<--|\{ *[.#:][^}]*\
 
 ## Dropped — report these
 
-Template overrides and hooks with no slot equivalent, `copyright`, code annotations, admonition title bars and collapsible callout colors, `inline` admonition placement, `palette.accent`, unmapped and brand icons, abbreviation tooltips, definition-list styling, snippet line ranges and sections (split into files), tag index pages, blog archive/category/pagination pages, anchor-level redirects without the script, cross-page tab memory, git committers, mkdocstrings/click/gen-files/notebook output not carried over, macro functions and Jinja logic, social platforms `footer.socials` lacks, a `linenums` start offset, image sizing from attribute lists, and every plugin you removed without an equivalent.
+Template overrides and hooks with no slot equivalent, links inside `copyright`, code annotations, admonition title bars and collapsible callout colors, `inline` admonition placement, `palette.accent`, unmapped and brand icons, abbreviation tooltips, definition-list styling, snippet line ranges and sections (split into files), tag index pages, blog archive/category/pagination pages, anchor-level redirects without the script, cross-page tab memory, git committers, mkdocstrings/click/gen-files/notebook output not carried over, macro functions and Jinja logic, social platforms `footer.socials` lacks, a `linenums` start offset, image sizing from attribute lists, and every plugin you removed without an equivalent.

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

@@ -15,8 +15,8 @@ Nextra (on Next.js) declares navigation and per-page labels in `_meta` files —
 
 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 footer's repo link); `docsRepositoryBase` → `github` (owner/repo/branch — and any trailing sub-path → `github.dir`; if its origin is not `https://github.com`, set `github.host` to that origin — with `host` omitted, Blume builds the repository and edit links against public GitHub); `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).
+- **v2/v3 — `theme.config.*`:** `logo` (JSX — extract text/image) → `logo`; `project.link` → `github` (renders the footer's repo link); `docsRepositoryBase` → `github` (owner/repo/branch — and any trailing sub-path → `github.dir`; if its origin is not `https://github.com`, set `github.host` to that origin — with `host` omitted, Blume builds the repository and edit links against public GitHub); `banner.text`/`banner.key` → `banner.content`/`banner.id` (`dismissible` maps); `primaryHue`/`primarySaturation` → pick an equivalent `theme.accent` color; `footer.text` (v2) / `footer.content` (v3) → `footer.copyright` when it's a copyright line: reduce the JSX to plain text, and a `{new Date().getFullYear()}` becomes `${new Date().getFullYear()}` in a template literal; anything else in it → 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>` (its children are v3's `footer.content`). 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 and `:param`/`:path*` patterns become Blume `redirects: [{ from, to }]` as written (`permanent: true` → `status: 308`, `false` → `307`); ones with regex params (`:slug(\d+)`) or `has`/`missing` conditions 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**.
 
@@ -76,4 +76,4 @@ Repoint `dev`/`build`/`start` scripts to the Blume CLI; remove `next`/`nextra`/`
 
 ## Dropped — report these
 
-Footer content; `primaryHue`-style theming beyond an accent color; `faviconGlyph`; `_meta` separators, menus, `newWindow`; per-page `theme` switches (and `layout: "full"` approximated as `mode: wide`); root-level pages `_meta` ordered after a folder; `<Bleed>`; MathJax macros; word-highlight/copy fence meta; any icon you can't reconstruct as a Lucide name.
+Footer content other than a copyright line; `primaryHue`-style theming beyond an accent color; `faviconGlyph`; `_meta` separators, menus, `newWindow`; per-page `theme` switches (and `layout: "full"` approximated as `mode: wide`); root-level pages `_meta` ordered after a folder; `<Bleed>`; MathJax macros; word-highlight/copy fence meta; any icon you can't reconstruct as a Lucide name.

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

@@ -66,7 +66,7 @@ There's no config file in Git. Every page of a Refactored hub embeds the project
 | `integrations.intercom`, `zendesk` (a support widget readers click) | a `PageFooter` component (`defineComponents`, SKILL.md "analytics") that loads it | not `analytics`, which can hold it until consent. Check region settings (an AU Intercom workspace needs `api_base`) |
 | `integrations.google.site_verification`, `<meta>` tags in head HTML | `seo.metatags` | other head HTML: report |
 | `stylesheet_hub2` (custom CSS) | a root `theme.css` | rules for ReadMe's classes (`.rm-*`, `.callout_*`, hashed names) match nothing: carry only rules for the site's own markup |
-| Footer HTML | `footer: { links }` | report the rest |
+| Footer HTML | `footer: { copyright, links }` | a copyright line → `copyright`, plain text: strip the tags, decode entities (`&copy;` → `©`). Report the rest |
 | `variables.defaults` | `variables` | Content. **Defaults can be real credentials** (an API key): never copy one into config |
 | `glossaryTerms` | `--glossary hub.html` | the codemod writes `<Tooltip>`s |
 | `redirects` | `redirects` | URLs and redirects |

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

@@ -36,7 +36,7 @@ Resolve `$ref`s first (`redirects: { $ref: ./redirects.yaml }` is common). Produ
 | `logo.image` / `logo.srcSet` (`"./l.svg light, ./d.svg dark"`), `altText`, `link` | `logo` / `logo: { image: { light, dark, alt }, href }` | move the files into `public/`; a wordmark also gets `text: ""` |
 | `logo.favicon` | **drop the field**: copy the file to `favicon.<ext>` or `icon.<ext>` in the root or `public/` | detected by filename, for `.svg`, `.png`, and `.ico` only: convert any other format |
 | `navbar.items` | `navigation.tabs` / `actions` / `cta` | see Navigation |
-| `footer.items` (columns, each a `{ group, items }` or a single item) | `footer.links` (one row) + `footer.socials` | flatten every column's items in order (`page` → its route). Links to a platform in Blume's `footer.socials` list (`docs/configuration/index.mdx`) become socials; a podcast (Spotify, Apple Podcasts) is `podcast`; others (TikTok) stay links. Column labels and `copyrightText` drop (report) |
+| `footer.items` (columns, each a `{ group, items }` or a single item) | `footer.links` (one row) + `footer.socials` | flatten every column's items in order (`page` → its route). Links to a platform in Blume's `footer.socials` list (`docs/configuration/index.mdx`) become socials; a podcast (Spotify, Apple Podcasts) is `podcast`; others (TikTok) stay links. `copyrightText` → `footer.copyright`. Column labels drop (report) |
 | `redirects` (`'/from': { to, type }`) | `redirects: [{ from, to, status: type }]` | write `from` without a trailing slash; a trailing `/*` carries over as written (`{ from: "/a/*", to: "/b/*" }`), and also matches the bare `/a`. Blume takes 301/302/307/308 only |
 | `markdown.toc` | `toc: { maxHeadingLevel: <depth> }`, or `toc: false` for `hide` | Realm's default depth 3 is Blume's default |
 | `markdown.lastUpdatedBlock` | `lastModified: "git"`, **only when declared** and not `hide: true` | Realm shows "Last updated" by default; if the source left it at that, offer `lastModified: "git"` in the report. Either way, every page the migration edits (nearly all of them, since each H1 moves) shows the migration commit's date; a rename alone keeps the page's date. Say so |
@@ -195,4 +195,4 @@ Realm icons are Font Awesome names (`book`, `solid check-circle`, `brands github
 
 ## Dropped — report these
 
-Login, RBAC, and SSO (every protected path); Reunite's editor, reviews, previews, and feedback dashboard; the API explorer's mock server, environments, saved auth, and default CORS proxy (and which APIs now fail CORS); `x-tagGroups` names and the tags they hid; API tag and `section/` pages (redirected); sidebar separators and `expanded: always`; footer column labels and copyright; the ` - <title>` suffix now on every `<title>`; dropped frontmatter titles; `seo.image`/`jsonLd` and `llms.txt` sections; extra banners; search facets; resolved `if` branches and per-reader content; `code-snippet` ranges; the Markdoc tags with no equivalent; PlantUML/Excalidraw; light/dark image pairs; unmatched icons; ejected components and Realm CSS; a `UA-` analytics id; scripts that now load only in production; trailing-slash URLs; the accidental pages left out; reset "last updated" dates.
+Login, RBAC, and SSO (every protected path); Reunite's editor, reviews, previews, and feedback dashboard; the API explorer's mock server, environments, saved auth, and default CORS proxy (and which APIs now fail CORS); `x-tagGroups` names and the tags they hid; API tag and `section/` pages (redirected); sidebar separators and `expanded: always`; footer column labels; the ` - <title>` suffix now on every `<title>`; dropped frontmatter titles; `seo.image`/`jsonLd` and `llms.txt` sections; extra banners; search facets; resolved `if` branches and per-reader content; `code-snippet` ranges; the Markdoc tags with no equivalent; PlantUML/Excalidraw; light/dark image pairs; unmatched icons; ejected components and Realm CSS; a `UA-` analytics id; scripts that now load only in production; trailing-slash URLs; the accidental pages left out; reset "last updated" dates.

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

@@ -69,7 +69,7 @@ Read the whole module and the helpers it imports (sidebars, nav, per-locale conf
 | `siteTitle: false` / a string | `logo: { image: …, text: "" }` / `logo.text` |
 | `nav`, `sidebar` | see the Navigation sections |
 | `socialLinks` | GitHub → `github: { owner, repo }` (it renders in the footer); known platforms → `footer.socials` (`twitter` → `x`; list under `footer` in `docs/configuration/index.mdx`); others, including custom `{ svg }` icons → `footer.links`, or drop (report) |
-| `footer` (`message`, `copyright`) | drop (report); `footer.links` takes `{ label, href }` |
+| `footer` (`message`, `copyright`) | `copyright` → `footer.copyright`, plain text: strip the tags, decode entities (`©` → `©`); a link inside it loses its URL (report, or add it to `footer.links`); a per-locale `copyright` → a locale map. `message` → drop (report); `footer.links` takes `{ label, href }` |
 | `editLink.pattern` (`…/edit/<branch>/<path>/:path`) | `github: { owner, repo, branch }`. `<path>` leads to the **srcDir**, but Blume builds edit links from the Blume project dir, so `github.dir` is `<path>` minus `content.root` (omit when empty). A non-`github.com` origin → `github.host` |
 | `lastUpdated.formatOptions` | its date fields → `dateFormat`; `text` → drop |
 | `search` | `local` → omit. **Algolia → omit `search`** (Blume's built-in Orama), remove the DocSearch deps, and report the `appId`/`indexName`. That index is almost always DocSearch's, filled by Algolia's crawler, and Blume's sync, given an admin key, replaces the whole index on every build: never point `algolia()` at it. `search: algolia({ appId, apiKey, indexName })` from `blume/search` is for a new index Blume owns, a separate opt-in |
@@ -201,4 +201,4 @@ The old URL list is `<old build>/**/*.html` (or the live `sitemap.xml`). Blume s
 
 ## Dropped — report these
 
-`titleTemplate`, footer text, forced `appearance`, per-page `outline`/`aside`, one-sided `prev`/`next`, page-level toggles (`editLink`, `footer`, `navbar`, `pageClass`), `head` entries beyond meta tags and analytics, build hooks, Vite and custom markdown-it plugins, unsupported social links, line-number offsets and the site-wide switch, snippet regions and include ranges (now split files), copied out-of-root snippets, data-driven and unregistered theme components (and any content they hid), `VPTeamMembers`, data loaders and dynamic routes, hero styling, the DocSearch index (with its credentials), old-site anchors that were already broken (and any left unpinned under `--only-linked`), version-dropdown links, and `::: note`/`important`/`caution` text that 1.x showed literally.
+`titleTemplate`, the footer `message` (and any link inside `copyright`), forced `appearance`, per-page `outline`/`aside`, one-sided `prev`/`next`, page-level toggles (`editLink`, `footer`, `navbar`, `pageClass`), `head` entries beyond meta tags and analytics, build hooks, Vite and custom markdown-it plugins, unsupported social links, line-number offsets and the site-wide switch, snippet regions and include ranges (now split files), copied out-of-root snippets, data-driven and unregistered theme components (and any content they hid), `VPTeamMembers`, data loaders and dynamic routes, hero styling, the DocSearch index (with its credentials), old-site anchors that were already broken (and any left unpinned under `--only-linked`), version-dropdown links, and `::: note`/`important`/`caution` text that 1.x showed literally.

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

@@ -170,7 +170,7 @@ Rebuild it as in vitepress.md § "Home page (`layout: home`)": `index.mdx` with
 - v1: `heroImage`, `heroAlt`, `heroText` (it defaults to the site title, and `null` hides it), `tagline` (it defaults to the site description, and `null` hides it), `actionText` + `actionLink` (one button), `features: [{ title, details }]`, and `footer`. **v2:** `actions: [{ text, link, type }]` replaces the single action, and adds `heroImageDark`, `heroHeight`, and `footerHtml` (which renders `footer` as HTML).
 - `mode: custom` is full-bleed with no padding, so a hero image renders huge and flush left. Wrap the hero in a centered block (`<div style={{ maxWidth: "60rem", margin: "0 auto", padding: "3rem 1.5rem 0", textAlign: "center" }}>`, with blank lines inside so the Markdown renders) and cap the image (`style={{ maxHeight: "280px", margin: "0 auto" }}`). Add `sidebar.hidden: true` so the home page isn't a sidebar row.
 - Features have no icon or link: each becomes a `<Card title>` with `details` as the body, in a `<CardGroup cols={3}>`. Features written as raw HTML in the body (`<div class="features">`) map the same way.
-- `footer`, `footerHtml`, or a `::: slot footer` → drop (report), or move its links into `footer.links`. `heroImageDark` → Blume has no light/dark pair for a content image, so keep one (report).
+- `footer` (HTML with **v2** `footerHtml: true`) or a `::: slot footer` is usually a copyright or license line ("MIT Licensed | Copyright © 2018-present …") → `footer.copyright`, plain text: strip the tags, decode entities (`&copy;` → `©`); move its links into `footer.links`, or they lose their URLs (report). A translated home page's `footer` → that locale's entry in a locale map. Other footer content → drop (report). `heroImageDark` → Blume has no light/dark pair for a content image, so keep one (report).
 
 ## Frontmatter
 

package/skills/blume-migrate/scripts/github-wiki-codemod.mjs

@@ -2323,7 +2323,7 @@ const siteNotes = (root, files, sidebarFile, layout) => {
       .split("\n")
       .slice(0, MAX_NOTICE_LINES);
     notes.push(
-      `${footer}: ${text.join(" / ")} (links → footer.links; a "contribute to this wiki" footer drops with its link)`
+      `${footer}: ${text.join(" / ")} (links → footer.links; a copyright line → footer.copyright; a "contribute to this wiki" footer drops with its link)`
     );
   }
   return notes;

package/src/astro/generate.ts

@@ -73,6 +73,7 @@ import { resolveFallbackLocale } from "../core/i18n.ts";
 import { buildIncludeGraph } from "../core/includes.ts";
 import { resolveLocalizable } from "../core/localizable.ts";
 import {
+  validateMcpClientIcons,
   validateNavTargets,
   validateSearchPopularIcons,
 } from "../core/nav-diagnostics.ts";
@@ -1028,7 +1029,9 @@ const resolveFooter = (
 ): ResolvedConfig["footer"] | null => {
   const { footer } = config;
   return footer &&
-    (footer.links.length > 0 || Object.keys(footer.socials).length > 0)
+    (footer.copyright !== undefined ||
+      footer.links.length > 0 ||
+      Object.keys(footer.socials).length > 0)
     ? footer
     : null;
 };
@@ -1273,6 +1276,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       logo,
       mcp: config.agents.mcp.enabled
         ? {
+            clients: config.agents.mcp.clients,
             name: config.agents.mcp.name ?? config.title,
             route: config.agents.mcp.route,
           }
@@ -2437,10 +2441,10 @@ export const generateRuntime = async (
 
   // Missing-navigation-target check, now that every servable route is known
   // (see `navTargetRoutes`).
-  // Curated `search.popular` icons live outside the navigation model, so they
-  // miss `validateNavIcons` in the graph build — they're checked here too,
-  // where the search config is known. A typo otherwise just renders the
-  // default glyph.
+  // Curated `search.popular` icons and custom MCP clients' icons live outside
+  // the navigation model, so they miss `validateNavIcons` in the graph build —
+  // they're checked here too, where their config is known. A typo otherwise
+  // just renders the default glyph, or no icon at all.
   warnings.push(
     ...[
       ...validateNavTargets(
@@ -2449,6 +2453,12 @@ export const generateRuntime = async (
         servedFiles(project)
       ),
       ...validateSearchPopularIcons(config.search.popular),
+      ...(config.agents.mcp.enabled
+        ? validateMcpClientIcons(
+            config.agents.mcp.clients,
+            config.i18n?.defaultLocale
+          )
+        : []),
     ].map(diagnosticWarning)
   );
 

package/src/astro/templates.ts

@@ -1244,9 +1244,9 @@ interface RateLimitTemplate {
  * `rateLimit` for one server route: a limiter built at module scope from the
  * configured adapter, checked against every request, keyed by the reader's
  * address and `scope` so each route keeps its own budget (see
- * `ratelimit/runtime.ts`). Upstash reads its secrets through `getSecret`;
- * Cloudflare's binding comes from the Worker's env. Nothing at all when
- * rate limiting is off.
+ * `ratelimit/runtime.ts`). An adapter that names secrets reads them through
+ * `getSecret`; Cloudflare's binding comes from the Worker's env. Nothing at
+ * all when rate limiting is off.
  */
 export const rateLimitTemplate = (
   adapter: RateLimitAdapter | null | undefined,
@@ -1259,7 +1259,7 @@ export const rateLimitTemplate = (
     'import { createLimiter, rateLimited } from "blume/ratelimit/runtime.ts";',
   ];
   let runtime = "";
-  if (adapter.kind === "upstash") {
+  if (adapter.requiredSecrets.length > 0) {
     imports.push('import { getSecret } from "astro:env/server";');
     runtime = ", { secret: getSecret }";
   } else if (adapter.kind === "cloudflare") {

package/src/cli/required-secrets.ts

@@ -45,7 +45,6 @@ const adapterSecretOwners = (config: ResolvedConfig): SecretOwner[] => {
       secrets: consent.requiredSecrets,
     });
   }
-  // Upstash's endpoint and token.
   if (rateLimit) {
     owners.push({
       feature: `Rate limiting (${rateLimit.kind})`,