blume 0.5.3 → 0.5.4

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

@@ -162,22 +162,16 @@ export interface NavSelectorItem {
     icon?: string;
     tag?: string;
 }
-/** Top-level Mintlify-style partition selectors. */
+/** Top-level partition selectors (products, versions, languages). */
 export interface NavSelector {
     label: string;
     kind: "dropdown" | "language" | "product" | "version";
     items: NavSelectorItem[];
 }
-/** Chrome overrides used when the current route belongs to a nav partition. */
-export interface NavChromeVariant {
-    path: string;
-    banner?: ResolvedConfig["banner"];
-}
 /** The complete navigation model derived from the content graph. */
 export interface Navigation {
     tabs: NavTab[];
     selectors: NavSelector[];
-    chromeVariants: NavChromeVariant[];
     sidebar: NavNode[];
     /** Repo URL for the header link, or null when hidden (`navigation.repo`). */
     repoUrl?: string | null;

package/docs/advanced/meta.ts

@@ -2,13 +2,6 @@ import { defineMeta } from "blume";
 
 export default defineMeta({
   order: 5,
-  pages: [
-    "migrate",
-    "bridge",
-    "custom-pages",
-    "changelog",
-    "blog",
-    "api-reference",
-  ],
+  pages: ["skills", "custom-pages", "changelog", "blog", "api-reference"],
   title: "Advanced",
 });

package/docs/advanced/skills.mdx

@@ -0,0 +1,28 @@
+---
+title: Skills
+description: The agent skills Blume ships — playbooks that teach a coding agent to build and maintain a Blume docs site.
+---
+
+Blume ships [agent skills](https://docs.claude.com/en/docs/claude-code/skills) — playbooks that teach a coding agent (Claude Code, Codex, Cursor) how to do a Blume-shaped job without you explaining it. They live on GitHub in the repo's `skills/` folder and are bundled in the package at `node_modules/blume/skills/` once Blume is installed, so any agent can be pointed at a `SKILL.md` directly.
+
+## Blume
+
+The core skill. It teaches the agent what Blume is and how to scaffold, write, and configure a site — filesystem-derived navigation, the config schema, content components — and points it at the full docs bundled in the installed package (`node_modules/blume/docs`). Install it in any project where an agent helps you build your docs:
+
+```bash
+npx skills add haydenbleasel/blume
+```
+
+## Self-updating docs
+
+`blume-update-docs` keeps your docs in sync with the product they document. On each run — typically from a schedule you configure in your agent runner — it audits recently merged PRs, changelogs, config schemas, and CLI help against the docs content, updates only pages that are factually stale (feature-flagged work is ignored), verifies with `blume build`, and opens or updates a `blume/*` pull request. If nothing drifted, it reports a clean no-op instead of opening a noisy PR.
+
+```bash
+npx skills use haydenbleasel/blume@blume-update-docs
+```
+
+Blume doesn't host the automation — wire the skill into a scheduled task in Claude Code, a Codex or Cursor automation, or plain cron, with permission to read repo history and open PRs. A typical weekly prompt:
+
+```text
+Use the blume-update-docs skill. Review the PRs merged within the last 7 days and compare them to the docs content. Ignore work behind feature flags. If docs need updates, make them, verify the docs build, and open a blume/* PR. If not, report what you checked and do not open a PR.
+```

package/docs/configuration/ai.mdx

@@ -184,3 +184,5 @@ npx skills add haydenbleasel/blume
 ```
 
 The skill teaches the agent what Blume is and how to scaffold, write, and configure a site, and points it at the full docs bundled in the installed package (`node_modules/blume/docs`).
+
+It's one of the [agent skills Blume ships](/docs/advanced/skills), alongside skills for migrating an existing docs site to Blume and keeping docs in sync with your product from a scheduled agent run.

package/docs/configuration/index.mdx

@@ -91,7 +91,7 @@ export default defineConfig({
 | --- | --- | --- |
 | `title` | `"Documentation"` | Site name — shown in the header, page titles, OG cards. |
 | `description` | — | Default meta description, used for SEO and OG. |
-| `logo` | — | Brand logo shown beside the title in the header. |
+| `logo` | — | Brand mark and/or wordmark shown in the header. |
 | `banner` | — | Site-wide announcement bar above the header. |
 
 ### Logo
@@ -102,18 +102,23 @@ Point `logo` at an SVG and Blume inlines it, so a `currentColor` logo follows th
 logo: "/logo.svg",
 ```
 
-The SVG can live at your project root or in `public/`. For raster images — or separate light and dark artwork — use the object form (these must live in `public/`):
+The SVG can live at your project root or in `public/`. The brand is a mark (`image`) plus a wordmark (`text`); the object form lets you set them independently:
 
 ```ts blume.config.ts lineNumbers
 logo: {
-  light: "/logo-light.png",
-  dark: "/logo-dark.png",
-  alt: "Acme",
-  href: "/",
+  image: "/logo.svg", // string, or { light, dark, alt } for themed raster art
+  text: "Acme",       // wordmark beside the mark
+  href: "/",          // overrides the brand link (defaults to "/")
 },
 ```
 
-`href` overrides the logo's link (it defaults to `/`).
+`image` takes the same value as the shorthand — a single path, or `{ light, dark, alt }` for separate light/dark artwork (raster images must live in `public/`).
+
+`text` controls the wordmark independently of the mark:
+
+- **Omit `text`** and the brand uses your site `title` (the default).
+- **Set `text: ""`** to show the mark alone — handy when the logo image already includes the wordmark.
+- **Set `text` with no `image`** for a text-only logo.
 
 ### Favicon
 
@@ -177,17 +182,8 @@ content: {
 | `exclude` | `["**/_*", "**/.*"]` | Globs to ignore (underscore- and dot-files). |
 | `pages` | `"pages"` | Folder for custom `.astro` pages. |
 | `defaultType` | `"doc"` | Page `type` used when frontmatter omits it. |
-| `assets` | `[]` | Extra top-level directories served at the site root, alongside `public/`. |
-
-Assets normally live in `public/` — a file at `public/logo.png` is served at `/logo.png`. Use `assets` to serve additional root-level folders in place instead of moving them under `public/`. Each entry is a directory relative to your project root, served at the matching URL and copied into `dist/` on build:
-
-```ts blume.config.ts
-content: {
-  assets: ["images"], // /images/create.png → images/create.png
-}
-```
 
-This is mainly useful after [migrating](/docs/advanced/migrate) from a tool that serves assets from the project root (like Mintlify), so references such as `![](/images/create.png)` keep resolving without relocating every file. [Bridge mode](/docs/advanced/bridge) uses the same mechanism to serve a Mintlify project's assets in place, untouched.
+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`.
 
 ## Last modified
 

package/docs/configuration/theming.mdx

@@ -112,17 +112,9 @@ theme: {
 }
 ```
 
-### Background decoration
+### Background image
 
-Add a subtle, theme-aware pattern behind your content with `backgroundDecoration` — `gradient`, `grid`, or `windows`:
-
-```ts blume.config.ts
-theme: {
-  backgroundDecoration: "grid",
-}
-```
-
-For a full background image, set `backgroundImage` (and `backgroundImageDark` for a dark variant) to a URL or a path under `public/`:
+Set a background image behind your content with `backgroundImage` (and `backgroundImageDark` for a dark variant) — a URL or a path under `public/`:
 
 ```ts blume.config.ts lineNumbers
 theme: {

package/docs/content/components.mdx

@@ -125,7 +125,7 @@ A negative or breaking state, such as a deprecation.
 
 ## Icon
 
-Render an icon by name — the same `icon` props power cards, steps, tiles, tabs, and sidebar entries. Names come from three bundled libraries: [Lucide](https://lucide.dev) (the default), [Font Awesome](https://fontawesome.com/icons) (its free set), and [Tabler](https://tabler.io/icons). Names are lowercase and kebab-cased (`rocket`, `gauge-high`, `book-open`).
+Render an icon by name — the same `icon` prop powers cards, steps, tabs, and sidebar entries. Names come from [Lucide](https://lucide.dev/icons), lowercase and kebab-cased (`rocket`, `gauge`, `book-open`).
 
 <Icon icon="rocket" size={20} />
 
@@ -133,27 +133,10 @@ Render an icon by name — the same `icon` props power cards, steps, tiles, tabs
 <Icon icon="rocket" size={20} />
 ```
 
-A bare name resolves against your project's [`icons.library`](#default-library) (Lucide unless you change it). Two ways to reach another library for a single icon:
-
-- **`iconType`** selects a Font Awesome style — `solid` (default), `regular`, or `brands`: `<Icon icon="github" iconType="brands" />`. Font Awesome Pro styles (`light`, `thin`, `duotone`, `sharp-solid`) aren't in the bundled free data and fall back to solid.
-- **A `library:name` prefix** overrides the default per icon: `fa6-solid:gauge-high`, `fa6-brands:github`, `lucide:rocket`, `tabler:heart`.
-
-`size` sets the pixel size (default `16`) and `color` tints it (any CSS color; defaults to `currentColor`). Pass a raw `<svg>` string, an image URL, or a local image path in place of a name to render your own art, and add a `label` to expose it to assistive tech — without one, the icon is decorative.
+Blume is Lucide-only — a bare name resolves against Lucide, and you can prefix a name with `lucide:` (`lucide:rocket`) for symmetry with other icon inputs. `size` sets the pixel size (default `16`) and `color` tints it (any CSS color; defaults to `currentColor`). Pass a raw `<svg>` string, an image URL, or a local image path in place of a name to render your own art, and add a `label` to expose it to assistive tech — without one, the icon is decorative.
 
 Icons resolve at build time and inline as zero-JS SVG — nothing is fetched at runtime.
 
-### Default library
-
-Set which library bare icon names resolve against:
-
-```ts title="blume.config.ts"
-export default defineConfig({
-  icons: { library: "fontawesome" }, // "lucide" (default) | "fontawesome" | "tabler"
-});
-```
-
-A `library:name` prefix always wins over this, so you can mix libraries on any default. Migrating from Mintlify sets this to `fontawesome` for you (Mintlify's default), so your existing icon names keep working.
-
 ## File tree
 
 Illustrate a project or folder layout. Wrap a normal Markdown list and Blume styles it as a tree — handy for explaining structure in setup and config guides.
@@ -457,40 +440,6 @@ Show or hide content by audience. `for="web"` renders only on the site; `for="ag
 <Visibility for="agents">Shown only in the generated Markdown.</Visibility>
 ```
 
-## API fields
-
-Document a single request/response field — a CLI flag, an SDK argument, an endpoint parameter — with its name, type, and description. `ParamField`, `ResponseField`, and `RequestField` are Mintlify-compatible, so a migrated site's field markup renders unchanged. Each takes a `type`, plus `required`, `deprecated`, and `default`; the description is the element's body and may hold rich MDX, including a nested [Expandable](#expandable) for sub-properties.
-
-`ParamField` names the field through the attribute that marks its location — `path`, `query`, `header`, or `body` (or a plain `name`); the location shows as a small label.
-
-<ParamField path="userId" type="string" required>
-  The unique identifier of the user.
-</ParamField>
-
-<ParamField query="limit" type="integer" default="20">
-  Maximum number of results to return per page.
-</ParamField>
-
-<ResponseField name="createdAt" type="string">
-  ISO 8601 timestamp for when the record was created.
-</ResponseField>
-
-```mdx
-<ParamField path="userId" type="string" required>
-  The unique identifier of the user.
-</ParamField>
-
-<ParamField query="limit" type="integer" default="20">
-  Maximum number of results to return per page.
-</ParamField>
-
-<ResponseField name="createdAt" type="string">
-  ISO 8601 timestamp for when the record was created.
-</ResponseField>
-```
-
-For a full spec-driven API reference — one page per operation with generated schemas — use the [OpenAPI reference](/docs/advanced/api-reference) instead.
-
 ## Type tables
 
 Tables for documenting an object's properties — its props, types, and defaults. Write the rows by hand with `TypeTable`, or generate them straight from a TypeScript interface or type alias with `AutoTypeTable`.

package/docs/content/i18n.mdx

@@ -22,10 +22,6 @@ i18n: {
 
 Each locale has a `code` (used in URLs), a `label` (shown in the language switcher), and an optional `dir` for right-to-left scripts (`"ltr"` by default).
 
-:::tip
-Migrating from Mintlify? [`blume migrate mintlify`](/docs/advanced/migrate) reads `navigation.languages[]` and writes the `i18n` block for you — the `default: true` language becomes `defaultLocale`, and translated folders already match Blume's layout.
-:::
-
 ## Organize translated content
 
 The default locale lives at your content root. Every other locale is a top-level folder named by its `code`, mirroring the default structure:

package/docs/content/syntax.mdx

@@ -95,7 +95,7 @@ Tabulate structured data — config options, comparison matrices, parameter list
 
 ## Links and images
 
-Link to other pages or external sites. Images accept any path under `public/` (or another directory listed in [`content.assets`](/docs/configuration#content)) or a remote URL.
+Link to other pages or external sites. Images accept any path under `public/` (served at the site root) or a remote URL.
 
 Read the [quickstart](/docs/quickstart) to get started.
 

package/docs/index.mdx

@@ -49,7 +49,6 @@ Your [`blume.config.ts`](/docs/configuration) and every [`meta.ts`](/docs/conten
 - **Navigation** — inferred from files, refined with `meta.ts` or config.
 - **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD, [built in](/docs/configuration/seo).
 - **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.
-- **Migration** — [`blume migrate mintlify | starlight | nextra | fumadocs`](/docs/advanced/migrate), or run `blume dev` on a Mintlify project as-is with [bridge mode](/docs/advanced/bridge).
 - **Eject** — `blume eject` produces a standalone Astro project that still uses the `blume` package.
 
 ## How it works

package/docs/reference/cli.mdx

@@ -9,19 +9,18 @@ blume <command> [options]
 
 ## Commands
 
-| Command | Description |
-| --- | --- |
-| `blume init` | Scaffold a minimal project. |
-| `blume dev` | Start the dev server with hot reload. |
-| `blume build` | Build the static (or server) site. |
-| `blume preview` | Preview the last build. |
-| `blume add <item>` | Install a source component from the registry. |
-| [`blume migrate <tool>`](/docs/advanced/migrate) | Migrate from Mintlify, Starlight, Nextra, or Fumadocs. |
-| `blume sync` | Re-fetch remote content sources and regenerate. |
-| `blume eject` | Promote the runtime into a standalone Astro app. |
-| `blume check` | Type-check the site with `astro check`. |
-| `blume doctor` | Diagnose config and content problems. |
-| `blume validate` | Validate links across your content. |
+| Command            | Description                                      |
+| ------------------ | ------------------------------------------------ |
+| `blume init`       | Scaffold a minimal project.                      |
+| `blume dev`        | Start the dev server with hot reload.            |
+| `blume build`      | Build the static (or server) site.               |
+| `blume preview`    | Preview the last build.                          |
+| `blume add <item>` | Install a source component from the registry.    |
+| `blume sync`       | Re-fetch remote content sources and regenerate.  |
+| `blume eject`      | Promote the runtime into a standalone Astro app. |
+| `blume check`      | Type-check the site with `astro check`.          |
+| `blume doctor`     | Diagnose config and content problems.            |
+| `blume validate`   | Validate links across your content.              |
 
 ## Common flags
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -28,7 +28,8 @@
     "dist",
     "src",
     "bin",
-    "docs"
+    "docs",
+    "skills"
   ],
   "type": "module",
   "types": "./dist/types/index.d.ts",
@@ -70,11 +71,7 @@
     "@astrojs/node": "^11.0.0",
     "@astrojs/react": "^6.0.0",
     "@astrojs/vercel": "^11.0.0",
-    "@iconify-json/fa6-brands": "^1.2.6",
-    "@iconify-json/fa6-regular": "^1.2.4",
-    "@iconify-json/fa6-solid": "^1.2.4",
     "@iconify-json/lucide": "^1.2.115",
-    "@iconify-json/tabler": "^1.2.35",
     "@iconify/types": "^2.0.0",
     "@iconify/utils": "^3.1.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -111,6 +108,7 @@
     "tailwindcss": "^4",
     "tinyglobby": "^0.2.10",
     "typescript": "^5.7.0",
+    "undici": "^8.6.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {

package/skills/blume/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: blume
+description: Build and maintain documentation sites with Blume, the markdown-first docs framework on Astro and Vite. Use when working in a project that depends on `blume`, when scaffolding or configuring a docs site, writing Markdown/MDX content, tuning navigation/search/theming/SEO/AI features, running the `blume` CLI (init, dev, build, eject), or editing `blume.config.ts` and `meta.ts` files.
+---
+
+# Blume
+
+Blume is an open-source, **markdown-first** documentation framework built on Astro and Vite. Drop Markdown or MDX into a folder, run `blume dev`, and get a production-grade docs site — navigation, search, theming, Open Graph images, and a rich component library — with no app boilerplate to write or maintain.
+
+The core idea: **the framework _is_ the template.** There's no starter to clone and no project to own before you've written a word. The only thing you touch is your content. When you outgrow the defaults, you add configuration one file at a time — and you can `blume eject` to a plain Astro project the day you want full control.
+
+## What makes it different
+
+- **Fast by default** — Static HTML on Astro/Vite. The core theme ships no client framework JS so pages score well on Core Web Vitals out of the box. You opt into server features only when you need them.
+- **AI-ready out of the box** — Emits `llms.txt`/`llms-full.txt`, serves any page's raw Markdown by appending `.md` to its URL, offers **Copy as Markdown** and **Open in chat** on every page, and can host an optional **Ask AI** assistant or an **MCP server** so coding agents read your docs directly.
+- **Zero configuration — even the template** — A folder of docs is a complete project. Navigation is inferred from files, search works in dev and production with no hosted service, and theming is a handful of tokens.
+- **Type-safe to the core** — `blume.config.ts` and every `meta.ts` are real TypeScript, validated by a schema and authored with `defineConfig` and `defineMeta`. Your editor autocompletes options and catches mistakes before a build.
+
+## Quickstart
+
+Blume needs **Node.js 22 or newer**. From an empty or existing project:
+
+```bash
+npm i blume      # install the package
+blume init       # scaffold: docs/index.mdx + blume.config.ts
+blume dev        # dev server with hot reload
+blume build      # static HTML to dist/, with a local search index
+```
+
+Blume works with any package manager and never requires you to set up Astro or Tailwind yourself.
+
+### Writing a page
+
+Every page is Markdown or MDX with a little frontmatter. The `title` and `description` render as the page heading and intro automatically; built-in components (callouts, cards, tabs, steps, and more) need **no imports**.
+
+```mdx
+---
+title: Introduction
+description: Welcome to my docs.
+---
+
+Welcome! Use **Markdown** and built-in components — no imports required:
+
+:::note Blume ships callouts, cards, tabs, steps, and more. :::
+```
+
+Navigation, search, and page metadata are inferred from your files as you add them.
+
+## What's included
+
+- **Components** — callouts, cards, steps, tabs, accordions, badges, file trees, and parameter tables, usable in MDX with no imports.
+- **Local search** — Orama in dev and production; Pagefind is one flag away for large sites. No hosted index.
+- **AI** — `llms.txt`, raw Markdown URLs, Copy as Markdown, Open in chat, an Ask AI assistant, and a hosted MCP server.
+- **Navigation** — inferred from files, refined with `meta.ts` or config.
+- **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD.
+- **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.
+- **Eject** — `blume eject` produces a standalone Astro project that still uses the `blume` package.
+
+## How it works
+
+The Blume CLI discovers your content, builds a content graph, and generates a hidden Astro project under `.blume/` that it drives for dev and build. The generated runtime is an implementation detail — you write Markdown, Blume handles the rest — until you choose to eject and own it.
+
+## Full documentation
+
+This is a high-level overview. For complete, authoritative docs — configuration reference, every CLI command and flag, component APIs, content authoring, navigation, search, SEO, AI features, theming, and deployment — read the bundled docs in the installed package:
+
+```
+node_modules/blume/docs
+```
+
+Start with `node_modules/blume/docs/index.mdx` (Introduction) and `node_modules/blume/docs/01-quickstart.mdx`, then browse the `configuration/`, `content/`, `reference/`, and `advanced/` sections for specifics.

package/skills/blume-update-docs/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: blume-update-docs
+description: Keep a Blume docs site in sync with the product it documents. Audit recently merged pull requests, changelogs, config schemas, CLI help, and public APIs against the docs content, update only pages that are factually stale, verify the docs build, and open (or update) a maintenance pull request — or report a clean no-op. Use when asked to check docs for drift, refresh stale documentation, run a scheduled docs audit, or keep docs current after a release.
+---
+
+# Update Blume Docs
+
+Blume is a **markdown-first** documentation framework on Astro/Vite: content lives as Markdown/MDX under a content root (default `docs/`), navigation derives from the file tree plus optional `meta.ts` files, and `blume build` validates links, anchors, frontmatter, and routes.
+
+Your job is **docs maintenance, not docs authorship**: find where shipped, user-facing behavior has drifted from what the docs claim, fix exactly that, prove the site still builds, and deliver the result as a pull request. A run that finds nothing actionable ends with a short report and **no branch, no commit, no PR** — prefer a no-op over a noisy PR.
+
+## Ground rules
+
+- **Only document what shipped.** Never invent features, timelines, pricing, APIs, or compatibility claims. Work behind a feature flag is not ready for docs unless the flag is enabled for the documented audience or the repo explicitly documents unreleased behavior.
+- **Facts over polish.** Edit when a command, option, default, route, prop, or workflow is wrong or missing. Skip subjective rewording, marketing polish, restructuring, and formatting-only churn.
+- **Smallest correct diff.** Touch the fewest pages that remove the drift. Preserve the site's voice, frontmatter style, component usage, and `meta.ts` navigation patterns.
+- **Exact source-of-truth wording** for commands, flags, config keys, environment variables, routes, and version numbers — copy them from code, don't paraphrase from memory.
+- **Respect the repo.** Follow `AGENTS.md`/`CLAUDE.md` conventions, don't touch generated output (`.blume/`, `dist/`), and never overwrite unrelated local changes.
+
+## Workflow
+
+1. **Establish context.**
+   - Read the repo's agent/contributor instructions (`AGENTS.md`, `CLAUDE.md`, contribution docs) and honor them.
+   - Locate the docs app and content root: `blume.config.ts` (`content.root`), the directory of `.md`/`.mdx` pages, `meta.ts` files, and the package manager + docs build command.
+   - If this run was configured with a trigger, lookback window, docs path, target branch, or PR policy, honor those. Use the defaults below only where the prompt is silent.
+
+2. **Reuse or create a maintenance branch.**
+   - If an open docs-maintenance PR from a previous run exists (head branch starting with `blume/`), check out and update that branch instead of opening a duplicate.
+   - Otherwise branch from the default branch as `blume/docs-refresh-YYYY-MM-DD`. Create the branch only once you know an edit is needed.
+
+3. **Find drift.** Read `references/audit-checklist.md` for the full source list and change criteria, then:
+   - Review PRs merged into the default branch within the lookback window (default: the last 7 days) and extract the user-facing changes.
+   - Compare those changes — plus changelogs, release notes, config schemas, exported APIs, CLI help, and examples — against the docs content.
+   - Check external links only when a checked page depends on them; prefer official docs and release notes over secondary sources.
+   - Keep notes: what you checked, what changed upstream, and why each edit is (or isn't) needed.
+
+4. **Update the docs.**
+   - Fix the stale pages. Add, rename, or remove `meta.ts` entries when pages are added, renamed, or deleted.
+   - Match the surrounding pages: frontmatter shape, Blume components already in use, code-fence style, root-relative internal links.
+
+5. **Verify.**
+   - Run the docs build (`blume build` or the repo's documented docs QA) — it validates links, anchors, frontmatter, and duplicate routes.
+   - Run lint/format/typecheck when the repo's conventions call for them on docs changes.
+   - Fix failures your edits caused; report pre-existing failures separately instead of fixing them in this PR.
+
+6. **Deliver.**
+   - **Changes made:** commit only the maintenance edits, push the `blume/*` branch, and open or update a PR against the default branch titled like `blume: refresh docs for YYYY-MM-DD`. In the body list sources checked, docs changed, verification commands and results, skipped checks, and residual risk.
+   - **No changes needed:** report the PRs and docs areas checked and the no-op result. Do not create a branch, commit, or PR.
+
+## Resources
+
+- `references/audit-checklist.md` — the source checklist, edit/skip criteria, and Blume-specific editing guidance. Read it before making docs changes.

package/skills/blume-update-docs/references/audit-checklist.md

@@ -0,0 +1,46 @@
+# Audit checklist
+
+Use this checklist to decide whether a docs-maintenance run should make changes.
+
+## Sources to check
+
+- **Repo instructions:** `AGENTS.md`, `CLAUDE.md`, contribution docs, release docs, PR templates, and package scripts.
+- **Blume config:** `blume.config.ts` — `content.root`, navigation (`meta.ts` files, tabs, selectors), site settings, AI/MCP settings, search, OpenAPI/AsyncAPI sources, theme, and export settings.
+- **Public surface area:** exported package entrypoints, config schemas, component props, CLI commands and help text, route handlers, environment variables, and registry items.
+- **User workflows:** quickstarts, examples, migration guides, deployment guides, screenshots, sample projects, and README snippets.
+- **Recent merge signals:** PRs merged within the lookback window (default 7 days), changelogs, release notes, changesets, tags, and package version bumps.
+- **Docs content:** every `.md`/`.mdx` page under the configured content root, plus custom pages and blog/changelog entries.
+- **External dependencies:** official provider docs and release notes for linked integrations — only when the docs mention them or the dependency changed.
+- **Generated docs surfaces:** `llms.txt`, raw Markdown URLs, MCP tools, OpenAPI pages, search, sitemap, robots, RSS, and OG behavior when relevant.
+
+## Change criteria
+
+Make a docs edit when at least one condition is true:
+
+- A command, config option, environment variable, route, CLI flag, component prop, or default value changed.
+- A documented workflow no longer works or misses a required step.
+- A page promises a feature, provider, adapter, or integration the code no longer supports.
+- A new user-facing capability shipped but is absent from the appropriate docs page.
+- A link points at moved, removed, or outdated primary documentation.
+- A changelog or release page needs an entry for shipped user-facing behavior.
+
+Skip the edit when the only available change is subjective polish, wording preference, duplicated information, speculative future work, or behavior still hidden behind a feature flag.
+
+## Blume editing guidance
+
+- Keep frontmatter short and factual; use `title` and `description` consistently with nearby pages. Blume's frontmatter schema is **strict** — unknown keys are build errors.
+- Preserve existing page order and `defineMeta` style; update `pages` arrays when adding, renaming, or removing pages.
+- Use the Blume components already present in the docs (callout directives, steps, cards) instead of inventing new markup patterns.
+- Match nearby code fences: filenames, language tags, and line numbers where the surrounding docs use them.
+- Keep internal links root-relative (`/docs/...`).
+- Do not edit generated `.blume/` or `dist/` output.
+
+## PR notes
+
+Include these sections in the PR body or no-op summary:
+
+- Sources checked
+- Docs changed
+- Verification run (commands and results)
+- Skipped checks, with reasons
+- Remaining risk or follow-up

package/src/astro/generate.ts

@@ -432,11 +432,16 @@ const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
   if (!logo) {
     return null;
   }
-  const config = typeof logo === "string" ? { light: logo } : logo;
-  const light = config.light ?? config.dark;
-  const dark = config.dark ?? config.light;
-  const alt = config.alt ?? "";
-  const href = config.href ?? "/";
+  const config = typeof logo === "string" ? { image: logo } : logo;
+  // `text` is passed through verbatim: `undefined` lets the brand fall back to
+  // the site title, `""` renders the mark alone (a logo with the wordmark baked
+  // in).
+  const { href, image: source, text } = config;
+  const image = typeof source === "string" ? { light: source } : source;
+  const light = image?.light ?? image?.dark;
+  const dark = image?.dark ?? image?.light;
+  const alt = image?.alt ?? "";
+  const brandHref = href ?? "/";
 
   if (light && light === dark && light.toLowerCase().endsWith(".svg")) {
     const rel = light.replace(/^\//u, "");
@@ -445,10 +450,10 @@ const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
       join(project.context.root, rel),
     ].find((path) => existsSync(path));
     if (file) {
-      return { alt, href, svg: readFileSync(file, "utf-8") };
+      return { alt, href: brandHref, svg: readFileSync(file, "utf-8"), text };
     }
   }
-  return { alt, dark, href, light };
+  return { alt, dark, href: brandHref, light, text };
 };
 
 /**
@@ -615,7 +620,6 @@ export const buildRuntimeData = (project: BlumeProject): string => {
           code,
           withReferenceTabs(
             graph.navigationByLocale[code] ?? {
-              chromeVariants: [],
               selectors: [],
               sidebar: [],
               tabs: [],
@@ -648,7 +652,6 @@ export const buildRuntimeData = (project: BlumeProject): string => {
             })),
           }
         : null,
-      icons: config.icons,
       imageZoom: config.markdown.imageZoom,
       logo: resolveLogo(project),
       mcp: config.mcp.enabled
@@ -974,9 +977,9 @@ export const generateRuntime = async (
   const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
   // Only emit a project-scanning `docs` collection when a filesystem source
-  // actually feeds it. Bridge mode has just the staged Mintlify source, so the
-  // `docs` glob would otherwise scan (and watch) the whole project root for
-  // nothing — see contentConfigTemplate.
+  // actually feeds it. An all-staged project (openapi/notion/…) has only staged
+  // sources, so the `docs` glob would otherwise scan (and watch) the whole
+  // project root for nothing — see contentConfigTemplate.
   const hasFilesystemSource = project.sources.some((source) => !source.staged);
 
   const structural = await Promise.all([

package/src/astro/integration.ts

@@ -1,13 +1,10 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { fileURLToPath } from "node:url";
 
 import type { AstroIntegration } from "astro";
 
-import type { AssetMount } from "../core/assets.ts";
 import { enrichDiagnostic } from "../core/diagnostics.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
-import { copyAssetMounts, serveAssetMounts } from "./static-assets.ts";
 
 /** The dev server's HMR channel — either `.ws` (Vite ≤5) or `.hot` (Vite 6+). */
 interface OverlayChannel {
@@ -77,11 +74,6 @@ export interface BlumeIntegrationOptions {
   contentRoutes: string[];
   /** Configured `deployment.base`, stripped from dev URLs before matching. */
   base?: string;
-  /**
-   * `content.assets` mounts: top-level dirs served at the site root in dev and
-   * copied into the build output, so root-served assets need no relocation.
-   */
-  assets?: AssetMount[];
 }
 
 /**
@@ -118,12 +110,6 @@ export const blumeIntegration = (
   options: BlumeIntegrationOptions
 ): AstroIntegration => ({
   hooks: {
-    "astro:build:done": async ({ dir }) => {
-      // Copy in-place asset mounts into the build output, mirroring publicDir.
-      if (options.assets?.length) {
-        await copyAssetMounts(options.assets, fileURLToPath(dir));
-      }
-    },
     "astro:config:setup": ({ injectRoute }) => {
       for (const page of options.pages) {
         injectRoute({
@@ -143,13 +129,6 @@ export const blumeIntegration = (
         handle: negotiateMarkdown(new Set(options.contentRoutes), options.base),
         route: "",
       });
-      // Serve `content.assets` mounts (Astro only serves publicDir in dev).
-      if (options.assets?.length) {
-        server.middlewares.stack.unshift({
-          handle: serveAssetMounts(options.assets),
-          route: "",
-        });
-      }
     },
   },
   name: "blume",