create-ailk 0.8.0 → 0.9.0

package/templates/apps/web/app/[locale]/alternatives/page.tsx

@@ -0,0 +1,104 @@
+// ComparisonsList hub (#6878 D9) — the /alternatives page. Reads
+// ComparisonsList MDX via the content adapter, injects a generated `items`
+// section listing every ComparisonPage spoke (so the visible card grid and
+// the CollectionPage's ItemList JSON-LD — built from the same sections —
+// always agree, D9), and emits via the dispatcher.
+//
+// notFound() when the hub seed is absent, so no empty hub is ever served
+// (unlike the /for hub's empty-state branch): an add-page run always writes
+// the seed alongside the first spoke (D11), so a fresh scaffold — which
+// excludes this gated surface entirely — never reaches this branch in
+// production, only a mis-authored site would.
+//
+// Gated off by default (surfaces.ts `alternatives` surface): no roster names
+// this route, so a fresh scaffold excludes it.
+import type {
+  getMdxSource as defaultGetMdxSource,
+  getPageSections as defaultGetPageSections,
+} from "@working-theory/page-renderer";
+import {
+  getMdxSlugs,
+  getMdxSource as loadMdxSource,
+  getPageSections as loadPageSections,
+  renderPage,
+  renderPageMetadata,
+} from "@working-theory/page-renderer";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import type { ReactElement } from "react";
+
+interface Props {
+  params: Promise<{ locale: string }>;
+  getMdxSource?: typeof defaultGetMdxSource;
+  getPageSections?: typeof defaultGetPageSections;
+}
+
+type Section = Awaited<ReturnType<typeof defaultGetPageSections>>[number];
+
+export async function generateMetadata({
+  params,
+}: Pick<Props, "params">): Promise<Metadata> {
+  const { locale } = await params;
+  return renderPageMetadata({
+    type: "ComparisonsList",
+    slug: "alternatives",
+    locale,
+  });
+}
+
+export default async function Page({
+  params,
+  getMdxSource,
+  getPageSections,
+}: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  const load = getMdxSource ?? loadMdxSource;
+  const loadSections = getPageSections ?? loadPageSections;
+
+  const source = await load("ComparisonsList", "alternatives", locale);
+  if (source === null) {
+    notFound();
+  }
+
+  /**
+   * Append one generated `items` section listing every ComparisonPage spoke
+   * — D9's "the visible list and the CollectionPage's ItemList always
+   * agree" property, since `renderPage` builds JSON-LD from these same
+   * sections. Absent when there are zero spokes: the hub still renders its
+   * own authored sections and answers 200 on its seed alone.
+   */
+  async function withSpokes(frontmatter: unknown): Promise<Section[]> {
+    const declared = await loadSections(frontmatter);
+    const slugs = await getMdxSlugs("ComparisonPage", locale);
+    if (slugs.length === 0) return declared;
+
+    const items = await Promise.all(
+      slugs.map(async (slug) => {
+        const spoke = await load("ComparisonPage", slug, locale);
+        const fm = (spoke?.frontmatter ?? {}) as {
+          title?: string;
+          description?: string;
+        };
+        return {
+          title: fm.title ?? slug,
+          description: fm.description ?? "",
+          link: { label: "Read the comparison", href: `/vs/${slug}` },
+        };
+      }),
+    );
+
+    return [
+      ...declared,
+      { type: "items" as const, id: "comparison-spokes", data: { items } },
+    ];
+  }
+
+  return renderPage({
+    type: "ComparisonsList",
+    slug: "alternatives",
+    locale,
+    translationsNamespace: "alternatives",
+    getPageSections: withSpokes,
+    ...(getMdxSource !== undefined && { getMdxSource }),
+  });
+}

package/templates/apps/web/app/[locale]/{use-cases → for}/[slug]/page.tsx

@@ -1,5 +1,6 @@
-// UseCase detail page (#6658 D4) — one use case at /use-cases/<slug>, listed by
-// the /use-cases page. Reads the UseCase MDX for the given slug, renders via
+// UseCase detail page (#6658 D4; route renamed to /for by #6878 D2) — one
+// customer page at /for/<slug>, listed by the /for hub. Reads the UseCase MDX
+// for the given slug, renders via
 // @working-theory/page-renderer, and emits a JSON-LD WebPage whose mainEntity
 // is an Article. Unknown slugs 404. Composed `sections[]` render as sections
 // (#6721); a prose page renders its MDX body.
@@ -40,7 +41,7 @@ export default async function Page({
 }: Props): Promise<ReactElement> {
   const { locale, slug } = await params;
   // A page that composes `sections[]` (the starter seeds, #6721) renders
-  // them; a prose page renders its MDX body — the same rule the /use-cases hub
+  // them; a prose page renders its MDX body — the same rule the /for hub
   // applies. JSON-LD is built from the frontmatter either way.
   const source = await (getMdxSource ?? loadMdxSource)("UseCase", slug, locale);
   const composed =

package/templates/apps/web/app/[locale]/for/__tests__/page-renderer-migration.test.tsx

@@ -0,0 +1,73 @@
+/**
+ * HTML snapshot regression tests for for/page.tsx → @working-theory/page-renderer migration
+ * (route renamed from use-cases/ by #6878 D2).
+ *
+ * Two-commit strategy:
+ *   Commit 1: this file added; snapshots captured against pre-migration route (RED-passing).
+ *   Commit 2: route migrated; same snapshots verify diff=0 (GREEN).
+ *
+ * Two states tested:
+ *   - empty: getMdxSource returns null → empty-state branch
+ *   - populated: getMdxSource returns a minimal MdxPageSource → full render
+ *
+ * Failure = snapshot diff > 0 bytes. DO NOT regenerate snapshots to pass.
+ */
+import React from "react";
+import { render } from "@testing-library/react";
+
+// ── @working-theory/ui mock ─────────────────────────────────────────────────────────────
+jest.mock("@working-theory/ui", () => ({
+  // #4446/#4447: renderPage's own fallback/empty-state title now composes
+  // Heading (mobile type-budget classes, #4417) instead of a bare <h1>.
+  Heading: ({
+    children,
+    level,
+  }: {
+    children: React.ReactNode;
+    level: number;
+  }): React.ReactElement => React.createElement(`h${level}`, null, children),
+  SectionRenderer: ({ sections }: { sections: unknown[] }) =>
+    React.createElement("div", {
+      "data-testid": "section-renderer",
+      "data-section-count": String(sections.length),
+    }),
+}));
+
+import ForPage from "../page";
+
+const getMdxSourceEmpty = jest.fn().mockResolvedValue(null);
+
+describe("ForPage — snapshot regression", () => {
+  it("empty state renders deterministic HTML", async () => {
+    const element = await ForPage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource: getMdxSourceEmpty,
+    });
+    const { container } = render(element);
+    expect(container.innerHTML).toMatchInlineSnapshot(
+      `"<main id="main"><h1>Customers</h1><p data-testid="section-empty-state">Customer pages coming soon.</p></main>"`,
+    );
+  });
+
+  it("populated state renders deterministic HTML", async () => {
+    const source = {
+      frontmatter: {
+        type: "UseCasesList" as const,
+        slug: "for",
+        title: "Use Cases",
+        description: "How teams use our platform.",
+      },
+      body: "",
+    };
+    const getMdxSourcePopulated = jest.fn().mockResolvedValue(source);
+
+    const element = await ForPage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource: getMdxSourcePopulated,
+    });
+    const { container } = render(element);
+    expect(container.innerHTML).toMatchInlineSnapshot(
+      `"<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@type":"CollectionPage","inLanguage":"en","name":"Use Cases","description":"How teams use our platform.","mainEntity":{"@type":"ItemList","itemListElement":[{"@type":"Article"}]}}</script><main id="main"><h1>Use Cases</h1><p data-testid="for-description">How teams use our platform.</p><div data-testid="markdown-view-toggle" class="ailk-markdown-view-toggle"><div class="flex justify-end mb-3"><div role="radiogroup" aria-label="Page view" data-testid="markdown-view-toggle" class="inline-flex items-center gap-0.5 rounded-lg p-1 bg-(--color-surface-secondary)"><button class="inline-flex items-center justify-center gap-2 font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 disabled:cursor-not-allowed disabled:opacity-50 [&amp;>svg]:shrink-0 text-(--color-fg) hover:bg-(--color-surface-secondary) active:bg-gray-200 rounded-control px-control-x h-(--control-height-thin) text-caption leading-none rounded-md px-3 text-body-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 min-w-(--control-height-thin) min-h-(--control-height-big) bg-(--color-bg) text-(--color-fg) shadow-sm" type="button" role="radio" aria-checked="true" aria-label="Rendered" tabindex="0" data-testid="markdown-view-toggle-rendered">Rendered</button><button class="inline-flex items-center justify-center gap-2 font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 disabled:cursor-not-allowed disabled:opacity-50 [&amp;>svg]:shrink-0 text-(--color-fg) hover:bg-(--color-surface-secondary) active:bg-gray-200 rounded-control px-control-x h-(--control-height-thin) text-caption leading-none rounded-md px-3 text-body-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent) focus-visible:ring-offset-1 min-w-(--control-height-thin) min-h-(--control-height-big) text-(--color-text-muted) hover:text-(--color-fg)" type="button" role="radio" aria-checked="false" aria-label="Markdown" tabindex="-1" data-testid="markdown-view-toggle-markdown">Markdown</button></div></div><div role="status" aria-live="polite" aria-atomic="true" class="sr-only" data-testid="markdown-view-toggle-status">Showing Rendered view</div><div data-testid="markdown-view-rendered"><article data-testid="mdx-body"><div data-testid="mdx-remote" data-source=""></div></article></div></div></main>"`,
+    );
+  });
+});

package/templates/apps/web/app/[locale]/{use-cases → for}/page.tsx

@@ -1,5 +1,6 @@
-// Use Cases list page. Reads UseCasesList MDX via the content adapter and emits
-// a JSON-LD CollectionPage via the dispatcher. List-only — no detail route.
+// Customers (/for) hub page (#6878 D2 — renamed from /use-cases). Reads
+// UseCasesList MDX via the content adapter and emits a JSON-LD CollectionPage
+// via the dispatcher. List-only — no detail route.
 import type {
   getMdxSource as defaultGetMdxSource,
 } from "@working-theory/page-renderer";
@@ -22,7 +23,7 @@ export async function generateMetadata({
   const { locale } = await params;
   return renderPageMetadata({
     type: "UseCasesList",
-    slug: "use-cases",
+    slug: "for",
     locale,
   });
 }
@@ -33,19 +34,19 @@ export default async function Page({
 }: Props): Promise<ReactElement> {
   const { locale } = await params;
   // A UseCasesList page that composes `sections[]` (the Free template's
-  // /use-cases, operator ruling 2026-09-23) renders them; a prose-only page
+  // /for hub, operator ruling 2026-09-23) renders them; a prose-only page
   // keeps the MDX-body render. The CollectionPage JSON-LD is built from the
   // sections either way (buildUseCasesList).
-  const source = await (getMdxSource ?? loadMdxSource)("UseCasesList", "use-cases", locale);
+  const source = await (getMdxSource ?? loadMdxSource)("UseCasesList", "for", locale);
   const composed =
     source !== null &&
     Array.isArray((source.frontmatter as { sections?: unknown[] }).sections) &&
     ((source.frontmatter as { sections?: unknown[] }).sections?.length ?? 0) > 0;
   return renderPage({
     type: "UseCasesList",
-    slug: "use-cases",
+    slug: "for",
     locale,
-    translationsNamespace: "use-cases",
+    translationsNamespace: "for",
     ...(composed ? {} : { bodyMode: "mdx-body" as const }),
     ...(getMdxSource !== undefined && { getMdxSource }),
   });

package/templates/apps/web/app/[locale]/glossary/page.tsx

@@ -2,7 +2,7 @@
 // `GlossaryList` MDX with slug `glossary` and emits a JSON-LD CollectionPage
 // whose mainEntity is a DefinedTermSet built from its `glossary-index`
 // sections. A module-less surface a template enables by naming it in its
-// roster; with no content the route 404s. Mirrors use-cases/page.tsx: a
+// roster; with no content the route 404s. Mirrors for/page.tsx: a
 // sections-composed page renders its sections, a prose-only page its MDX body.
 import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
 import {

package/templates/apps/web/app/[locale]/layout.tsx

@@ -50,10 +50,12 @@ import { auth } from "../../auth";
 import { GoogleAnalytics } from "../../components/google-analytics";
 import { SignOutTrigger } from "../../components/sign-out-trigger";
 import { isAuthPath } from "../../lib/auth-routes";
+import { assertEnabledLocale } from "../../lib/locale-guard";
 import { footerColumns, navItems } from "../../lib/nav-config";
 import { getOgImageUrl } from "../../lib/og";
-import { SITE_NAME, siteLogo } from "../../lib/site-brand";
+import { SITE_NAME } from "../../lib/site-brand";
 import { siteChrome } from "../../lib/site-chrome";
+import { siteLogo } from "../../lib/site-logo";
 // Registers the `_site.mdx` identity with page-renderer at module load, so
 // every page rendered under this layout carries the sitewide JSON-LD (#6597).
 import "../../lib/site-identity";
@@ -211,6 +213,9 @@ export default async function LocaleLayout({
   params,
 }: Props): Promise<ReactElement> {
   const { locale } = await params;
+  // #6107 — a segment that is not an enabled locale is a 404, before any
+  // message load or session read.
+  assertEnabledLocale(locale);
   const messages = await getMessages();
   const themeMode = await resolveThemeMode();
   const consentDecided = await hasConsentChoice();
@@ -227,6 +232,7 @@ export default async function LocaleLayout({
       // The Free marketing-site chrome (#5469 D5): the Product flyout's three
       // entries + descriptions, the top-level items, and the Get started CTA.
       product: tNav("product"),
+      services: tNav("services"),
       useCases: tNav("useCases"),
       useCasesDesc: tNav("useCasesDesc"),
       footerSitePagesHeading: tNav("footerSitePagesHeading"),
@@ -238,14 +244,20 @@ export default async function LocaleLayout({
       feature4: tNav("feature4"),
       feature5: tNav("feature5"),
       allFeatures: tNav("allFeatures"),
-      // #6721 — the two-column Product flyout + the Use Cases footer column.
+      // #6878 D6 — one flyout rule for every shape: the offering column
+      // (Features or Services) beside the Customers column (the /for
+      // persona pages), plus the Customers footer column.
       flyoutFeaturesHeading: tNav("flyoutFeaturesHeading"),
-      flyoutUseCasesHeading: tNav("flyoutUseCasesHeading"),
-      footerUseCasesHeading: tNav("footerUseCasesHeading"),
-      useCase1: tNav("useCase1"),
-      useCase2: tNav("useCase2"),
-      useCase3: tNav("useCase3"),
-      allUseCases: tNav("allUseCases"),
+      flyoutServicesHeading: tNav("flyoutServicesHeading"),
+      flyoutCustomersHeading: tNav("flyoutCustomersHeading"),
+      footerCustomersHeading: tNav("footerCustomersHeading"),
+      allCustomers: tNav("allCustomers"),
+      customer1: tNav("customer1"),
+      customer2: tNav("customer2"),
+      customer3: tNav("customer3"),
+      service1: tNav("service1"),
+      service2: tNav("service2"),
+      service3: tNav("service3"),
       howItWorks: tNav("howItWorks"),
       howItWorksDesc: tNav("howItWorksDesc"),
       features: tNav("features"),
@@ -253,6 +265,7 @@ export default async function LocaleLayout({
       faq: tNav("faq"),
       faqDesc: tNav("faqDesc"),
       pricing: tNav("pricing"),
+      portfolio: tNav("portfolio"),
       about: tNav("about"),
       // The footer's column groups (#6468): their two headings + Contact.
       contact: tNav("contact"),
@@ -292,10 +305,13 @@ export default async function LocaleLayout({
   // enforcement, the callbacks are the hook for @working-theory/consent.
   const tConsent = await getTranslations({ locale, namespace: "consent" });
 
-  // Right-side action cluster (#4984). Signed out → the Free template's pair
-  // (#5469 D5): a primary "Get started" → /contact beside the outline-strong
-  // "Sign in" link (the operator's auth-pair idiom, #4370, MINUS Sign up —
-  // this site offers no sign-up flow). Signed in → the user's name (a
+  // Right-side action cluster (#4984). Signed out → the auth pair: an
+  // outline-strong "Sign in" → /sign-in beside a primary "Sign up" → /sign-up
+  // (the operator's auth-pair idiom, #4370). Every shape ships the (auth)
+  // route group, so both routes exist in every scaffold; whether the header
+  // shows them is the design's nav setting (#6797 — an earlier revision of
+  // this comment said the Free site had no sign-up flow; it renders both and
+  // the service shapes now roster both). Signed in → the user's name (a
   // non-navigating label) + an outline-strong "Sign out"; both authored as
   // `kind: "flow"` so Nav hands their triggers back through
   // `renderFlowTrigger` (see NAV_CLIENT_ACTION_FLOW above).
@@ -327,7 +343,7 @@ export default async function LocaleLayout({
   const hasFlowAction = navActions.some((action) => action.kind === "flow");
 
   // Shared brand mark injected into both Nav and Footer chrome slots. The
-  // mark comes from site-brand.tsx (the mark the /sign-in card also renders);
+  // mark comes from site-logo.tsx (the mark the /sign-in card also renders);
   // both add the shipped wordmark beside it — the Nav composes mark + wordmark
   // on desktop and mark-only below `md` (#5469 D5), the columns Footer shows
   // the full lockup at every width (#6507).
@@ -372,11 +388,10 @@ export default async function LocaleLayout({
   // `(marketing)` group — a ~35-directory move for a five-page delta (spec D1).
   const isAuthRoute = isAuthPath(pathname, enabledLocales);
 
-  // Placeholder social handles + copyright (#5469 D5): `{{COMPANY_HANDLE}}` /
-  // `{{COMPANY_NAME}}` are create-ailk markers substituted at scaffold time
+  // Placeholder social handles (#5469 D5): `{{COMPANY_HANDLE}}` is a
+  // create-ailk marker substituted at scaffold time
   // (packages/create-ailk/src/programmatic.ts), so a customer's site never
-  // carries the kit vendor's own identity here. The year is computed, never
-  // typed, so the placeholder does not go stale.
+  // carries the kit vendor's own identity here.
   const socialLinks = [
     { platform: "facebook", href: "https://facebook.com/{{COMPANY_HANDLE}}" },
     { platform: "instagram", href: "https://instagram.com/{{COMPANY_HANDLE}}" },
@@ -400,8 +415,9 @@ export default async function LocaleLayout({
     items: col.items.map((item) => ({ ...item, label: labelFor(item.labelKey) })),
   }));
 
-  // NO_HAND_IMPLEMENT_OK: operator-directed live Free-template pass (2026-09-23).
-  const copyrightText = `© ${new Date().getFullYear()} SalesSmyth LLC. All rights reserved.`;
+  // The site's own name (#6942) — `SITE_NAME` resolves from `_site.mdx`'s
+  // `siteName:`, so a customer's footer never carries the kit vendor's name.
+  const copyrightText = `© ${new Date().getFullYear()} ${SITE_NAME}. All rights reserved.`;
 
   // Footer legal links (#5612 D3). The centered variant folds in FAQ — the
   // roster's third always-scaffolded core route (`/faq`, alongside `/privacy`

package/templates/apps/web/app/[locale]/newsletter/page.tsx

@@ -1,6 +1,6 @@
 // Newsletter page (#6658 D5) — a NewsletterSignup at /newsletter. A
 // module-less surface a template enables by naming it in its roster; with no
-// content the route 404s. Mirrors use-cases/page.tsx: a sections-composed
+// content the route 404s. Mirrors for/page.tsx: a sections-composed
 // page renders its sections, a prose-only page its MDX body.
 //
 // A signup only when there is somewhere to keep it (#6730 D9). The API says

package/templates/apps/web/app/[locale]/portfolio/[slug]/page.tsx

@@ -1,6 +1,6 @@
 // Portfolio item page (#6687). Reads the PortfolioItem MDX for the given slug and emits a
 // JSON-LD <script>. Unknown slugs trigger 404. Renders `sections[]` when the
-// frontmatter carries them (the use-cases composed pattern), MDX prose otherwise.
+// frontmatter carries them (the /for composed pattern), MDX prose otherwise.
 // NO_HAND_IMPLEMENT_OK: /build-starter operator-directed live pass (#6687).
 import {
   getMdxSource as defaultGetMdxSource,

package/templates/apps/web/app/[locale]/portfolio/page.tsx

@@ -1,7 +1,7 @@
 // Portfolio list page (#6687). Reads PortfolioList MDX via the content adapter and emits
 // a JSON-LD CollectionPage via the dispatcher.
 // NO_HAND_IMPLEMENT_OK: /build-starter operator-directed live pass (#6687) — the
-// use-cases composed pattern mirrored onto the portfolio hub: sections when the
+// /for composed pattern mirrored onto the portfolio hub: sections when the
 // frontmatter carries `sections[]`, MDX prose otherwise (existing prose pages unchanged).
 import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
 import {

package/templates/apps/web/app/[locale]/vs/[slug]/__tests__/page.test.tsx

@@ -0,0 +1,112 @@
+/**
+ * Tests for /vs/[slug] (#6878 D9) — the ComparisonPage detail route.
+ * `renderPage`/`renderPageMetadata`/`getMdxSlugs` are mocked at the
+ * `@working-theory/page-renderer` boundary; `getMdxSource` is supplied
+ * per-call through the route's DI prop.
+ */
+// The mock return value is never rendered — every assertion below inspects
+// `mockRenderPage.mock.calls` directly — so it carries no `ReactElement`
+// cast; `renderPage`'s real return type is `Promise<ReactElement>` in
+// production, unaffected by this mock's loose type here.
+const mockRenderPage = jest.fn(async (..._args: unknown[]) => "<rendered/>");
+const mockRenderPageMetadata = jest.fn((..._args: unknown[]) => undefined);
+const mockGetMdxSlugs = jest.fn((..._args: unknown[]) => Promise.resolve<string[]>([]));
+
+jest.mock("@working-theory/page-renderer", () => ({
+  __esModule: true,
+  getMdxSlugs: (...args: unknown[]) => mockGetMdxSlugs(...args),
+  renderPage: (...args: unknown[]) => mockRenderPage(...args),
+  renderPageMetadata: (...args: unknown[]) => mockRenderPageMetadata(...args),
+  getMdxSource: jest.fn(),
+}));
+
+import ComparisonPage, {
+  generateMetadata,
+  generateStaticParams,
+} from "../page";
+
+beforeEach(() => jest.clearAllMocks());
+
+describe("ComparisonPage detail — metadata + static params", () => {
+  it("resolves metadata for the given slug", async () => {
+    await generateMetadata({
+      params: Promise.resolve({ locale: "en", slug: "acme" }),
+    });
+    expect(mockRenderPageMetadata).toHaveBeenCalledWith({
+      type: "ComparisonPage",
+      slug: "acme",
+      locale: "en",
+    });
+  });
+
+  it("enumerates every ComparisonPage slug for static generation", async () => {
+    mockGetMdxSlugs.mockResolvedValue(["acme", "globex"]);
+    const params = await generateStaticParams({ params: { locale: "en" } });
+    expect(mockGetMdxSlugs).toHaveBeenCalledWith("ComparisonPage", "en");
+    expect(params).toEqual([{ slug: "acme" }, { slug: "globex" }]);
+  });
+});
+
+describe("ComparisonPage detail — sections vs mdx-body", () => {
+  it("renders in sections mode (D10: hero, decision-split, comparison-table, cta) when frontmatter carries sections", async () => {
+    const getMdxSource = jest.fn().mockResolvedValue({
+      frontmatter: {
+        type: "ComparisonPage",
+        slug: "acme",
+        title: "vs. Acme",
+        description: "How we compare to Acme.",
+        sections: [
+          { id: "hero", type: "hero", data: {} },
+          { id: "compare", type: "decision-split", data: {} },
+          { id: "table", type: "comparison-table", data: {} },
+          {
+            id: "cta",
+            type: "cta",
+            data: { primaryCta: { label: "See all alternatives", href: "/alternatives" } },
+          },
+        ],
+      },
+      body: "",
+    });
+
+    await ComparisonPage({
+      params: Promise.resolve({ locale: "en", slug: "acme" }),
+      getMdxSource,
+    });
+
+    const passedInput = mockRenderPage.mock.calls[0]?.[0] as {
+      type: string;
+      slug: string;
+      bodyMode?: string;
+    };
+    expect(passedInput.type).toBe("ComparisonPage");
+    expect(passedInput.slug).toBe("acme");
+    expect(passedInput.bodyMode).toBeUndefined();
+  });
+
+  it("falls back to mdx-body mode for a prose-only comparison page", async () => {
+    const getMdxSource = jest.fn().mockResolvedValue({
+      frontmatter: {
+        type: "ComparisonPage",
+        slug: "acme",
+        title: "vs. Acme",
+        description: "How we compare to Acme.",
+      },
+      body: "Prose comparison.",
+    });
+
+    await ComparisonPage({
+      params: Promise.resolve({ locale: "en", slug: "acme" }),
+      getMdxSource,
+    });
+
+    const passedInput = mockRenderPage.mock.calls[0]?.[0] as {
+      bodyMode?: string;
+      populatedDescriptionTestId?: string;
+    };
+    expect(passedInput.bodyMode).toBe("mdx-body");
+    expect(passedInput.populatedDescriptionTestId).toBe(
+      "comparison-description",
+    );
+  });
+});

package/templates/apps/web/app/[locale]/vs/[slug]/page.tsx

@@ -0,0 +1,70 @@
+// ComparisonPage detail (#6878 D9) — one head-to-head comparison at
+// /vs/<slug>, listed by the /alternatives hub. Reads the ComparisonPage MDX
+// for the given slug, renders via @working-theory/page-renderer, and emits a
+// JSON-LD WebPage. Unknown slugs 404. Composed `sections[]` (D10 — the
+// generic detail chassis, no dedicated comparison section: hero,
+// decision-split, comparison-table, cta) render as sections; a prose page
+// renders its MDX body — the same rule the /for detail page applies.
+//
+// Gated off by default (surfaces.ts `alternatives` surface): no roster names
+// this route, so a fresh scaffold excludes it. `add-page` installs it (D11)
+// the first time a site adds a comparison.
+import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
+import {
+  getMdxSource as loadMdxSource,
+  getMdxSlugs,
+  renderPage,
+  renderPageMetadata,
+} from "@working-theory/page-renderer";
+import type { Metadata } from "next";
+import type { ReactElement } from "react";
+
+interface Props {
+  params: Promise<{ locale: string; slug: string }>;
+  getMdxSource?: typeof defaultGetMdxSource;
+}
+
+export async function generateMetadata({
+  params,
+}: Pick<Props, "params">): Promise<Metadata> {
+  const { locale, slug } = await params;
+  return renderPageMetadata({ type: "ComparisonPage", slug, locale });
+}
+
+export async function generateStaticParams({
+  params,
+}: {
+  params: { locale: string };
+}): Promise<{ slug: string }[]> {
+  const slugs = await getMdxSlugs("ComparisonPage", params.locale);
+  return slugs.map((slug) => ({ slug }));
+}
+
+export default async function Page({
+  params,
+  getMdxSource,
+}: Props): Promise<ReactElement> {
+  const { locale, slug } = await params;
+  const source = await (getMdxSource ?? loadMdxSource)(
+    "ComparisonPage",
+    slug,
+    locale,
+  );
+  const composed =
+    source !== null &&
+    Array.isArray((source.frontmatter as { sections?: unknown[] }).sections) &&
+    ((source.frontmatter as { sections?: unknown[] }).sections?.length ?? 0) >
+      0;
+  return renderPage({
+    type: "ComparisonPage",
+    slug,
+    locale,
+    ...(composed
+      ? {}
+      : {
+          bodyMode: "mdx-body" as const,
+          populatedDescriptionTestId: "comparison-description",
+        }),
+    ...(getMdxSource !== undefined && { getMdxSource }),
+  });
+}