create-ailk 0.8.0 → 0.9.0

package/templates/apps/mcp/__tests__/tools/create_project.test.ts

@@ -102,6 +102,30 @@ describe("scaffoldOutputSchema", () => {
 // __tests__/tools → __tests__ → apps/mcp → apps → repo root
 const REPO_ROOT = resolve(__dirname, "../../../..");
 const CLI_PATH = join(REPO_ROOT, "packages/create-ailk/dist/cli.js");
+// NO_HAND_IMPLEMENT_OK: trunk fix for a red main (CI run 36386534464), operator-attended session.
+// The CLI substitutes `workspace:*` versions from create-ailk's gitignored
+// `versions.json`, which only `build-templates` writes ("empty before the first
+// build"); with it absent every scaffold throws "no version found for …".
+// Turbo gives this package's test no dependency on create-ailk's build-templates
+// step, so whether the file exists here depends on shard packing. Every case
+// that runs the CLI therefore skips — with a warning, never a failure — until
+// both the CLI and its version map are on disk.
+const VERSIONS_PATH = join(REPO_ROOT, "packages/create-ailk/versions.json");
+
+/** True (after warning) when the CLI cannot scaffold in this checkout yet. */
+function skipUnlessCliReady(): boolean {
+  if (!existsSync(CLI_PATH)) {
+    console.warn("[create_project.test] skipping integration test — CLI not built");
+    return true;
+  }
+  if (!existsSync(VERSIONS_PATH)) {
+    console.warn(
+      "[create_project.test] skipping integration test — run `pnpm --filter create-ailk run build-templates` first",
+    );
+    return true;
+  }
+  return false;
+}
 
 describe("ailkCreateProject handler", () => {
   let scratch: string;
@@ -124,10 +148,7 @@ describe("ailkCreateProject handler", () => {
   });
 
   it("scaffolds at least one file into a fresh tmp dir and reports targetDir", async () => {
-    if (!existsSync(CLI_PATH)) {
-      console.warn("[create_project.test] skipping integration test — CLI not built");
-      return;
-    }
+    if (skipUnlessCliReady()) return;
     const target = join(scratch, "my-site");
     const output = await ailkCreateProject(
       { targetDir: target, projectName: "my-site" },
@@ -138,10 +159,7 @@ describe("ailkCreateProject handler", () => {
   });
 
   it("scaffolds package.json when full templates are built (build-templates required)", async () => {
-    if (!existsSync(CLI_PATH)) {
-      console.warn("[create_project.test] skipping integration test — CLI not built");
-      return;
-    }
+    if (skipUnlessCliReady()) return;
     const TEMPLATES_DIR = join(REPO_ROOT, "packages/create-ailk/templates");
     const PKG_JSON_IN_TEMPLATES = join(TEMPLATES_DIR, "package.json");
     if (!existsSync(PKG_JSON_IN_TEMPLATES)) {
@@ -156,10 +174,7 @@ describe("ailkCreateProject handler", () => {
   });
 
   it("scaffolds app dir when full templates are built (build-templates required)", async () => {
-    if (!existsSync(CLI_PATH)) {
-      console.warn("[create_project.test] skipping integration test — CLI not built");
-      return;
-    }
+    if (skipUnlessCliReady()) return;
     const TEMPLATES_DIR = join(REPO_ROOT, "packages/create-ailk/templates");
     const PKG_JSON_IN_TEMPLATES = join(TEMPLATES_DIR, "package.json");
     if (!existsSync(PKG_JSON_IN_TEMPLATES)) {
@@ -178,10 +193,7 @@ describe("ailkCreateProject handler", () => {
   });
 
   it("returns at least one file (schema-typed page seed or README.md)", async () => {
-    if (!existsSync(CLI_PATH)) {
-      console.warn("[create_project.test] skipping integration test — CLI not built");
-      return;
-    }
+    if (skipUnlessCliReady()) return;
     const target = join(scratch, "my-site");
     await ailkCreateProject({ targetDir: target, projectName: "my-site" }, CLI_PATH);
     // At minimum README.md is always emitted by the template.
@@ -189,10 +201,7 @@ describe("ailkCreateProject handler", () => {
   });
 
   it("returns output conforming to scaffoldOutputSchema", async () => {
-    if (!existsSync(CLI_PATH)) {
-      console.warn("[create_project.test] skipping integration test — CLI not built");
-      return;
-    }
+    if (skipUnlessCliReady()) return;
     const target = join(scratch, "my-site");
     const output = await ailkCreateProject(
       { targetDir: target, projectName: "my-site" },
@@ -203,10 +212,7 @@ describe("ailkCreateProject handler", () => {
   });
 
   it("rejects with a clear error when targetDir is non-empty", async () => {
-    if (!existsSync(CLI_PATH)) {
-      console.warn("[create_project.test] skipping integration test — CLI not built");
-      return;
-    }
+    if (skipUnlessCliReady()) return;
     const target = join(scratch, "populated");
     mkdirSync(target);
     writeFileSync(join(target, "existing.txt"), "data");

package/templates/apps/mcp/src/tools/purchase.ts

@@ -41,8 +41,10 @@
  * simply not part of that shape. Either path is safe: the payload built
  * below can never carry a caller-supplied redirect. The shared
  * `purchaseInputSchema` (and the Server Action / API route that use it) is
- * unaffected: those are not anonymous surfaces and keep accepting a
- * caller-supplied redirect.
+ * unaffected: both keep accepting a caller-supplied redirect. The route's own
+ * anonymous exposure is gated only when `OSS_API_INTERNAL_SECRET` is set
+ * (`passesInternalAuthGate()` in `apps/api/src/routes/checkout/sessions.ts`);
+ * unset — the OSS standalone default — the route accepts anonymous callers.
  *
  * The file stays in the BASE tree and is never added to
  * `MODULE_SLICES.commerce.ownedFiles`: `../server.js` statically imports

package/templates/apps/web/.env.example

@@ -52,6 +52,19 @@ CONTENT_ADAPTER=mdx
 # browser never sees.
 # NEXT_PUBLIC_AILK_API_URL=http://localhost:3002
 
+# =============================================================================
+# apps/api internal-auth secret (server-side only) — #6876
+# =============================================================================
+# SERVER-SIDE ONLY — never rename it with a NEXT_PUBLIC_ prefix. The /dev/purchase
+# Server Action sends it as X-Internal-Auth on POST /v1/checkout/sessions,
+# alongside the buyer's session cookie, so the route can stamp a signed-in
+# buyer's Checkout. Must equal OSS_API_INTERNAL_SECRET in apps/api's
+# environment. Unset on both sides for OSS standalone deployments: the API
+# applies no gate and this app sends no header. Set on the API but not here,
+# and the purchase fails with the route's 401.
+# Generate with: openssl rand -hex 32 (see apps/api/.env.example)
+# OSS_API_INTERNAL_SECRET=your-shared-secret-here
+
 # =============================================================================
 # Better Auth (apps/web)
 # =============================================================================

package/templates/apps/web/CLAUDE.md

@@ -43,7 +43,7 @@ Raw HTML is allowed only when no `@working-theory/ui` component fits. Flag it in
 - Animations: only `transform` and `opacity`. Never `transition-all`.
 - Every interactive element needs hover, focus-visible, and active states.
 
-For the full responsive contract (path-scoped to UI files), see `.claude/rules/responsive.md`. For brand-asset discovery (logos, colors, photos), see `.claude/rules/brand.md`.
+The four widths above are the responsive contract. Brand reference files (logos, photos, colour and type notes) live in `brand_assets/` at the repo root; the site's own brand colours and fonts are set in `content/_site.mdx` under `brand.colors` and `brand.fonts`.
 
 ## Local dev
 
@@ -110,33 +110,27 @@ function — the page under test throws instead of taking a branch. Declare
 every predicate the pages call, binding the two reset ones to the same
 `jest.fn()` when the case does not need them to disagree.
 
-## Conversational intake (contact page)
-
-The contact page (`apps/web/app/[locale]/contact/`) consumes
-`ConversationalIntake` — a chat-style intake block + deterministic engine
-from `@working-theory/ui`, unmodified. The block/engine contract (six-behavior
-mapping, `NextTurn`/`IntakeScript` shapes, the v1/v2 seam) is documented in
-`packages/ui/src/blocks/conversational-intake/README.md`; read that first.
-
-This app's specific wiring: `ConversationalIntakeWrapper.tsx` hosts the
-block and owns submission + fallback; `intake-script.ts` supplies the script
-via `buildContactIntakeScript(copy)`, whose question ids (`name` / `message`
-/ `email`) double as the field-mapping contract into `submitLeadInputSchema`;
-`intake-analytics.ts` fires the `"intake-turn-abandonment"` event once per
-turn (turn index + status only, never answer text) from the block's
-`getThinkingDelayMs` override seam. Completion submits through the existing
-`captureLeadAction`; Skip or a failed submit falls back to the existing
-`<ContactForm/>`, prefilled with whatever was already captured — a lead is
-never silently lost.
-
-**Note:** the contact page currently mounts the wrapper alongside
-`renderPage`'s output (`page.tsx`), not as a page-level swap. A downstream
-Positionary consumer pattern that DID swap the whole page was corrected
-under #4577 (decision D71 — the intake belongs behind the hero CTA's
-lightbox gate; landed in PR #4583 via `packages/ui/src/sections/FormLightbox.tsx`
-and `HeroIntakeContext.tsx`, spec `docs/specs/4577-intake-lightbox-correction-spec.md`).
-Don't take a whole-page mount as the pattern to replicate; the lightbox-gate
-seam is the canonical embedding shape.
+## Contact page
+
+The contact page (`apps/web/app/[locale]/contact/page.tsx`) renders the
+page's sections through `renderPage` and places ONE contact surface: into the
+page's first `contact-form` section, else into a leading split hero's right
+column, else after the page. That surface is the shared `LeadCaptureForm`
+block from `@working-theory/ui`, bound to `captureLeadAction` — unless the
+API reports this deployment accepts no contact message (production with
+neither a database nor an email key), in which case it is `ContactFallback`:
+the site's contact email, never a form that would report a message as sent
+when it reached nobody. A failed status read counts as accepting, so the
+form renders and its submit reports honestly.
+
+The chat-style intake is not mounted by default.
+`ConversationalIntakeWrapper.tsx` remains for a site that prefers it: it hosts
+`@working-theory/ui`'s `ConversationalIntake` block (contract in
+`packages/ui/src/blocks/conversational-intake/README.md`), submits through the
+same `captureLeadAction`, and on Skip or a failed submit swaps to
+`LeadCaptureForm`, prefilled with what was already captured. The canonical
+embedding for it is behind the hero CTA's lightbox gate
+(`packages/ui/src/sections/FormLightbox.tsx`, #4577), not a whole-page mount.
 
 ## AEO & performance
 

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

@@ -24,7 +24,7 @@ import { headers } from "next/headers";
 import { getTranslations } from "next-intl/server";
 import type { ReactElement, ReactNode } from "react";
 
-import { siteLogo } from "../../../lib/site-brand";
+import { siteLogo } from "../../../lib/site-logo";
 
 interface Props {
   children: ReactNode;

package/templates/apps/web/app/[locale]/(authed)/leads/__tests__/page.test.tsx

@@ -10,6 +10,10 @@
  *   4. Renders an EmptyState — not a headerless table — for an empty page.
  *   5. Renders ForbiddenState on a 401/403; falls back to the first page
  *      when a supplied `?cursor=` 400s; rethrows every other error.
+ *   6. With no session, renders ForbiddenState and makes no apps/api request
+ *      — the (authed) layout's gate renders concurrently, so the page must
+ *      not spend (or fail) an API call on a visitor it will never serve
+ *      (#6865).
  */
 import { render, screen } from "@testing-library/react";
 
@@ -26,6 +30,13 @@ jest.mock("next/headers", () => ({
   cookies: jest.fn().mockResolvedValue({ toString: () => "session=abc" }),
 }));
 
+const mockGetSession = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- #507: mock-internal rewrite pending; auth.ts's lazy Better-Auth singleton has no HTTP/DB boundary a unit test can mock without standing up Prisma.
+jest.mock("../../../../../auth", () => ({
+  __esModule: true,
+  auth: { api: { getSession: (...args: unknown[]) => mockGetSession(...args) } },
+}));
+
 const mockList = jest.fn();
 jest.mock("@working-theory/api-client", () => ({
   __esModule: true,
@@ -64,6 +75,19 @@ function renderPage(cursor?: string) {
 describe("LeadsInboxPage", () => {
   beforeEach(() => {
     mockList.mockReset();
+    mockGetSession.mockReset();
+    mockGetSession.mockResolvedValue({ user: { id: "user_1" } });
+  });
+
+  // #6865: the (authed) layout renders SignInGate to an anonymous visitor,
+  // but Next renders this page concurrently — it must not call apps/api.
+  it("makes no apps/api request and renders ForbiddenState with no session", async () => {
+    mockGetSession.mockResolvedValue(null);
+    render(await renderPage("lead_9"));
+
+    expect(mockList).not.toHaveBeenCalled();
+    expect(screen.getByTestId("waitlist-forbidden")).toBeInTheDocument();
+    expect(screen.queryByTestId("leads-inbox-page")).not.toBeInTheDocument();
   });
 
   it("renders one row per lead, with email and source", async () => {

package/templates/apps/web/app/[locale]/(authed)/leads/page.tsx

@@ -12,15 +12,24 @@
  * waitlist comparison page uses); every other error (a 400 on a malformed
  * cursor, a 500) rethrows to the route's error boundary rather than being
  * swallowed.
+ *
+ * The page reads the session itself before any API call (#6865): Next renders
+ * it concurrently with the (authed) layout, so for an anonymous visitor the
+ * layout's `SignInGate` wins but this page would still have called
+ * `leads.list()` — spending (or, with no API reachable, failing) a request
+ * for a result nobody sees. No session renders `ForbiddenState` with no
+ * apps/api request, the same guard `../account/page.tsx` carries.
  */
 
 import { leads, type LeadInboxPage } from "@working-theory/api-client";
 import { PageHeader } from "@working-theory/ui/blocks";
 import { Container, Heading, Text } from "@working-theory/ui/primitives";
 import type { Metadata } from "next";
+import { headers } from "next/headers";
 import { getTranslations } from "next-intl/server";
 import type { ReactElement } from "react";
 
+import { auth } from "../../../../auth";
 import { ApiError, forwardedCookieInit, unwrapApiResult } from "../../../../lib/server-api";
 import { ForbiddenState } from "../waitlist/components/ForbiddenState";
 import { formatDateTime } from "../waitlist/format";
@@ -46,6 +55,13 @@ export default async function LeadsInboxPage({
   const { cursor } = await searchParams;
   const t = await getTranslations({ locale, namespace: "leadsInbox" });
 
+  const forbidden = (
+    <ForbiddenState headline={t("forbiddenHeadline")} description={t("forbiddenDescription")} />
+  );
+
+  const session = await auth.api.getSession({ headers: await headers() });
+  if (!session) return forbidden;
+
   const init = await forwardedCookieInit();
 
   let page: LeadInboxPage;
@@ -53,12 +69,7 @@ export default async function LeadsInboxPage({
     page = await unwrapApiResult(leads.list(cursor ? { cursor } : {}, init));
   } catch (err) {
     if (err instanceof ApiError && (err.status === 401 || err.status === 403)) {
-      return (
-        <ForbiddenState
-          headline={t("forbiddenHeadline")}
-          description={t("forbiddenDescription")}
-        />
-      );
+      return forbidden;
     }
     // A 400 means the `?cursor=` in the URL did not resolve — it was typed,
     // or it is a stale next-page link whose row has since gone. That is a bad

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

@@ -0,0 +1,110 @@
+/**
+ * Tests for the `[slug]/[detail]` route — the Free `/meet/<slug>` placeholder
+ * detail pages (#6897 D2).
+ *
+ * - `slug !== "meet"` → notFound() immediately, never reaching getMdxSource.
+ * - `slug === "meet"` and a BookCall source exists at `detail` → renders
+ *   through renderPage sections mode, no notFound() call.
+ * - `slug === "meet"` and no BookCall source exists at `detail` → renderPage's
+ *   own detail-route branch (no translationsNamespace passed) calls
+ *   notFound().
+ */
+import React from "react";
+import { render } from "@testing-library/react";
+
+jest.mock("next/navigation", () => ({
+  __esModule: true,
+  notFound: jest.fn(() => {
+    throw new Error("NEXT_NOT_FOUND");
+  }),
+}));
+
+jest.mock("@working-theory/ui", () => ({
+  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 { notFound } from "next/navigation";
+
+import DetailPage from "../page";
+
+const mockNotFound = notFound as jest.MockedFunction<typeof notFound>;
+
+function makeSource(slug: string) {
+  return {
+    frontmatter: {
+      type: "BookCall" as const,
+      slug,
+      title: `Title for ${slug}`,
+      description: `Description for ${slug}`,
+      sections: [
+        {
+          id: "hero",
+          type: "hero" as const,
+          data: { headline: `Title for ${slug}` },
+        },
+      ],
+    },
+    body: "",
+  };
+}
+
+describe("[slug]/[detail] — the Free /meet/<slug> placeholder route (#6897 D2)", () => {
+  beforeEach(() => {
+    mockNotFound.mockClear();
+  });
+
+  it("renders a BookCall seed at meet/<detail> through renderPage sections mode", async () => {
+    const getMdxSource = jest.fn().mockResolvedValue(makeSource("book-a-call"));
+
+    const element = await DetailPage({
+      params: Promise.resolve({ locale: "en", slug: "meet", detail: "book-a-call" }),
+      getMdxSource,
+    });
+    const { container } = render(element);
+
+    expect(getMdxSource).toHaveBeenCalledWith("BookCall", "book-a-call", "en");
+    expect(
+      container.querySelector("[data-testid='section-renderer']"),
+    ).not.toBeNull();
+    expect(
+      container.querySelector("script[type='application/ld+json']"),
+    ).not.toBeNull();
+    expect(mockNotFound).not.toHaveBeenCalled();
+  });
+
+  it("404s for another hub — the guard fires before getMdxSource is ever called", async () => {
+    const getMdxSource = jest.fn().mockResolvedValue(makeSource("book-a-call"));
+
+    await expect(
+      DetailPage({
+        params: Promise.resolve({ locale: "en", slug: "not-meet", detail: "book-a-call" }),
+        getMdxSource,
+      }),
+    ).rejects.toThrow("NEXT_NOT_FOUND");
+    expect(mockNotFound).toHaveBeenCalledTimes(1);
+    expect(getMdxSource).not.toHaveBeenCalled();
+  });
+
+  it("404s for an unknown detail slug under the meet hub", async () => {
+    const getMdxSource = jest.fn().mockResolvedValue(null);
+
+    await expect(
+      DetailPage({
+        params: Promise.resolve({ locale: "en", slug: "meet", detail: "not-a-page" }),
+        getMdxSource,
+      }),
+    ).rejects.toThrow("NEXT_NOT_FOUND");
+    expect(mockNotFound).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -0,0 +1,60 @@
+// The Free /meet/<slug> placeholder detail route (#6897 D2). BookCall
+// content served at /meet/<detail> by Next.js static-segment precedence:
+// wherever apps/web/app/[locale]/meet/ exists (the scheduling module), that
+// directory resolves every /meet/* URL first and this route never runs. On a
+// keyless scaffold, this route serves the four Free placeholder detail pages.
+//
+// `slug` must equal MEET_PLACEHOLDER_HUB ("meet") — any other value 404s.
+// This route deliberately serves ONLY the one meet hub, not a generic
+// two-segment content route: BookCall's slug pattern forbids "/", so a
+// generic join would also be reachable at a one-segment URL through the
+// `[slug]` route — a duplicate-content defect. A second hub can generalize
+// this route when one exists.
+//
+// Unknown detail slug → notFound() (renderPage's own detail-route branch: no
+// translationsNamespace is passed, so a null source 404s rather than
+// rendering an empty-state placeholder — the same contract `[slug]/page.tsx`
+// documents).
+//
+// Deliberately NO generateStaticParams, for the same reason as `[slug]/page.tsx`:
+// the locale layout reads cookies()/headers(), so this segment always renders
+// on request.
+import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
+import { renderPage, renderPageMetadata } from "@working-theory/page-renderer";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import type { ReactElement } from "react";
+
+import { MEET_PLACEHOLDER_HUB } from "../../../../lib/meet-placeholder";
+
+interface Props {
+  params: Promise<{ locale: string; slug: string; detail: string }>;
+  /** Test-only DI override for getMdxSource. Production callers leave undefined. */
+  getMdxSource?: typeof defaultGetMdxSource;
+}
+
+export async function generateMetadata({
+  params,
+}: Pick<Props, "params">): Promise<Metadata> {
+  const { locale, slug, detail } = await params;
+  // Mirrors renderPageMetadata's own missing-frontmatter → {} contract: a
+  // hub mismatch is the same "nothing to title" case, not a thrown 404 —
+  // generateMetadata cannot itself change the response status.
+  if (slug !== MEET_PLACEHOLDER_HUB) return {};
+  return renderPageMetadata({ type: "BookCall", slug: detail, locale });
+}
+
+export default async function Page({
+  params,
+  getMdxSource,
+}: Props): Promise<ReactElement> {
+  const { locale, slug, detail } = await params;
+  if (slug !== MEET_PLACEHOLDER_HUB) notFound();
+  return renderPage({
+    type: "BookCall",
+    slug: detail,
+    locale,
+    populatedDescriptionTestId: `${detail}-description`,
+    ...(getMdxSource !== undefined && { getMdxSource }),
+  });
+}

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

@@ -21,7 +21,7 @@
 // `ItemList` — the correct page type, not a LandingPage wearing a `schema:`
 // override the structured-data gate rejects) served here, and still yields
 // to the module's directory by the same precedence. Every other list type
-// has its own route directory (`/features` → ProductsList, `/use-cases` →
+// has its own route directory (`/features` → ProductsList, `/for` →
 // UseCasesList) and never reaches this route.
 //
 // Unknown slug → `notFound()` (renderPage's own detail-route branch: no

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

@@ -0,0 +1,161 @@
+/**
+ * Tests for /alternatives (#6878 D9) — the ComparisonsList hub.
+ *
+ * `renderPage`/`renderPageMetadata`/`getMdxSlugs` are mocked at the
+ * `@working-theory/page-renderer` boundary so this suite can assert on the
+ * exact input `renderPage` receives — in particular the injected
+ * `getPageSections` override that appends the generated spoke list (AC-7:
+ * "the hub links each /vs spoke").  `getMdxSource` and `getPageSections`
+ * (the hub's own declared sections) are supplied per-call through the
+ * route's DI props, as every other page in this app does.
+ */
+// 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[]>([]));
+const mockNotFound = jest.fn(() => {
+  throw new Error("NEXT_NOT_FOUND");
+});
+
+jest.mock("next/navigation", () => ({
+  __esModule: true,
+  notFound: () => mockNotFound(),
+}));
+
+jest.mock("@working-theory/page-renderer", () => ({
+  __esModule: true,
+  getMdxSlugs: (...args: unknown[]) => mockGetMdxSlugs(...args),
+  renderPage: (...args: unknown[]) => mockRenderPage(...args),
+  renderPageMetadata: (...args: unknown[]) => mockRenderPageMetadata(...args),
+  // Never reached — every call in this suite passes both via DI props.
+  getMdxSource: jest.fn(),
+  getPageSections: jest.fn(),
+}));
+
+import AlternativesPage, { generateMetadata } from "../page";
+
+const HUB_SOURCE = {
+  frontmatter: {
+    type: "ComparisonsList",
+    slug: "alternatives",
+    title: "Alternatives",
+    description: "How we compare.",
+  },
+  body: "",
+};
+
+beforeEach(() => jest.clearAllMocks());
+
+describe("AlternativesPage — hub seed absent", () => {
+  it("calls notFound() and never reaches renderPage", async () => {
+    const getMdxSource = jest.fn().mockResolvedValue(null);
+
+    await expect(
+      AlternativesPage({
+        params: Promise.resolve({ locale: "en" }),
+        getMdxSource,
+        getPageSections: jest.fn(),
+      }),
+    ).rejects.toThrow("NEXT_NOT_FOUND");
+
+    expect(mockNotFound).toHaveBeenCalledTimes(1);
+    expect(mockRenderPage).not.toHaveBeenCalled();
+  });
+});
+
+describe("AlternativesPage — metadata", () => {
+  it("resolves ComparisonsList slug alternatives", async () => {
+    await generateMetadata({ params: Promise.resolve({ locale: "en" }) });
+    expect(mockRenderPageMetadata).toHaveBeenCalledWith({
+      type: "ComparisonsList",
+      slug: "alternatives",
+      locale: "en",
+    });
+  });
+});
+
+describe("AlternativesPage — generated spoke list (D9)", () => {
+  it("appends one items section entry per ComparisonPage spoke, each linking /vs/<slug>", async () => {
+    mockGetMdxSlugs.mockResolvedValue(["acme", "globex"]);
+    const spokeSources: Record<string, unknown> = {
+      acme: {
+        frontmatter: { title: "vs. Acme", description: "How we compare to Acme." },
+        body: "",
+      },
+      globex: {
+        frontmatter: { title: "vs. Globex", description: "How we compare to Globex." },
+        body: "",
+      },
+    };
+    const getMdxSource = jest
+      .fn()
+      .mockImplementation((type: string, slug: string) => {
+        if (type === "ComparisonsList") return Promise.resolve(HUB_SOURCE);
+        return Promise.resolve(spokeSources[slug] ?? null);
+      });
+    const getPageSections = jest
+      .fn()
+      .mockResolvedValue([{ id: "hero", type: "hero", data: {} }]);
+
+    await AlternativesPage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource,
+      getPageSections,
+    });
+
+    expect(mockRenderPage).toHaveBeenCalledTimes(1);
+    const passedInput = mockRenderPage.mock.calls[0]?.[0] as {
+      type: string;
+      slug: string;
+      getPageSections: (frontmatter: unknown) => Promise<unknown[]>;
+    };
+    expect(passedInput.type).toBe("ComparisonsList");
+    expect(passedInput.slug).toBe("alternatives");
+
+    const sections = await passedInput.getPageSections({});
+    expect(sections).toEqual([
+      { id: "hero", type: "hero", data: {} },
+      {
+        type: "items",
+        id: "comparison-spokes",
+        data: {
+          items: [
+            {
+              title: "vs. Acme",
+              description: "How we compare to Acme.",
+              link: { label: "Read the comparison", href: "/vs/acme" },
+            },
+            {
+              title: "vs. Globex",
+              description: "How we compare to Globex.",
+              link: { label: "Read the comparison", href: "/vs/globex" },
+            },
+          ],
+        },
+      },
+    ]);
+  });
+
+  it("omits the generated section entirely with zero spokes (the hub's own sections render alone)", async () => {
+    mockGetMdxSlugs.mockResolvedValue([]);
+    const getMdxSource = jest.fn().mockResolvedValue(HUB_SOURCE);
+    const getPageSections = jest
+      .fn()
+      .mockResolvedValue([{ id: "hero", type: "hero", data: {} }]);
+
+    await AlternativesPage({
+      params: Promise.resolve({ locale: "en" }),
+      getMdxSource,
+      getPageSections,
+    });
+
+    const passedInput = mockRenderPage.mock.calls[0]?.[0] as {
+      getPageSections: (frontmatter: unknown) => Promise<unknown[]>;
+    };
+    const sections = await passedInput.getPageSections({});
+    expect(sections).toEqual([{ id: "hero", type: "hero", data: {} }]);
+  });
+});