create-ailk 0.6.1 → 0.7.0

package/templates/apps/web/app/not-found.tsx

@@ -1,48 +1,24 @@
 /* eslint-disable no-restricted-syntax -- i18n-allow: not-found boundary renders outside the [locale] intl provider; translations unavailable at this segment (ADR 0019) */
 // Next.js App Router not-found boundary. Renders for any route that calls
 // notFound() or when no route matches. Server Component by default.
-import { tokens } from "@working-theory/theme";
-import type { ReactElement } from "react";
+//
+// This boundary renders under the pass-through root layout, outside
+// app/[locale]/layout.tsx — the only other importer of globals.css — so it
+// imports the stylesheet itself; without it the primitives' token classes
+// would render unstyled here (#6514).
+import "./globals.css";
 
-const styles = {
-  main: {
-    background: tokens.colors.light.bg,
-    color: tokens.colors.light.fg,
-    minHeight: "100vh",
-    display: "flex",
-    flexDirection: "column" as const,
-    alignItems: "center",
-    justifyContent: "center",
-    padding: tokens.radius.lg,
-    gap: tokens.radius.md,
-  },
-  heading: {
-    fontSize: "1.5rem",
-    lineHeight: tokens.lineHeight.md,
-    margin: 0,
-  },
-  body: {
-    fontSize: "1rem",
-    lineHeight: tokens.lineHeight.md,
-    margin: 0,
-  },
-  link: {
-    color: tokens.colors.light.brand,
-    fontSize: "1rem",
-    lineHeight: tokens.lineHeight.md,
-  },
-} as const;
+import { Heading, Link, Text } from "@working-theory/ui/primitives";
+import type { ReactElement } from "react";
 
 export default function NotFound(): ReactElement {
   return (
-    <main style={styles.main}>
-      <h1 style={styles.heading}>We couldn&apos;t find that page</h1>
-      <p style={styles.body}>
-        The page you are looking for does not exist or may have moved.
-      </p>
-      <a href="/" style={styles.link}>
-        Return home
-      </a>
+    <main className="flex min-h-screen flex-col items-center justify-center gap-4 bg-(--color-bg) p-card text-(--color-fg)">
+      <Heading level={1} visual={3}>
+        We couldn&apos;t find that page
+      </Heading>
+      <Text>The page you are looking for does not exist or may have moved.</Text>
+      <Link href="/">Return home</Link>
     </main>
   );
 }

package/templates/apps/web/app/og/route.tsx

@@ -15,6 +15,12 @@
  *  - Strip control characters \x00–\x1F and \x7F from title and schemaType
  *  - Cap title at 200 chars, schemaType at 50 chars
  *  - If sanitization yields an empty title, fall back to static PNG redirect
+ *
+ * Composition exception (#6514): this route renders raw elements with inline
+ * `style` objects, and is deliberately left out of the page-surface
+ * `no-raw-html-elements` scope in eslint.config.ts. Satori (next/og) rasterises
+ * a JSX tree to PNG — it reads only inline styles, supports no stylesheet or
+ * Tailwind classes, and cannot render @working-theory/ui components.
  */
 import { clientError } from "@working-theory/page-renderer/edge";
 import { tokens } from "@working-theory/theme";

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

@@ -28,6 +28,9 @@ export default tseslint.config(
       "**/dist/**",
       "**/generated/**",
       "**/node_modules/**",
+      // fumadocs-mdx's generated collection code (#6680) — present only with
+      // the docs-blog module, and never hand-edited.
+      "**/.source/**",
     ],
   },
   js.configs.recommended,

package/templates/apps/web/instrumentation.ts

@@ -0,0 +1,14 @@
+/**
+ * Next.js instrumentation hook — runs once per server instance at boot.
+ *
+ * Registers the durable home of a renewed licence key (#6677 DD-6) before any
+ * request resolves the licence. Node runtime only: the store reaches the
+ * database through Prisma, which the Edge runtime cannot load.
+ */
+
+export async function register(): Promise<void> {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const { registerLicenseKeyStore } = await import("./lib/license-key-store");
+    await registerLicenseKeyStore();
+  }
+}

package/templates/apps/web/lib/__tests__/structured-data.test.tsx

@@ -56,6 +56,10 @@ import {
 import type { ReactElement } from "react";
 import { parse as parseYaml } from "yaml";
 
+// Registers the site's `_site.mdx` identity at module load, as the `[locale]`
+// layout does in production (#6597).
+import { readSiteIdentity } from "../site-identity";
+
 // Detail routes call notFound() on a missing page; a thrown error is how the
 // test sees it (the same shape the per-surface suites use).
 jest.mock("next/navigation", () => ({
@@ -187,6 +191,38 @@ function extractJsonLdBlocks(container: HTMLElement): JsonLdObject[] {
   return blocks;
 }
 
+const SITE_IDENTITY = readSiteIdentity(CONTENT_ROOT);
+const SITE_ORIGIN = (
+  process.env.NEXT_PUBLIC_SITE_URL ??
+  process.env.MARKETING_WEB_BASE_URL ??
+  "http://localhost:3000"
+).replace(/\/+$/, "");
+
+/**
+ * The sitewide identity trio every rendered page carries when the site's own
+ * `_site.mdx` reads (#6597): exactly one identity node at its `@id`, exactly
+ * one `WebSite` published by it, and the page's primary linked `isPartOf`.
+ * `null` when the page carries all three.
+ */
+function identityFailure(blocks: JsonLdObject[], label: string): string | null {
+  if (SITE_IDENTITY === undefined) return null;
+  const identityId = `${SITE_ORIGIN}/#${SITE_IDENTITY.identity.kind === "Person" ? "person" : "organization"}`;
+  const webSiteId = `${SITE_ORIGIN}/#website`;
+  const identity = blocks.filter((b) => b["@id"] === identityId);
+  const webSite = blocks.filter((b) => b["@id"] === webSiteId);
+  const problems: string[] = [];
+  if (identity.length !== 1 || identity[0]?.["@type"] !== SITE_IDENTITY.identity.kind)
+    problems.push(`expected one ${SITE_IDENTITY.identity.kind} at ${identityId}, got ${identity.length}`);
+  if (webSite.length !== 1 || webSite[0]?.["@type"] !== "WebSite")
+    problems.push(`expected one WebSite at ${webSiteId}, got ${webSite.length}`);
+  else if ((webSite[0]["publisher"] as { "@id"?: unknown } | undefined)?.["@id"] !== identityId)
+    problems.push(`WebSite publisher is not {"@id": "${identityId}"}`);
+  // A page's own `isPartOf` wins over the sitewide link (composeGraph), so the
+  // check is that the primary is linked, not what to.
+  if (blocks[0]?.["isPartOf"] === undefined) problems.push("the primary carries no isPartOf");
+  return problems.length === 0 ? null : `${label}: sitewide identity — ${problems.join("; ")}`;
+}
+
 // ── 1. Content-driven: every content page builds valid JSON-LD ──────────────
 
 describe("structured data — every content page builds valid JSON-LD", () => {
@@ -510,6 +546,8 @@ describe("structured data — every route emits a valid JSON-LD script", () => {
       }
       const failure = validateFor(blocks, type, pageLabel);
       if (failure !== null) failures.push(failure);
+      const missingIdentity = identityFailure(blocks, pageLabel);
+      if (missingIdentity !== null) failures.push(missingIdentity);
     }
     expect(failures).toEqual([]);
   });

package/templates/apps/web/lib/license-key-store.ts

@@ -0,0 +1,52 @@
+/**
+ * Registers the durable home of a renewed licence key (#6677 DD-6).
+ *
+ * `@working-theory/license` renews the deployment's key before it lapses and
+ * keeps the renewed key in a `LicenseKeyStore`. Its default store is a file,
+ * which a redeploy wipes — and this app's one real `checkLicense()` caller
+ * (`src/lib/commerce-claim.ts`, gating /purchase/* and /.well-known/mcp.json)
+ * would then run on the older `AILK_LICENSE_KEY` alone. With a database
+ * configured, this registers the store backed by ONE deployment-wide
+ * `SiteSetting` row, `(DEFAULT_WORKSPACE_ID, "license.renewed_key")`, shared
+ * with apps/api and apps/mcp.
+ *
+ * NARROW, NAMED EXCEPTION to "apps/web never touches the database directly"
+ * (spec 6677 DD-6 and § 7; architecture.yaml `web.description`; the
+ * `prisma-for-auth.ts` header): this file, and only this file, hands
+ * `prismaForAuth.siteSetting` to `createSiteSettingLicenseKeyStore`, which
+ * reads and writes the one `license.renewed_key` row and nothing else. The
+ * alternative — an apps/api route serving the key over HTTP — is a hard floor
+ * and a wider exposure of a bearer credential.
+ *
+ * Imported from `instrumentation.ts` `register()` on the Node runtime only.
+ * Both imports are dynamic and reached only when `DATABASE_URL` is set.
+ */
+
+/**
+ * Register the SiteSetting-backed store when `DATABASE_URL` is set. An
+ * explicitly set `AILK_LICENSE_STORAGE_PATH` is the operator choosing the
+ * file store, and is honoured. Never throws: a failure logs and leaves the
+ * file store in place.
+ */
+export async function registerLicenseKeyStore(): Promise<void> {
+  if (!process.env.DATABASE_URL || process.env.AILK_LICENSE_STORAGE_PATH) return;
+  try {
+    const [{ prismaForAuth: prisma }, { DEFAULT_WORKSPACE_ID }, license] =
+      await Promise.all([
+        import("./prisma-for-auth"),
+        import("@working-theory/database/tenancy"),
+        import("@working-theory/license"),
+      ]);
+    license.setLicenseKeyStore(
+      license.createSiteSettingLicenseKeyStore(
+        prisma.siteSetting,
+        DEFAULT_WORKSPACE_ID,
+      ),
+    );
+  } catch (err) {
+    console.error(
+      "[web] could not register the SiteSetting licence-key store — the file store stays in place:",
+      err instanceof Error ? err.name : "non-Error thrown",
+    );
+  }
+}

package/templates/apps/web/lib/nav-config.ts

@@ -1,33 +1,85 @@
-// nav-config.ts — Nav item registry for apps/web (#1451, re-shaped by #5469).
+// nav-config.ts — Nav item registry for apps/web (#1451, re-shaped by #5469,
+// #6508).
 //
-// The Free marketing-site template's nav (the approved chrome, #5469 D5):
-// a Product flyout (How it works · Features · FAQ), then How it works,
-// Pricing and About as top-level items. Paths are locale-agnostic; Nav
-// prefixes them with the active locale at render.
+// The Free marketing-site template's nav (the approved chrome, #5469 D5,
+// #6508 D5): a Product flyout (How it works · Features · FAQ) rendered as a
+// fixed-640px two-column panel (the Standard Issue direction — #6508), then
+// How it works, Pricing and About as top-level items. Paths are
+// locale-agnostic; Nav prefixes them with the active locale at render.
+// `footerColumns` carries the footer's column groups (#6468), keys only — the
+// layout resolves the labels.
 //
 // In a SCAFFOLD this file is regenerated by create-ailk from the declared
 // route surfaces (`renderNavConfig` in packages/create-ailk/src/surfaces.ts)
 // so the nav never links a page the scaffold does not carry — keep the two in
 // step when the base item set changes.
+//
+// SOFT_LOCK_OK: #6508 — Product's flyout is `width: "panel"` (D4/D5): a fixed
+// 640px, two-column grid, replacing the prior "list"/"trigger" one-column
+// menu. `presentation` is omitted — it defaults to "grid" (D5). The `docs`
+// action is dropped (it duplicated the first feature's /how-it-works
+// destination, § 1.4). This note lives here, not inside the `navItems` array
+// below, so this file's `navItems`/`footerColumns` blocks stay byte-identical
+// to `renderNavConfig`'s generated output — the mirror test (#6468) diffs the
+// arrays verbatim.
 
 import type { NavItem } from "@working-theory/ui";
-import { BookOpen, HelpCircle, Layers, Sparkles } from "lucide-react";
+import { HelpCircle, Layers, Sparkles } from "lucide-react";
 
 export const navItems: NavItem[] = [
   {
     labelKey: "product",
     flyout: {
-      presentation: "list",
-      width: "trigger",
+      width: "panel",
       features: [
-        { labelKey: "howItWorks", descKey: "howItWorksDesc", icon: Layers, path: "/how-it-works" },
-        { labelKey: "features", descKey: "featuresDesc", icon: Sparkles, path: "/features" },
+        { labelKey: "useCases", descKey: "useCasesDesc", icon: Layers, path: "/use-cases" },
+        { labelKey: "features", descKey: "featuresDesc", icon: Sparkles, path: "/software/product" },
         { labelKey: "faq", descKey: "faqDesc", icon: HelpCircle, path: "/faq" },
       ],
-      actions: [{ labelKey: "docs", icon: BookOpen, path: "/how-it-works" }],
+      actions: [],
     },
   },
-  { labelKey: "howItWorks", path: "/how-it-works" },
+  { labelKey: "useCases", path: "/use-cases" },
+  { labelKey: "blog", path: "/blog" },
   { labelKey: "pricing", path: "/pricing" },
   { labelKey: "about", path: "/about" },
 ];
+
+export interface FooterColumnConfig {
+  headingKey: string;
+  items: { labelKey: string; path: string }[];
+}
+
+export const footerColumns: FooterColumnConfig[] = [
+  {
+    headingKey: "footerSitePagesHeading",
+    items: [
+      { labelKey: "features", path: "/software/product" },
+      { labelKey: "pricing", path: "/pricing" },
+      { labelKey: "useCases", path: "/use-cases" },
+      { labelKey: "about", path: "/about" },
+      { labelKey: "contact", path: "/contact" },
+      { labelKey: "bookACall", path: "/book-a-call" },
+    ],
+  },
+  {
+    headingKey: "footerFeaturesHeading",
+    items: [
+      { labelKey: "feature1", path: "/software/product" },
+      { labelKey: "feature2", path: "/software/product" },
+      { labelKey: "feature3", path: "/software/product" },
+      { labelKey: "feature4", path: "/software/product" },
+      { labelKey: "feature5", path: "/software/product" },
+      { labelKey: "allFeatures", path: "/software/product" },
+    ],
+  },
+  {
+    headingKey: "footerResourcesHeading",
+    items: [
+      { labelKey: "blog", path: "/blog" },
+      { labelKey: "glossary", path: "/glossary" },
+      { labelKey: "newsletter", path: "/newsletter" },
+      { labelKey: "faq", path: "/faq" },
+    ],
+  },
+];

package/templates/apps/web/lib/prisma-for-auth.ts

@@ -5,16 +5,19 @@
  * Better Auth migration (#587). Driver adapter wrapping landed in Phase B
  * of the Prisma 7 migration (#661) ahead of the v7 bump in Phase C.
  *
- * Only `apps/web/auth.ts` should import this — business-logic callers go
- * through apps/api, never the database directly (architecture.yaml
- * `apps/web` may_not_import_from `database`; the single-file singleton
- * here is the documented exception, matching the pre-migration carve-out
- * for NextAuth's adapter).
+ * Two files import this: `apps/web/auth.ts`, for Better Auth, and
+ * `lib/license-key-store.ts`, which hands `prismaForAuth.siteSetting` to the
+ * licence client's SiteSetting store for the ONE deployment-wide
+ * `license.renewed_key` row (#6677 DD-6 — a narrow, named exception).
+ * Every other business-logic caller goes through apps/api, never the
+ * database directly (architecture.yaml `apps/web` may_not_import_from
+ * `database`; the single-file singleton here is the documented exception,
+ * matching the pre-migration carve-out for NextAuth's adapter).
  */
 
  
-import { PrismaClient } from "@working-theory/database";
 import { PrismaPg } from "@prisma/adapter-pg";
+import { PrismaClient } from "@working-theory/database";
 
 declare global {
   var __ailk_prisma: PrismaClient | undefined;

package/templates/apps/web/lib/site-brand.tsx

@@ -109,7 +109,7 @@ export const SITE_BASE_URL =
 
 /**
  * Shared brand mark — the square logomark (the central brand library's
- * `logomark/loop/icon.svg`). The Nav pairs it with `/wordmark.svg`.
+ * `logomark/loop/tile-black.svg`). The Nav pairs it with `/wordmark.svg`.
  * RSC-safe (no hooks, no client state).
  */
 export function siteLogo(): ReactElement {

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

@@ -2,8 +2,8 @@
 //
 // GENERATED by create-ailk from the declared template's `layout` block
 // (#5612). A scaffold with no template, or a template with no `layout`
-// block, gets these defaults — byte-identical to every scaffold before this
-// file existed. `apps/web/app/[locale]/layout.tsx` reads this to decide:
+// block, gets the defaults below (the announcement banner is off unless a
+// template turns it on, #6469). `apps/web/app/[locale]/layout.tsx` reads this to decide:
 //   - nav: "mark-only" → Nav renders the brand mark + right-hand controls
 //     only (no nav links).
 //   - footer: "centered" → Footer renders its existing centered variant.
@@ -24,6 +24,6 @@ export interface SiteChrome {
 export const siteChrome: SiteChrome = {
   nav: "full",
   footer: "columns",
-  announcementBanner: true,
+  announcementBanner: false,
   home: "default",
 };

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

@@ -0,0 +1,134 @@
+/**
+ * Site identity — reads `siteIdentity` out of `content/_site.mdx` and
+ * registers it with `@working-theory/page-renderer`, so every page's JSON-LD
+ * carries the site's entity graph: the identity node, its optional secondary
+ * (the product), and the `WebSite` (#6597).
+ *
+ * A mirror of `lib/site-theme.ts`: a local frontmatter parse (the
+ * `@working-theory/site-config/server` subpath is forbidden in `apps/web`,
+ * #1567), validated against the canonical `SiteIdentitySchema` from the
+ * package's client-safe `/schema` entry. `page-renderer` may not import
+ * site-config (`architecture.yaml`), so the identity is read here, once, and
+ * handed over through `setSiteIdentity`.
+ *
+ * Registration happens at module load. `app/[locale]/layout.tsx` imports this
+ * module, and Next.js evaluates a layout module before any page under it
+ * renders, so every `renderPage` / `pageToJsonLd` call sees the identity
+ * without a per-route prop.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  setSiteIdentity,
+  type SiteIdentityRegistration,
+} from "@working-theory/page-renderer";
+import { featureListFromSections } from "@working-theory/schema";
+import { SiteIdentitySchema } from "@working-theory/site-config/schema";
+import { parse as parseYaml } from "yaml";
+
+import { resolveContentRoot } from "./site-brand";
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/** The parsed frontmatter of one file, or `undefined` when it cannot be read. */
+function readFrontmatter(path: string): Record<string, unknown> | undefined {
+  try {
+    const match = FRONTMATTER_RE.exec(readFileSync(path, "utf8"));
+    if (!match) return undefined;
+    const parsed: unknown = parseYaml(match[1] ?? "");
+    return parsed && typeof parsed === "object"
+      ? (parsed as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The product's `featureList`: the feature titles of the product's own page —
+ * the first `SoftwareProduct` seed in the default locale, in sorted order
+ * (#6658 D3) — projected by `featureListFromSections`. A site with no product
+ * page falls back to a page whose slug is `features` (any type directory,
+ * first match in sorted order). Empty when there is neither.
+ */
+function readFeatureList(contentRoot: string, locale: string): string[] {
+  // A `feature` section in the `steps` variant is how the product is set up,
+  // not what it does (the product page carries both, #6658 D3), so its step
+  // titles never enter the featureList.
+  const featuresOf = (frontmatter: Record<string, unknown>): string[] =>
+    featureListFromSections(
+      (Array.isArray(frontmatter.sections)
+        ? (frontmatter.sections as Array<{ type: string; data?: unknown }>)
+        : []
+      ).filter(
+        (section) =>
+          !(
+            section.type === "feature" &&
+            (section.data as { variant?: unknown } | undefined)?.variant === "steps"
+          ),
+      ),
+    );
+  // #6658 D3: the product's own detail page (the first `SoftwareProduct`
+  // seed in sorted order) is where the feature sections live now.
+  const productDir = join(contentRoot, locale, "SoftwareProduct");
+  let productSeeds: string[] = [];
+  try {
+    productSeeds = readdirSync(productDir)
+      .filter((name) => name.endsWith(".mdx"))
+      .sort();
+  } catch {
+    // No SoftwareProduct directory — fall through to the legacy probe.
+  }
+  for (const name of productSeeds) {
+    const frontmatter = readFrontmatter(join(productDir, name));
+    if (frontmatter !== undefined) return featuresOf(frontmatter);
+  }
+  let typeDirs: string[];
+  try {
+    typeDirs = readdirSync(join(contentRoot, locale)).sort();
+  } catch {
+    return [];
+  }
+  for (const typeDir of typeDirs) {
+    const frontmatter = readFrontmatter(
+      join(contentRoot, locale, typeDir, "features.mdx"),
+    );
+    if (frontmatter !== undefined) return featuresOf(frontmatter);
+  }
+  return [];
+}
+
+/**
+ * The site's identity registration, or `undefined` when `_site.mdx` is absent,
+ * unreadable, or declares no `siteIdentity`. An invalid `siteIdentity` throws,
+ * deliberately: a customer whose identity silently vanished from every page
+ * would have been lied to (the stance `site-theme.ts` takes on colours).
+ */
+export function readSiteIdentity(
+  contentRoot: string = resolveContentRoot(),
+): SiteIdentityRegistration | undefined {
+  const frontmatter = readFrontmatter(join(contentRoot, "_site.mdx"));
+  if (frontmatter?.siteIdentity === undefined) return undefined;
+
+  const identity = SiteIdentitySchema.parse(frontmatter.siteIdentity);
+  const { siteName, baseUrl, defaultLocale } = frontmatter;
+  const registration: SiteIdentityRegistration = {
+    siteName: typeof siteName === "string" ? siteName : identity.name,
+    baseUrl: typeof baseUrl === "string" ? baseUrl : identity.url,
+    identity,
+  };
+  if (
+    identity.kind === "Organization" &&
+    identity.secondary?.kind === "SoftwareApplication"
+  ) {
+    registration.featureList = readFeatureList(
+      contentRoot,
+      typeof defaultLocale === "string" ? defaultLocale : "en",
+    );
+  }
+  return registration;
+}
+
+setSiteIdentity(readSiteIdentity());

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

@@ -25,6 +25,7 @@ import { join } from "node:path";
 
 import { SiteThemeSchema } from "@working-theory/site-config/schema";
 import {
+  siteThemeShapeCss,
   siteThemeToBrandTokens,
   type BrandTokenOverrides,
 } from "@working-theory/theme";
@@ -72,3 +73,13 @@ export function loadSiteBrandTokens(): BrandTokenOverrides | undefined {
   const theme = SiteThemeSchema.parse(block);
   return siteThemeToBrandTokens(theme, SOURCE);
 }
+
+/**
+ * The site's shape settings (`theme.corners`, `theme.eyebrowCase`) as a CSS
+ * override block for `:root`. "" when the site sets neither.
+ */
+export function loadSiteShapeCss(): string {
+  const block = readThemeBlock();
+  if (block === undefined) return "";
+  return siteThemeShapeCss(SiteThemeSchema.parse(block));
+}