create-ailk 0.30.0 → 0.32.0

package/templates/apps/web/lib/bot-check.ts

@@ -12,11 +12,24 @@
  * a check that throws, answers no boolean or takes over 5 seconds is
  * `unavailable`. It runs only on Vercel (`VERCEL=1`); `AILK_BOT_CHECK=off`
  * turns every check off and `AILK_BOOKING_BOT_CHECK=off` the booking's alone.
+ * `AILK_BOT_CHECK=observe` (#10715) runs the check and logs what it found as
+ * `observed`, but passes every write — for diagnosis, never for production.
  *
- * NO SECRET IS LOGGED. A refusal logs `{ path, outcome }` and, for a failed
- * check, the error's name — never its message.
+ * A BotID-protected site MUST be reached directly (#10715): Cloudflare
+ * DNS-only, no reverse proxy in front of Vercel. Behind a proxy the browser
+ * solves BotID's challenge but the write reaches Vercel from the proxy's
+ * egress, so BotID judges every real visitor a bot. A request carrying
+ * `cf-ray` is `proxied`, and the first one per process logs an error naming
+ * that fix.
+ *
+ * NO SECRET IS LOGGED. A refusal logs `{ path, outcome }`, BotID's
+ * `classificationReason`, `bypassed` and `isVerifiedBot`, the request's
+ * `host` and `x-forwarded-host` and whether it was `proxied` — no other
+ * header value, no form field — and, for a failed check, the error's name —
+ * never its message.
  */
 import { checkBotId } from "botid/server";
+import { headers } from "next/headers";
 
 export type BotCheckScope = "write" | "booking";
 export type BotCheckOutcome = "pass" | "bot" | "unavailable";
@@ -46,6 +59,11 @@ function switchedOff(scope: BotCheckScope): boolean {
   );
 }
 
+/** `AILK_BOT_CHECK=observe`: the check runs and logs, but never refuses. */
+function observing(): boolean {
+  return process.env.AILK_BOT_CHECK?.trim().toLowerCase() === "observe";
+}
+
 /** True when the check runs for `scope`. Read on every call, never cached. */
 export function botCheckOn(scope: BotCheckScope): boolean {
   return process.env.VERCEL === "1" && !switchedOff(scope);
@@ -73,13 +91,21 @@ function namedError(name: string): Error {
   return err;
 }
 
+/** BotID's answer: `isBot` decides, the rest says why. */
+interface BotVerdict {
+  isBot: boolean;
+  classificationReason: string | null;
+  bypassed: boolean | null;
+  isVerifiedBot: boolean | null;
+}
+
 /**
- * BotID's verdict on this request: `true` for a bot, `false` for a human.
- * Throws `TimeoutError` past `BOT_CHECK_TIMEOUT_MS` and `InvalidVerdictError`
- * when `isBot` is not a boolean, as `checkBotId` returns for an error answer
- * from Vercel.
+ * BotID's verdict on this request: `isBot` is `true` for a bot, `false` for a
+ * human. Throws `TimeoutError` past `BOT_CHECK_TIMEOUT_MS` and
+ * `InvalidVerdictError` when `isBot` is not a boolean, as `checkBotId`
+ * returns for an error answer from Vercel.
  */
-async function isBotVerdict(): Promise<boolean> {
+async function botVerdict(): Promise<BotVerdict> {
   let timer: ReturnType<typeof setTimeout> | undefined;
   try {
     const verdict = await Promise.race([
@@ -91,14 +117,67 @@ async function isBotVerdict(): Promise<boolean> {
         );
       }),
     ]);
-    const isBot = (verdict as { isBot?: unknown } | undefined)?.isBot;
+    const answer = verdict as Record<string, unknown> | undefined;
+    const isBot = answer?.isBot;
     if (typeof isBot !== "boolean") throw namedError("InvalidVerdictError");
-    return isBot;
+    const reason = answer?.classificationReason;
+    return {
+      isBot,
+      classificationReason: typeof reason === "string" ? reason : null,
+      bypassed: typeof answer?.bypassed === "boolean" ? answer.bypassed : null,
+      isVerifiedBot:
+        typeof answer?.isVerifiedBot === "boolean"
+          ? answer.isVerifiedBot
+          : null,
+    };
   } finally {
     clearTimeout(timer);
   }
 }
 
+/** The only request facts a log carries: the two hosts and a proxy marker. */
+interface RequestFacts {
+  host: string | null;
+  forwardedHost: string | null;
+  proxied: boolean;
+}
+
+/** Read as `checkBotId` reads them; unreadable headers are no facts, never a throw. */
+async function requestFacts(): Promise<RequestFacts> {
+  try {
+    const h = await headers();
+    return {
+      host: h.get("host"),
+      forwardedHost: h.get("x-forwarded-host"),
+      proxied: h.has("cf-ray"),
+    };
+  } catch {
+    return { host: null, forwardedHost: null, proxied: false };
+  }
+}
+
+const PROXY_FIX =
+  "Serve the site direct to Vercel: set its Cloudflare DNS record to DNS-only (no orange cloud), never behind a reverse proxy (#10715).";
+
+let warnedProxied = false;
+
+/** A proxied request makes BotID refuse real visitors; say so once per process. */
+function warnProxiedOnce(
+  source: string,
+  target: string,
+  facts: RequestFacts,
+): void {
+  if (warnedProxied) return;
+  warnedProxied = true;
+  console.error(`[${source}] reverse proxy detected`, {
+    path: target,
+    outcome: "proxied",
+    host: facts.host,
+    forwardedHost: facts.forwardedHost,
+    fix: PROXY_FIX,
+  });
+}
+
 /**
  * The check for one write. `source` names the log prefix and `target` the
  * relayed path or the action's name — never a field value. Never throws.
@@ -116,21 +195,42 @@ export async function runBotCheck({
     warnBotCheckInactiveOnce(scope);
     return "pass";
   }
-  let isBot: boolean;
+  const observe = observing();
+  let verdict: BotVerdict | undefined;
+  let failure: unknown;
   try {
-    isBot = await isBotVerdict();
+    verdict = await botVerdict();
   } catch (err) {
+    failure = err;
+  }
+  // Read after the verdict, so the timeout starts with the check.
+  const facts = await requestFacts();
+  if (facts.proxied) warnProxiedOnce(source, target, facts);
+  if (!verdict) {
     console.error(`[${source}] bot check failed`, {
       path: target,
       outcome: "bot-check-failed",
-      error: err instanceof Error ? err.name : "unknown",
+      error: failure instanceof Error ? failure.name : "unknown",
     });
-    return "unavailable";
+    return observe ? "pass" : "unavailable";
+  }
+  const { isBot, ...detail } = verdict;
+  if (observe) {
+    console.warn(`[${source}] bot check observed`, {
+      path: target,
+      outcome: "observed",
+      isBot,
+      ...detail,
+      ...facts,
+    });
+    return "pass";
   }
   if (isBot) {
     console.warn(`[${source}] bot refused`, {
       path: target,
       outcome: "bot-detected",
+      ...detail,
+      ...facts,
     });
     return "bot";
   }

package/templates/apps/web/lib/in-page-magnet.ts

@@ -325,6 +325,8 @@ export interface NewsletterSignupOptions {
   /** The footer's compact form: stacked, the label `sr-only`, the placeholder naming the field. */
   compact?: boolean;
   className?: string;
+  /** #10629 D4 — the consent gate; the bound newsletter section passes `"on-submit"`. Omitted → the block's default. */
+  consentGate?: "disable" | "on-submit";
 }
 
 /**
@@ -335,7 +337,7 @@ export interface NewsletterSignupOptions {
  */
 export function newsletterSignup(
   view: InPageView & { form: NewsletterFormView },
-  { locale, fallbackEmail, compact = false, className }: NewsletterSignupOptions,
+  { locale, fallbackEmail, compact = false, className, consentGate }: NewsletterSignupOptions,
 ): ReactElement {
   const { form, ending } = view;
   const placeholder = form.placeholder ?? (compact ? form.label : undefined);
@@ -356,6 +358,7 @@ export function newsletterSignup(
     }),
     ...(fallbackEmail !== undefined && { fallbackEmail }),
     ...(className !== undefined && { className }),
+    ...(consentGate !== undefined && { consentGate }),
   });
 }
 

package/templates/apps/web/lib/page-chrome.ts

@@ -25,9 +25,12 @@ import {
   type SchemaOrgType,
 } from "@working-theory/page-renderer";
 import {
+  FooterStyleSchema,
   HeaderStyleSchema,
   ROUTE_FAMILY_KEYS,
   SiteConfigSchema,
+  SiteFooterSchema,
+  type ClosingFooterAction,
   type FooterStyle,
   type HeaderStyle,
   type RouteFamilyChrome,
@@ -130,11 +133,17 @@ export const readSiteChromeSettings = cache(
             )
           : undefined;
       if (headerStyle !== undefined) settings.headerStyle = headerStyle;
-      const footerStyle = validated(
-        SiteConfigSchema.shape.footer,
-        record["footer"],
-        "footer",
-      )?.style;
+      // #10550 D3 — the style alone, so an invalid closing-footer key
+      // (read by `readClosingFooterSettings`) never drops it.
+      const footer = record["footer"];
+      const footerStyle =
+        footer && typeof footer === "object"
+          ? validated(
+              FooterStyleSchema,
+              (footer as Record<string, unknown>)["style"],
+              "footer.style",
+            )
+          : undefined;
       if (footerStyle !== undefined) settings.footerStyle = footerStyle;
       const layout = validated(
         SiteConfigSchema.shape.layout,
@@ -157,6 +166,57 @@ export const readSiteChromeSettings = cache(
   },
 );
 
+/** The closing footer's site settings (#10550 D3). */
+export interface ClosingFooterSettings {
+  locality?: string;
+  actions?: ClosingFooterAction[];
+  legalBar: boolean;
+}
+
+/**
+ * `_site.mdx`'s closing-footer keys — `footer.locality`, `footer.actions`
+ * and `footer.legalBar` (#10550 D3). Each validates on its own, so one bad
+ * key drops only itself with one warning; an absent file or key is silent.
+ * A `footer` that is not an object, and each key `SiteFooterSchema` does not
+ * name, warn once too — the whole-object read this replaced warned on both.
+ */
+export const readClosingFooterSettings = cache(
+  function readClosingFooterSettings(): ClosingFooterSettings {
+    try {
+      const raw = readFileSync(join(resolveContentRoot(), "_site.mdx"), "utf8");
+      const match = FRONTMATTER_RE.exec(raw);
+      if (!match) return { legalBar: false };
+      const fm: unknown = parseYaml(match[1] ?? "");
+      if (!fm || typeof fm !== "object") return { legalBar: false };
+      const footer = (fm as Record<string, unknown>)["footer"];
+      if (footer === undefined) return { legalBar: false };
+      if (!footer || typeof footer !== "object" || Array.isArray(footer)) {
+        warnOnce("footer", "expected an object");
+        return { legalBar: false };
+      }
+      const record = footer as Record<string, unknown>;
+      const shape = SiteFooterSchema.shape;
+      for (const key of Object.keys(record)) {
+        if (!(key in shape)) warnOnce(`footer.${key}`, "unknown key");
+      }
+      const settings: ClosingFooterSettings = {
+        legalBar:
+          validated(shape.legalBar, record["legalBar"], "footer.legalBar") === true,
+      };
+      const locality = validated(shape.locality, record["locality"], "footer.locality");
+      if (locality !== undefined) settings.locality = locality;
+      const actions = validated(shape.actions, record["actions"], "footer.actions");
+      if (actions !== undefined) settings.actions = actions;
+      return settings;
+    } catch (err) {
+      if ((err as { code?: unknown }).code !== "ENOENT") {
+        warnOnce("frontmatter", "could not be read");
+      }
+      return { legalBar: false };
+    }
+  },
+);
+
 function camelCase(prefix: string): string {
   return prefix
     .replace(/^\//, "")

package/templates/apps/web/lib/relay.ts

@@ -49,7 +49,11 @@
  */
 import { isIP } from "node:net";
 
-import { relayToApi, visitorForwardHeaders } from "@working-theory/api-client";
+import {
+  getApiBase,
+  relayToApi,
+  visitorForwardHeaders,
+} from "@working-theory/api-client";
 
 import { browserApiOrigin } from "./api-origin.generated";
 import { runBotCheck } from "./bot-check";
@@ -333,6 +337,21 @@ function hubConfigured(): boolean {
   );
 }
 
+/**
+ * True when the API address `relayToApi` would call is this site's own host
+ * (#10553): the call would land back on this relay. (The API client itself
+ * refuses this server's own loopback port.)
+ */
+function apiIsOwnHost(request: Request): boolean {
+  try {
+    const api = new URL(getApiBase());
+    // Parsed under the API's scheme, so a default port compares equal.
+    return api.host === new URL(`${api.protocol}//${ownHost(request)}`).host;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * The host the browser addressed: the first `x-forwarded-host`, else `host`.
  * The site's edge must overwrite `x-forwarded-host`, never pass a client's on.
@@ -486,10 +505,10 @@ export async function handleRelay(request: Request): Promise<Response> {
     body = text;
   }
 
-  if (!hubConfigured()) {
+  if (!hubConfigured() || apiIsOwnHost(request)) {
     console.error("[relay] hub call failed", {
       path: entry.path,
-      outcome: "no-api-address",
+      outcome: hubConfigured() ? "own-address" : "no-api-address",
     });
     return refusal(502, "relay_unreachable", "The site could not reach its API");
   }

package/templates/apps/web/lib/site-identity.ts

@@ -21,6 +21,12 @@ import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import {
+  resolvedAdapterKind,
+  type ContentAdapter,
+} from "@working-theory/content-adapters";
+import {
+  getContentAdapter,
+  setSiteFeatureListReader,
   setSiteIdentity,
   type SiteIdentityRegistration,
 } from "@working-theory/page-renderer";
@@ -46,6 +52,59 @@ function readFrontmatter(path: string): Record<string, unknown> | undefined {
   }
 }
 
+/**
+ * A product page's feature titles. A `feature` section in the `steps` variant
+ * is how the product is set up, not what it does (the product page carries
+ * both, #6658 D3), so its step titles never enter the featureList.
+ */
+function featuresOf(page: { sections?: unknown }): string[] {
+  return featureListFromSections(
+    (Array.isArray(page.sections)
+      ? (page.sections as Array<{ type: string; data?: unknown }>)
+      : []
+    ).filter(
+      (section) =>
+        !(
+          section.type === "feature" &&
+          (section.data as { variant?: unknown } | undefined)?.variant === "steps"
+        ),
+    ),
+  );
+}
+
+/** Pages in the order the directory scan reads their seeds: by `<slug>.mdx`. */
+function inSeedOrder<T extends { slug: string }>(pages: readonly T[]): T[] {
+  const key = (page: T): string => `${page.slug}.mdx`;
+  return [...pages].sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+}
+
+/**
+ * The product's `featureList` read through the content adapter (#10644 D4):
+ * the first published `SoftwareProduct` page's features, else the titles of
+ * the published `Feature` pages, else none — the directory scan's first two
+ * steps, in the same seed order.
+ */
+export async function readFeatureListFromAdapter(
+  adapter: Pick<ContentAdapter, "listPages">,
+  locale: string,
+): Promise<string[]> {
+  const [product] = inSeedOrder(await adapter.listPages("SoftwareProduct", locale));
+  if (product !== undefined) return featuresOf(product);
+  return inSeedOrder(await adapter.listPages("Feature", locale))
+    .map((page) => page.title)
+    .filter((title): title is string => typeof title === "string" && title.length > 0);
+}
+
+/** Whether the identity carries a product, whose featureList the graph shows. */
+function carriesProduct(identity: SiteIdentityRegistration["identity"]): boolean {
+  return identity.kind === "Organization" && identity.secondary?.kind === "SoftwareApplication";
+}
+
+/** `_site.mdx`'s `defaultLocale`, else `"en"`. */
+function localeOf(defaultLocale: unknown): string {
+  return typeof defaultLocale === "string" ? defaultLocale : "en";
+}
+
 /**
  * The product's `featureList`: the feature titles of the product's own page —
  * the first `SoftwareProduct` seed in the default locale, in sorted order
@@ -54,22 +113,6 @@ function readFrontmatter(path: string): Record<string, unknown> | undefined {
  * first match in sorted order). Empty when there is neither.
  */
 function readFeatureList(contentRoot: string, locale: string): string[] {
-  // A `feature` section in the `steps` variant is how the product is set up,
-  // not what it does (the product page carries both, #6658 D3), so its step
-  // titles never enter the featureList.
-  const featuresOf = (frontmatter: Record<string, unknown>): string[] =>
-    featureListFromSections(
-      (Array.isArray(frontmatter.sections)
-        ? (frontmatter.sections as Array<{ type: string; data?: unknown }>)
-        : []
-      ).filter(
-        (section) =>
-          !(
-            section.type === "feature" &&
-            (section.data as { variant?: unknown } | undefined)?.variant === "steps"
-          ),
-      ),
-    );
   // #6658 D3: the product's own detail page (the first `SoftwareProduct`
   // seed in sorted order) is where the feature sections live now.
   const productDir = join(contentRoot, locale, "SoftwareProduct");
@@ -133,16 +176,24 @@ export function readSiteIdentity(
     baseUrl: typeof baseUrl === "string" ? baseUrl : identity.url,
     identity,
   };
-  if (
-    identity.kind === "Organization" &&
-    identity.secondary?.kind === "SoftwareApplication"
-  ) {
-    registration.featureList = readFeatureList(
-      contentRoot,
-      typeof defaultLocale === "string" ? defaultLocale : "en",
-    );
+  // Under the database adapter the list is read through the adapter when a
+  // page's JSON-LD is composed (#10644 D3), never scanned here.
+  if (carriesProduct(identity) && resolvedAdapterKind() !== "database") {
+    registration.featureList = readFeatureList(contentRoot, localeOf(defaultLocale));
   }
   return registration;
 }
 
 setSiteIdentity(readSiteIdentity());
+
+// #10644 D3, D4 — under the database adapter the product's featureList is
+// read through the adapter each time a page's JSON-LD is composed: an async
+// read cannot run at module load.
+if (resolvedAdapterKind() === "database") {
+  const contentRoot = resolveContentRoot();
+  const site = readSiteIdentity(contentRoot);
+  if (site !== undefined && carriesProduct(site.identity)) {
+    const locale = localeOf(readFrontmatter(join(contentRoot, "_site.mdx"))?.defaultLocale);
+    setSiteFeatureListReader(() => readFeatureListFromAdapter(getContentAdapter(), locale));
+  }
+}

package/templates/apps/web/messages/en.json

@@ -179,7 +179,11 @@
   },
   "events": {
     "heading": "Events",
-    "emptyState": "Events listing coming soon."
+    "emptyState": "Events listing coming soon.",
+    "addToCalendar": "Add to calendar",
+    "addToGoogleCalendar": "Google Calendar",
+    "addToOutlook": "Outlook",
+    "addToAppleCalendar": "Apple Calendar (.ics)"
   },
   "faq": {
     "heading": "FAQ",

package/templates/apps/web/next.config.mjs

@@ -6,6 +6,7 @@ import { withSentryConfig } from "@sentry/nextjs";
 import createNextIntlPlugin from "next-intl/plugin";
 import { DocsPathSchema, ServicesPathSchema } from "@working-theory/site-config/schema";
 import { legacyRedirects, ROUTES, SERVICES_ROUTE } from "@working-theory/templates/routes";
+import { assetRemotePattern } from "@working-theory/validation";
 import { parseStealth } from "@working-theory/web-i18n/stealth";
 import { withBotId } from "botid/next/config";
 
@@ -279,6 +280,14 @@ function readServiceParents() {
 const servicesPathAtBuild = readServicesPathFromSiteMdx();
 readServiceParents();
 
+// #10647 D6 — a database spoke's pages name library images as `asset:<key>`,
+// which the hub resolves to its own `/v1/assets/:id` URLs. `next/image` admits
+// that path on the hub's origin, and nothing else, when `AILK_API_URL` (the
+// server-side hub origin this site already reads) is an http(s) URL at build
+// time; otherwise there is no `images` key, as before. A change of hub origin
+// needs a rebuild.
+const assetPatternAtBuild = assetRemotePattern(process.env.AILK_API_URL);
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   reactStrictMode: true,
@@ -302,7 +311,9 @@ const nextConfig = {
   // content/ directory that carries the schema-typed pages, so the standalone
   // output shipped without them and postbuild's assert-content-bundled failed.
   outputFileTracingIncludes: {
-    "/**": ["../../content/**/*.mdx"],
+    // #10605 D6 — the last-good content snapshot. An exact path, never a glob
+    // over `.ailk/`: that directory also holds the lead-inbox fallback.
+    "/**": ["../../content/**/*.mdx", "./.ailk/content-snapshot.json"],
     // #10041 D8 — /sitemap.xml and /llms.txt list the docs by reading this
     // app's own content/<locale>/docs/ at request time.
     "/sitemap.xml": ["./content/**/*.mdx"],
@@ -349,6 +360,9 @@ const nextConfig = {
   // mutates a tracked file as a side effect of running the dev server,
   // which this scaffold does not want.
   agentRules: false,
+  ...(assetPatternAtBuild === null
+    ? {}
+    : { images: { remotePatterns: [assetPatternAtBuild] } }),
   env: {
     // Comma-separated locale list baked at build time — consumed by middleware
     // and the sitemap route. NEXT_PUBLIC_ prefix makes it available in Edge

package/templates/apps/web/package.json

@@ -6,7 +6,7 @@
   "license": "Apache-2.0",
   "scripts": {
     "dev": "next dev --webpack",
-    "build": "tsx scripts/check-nav-labels.ts && next build --webpack",
+    "build": "tsx scripts/check-nav-labels.ts && tsx scripts/content-snapshot.ts && next build --webpack",
     "postbuild": "tsx scripts/assert-content-bundled.ts",
     "start": "next start",
     "type-check": "tsc --noEmit",

package/templates/apps/web/scripts/assert-content-bundled.ts

@@ -5,6 +5,13 @@
  * preserving their path relative to outputFileTracingRoot (repo root). So
  * <repo-root>/content/en/HomePage/home.mdx → .next/standalone/content/en/...
  *
+ * Under CONTENT_ADAPTER=database (#10646 D1) a site's pages live on its hub,
+ * so content/ may hold no page at all. The build's own content file is then
+ * the snapshot (#10605), traced by exact path: when the build wrote one, the
+ * sentinel is apps/web/.ailk/content-snapshot.json →
+ * .next/standalone/apps/web/.ailk/content-snapshot.json. Without one (an
+ * unreachable hub, #10605 D3), the .mdx walk below still runs.
+ *
  * See: docs/runbooks/page-renderer-deploy-verification.md §1 Cause 2
  */
 
@@ -38,12 +45,25 @@ function firstMdx(dir: string): string | undefined {
   }
   return undefined;
 }
-const sentinelAbs = firstMdx(contentDir);
-if (sentinelAbs === undefined) {
-  console.error("[assert-content-bundled] ERROR: no .mdx file under content/ to trace.");
-  process.exit(1);
+const repoRoot = resolve(appWebDir, "..", "..");
+const snapshotAbs = join(appWebDir, ".ailk", "content-snapshot.json");
+const database = process.env.CONTENT_ADAPTER === "database";
+const snapshotSentinel = database && existsSync(snapshotAbs);
+let sentinelRelative: string;
+if (snapshotSentinel) {
+  sentinelRelative = relative(repoRoot, snapshotAbs);
+} else {
+  const sentinelAbs = firstMdx(contentDir);
+  if (sentinelAbs === undefined) {
+    console.error(
+      database
+        ? "[assert-content-bundled] ERROR: no content snapshot (.ailk/content-snapshot.json) and no .mdx file under content/ to trace."
+        : "[assert-content-bundled] ERROR: no .mdx file under content/ to trace.",
+    );
+    process.exit(1);
+  }
+  sentinelRelative = join("content", relative(contentDir, sentinelAbs));
 }
-const sentinelRelative = join("content", relative(contentDir, sentinelAbs));
 const sentinelPath = join(standaloneDir, sentinelRelative);
 
 if (!existsSync(standaloneDir)) {
@@ -60,11 +80,19 @@ if (!existsSync(sentinelPath)) {
   );
   console.error("  Expected path:", sentinelPath);
   console.error(
-    "  This means outputFileTracingIncludes did not bundle content/ into the build artifact.",
+    snapshotSentinel
+      ? "  This means outputFileTracingIncludes did not bundle the content snapshot into the build artifact."
+      : "  This means outputFileTracingIncludes did not bundle content/ into the build artifact.",
+  );
+  console.error(
+    snapshotSentinel
+      ? "  The deployed site cannot fall back to its last-good hub content."
+      : "  The deployed site cannot serve MDX content.",
   );
-  console.error("  The deployed site cannot serve MDX content.");
   console.error(
-    "  Fix: verify outputFileTracingIncludes in apps/web/next.config.mjs covers '../../content/**/*.mdx'.",
+    `  Fix: verify outputFileTracingIncludes in apps/web/next.config.mjs covers ${
+      snapshotSentinel ? "'./.ailk/content-snapshot.json'" : "'../../content/**/*.mdx'"
+    }.`,
   );
   console.error(
     "  See: docs/runbooks/page-renderer-deploy-verification.md §1 Cause 2",

package/templates/apps/web/scripts/content-snapshot.ts

@@ -0,0 +1,33 @@
+/**
+ * Write the last-good content snapshot (#10605 D5). Runs in `pnpm build`
+ * before `next build` — never in `prebuild`, which the docs-blog module owns
+ * in a scaffold.
+ *
+ * Under `CONTENT_ADAPTER=database` it reads every published page from the hub
+ * into `.ailk/content-snapshot.json`; under any other adapter it does nothing.
+ * An unreachable hub keeps the previous snapshot and the build goes on; only
+ * a configuration fault (a 4xx other than 404/429) fails the build.
+ */
+
+import { join } from "node:path";
+
+import { refreshContentSnapshot } from "@working-theory/page-renderer/snapshot";
+import { readLocales } from "@working-theory/web-i18n";
+
+function enabledLocales(): string[] {
+  try {
+    return readLocales(join(process.cwd(), "..", ".."));
+  } catch (error) {
+    // next.config.mjs's own fallback when project.yaml has no locales.
+    console.warn("[content-snapshot] locales unreadable, using en:", error);
+    return ["en"];
+  }
+}
+
+refreshContentSnapshot({ locales: enabledLocales() }).then(
+  (outcome) => console.log(`[content-snapshot] ${outcome}`),
+  (error: unknown) => {
+    console.error("[content-snapshot] ERROR:", error);
+    process.exit(1);
+  },
+);

package/templates/apps/web/src/lib/routes.ts

@@ -39,9 +39,11 @@ export function resolveBaseUrl(): string {
  * `packages/templates/src/__tests__/routes-map.test.ts`'s table test and
  * `apps/web/__tests__/routes/routes-map-identity.test.ts`'s differential
  * test over the live content tree). The signature is annotated explicitly so
- * this stays the exact `(type: string, slug: string) => string` contract the
- * three call sites (`sitemap.xml`, `llms.txt`, `docs-blog/llms-route.ts`)
- * depend on, even though `routeFor`'s own `slug` parameter is optional.
+ * this stays the exact `(type: string, slug: string) => string` contract its
+ * callers depend on, even though `routeFor`'s own `slug` parameter is
+ * optional. `sitemap.xml`, `llms.txt` and, since #10775, the docs-blog
+ * module's `docs-blog/llms-route.ts` call `pagePathFor` instead; the export
+ * stays for a docs-blog site that installed the older copy of that route.
  */
 export const slugToPath: (type: string, slug: string) => string = routeFor;