blume 1.5.3 → 1.6.1

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

@@ -18,19 +18,21 @@ Read `themeConfig`, `presets`, and `plugins`:
 | `tagline` | `description` |
 | `themeConfig.navbar.title` / `.logo` | `title` / `logo` (move the image into `public/`) |
 | `themeConfig.navbar.items` (doc items) | `navigation.tabs` (for section links) |
-| `themeConfig.navbar.items` (external/utility links — Blog, GitHub, Discord…) | **`navigation.featured`** (`{ label, href, icon? }`, pinned above the sidebar on every route); the GitHub link → the `github` config instead |
+| `themeConfig.navbar.items` (external/utility links — Blog, Discord…) | **`navigation.actions`** (`[{ label, href }]`, plain header links) to keep them in the header, or **`navigation.featured`** (`{ label, href, icon? }`, pinned above the sidebar on every route) if they should survive on phones; the GitHub link → the `github` config instead |
+| `themeConfig.navbar.items` (a `className`-styled button — "Get started", "Sign up") | **`navigation.cta`** (`{ label, href }`, the header's one filled button; a route the docs don't serve must be an absolute URL) |
 | `themeConfig.colorMode.defaultMode` | `theme.mode` (`respectPrefersColorScheme: true` → `"system"`) |
 | `themeConfig.prism.theme` / `.darkTheme` | `markdown.codeBlocks.theme: { light, dark }` (map Prism theme names to Shiki themes, e.g. `github`/`github-dark`) |
 | `themeConfig.metadata` / `themeConfig.image` | per-page `seo` frontmatter / `seo.og`; report what doesn't fit |
 | `url` + `baseUrl` | **`url` → drop** (`deployment.site` auto-detects); `baseUrl` (when not `/`) → `deployment.base` |
 | 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`) |
+| 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` | drop → 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 |
 | `@docusaurus/plugin-client-redirects` | **static `redirects: [{from, to}]` arrays convert 1:1** to Blume `redirects` (a `from` array = one entry per item); only `createRedirects` functions are truly dynamic → host rules |
 | `@docusaurus/theme-mermaid` | delete the dep — ` ```mermaid ` renders natively (in `.mdx`) |
+| GraphQL doc generators (`@graphql-markdown/docusaurus`, `@edno/docusaurus2-graphql-doc-generator`) | delete the plugin **and its generated pages** — point the top-level `graphql: { enabled: true, spec, endpoint }` at the schema instead (see SKILL.md "GraphQL") |
 | `remark-math` + `rehype-katex` | delete — block `$$…$$` renders in `.mdx` with no config (no `markdown.math` field exists); **inline `$…$` is not supported** — convert or drop (report) |
 | Multi-instance docs plugins (`plugin-content-docs` with `id`) | one folder (and usually one `navigation.tabs` entry) per instance |
 
@@ -42,7 +44,7 @@ Every Docusaurus repo serves **`static/`** at the site root (`static/img/foo.png
 
 - **Autogenerated sidebar** (`{ type: 'autogenerated', dirName: '...' }`) → Blume's default filesystem navigation. Docusaurus strips numeric prefixes (`01-`) exactly like Blume, so the convention round-trips; no config needed.
 - **Explicit sidebar** (arrays of doc IDs, categories, links) → restructure into folders where possible; use `navigation.sidebar` only for shapes files can't express. A category `{ type: 'category', label, items }` → a folder (label → `meta.ts` `title`); `collapsed` → `meta.ts` `collapsed`, and collapsible rendering → that folder's `meta.ts` `display: "group"` (or `navigation.sidebar.display: "group"` once in config when every category collapses).
-- **`_category_.json`** (also `.yml`) (`{ label, position, collapsed, collapsible, link, className, customProps }`) → a folder `meta.ts`: `label`→`title`, `position`→`order`, `collapsed`→`collapsed`. `link.type: 'generated-index'` → an `index` page in the folder — **and the old URL was `/docs/category/<slug>`**, so add a redirect and rewrite inbound links. `link.type: 'doc'` → make that doc the folder's `index`. `collapsible`/`className`/`customProps` → drop (report).
+- **`_category_.json`** (also `.yml`) (`{ label, position, collapsed, collapsible, link, className, customProps }`) → a folder `meta.ts`: `label`→`title`, `position`→`order`, `collapsed`→`collapsed`. `link.type: 'generated-index'` → an `index` page in the folder — **and the old URL was `/docs/category/<slug>`**, so add a redirect and rewrite inbound links. `link.type: 'doc'` → make that doc the folder's `index`. `collapsible: false` → that folder's `meta.ts` `display: "flat"`, so it stays a plain heading even under a global `"group"` mode. `className`/`customProps` → drop (report).
 - **`src/pages/` — inventory, don't nuke.** Nearly every repo has a React landing page (`src/pages/index.tsx`) and often extra Markdown pages. Markdown pages → content pages; the React home page → rebuild as a docs index or a custom `.astro` page under `content.pages` — report either way.
 
 ## Versioned docs

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

@@ -37,7 +37,7 @@ Everything else is `defineConfig({ title })`.
 | `root: true` | a **`navigation.tabs` entry** (see below) — **not** a `meta.ts` field |
 | `pages: [...]` slugs | `pages: [...]` (ordering) |
 | `description` | **drop** (folders have no description) |
-| `collapsible: false` | **drop** (report — no per-folder equivalent) |
+| `collapsible: false` | that folder's `display: "flat"` (a plain heading, even under a global `"group"` mode) |
 
 `meta.ts` accepts **only** `title`, `icon`, `order`, `collapsed`, `pages`, `display`. Render mode is per-folder or global: a folder that needs collapsible rendering sets its own `meta.ts` `display: "group"` (drill-in is `"page"`); when the whole sidebar should collapse, set `navigation.sidebar.display: "group"` once in `blume.config.ts` instead of repeating it per folder.
 
@@ -73,6 +73,10 @@ Fumadocs icons are strings resolved by the repo's own `icon` handler in `loader(
 - **No equivalent — report:** `<DynamicCodeBlock>`, `<ImageZoom>` (Blume zooms content images by default), `<InlineTOC>`.
 - **Strip or convert every import** — not just `fumadocs-*`: `lucide-react` imports (icon JSX → string names), `next/image`/`next/link` (→ Markdown image/link), and local components. **Inventory `mdx-components.tsx` before deleting it** — components registered there are used import-free in MDX bodies; port or inline each usage first.
 
+## Headings
+
+Trailing heading markers — `[#custom-id]` (pinned anchor), `[!toc]` (hide from the TOC), `[toc]` (TOC-only entry) — use the same syntax in Blume. **Pass through unchanged.** One exception: Fumadocs' looser grammar accepts an id containing whitespace (`[#two words]`); Blume does not parse that as a marker, so rewrite such an id to a hyphenated one and update every link that targets it.
+
 ## Code fences
 
 - ` ```npm ` fences (Fumadocs' remark-npm accepts both) → ` ```package-install `.
@@ -82,13 +86,17 @@ Fumadocs icons are strings resolved by the repo's own `icon` handler in `loader(
 
 `fumadocs-openapi` writes **generated MDX stubs into the content tree** (`generateFiles()` output: pages containing `<APIPage>`/`<OpenAPIPage>` with `_openapi` frontmatter), plus `lib/openapi.ts` (`createOpenAPI`) and a generate script. Treat these exactly like Mintlify endpoint stubs: **delete the generated pages**, point `openapi: { enabled: true, sources: [{ spec }] }` at the spec (vendor it locally), add a `navigation.tabs` entry for the reference route, and remove `fumadocs-openapi`, `lib/openapi.ts`, and the generate script. Keep hand-written conceptual pages (intro/auth) under the reference route.
 
+## GraphQL
+
+`@fumadocs/graphql` works differently from the OpenAPI flow: **no stub files** — pages are virtual, served through the Loader API. The artifacts to harvest and tear down: `lib/graphql.ts` (`createGraphQL()` — read its `input` for the schema and any per-source routes/labels), the `graphql.staticSource()`/`graphql.loaderPlugin()` wiring in the source config, the `GraphQLPage` component (`createGraphQLPage()`, usually `components/api-page.tsx` — read its playground `endpoint`), and the `@fumadocs/graphql/css/preset.css` import. Map to the top-level `graphql: { enabled: true, spec, endpoint }` block (see SKILL.md "GraphQL"): SDL files/text and introspection results carry over as `spec` (vendor a URL input locally); a programmatic `GraphQLSchema` instance must be printed to SDL and committed (report); the `createGraphQLPage` playground endpoint becomes `endpoint`. When `createGraphQL()` takes several inputs, or sources carry their own routes, labels, or endpoints, map each one to an entry in `graphql.sources` (`{ spec, route, label, endpoint }`) instead of the single block-level `spec` — otherwise a schema is dropped or mounted on the wrong route. Blume groups routes the same way (`<route>/queries/<field>`, `<route>/objects/<type>`), but slugs are re-derived — rewrite inbound links and let `blume validate` catch strays. Then remove `@fumadocs/graphql`, the two lib/component files, and the CSS import. Since there are no generated pages, there is nothing to delete from the content tree — but keep any hand-written conceptual pages under the reference route.
+
 ## i18n
 
 A `loader({ i18n })` setup (locale-suffixed files or locale dirs) → Blume `i18n: { defaultLocale, locales: [{ code, label }] }`. Locale **directories** match Blume's `dir` parser as-is; locale **file suffixes** (`page.cn.mdx`) need restructuring into locale folders. Report whichever transform you apply.
 
 ## Package.json & teardown
 
-Repoint scripts (`dev`→`blume dev`, `build`→`blume build`, `start`→`blume preview`), remove the `fumadocs-*` deps and the host framework's deps (`next`, `react-router`, `@tanstack/*`…), add `blume`. Safe to delete after harvesting (see above for what to read first): `source.config.*`, `mdx-components.tsx`, the app/route dir, and host-framework config (`next.config.*`, `next-env.d.ts`, the `next` tsconfig plugin — or the React Router/TanStack equivalents).
+Repoint scripts (`dev`→`blume dev`, `build`→`blume build`, `start`→`blume preview`), remove the `fumadocs-*`/`@fumadocs/*` deps and the host framework's deps (`next`, `react-router`, `@tanstack/*`…), add `blume`. Safe to delete after harvesting (see above for what to read first): `source.config.*`, `mdx-components.tsx`, the app/route dir, and host-framework config (`next.config.*`, `next-env.d.ts`, the `next` tsconfig plugin — or the React Router/TanStack equivalents).
 
 ## Dropped — report these
 

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

@@ -94,7 +94,9 @@ Mintlify's `navigation` object (`tabs`/`anchors`/`dropdowns`/`products`/`version
   Call this trade out explicitly in the migration report; don't silently pick one. **The scoping is bidirectional:** on the root/landing route Blume _hides_ every tab folder and lists only untabbed top-level pages — so a Mintlify home whose single sidebar showed everything becomes a lean root list plus one sidebar per tab. That's automatic; don't try to exclude tab folders from the root by hand.
 
 - **`dropdowns`/`products`/`versions`** → `navigation.selectors` (`{ kind, label, items: [{ label, path, icon?, description?, tag? }] }`). Use `kind` `dropdown`/`product`/`version` accordingly.
-- **`anchors` / `navigation.global.anchors` / `navbar.links`** (persistent header links — Blog, Changelog, Community, Contact/Support) → **`navigation.featured`** (`{ label, href, icon? }`). These pin to the **top of the sidebar, above every section, on every route** (not tab-scoped) — the right home for Mintlify's always-visible utility links. An external `href` opens in a new tab; an internal one (`/contact`) is build-time validated against your pages. Convert the FontAwesome `icon` to Lucide as usual. (This replaces the old "drop and report" for anchors.) The `navbar.primary` **CTA button** has no featured equivalent — see Dropped.
+- **`anchors` / `navigation.global.anchors`** (persistent sidebar-top links — Blog, Changelog, Community, Contact/Support) → **`navigation.featured`** (`{ label, href, icon? }`). These pin to the **top of the sidebar, above every section, on every route** (not tab-scoped) — the right home for Mintlify's always-visible utility links. An external `href` opens in a new tab; an internal one (`/contact`) is build-time validated against your pages. Convert the FontAwesome `icon` to Lucide as usual. (This replaces the old "drop and report" for anchors.)
+- **`navbar.links`** (plain header links — Log in, Status, Support) → **`navigation.actions`** (`[{ label, href }]`), rendered in the header left of the icon buttons. A GitHub link → the `github` config (or `navigation.repo` as a URL when the docs repo is private) instead. Header links hide on phones; a link that must survive there belongs in `featured`.
+- **`navbar.primary`** (the header **CTA button** — "Get Started"/"Sign Up", `type: "button"`) → **`navigation.cta`** (`{ label, href }`, singular: Blume renders exactly one filled button). A `type: "github"` primary → the `github` config instead. A route the docs don't serve (the product's own `/signup`) must be an absolute URL, or it raises `BLUME_NAV_MISSING_PAGE`.
 - **`languages`** → `i18n`, not a selector (see below).
 - Only fall back to an explicit `navigation.sidebar` for a shape the filesystem genuinely can't express.
 
@@ -149,7 +151,6 @@ Mintlify serves every top-level dir (e.g. `/images`) at the site root. Blume ser
 
 ## Dropped — report these
 
-- **`navbar.primary`** (the prominent header **CTA button**, e.g. "Get Started"/"Sign Up") → no button equivalent; re-add via `navigation.tabs`, a `navigation.featured` link, or a Header override. (Plain `navbar.links` and `anchors` map to `navigation.featured` — see Navigation above, not here.)
 - **`footer.socials`** → suggest the `github` config, or a Footer override.
 - **Per-language banners** (`navigation.languages[].banner`) → no equivalent.
 - **Dynamic redirects** (`:slug*`/`:id` params) → can't be static path-to-path; move to host rules (`_redirects`, `vercel.json`).

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

@@ -15,7 +15,7 @@ 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 header repo link); `docsRepositoryBase` → `github` (owner/repo/branch — and any trailing sub-path → `github.dir`); `banner.text`/`banner.key` → `banner.content`/`banner.id` (`dismissible` maps); `primaryHue`/`primarySaturation` → pick an equivalent `theme.accent` color; `footer` → drop (report); `faviconGlyph` → drop (Blume's favicon is a file convention); `useNextSeoProps`/head → per-page `seo` frontmatter or drop.
+- **v2/v3 — `theme.config.*`:** `logo` (JSX — extract text/image) → `logo`; `project.link` → `github` (renders the header repo link); `docsRepositoryBase` → `github` (owner/repo/branch — and any trailing sub-path → `github.dir`; 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).
 - **`next.config.*`:** harvest **`redirects()`** — static entries become Blume `redirects: [{ from, to }]`; wildcard/dynamic ones move to host config (report). A `latex: true` flag means math is in play (see Math below). Then delete the file.
 - Root `_meta` entries with **`type: "page"`** → `navigation.tabs` (`{ label, path }`, where `path` is `/` for `index`, else `/<slug>`). `type: "page"` only maps at the **root**.
@@ -32,7 +32,7 @@ For each `_meta` entry (`key` = slug, value = string title or `{ title, type, di
 | `display: "hidden"` | frontmatter `sidebar.hidden: true` |
 | `type: "separator"` | drop → recreate as a `(Group)/` folder / `meta.ts` boundary if needed |
 | `type: "menu"` (navbar dropdown) | drop → recreate via `navigation.selectors` if wanted |
-| `href` (external link) | **`navigation.featured`** (`{ label, href, icon? }` — pinned above the sidebar on every route); only drop deep-nested ones (report) |
+| `href` (external link) | root-level → **`navigation.actions`** (`[{ label, href }]`, plain header links, matching Nextra's navbar placement) or **`navigation.featured`** (`{ label, href, icon? }` — pinned above the sidebar on every route, survives on phones); only drop deep-nested ones (report) |
 | `type: "page"` (subfolder, not root) | drop (only root → tabs) |
 | `theme: { collapsed }` on a folder | `meta.ts` `collapsed` |
 | `theme: { layout: "full" \| sidebar: false \| … }` | drop (report — no per-page layout switches) |

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

@@ -22,7 +22,7 @@ Keep content where it is — set `content.root: "src/content/docs"`.
 | `logo.replacesTitle` | `logo: { text: "" }` (renders the mark alone) |
 | `favicon` | copy the file into `public/` (drop the config field — Blume auto-detects) |
 | `social` (array of `{ label, icon, href }`; pre-0.33 legacy: `{ github: url }` object) | derive **`github: { owner, repo }`** from the GitHub entry; other socials drop (report) |
-| `editLink.baseUrl` (`…/edit/<branch>/<subdir?>`) | `github: { owner, repo, branch }` — **and any repo sub-path after the branch → `github.dir`** (a docs-in-subfolder repo breaks every edit link without it) |
+| `editLink.baseUrl` (`…/edit/<branch>/<subdir?>`) | `github: { owner, repo, branch }` — **and any repo sub-path after the branch → `github.dir`** (a docs-in-subfolder repo breaks every edit link without it); **an origin other than `https://github.com` → `github.host`** (a GitHub Enterprise repo otherwise links to the public site) |
 | `sidebar` (array) | filesystem nav / `navigation.sidebar` (see below) |
 | `tableOfContents` (`false` or `{ minHeadingLevel, maxHeadingLevel }`) | `toc` — identical shape, 1:1 |
 | `markdown.headingLinks: false` | `markdown.headingAnchors: false` |

package/src/ai/agent-readability.ts

@@ -1,4 +1,5 @@
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import { repoUrl } from "../core/github.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
 import { absoluteUrl } from "../core/site-url.ts";
@@ -175,7 +176,7 @@ export const buildAgentReadability = (
     manifest.contentUsage = usage;
   }
   if (config.github) {
-    manifest.repository = `https://github.com/${config.github.owner}/${config.github.repo}`;
+    manifest.repository = repoUrl(config.github);
   }
 
   return manifest;

package/src/ai/ask-data.ts

@@ -10,7 +10,8 @@ import type { AskData } from "./ask-context.ts";
  * content is kept as Markdown so grounding sees fenced code examples — the model
  * answers "what does the config look like?" from the docs instead of declining.
  * The reader is an AI agent, so `<Visibility>` resolves for the agents audience
- * (web-only content removed, agents-only unwrapped), matching llms-full.txt.
+ * (web-only content removed, agents-only unwrapped) and components downlevel to
+ * Markdown, both matching llms-full.txt.
  */
 export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
   const documents = await buildSearchDocuments(project, {

package/src/ai/component-markdown.ts

@@ -3,6 +3,7 @@ import { mdxToMdast } from "satteri";
 
 import { parseYouTubeId } from "../components/content/youtube.ts";
 import type { ExampleLookup } from "../core/types.ts";
+import { MDX_FEATURES } from "../markdown/features.ts";
 
 /**
  * Downlevel Blume's MDX components to plain Markdown for agent-facing output
@@ -26,7 +27,8 @@ interface Offset {
   offset: number;
 }
 
-interface MdastNode {
+/** The structural slice of an mdast node the downlevel walk reads. */
+export interface MdastNode {
   attributes?: MdxAttribute[];
   children?: MdastNode[];
   name?: string;
@@ -80,8 +82,28 @@ export interface ComponentMarkdownChild extends EvaluatedProps {
   children: string;
 }
 
+/** One direct child of a component — a child component or prose — as Markdown. */
+export interface ComponentMarkdownBlock {
+  /**
+   * The child downleveled: a serializable component's rendering (through the
+   * registry, so a user override of that component applies), or — for prose,
+   * a component with no serializer, or one that declined — its source with
+   * any serializable descendants downleveled in place.
+   */
+  markdown: string;
+  /** The JSX name of a child component; `undefined` for prose. */
+  name?: string;
+}
+
 /** What a serializer receives for one component usage. */
 export interface ComponentMarkdownContext extends EvaluatedProps {
+  /**
+   * Every direct child of the element in document order, components and
+   * prose alike, each as a block of Markdown. For a container that is nothing
+   * but its contents — `<CardGroup>` — joining these with blank lines is the
+   * whole serializer.
+   */
+  childBlocks: () => ComponentMarkdownBlock[];
   /** Direct child components of `name`, each with evaluated props and body. */
   childComponents: (name: string) => ComponentMarkdownChild[];
   /** The element's body, downleveled and dedented (empty if self-closing). */
@@ -160,9 +182,10 @@ const readProps = (
   return { lossy, props };
 };
 
-const hasOffsets = (
-  node: MdastNode
-): node is MdastNode & { position: { end: Offset; start: Offset } } =>
+/** A node Satteri stamped with byte offsets. */
+type Positioned = MdastNode & { position: { end: Offset; start: Offset } };
+
+const hasOffsets = (node: MdastNode): node is Positioned =>
   typeof node.position?.start?.offset === "number" &&
   typeof node.position?.end?.offset === "number";
 
@@ -352,6 +375,80 @@ const tabs: ComponentMarkdown = ({ childComponents, children }) => {
     .join("\n\n");
 };
 
+/** Escape the brackets that would end a link's text early. */
+const linkText = (value: string): string =>
+  value.replaceAll(/[[\]]/gu, String.raw`\$&`);
+
+/**
+ * A link destination. Whitespace ends one, and a `)` ends one unless it is
+ * part of a balanced pair — so an href carrying either goes in the angle
+ * bracket form, where only `<` and `>` are special.
+ */
+const linkDestination = (href: string): string =>
+  /[\s()<>]/u.test(href)
+    ? `<${href.replaceAll(/[<>]/gu, String.raw`\$&`)}>`
+    : href;
+
+/** A text prop: a string, or a number stringified — `title={2024}` is a title. */
+const textProp = (value: EvaluatedValue): string => {
+  if (isString(value)) {
+    return value.trim();
+  }
+  return isNumber(value) ? String(value) : "";
+};
+
+/**
+ * A card is a link with a blurb, so that is what it becomes: the title as the
+ * link text, the body under it, and the call to action last — the order the
+ * card renders in. Shaped like {@link tabs}, a bold label over the body,
+ * rather than a heading: a card sits inside a page whose outline its author
+ * wrote, and a heading would add a level to it.
+ *
+ * The icon and image are presentation and drop out. A card with no title
+ * falls back to its `href`, and one with neither is just its body. `lossy`
+ * declines: a title or href recovered from an expression that would not
+ * evaluate is a link pointing somewhere wrong, which is worse than the
+ * visible JSX.
+ */
+const card: ComponentMarkdown = ({ children, lossy, props }) => {
+  if (lossy) {
+    return null;
+  }
+  const title = textProp(props.title);
+  const href = isString(props.href) ? props.href.trim() : "";
+  const body = children.trim();
+  const cta = textProp(props.cta);
+  const label = title || href;
+  if (label === "") {
+    // Nothing to head the card with, so it is whatever text it carries.
+    const rest = [body, cta].filter(Boolean).join("\n\n");
+    // Nothing but presentation left — keep the JSX rather than delete a card.
+    return rest === "" ? null : rest;
+  }
+  const head =
+    href === ""
+      ? `**${label}**`
+      : `**[${linkText(label)}](${linkDestination(href)})**`;
+  return [head, body, cta].filter(Boolean).join("\n\n");
+};
+
+/**
+ * `CardGroup` is the grid its cards sit in and carries no meaning of its own,
+ * so it becomes its contents: every direct child in order, each a block, a
+ * blank line between them. Built on `childBlocks` rather than extracting the
+ * cards so nothing the group holds is lost — a `Card` renders through the
+ * registry (a user override of `Card` applies in here too), a nested group
+ * recurses, prose between the cards stays, and a card that declines keeps its
+ * JSX as a block of its own instead of vanishing beside a rendered sibling.
+ * Passing the body slice through instead would leave each card's source
+ * indentation in the output and run one card's title straight on from the
+ * previous card's body as the same paragraph.
+ */
+const cardGroup: ComponentMarkdown = ({ childBlocks }) =>
+  childBlocks()
+    .map((block) => block.markdown)
+    .join("\n\n");
+
 const youtube: ComponentMarkdown = ({ props }) => {
   let input = "";
   if (isString(props.id)) {
@@ -407,6 +504,8 @@ export const exampleComponentSerializers = (examples: ExampleLookup) =>
  */
 const SERIALIZERS = {
   Callout: callout,
+  Card: card,
+  CardGroup: cardGroup,
   Steps: steps,
   Tabs: tabs,
   TypeTable: typeTable,
@@ -428,29 +527,37 @@ const componentHint = (registry: Record<string, ComponentMarkdown>): RegExp =>
 const BUILT_IN_HINT = componentHint(SERIALIZERS);
 
 /** One downlevel pass's inputs: the source, registry, and page metadata. */
-interface Walk {
+/** What a downlevel walk needs: the serializers, the page's front matter, and the source its nodes were parsed from. */
+export interface DownlevelWalk {
   frontmatter: Record<string, EvaluatedValue> | undefined;
   registry: Record<string, ComponentMarkdown>;
   source: string;
 }
+type Walk = DownlevelWalk;
+
+/** The serializer registry for a site: built-ins under a user's `ai.markdownComponents`. */
+export const componentRegistry = (
+  components?: Record<string, ComponentMarkdown>
+): Record<string, ComponentMarkdown> =>
+  components && Object.keys(components).length > 0
+    ? { ...SERIALIZERS, ...components }
+    : SERIALIZERS;
 
 /**
- * The element's body as Markdown: the verbatim source slice covering its
- * children, with any serializable descendant components downleveled in place.
- * Mutually recursive with {@link collectSplices} (a container's children may
- * hold further serializable components), hence the forward reference.
+ * A source slice as Markdown: the verbatim `[start, end)` range with any
+ * serializable component under `nodes` downleveled in place, dedented and
+ * trimmed. Mutually recursive with {@link collectSplices} (the nodes may hold
+ * further serializable components), hence the forward reference.
  */
-const renderChildren = (walk: Walk, node: MdastNode): string => {
-  const children = (node.children ?? []).filter(hasOffsets);
-  const [first] = children;
-  if (!first) {
-    return "";
-  }
-  const start = first.position.start.offset;
-  const end = children.at(-1)?.position.end.offset ?? start;
+const renderSlice = (
+  walk: Walk,
+  start: number,
+  end: number,
+  nodes: MdastNode[]
+): string => {
   const splices: Splice[] = [];
   // oxlint-disable-next-line no-use-before-define
-  collectSplices(walk, children, splices);
+  collectSplices(walk, nodes, splices);
   const spliced = applySplices(
     walk.source.slice(start, end),
     splices.map((splice) => ({
@@ -462,6 +569,45 @@ const renderChildren = (walk: Walk, node: MdastNode): string => {
   return dedent(spliced).trim();
 };
 
+/** The element's body as Markdown: the slice covering all of its children. */
+const renderChildren = (walk: Walk, node: MdastNode): string => {
+  const children = (node.children ?? []).filter(hasOffsets);
+  const [first] = children;
+  if (!first) {
+    return "";
+  }
+  const start = first.position.start.offset;
+  return renderSlice(
+    walk,
+    start,
+    children.at(-1)?.position.end.offset ?? start,
+    children
+  );
+};
+
+/**
+ * One direct child as a block of Markdown: a registered component's own
+ * rendering, else — prose, an unknown component, or one that declined — its
+ * source slice, the same choice {@link collectSplices} makes at the top level.
+ */
+const renderBlock = (walk: Walk, node: Positioned): string => {
+  const serializer =
+    isJsxElement(node) && node.name ? walk.registry[node.name] : undefined;
+  const text = serializer
+    ? // oxlint-disable-next-line no-use-before-define
+      serializeElement(serializer, walk, node)
+    : null;
+  return (
+    text ??
+    renderSlice(
+      walk,
+      node.position.start.offset,
+      node.position.end.offset,
+      node.children ?? []
+    )
+  );
+};
+
 /** Serialize one component usage, or `null` to keep its JSX verbatim. */
 const serializeElement = (
   serializer: ComponentMarkdown,
@@ -470,6 +616,11 @@ const serializeElement = (
 ): string | null =>
   serializer({
     ...readProps(node, walk.frontmatter),
+    childBlocks: () =>
+      (node.children ?? []).filter(hasOffsets).map((child) => ({
+        markdown: renderBlock(walk, child),
+        name: isJsxElement(child) ? child.name : undefined,
+      })),
     childComponents: (name) =>
       (node.children ?? [])
         .filter((child) => isJsxElement(child) && child.name === name)
@@ -487,26 +638,38 @@ const serializeElement = (
  * doesn't descend into it; when a serializer declines, the walk continues
  * inside so nested serializable components still convert.
  */
+/**
+ * Downlevel one parsed component to the Markdown its serializer emits, or
+ * `null` when the node isn't a component, has no serializer, or its
+ * serializer declines. `walk.source` must be the text `node` was parsed from.
+ */
+export const downlevelComponentNode = (
+  node: MdastNode,
+  walk: DownlevelWalk
+): string | null => {
+  const serializer =
+    node.type === "mdxJsxFlowElement" && node.name
+      ? walk.registry[node.name]
+      : undefined;
+  return serializer && hasOffsets(node)
+    ? serializeElement(serializer, walk, node)
+    : null;
+};
+
 const collectSplices = (
   walk: Walk,
   nodes: MdastNode[],
   out: Splice[]
 ): void => {
   for (const node of nodes) {
-    const serializer =
-      node.type === "mdxJsxFlowElement" && node.name
-        ? walk.registry[node.name]
-        : undefined;
-    if (serializer && hasOffsets(node)) {
-      const text = serializeElement(serializer, walk, node);
-      if (text !== null) {
-        out.push({
-          end: node.position.end.offset,
-          start: node.position.start.offset,
-          text,
-        });
-        continue;
-      }
+    const text = hasOffsets(node) ? downlevelComponentNode(node, walk) : null;
+    if (text !== null && hasOffsets(node)) {
+      out.push({
+        end: node.position.end.offset,
+        start: node.position.start.offset,
+        text,
+      });
+      continue;
     }
     collectSplices(walk, node.children ?? [], out);
   }
@@ -531,9 +694,9 @@ export const downlevelComponents = (
   components?: Record<string, ComponentMarkdown>,
   frontmatter?: Record<string, EvaluatedValue>
 ): string => {
-  const custom = components && Object.keys(components).length > 0;
-  const registry = custom ? { ...SERIALIZERS, ...components } : SERIALIZERS;
-  const hint = custom ? componentHint(registry) : BUILT_IN_HINT;
+  const registry = componentRegistry(components);
+  const hint =
+    registry === SERIALIZERS ? BUILT_IN_HINT : componentHint(registry);
   if (!hint.test(source)) {
     return source;
   }
@@ -541,7 +704,7 @@ export const downlevelComponents = (
   try {
     // SAFETY: MdastNode is a structural subset of Satteri's mdast output —
     // every node carries `type`, and the walk reads only optional fields.
-    tree = mdxToMdast(source) as MdastNode;
+    tree = mdxToMdast(source, { features: MDX_FEATURES }) as MdastNode;
   } catch {
     return source;
   }

package/src/ai/llms.ts

@@ -3,13 +3,16 @@ import { rewriteRelativeImages } from "../core/content-assets.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { absoluteUrl } from "../core/site-url.ts";
-import { readEntryText } from "../core/sources/read.ts";
+import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
+import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
 import {
   downlevelComponents,
   exampleComponentSerializers,
 } from "./component-markdown.ts";
+import { AGENT_SKILLS_DIR, AGENT_SKILLS_INDEX_PATH } from "./skills.ts";
+import type { SkillArtifact } from "./skills.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top —
@@ -21,6 +24,65 @@ const pageUrl = (route: string, site?: string, base = ""): string => {
   return encodeURI(site ? absoluteUrl(site, path) : path);
 };
 
+/** Inputs only the build has: the published skills, collected once per build. */
+export interface LlmsIndexOptions {
+  /**
+   * The Agent Skills the build publishes under `/.well-known/agent-skills/`,
+   * listed in their own section with each skill's description — which is
+   * where a skill says when to use it. Absent (empty) for the homepage
+   * Markdown mirror, which is synthesized before the skills are collected.
+   */
+  skills?: readonly SkillArtifact[];
+}
+
+/** A skill description on one line — SKILL.md frontmatter may wrap it. */
+const oneLine = (text: string): string => text.replaceAll(/\s+/gu, " ").trim();
+
+/**
+ * The "Agent resources" section: every machine-readable artifact the site
+ * publishes, so an agent that only reads llms.txt still finds the full
+ * Markdown dump, the per-page Markdown mirrors, the MCP server, the skills
+ * index, the API catalog, the readability manifest, and the sitemap. The
+ * same artifact set `agent-readability.json` indexes, in prose an agent can
+ * act on without a second fetch.
+ */
+const agentResourceLines = (project: BlumeProject): string[] => {
+  const { config } = project;
+  const { site } = config.deployment;
+  const url = (path: string): string =>
+    pageUrl(path, site, normalizeBasePath(config.deployment.base));
+  const lines = [
+    `- [llms-full.txt](${url("/llms-full.txt")}): The full Markdown of every page in one file.`,
+    `- [Page Markdown](${url("/index.md")}): Append \`.md\` to any page URL to fetch that page as raw Markdown.`,
+  ];
+  if (config.ai.mcp.enabled) {
+    lines.push(
+      `- [MCP server](${url(config.ai.mcp.route)}): Streamable HTTP Model Context Protocol server with search_docs, get_page, list_pages, and get_navigation tools, plus every page as a resource. Discovery document: ${url("/.well-known/mcp.json")}`
+    );
+  }
+  if (config.ai.skills) {
+    lines.push(
+      `- [Agent skills](${url(AGENT_SKILLS_INDEX_PATH)}): Agent Skills discovery index of the skills this site publishes.`
+    );
+  }
+  if (hasApiCatalog(config)) {
+    lines.push(
+      `- [API catalog](${url(API_CATALOG_PATH)}): RFC 9727 linkset of the APIs documented here.`
+    );
+  }
+  if (config.seo.agentReadability) {
+    lines.push(
+      `- [agent-readability.json](${url("/agent-readability.json")}): Manifest of every agent-facing artifact on this site.`
+    );
+  }
+  if (site && config.seo.sitemap) {
+    lines.push(
+      `- [Sitemap](${url("/sitemap.xml")}): Every indexable page URL with its last-modified date.`
+    );
+  }
+  return lines;
+};
+
 // Drafts, hidden, and ordinary `noindex` pages are excluded. Generated API
 // references keep crawler visibility (`noindex`) separate from LLM visibility
 // (`ai.exclude`), and are excluded wholesale when `ai.llmsTxt.openapi` is off.
@@ -88,7 +150,10 @@ const indexedNavigations = (
  * Also serves as the homepage's synthesized Markdown mirror when the home
  * route is a landing page (see `buildRawMarkdown`).
  */
-export const buildLlmsIndex = (project: BlumeProject): string => {
+export const buildLlmsIndex = (
+  project: BlumeProject,
+  options: LlmsIndexOptions = {}
+): string => {
   const { config } = project;
   const { site } = config.deployment;
   const base = normalizeBasePath(config.deployment.base);
@@ -187,10 +252,31 @@ export const buildLlmsIndex = (project: BlumeProject): string => {
     );
   }
 
+  // The published skills, each with its description — the one place a skill
+  // states when an agent should reach for it.
+  const skills = options.skills ?? [];
+  if (skills.length > 0) {
+    blocks.push(
+      "## Agent skills",
+      skills
+        .map(
+          (skill) =>
+            `- [${skill.name}](${pageUrl(`${AGENT_SKILLS_DIR}/${skill.path}`, site, base)}): ${oneLine(skill.description)}`
+        )
+        .join("\n")
+    );
+  }
+
+  blocks.push("## Agent resources", agentResourceLines(project).join("\n"));
+
   const header = config.description
     ? `# ${config.title}\n\n> ${config.description}`
     : `# ${config.title}`;
-  return `${[header, ...blocks].join("\n\n")}\n`;
+  // `details` is the llms.txt spec's free-form block between the summary and
+  // the file sections — "when to use this" guidance in the site's own words.
+  const { details } = config.ai.llmsTxt;
+  const lead = details ? `${header}\n\n${details}` : header;
+  return `${[lead, ...blocks].join("\n\n")}\n`;
 };
 
 /** Build `llms-full.txt`: the full Markdown body of every current-docs page. */
@@ -208,7 +294,7 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
 
   const sections = await Promise.all(
     pages.map(async (page) => {
-      let raw = await readEntryText(project, page);
+      let raw = await readExpandedEntryText(project, page);
       // Colocated `./image.png` references resolve to nothing for a reader of
       // llms-full.txt; point them at the served originals instead.
       if (page.sourcePath) {
@@ -246,8 +332,9 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
 
 /** Build both LLM text artifacts for a project. */
 export const buildLlmsFiles = async (
-  project: BlumeProject
+  project: BlumeProject,
+  options: LlmsIndexOptions = {}
 ): Promise<{ index: string; full: string }> => ({
   full: await buildFull(project),
-  index: buildLlmsIndex(project),
+  index: buildLlmsIndex(project, options),
 });