blume 1.1.0 → 1.1.1

package/dist/types/ai/component-markdown.d.ts

@@ -14,6 +14,12 @@ export interface ComponentMarkdownContext extends EvaluatedProps {
     childComponents: (name: string) => ComponentMarkdownChild[];
     /** The element's body, downleveled and dedented (empty if self-closing). */
     children: string;
+    /**
+     * The page's parsed front-matter (empty when the caller has none). Lets a
+     * serializer read page metadata directly, even when a prop expression is
+     * not statically evaluable.
+     */
+    frontmatter: Record<string, unknown>;
 }
 /**
  * A component's Markdown serializer. Return the replacement Markdown, or
@@ -29,6 +35,11 @@ export type ComponentMarkdown = (context: ComponentMarkdownContext) => string |
  * `components` adds user serializers from `ai.markdownComponents`, layered
  * over the built-ins: a same-name entry replaces the built-in serializer, and
  * one that always returns `null` effectively opts that component out.
+ *
+ * `frontmatter` is the page's parsed front-matter data. It is put in scope
+ * when evaluating attribute expressions — so `prop={frontmatter.status}`
+ * resolves the way it does when Astro renders the page — and handed to
+ * serializers on their context.
  */
-export declare const downlevelComponents: (source: string, components?: Record<string, ComponentMarkdown>) => string;
+export declare const downlevelComponents: (source: string, components?: Record<string, ComponentMarkdown>, frontmatter?: Record<string, unknown>) => string;
 export {};

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

@@ -487,9 +487,11 @@ export interface AiConfig {
     /**
      * Markdown serializers for custom components in agent-facing output (the
      * `.md` mirror, `llms-full.txt`, MCP `get_page`), keyed by JSX name. Each
-     * receives the component's statically-evaluated `props` and downleveled
-     * `children` and returns replacement Markdown — or `null` to leave the JSX
-     * verbatim. A same-name entry replaces a built-in serializer.
+     * receives the component's statically-evaluated `props` (with the page's
+     * `frontmatter` in scope, so `prop={frontmatter.status}` resolves), its
+     * downleveled `children`, and the page's `frontmatter` data, and returns
+     * replacement Markdown — or `null` to leave the JSX verbatim. A same-name
+     * entry replaces a built-in serializer.
      *
      * These live in `blume.config.ts` (which is executed at build time), not in
      * `components.tsx` (which is only statically analyzed, never run).
@@ -654,6 +656,13 @@ export interface OgConfig {
     logo?: string;
     /** Optional generated-card colors. */
     palette?: OgPaletteConfig;
+    /**
+     * Card headlines for custom `.astro` pages, keyed by route (`"/"`, `"/cli"`).
+     * A custom page has no frontmatter to read, so its card is otherwise titled
+     * by humanizing its last URL segment (`/cli` → "Cli"); an entry here wins.
+     * Content pages always take their card headline from the page title.
+     */
+    titles?: Record<string, string>;
 }
 /** Discoverability: OG images, feeds, sitemap, robots, and structured data. */
 export interface SeoConfig {

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

@@ -2529,6 +2529,13 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             }>>;
+            /**
+             * Card headlines for custom `.astro` pages, keyed by route (`"/"`, `"/cli"`).
+             * A custom page has no frontmatter to read, so its card is otherwise titled
+             * by humanizing its last URL segment (`/cli` → "Cli"); an entry here wins.
+             * Content pages always take their card headline from the page title.
+             */
+            titles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, "strict", z.ZodTypeAny, {
             enabled?: boolean | undefined;
             logo?: string | undefined;
@@ -2544,6 +2551,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         }, {
             enabled?: boolean | undefined;
             logo?: string | undefined;
@@ -2559,6 +2567,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         }>>;
         /** Generate robots.txt (with a Sitemap reference when available). */
         robots: z.ZodDefault<z.ZodBoolean>;
@@ -2616,6 +2625,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         };
         robots: boolean;
         rss: {
@@ -2651,6 +2661,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         } | undefined;
         robots?: boolean | undefined;
         rss?: {
@@ -2803,6 +2814,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
     } | undefined>;
 }, "strict", z.ZodTypeAny, {
     title: string;
+    frontmatter: {
+        extend: Record<string, StandardSchema<unknown, unknown>>;
+    };
     openapi: {
         enabled: boolean;
         route: string;
@@ -2961,9 +2975,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         pdf: boolean;
     };
     feedback: boolean;
-    frontmatter: {
-        extend: Record<string, StandardSchema<unknown, unknown>>;
-    };
     markdown: {
         code: {
             icons: boolean;
@@ -3074,6 +3085,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         };
         robots: boolean;
         rss: {
@@ -3145,6 +3157,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
     } | undefined;
 }, {
     title?: string | undefined;
+    frontmatter?: {
+        extend?: Record<string, StandardSchema<unknown, unknown>> | undefined;
+    } | undefined;
     openapi?: {
         enabled?: boolean | undefined;
         route?: string | undefined;
@@ -3332,9 +3347,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
         pdf?: boolean | undefined;
     } | undefined;
     feedback?: boolean | undefined;
-    frontmatter?: {
-        extend?: Record<string, StandardSchema<unknown, unknown>> | undefined;
-    } | undefined;
     i18n?: {
         locales: {
             code: string;
@@ -3466,6 +3478,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 foreground?: string | undefined;
                 muted?: string | undefined;
             } | undefined;
+            titles?: Record<string, string> | undefined;
         } | undefined;
         robots?: boolean | undefined;
         rss?: {

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

@@ -103,6 +103,13 @@ export interface PageRecord {
      * `/guides/x`). Pages with the same key are translations of each other.
      */
     translationKey: string;
+    /**
+     * True for entries filled in from the fallback locale to pad a locale's
+     * navigation for pages it hasn't translated yet. The record's content —
+     * title included — belongs to the fallback locale, so per-locale content
+     * checks skip these.
+     */
+    fallback?: boolean;
     /**
      * Content-relative path with the leading locale directory stripped, used for
      * sidebar grouping so the locale dir is not surfaced as a nav group. Equals

package/docs/advanced/changelog.mdx

@@ -87,7 +87,7 @@ content: {
 }
 ```
 
-The release name becomes the title, its tag becomes `changelog.version`, and its published date sorts the timeline. A private repo authenticates with the `GITHUB_TOKEN` environment variable. See [Content sources](/docs/content/sources#github-releases) for every option.
+The release name becomes the title, its tag becomes `changelog.version`, and its published date sorts the timeline. Each release page also gets a unique meta description summarized from its notes — markdown stripped, section headings and changeset commit-hash prefixes dropped, trimmed to the search-snippet length [`blume audit`](/docs/reference/cli#auditing-the-built-site) checks for — instead of falling back to the site description. A private repo authenticates with the `GITHUB_TOKEN` environment variable. See [Content sources](/docs/content/sources#github-releases) for every option.
 
 ## The RSS feed
 

package/docs/configuration/ai.mdx

@@ -47,11 +47,11 @@ Append `.md` or `.mdx` to any page's URL to fetch its raw Markdown source — pe
 
 Nested routes work the same way (`/content/syntax.md`), and the home page is served at `/index.md`.
 
-The `.md` variant _downlevels_ components to plain Markdown for consumers that can't interpret JSX: `<TypeTable>` becomes a Markdown table, `<Callout>` a labeled blockquote, `<Steps>` an ordered list, `<Tabs>` bold-labeled sections, and `<YouTube>` a link. Anything that can't be converted faithfully — a custom component, or a prop computed from an import — is left as-is, and component markup inside fenced code blocks is never touched. The same conversion applies to `llms-full.txt` and the MCP server's `get_page` tool, so every agent-facing surface reads clean Markdown. When you want the untransformed source, use the `.mdx` variant.
+The `.md` variant _downlevels_ components to plain Markdown for consumers that can't interpret JSX: `<TypeTable>` becomes a Markdown table, `<Callout>` a labeled blockquote, `<Steps>` an ordered list, `<Tabs>` bold-labeled sections, and `<YouTube>` a link. Props are evaluated with the page's `frontmatter` in scope, so a prop like `title={frontmatter.status}` resolves to the same value the rendered page shows. Anything that can't be converted faithfully — a custom component, or a prop computed from an import — is left as-is, and component markup inside fenced code blocks is never touched. The same conversion applies to `llms-full.txt` and the MCP server's `get_page` tool, so every agent-facing surface reads clean Markdown. When you want the untransformed source, use the `.mdx` variant.
 
 ### Custom component serializers
 
-Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes) and its `children` (already downleveled to Markdown), and returns the replacement — or `null` to leave the JSX as-is:
+Give your own components a Markdown form with `ai.markdownComponents` — a map of JSX name to serializer. Each serializer receives the component's `props` (statically evaluated from the MDX attributes, with the page's `frontmatter` in scope), its `children` (already downleveled to Markdown), and the page's `frontmatter` data, and returns the replacement — or `null` to leave the JSX as-is:
 
 ```ts blume.config.ts lineNumbers
 import { defineConfig } from "blume";

package/docs/configuration/seo.mdx

@@ -166,6 +166,22 @@ seo: {
 
 Each entry is a family name, or an object pinning its `weight` (a number, a list, or a variable range like `"100..900"`) and `style` (`"normal"`, `"italic"`, or both). The families are fetched from Google Fonts at build — so a build that uses them needs network access — and the renderer only pulls the glyph subsets each title actually uses. Fallback is per-glyph, so adding a family only affects glyphs the built-in font can't draw; Latin text renders exactly as before.
 
+### Custom page titles
+
+A custom [`.astro` page](/docs/advanced/custom-pages) has no frontmatter to read, so its generated card is titled by humanizing the last URL segment of its route — `/getting-started` becomes "Getting Started", but `/cli` becomes "Cli". Name those cards explicitly with `og.titles`, keyed by route (`"/"` addresses the home, whose card otherwise carries the site title):
+
+```ts blume.config.ts lineNumbers
+seo: {
+  og: {
+    titles: {
+      "/cli": "CLI",
+    },
+  },
+}
+```
+
+Entries only apply to custom pages — a content page's card always takes its headline from the page title, so retitle those in frontmatter instead.
+
 `seo.image` is frontmatter, so it only covers Markdown and MDX content. To give a custom [`.astro` page](/docs/advanced/custom-pages) its own social image — a marketing home or landing page, and the way to give the home page alone a bespoke share image — pass the `ogImage` prop to `PageLayout`.
 
 ## RSS feeds

package/docs/content/navigation.mdx

@@ -45,6 +45,8 @@ export default defineMeta({
 
 See [Folder meta](/docs/content/meta) for every field and computing meta at scan time.
 
+A folder's `meta.title` and its own `index` page's frontmatter `title` are resolved independently — translating one under i18n and forgetting the other renders a correct sidebar with a stale `<title>`/heading on the landing page itself. Blume reports a `BLUME_NAV_INDEX_TITLE_MISMATCH` warning when they diverge. Untranslated pages filled in from the fallback locale are exempt — their title belongs to the fallback locale, and the fix is translating the page, not editing its frontmatter.
+
 To group pages _without_ adding a URL segment, use a parenthesized folder name — see [Pages](/docs/content#group-folders).
 
 ## Display modes
@@ -86,6 +88,8 @@ When the sidebar is generated, order is resolved highest priority first:
   </Step>
 </Steps>
 
+Two siblings that land on the same explicit or numeric order fall back to alphabetical order between themselves — Blume reports a `BLUME_DUPLICATE_SIDEBAR_ORDER` warning so the tie doesn't go unnoticed.
+
 ## Hidden pages
 
 Hide a page from the sidebar — and from previous/next pagination — while keeping it built and reachable by its URL:

package/docs/reference/cli.mdx

@@ -35,7 +35,7 @@ blume <command> [options]
 - `blume dev --content-dir <dir>` — scan a different content folder without editing `blume.config.ts`.
 - `blume dev --debug` — verbose Astro/Vite logging for troubleshooting.
 - `blume dev --preview` / `blume build --preview` — include drafts and unpublished CMS content.
-- `blume build --strict` — fail the build on diagnostic errors (also works on `blume dev`).
+- `blume build --no-strict` — build despite diagnostic errors. By default `blume build` fails (exit 1) on any error diagnostic, because pages that fail frontmatter validation are dropped from the output; with `--no-strict` the build succeeds and reports how many pages are missing. `blume dev --strict` opts dev into the same fail-fast behavior.
 - `blume build --output static|server --adapter vercel|node|netlify|cloudflare --base /docs` — override the deployment output, adapter, and base path from `blume.config.ts`.
 - `blume build --analyze` — print the client JavaScript bundle sizes (largest first) after the build.
 - `blume build --budget-js <kb> --budget-css <kb>` — fail the build when total client JavaScript/CSS exceeds the budget, turning a performance target into a CI gate.

package/docs/reference/frontmatter.mdx

@@ -109,4 +109,6 @@ reviewedAt: 2026-06-20
 
 Schemas are accepted through the [Standard Schema](https://standardschema.dev) interface, so Zod (whichever version your project installs), Valibot, and ArkType all work. Every declared key is validated on every page — absent ones included — so a required schema enforces the key site-wide; mark it `.optional()` to validate only where present. All other keys stay strictly validated, and built-in fields can't be redeclared.
 
+A page that fails validation fails `blume build` with a diagnostic naming the file and key. With [`--no-strict`](/docs/reference/cli#common-flags), the build succeeds anyway and the failing pages are dropped from the output — the build summary reports how many.
+
 Schemas are exported from `blume/schema` for editor and migration tooling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -112,6 +112,7 @@
     "tailwindcss": "^4",
     "takumi-js": "^2.2.1",
     "tinyglobby": "^0.2.10",
+    "twoslash": "^0.3.9",
     "typescript": "^6.0.3",
     "undici": "^8.6.0",
     "zod": "^3.24.0"

package/src/ai/component-markdown.ts

@@ -63,6 +63,12 @@ export interface ComponentMarkdownContext extends EvaluatedProps {
   childComponents: (name: string) => ComponentMarkdownChild[];
   /** The element's body, downleveled and dedented (empty if self-closing). */
   children: string;
+  /**
+   * The page's parsed front-matter (empty when the caller has none). Lets a
+   * serializer read page metadata directly, even when a prop expression is
+   * not statically evaluable.
+   */
+  frontmatter: Record<string, unknown>;
 }
 
 /**
@@ -78,15 +84,22 @@ export type ComponentMarkdown = (
  * Statically evaluate an MDX attribute expression (`prop={...}`). Component
  * data props are object/array/number literals in practice; evaluation runs at
  * build time over the author's own content — the same trust level as the MDX
- * itself, which Astro compiles and executes. Expressions that reference
- * imports or scope throw and report as not evaluable.
+ * itself, which Astro compiles and executes. The page's `frontmatter` is in
+ * scope, mirroring what Astro provides an MDX body at render time, so
+ * `prop={frontmatter.status}` resolves; expressions that reference imports or
+ * other scope throw and report as not evaluable.
  */
-const evaluateExpression = (raw: string): { ok: boolean; value: unknown } => {
+const evaluateExpression = (
+  raw: string,
+  frontmatter: Record<string, unknown> | undefined
+): { ok: boolean; value: unknown } => {
   try {
     // Build-time eval of the author's own attribute literals; a throw falls
     // back to leaving the JSX verbatim.
     // oxlint-disable-next-line no-new-func
-    const value = new Function(`"use strict"; return (${raw});`)();
+    const value = new Function("frontmatter", `"use strict"; return (${raw});`)(
+      frontmatter
+    );
     return { ok: true, value };
   } catch {
     return { ok: false, value: undefined };
@@ -94,7 +107,10 @@ const evaluateExpression = (raw: string): { ok: boolean; value: unknown } => {
 };
 
 /** Evaluate an element's attributes into a plain props object. */
-const readProps = (node: MdastNode): EvaluatedProps => {
+const readProps = (
+  node: MdastNode,
+  frontmatter: Record<string, unknown> | undefined
+): EvaluatedProps => {
   const props: Record<string, unknown> = {};
   let lossy = false;
   for (const attribute of node.attributes ?? []) {
@@ -109,7 +125,7 @@ const readProps = (node: MdastNode): EvaluatedProps => {
     } else if (typeof attribute.value === "string") {
       props[attribute.name] = attribute.value;
     } else {
-      const result = evaluateExpression(attribute.value.value);
+      const result = evaluateExpression(attribute.value.value, frontmatter);
       if (result.ok) {
         props[attribute.name] = result.value;
       } else {
@@ -347,8 +363,9 @@ const componentHint = (registry: Record<string, ComponentMarkdown>): RegExp =>
 
 const BUILT_IN_HINT = componentHint(SERIALIZERS);
 
-/** One downlevel pass's inputs: the full source and the active registry. */
+/** One downlevel pass's inputs: the source, registry, and page metadata. */
 interface Walk {
+  frontmatter: Record<string, unknown> | undefined;
   registry: Record<string, ComponentMarkdown>;
   source: string;
 }
@@ -388,15 +405,16 @@ const serializeElement = (
   node: MdastNode
 ): string | null =>
   serializer({
-    ...readProps(node),
+    ...readProps(node, walk.frontmatter),
     childComponents: (name) =>
       (node.children ?? [])
         .filter((child) => isJsxElement(child) && child.name === name)
         .map((child) => ({
-          ...readProps(child),
+          ...readProps(child, walk.frontmatter),
           children: renderChildren(walk, child),
         })),
     children: renderChildren(walk, node),
+    frontmatter: walk.frontmatter ?? {},
   });
 
 /**
@@ -438,10 +456,16 @@ const collectSplices = (
  * `components` adds user serializers from `ai.markdownComponents`, layered
  * over the built-ins: a same-name entry replaces the built-in serializer, and
  * one that always returns `null` effectively opts that component out.
+ *
+ * `frontmatter` is the page's parsed front-matter data. It is put in scope
+ * when evaluating attribute expressions — so `prop={frontmatter.status}`
+ * resolves the way it does when Astro renders the page — and handed to
+ * serializers on their context.
  */
 export const downlevelComponents = (
   source: string,
-  components?: Record<string, ComponentMarkdown>
+  components?: Record<string, ComponentMarkdown>,
+  frontmatter?: Record<string, unknown>
 ): string => {
   const custom = components && Object.keys(components).length > 0;
   const registry = custom ? { ...SERIALIZERS, ...components } : SERIALIZERS;
@@ -456,6 +480,10 @@ export const downlevelComponents = (
     return source;
   }
   const splices: Splice[] = [];
-  collectSplices({ registry, source }, tree.children ?? [], splices);
+  collectSplices(
+    { frontmatter, registry, source },
+    tree.children ?? [],
+    splices
+  );
   return splices.length > 0 ? applySplices(source, splices) : source;
 };

package/src/ai/llms.ts

@@ -170,9 +170,11 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
       // Resolve `<Visibility>` audiences (web-only content omitted from the
       // agent-facing output, agents-only unwrapped), then downlevel supported
       // components to plain Markdown.
+      const parsed = matter(raw);
       const body = downlevelComponents(
-        applyAgentVisibility(matter(raw).content),
-        config.ai.markdownComponents
+        applyAgentVisibility(parsed.content),
+        config.ai.markdownComponents,
+        parsed.data
       ).trim();
       const url = pageUrl(
         page.route,

package/src/ai/markdown.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 
+import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
@@ -47,9 +48,12 @@ export const buildRawMarkdown = async (
   const entries = await Promise.all(
     project.manifest.routes.map(async (route) => {
       const source = applyAgentVisibility(await readRoute(route));
+      // The `.md` variant keeps the front-matter block in the output, but its
+      // data must also be in scope for `prop={frontmatter.*}` expressions.
       const md = downlevelComponents(
         source,
-        project.config.ai.markdownComponents
+        project.config.ai.markdownComponents,
+        matter(source).data
       );
       const entry: RawMarkdownEntry =
         md === source ? { mdx: source } : { md, mdx: source };

package/src/astro/generate.ts

@@ -185,6 +185,29 @@ const resolvedAstroPath = (fromDir: string): string | null => {
   }
 };
 
+/**
+ * The two places an installer can put Blume's dependencies:
+ *   - `<blume>/node_modules` — deps nested under the package (workspace source,
+ *     or npm nesting them away from a conflicting hoisted copy)
+ *   - `dirname(<blume>)`     — deps as siblings in the store (isolated/pnpm)
+ *
+ * `packageRoot()` resolves to Blume's real on-disk path (Node follows the
+ * install symlink), so its parent is the store's package directory where the
+ * isolated linker places the siblings.
+ */
+const depsCandidates = (pkgDir: string): string[] => [
+  join(pkgDir, "node_modules"),
+  dirname(pkgDir),
+];
+
+/** First dependency candidate containing the package dir `segments`, or null. */
+const candidateHolding = (
+  pkgDir: string,
+  ...segments: string[]
+): string | null =>
+  depsCandidates(pkgDir).find((dir) => existsSync(join(dir, ...segments))) ??
+  null;
+
 /**
  * Locate the directory that holds Blume's installed dependencies (Astro and its
  * integrations).
@@ -194,19 +217,28 @@ const resolvedAstroPath = (fromDir: string): string | null => {
  * short-circuits before we need it. But under isolated linkers (Bun's
  * `isolated` mode, pnpm) Blume's deps are NOT hoisted into the project; they
  * live beside the Blume package in a virtual store, invisible to the upward
- * walk from `.blume/`. Two layouts are possible, so probe for `astro`:
- *   - `<blume>/node_modules` — deps nested under the package (workspace source)
- *   - `dirname(<blume>)`     — deps as siblings in the store (isolated/pnpm)
+ * walk from `.blume/` — so probe the {@link depsCandidates}.
  *
- * `packageRoot()` resolves to Blume's real on-disk path (Node follows the
- * install symlink), so its parent is the store's package directory where the
- * isolated linker places the siblings. The previous fixed
- * `packageRoot()/node_modules` assumption missed the sibling layout entirely,
- * which is why isolated-linker projects had to redeclare Blume's deps by hand.
+ * Astro alone is a bad probe: an npm split install (an `overrides` pin plus an
+ * incremental install) hoists `astro` to the project root while Blume's other
+ * deps stay nested, and probing for astro then picks the root directory — one
+ * that holds none of them. Prefer a candidate with the full set (astro beside
+ * `@astrojs/mdx`, the integration every generated runtime declares), then one
+ * with the integrations (astro hoisted away — the rest of Blume's deps sit
+ * there too), then one with astro alone.
  */
+const holdsAstro = (dir: string): boolean => existsSync(join(dir, "astro"));
+const holdsMdx = (dir: string): boolean =>
+  existsSync(join(dir, "@astrojs", "mdx"));
+
 export const blumeDepsDir = (pkgDir: string = packageRoot()): string | null => {
-  const candidates = [join(pkgDir, "node_modules"), dirname(pkgDir)];
-  return candidates.find((dir) => existsSync(join(dir, "astro"))) ?? null;
+  const candidates = depsCandidates(pkgDir);
+  return (
+    candidates.find((dir) => holdsAstro(dir) && holdsMdx(dir)) ??
+    candidates.find(holdsMdx) ??
+    candidates.find(holdsAstro) ??
+    null
+  );
 };
 
 /**
@@ -271,7 +303,7 @@ const astroConflictWarning = (
 
 /**
  * Make the generated runtime resolve Astro and its integrations against Blume's
- * own dependency set. Two failure modes this repairs:
+ * own dependency set. Three failure modes this repairs:
  *
  *   - Astro is *unreachable* from `.blume/` (workspaces under isolated linkers,
  *     pnpm) — the deps live in a store the upward walk can't see.
@@ -280,38 +312,49 @@ const astroConflictWarning = (
  *     `astro@7`, so `@astrojs/mdx@7` binds to it and crashes the build on a
  *     missing export. Resolving merely *an* astro isn't enough; it must be the
  *     same one Blume uses.
+ *   - The *integrations* are unreachable while astro is fine — npm's split
+ *     install. An `overrides` pin plus an incremental `npm install` hoists
+ *     astro to the project root (deleting Blume's nested copy) but leaves
+ *     `@astrojs/mdx` and friends nested under `blume/node_modules`, where the
+ *     upward walk from `.blume/` can't see them.
  *
- * In both cases we symlink Blume's dependency directory in as
+ * The repair is the same symlink: Blume's dependency directory linked in as
  * `.blume/node_modules` so the generated config's bare specifiers (`astro`,
- * `@astrojs/mdx`, …) bind to the matching set. We only do this when those deps
- * are a *co-located, consistent* set (astro beside the `@astrojs/mdx` that binds
- * to it). A split layout — an integration hoisted away from a conflicting astro
- * — can't be made consistent by a single symlink and needs a root `overrides`/
- * `resolutions` pin instead. We can't fix that from `.blume/`, so we return a
- * diagnostic naming the conflict rather than silently shipping a runtime that
- * crashes downstream. Returns the warning, or null when nothing needs saying.
+ * `@astrojs/mdx`, …) bind to a consistent set. That's safe when the linked
+ * directory holds the full set, or when it holds only the integrations but the
+ * runtime already resolves Blume's astro — the junction has no `astro` entry,
+ * so astro lookups fall through to the hoisted copy the integrations bind to
+ * anyway. What it can't fix is the inverse split: Blume's astro nested under a
+ * *conflicting* hoisted astro with the integrations hoisted away from it. No
+ * single directory yields a consistent set there; only a root `overrides`/
+ * `resolutions` pin does, so we return a diagnostic naming the conflict rather
+ * than silently shipping a runtime that crashes downstream. Returns the
+ * warning, or null when nothing needs saying.
  */
 export const ensureDepsLink = async (
   outDir: string,
   pkgDir: string = packageRoot()
 ): Promise<string | null> => {
-  const depsDir = blumeDepsDir(pkgDir);
-  if (!depsDir) {
+  const astroDir = candidateHolding(pkgDir, "astro");
+  if (!astroDir) {
     return null;
   }
-  // Already correct when `.blume/` resolves the very same astro Blume's deps
-  // provide — the clean hoisted case, nothing to do.
-  const blumeAstro = resolveAstroPackageJson(depsDir);
+  const mdxDir = candidateHolding(pkgDir, "@astrojs", "mdx");
+  const blumeAstro = resolveAstroPackageJson(astroDir);
   const outDirAstro = resolvedAstroPath(outDir);
-  if (blumeAstro && outDirAstro === blumeAstro) {
+  // `.blume/` resolves the very same astro Blume's deps provide.
+  const astroCorrect = blumeAstro !== null && outDirAstro === blumeAstro;
+  // Clean hoisted install: astro is correct and the integrations sit beside
+  // it, so they resolve through the same walk — nothing to do.
+  if (astroCorrect && mdxDir === astroDir) {
     return null;
   }
-  // A co-located, consistent set (astro beside the @astrojs/mdx that binds to
-  // it) can be linked in wholesale; this repairs the unreachable and the
-  // repairable-conflict cases. Any existing link here is stale and gets
-  // replaced.
-  if (existsSync(join(depsDir, "@astrojs", "mdx"))) {
-    await linkDepsJunction(join(outDir, "node_modules"), depsDir);
+  // Linking the integrations' directory yields a consistent set when it also
+  // holds Blume's astro (the unreachable and repairable-conflict cases) or
+  // when the correct astro is reachable without it (the npm split install).
+  // Any existing link here is stale and gets replaced.
+  if (mdxDir && (mdxDir === astroDir || astroCorrect)) {
+    await linkDepsJunction(join(outDir, "node_modules"), mdxDir);
     return null;
   }
   // Split layout: Blume's astro is nested (a conflicting astro took the root
@@ -1269,7 +1312,7 @@ export const generateRuntime = async (
   // Custom pages that should get a generated OG card (the home most of all).
   // Computed before the MCP `.well-known` routes are appended below — those are
   // private and filtered out anyway, but the intent is the user's pages.
-  const ogRoutes = customOgRoutes(pages, config.title);
+  const ogRoutes = customOgRoutes(pages, config.title, config.seo.og.titles);
 
   // The hosted MCP server. The `.well-known` discovery docs are injected as
   // prerendered routes alongside user pages; the server endpoint itself is a

package/src/astro/pages.ts

@@ -149,14 +149,25 @@ const humanizeSegment = (segment: string): string =>
  * — most importantly the landing `/`, the most-shared URL — would have no card.
  *
  * Dynamic (`[param]`) routes and private segments (`_partials`, `.well-known`)
- * are skipped: they aren't shareable pages. The home is titled with the site
- * title; a deeper page is titled from its last path segment. The card's brand
- * lockup, description, and footer come from the resolved config at render time.
+ * are skipped: they aren't shareable pages. A `titles` entry (`seo.og.titles`,
+ * keyed by route) names a card outright — the only way to say "CLI" when the
+ * segment humanizes to "Cli". Otherwise the home is titled with the site title
+ * and a deeper page from its last path segment. The card's brand lockup,
+ * description, and footer come from the resolved config at render time.
  */
 export const customOgRoutes = (
   pages: BlumePageRoute[],
-  siteTitle: string
+  siteTitle: string,
+  titles: Record<string, string> = {}
 ): OgCustomRoute[] => {
+  // Keys normalized to `/`-joined segments so `cli`, `/cli`, and `/cli/` all
+  // address the page served at `/cli` (and `/` addresses the home).
+  const overrides = new Map(
+    Object.entries(titles).map(([route, title]) => [
+      `/${route.split("/").filter(Boolean).join("/")}`,
+      title,
+    ])
+  );
   const seen = new Set<string>();
   const routes: OgCustomRoute[] = [];
   // Extracted so the skip paths become early `return`s (one `continue` budget
@@ -172,7 +183,12 @@ export const customOgRoutes = (
     }
     seen.add(slug);
     const last = segments.at(-1);
-    routes.push({ slug, title: last ? humanizeSegment(last) : siteTitle });
+    routes.push({
+      slug,
+      title:
+        overrides.get(`/${segments.join("/")}`) ??
+        (last ? humanizeSegment(last) : siteTitle),
+    });
   };
   for (const { pattern } of pages) {
     collectRoute(pattern);