create-ailk 0.1.0 → 0.2.0

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

@@ -49,7 +49,7 @@ describe("courses/page — snapshot regression", () => {
     });
     const { container } = render(element);
     expect(container.innerHTML).toMatchInlineSnapshot(
-      `"<main><h1>Courses</h1><p data-testid="section-empty-state">Courses listing coming soon.</p></main>"`,
+      `"<main><h1 class="text-heading-1 font-display font-normal tracking-tighter text-fg hero-type-display">Courses</h1><p data-testid="section-empty-state">Courses listing coming soon.</p></main>"`,
     );
   });
 
@@ -70,7 +70,7 @@ describe("courses/page — snapshot regression", () => {
     });
     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":"Courses","description":"Structured learning paths for teams adopting AILK.","mainEntity":{"@type":"ItemList","itemListElement":[{"@type":"Course"}]}}</script><main><h1>Courses</h1><p data-testid="courses-description">Structured learning paths for teams adopting AILK.</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) 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) 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-rendered">## Courses
+     "<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@type":"CollectionPage","inLanguage":"en","name":"Courses","description":"Structured learning paths for teams adopting AILK.","mainEntity":{"@type":"ItemList","itemListElement":[{"@type":"Course"}]}}</script><main><h1>Courses</h1><p data-testid="courses-description">Structured learning paths for teams adopting AILK.</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-rendered">## Courses
 
      Body content.</div></article></div></div></main>"
     `);
@@ -99,7 +99,7 @@ describe("courses/[slug] — snapshot regression", () => {
     });
     const { container } = render(element);
     expect(container.innerHTML).toMatchInlineSnapshot(`
-     "<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@graph":[{"@context":"https://schema.org","@type":"WebPage","inLanguage":"en","name":"AEO Fundamentals","description":"A practical course covering Layer 1 AEO rules.","mainEntity":{"@context":"https://schema.org","@type":"Course","name":"AEO Fundamentals","description":"A practical course covering Layer 1 AEO rules."}},{"@context":"https://schema.org","@type":"BreadcrumbList","inLanguage":"en","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"http://localhost:3000/en/"},{"@type":"ListItem","position":2,"name":"Courses","item":"http://localhost:3000/en/courses"},{"@type":"ListItem","position":3,"name":"AEO Fundamentals","item":"http://localhost:3000/en/courses/aeo-fundamentals"}]}]}</script><main><h1>AEO Fundamentals</h1><p data-testid="course-description">A practical course covering Layer 1 AEO rules.</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) 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) 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-rendered">## AEO Fundamentals
+     "<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@graph":[{"@context":"https://schema.org","@type":"WebPage","inLanguage":"en","name":"AEO Fundamentals","description":"A practical course covering Layer 1 AEO rules.","mainEntity":{"@context":"https://schema.org","@type":"Course","name":"AEO Fundamentals","description":"A practical course covering Layer 1 AEO rules."}},{"@context":"https://schema.org","@type":"BreadcrumbList","inLanguage":"en","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"http://localhost:3000/en/"},{"@type":"ListItem","position":2,"name":"Courses","item":"http://localhost:3000/en/courses"},{"@type":"ListItem","position":3,"name":"AEO Fundamentals","item":"http://localhost:3000/en/courses/aeo-fundamentals"}]}]}</script><main><h1>AEO Fundamentals</h1><p data-testid="course-description">A practical course covering Layer 1 AEO rules.</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-rendered">## AEO Fundamentals
 
      Body content.</div></article></div></div></main>"
     `);

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

@@ -1,7 +1,8 @@
 // Courses list page. Reads CoursesList MDX via the content adapter and emits
 // a JSON-LD CollectionPage via the dispatcher.
 import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
-import { renderPage } from "@working-theory/page-renderer";
+import { renderPage, renderPageMetadata } from "@working-theory/page-renderer";
+import type { Metadata } from "next";
 import type { ReactElement } from "react";
 
 interface Props {
@@ -9,6 +10,13 @@ interface Props {
   getMdxSource?: typeof defaultGetMdxSource;
 }
 
+export async function generateMetadata({
+  params,
+}: Pick<Props, "params">): Promise<Metadata> {
+  const { locale } = await params;
+  return renderPageMetadata({ type: "CoursesList", slug: "courses", locale });
+}
+
 export default async function Page({
   params,
   getMdxSource,

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

@@ -1,3 +1,4 @@
+// oss: false
 /**
  * /docs catch-all route. Renders placeholder docs from
  * `apps/web/content/en/docs/` via the Fumadocs docsSource loader.

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

@@ -22,6 +22,16 @@ jest.mock("next-mdx-remote/rsc", () => ({
 
 // ── @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",
@@ -64,7 +74,7 @@ describe("DownloadsPage — snapshot regression", () => {
     });
     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":"Downloads","description":"Downloadable assets and templates.","mainEntity":{"@type":"ItemList","itemListElement":[{"@type":"DigitalDocument"}]}}</script><main><h1>Downloads</h1><p data-testid="downloads-description">Downloadable assets and templates.</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) 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) 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-rendered"># Downloads
+     "<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@type":"CollectionPage","inLanguage":"en","name":"Downloads","description":"Downloadable assets and templates.","mainEntity":{"@type":"ItemList","itemListElement":[{"@type":"DigitalDocument"}]}}</script><main><h1>Downloads</h1><p data-testid="downloads-description">Downloadable assets and templates.</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-rendered"># Downloads
 
      Body.</div></article></div></div></main>"
     `);

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

@@ -1,7 +1,8 @@
 // Downloads list page. Reads DownloadsList MDX via renderPage and emits
 // a JSON-LD CollectionPage via the dispatcher. List-only — no detail route.
 import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
-import { renderPage } from "@working-theory/page-renderer";
+import { renderPage, renderPageMetadata } from "@working-theory/page-renderer";
+import type { Metadata } from "next";
 import type { ReactElement } from "react";
 
 interface Props {
@@ -9,6 +10,17 @@ interface Props {
   getMdxSource?: typeof defaultGetMdxSource;
 }
 
+export async function generateMetadata({
+  params,
+}: Pick<Props, "params">): Promise<Metadata> {
+  const { locale } = await params;
+  return renderPageMetadata({
+    type: "DownloadsList",
+    slug: "downloads",
+    locale,
+  });
+}
+
 export default async function Page({
   params,
   getMdxSource,

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

@@ -2,9 +2,11 @@
 // renderPage, and emits a JSON-LD <script>. Unknown slugs trigger 404.
 import {
   renderPage,
+  renderPageMetadata,
   getMdxSource as defaultGetMdxSource,
   getMdxSlugs,
 } from "@working-theory/page-renderer";
+import type { Metadata } from "next";
 import { notFound } from "next/navigation";
 import type { ReactElement } from "react";
 
@@ -13,6 +15,13 @@ interface Props {
   getMdxSource?: typeof defaultGetMdxSource;
 }
 
+export async function generateMetadata({
+  params,
+}: Pick<Props, "params">): Promise<Metadata> {
+  const { locale, slug } = await params;
+  return renderPageMetadata({ type: "Event", slug, locale });
+}
+
 export async function generateStaticParams({
   params,
 }: {

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

@@ -31,6 +31,16 @@ jest.mock("next/navigation", () => ({
 
 // ── @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",
@@ -77,7 +87,7 @@ describe("EventsPage — snapshot regression", () => {
     });
     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":"Events","description":"Upcoming and past events.","mainEntity":{"@type":"ItemList","itemListElement":[{"@type":"Event"}]}}</script><main><h1>Events</h1><p data-testid="events-description">Upcoming and past events.</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) 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) 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-rendered"># Events
+     "<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@type":"CollectionPage","inLanguage":"en","name":"Events","description":"Upcoming and past events.","mainEntity":{"@type":"ItemList","itemListElement":[{"@type":"Event"}]}}</script><main><h1>Events</h1><p data-testid="events-description">Upcoming and past events.</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-rendered"># Events
 
      Body.</div></article></div></div></main>"
     `);
@@ -112,7 +122,7 @@ describe("EventSlugPage — snapshot regression", () => {
     // This replaces the pre-migration hardcoded "event-description" testid
     // with the slug-derived "annual-summit-description". Intentional per spec.
     expect(container.innerHTML).toMatchInlineSnapshot(`
-     "<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@graph":[{"@context":"https://schema.org","@type":"WebPage","inLanguage":"en","name":"Annual Summit","description":"Our annual developer summit.","mainEntity":{"@context":"https://schema.org","@type":"Event","name":"Annual Summit","description":"Our annual developer summit."}},{"@context":"https://schema.org","@type":"BreadcrumbList","inLanguage":"en","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"http://localhost:3000/en/"},{"@type":"ListItem","position":2,"name":"Events","item":"http://localhost:3000/en/events"},{"@type":"ListItem","position":3,"name":"Annual Summit","item":"http://localhost:3000/en/events/annual-summit"}]}]}</script><main><h1>Annual Summit</h1><p data-testid="annual-summit-description">Our annual developer summit.</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) 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) 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-rendered"># Annual Summit
+     "<script type="application/ld+json" data-testid="json-ld">{"@context":"https://schema.org","@graph":[{"@context":"https://schema.org","@type":"WebPage","inLanguage":"en","name":"Annual Summit","description":"Our annual developer summit.","mainEntity":{"@context":"https://schema.org","@type":"Event","name":"Annual Summit","description":"Our annual developer summit."}},{"@context":"https://schema.org","@type":"BreadcrumbList","inLanguage":"en","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"http://localhost:3000/en/"},{"@type":"ListItem","position":2,"name":"Events","item":"http://localhost:3000/en/events"},{"@type":"ListItem","position":3,"name":"Annual Summit","item":"http://localhost:3000/en/events/annual-summit"}]}]}</script><main><h1>Annual Summit</h1><p data-testid="annual-summit-description">Our annual developer summit.</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-rendered"># Annual Summit
 
      Body.</div></article></div></div></main>"
     `);

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

@@ -1,7 +1,8 @@
 // Events list page. Reads EventsList MDX via renderPage and emits
 // a JSON-LD CollectionPage via the dispatcher.
 import type { getMdxSource as defaultGetMdxSource } from "@working-theory/page-renderer";
-import { renderPage } from "@working-theory/page-renderer";
+import { renderPage, renderPageMetadata } from "@working-theory/page-renderer";
+import type { Metadata } from "next";
 import type { ReactElement } from "react";
 
 interface Props {
@@ -9,6 +10,13 @@ interface Props {
   getMdxSource?: typeof defaultGetMdxSource;
 }
 
+export async function generateMetadata({
+  params,
+}: Pick<Props, "params">): Promise<Metadata> {
+  const { locale } = await params;
+  return renderPageMetadata({ type: "EventsList", slug: "events", locale });
+}
+
 export default async function Page({
   params,
   getMdxSource,

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

@@ -5,8 +5,10 @@ import type {
   getMdxSource as defaultGetMdxSource,
   getPageSections as defaultGetPageSections} from "@working-theory/page-renderer";
 import {
-  renderPage
+  renderPage,
+  renderPageMetadata
 } from "@working-theory/page-renderer";
+import type { Metadata } from "next";
 import type { ReactElement } from "react";
 
 interface Props {
@@ -15,6 +17,13 @@ interface Props {
   getPageSections?: typeof defaultGetPageSections;
 }
 
+export async function generateMetadata({
+  params,
+}: Pick<Props, "params">): Promise<Metadata> {
+  const { locale } = await params;
+  return renderPageMetadata({ type: "FAQPage", slug: "faq", locale });
+}
+
 export default async function Page({
   params,
   getMdxSource,

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

@@ -0,0 +1,265 @@
+"use client";
+
+/**
+ * FlowStepperClient — the thin client wrapper that owns the web-layer
+ * wiring for FlowStepper (#3957 D8): builds `messages` from the `flow`
+ * next-intl namespace and binds `onSubmitStep` directly to the
+ * `submitFlowStepAction` Server Action (React 19 supports calling Server
+ * Actions directly — no `useFormState`; the stepper needs the response
+ * payload on every per-step call).
+ *
+ * Segment-keyed completion redirect (#3960 D5): when the served config
+ * carries a `thankYou` block, the client supplies `onCompleted` — resolve
+ * the slug (D4's pure `resolveThankYouSlug`), then navigate to the
+ * locale-prefixed `/thanks/<slug>` route. The redirect's ONLY inputs are the
+ * active route `locale` and the config-declared, kebab-case slug the
+ * resolver returns — no submitted form value (email/name/phone/free text)
+ * ever reaches the URL (AC2). With no `thankYou` block, `onCompleted` is
+ * never passed — `FlowStepper`'s own in-component completion state renders,
+ * byte-identical to #3957 (AC4).
+ *
+ * Permalink completion redirect (#4770 D1/D7/D12): on a `mode:"recommending"`
+ * flow, completion instead navigates to that flow's results permalink —
+ * `/flows/<slug>/results/<payload>`, where `<payload>` encodes the answers
+ * the visitor SUBMITTED (never an unsubmitted, part-filled edit) to the
+ * flow's `segmentation`-typed questions ONLY (never a `field`-step value,
+ * mapped or unmapped — the PRD's "answers, never identity" constraint, D7).
+ * `FlowStepper.tsx` itself is not touched: this client accumulates its own
+ * copy of the answered state — `answersRef` below — from the RESOLVED
+ * result of the `onSubmitStep` calls it already forwards (D1), because
+ * `FlowStepper`'s own `onCompleted` payload carries no answers today
+ * (`{ segment?, aeoScore? }` only). `onCompleted` is passed whenever the
+ * config carries a `thankYou` block OR is a recommending flow (D12) — a
+ * recommending flow's terminal is the compiled `recommendation` marker, not
+ * a `thankYou` block, so without this widening the callback would never be
+ * supplied on a recommending flow at all.
+ *
+ * Locale validation before interpolation (AILK #4707, security review on
+ * samhenry PR #163): the `[locale]` route segment is a Next.js dynamic
+ * segment — the framework matches ANY string there, and next-intl's
+ * middleware only rewrites/redirects for locale *detection*, it does not
+ * reject an already-present, non-configured locale prefix from reaching
+ * this component. Interpolating that unvalidated value into the redirect
+ * path would let an unexpected/malformed segment ride into the pushed URL.
+ * `resolveSafeLocale` validates it against the same build-time-baked
+ * `NEXT_PUBLIC_ENABLED_LOCALES` list `middleware.ts` reads (mirrored here,
+ * not imported from `@working-theory/web-i18n`'s `readLocales()` — that
+ * helper falls back to a `node:fs` read that has no place in a client
+ * bundle, the same reasoning `middleware.ts` already documents for the
+ * Edge runtime) before it ever reaches the template literal.
+ */
+import {
+  FlowStepper,
+  type FlowStepperMessages,
+  type FlowStepSubmitPayload,
+  type FlowStepSubmitResult,
+} from "@working-theory/ui";
+import type { AeoScoreResult, FlowConfig, FlowState } from "@working-theory/validation";
+import {
+  deriveFlags,
+  encodePermalink,
+  flattenState,
+  hiddenAnswers,
+  PERMALINK_VERSION,
+  pruneHiddenState,
+  resolveThankYouSlug,
+} from "@working-theory/validation";
+import { useRouter } from "next/navigation";
+import { useMessages, useTranslations } from "next-intl";
+import type { ReactElement } from "react";
+import { useRef } from "react";
+
+import { submitFlowStepAction } from "./flow.actions";
+
+interface Props {
+  config: FlowConfig;
+  locale: string;
+  slug: string;
+}
+
+const DEFAULT_LOCALE = "en";
+const ENABLED_LOCALES = (
+  process.env.NEXT_PUBLIC_ENABLED_LOCALES ?? DEFAULT_LOCALE
+).split(",");
+
+/** Validate a candidate locale against the configured set; unknown → default. */
+function resolveSafeLocale(candidate: string): string {
+  return ENABLED_LOCALES.includes(candidate) ? candidate : DEFAULT_LOCALE;
+}
+
+/**
+ * D7 (#4770) — every question `name` contributed by a `segmentation`-typed
+ * step. This is the allowlist the encoded permalink is filtered to: a
+ * `field`-typed step's values — mapped or unmapped, including the invisible
+ * `aeo_score` step's own submission (D1) — never reach it.
+ */
+function segmentationQuestionNames(config: FlowConfig): Set<string> {
+  const names = new Set<string>();
+  for (const step of config.steps) {
+    if (step.type === "segmentation") {
+      for (const question of step.questions) {
+        names.add(question.name);
+      }
+    }
+  }
+  return names;
+}
+
+export function FlowStepperClient({
+  config,
+  locale,
+  slug,
+}: Props): ReactElement {
+  const t = useTranslations("flow");
+  const router = useRouter();
+  const { thankYou } = config;
+  // #4770 D8/D12 — the SAME predicate the results route's own server-side
+  // guard uses (D8), so a flow the route would bounce is also a flow the
+  // client never routes to.
+  const isRecommending =
+    config.mode === "recommending" && config.offers !== undefined;
+
+  // #4770 D1 — the client's own accumulated answers, written from the
+  // RESOLVED result of onSubmitStep (never the inbound payload) so a
+  // rejected submission is never recorded and a `step_conflict` clears it,
+  // mirroring exactly what FlowStepper does with its own `answers` state on
+  // the same two paths.
+  const answersRef = useRef<FlowState>({});
+  // #4842 FR6/D4 — the last successful step response's own session id, so a
+  // recommending completion can hand the walk's session to the results page
+  // via `sessionStorage` (never the URL — the permalink stays answers-only).
+  const lastSessionIdRef = useRef<string | undefined>(undefined);
+
+  async function handleSubmitStep(
+    payload: FlowStepSubmitPayload,
+  ): Promise<FlowStepSubmitResult> {
+    const result = await submitFlowStepAction(slug, payload);
+    if (result.ok) {
+      answersRef.current = {
+        ...answersRef.current,
+        [payload.stepKey]: payload.values,
+      };
+      lastSessionIdRef.current = result.response.sessionId;
+    } else if (result.kind === "step_conflict") {
+      answersRef.current = {};
+    }
+    return result;
+  }
+
+  // #4663 D11 — `aeoScore` passes through untouched: this repo's segment
+  // redirect is unchanged; C2's results page (on samhenry) is the consumer
+  // of the score.
+  function handleCompleted(result: {
+    segment?: string;
+    aeoScore?: AeoScoreResult;
+  }): void {
+    if (isRecommending) {
+      // D1 (hidden-step pruning) — apply the shipped visibility resolver to
+      // the accumulated state before encoding, so an abandoned branch's
+      // answers never reach the URL.
+      const flags = deriveFlags(config, answersRef.current);
+      const pruned = pruneHiddenState(config, answersRef.current, flags);
+      const flat = flattenState(pruned);
+
+      // Code-review finding (#4770): mirror the server's OWN completion-
+      // payload assembly (flow-engine.ts's completeSubmission), which merges
+      // `hiddenAnswers()` — the `whenHidden` auto-answers of every currently-
+      // hidden segmentation step — in AFTER the visible-step values. Without
+      // this, a config using `whenHidden` could silently score a different
+      // recommendation on this cold-load permalink than the walk that
+      // produced it. `hiddenAnswers` reads the UNPRUNED state (it derives its
+      // own hidden/visible split internally) and only ever contributes
+      // segmentation-question keys, so it composes safely with the D7 filter
+      // below.
+      Object.assign(flat, hiddenAnswers(config, answersRef.current, flags));
+
+      // D7 — segmentation-only filter.
+      const segmentationNames = segmentationQuestionNames(config);
+      const answers: Record<string, string | string[]> = {};
+      for (const [name, value] of Object.entries(flat)) {
+        if (!segmentationNames.has(name)) continue;
+        if (typeof value === "string" || Array.isArray(value)) {
+          answers[name] = value as string | string[];
+        }
+      }
+
+      const payload = encodePermalink({
+        version: PERMALINK_VERSION,
+        flowSlug: slug,
+        answers,
+      });
+      // #4842 FR6/D4 — hand the walk's session id to the results page through
+      // the per-tab `sessionStorage` (the key `ResultsClient` reads), never
+      // through the permalink. Only on a recommending completion; a privacy
+      // mode that throws degrades to a cold results page.
+      const sessionId = lastSessionIdRef.current;
+      if (typeof window !== "undefined" && sessionId) {
+        try {
+          window.sessionStorage.setItem(`ailk:flow-session:${slug}`, sessionId);
+        } catch {
+          // cold results page
+        }
+      }
+      router.push(
+        `/${resolveSafeLocale(locale)}/flows/${slug}/results/${payload}`,
+      );
+      return;
+    }
+
+    if (!thankYou) return;
+    const thankYouSlug = resolveThankYouSlug(thankYou, result.segment);
+    router.push(`/${resolveSafeLocale(locale)}/thanks/${thankYouSlug}`);
+  }
+
+  // The typed-messages augmentation (types/messages.d.ts) restricts t.raw()
+  // to leaf string keys, so the deliberately open-ended `flow.questions`
+  // sub-object (D2/D4 — app-supplied, keyed by question `name`) is read via
+  // useMessages() instead — untyped (AbstractIntlMessages), asserted to the
+  // shape this namespace actually carries.
+  const allMessages = useMessages() as unknown as {
+    flow?: { questions?: Record<string, string> };
+  };
+  const questionPrompts = allMessages.flow?.questions ?? {};
+
+  const messages: FlowStepperMessages = {
+    progressLabel: (current, total) => t("progress", { current, total }),
+    validation: {
+      required: t("validationRequired"),
+      invalidEmail: t("validationInvalidEmail"),
+      selectOption: t("validationSelectOption"),
+      tooLong: t("validationTooLong"),
+      // #4663 D5/D4 — url/minLength/multi validation chrome.
+      invalidUrl: t("validationInvalidUrl"),
+      tooShort: t("validationTooShort"),
+      selectAtLeastOne: t("validationSelectAtLeastOne"),
+    },
+    submitError: t("submitError"),
+    // #4730 — distinct retryable message on a 429; receives the API's own
+    // Retry-After-derived seconds.
+    rateLimited: (seconds) => t("rateLimited", { seconds }),
+    // #4708 — default submit-button label when a step's copy.cta is absent.
+    next: t("next"),
+    completedTitle: t("completedTitle"),
+    completedBody: t("completedBody"),
+    questionPrompts,
+    // #4663 D8 — opt-in back-nav chrome string.
+    goBack: t("goBack"),
+    // #4663 D7 — shown while the invisible aeo_score step's submission is pending.
+    computing: t("computing"),
+    // #4802 D5 — the "Select all that apply" subline under a multi-select
+    // question's prompt; a required FlowStepperMessages field as of #4802.
+    selectAllThatApply: t("selectAllThatApply"),
+  };
+
+  return (
+    <FlowStepper
+      config={config}
+      locale={locale}
+      messages={messages}
+      onSubmitStep={handleSubmitStep}
+      {...(thankYou !== undefined || isRecommending
+        ? { onCompleted: handleCompleted }
+        : {})}
+    />
+  );
+}