create-ailk 0.30.0 → 0.31.0

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.
 
-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`. The signed-out header button is set there too, as `header.cta` (`label`, `href`), with `header.signIn: link | hidden` choosing whether Sign in stays beside it as a text link — never by editing `app/[locale]/layout.tsx`. Each page's chrome is set there too (#10049, resolved by `lib/page-chrome.ts`): `header.style` (`full | bare | none`), `footer.style` (`columns | centered | closing | none`), `layout` (`deck | default`, the home's) and one `{ header, footer }` key per route family (`blog`, `docs`, `services`, …), with a page's own `header:` / `footer:` / `layout:` frontmatter winning over all of them.
+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`. The signed-out header button is set there too, as `header.cta` (`label`, `href`), with `header.signIn: link | hidden` choosing whether Sign in stays beside it as a text link — never by editing `app/[locale]/layout.tsx`. Each page's chrome is set there too (#10049, resolved by `lib/page-chrome.ts`): `header.style` (`full | bare | none`), `footer.style` (`columns | centered | closing | none`), `layout` (`deck | default`, the home's) and one `{ header, footer }` key per route family (`blog`, `docs`, `services`, …), with a page's own `header:` / `footer:` / `layout:` frontmatter winning over all of them. The closing footer alone also reads three site-level keys (#10550): `footer.locality` (the line above the email, winning over the identity's address), `footer.actions` (one or two `{ label, href }` site paths — the primary, then the secondary — in place of the auth links) and `footer.legalBar` (off by default: `true` moves the legal line into a full-width bottom bar, on the deck's closing slide its bottom edge). The cookie notice's look is set there too (#10555, #10721): `consent.appearance` is `compact` (the floating card, bottom-left) or `hairline` (the full-width band on the page ground); absent, it follows the design's `chromeStyle` — the band under `minimal`, else the card. Only the band waits for the minimal deck home's first slide to leave view (#7782); the card shows on load on every page.
 
 ## Local dev
 
@@ -277,8 +277,8 @@ embedding for it is behind the hero CTA's lightbox gate
 
 The workspace's **Newsletter magnet** (#8847) — seeded live at slug
 `newsletter` in every workspace — is the only source of `/newsletter`,
-`/unsubscribe` and the footer signup; none of their copy is in page code,
-content or the message catalog. All three read it through
+`/unsubscribe`, the footer signup and a bound `newsletter` section; none of
+their copy is in page code, content or the message catalog. All four read it through
 `lib/in-page-magnet.ts`'s `readServedMagnet("newsletter")`, shared for 15
 seconds per instance like /contact's read.
 
@@ -306,6 +306,13 @@ seconds per instance like /contact's read.
 - **The footer** fills `Footer`'s `subscribe` slot with the compact form
   (stacked, `sr-only` label) only when the magnet is served and capture is
   on; the built-in config never fills it.
+- **A bound `newsletter` section** (#10629) — a content `newsletter` section
+  with `magnet: "newsletter"` in place of `action` renders, under its own
+  headline, the full-size signup the locale layout builds from the footer's
+  same read and hands every page through `NewsletterSignupProvider` — with
+  `consentGate: "on-submit"`, so Subscribe stays enabled and an unticked
+  submit shows the consent error beside the box. It renders nothing whenever
+  the footer would show nothing. A section with `action` posts as before.
 
 ## Careers
 
@@ -581,7 +588,7 @@ A visitor's browser never calls the hub. Lead capture, newsletter signup, callba
 - **No cross-site POST.** A `Sec-Fetch-Site` other than `same-origin`, or an `Origin` not on this site's own host, is refused 403 before the hub is called.
 - **Headers are an allow-list.** The visitor's `x-forwarded-for` (else `x-real-ip`) and `user-agent` pass through so per-visitor rate limits still count each visitor; no `authorization`, client-sent `x-ailk-*` or `host` is forwarded, and a `cookie` goes only on `POST /v1/commerce/invoices`, the one session route.
 - **The relay has its own per-visitor budget (#7707).** Each visitor gets 8 calls per 10 minutes across the five visitor routes, and the session route (`POST /v1/commerce/invoices`) gets its own, wider budget of 30 per 10 minutes; the call that exceeds either gets `429 rate_limited` before any hub call. The budget is held in this instance's own process (no shared store, no env variable) and holds only where the site's edge overwrites `x-forwarded-for` and `x-real-ip` — Vercel does; a bare self-hosted Next server does not.
-- **A bot check on the public writes (#9889, #9255).** On Vercel, `lib/bot-check.ts`'s `runBotCheck` asks Vercel BotID for a verdict before the hub is called — in the relay for `POST /v1/leads/{submit,subscribe,callback}` and `POST /v1/schedule/book` (`BOT_CHECKED_ROUTES`: `403 bot_detected`, or `503 bot_check_unavailable` when the check throws, answers no boolean or takes over 5 seconds), and in the contact, careers, newsletter, flow-step, flow-checkout, saved-recommendation and `/dev/purchase` Server Actions immediately before their hub call, which answer their own existing failure variant. The locale layout's `BotIdClient` protects every same-origin POST (`BOT_CLIENT_PROTECT`, `/*`), because a Server Action posts to the page it was submitted from; `next.config.mjs` wraps `withBotId` and `middleware.ts` keeps BotID's proxy prefix out of its matcher. It is on by default and inert off Vercel: `AILK_BOT_CHECK=off` turns every check off, `AILK_BOOKING_BOT_CHECK=off` the booking's alone, and MCP tools never pass through a site, so they are never challenged.
+- **A bot check on the public writes (#9889, #9255).** On Vercel, `lib/bot-check.ts`'s `runBotCheck` asks Vercel BotID for a verdict before the hub is called — in the relay for `POST /v1/leads/{submit,subscribe,callback}` and `POST /v1/schedule/book` (`BOT_CHECKED_ROUTES`: `403 bot_detected`, or `503 bot_check_unavailable` when the check throws, answers no boolean or takes over 5 seconds), and in the contact, careers, newsletter, flow-step, flow-checkout, saved-recommendation and `/dev/purchase` Server Actions immediately before their hub call, which answer their own existing failure variant. The locale layout's `BotIdClient` protects every same-origin POST (`BOT_CLIENT_PROTECT`, `/*`), because a Server Action posts to the page it was submitted from; `next.config.mjs` wraps `withBotId` and `middleware.ts` keeps BotID's proxy prefix out of its matcher. It is on by default and inert off Vercel: `AILK_BOT_CHECK=off` turns every check off, `AILK_BOOKING_BOT_CHECK=off` the booking's alone, and MCP tools never pass through a site, so they are never challenged. A refusal logs `[<source>] bot refused` with BotID's `classificationReason`, `bypassed` and `isVerifiedBot`, the request's `host` and `forwardedHost`, and `proxied` (a `cf-ray` header) — no other header value, no form field (#10715). `AILK_BOT_CHECK=observe` runs the check and logs the same facts plus `isBot` as `observed`, but passes every write — for diagnosis only. **A BotID-protected site must be reached directly — Cloudflare DNS-only, no reverse proxy in front of Vercel (#10715).** Behind a proxy the write reaches Vercel from the proxy's egress rather than the browser that solved the challenge, so BotID refuses every real visitor; the first proxied request per process logs `[<source>] reverse proxy detected` (outcome `proxied`) naming that fix.
 - `/v1` is exempt from next-intl's locale rewrite in `middleware.ts`, as `/api` is.
 
 ## Where the docs live (`docsPath`)
@@ -637,7 +644,11 @@ A list page whose frontmatter sets `navOnly: true` (valid on a registry list typ
 - Don't reach into `apps/api` or `apps/mcp` from `apps/web`. They're peer apps — talk via HTTP/MCP.
 - Don't commit images to `screenshots/` — only the `.gitkeep` is tracked.
 
-Last updated: 2026-11-01 — § The owner's discovery switch: the six discovery files read the workspace's `discoverable` setting per request through `siteDiscoverable()`, off answering robots.txt's disallow-all and 404 for the rest, never cached (#10510) — verified against `app/{robots.txt,sitemap.xml,llms.txt,openapi.json}/route.ts`, `app/.well-known/{mcp.json,ai-plugin.json}/route.ts`, `lib/slices/docs-blog/llms-route.ts` and `packages/api-client/src/discovery.ts`.
+Last updated: 2026-11-02 — § Theme & styling: `consent.appearance` named beside the other `_site.mdx` chrome keys, and the minimal deck home's hold-back is the band's alone, so a minimal site that picks the card sees it on load there too (#10721) — verified against `app/[locale]/layout.tsx`.
+
+Prior: 2026-11-02 — § The same-origin relay: a bot-check refusal names its cause (`classificationReason`, `bypassed`, `isVerifiedBot`, both hosts, `proxied`), `AILK_BOT_CHECK=observe` logs and never refuses, and a BotID-protected site must be reached directly, Cloudflare DNS-only (#10715) — verified against `lib/bot-check.ts`.
+
+Prior: 2026-11-01 — § The owner's discovery switch: the six discovery files read the workspace's `discoverable` setting per request through `siteDiscoverable()`, off answering robots.txt's disallow-all and 404 for the rest, never cached (#10510) — verified against `app/{robots.txt,sitemap.xml,llms.txt,openapi.json}/route.ts`, `app/.well-known/{mcp.json,ai-plugin.json}/route.ts`, `lib/slices/docs-blog/llms-route.ts` and `packages/api-client/src/discovery.ts`.
 
 Prior: 2026-10-30 — § The MCP authorization server: the site's OAuth 2.1 authorization server, its consent step, rotation and revocation (#10357) — verified against `auth.ts`, `lib/mcp-oauth.ts`, `app/[locale]/(auth)/consent/` and `app/.well-known/oauth-authorization-server/route.ts`.
 

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

@@ -50,6 +50,33 @@ jest.mock("../../../../../lib/paid-sections.generated", () => {
   };
 });
 
+// #10552 — an MDX body's `## ` lines render through the page's own component
+// map, so a heading's `id` is the real heading adapter's (AC-4).
+jest.mock("next-mdx-remote/rsc", () => {
+  const { createElement, Fragment } = jest.requireActual<typeof import("react")>("react");
+  return {
+    MDXRemote: ({
+      source,
+      components,
+    }: {
+      source: string;
+      components: Record<string, React.ComponentType<{ children?: React.ReactNode }>>;
+    }) =>
+      createElement(
+        Fragment,
+        null,
+        ...source
+          .split("\n")
+          .filter((line) => line.trim() !== "")
+          .map((line, i) =>
+            line.startsWith("## ")
+              ? createElement(components["h2"]!, { key: i }, line.slice(3))
+              : createElement("p", { key: i }, line),
+          ),
+      ),
+  };
+});
+
 jest.mock("@working-theory/ui", () => ({
   // #7789: renderPage's fallback page head renders inside the section Container.
   Container: ({ children }: { children?: React.ReactNode }) =>
@@ -60,10 +87,12 @@ jest.mock("@working-theory/ui", () => ({
   Heading: ({
     children,
     level,
+    id,
   }: {
     children: React.ReactNode;
     level: number;
-  }): React.ReactElement => React.createElement(`h${level}`, null, children),
+    id?: string;
+  }): React.ReactElement => React.createElement(`h${level}`, id ? { id } : null, children),
   SectionRenderer: ({ sections }: { sections: unknown[] }) =>
     React.createElement("div", {
       "data-testid": "section-renderer",
@@ -73,7 +102,8 @@ jest.mock("@working-theory/ui", () => ({
 
 import { notFound } from "next/navigation";
 
-import DetailPage from "../page";
+import { listingExtension } from "../../../../../lib/listings";
+import DetailPage, { generateMetadata } from "../page";
 
 const mockNotFound = notFound as jest.MockedFunction<typeof notFound>;
 
@@ -120,7 +150,7 @@ describe("[slug]/[detail] — the Free /meet/<slug> placeholder route (#6897 D2)
     expect(mockNotFound).not.toHaveBeenCalled();
   });
 
-  it("404s for another hub — the guard fires before getMdxSource is ever called", async () => {
+  it("404s for another hub — no BookCall source is ever read", async () => {
     const getMdxSource = jest.fn().mockResolvedValue(makeSource("book-a-call"));
 
     await expect(
@@ -130,7 +160,9 @@ describe("[slug]/[detail] — the Free /meet/<slug> placeholder route (#6897 D2)
       }),
     ).rejects.toThrow("NEXT_NOT_FOUND");
     expect(mockNotFound).toHaveBeenCalledTimes(1);
-    expect(getMdxSource).not.toHaveBeenCalled();
+    // #10552 — the program-event branch reads the Event source first; the
+    // meet branch's BookCall read never runs for another hub.
+    expect(getMdxSource).not.toHaveBeenCalledWith("BookCall", expect.anything(), expect.anything());
   });
 
   it("404s for an unknown detail slug under the meet hub", async () => {
@@ -248,3 +280,120 @@ describe("[slug]/[detail] — a listicle entry at /<landingPage>/<slug> (#7521)"
     expect(global.fetch).not.toHaveBeenCalled();
   });
 });
+
+// ── #10552 — an Event under a program at /<program>/<event> ─────────────────
+describe("[slug]/[detail] — an Event under a program at /<program>/<event> (#10552)", () => {
+  const landing = (slug: string, title: string) => ({
+    frontmatter: { type: "LandingPage" as const, slug, title, description: `${title}.` },
+    body: "",
+  });
+  const golf = (frontmatter: Record<string, unknown> = { parent: "younglife" }) => ({
+    frontmatter: {
+      type: "Event" as const,
+      slug: "golf-tournament",
+      title: "Golf Tournament 2026",
+      description: "Our annual golf tournament.",
+      publishedAt: "2026-06-12",
+      ...frontmatter,
+    },
+    body: "Tee off with us.\n\n## Sponsorship\n\nBecome a hole sponsor.",
+  });
+  const loader = (
+    pages: Record<string, ReturnType<typeof landing> | ReturnType<typeof golf>>,
+  ) => jest.fn(async (type: string, slug: string) => pages[`${type}/${slug}`] ?? null);
+  const params = (slug: string, detail = "golf-tournament") =>
+    Promise.resolve({ locale: "en", slug, detail });
+
+  let entryAt: jest.SpyInstance;
+  beforeEach(() => {
+    mockNotFound.mockClear();
+    entryAt = jest.spyOn(listingExtension, "entryAt");
+  });
+  afterEach(() => entryAt.mockRestore());
+
+  it("renders the Event with its Event JSON-LD and the program breadcrumb (AC-3)", async () => {
+    const getMdxSource = loader({
+      "LandingPage/younglife": landing("younglife", "Young Life"),
+      "Event/golf-tournament": golf(),
+    });
+
+    const { container } = render(await DetailPage({ params: params("younglife"), getMdxSource }));
+
+    expect(mockNotFound).not.toHaveBeenCalled();
+    const ld = JSON.parse(
+      container.querySelector("script[type='application/ld+json']")?.textContent ?? "{}",
+    ) as Record<string, unknown>;
+    const nodes = (ld["@graph"] ?? [ld]) as Array<Record<string, unknown>>;
+    const event = nodes
+      .map((node) => node["mainEntity"] as Record<string, unknown> | undefined)
+      .find((entity) => entity?.["@type"] === "Event");
+    expect(event).toMatchObject({ name: "Golf Tournament 2026", startDate: "2026-06-12" });
+    const crumbs = nodes.find((node) => node["@type"] === "BreadcrumbList")?.[
+      "itemListElement"
+    ] as Array<Record<string, unknown>>;
+    expect(crumbs[1]).toMatchObject({ name: "Young Life" });
+    expect(crumbs[2]?.["item"]).toMatch(/\/younglife\/golf-tournament$/);
+    expect(entryAt).not.toHaveBeenCalled();
+
+    const metadata = await generateMetadata({ params: params("younglife"), getMdxSource });
+    expect(metadata.title).toBe("Golf Tournament 2026");
+  });
+
+  it("offers add-to-calendar for Google, Outlook and Apple (.ics) at the program URL", async () => {
+    const getMdxSource = loader({
+      "LandingPage/younglife": landing("younglife", "Young Life"),
+      "Event/golf-tournament": golf(),
+    });
+
+    const { container } = render(await DetailPage({ params: params("younglife"), getMdxSource }));
+
+    const href = (id: string) =>
+      container.querySelector(`[data-testid='add-to-calendar-${id}']`)?.getAttribute("href") ?? "";
+    expect(href("google")).toMatch(/^https:\/\/calendar\.google\.com\//);
+    expect(href("outlook")).toMatch(/^https:\/\/outlook\./);
+    expect(href("apple")).toMatch(/^data:text\/calendar/);
+    expect(decodeURIComponent(href("apple"))).toContain("/younglife/golf-tournament");
+  });
+
+  it("supports a #sponsorship anchor from the body heading (AC-4)", async () => {
+    const getMdxSource = loader({
+      "LandingPage/younglife": landing("younglife", "Young Life"),
+      "Event/golf-tournament": golf(),
+    });
+
+    const { container } = render(await DetailPage({ params: params("younglife"), getMdxSource }));
+
+    const anchors = container.querySelectorAll("#sponsorship");
+    expect(anchors).toHaveLength(1);
+    expect(anchors[0]?.tagName).toBe("H2");
+    expect(anchors[0]?.textContent).toBe("Sponsorship");
+  });
+
+  it("serves it only under the program it names (AC-5)", async () => {
+    const cases: Array<[string, ReturnType<typeof loader>]> = [
+      [
+        "other",
+        loader({
+          "LandingPage/other": landing("other", "Other"),
+          "LandingPage/younglife": landing("younglife", "Young Life"),
+          "Event/golf-tournament": golf(),
+        }),
+      ],
+      ["younglife", loader({ "Event/golf-tournament": golf() })],
+      [
+        "younglife",
+        loader({
+          "LandingPage/younglife": landing("younglife", "Young Life"),
+          "Event/golf-tournament": golf({}),
+        }),
+      ],
+    ];
+    for (const [slug, getMdxSource] of cases) {
+      mockNotFound.mockClear();
+      await expect(DetailPage({ params: params(slug), getMdxSource })).rejects.toThrow(
+        "NEXT_NOT_FOUND",
+      );
+      expect(mockNotFound).toHaveBeenCalledTimes(1);
+    }
+  });
+});

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

@@ -1,5 +1,6 @@
 // Two-segment URLs: the Free /meet/<slug> placeholder detail pages (#6897
-// D2), and a listicle directory's entry pages (#7521).
+// D2), an Event under a program (#10552), and a listicle directory's entry
+// pages (#7521).
 //
 // The meet hub: BookCall content served at /meet/<detail> by Next.js
 // static-segment precedence: wherever apps/web/app/[locale]/meet/ exists (the
@@ -10,6 +11,13 @@
 // 404s rather than rendering an empty-state placeholder — the same contract
 // `[slug]/page.tsx` documents).
 //
+// A program's event: `/<program>/<event>` serves the Event MDX `<event>` when
+// its frontmatter `parent` is `<program>` and `/<program>` is a LandingPage —
+// before the listing extension, so an event URL costs no listing read. Any
+// other combination falls through. A `parent` that names a static top-level
+// route directory (`events`, `services`, …) or `meet` is unreachable here:
+// Next.js serves the static directory first (spec 10552 § 5.3).
+//
 // Every other hub: `/<landingPage>/<entry>` for a listicle whose landing page
 // is a generic one-segment page (`/tools` → `[slug]/page.tsx`). The listing
 // extension (`lib/listings.tsx`) renders the accepted entry, or the route
@@ -49,6 +57,18 @@ function hubPage(
     (await getMdxSource("BlogList", slug, locale)) !== null;
 }
 
+/** The Event `detail` when it names `slug` as its program and `/<slug>` is a LandingPage. */
+async function programEvent(
+  slug: string,
+  detail: string,
+  locale: string,
+  getMdxSource: typeof defaultGetMdxSource = loadMdxSource,
+): Promise<Awaited<ReturnType<typeof defaultGetMdxSource>>> {
+  const source = await getMdxSource("Event", detail, locale);
+  if (source === null || source.frontmatter.parent !== slug) return null;
+  return (await getMdxSource("LandingPage", slug, locale)) === null ? null : source;
+}
+
 interface Props {
   params: Promise<{ locale: string; slug: string; detail: string }>;
   /** Test-only DI override for getMdxSource. Production callers leave undefined. */
@@ -57,12 +77,21 @@ interface Props {
 
 export async function generateMetadata({
   params,
-}: Pick<Props, "params">): Promise<Metadata> {
+  getMdxSource,
+}: Pick<Props, "params" | "getMdxSource">): Promise<Metadata> {
   const { locale, slug, detail } = await params;
   // Mirrors renderPageMetadata's own missing-frontmatter → {} contract: a
   // hub with no listing entry is the same "nothing to title" case, not a
   // thrown 404 — generateMetadata cannot itself change the response status.
   if (slug !== MEET_PLACEHOLDER_HUB) {
+    if ((await programEvent(slug, detail, locale, getMdxSource)) !== null) {
+      return renderPageMetadata({
+        type: "Event",
+        slug: detail,
+        locale,
+        ...(getMdxSource !== undefined && { getMdxSource }),
+      });
+    }
     return (
       (await listingExtension.entryMetadataAt(
         `/${slug}/${detail}`,
@@ -81,6 +110,20 @@ export default async function Page({
 }: Props): Promise<ReactElement> {
   const { locale, slug, detail } = await params;
   if (slug !== MEET_PLACEHOLDER_HUB) {
+    const event = await programEvent(slug, detail, locale, getMdxSource);
+    if (event !== null) {
+      // A composed Event renders its sections; a prose one its MDX body — the
+      // rule events/[slug]/page.tsx applies.
+      const sections = (event.frontmatter as { sections?: unknown[] }).sections;
+      const composed = Array.isArray(sections) && sections.length > 0;
+      return renderPage({
+        type: "Event",
+        slug: detail,
+        locale,
+        ...(composed ? {} : { bodyMode: "mdx-body" as const }),
+        ...(getMdxSource !== undefined && { getMdxSource }),
+      });
+    }
     const entry = await listingExtension.entryAt(
       `/${slug}/${detail}`,
       detail,

package/templates/apps/web/app/[locale]/contact/__tests__/site-contact-lines.test.ts

@@ -161,3 +161,52 @@ describe("readSiteContactLines (#7742 D4)", () => {
     expect(readSiteContactLines()).toEqual([]);
   });
 });
+
+describe("readSiteContactLines(locality) — the site's own locality line (#10550 D2)", () => {
+  function writePerson(): void {
+    writeSite(
+      [
+        "siteName: Wendi Henry",
+        "contactEmail: a@b.test",
+        "siteIdentity:",
+        "  kind: Person",
+        "  name: Wendi Henry",
+        "  url: https://wendi.test",
+        ...addressYaml("  ", "Denver", "CO"),
+      ].join("\n"),
+    );
+  }
+
+  it("a set locality wins over the address line, above the email", () => {
+    writePerson();
+    expect(readSiteContactLines("Colorado Springs, CO")).toEqual([
+      { label: "Colorado Springs, CO" },
+      { label: "a@b.test", href: "mailto:a@b.test" },
+    ]);
+  });
+
+  it.each([[undefined], ["  "]])("locality %p keeps the address line", (locality) => {
+    writePerson();
+    expect(readSiteContactLines(locality)).toEqual([
+      { label: "Denver, CO" },
+      { label: "a@b.test", href: "mailto:a@b.test" },
+    ]);
+  });
+
+  it("an Organization takes the set locality, then the email", () => {
+    writeSite(
+      [
+        "siteName: Acme",
+        "contactEmail: a@b.test",
+        "siteIdentity:",
+        "  kind: Organization",
+        "  name: Acme",
+        "  url: https://acme.test",
+      ].join("\n"),
+    );
+    expect(readSiteContactLines("Colorado Springs, CO")).toEqual([
+      { label: "Colorado Springs, CO" },
+      { label: "a@b.test", href: "mailto:a@b.test" },
+    ]);
+  });
+});

package/templates/apps/web/app/[locale]/contact/site-contact-lines.ts

@@ -8,7 +8,9 @@
  *      read through the typed `SiteIdentitySchema` (#7824), so an invalid
  *      identity or address gives no line rather than a half-trusted one;
  *   2. the published contact email (`readSiteContactEmail`, the address
- *      `/contact` shows), as a `mailto:` link.
+ *      `/contact` shows), as a `mailto:` link;
+ *   3. a site's own `footer.locality` (#10550 D2), passed in by the layout,
+ *      which replaces line 1 when it is non-blank.
  *
  * Either line is left out when the site has none, so a site shows zero, one
  * or two lines. The same local `_site.mdx` frontmatter read as its sibling
@@ -54,11 +56,11 @@ function readLocalityLine(): string | undefined {
   return parts.length > 0 ? parts.join(", ") : undefined;
 }
 
-export function readSiteContactLines(): SiteContactLine[] {
+export function readSiteContactLines(locality?: string): SiteContactLine[] {
   try {
     const lines: SiteContactLine[] = [];
-    const locality = readLocalityLine();
-    if (locality !== undefined) lines.push({ label: locality });
+    const localityLine = nonEmpty(locality) ?? readLocalityLine();
+    if (localityLine !== undefined) lines.push({ label: localityLine });
     const email = readSiteContactEmail();
     if (email !== undefined) lines.push({ label: email, href: `mailto:${email}` });
     return lines;

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

@@ -1,5 +1,7 @@
 // Event detail page. Reads the Event MDX for the given slug, renders via
 // renderPage, and emits a JSON-LD <script>. Unknown slugs 404 through renderPage.
+// An Event under a program (`parent`) lives at /<program>/<event> (#10552), so
+// this URL answers a 308 there.
 import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
 import {
   getMdxSource as loadMdxSource,
@@ -7,6 +9,7 @@ import {
   renderPageMetadata,
 } from "@working-theory/page-renderer";
 import type { Metadata } from "next";
+import { permanentRedirect } from "next/navigation";
 import type { ReactElement } from "react";
 
 interface Props {
@@ -29,7 +32,16 @@ export default async function Page({
   // A page that composes `sections[]` renders them (JSON-LD is built from
   // the same sections); a prose page renders its MDX body — the rule
   // /vs/[slug] applies (#10122).
-  const source = await (getMdxSource ?? loadMdxSource)("Event", slug, locale);
+  const load = getMdxSource ?? loadMdxSource;
+  const source = await load("Event", slug, locale);
+  const parent = source?.frontmatter.parent;
+  // Only to a program the program route serves (a LandingPage at /<parent>),
+  // so a mistyped `parent` never turns this URL into a dead redirect.
+  if (parent !== undefined && (await load("LandingPage", parent, locale)) !== null) {
+    const defaultLocale = process.env.NEXT_PUBLIC_DEFAULT_LOCALE ?? "en";
+    const prefix = locale === defaultLocale ? "" : `/${locale}`;
+    permanentRedirect(`${prefix}/${parent}/${slug}`);
+  }
   const composed =
     source !== null &&
     Array.isArray((source.frontmatter as { sections?: unknown[] }).sections) &&

package/templates/apps/web/app/[locale]/events/__tests__/program-event.test.tsx

@@ -0,0 +1,120 @@
+/**
+ * #10552 AC-6 — an Event under a program has one URL, `/<program>/<event>`:
+ * `/events/<event>` answers a 308 there, and the /events hub's card links it
+ * directly. An Event with no `parent` keeps `/events/<event>` on both.
+ *
+ * Its own suite: `hub-children.test.tsx` mocks `@working-theory/page-renderer`
+ * whole, so the hub's real cards are not rendered there.
+ */
+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");
+  }),
+  permanentRedirect: jest.fn((url: string) => {
+    throw new Error(`NEXT_REDIRECT ${url}`);
+  }),
+}));
+
+import { permanentRedirect } from "next/navigation";
+
+import EventsPage from "../page";
+import EventSlugPage from "../[slug]/page";
+
+const mockRedirect = permanentRedirect as jest.MockedFunction<typeof permanentRedirect>;
+
+const event = (slug: string, parent?: string) => ({
+  frontmatter: {
+    type: "Event" as const,
+    slug,
+    title: `Title for ${slug}`,
+    description: `Description for ${slug}.`,
+    ...(parent !== undefined && { parent }),
+  },
+  body: `# Title for ${slug}\n\nBody.`,
+});
+
+const eventsList = {
+  frontmatter: { type: "EventsList" as const, slug: "events", title: "Events", description: "Events." },
+  body: "# Events\n\nBody.",
+};
+
+const events: Record<string, ReturnType<typeof event>> = {
+  "golf-tournament": event("golf-tournament", "younglife"),
+  "annual-summit": event("annual-summit"),
+  "typo-gala": event("typo-gala", "no-such-program"),
+};
+
+const younglife = {
+  frontmatter: { type: "LandingPage" as const, slug: "younglife", title: "Young Life", description: "YL." },
+  body: "",
+};
+
+const getMdxSource = jest.fn(async (type: string, slug: string) =>
+  type === "Event"
+    ? (events[slug] ?? null)
+    : type === "EventsList"
+      ? eventsList
+      : type === "LandingPage" && slug === "younglife"
+        ? younglife
+        : null,
+);
+
+describe("/events/<event> for an Event under a program (#10552 D3)", () => {
+  const savedDefault = process.env.NEXT_PUBLIC_DEFAULT_LOCALE;
+  beforeEach(() => {
+    mockRedirect.mockClear();
+    delete process.env.NEXT_PUBLIC_DEFAULT_LOCALE;
+  });
+  afterAll(() => {
+    if (savedDefault === undefined) delete process.env.NEXT_PUBLIC_DEFAULT_LOCALE;
+    else process.env.NEXT_PUBLIC_DEFAULT_LOCALE = savedDefault;
+  });
+
+  it.each([
+    ["en", "/younglife/golf-tournament"],
+    ["es", "/es/younglife/golf-tournament"],
+  ])("answers a 308 to the program URL at %s", async (locale, target) => {
+    await expect(
+      EventSlugPage({ params: Promise.resolve({ locale, slug: "golf-tournament" }), getMdxSource }),
+    ).rejects.toThrow(`NEXT_REDIRECT ${target}`);
+    expect(mockRedirect).toHaveBeenCalledWith(target);
+  });
+
+  it("does not redirect when the parent names no program page", async () => {
+    render(
+      await EventSlugPage({ params: Promise.resolve({ locale: "en", slug: "typo-gala" }), getMdxSource }),
+    );
+    expect(mockRedirect).not.toHaveBeenCalled();
+  });
+
+  it("renders an Event with no parent, with no redirect", async () => {
+    const { container } = render(
+      await EventSlugPage({
+        params: Promise.resolve({ locale: "en", slug: "annual-summit" }),
+        getMdxSource,
+      }),
+    );
+    expect(mockRedirect).not.toHaveBeenCalled();
+    expect(container.querySelector("script[type='application/ld+json']")).not.toBeNull();
+  });
+});
+
+describe("the /events hub's card for an Event under a program (#10552 D5)", () => {
+  it("links the program URL, and /events/<slug> for an Event with no parent", async () => {
+    const { container } = render(
+      await EventsPage({
+        params: Promise.resolve({ locale: "en" }),
+        getMdxSlugs: async () => ["golf-tournament", "annual-summit"],
+        getMdxSource,
+      }),
+    );
+    const hrefs = Array.from(container.querySelectorAll("a")).map((a) => a.getAttribute("href"));
+    expect(hrefs).toContain("/younglife/golf-tournament");
+    expect(hrefs).not.toContain("/events/golf-tournament");
+    expect(hrefs).toContain("/events/annual-summit");
+  });
+});

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

@@ -12,6 +12,7 @@ import type { Metadata } from "next";
 import type { ReactElement } from "react";
 
 import { type HubConfig, hubPageInput } from "../../../lib/hub-children";
+import { pagePathFor } from "../../../src/lib/routes";
 
 interface Props {
   params: Promise<{ locale: string }>;
@@ -27,6 +28,16 @@ const HUB: HubConfig = {
   linkLabel: "View the event",
   sectionId: "event-cards",
   body: "mdx-body",
+  // #10552 D5 — an Event under a program links its program URL; the rest is
+  // the default card, byte for byte.
+  card: ({ slug, frontmatter }) => {
+    const fm = frontmatter as { title?: string; description?: string; parent?: string };
+    return {
+      title: fm.title ?? slug,
+      description: fm.description ?? "",
+      link: { label: HUB.linkLabel, href: pagePathFor({ type: "Event", slug, parent: fm.parent }) },
+    };
+  },
 };
 
 export async function generateMetadata({