blume 0.5.3 → 0.6.0

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

@@ -162,23 +162,25 @@ 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"];
+/** A pinned link rendered above the sidebar sections (external or internal). */
+export interface FeaturedLink {
+    label: string;
+    href: string;
+    icon?: string;
 }
 /** The complete navigation model derived from the content graph. */
 export interface Navigation {
     tabs: NavTab[];
     selectors: NavSelector[];
-    chromeVariants: NavChromeVariant[];
     sidebar: NavNode[];
+    /** Pinned links shown above the sidebar sections, unscoped by tab. */
+    featured: FeaturedLink[];
     /** 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

@@ -62,6 +62,25 @@ ai: {
 }
 ```
 
+### Suggested questions
+
+Seed the empty state with a few starter prompts. Each renders as a clickable suggestion — click one to send it — with an optional [Lucide icon](/docs/content/components#icon) beside the label:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    suggestions: [
+      { label: "What is Blume?", icon: "rocket" },
+      { label: "How do I write a docs page?", icon: "file-text" },
+      { label: "How do I configure the theme?", icon: "settings" },
+    ],
+  },
+}
+```
+
+`label` is the question that gets asked; `icon` is optional. Leave `suggestions` unset (or empty) and the panel opens to a plain input.
+
 ### Grounding
 
 Ask AI is **grounded in your docs**. For each question it retrieves the most relevant pages — using the same lexical [Orama](/docs/configuration/search) index that powers on-page search — and injects them into the model's system prompt, so answers come from your content instead of the model's own knowledge. The assistant is told to answer only from the retrieved pages, to say when something isn't covered, and to cite the pages it drew from.
@@ -175,6 +194,43 @@ A static build with `mcp.enabled` fails fast with a message telling you to set `
 claude mcp add --transport http my-docs https://docs.example.com/mcp
 ```
 
+## Agent readability
+
+Blume writes an **`/agent-readability.json`** manifest at your site root that indexes the agent-facing surface described on this page — so an agent can discover it in a single fetch instead of guessing at conventions or scraping HTML. Unlike the features above, it's on by default:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  agentReadability: true,
+}
+```
+
+The manifest lists only what you've enabled — the [raw Markdown](#raw-markdown) mirror pattern, [`llms.txt`](#llmstxt) and `llms-full.txt`, the [MCP server](#mcp-server) and its discovery document, the [Ask AI](#ask-ai) endpoint, the [sitemap](/docs/configuration/seo#sitemap), and [RSS feeds](/docs/configuration/seo#rss-feeds) — alongside your site name, description, source repository, and the [content-signal](/docs/configuration/seo#content-signals) usage policy. URLs are absolute when [`deployment.site`](/docs/deployment) is set and root-relative otherwise:
+
+```json agent-readability.json
+{
+  "artifacts": {
+    "markdown": {
+      "contentNegotiation": "text/markdown",
+      "pattern": "https://docs.example.com/{route}.md"
+    },
+    "llmsFullTxt": "https://docs.example.com/llms-full.txt",
+    "llmsTxt": "https://docs.example.com/llms.txt",
+    "mcp": {
+      "discovery": "https://docs.example.com/.well-known/mcp.json",
+      "url": "https://docs.example.com/mcp"
+    }
+  },
+  "description": "Docs for the Acme API.",
+  "generator": "blume@1.0.0",
+  "name": "Acme Docs",
+  "site": "https://docs.example.com",
+  "contentUsage": { "search": true, "ai-input": true, "ai-train": true },
+  "repository": "https://github.com/acme/docs"
+}
+```
+
+Set `seo.agentReadability` to `false` to skip it, or ship your own `public/agent-readability.json` to take over — Blume never overwrites a file you place in `public/`.
+
 ## Agent skill
 
 Building a Blume site with the help of a coding agent? Install the Blume [agent skill](https://docs.claude.com/en/docs/claude-code/skills) so it knows how Blume works without you explaining it:
@@ -184,3 +240,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/seo.mdx

@@ -154,7 +154,7 @@ Ship your own `public/sitemap.xml` to take over — Blume never overwrites a fil
 
 ## Robots
 
-Blume writes a `robots.txt` that allows all crawlers and adds a `Sitemap:` line pointing to the sitemap when one is available. On by default:
+Blume writes a `robots.txt` that allows all crawlers, declares your [content signals](#content-signals), and adds a `Sitemap:` line pointing to the sitemap when one is available. On by default:
 
 ```ts blume.config.ts lineNumbers
 seo: {
@@ -164,9 +164,67 @@ seo: {
 
 ```txt robots.txt
 User-agent: *
+Content-Signal: search=yes, ai-input=yes, ai-train=yes
 Allow: /
 
 Sitemap: https://docs.example.com/sitemap.xml
 ```
 
+### Content signals
+
+The `Content-Signal` line — the emerging content-usage convention — declares how AI crawlers may reuse your docs. Blume emits it **on by default with every signal set to `yes`**, matching its stance that docs are open to humans and agents alike:
+
+- `search` — traditional and AI search indexing
+- `aiInput` — grounding / RAG at answer time
+- `aiTrain` — model training
+
+Restrict any signal by setting it to `false`; the ones you leave out stay `yes`:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  contentSignals: {
+    aiTrain: false, // opt out of training, keep search + grounding
+  },
+}
+```
+
+```txt robots.txt
+User-agent: *
+Content-Signal: search=yes, ai-input=yes, ai-train=no
+Allow: /
+```
+
+Set `contentSignals: false` to drop the declaration entirely:
+
+```ts blume.config.ts lineNumbers
+seo: {
+  contentSignals: false,
+}
+```
+
+<TypeTable
+  type={{
+    "seo.contentSignals": {
+      type: "boolean | object",
+      description:
+        "Content-Signal declaration. true or omitted emits all signals as yes; false drops the line; an object sets signals individually.",
+    },
+    "contentSignals.search": {
+      type: "boolean",
+      description: "Allow use for search indexing (search). Default true.",
+    },
+    "contentSignals.aiInput": {
+      type: "boolean",
+      description:
+        "Allow use for AI grounding / RAG at answer time (ai-input). Default true.",
+    },
+    "contentSignals.aiTrain": {
+      type: "boolean",
+      description: "Allow use for AI model training (ai-train). Default true.",
+    },
+  }}
+/>
+
+Content signals express a preference, not access control: they tell well-behaved crawlers how you'd like your content used, and it's on the crawler to honour them.
+
 Ship your own `public/robots.txt` to take over.

package/docs/configuration/theming.mdx

@@ -34,6 +34,8 @@ theme: {
 
 Named presets: `blue` (default), `green`, `orange`, `pink`, `purple`, `red`, and `teal`.
 
+A string applies to both color modes; pass an object for [a different accent per mode](#dark-mode-colors).
+
 ### Radius
 
 `radius` sets the corner rounding shared by cards, code blocks, callouts, and inputs — `none`, `sm`, `md` (default), or `lg`.
@@ -89,18 +91,19 @@ Need a font that isn't listed, or want to drop back to the system stack? Overrid
 
 ### Dark-mode colors
 
-By default light and dark share one `accent`. Set `accentDark` for a different accent in dark mode, and `background` / `backgroundDark` to override the page background per mode:
+`accent` and `background` follow one rule: a string applies to both color modes, and a `{ light, dark }` object sets each mode individually:
 
 ```ts blume.config.ts lineNumbers
 theme: {
-  accent: "blue",
-  accentDark: "teal",        // a different accent in dark mode
-  background: "#ffffff",     // light-mode page background
-  backgroundDark: "#0a0a0a", // dark-mode page background
+  accent: { light: "blue", dark: "teal" },
+  background: {
+    light: "#ffffff",
+    dark: "#0a0a0a",
+  },
 }
 ```
 
-Each takes a named preset or any CSS color, exactly like `accent`.
+Each color takes a named preset or any CSS color. For `background` (and `backgroundImage`) either key can be omitted to override a single mode — `background: { dark: "#0a0a0a" }` keeps the default light background.
 
 ### Action color
 
@@ -112,22 +115,16 @@ 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` — a URL or a path under `public/`. Like the colors, a string applies to both modes and a `{ light, dark }` object sets each mode's image:
 
 ```ts blume.config.ts lineNumbers
 theme: {
-  backgroundImage: "/bg-light.svg",
-  backgroundImageDark: "/bg-dark.svg",
+  backgroundImage: {
+    light: "/bg-light.svg",
+    dark: "/bg-dark.svg",
+  },
 }
 ```
 

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/meta.mdx

@@ -1,6 +1,6 @@
 ---
 title: Folder meta
-description: Configure a sidebar group — its title, icon, order, display mode, and page order — with a meta.ts file.
+description: Configure a sidebar group — its title, icon, order, and page order — with a meta.ts file.
 ---
 
 Every folder in your content tree becomes a sidebar group. Drop a `meta.ts` beside its pages to control how that group looks and how its children are ordered. It's entirely optional: without one, the group's label is the humanized folder name and its pages sort by [index, numeric prefix, then alphabetically](/docs/content/navigation#ordering).
@@ -16,7 +16,6 @@ export default defineMeta({
   title: "Guides",
   icon: "book-open",
   order: 2,
-  display: "flat",
   collapsed: false,
   pages: ["configuration", "theming", "deployment"],
 });
@@ -31,25 +30,12 @@ Every field is optional — set only what you want to override.
 | `title` | `string` | The group's label. Defaults to the humanized folder name. |
 | `icon` | `string` | Icon shown next to the label. |
 | `order` | `number` | Position among sibling groups and pages. Lower numbers sort first. |
-| `display` | `"flat" \| "group" \| "page"` | How the group renders in the sidebar. Defaults to `flat`. See [below](#display-modes). |
-| `collapsed` | `boolean` | For `display: "group"`, whether the group starts collapsed. |
+| `collapsed` | `boolean` | Under the [`group` display mode](/docs/content/navigation#display-modes), whether the group starts collapsed. |
 | `pages` | `string[]` | Explicit order for the group's children, by slug. |
 
 The `pages` array lists children by slug — the folder or file name with its numeric prefix and any parentheses stripped (so `01-quickstart.mdx` is `"quickstart"`). Children you leave out still appear, after the listed ones.
 
-## Display modes
-
-`display` controls how a group and its items appear in the sidebar:
-
-- **`flat`** (default) — a non-collapsible header with its pages listed beneath.
-- **`group`** — a collapsible `<details>` disclosure. Pair it with `collapsed` to set the initial state; a group containing the current page always starts open.
-- **`page`** — a single row that, when clicked, slides the sidebar into a sub-panel showing only that group's items, with a back arrow at the top. The panel is route-aware, so landing directly on a page inside the group opens straight to it.
-
-:::tip
-`page` mode keeps deep sections tidy — reach for it when a group has many children and you'd rather drill into it than scroll past it.
-:::
-
-`display` works the same on a group in an [explicit sidebar](/docs/content/navigation#explicit-sidebar) config.
+How groups render — flat headers, collapsible disclosures, or drill-in panels — is a sidebar-wide setting, not per folder: see [display modes](/docs/content/navigation#display-modes).
 
 ## Computed meta
 

package/docs/content/navigation.mdx

@@ -31,7 +31,7 @@ See [Frontmatter](/docs/reference/frontmatter) for the full page schema.
 
 ## Folder groups
 
-Each folder becomes a sidebar group. Drop a [`meta.ts`](/docs/content/meta) beside its pages to set the group's title, icon, order, [display mode](/docs/content/meta#display-modes), and the order of its children:
+Each folder becomes a sidebar group. Drop a [`meta.ts`](/docs/content/meta) beside its pages to set the group's title, icon, order, and the order of its children:
 
 ```ts meta.ts
 import { defineMeta } from "blume";
@@ -43,10 +43,32 @@ export default defineMeta({
 });
 ```
 
-See [Folder meta](/docs/content/meta) for every field, the three display modes, and computing meta at scan time.
+See [Folder meta](/docs/content/meta) for every field and computing meta at scan time.
 
 To group pages _without_ adding a URL segment, use a parenthesized folder name — see [Pages](/docs/content#group-folders).
 
+## Display modes
+
+`navigation.sidebar.display` sets how every sidebar group renders:
+
+```ts blume.config.ts lineNumbers
+navigation: {
+  sidebar: {
+    display: "flat", // "flat" | "group" | "page"
+  },
+}
+```
+
+- **`flat`** (default) — a non-collapsible header with its pages listed beneath. Pages that aren't in any group always list first, above the group sections, so they can't be mistaken for a group's children.
+- **`group`** — a collapsible `<details>` disclosure per group. Pair it with `collapsed` in [folder meta](/docs/content/meta) to set the initial state; a group containing the current page always starts open.
+- **`page`** — each group is a single row that, when clicked, slides the sidebar into a sub-panel showing only that group's items, with a back arrow at the top. The panel is route-aware, so landing directly on a page inside the group opens straight to it.
+
+:::tip
+`page` mode keeps deep sections tidy — reach for it when groups have many children and you'd rather drill into them than scroll past them.
+:::
+
+A group in an [explicit sidebar](#explicit-sidebar) can override the global mode with its own `display`.
+
 ## Ordering
 
 When the sidebar is generated, order is resolved highest priority first:
@@ -112,9 +134,24 @@ navigation: {
 
 Each item takes a `label`, a `path`, and optional `icon`, `description`, and `tag`. `kind` (`dropdown`, `product`, `version`, or `language`) is a hint for how the selector is used; all render the same dropdown.
 
+## Featured links
+
+Pin links to the top of the sidebar, above every section — a blog, a changelog, a contact or support page that should always be one click away. Unlike the generated tree, featured links are **not scoped by tab**: they show on every route, on every breakpoint.
+
+```ts blume.config.ts lineNumbers
+navigation: {
+  featured: [
+    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
+    { label: "Contact", href: "/contact", icon: "headphones" },
+  ],
+}
+```
+
+Each link takes a `label`, an `href`, and an optional `icon` (a [built-in icon](/docs/configuration/customization) name, image path/URL, or inline SVG — the same as anywhere else). An `href` may point anywhere: an external URL opens in a new tab, while an internal route (`/contact`) is validated against your pages at build time, warning you if nothing matches.
+
 ## Explicit sidebar
 
-For full control, define `navigation.sidebar` in config. When it's set, Blume uses it verbatim and skips file-system generation:
+For full control, list explicit items in `navigation.sidebar` — a bare array is shorthand for `sidebar.items`, and the object form combines them with a global [`display`](#display-modes). When items are set, Blume uses them verbatim and skips file-system generation:
 
 ```ts blume.config.ts lineNumbers
 navigation: {
@@ -130,7 +167,7 @@ navigation: {
 }
 ```
 
-Each item is a page route (a string), a group (`label` + `items`), or a link (`label` + `href`). Groups can nest, take a [`display` mode](/docs/content/meta#display-modes), and start `collapsed`.
+Each item is a page route (a string), a group (`label` + `items`), or a link (`label` + `href`). Groups can nest, override the global [`display` mode](#display-modes), and start `collapsed`.
 
 ## Repository link
 

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