blume 1.0.4 → 1.1.1

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

@@ -3,6 +3,7 @@ import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
+import { buildRssFeeds } from "../deploy/rss.ts";
 import { downlevelComponents } from "./component-markdown.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
@@ -136,6 +137,20 @@ const buildIndex = (project: BlumeProject): string => {
     );
   }
 
+  // Surface the RSS feeds so agents can find fresh content (new blog posts,
+  // changelog entries) without re-crawling the index. `buildRssFeeds` is empty
+  // unless RSS is enabled and an absolute `site` is set — the same condition
+  // under which agent-readability.json lists `artifacts.feeds`.
+  const feeds = buildRssFeeds(project);
+  if (feeds.length > 0) {
+    blocks.push(
+      "## RSS Feeds",
+      feeds
+        .map((feed) => `- [${feed.title}](${pageUrl(feed.path, site, base)})`)
+        .join("\n")
+    );
+  }
+
   const header = config.description
     ? `# ${config.title}\n\n> ${config.description}`
     : `# ${config.title}`;
@@ -155,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/adapter-root.ts

@@ -0,0 +1,70 @@
+import { pathToFileURL } from "node:url";
+
+import type { AstroIntegration } from "astro";
+
+/**
+ * Present a deploy adapter with `root` pointed at the real project root rather
+ * than the hidden `.blume` runtime.
+ *
+ * Astro's `root` and `outDir` normally sit together (`outDir` defaults to
+ * `<root>/dist`), and `@astrojs/vercel` leans on that: it writes its Build
+ * Output tree to `<root>/.vercel/output` and — the part that bites — traces the
+ * function's dependency closure with `@vercel/nft` using a base derived from
+ * `root`, silently dropping every traced file that falls outside it.
+ *
+ * Blume splits the two: `root` is `<project>/.blume`, so Astro resolves the
+ * runtime's own `package.json` and its `node_modules` junction, while `outDir`
+ * stays at `<project>/dist` so the build lands where users expect. That puts
+ * `build.server` (`<outDir>/server`) *outside* `root`, so nft's base excludes
+ * the server bundle entirely: the traced file list collapses to `entry.mjs`
+ * alone, and the deployed function dies on its first import with
+ * ERR_MODULE_NOT_FOUND — missing its chunks, its virtual middleware, and every
+ * npm dependency.
+ *
+ * A project inside a workspace accidentally escapes this, because nft's base
+ * search climbs past `.blume` to the workspace root, which does contain both
+ * `dist/` and `node_modules` — which is why the bug only ever surfaced in
+ * standalone projects.
+ *
+ * Handing the adapter the root its own `outDir` assumption implies restores the
+ * invariant without moving Astro's real root: the trace covers `dist/server`
+ * and `node_modules`, and the Build Output tree lands at the project root
+ * natively, where `vercel deploy --prebuilt` looks for it.
+ *
+ * `astro:config:setup` and `astro:config:done` are the only hooks handed a
+ * `config`; an adapter reads `root` from one or both and closes over it for its
+ * later build hooks, so overriding it there covers the whole adapter.
+ */
+const stripTrailingSlashes = (value: string): string => {
+  let end = value.length;
+
+  while (end > 0 && value[end - 1] === "/") {
+    end -= 1;
+  }
+
+  return value.slice(0, end);
+};
+
+export const withAdapterRoot = (
+  integration: AstroIntegration,
+  root: string
+): AstroIntegration => {
+  const rootUrl = pathToFileURL(`${stripTrailingSlashes(root)}/`);
+  const setup = integration.hooks["astro:config:setup"];
+  const done = integration.hooks["astro:config:done"];
+
+  return {
+    ...integration,
+    hooks: {
+      ...integration.hooks,
+      ...(setup && {
+        "astro:config:setup": (options) =>
+          setup({ ...options, config: { ...options.config, root: rootUrl } }),
+      }),
+      ...(done && {
+        "astro:config:done": (options) =>
+          done({ ...options, config: { ...options.config, root: rootUrl } }),
+      }),
+    },
+  };
+};

package/src/astro/generate.ts

@@ -29,7 +29,10 @@ import type {
 } from "../core/data.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
-import { validateNavTargets } from "../core/nav-diagnostics.ts";
+import {
+  validateNavTargets,
+  validateSearchPopularIcons,
+} from "../core/nav-diagnostics.ts";
 import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
@@ -43,6 +46,7 @@ import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { registry } from "../registry/registry.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
+import { resolveSearchPopular } from "../search/popular.ts";
 import { searchProviderMeta, servesStaticIndex } from "../search/providers.ts";
 import {
   examplesEntryTemplate,
@@ -145,23 +149,65 @@ const reactCompilerWarnings = (
       ]
     : [];
 
-/**
- * Realpath of the `astro` package node resolves from a directory, or null when
- * none resolves. Comparing this for `.blume/` against Blume's own deps tells
- * whether the runtime would bind to the *same* astro Blume uses or a different
- * one shadowing it (the hoisted-conflict failure mode).
- */
-const resolvedAstroPath = (fromDir: string): string | null => {
+/** Resolve Astro's package.json directly inside a node_modules directory. */
+const resolveAstroPackageJson = (modulesDir: string): string | null => {
   try {
-    const pkg = createRequire(
-      pathToFileURL(join(fromDir, "_.js")).href
-    ).resolve("astro/package.json");
-    return realpathSync(pkg);
+    return realpathSync(join(modulesDir, "astro", "package.json"));
   } catch {
     return null;
   }
 };
 
+/**
+ * Realpath of the `astro` package reachable through the normal node_modules
+ * ancestor walk from a generated runtime, or null when none resolves.
+ *
+ * This deliberately does not use `createRequire().resolve()`. pnpm's generated
+ * bin shim adds Blume's virtual-store dependencies to `NODE_PATH`, which
+ * CommonJS resolution honors but ESM package resolution ignores. The generated
+ * Astro config uses ESM imports, so treating a NODE_PATH-only result as
+ * reachable skips the dependency link and makes `import "astro/config"` fail.
+ * Walking the physical node_modules ancestors mirrors the lookup that config
+ * actually gets.
+ */
+const resolvedAstroPath = (fromDir: string): string | null => {
+  let dir = normalize(fromDir);
+  while (true) {
+    const resolved = resolveAstroPackageJson(join(dir, "node_modules"));
+    if (resolved) {
+      return resolved;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+};
+
+/**
+ * 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).
@@ -171,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
+  );
 };
 
 /**
@@ -248,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.
@@ -257,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 = resolvedAstroPath(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
@@ -299,7 +365,7 @@ export const ensureDepsLink = async (
 
 /**
  * Vite plugin that makes Blume's externalized runtime deps (zod, shiki, sharp,
- * `@takumi-rs/core`, …) resolvable when Astro executes the static prerender
+ * `takumi-js`, …) resolvable when Astro executes the static prerender
  * bundle under an isolated linker (Bun's `isolated` mode, pnpm).
  *
  * Astro's static build emits a self-contained SSR bundle to
@@ -931,12 +997,14 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       // the optional schema type so the serialized shape stays `boolean`.
       og: {
         enabled: config.seo.og.enabled ?? false,
+        fonts: config.seo.og.fonts ?? [],
         logo: ogLogo,
         palette: config.seo.og.palette,
       },
       repoUrl,
       search: {
         enabled: config.search.provider !== "none",
+        popular: resolveSearchPopular(config.search.popular, config.basePath),
         provider: config.search.provider,
       },
       site: config.deployment.site ?? null,
@@ -1244,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
@@ -1509,12 +1577,18 @@ export const generateRuntime = async (
   if (hasGeneratedChangelog(project, pages)) {
     navTargetRoutes.add("/changelog");
   }
+  // Curated `search.popular` icons live outside the navigation model, so they
+  // miss `validateNavIcons` in the graph build — they're checked here too,
+  // where the search config is known. A typo otherwise just renders the
+  // default glyph.
   warnings.push(
-    ...validateNavTargets(project.graph.navigation, navTargetRoutes).map(
-      (diagnostic) =>
-        diagnostic.suggestion
-          ? `${diagnostic.message} ${diagnostic.suggestion}`
-          : diagnostic.message
+    ...[
+      ...validateNavTargets(project.graph.navigation, navTargetRoutes),
+      ...validateSearchPopularIcons(config.search.popular),
+    ].map((diagnostic) =>
+      diagnostic.suggestion
+        ? `${diagnostic.message} ${diagnostic.suggestion}`
+        : diagnostic.message
     )
   );
 

package/src/astro/index.ts

@@ -1,3 +1,4 @@
+export { withAdapterRoot } from "./adapter-root.ts";
 export {
   generateRuntime,
   prerenderDepsPlugin,

package/src/astro/pages.ts

@@ -6,11 +6,25 @@ import type { BlumePageRoute } from "./integration.ts";
 
 const PAGE_GLOB = ["**/*.astro"];
 
+/**
+ * Astro's routing convention: a file or folder whose name starts with `_` is a
+ * private partial — importable (shared layouts, home-page sections), but never
+ * built into a route. Blume injects pages itself, so it must reproduce the same
+ * exclusion or every `pages/_home/Hero.astro`-style component ships as an HTML
+ * page.
+ */
+const isPrivatePage = (rel: string): boolean =>
+  rel.split("/").some((segment) => segment.startsWith("_"));
+
 /** Map discovered page files to routes; shared by the async/sync discoverers. */
 const toPageRoutes = (pagesRoot: string, files: string[]): BlumePageRoute[] => {
   files.sort();
-  return files.map((file) => {
+  const routes: BlumePageRoute[] = [];
+  for (const file of files) {
     const rel = relative(pagesRoot, file);
+    if (isPrivatePage(rel)) {
+      continue;
+    }
     const withoutExt = rel.slice(0, rel.length - extname(rel).length);
     const parts = withoutExt.split("/");
     // Only a trailing `index` maps to its parent dir; a folder literally named
@@ -19,8 +33,9 @@ const toPageRoutes = (pagesRoot: string, files: string[]): BlumePageRoute[] => {
       parts.pop();
     }
     const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
-    return { entrypoint: file, pattern };
-  });
+    routes.push({ entrypoint: file, pattern });
+  }
+  return routes;
 };
 
 /**
@@ -134,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
@@ -157,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);