blume 2.1.3 → 2.2.1

package/dist/types/ai/operation-details.d.ts

@@ -0,0 +1,39 @@
+import type { ResponseLike } from "../components/openapi/example-panels.ts";
+import type { MediaLike } from "../components/openapi/helpers.ts";
+import type { ApiDocument } from "../openapi/model.ts";
+/**
+ * The body and responses of an OpenAPI operation as compact Markdown, for the
+ * agent-facing copy of its page (`<route>.md`, llms-full.txt, MCP
+ * `get_page`): the request body's media type and top-level properties, its
+ * example (every named one), each response's status and description, and
+ * the examples the spec records. Without these an agent read an endpoint
+ * with no word of what to send or what comes back, though the spec, and the
+ * page, had both. Built from the helpers the page's own components use, so
+ * the two can't disagree: the same JSON-ish media type, the same examples,
+ * `readOnly` and `writeOnly` properties left out the same way.
+ *
+ * Kept compact: properties one level deep (an example shows the rest), and
+ * a sampled response example only for the first success response that
+ * records none, since error bodies often all share one schema.
+ */
+/** A request body, `$ref` resolved. */
+interface RequestBodyLike {
+    description?: string;
+    required?: boolean;
+    content?: Record<string, MediaLike>;
+}
+/** The operation fields read here. */
+export interface OperationParts {
+    requestBody?: RequestBodyLike & {
+        $ref?: string;
+    };
+    responses?: Record<string, ResponseLike & {
+        $ref?: string;
+    }>;
+}
+/**
+ * An operation's body and responses as Markdown blocks, `$ref`s to
+ * `components` resolved, ready to join with blank lines.
+ */
+export declare const operationDetails: (document: ApiDocument, operation: OperationParts, webhook: boolean) => string[];
+export {};

package/dist/types/ai/relative-links.d.ts

@@ -13,7 +13,9 @@ import type { BlumeProject } from "../core/project-graph.ts";
  * `basePath` prefix, a public file (`/spec.pdf`) or image the
  * `deployment.base` alone, and, on a page in a prefixed locale, a page link
  * that locale's copy of the route when it is served
- * (`components/layout/LocaleLinks.astro`). Inline links, images, component
+ * (`components/layout/LocaleLinks.astro`). A root-relative link to a content
+ * file (`/guide/new.md`) lands on that file's page, as on the rendered page
+ * (`resolveRootFileHref`). Inline links, images, component
  * `href`s, and reference definitions are rewritten; fenced and inline code,
  * relative images and asset links, and external URLs are left as written.
  */

package/dist/types/ai/serializers.d.ts

@@ -3,11 +3,13 @@ import type { BlumeProject } from "../core/project-graph.ts";
  * Every serializer a project brings to a downlevel pass, layered once for all
  * the agent surfaces (`<route>.md`, llms-full.txt, the search and assistant
  * corpora): the built-in families that read project data — examples, then the
- * API reference — under the user's `agents.markdownComponents`, which is spread
- * last so an entry of the same name still wins. One layering, so a new family
- * or a new surface cannot leave one consumer printing raw JSX.
+ * API reference, then the changelog index — under the user's
+ * `agents.markdownComponents`, which is spread last so an entry of the same
+ * name still wins. One layering, so a new family or a new surface cannot leave
+ * one consumer printing raw JSX.
  */
-export declare const projectComponentSerializers: (project: Pick<BlumeProject, "config" | "examples" | "sources">) => {
+export declare const projectComponentSerializers: (project: BlumeProject) => {
+    Changelog: () => string;
     ApiOverview: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
     ApiTagOperations: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
     Operation: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;

package/dist/types/analytics/head.d.ts

@@ -25,6 +25,8 @@ export type HeadNode = (HeadScript & {
 /**
  * Map the configured adapters to what `Analytics.astro` renders, in declared
  * order. A second `vercel()` is dropped — two copies of the component would
- * count every pageview twice — so the first one keeps its position.
+ * count every pageview twice — so the first one keeps its position. `base` is
+ * the deployment base a `script()` adapter's root-relative `src` is served
+ * under.
  */
-export declare const analyticsHead: (adapters: AnalyticsAdapter[]) => HeadNode[];
+export declare const analyticsHead: (adapters: AnalyticsAdapter[], base?: string) => HeadNode[];

package/dist/types/analytics/script.d.ts

@@ -42,5 +42,11 @@ export declare const scriptAdapterSchema: z.ZodObject<{
  * passthrough here — every entry lands on the tag as-is.
  */
 export declare const script: (options: ScriptOptions) => ScriptAdapter;
-/** The tag. Explicit `src`/`strategy` win over a same-named spread attribute. */
-export declare const scriptHead: (options: ScriptOptions) => HeadScript[];
+/**
+ * The tag. Explicit `src`/`strategy` win over a same-named spread attribute.
+ * A root-relative `src` (`/js/x.js`, a file in `public/`) is served under the
+ * deployment `base`, so it gets the base the way a link does; one already
+ * under it is left alone, and absolute and protocol-relative URLs pass
+ * through.
+ */
+export declare const scriptHead: (options: ScriptOptions, base: string) => HeadScript[];

package/dist/types/components/content/youtube.d.ts

@@ -9,6 +9,12 @@
  * nothing rather than a broken embed.
  */
 export declare const parseYouTubeId: (input: string) => string | null;
+/**
+ * The playlist id of a YouTube playlist URL (`/embed/videoseries?list=…` or
+ * `/playlist?list=…`), or `null` for anything else — a video URL that also
+ * carries a `list` (`watch?v=…&list=…`) is that video.
+ */
+export declare const parseYouTubePlaylist: (input: string) => string | null;
 /**
  * Build a privacy-enhanced (`youtube-nocookie.com`) embed URL, optionally
  * starting at `start` seconds.
@@ -16,3 +22,17 @@ export declare const parseYouTubeId: (input: string) => string | null;
 export declare const youtubeEmbedUrl: (id: string, options?: {
     start?: number;
 }) => string;
+/**
+ * The privacy-enhanced embed URL for a playlist, optionally starting its
+ * first video at `start` seconds.
+ */
+export declare const youtubePlaylistEmbedUrl: (list: string, options?: {
+    start?: number;
+}) => string;
+/**
+ * The embed URL for a `<YouTube>`'s `id` or `url`: a video, else a playlist,
+ * else `null` when the input names neither.
+ */
+export declare const youtubeEmbedSrc: (input: string, options?: {
+    start?: number;
+}) => string | null;

package/dist/types/components/layout/nav-utils.d.ts

@@ -73,6 +73,14 @@ export declare const getPagination: (flat: FlatPage[], route: string) => {
 export type NavGroup = Extract<NavNode, {
     kind: "group";
 }>;
+/**
+ * Whether a `group`-mode disclosure renders open: it holds the current page,
+ * its meta forces it open (`collapsed: false`), or it is the only row at the
+ * top of the sidebar, where starting closed would leave a sidebar of one row
+ * to click before any link shows (a wrapper folder around every page). An
+ * explicit `collapsed: true` keeps that lone group closed.
+ */
+export declare const groupStartsOpen: (group: NavGroup, active: boolean, lone: boolean) => boolean;
 /**
  * The group whose own page `route` is, when that page lists the group's
  * pages: its `directory` (inherited when the group sets none) is `card` or

package/dist/types/components/openapi/example-panels.d.ts

@@ -0,0 +1,33 @@
+import type { ComponentsLike, MediaLike, SchemaLike, SpecValue } from "./helpers.ts";
+/**
+ * The example tabs of an operation's rail (`RequestPanel.astro`): one per
+ * response status, or per webhook payload media type — and one per named
+ * example where its `examples` map names two or more, labeled by the
+ * example's `summary` (else its key) after the status or media type, so
+ * every recorded example shows, under its name. Values are left for the
+ * component to highlight.
+ */
+/** One tab before highlighting. */
+export interface ExamplePanel {
+    key: string;
+    label: string;
+    /** The status or media type the tab is under. */
+    name: string;
+    /** The media type the value is an example of. */
+    type: string;
+    /** The example, or `null`/`undefined` when there's none to show. */
+    value: SpecValue;
+    /** What the tab says when there's no example. */
+    text: string;
+}
+/** A response: its description and its body's media types. */
+export interface ResponseLike {
+    description?: string;
+    content?: Record<string, MediaLike>;
+}
+/** The media entry a body shows: the first JSON-ish one, else the first. */
+export declare const preferredMedia: (content?: Record<string, MediaLike>) => [string, MediaLike] | undefined;
+/** The Response tabs: per status, per named example. */
+export declare const responsePanels: (responses: Record<string, ResponseLike>, schemas: Record<string, SchemaLike>, components?: ComponentsLike) => ExamplePanel[];
+/** A webhook's Payload tabs: per media type, per named example. */
+export declare const payloadPanels: (payload: Record<string, MediaLike> | undefined, schemas: Record<string, SchemaLike>, components?: ComponentsLike) => ExamplePanel[];

package/dist/types/components/openapi/helpers.d.ts

@@ -83,7 +83,10 @@ export declare const soleAllOfMember: (schema: SchemaLike) => SchemaLike | undef
 /**
  * Resolve one level of `$ref` against the document's component schemas. A
  * single-member `allOf` wrapper resolves like its member, with the wrapper's
- * own keywords on top: its `description` is about this field.
+ * own keywords on top: its `description` is about this field. So does a
+ * `$ref` with keywords beside it, which OpenAPI 3.1 allows and .NET writes
+ * for every enum-typed property: the `description` beside the `$ref` is the
+ * property's, the referenced one the type's.
  */
 export declare const resolveSchema: (schemas: Record<string, SchemaLike>, schema?: SchemaLike) => SchemaLike;
 /**
@@ -121,16 +124,30 @@ export interface ObjectPropertySet {
  * the merged required set.
  */
 export declare const objectProperties: (schema: SchemaLike, schemas: Record<string, SchemaLike>) => ObjectPropertySet;
+/** Which way an example travels: to the API, or back from it. */
+export type ExampleDirection = "request" | "response";
+/**
+ * An example value with the properties that don't travel `direction` left
+ * out, at every depth its schema describes: `readOnly` ones from a request,
+ * which the server sets, and `writeOnly` ones from a response, which it
+ * never returns. openapi-sampler skips those only in the values it builds; a
+ * declared example (a model's `example`, which TypeSpec writes, or a media
+ * type's) keeps them, so a request sample would send the model's `id`. A
+ * property the schema doesn't describe stays as written.
+ */
+export declare const forDirection: (value: SpecValue, schema: SchemaLike | undefined, schemas: Record<string, SchemaLike>, direction: ExampleDirection) => SpecValue;
 /**
  * Build a representative example value for a schema via openapi-sampler
  * (Redoc's generator): declared `example`/`const`/`default`/`enum` values
- * win, formats produce realistic placeholders (`email`, `uuid`, `date-time`),
- * and circular `$ref` chains — which keeping refs intact allows — terminate
- * safely. A request sample skips `readOnly` fields (a server-generated field
- * has no place in one); a response sample skips `writeOnly` fields (a
- * password the client sends never comes back) and keeps the `readOnly` ones.
+ * win, a value beside a `$ref` included, formats produce realistic
+ * placeholders (`email`, `uuid`, `date-time`), and circular `$ref` chains —
+ * which keeping refs intact allows — terminate safely. A request sample
+ * leaves out `readOnly` fields (a server-generated field has no place in
+ * one); a response sample leaves out `writeOnly` fields (a password the
+ * client sends never comes back) and keeps the `readOnly` ones. That holds
+ * inside a declared value the sampler copies too (see {@link forDirection}).
  */
-export declare const exampleValue: (schema: SchemaLike | undefined, schemas: Record<string, SchemaLike>, direction?: "request" | "response") => SpecValue;
+export declare const exampleValue: (schema: SchemaLike | undefined, schemas: Record<string, SchemaLike>, direction?: ExampleDirection) => SpecValue;
 /** Where an author can declare an example: a parameter or a media type. */
 export interface ExampleCarrier {
     example?: SpecValue;
@@ -146,13 +163,38 @@ export interface ExampleCarrier {
  * declared.
  */
 export declare const declaredExample: (carrier: ExampleCarrier, components?: ComponentsLike) => SpecValue;
+/** A media type: the schema of a body and the examples it declares. */
+export type MediaLike = ExampleCarrier & {
+    schema?: SchemaLike;
+};
+/**
+ * A media type's example for a body travelling `direction`: the declared
+ * one, else a sample built from its schema, with the properties that don't
+ * travel that way left out (see {@link forDirection}).
+ */
+export declare const mediaExample: (media: MediaLike, schemas: Record<string, SchemaLike>, direction: ExampleDirection, components?: ComponentsLike) => SpecValue;
 /**
  * A response media type's example for the Response panel: the declared one,
  * else a sample built for the response direction (`readOnly` kept,
- * `writeOnly` skipped).
+ * `writeOnly` left out).
  */
-export declare const responseExample: (media: ExampleCarrier & {
-    schema?: SchemaLike;
-}, schemas: Record<string, SchemaLike>, components?: ComponentsLike) => SpecValue;
+export declare const responseExample: (media: MediaLike, schemas: Record<string, SchemaLike>, components?: ComponentsLike) => SpecValue;
+/** One of a media type's named examples, as a tab or the Markdown copy shows it. */
+export interface NamedExample {
+    /** The example's key in the `examples` map. */
+    key: string;
+    /** Its `summary`, else its key. */
+    label: string;
+    value: SpecValue;
+}
+/**
+ * Every example a media type's `examples` map names, in order, `$ref`s to
+ * `#/components/examples` resolved, each labeled by its `summary` or else
+ * its key, with the properties that don't travel `direction` left out. Empty
+ * unless the map names two or more: Scalar's upgrade files a 3.0 `example`
+ * as the one entry `default`, which is no name to show, and a lone example
+ * is the one {@link mediaExample} already gives.
+ */
+export declare const namedExamples: (media: MediaLike, schemas: Record<string, SchemaLike>, direction: ExampleDirection, components?: ComponentsLike) => NamedExample[];
 /** Pretty-print a JSON value for an example/code block. */
 export declare const toJson: <T>(value: T) => string;

package/dist/types/components/openapi/snippets.d.ts

@@ -53,8 +53,14 @@ export interface SampleLanguageInfo {
 export declare const sampleLanguageInfo: (raw: string) => SampleLanguageInfo | null;
 /** `openapi()`'s default `codeSamples`, which hand-written endpoint pages always use. */
 export declare const DEFAULT_SAMPLE_LANGUAGES: string[];
+/**
+ * The configured ids Blume generates no sample for, as written: the ones
+ * {@link sampleLanguages} drops, which the reference source warns about.
+ */
+export declare const unknownSampleLanguages: (ids: string[] | false) => string[];
 /**
  * The sample languages to render, resolved from config ids (unknown ids
- * dropped), in order. `false` and an empty list both render none.
+ * dropped, with a warning from the reference source), in order. `false` and
+ * an empty list both render none.
  */
 export declare const sampleLanguages: (ids: string[] | false) => SampleLanguage[];

package/dist/types/core/alert-diagnostics.d.ts

@@ -0,0 +1,10 @@
+import type { SourceEntry } from "./sources/types.ts";
+import type { Diagnostic } from "./types.ts";
+/**
+ * Warn about GitHub alerts (`> [!NOTE]`) in an `.md` entry, which renders
+ * them as plain quotes that show the marker as text: alerts become callouts
+ * only in `.mdx`, where Blume renders components (see
+ * `markdown/github-alerts.ts`). Lines point into the file the author wrote, a
+ * partial's own file for an alert an `<include>` brought in.
+ */
+export declare const alertDiagnostics: (entry: SourceEntry, sourceName: string) => Diagnostic[];

package/dist/types/core/builtin-tags.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The MDX component tags Blume ships (the keys of the catch-all's component map,
+ * plus composed sub-parts like `Color.Item`/`Tree.File`). Used by the
+ * missing-component diagnostic to tell an unknown `<Tag>` from a built-in. Keep
+ * in sync with the component map in `astro/templates.ts`.
+ */
+export declare const BUILTIN_MDX_TAGS: Set<string>;
+/**
+ * The props each built-in that shows its children takes, keyed by MDX tag. A
+ * childless use with any other prop renders without the content its author
+ * meant it to carry (VitePress writes `<Badge type="tip" text="beta" />`, and
+ * Blume's Badge shows only its children), which the unknown-prop diagnostic
+ * reports. Each list is the component's own `Props` (or what it reads from
+ * `Astro.props`); a test checks them against the `.astro` files.
+ */
+export declare const BUILTIN_CHILD_PROPS: ReadonlyMap<string, readonly string[]>;

package/dist/types/core/changelog-list.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The policy the changelog index lists by, shared by the surfaces that build
+ * it: the `<Changelog />` component (reading Astro collection entries) and
+ * `ai/changelog-markdown.ts` (reading the build-time page graph for the
+ * `/changelog.md` mirror and MCP `get_page`).
+ *
+ * The data sources genuinely differ — a collection entry on the Astro side, a
+ * `PageRecord` on the Node side — so what lives here is the *decisions*, not
+ * the access: which date a row carries, what order rows come in, and how they
+ * fall into year groups. Keeping them in one place is what stops the rendered
+ * page and the Markdown an agent reads from drifting apart.
+ */
+/**
+ * A changelog entry's date, from `date` or the `changelog.date` it may live
+ * under instead. Front matter hands either a `Date` (an unquoted YAML date) or
+ * a string, and an unparseable value is treated as no date at all rather than
+ * failing the build — a malformed date costs the row its stamp and its year
+ * group, not the page.
+ */
+export declare const parseChangelogDate: (value: Date | string | null | undefined) => Date | null;
+/**
+ * Newest first. An undated entry sorts as the epoch, so undated rows collect
+ * at the end of the list (and, through {@link groupChangelogYears}, into a
+ * final group with no year label).
+ */
+export declare const compareChangelogDates: (a: Date | null, b: Date | null) => number;
+/** One year's run of rows. `year` is `null` for the undated group. */
+export interface ChangelogYearGroup<T> {
+    items: T[];
+    year: string | null;
+}
+/**
+ * Consecutive rows sharing a year, in list order, so the index reads as a year
+ * rail beside its rows. Runs are consecutive rather than keyed, which matters
+ * only for a list that isn't sorted by date: such a list keeps its order and
+ * repeats the year heading instead of silently regrouping around it.
+ *
+ * `yearOf` returns the label the surface wants — a locale-formatted year on the
+ * rendered page, a plain number in Markdown — or `null` for an undated row.
+ */
+export declare const groupChangelogYears: <T>(items: T[], yearOf: (item: T) => string | null) => ChangelogYearGroup<T>[];
+/**
+ * Make each row's anchor unique. Repeated labels slug to the same id (two
+ * entries with neither a title nor a version both fall back to "update"), so
+ * the later ones take a `-2`, `-3`, … suffix and the first keeps the plain
+ * slug — every row ends up with its own hash anchor.
+ */
+export declare const uniqueAnchorIds: (ids: string[]) => string[];

package/dist/types/core/closest-match.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The candidate closest to `name`, when it's close enough to be the likely
+ * intent: at most two edits away, and fewer edits than half the candidate's
+ * length, so a short typo doesn't "suggest" an unrelated short word.
+ */
+export declare const closestMatch: (name: string, candidates: readonly string[]) => string | undefined;

package/dist/types/core/code-fence-diagnostics.d.ts

@@ -0,0 +1,18 @@
+import type { SourceEntry } from "./sources/types.ts";
+import type { Diagnostic } from "./types.ts";
+/**
+ * Warn about code fences that don't render as their author meant:
+ *
+ * - `BLUME_UNKNOWN_CODE_LANGUAGE`: a language Shiki doesn't know, so the block
+ *   renders as plain text. Shiki itself only logs a console line naming the
+ *   language, with no page or line.
+ * - `BLUME_CODE_FENCE_OPTION`: an option another docs tool reads, like MkDocs'
+ *   `hl_lines="2 3"`, Docusaurus' `showLineNumbers`, Mintlify's `lines`, or
+ *   rustdoc's `no_run`, which Blume ignores. None of them becomes part of the
+ *   block's title. The suggestion gives the Blume spelling, or says to remove
+ *   an option Blume has no use for.
+ *
+ * Lines point into the file the author wrote, a partial's own file for a
+ * fence an `<include>` brought in.
+ */
+export declare const codeFenceDiagnostics: (entry: SourceEntry, sourceName: string) => Diagnostic[];

package/dist/types/core/code-fences.d.ts

@@ -1,11 +1,18 @@
-/** The open fence's delimiter char and run length, or null outside one. */
+/**
+ * The open fence's delimiter char, its run length, and the block-quote depth
+ * it opened at, or null outside one.
+ */
 export type FenceState = {
     delimiter: "`" | "~";
     length: number;
+    quotes: number;
 } | null;
 /**
  * Advance the fenced-code state for one line: an opening fence records its
  * delimiter and run length, only a bare run of the same character at least as
  * long closes it (CommonMark), and any other line leaves the state untouched.
+ * A fence inside block quotes is read past the quote markers it opened under,
+ * and a line without them ends the quote, and the fence with it: code takes
+ * no lazy continuation lines (CommonMark).
  */
 export declare const nextFenceState: (line: string, fence: FenceState) => FenceState;

package/dist/types/core/config-input.d.ts

@@ -13,7 +13,7 @@ import type { AnySearchAdapter } from "../search/adapters/registry.ts";
 import type { SourceAdapterInput } from "../sources/registry.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type { FooterSocial } from "./footer.ts";
-import type { OpenInChatProvider, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
+import type { McpClient, McpCustomClient, OpenInChatProvider, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
 import type { StandardSchema } from "./standard-schema.ts";
 /**
  * The public, hand-documented authoring type for `blume.config.ts`.
@@ -115,9 +115,15 @@ export interface FooterLink {
 }
 /**
  * The site footer, below the content on every page: a row of links on one
- * side, and social profile icons on the other.
+ * side, social profile icons on the other, and a copyright line centered
+ * between them.
  */
 export interface FooterConfig {
+    /**
+     * A line of plain text centered between the links and the icons, like
+     * `© 2026 Acme, Inc.`, or a map of locale code to text.
+     */
+    copyright?: LocalizableLabel;
     /** Links in one row, left to right. */
     links?: FooterLink[];
     /**
@@ -147,7 +153,7 @@ export interface ChangelogConfig {
 export interface ContentConfig {
     /** Default page `type` for content that sets none. Defaults to `doc`. */
     defaultType?: string;
-    /** Glob patterns to ignore. Defaults to `["**\/_*", "**\/.*"]`. Shorthand; not allowed beside `sources`. */
+    /** Glob patterns to ignore, on top of `["**\/_*", "**\/.*"]`; a `!pattern` entry stops ignoring that pattern, a default included. Shorthand; not allowed beside `sources`. */
     exclude?: string[];
     /** Glob patterns to include. Defaults to `["**\/*.{md,mdx}"]`. Shorthand; not allowed beside `sources`. */
     include?: string[];
@@ -638,6 +644,32 @@ export interface LlmsTxtConfig {
 }
 /** Expose the docs as an MCP server for connecting agents. */
 export interface McpConfig {
+    /**
+     * The clients the "Connect to MCP" page action installs the server into,
+     * beside its "Copy server URL" row. Defaults to `true` (every built-in
+     * client). Set `false` to list none, or list built-in keys and your own
+     * clients, in order. A custom client's `command` is copied with `{name}`
+     * (the server name as an id) and `{url}` (the server's URL) filled in; its
+     * `label` localizes like a header link's, and `icon` defaults to `terminal`.
+     *
+     * ```ts
+     * agents: {
+     *   mcp: {
+     *     enabled: true,
+     *     clients: [
+     *       "claude-code",
+     *       {
+     *         label: "Copy Copilot CLI command",
+     *         command: "copilot mcp add --transport http {name} {url}",
+     *         icon: "terminal",
+     *       },
+     *       "vscode",
+     *     ],
+     *   },
+     * }
+     * ```
+     */
+    clients?: boolean | (McpClient | McpCustomClient)[];
     /** Turn the MCP server on. Defaults to `false`. */
     enabled?: boolean;
     /** Optional system hint passed to connecting agents. */
@@ -1408,8 +1440,8 @@ export interface BlumeConfig {
      */
     feedback?: boolean | FeedbackConfig;
     /**
-     * The site footer: social profile icons and up to four link columns. Unset,
-     * the site has no footer.
+     * The site footer: a copyright line, a row of links, and social profile
+     * icons. Unset, the site has no footer.
      */
     footer?: FooterConfig;
     /** Opt-in custom frontmatter keys, validated by schemas you supply. */
@@ -1438,7 +1470,7 @@ export interface BlumeConfig {
      * Limit how often one reader (by IP address) can call the server routes —
      * the assistant, the API playground proxy, server-side search — with an
      * adapter from `blume/ratelimit`: `memory()` (the default, 30 requests per
-     * 10 minutes), `upstash()`, or `cloudflare()`. `false` turns it off.
+     * 10 minutes), `upstash()`, `cloudflare()`, or `unkey()`. `false` turns it off.
      */
     rateLimit?: false | RateLimitAdapter;
     /** React island behavior (compiler auto-memoization). */

package/dist/types/core/content-assets.d.ts

@@ -10,8 +10,15 @@ import type { PageRecord } from "./types.ts";
  * `/blume-assets/content/<project-relative path>` by a generated endpoint (see
  * `contentAssetsEndpointTemplate`), and these helpers rewrite the relative
  * references in agent-facing output to that URL.
+ *
+ * Other files beside a page are published the same way: a link to one
+ * (`[spec](./spec.pdf)`, a reference definition), a raw HTML or `.mdx`
+ * element's `src` (`<img src="./diagram.png">`, `<video>`, `<source>`,
+ * `<audio>`), and an `<a>`'s or a component's `href`. Nothing else serves
+ * them, so the HTML render points those at the same URLs (see
+ * `markdown/content-assets.ts`).
  */
-/** The endpoint route prefix colocated content images are served under. */
+/** The endpoint route prefix colocated content files are served under. */
 export declare const CONTENT_ASSETS_PREFIX = "/blume-assets/content";
 /**
  * The endpoint param a colocated image is served under: its project-relative
@@ -21,29 +28,20 @@ export declare const CONTENT_ASSETS_PREFIX = "/blume-assets/content";
  */
 export declare const contentAssetParam: (projectRoot: string, absPath: string) => string;
 /**
- * Whether a target is *shaped* like a colocated image reference: a relative
- * filesystem path with an image extension. Exported so link validation can
- * tell "not a colocated candidate" apart from "a candidate that resolves
- * nowhere" — the former falls through to the public-dir probe, the latter is
- * a broken reference beside the page source.
+ * The URL a colocated image's endpoint param is served at, under
+ * `deployment.base` when set, encoded for a Markdown or HTML URL with its `/`
+ * separators kept.
  */
-export declare const isRelativeImageTarget: (target: string) => boolean;
+export declare const contentAssetUrl: (param: string, deployBase?: string) => string;
 /**
- * Resolve one image target against its page's directory. Returns the absolute
- * file path when the target is relative, is an image, and exists on disk —
- * anything else (remote URLs, `public/` absolutes, broken refs, code-block
- * examples that happen to look like paths) is null and left untouched. Shared
- * with link validation, so what counts as a colocated image is decided once.
- */
-export declare const resolveRelativeImage: (sourceDir: string, target: string) => string | null;
-/**
- * Rewrite a page's relative image references to their served
+ * Rewrite a page's relative image references, and its links and element
+ * URLs naming other files beside it, to their served
  * `/blume-assets/content/…` URLs (under `deployment.base` when set). Fenced
  * code blocks and inline code are skipped; only references whose file actually
  * exists next to the source are touched. `register` observes each rewritten
  * asset so a caller can accumulate the files the endpoint must serve.
  */
-export declare const rewriteRelativeImages: (options: {
+export declare const rewriteRelativeAssets: (options: {
     source: string;
     sourcePath: string;
     projectRoot: string;
@@ -51,7 +49,7 @@ export declare const rewriteRelativeImages: (options: {
     register?: (param: string, absPath: string) => void;
 }) => string;
 /**
- * Every colocated image the project's pages reference, keyed by endpoint param.
+ * Every colocated file the project's pages reference, keyed by endpoint param.
  * Serialized to `generated/content-assets.json`, which the
  * `/blume-assets/[...asset]` endpoint reads to serve the original files. Runs
  * the same rewrite the agent-Markdown builders apply — over the same

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

@@ -193,7 +193,7 @@ export interface BlumeDataConfig {
     feedback: boolean;
     /** Whether the rating asks for a written comment after it (`feedback.comments`). */
     feedbackComments: boolean;
-    /** `footer`: social profile icons and link columns, or `null` when unset. */
+    /** `footer`: the copyright line, links, and social profile icons, or `null` when unset. */
     footer: ResolvedConfig["footer"] | null;
     /**
      * Repo coordinates for content components that address the API or build
@@ -217,8 +217,12 @@ export interface BlumeDataConfig {
     /** `markdown.imageZoom`: click-to-zoom content images. */
     imageZoom: boolean;
     logo: BlumeLogo | null;
-    /** Hosted MCP server, or `null` when MCP is off. */
+    /**
+     * Hosted MCP server, or `null` when MCP is off, with the clients its
+     * "Connect to MCP" page action lists (`agents.mcp.clients`), in order.
+     */
     mcp: {
+        clients: ResolvedConfig["agents"]["mcp"]["clients"];
         name: string;
         route: string;
     } | null;

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

@@ -10,6 +10,20 @@ export declare const createDiagnostic: (diagnostic: Diagnostic) => Diagnostic;
 export declare const resolveDocsUrl: (code: string) => string | undefined;
 /** Fill in `docsUrl` from the code map where a diagnostic doesn't set its own. */
 export declare const enrichDiagnostic: (diagnostic: Diagnostic) => Diagnostic;
+/**
+ * Best-effort source position for a Zod issue path (e.g. `["seo", "title"]`,
+ * `["redirects", 2, "status"]`) in the raw config / frontmatter text. Narrows
+ * segment by segment: a key is found among its parent's own entries (or, where
+ * there are no brackets, in the parent's indented lines), an index picks that
+ * element of an array literal. A segment that isn't there — a missing key —
+ * stops the walk at its parent, so the position never escapes into a sibling.
+ * Returns 1-based line/column, or undefined when not even the first segment
+ * matches.
+ */
+export declare const locatePath: (source: string, path: readonly (string | number)[]) => {
+    column: number;
+    line: number;
+} | undefined;
 /**
  * Locate a front matter key in a content file, e.g. `["seo", "description"]` in
  * `docs/api.mdx`. Scoped to the front matter block so a `title:` written in the