create-ailk 0.8.0 → 0.10.0

package/dist/lib/scaffold-render-sweep.d.ts

@@ -0,0 +1,105 @@
+/** One redirect the driver followed: the status and the raw `Location`. */
+export interface RedirectHop {
+    status: number;
+    location: string | null;
+}
+export interface SweepVerdict {
+    ok: boolean;
+    reason: string;
+}
+/** A passing page verdict names the own-content marker that matched. */
+export interface PageRenderVerdict extends SweepVerdict {
+    marker?: PageMarker;
+}
+export type PageMarker = "h1" | "auth-card" | "sign-in-gate";
+/** More hops than this is a redirect chain, not a render. */
+export declare const MAX_REDIRECTS = 5;
+/**
+ * Routes that are correct to answer 404 in every leg, and the licence claim
+ * that gates them. No leg's served app holds a signed licence — the driver
+ * scrubs `AILK_LICENSE_KEY`, and the mock key is a fixture string, not a JWT —
+ * so each entry must answer exactly 404. A 200 means the gate stopped gating.
+ */
+export declare const CLAIM_GATED_ROUTES: Readonly<Record<string, string>>;
+/**
+ * A route whose live page needs an env var the driver never sets (#6146).
+ * While it is unset the route serves its Free placeholder seed instead
+ * (#6942): a 200 whose `<h1>` carries the `CONFIG_GATED_PLACEHOLDERS`
+ * heading. A 404 is the bug — the site's own nav link dead — and a rendered
+ * page without that heading means the gate stopped gating. Unlike
+ * `CLAIM_GATED_ROUTES`, a route absent from the route table is not stale: the
+ * module that owns it may simply not be installed in this leg.
+ */
+export declare const CONFIG_GATED_ROUTES: Readonly<Record<string, string>>;
+/**
+ * The placeholder heading each `CONFIG_GATED_ROUTES` entry renders while its
+ * env var is unset — for `/meet`, the hero headline of the overlay's
+ * `content/en/LandingPage/meet.mdx` seed. A fresh scaffold never edits it.
+ */
+export declare const CONFIG_GATED_PLACEHOLDERS: Readonly<Record<string, string>>;
+/** Reachability only — for routes that are not pages (`/og`, `/llms.txt`, …). */
+export declare function assessRouteStatus(input: {
+    route: string;
+    hops: RedirectHop[];
+    status: number | null;
+}): SweepVerdict;
+/**
+ * A `CLAIM_GATED_ROUTES` entry: it must be in the route table (a missing one
+ * is stale) and answer exactly 404.
+ */
+export declare function assessClaimGatedRoute(input: {
+    route: string;
+    routeTable: string[];
+    hops: RedirectHop[];
+    status: number | null;
+}): SweepVerdict;
+/**
+ * Decide whether a page route rendered, under the real locale, with its own
+ * content. The first failed rule is the reason:
+ *
+ * 1. no self-redirect, and at most `MAX_REDIRECTS` hops;
+ * 2. a final 200;
+ * 3. an HTML response;
+ * 4. `<html lang>` equal to `locale` — a page under a bogus locale fails;
+ * 5. no streamed error or not-found digest;
+ * 6. an own-content marker — a non-empty `<h1>` (a content page), an
+ *    `auth-card` testid (an `(auth)` page), or a `sign-in-gate` testid (an
+ *    `(authed)` page seen anonymously). The layout carries none of them.
+ */
+export declare function assessPageRender(input: {
+    route: string;
+    hops: RedirectHop[];
+    status: number | null;
+    contentType: string | null;
+    html: string;
+    locale: string;
+}): PageRenderVerdict;
+/**
+ * A `CONFIG_GATED_ROUTES` entry. Unlike `assessClaimGatedRoute`, a route
+ * absent from the route table is not stale — the module that owns it may
+ * simply not be installed in this leg — so it PASSES, skipped, with no
+ * network call needed to decide that (mirroring how `assessClaimGatedRoute`
+ * is called with sentinel `hops`/`status` for its own absent case, never
+ * fetched). Once the route IS present it is scored as an ordinary page via
+ * `assessPageRender`; with its gating env var unset it must ALSO be the
+ * placeholder — an `<h1>` carrying its `CONFIG_GATED_PLACEHOLDERS` heading.
+ * Every failure with the env var unset names it, pinning the cause.
+ */
+export declare function assessConfigGatedRoute(input: {
+    route: string;
+    envVar: string;
+    envSet: boolean;
+    routeTable: string[];
+    hops: RedirectHop[];
+    status: number | null;
+    contentType: string | null;
+    html: string;
+    locale: string;
+}): SweepVerdict;
+/**
+ * Every FILE under `dir`, recursing into directories, as sorted slash-joined
+ * paths relative to it — so `public/.well-known/security.txt` is listed and
+ * the `.well-known` directory never is. Anything that is neither (a symlink,
+ * a socket) throws rather than being silently followed or skipped.
+ */
+export declare function listPublicFiles(dir: string): string[];

package/dist/lib/scaffold-render-sweep.js

@@ -0,0 +1,236 @@
+/**
+ * The verdicts of the scaffold render sweep (#6146).
+ *
+ * `scripts/verify-scaffold.mjs` serves a built scaffold and fetches every
+ * declared route. Until #6146 it served on `-H 127.0.0.1`, which made Next
+ * proxy next-intl's locale rewrite as an EXTERNAL one back into the same
+ * server, so every locale page answered a 307 to itself — and the driver
+ * recorded each as a "known gap" and passed. No request in a leg rendered a
+ * page, and a scaffold that 500'd on every page (#6107) stayed green.
+ *
+ * The rules that decide whether a route really rendered live here, apart from
+ * the driver, for the reason `api-boot-assertion.ts` does: proving them must
+ * not cost a templates build, an install and a `next build`. Each is a pure
+ * function of what the driver observed, so
+ * `__tests__/verify-scaffold-render-sweep.test.ts` drives them directly. The
+ * driver loads this module from `dist/`. Only `listPublicFiles` touches the
+ * filesystem, and none of it touches the network.
+ */
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+/** More hops than this is a redirect chain, not a render. */
+export const MAX_REDIRECTS = 5;
+/**
+ * Routes that are correct to answer 404 in every leg, and the licence claim
+ * that gates them. No leg's served app holds a signed licence — the driver
+ * scrubs `AILK_LICENSE_KEY`, and the mock key is a fixture string, not a JWT —
+ * so each entry must answer exactly 404. A 200 means the gate stopped gating.
+ */
+export const CLAIM_GATED_ROUTES = {
+    "/purchase/success": "commerce",
+    "/purchase/cancel": "commerce",
+};
+/**
+ * A route whose live page needs an env var the driver never sets (#6146).
+ * While it is unset the route serves its Free placeholder seed instead
+ * (#6942): a 200 whose `<h1>` carries the `CONFIG_GATED_PLACEHOLDERS`
+ * heading. A 404 is the bug — the site's own nav link dead — and a rendered
+ * page without that heading means the gate stopped gating. Unlike
+ * `CLAIM_GATED_ROUTES`, a route absent from the route table is not stale: the
+ * module that owns it may simply not be installed in this leg.
+ */
+export const CONFIG_GATED_ROUTES = {
+    "/meet": "SCHEDULING_CAL_LINK",
+};
+/**
+ * The placeholder heading each `CONFIG_GATED_ROUTES` entry renders while its
+ * env var is unset — for `/meet`, the hero headline of the overlay's
+ * `content/en/LandingPage/meet.mdx` seed. A fresh scaffold never edits it.
+ */
+export const CONFIG_GATED_PLACEHOLDERS = {
+    "/meet": "{Book a time with us}",
+};
+const LOOPBACK_BASE = "http://localhost";
+function pathnameOf(location, relativeTo) {
+    return new URL(location, new URL(relativeTo, LOOPBACK_BASE)).pathname;
+}
+/**
+ * Rules 1 and 2 of every verdict: no self-redirect, at most `MAX_REDIRECTS`
+ * hops, and a final 200. A hop is a self-redirect when its `Location`
+ * pathname equals the pathname that hop answered — the route itself for the
+ * first hop, the previous hop's target after that. Query and host are not
+ * compared: the next-intl loop this catches differs from its request in
+ * neither.
+ */
+function assessReachable(route, hops, status) {
+    let answered = route;
+    for (const hop of hops) {
+        if (hop.location === null)
+            break;
+        const target = pathnameOf(hop.location, answered);
+        if (target === new URL(answered, LOOPBACK_BASE).pathname) {
+            return { ok: false, reason: `${answered} -> ${hop.status} self-redirect` };
+        }
+        answered = target;
+    }
+    if (hops.length > MAX_REDIRECTS) {
+        return { ok: false, reason: `${route} -> redirect chain of more than ${MAX_REDIRECTS} hops` };
+    }
+    if (status !== 200)
+        return { ok: false, reason: `${route} -> status ${status}` };
+    return { ok: true, reason: "200" };
+}
+/** Reachability only — for routes that are not pages (`/og`, `/llms.txt`, …). */
+export function assessRouteStatus(input) {
+    return assessReachable(input.route, input.hops, input.status);
+}
+/**
+ * A `CLAIM_GATED_ROUTES` entry: it must be in the route table (a missing one
+ * is stale) and answer exactly 404.
+ */
+export function assessClaimGatedRoute(input) {
+    const { route, routeTable, hops, status } = input;
+    const claim = CLAIM_GATED_ROUTES[route];
+    if (!routeTable.some((r) => (r.replace("/[locale]", "") || "/") === route)) {
+        return { ok: false, reason: `${route} -> stale CLAIM_GATED_ROUTES entry: not in the route table` };
+    }
+    if (hops.length > 0 || status !== 404) {
+        const first = hops[0];
+        const seen = first ? `${first.status} redirect` : `status ${status}`;
+        const why = status === 200 ? "gate open in a keyless serve" : `expected 404, got ${seen}`;
+        return { ok: false, reason: `${route} -> ${why} (claim-gated: ${claim})` };
+    }
+    return { ok: true, reason: `404 (claim-gated: ${claim})` };
+}
+/** The `lang` of the document's `<html>` element, or null when it has none. */
+function htmlLang(html) {
+    return /<html\b[^>]*\slang="([^"]*)"/i.exec(html)?.[1] ?? null;
+}
+/**
+ * The first React Server Components error digest in the flight payload, or
+ * null. It is serialized inside a script string as `\"digest\":\"<value>\"`.
+ * An error or not-found boundary streamed after the shell answers 200 and can
+ * carry its own `<h1>`; this entry is the one reliable trace it leaves.
+ */
+function flightDigest(html) {
+    return /\\"digest\\":\\"([^"\\]*)\\"/.exec(html)?.[1] ?? null;
+}
+/**
+ * Whether an `<h1>`'s inner HTML carries a name: text once tags are stripped,
+ * or an image with a non-empty `alt` (the Hero's lockup renders the wordmark
+ * inside the `<h1>`, and the heading takes its accessible name from it).
+ */
+function headingHasName(inner) {
+    if (inner.replace(/<[^>]*>/g, "").trim() !== "")
+        return true;
+    return [...inner.matchAll(/<img\b[^>]*\salt="([^"]*)"/gi)].some((m) => (m[1] ?? "").trim() !== "");
+}
+/** The first own-content marker the page carries, in the order checked. */
+function ownContentMarker(html) {
+    for (const m of html.matchAll(/<h1\b[^>]*>([\s\S]*?)<\/h1>/gi)) {
+        if (headingHasName(m[1] ?? ""))
+            return "h1";
+    }
+    if (html.includes('data-testid="auth-card"'))
+        return "auth-card";
+    if (html.includes('data-testid="sign-in-gate'))
+        return "sign-in-gate";
+    return null;
+}
+/**
+ * Decide whether a page route rendered, under the real locale, with its own
+ * content. The first failed rule is the reason:
+ *
+ * 1. no self-redirect, and at most `MAX_REDIRECTS` hops;
+ * 2. a final 200;
+ * 3. an HTML response;
+ * 4. `<html lang>` equal to `locale` — a page under a bogus locale fails;
+ * 5. no streamed error or not-found digest;
+ * 6. an own-content marker — a non-empty `<h1>` (a content page), an
+ *    `auth-card` testid (an `(auth)` page), or a `sign-in-gate` testid (an
+ *    `(authed)` page seen anonymously). The layout carries none of them.
+ */
+export function assessPageRender(input) {
+    const { route, hops, status, contentType, html, locale } = input;
+    const reachable = assessReachable(route, hops, status);
+    if (!reachable.ok)
+        return reachable;
+    if (!(contentType ?? "").startsWith("text/html")) {
+        return { ok: false, reason: `${route} -> not html (${contentType})` };
+    }
+    const lang = htmlLang(html);
+    if (lang !== locale)
+        return { ok: false, reason: `${route} -> rendered under locale "${lang}"` };
+    const digest = flightDigest(html);
+    if (digest !== null) {
+        const why = digest.startsWith("NEXT_HTTP_ERROR_FALLBACK;404")
+            ? "streamed not-found"
+            : `streamed error (digest ${digest})`;
+        return { ok: false, reason: `${route} -> ${why}` };
+    }
+    const marker = ownContentMarker(html);
+    if (marker === null) {
+        return { ok: false, reason: `${route} -> no own content (no <h1>, auth-card or sign-in-gate)` };
+    }
+    return { ok: true, reason: marker, marker };
+}
+/**
+ * A `CONFIG_GATED_ROUTES` entry. Unlike `assessClaimGatedRoute`, a route
+ * absent from the route table is not stale — the module that owns it may
+ * simply not be installed in this leg — so it PASSES, skipped, with no
+ * network call needed to decide that (mirroring how `assessClaimGatedRoute`
+ * is called with sentinel `hops`/`status` for its own absent case, never
+ * fetched). Once the route IS present it is scored as an ordinary page via
+ * `assessPageRender`; with its gating env var unset it must ALSO be the
+ * placeholder — an `<h1>` carrying its `CONFIG_GATED_PLACEHOLDERS` heading.
+ * Every failure with the env var unset names it, pinning the cause.
+ */
+export function assessConfigGatedRoute(input) {
+    const { route, envVar, envSet, routeTable, hops, status, contentType, html, locale } = input;
+    if (!routeTable.some((r) => (r.replace("/[locale]", "") || "/") === route)) {
+        return { ok: true, reason: `${route} -> skipped: not in the route table (module not installed)` };
+    }
+    const rendered = assessPageRender({ route, hops, status, contentType, html, locale });
+    if (envSet)
+        return rendered;
+    if (!rendered.ok)
+        return { ok: false, reason: `${rendered.reason} (${envVar} unset)` };
+    const placeholder = CONFIG_GATED_PLACEHOLDERS[route];
+    if (placeholder === undefined) {
+        return { ok: false, reason: `${route} -> no CONFIG_GATED_PLACEHOLDERS entry to check with ${envVar} unset` };
+    }
+    if (!headingTexts(html).some((text) => text.includes(placeholder))) {
+        return {
+            ok: false,
+            reason: `${route} -> expected the "${placeholder}" placeholder with ${envVar} unset, rendered another page`,
+        };
+    }
+    return { ok: true, reason: `placeholder (${envVar} unset)` };
+}
+/** The text of every `<h1>` in the document, tags stripped. */
+function headingTexts(html) {
+    return [...html.matchAll(/<h1\b[^>]*>([\s\S]*?)<\/h1>/gi)].map((m) => (m[1] ?? "").replace(/<[^>]*>/g, ""));
+}
+/**
+ * Every FILE under `dir`, recursing into directories, as sorted slash-joined
+ * paths relative to it — so `public/.well-known/security.txt` is listed and
+ * the `.well-known` directory never is. Anything that is neither (a symlink,
+ * a socket) throws rather than being silently followed or skipped.
+ */
+export function listPublicFiles(dir) {
+    return listFilesUnder(dir, "");
+}
+function listFilesUnder(dir, relPrefix) {
+    const out = [];
+    const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1));
+    for (const entry of entries) {
+        const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            out.push(...listFilesUnder(join(dir, entry.name), rel));
+        else if (entry.isFile())
+            out.push(rel);
+        else
+            throw new Error(`public/${rel} is neither a file nor a directory`);
+    }
+    return out;
+}

package/dist/module-architecture.d.ts

@@ -73,15 +73,19 @@ export interface PageRosterRow {
 /**
  * The architecture fragment one module contributes.
  *
- * `apps/web` (the presentation shell) is BASE — always present — so a module
- * extends it via `webImports` (packages added to `apps/web.may_import_from`)
- * rather than redeclaring it. Additional apps (api, mcp), packages, namespaces,
- * and top-level forbidden patterns are contributed outright.
+ * `apps/web`, `apps/api` and `apps/mcp` are BASE — always present. A module
+ * extends apps/web via `webImports` (added to `apps/web.may_import_from`)
+ * rather than redeclaring it; an `apps` entry replaces a base api/mcp block or
+ * adds an app (admin). Packages, namespaces and top-level forbidden patterns
+ * are contributed outright. `webImports`, `packages` and every `packages/*`
+ * entry describe this monorepo's boundaries: a scaffold has no `packages/`
+ * tree, so `deriveArchitecture` keeps only the entries naming a path the
+ * scaffold carries (#6940).
  */
 export interface ModuleSlice {
     /** Packages this module adds to apps/web.may_import_from (its presentation surface). */
     webImports?: string[];
-    /** Additional apps this module introduces (api, mcp). web is BASE, never here. */
+    /** Apps this module declares (api, mcp replace the base block; admin is new). web is BASE, never here. */
     apps?: Record<string, ArchApp>;
     /** Packages this module contributes. */
     packages?: Record<string, ArchPackage>;
@@ -308,33 +312,32 @@ export interface AddTransformOp {
     value: string;
 }
 /**
- * The module-independent base: `apps/web` (the Next.js presentation shell every
- * AILK site has) plus the standalone forbidden-pattern floor. `may_import_from`
- * starts EMPTY — the selected modules fill it via `webImports`.
+ * The module-independent base: the three apps every scaffold ships on disk
+ * (`apps/web`, `apps/api`, `apps/mcp` — template-overlay/apps carries all
+ * three whatever the module set, #6940) plus the standalone forbidden-pattern
+ * floor. apps/web's `may_import_from` starts EMPTY — the selected modules fill
+ * it via `webImports`; a module that declares `api`/`mcp` replaces the base
+ * block with its own.
  */
 export declare const ARCHITECTURE_BASE: {
     readonly version: 1;
     readonly composition_model: {
-        readonly reference: "claude-setup rules/need-to-know.md § Vocabulary (Module / Surface)";
         readonly tiers: {
             readonly data: "database/ — Prisma schema + migrations";
             readonly api: "apps/api (public HTTP API) + apps/mcp (agent tools)";
             readonly presentation: "apps/web — frontend surfaces";
         };
     };
+    /** Every declared app's own forbidden patterns (merged ahead of any the app adds). */
+    readonly appForbiddenPatterns: ForbiddenPattern[];
     /** The base apps/web shell. may_import_from is filled from the selected modules' webImports. */
     readonly web: {
         readonly path: "apps/web";
         readonly description: "Next.js — presentation tier. Frontend surfaces composed from the selected modules.";
         readonly may_not_import_from: readonly ["apps/api", "apps/mcp"];
-        readonly forbidden_patterns: readonly [{
-            readonly pattern: string;
-            readonly reason: "A scaffolded AILK site is standalone — no upstream-monorepo imports";
-        }, {
-            readonly pattern: "@alkit/";
-            readonly reason: "Renamed to @working-theory/* on extraction";
-        }];
     };
+    /** The base apps/api and apps/mcp — present in every scaffold (#6940). */
+    readonly apps: Record<string, ArchApp>;
     /** Standalone-site forbidden-pattern floor (top-level, always present). */
     readonly forbiddenPatterns: ForbiddenPattern[];
 };

package/dist/module-architecture.js

@@ -83,35 +83,59 @@ const PUBLIC_SCHEDULING_VAR_PATTERN = [
  */
 const STRIPE_LIVE_KEY_PATTERN = ["(sk|pk|rk)_li", "ve_[A-Za-z0-9]"].join("");
 /**
- * The module-independent base: `apps/web` (the Next.js presentation shell every
- * AILK site has) plus the standalone forbidden-pattern floor. `may_import_from`
- * starts EMPTY — the selected modules fill it via `webImports`.
+ * The per-app forbidden-pattern floor every declared app carries — so each app
+ * a scaffold ships has its own rule in `architecture.yaml`, not only the
+ * top-level floor below.
+ */
+const APP_FORBIDDEN_FLOOR = [
+    {
+        pattern: NO_UPSTREAM_IMPORT_PATTERN,
+        reason: "A scaffolded AILK site is standalone — no upstream-monorepo imports",
+    },
+    {
+        pattern: "@alkit/",
+        reason: "Renamed to @working-theory/* on extraction",
+    },
+];
+/**
+ * The module-independent base: the three apps every scaffold ships on disk
+ * (`apps/web`, `apps/api`, `apps/mcp` — template-overlay/apps carries all
+ * three whatever the module set, #6940) plus the standalone forbidden-pattern
+ * floor. apps/web's `may_import_from` starts EMPTY — the selected modules fill
+ * it via `webImports`; a module that declares `api`/`mcp` replaces the base
+ * block with its own.
  */
 export const ARCHITECTURE_BASE = {
     version: 1,
     composition_model: {
-        reference: "claude-setup rules/need-to-know.md § Vocabulary (Module / Surface)",
         tiers: {
             data: "database/ — Prisma schema + migrations",
             api: "apps/api (public HTTP API) + apps/mcp (agent tools)",
             presentation: "apps/web — frontend surfaces",
         },
     },
+    /** Every declared app's own forbidden patterns (merged ahead of any the app adds). */
+    appForbiddenPatterns: APP_FORBIDDEN_FLOOR,
     /** The base apps/web shell. may_import_from is filled from the selected modules' webImports. */
     web: {
         path: "apps/web",
         description: "Next.js — presentation tier. Frontend surfaces composed from the selected modules.",
         may_not_import_from: ["apps/api", "apps/mcp"],
-        forbidden_patterns: [
-            {
-                pattern: NO_UPSTREAM_IMPORT_PATTERN,
-                reason: "A scaffolded AILK site is standalone — no upstream-monorepo imports",
-            },
-            {
-                pattern: "@alkit/",
-                reason: "Renamed to @working-theory/* on extraction",
-            },
-        ],
+    },
+    /** The base apps/api and apps/mcp — present in every scaffold (#6940). */
+    apps: {
+        api: {
+            path: "apps/api",
+            description: "Public HTTP API — routes + services (Fastify).",
+            may_import_from: ["database"],
+            may_not_import_from: ["apps/mcp", "apps/web"],
+        },
+        mcp: {
+            path: "apps/mcp",
+            description: "MCP server — agent-facing tools. Calls apps/api for writes.",
+            may_import_from: ["database"],
+            may_not_import_from: ["apps/api", "apps/web"],
+        },
     },
     /** Standalone-site forbidden-pattern floor (top-level, always present). */
     forbiddenPatterns: [
@@ -595,12 +619,12 @@ export const MODULE_SLICES = {
             {
                 pattern: "import.*['\"]stripe['\"]",
                 paths_excluded: ["packages/stripe-client/**"],
-                reason: "Stripe SDK imports go through packages/stripe-client only — single point of config",
+                reason: "Stripe SDK imports go through @working-theory/stripe-client only — single point of config",
             },
             {
                 pattern: "import.*['\"]resend['\"]|['\"]nodemailer['\"]",
                 paths_excluded: ["packages/email/**"],
-                reason: "Email provider SDKs go through packages/email — provider swap is a one-package change",
+                reason: "Email provider SDKs go through @working-theory/email — provider swap is a one-package change",
             },
         ],
         // ownedFiles (S1, #5088). Verified against the current filesystem and
@@ -1413,6 +1437,9 @@ export const MODULE_SLICES = {
             // upgrade-path fixture to protect either — it is net-new here, so nothing
             // in `templates/` can regress by its absence.
             "apps/web/app/[locale]/reports/[slug]/page.tsx",
+            // spec 6892 D2 — the /reports hub, alongside its reader above: also a
+            // URL segment MODULE_SURFACES["signal-collectors"] does not gate.
+            "apps/web/app/[locale]/reports/page.tsx",
             //
             // The two sections that route composes — `report-header` and
             // `reports-list` — are deliberately NOT owned here. They are
@@ -1446,11 +1473,13 @@ export const MODULE_SLICES = {
             // #5562 — the report reader. Unlike the three rows above, this row's
             // code IS this module's own `ownedFiles` (see the note beside it), so
             // the contribution and the delivery shape carrying it agree here. Its
-            // seeds are a directory a template supplies (minimalism-site's four
-            // reports), so the row declares that directory (#6646).
+            // seeds are SELF-SEEDING (spec 6892 D3): this module's own `installMap`
+            // lands the four `ReportPage` samples below, so every template taking
+            // the module gets them — `moduleRosterRows` derives the code-route form
+            // for this row rather than requiring a template to ship one (D9).
             { route: "/reports/[slug]", contentDir: "content/en/ReportPage" },
         ],
-        // installMap (#5618 D6.3) — the module's ten sample files, moved here out
+        // installMap (#5618 D6.3) — the module's sample files, moved here out
         // of `site-templates/marketing-site/` so the module OWNS its samples
         // (Rule B) and a keyed `--modules signal-collectors` scaffold with no
         // template lands them. Their in-repo home is
@@ -1463,12 +1492,19 @@ export const MODULE_SLICES = {
         // `module-templates/` the two never meet.
         //
         // Four entries are real renames (the flow and waitlist seeds the API
-        // reads, and the report PDF under apps/web/public/); the six MDX entries
+        // reads, and the report PDF under apps/web/public/); the ten MDX entries
         // are self-addressed. Their `/projects`, `/projects/[slug]` and
         // `/thanks/[slug]` rows are declared by the templates that install them
         // (`template-manifest.ts`'s signal-collectors sample rows, #6646), not
         // here — a module contribution would change the enabled-surface set and
-        // so the Pro scaffold's file set (spec 5618 § 7 finding 7).
+        // so the Pro scaffold's file set (spec 5618 § 7 finding 7). The four
+        // `ReportPage` seeds and the `ReportsList` hub seed are the one exception
+        // (spec 6892 D3): their `/reports/[slug]` and `/reports` rows ARE this
+        // module's own `pageContributions`/`starter-grid.ts` rows respectively,
+        // so this module installs its own seeds for them directly, unlike the
+        // sample rows above. `/referral`'s seed and flow move here the same way,
+        // moved out of a retired template tree (spec 6892 D3), which owned no
+        // code of its own for either route.
         // `generate-sample-report.py` keeps its root-level destination
         // (finding 1 — AC7 forbids changing the Pro file set).
         installMap: {
@@ -1478,7 +1514,14 @@ export const MODULE_SLICES = {
             "packages/create-ailk/module-templates/signal-collectors/content/en/ThankYouPage/contact.mdx": "content/en/ThankYouPage/contact.mdx",
             "packages/create-ailk/module-templates/signal-collectors/content/en/ThankYouPage/newsletter.mdx": "content/en/ThankYouPage/newsletter.mdx",
             "packages/create-ailk/module-templates/signal-collectors/content/en/ThankYouPage/apply.mdx": "content/en/ThankYouPage/apply.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/ReportPage/annual-letter-2024.mdx": "content/en/ReportPage/annual-letter-2024.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/ReportPage/field-notes-2023.mdx": "content/en/ReportPage/field-notes-2023.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/ReportPage/platform-shift-2025.mdx": "content/en/ReportPage/platform-shift-2025.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/ReportPage/state-of-the-market-2026.mdx": "content/en/ReportPage/state-of-the-market-2026.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/ReportsList/reports.mdx": "content/en/ReportsList/reports.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/LandingPage/referral.mdx": "content/en/LandingPage/referral.mdx",
             "packages/create-ailk/module-templates/signal-collectors/flows/fit-check.flow.json": "database/flows/fit-check.flow.json",
+            "packages/create-ailk/module-templates/signal-collectors/flows/referral.flow.json": "database/flows/referral.flow.json",
             "packages/create-ailk/module-templates/signal-collectors/waitlist/launch-waitlist.experiment.json": "database/waitlist/launch-waitlist.experiment.json",
             "packages/create-ailk/module-templates/signal-collectors/reports/sample-report.pdf": "apps/web/public/reports/sample-report.pdf",
             "packages/create-ailk/module-templates/signal-collectors/reports/generate-sample-report.py": "reports/generate-sample-report.py",
@@ -1618,7 +1661,7 @@ export const MODULE_SLICES = {
         // it sits outside build-templates.mjs's SNAPSHOT_DIRS/overlay, so
         // ownedFiles/paidModuleTemplateExclusions cannot reach it) to
         // `module-templates/commerce/.claude/skills/scaffold-commerce/`, and
-        // delivered into a keyed scaffold by `installMap` instead. Ten literal
+        // delivered into a keyed scaffold by `installMap` instead. Eleven literal
         // entries, not one directory entry: `extractModuleBundle`'s
         // `validateInstallMap` requires every source to be a FILE the bundle
         // produced (`extract-module-bundle.ts`'s `!sourceStat.isFile()` check) —
@@ -1634,10 +1677,11 @@ export const MODULE_SLICES = {
             "packages/create-ailk/module-templates/commerce/.claude/skills/scaffold-commerce/templates/portal-route.template.ts": ".claude/skills/scaffold-commerce/templates/portal-route.template.ts",
             "packages/create-ailk/module-templates/commerce/.claude/skills/scaffold-commerce/templates/stripe-config.template.ts": ".claude/skills/scaffold-commerce/templates/stripe-config.template.ts",
             "packages/create-ailk/module-templates/commerce/.claude/skills/scaffold-commerce/templates/subscription-route.template.ts": ".claude/skills/scaffold-commerce/templates/subscription-route.template.ts",
+            "packages/create-ailk/module-templates/commerce/.claude/skills/scaffold-commerce/scripts/stripe-catalog.ts": ".claude/skills/scaffold-commerce/scripts/stripe-catalog.ts",
             // The commerce-boundary rule (#6039/#6070, this entry #6041): ships to
             // a commerce-keyed scaffold's project root so an agent working there
             // reads the money/live-mode/personal-data classification before it
-            // acts. One more literal entry alongside the ten scaffold-commerce
+            // acts. One more literal entry alongside the eleven scaffold-commerce
             // skill entries above, for the same reason — a directory source is
             // rejected by `validateInstallMap`.
             "packages/create-ailk/module-templates/commerce/.claude/rules/commerce-boundary.md": ".claude/rules/commerce-boundary.md",

package/dist/parse-args.d.ts

@@ -39,8 +39,12 @@ export interface CliOptions {
     template: string | undefined;
     /** The starter's shape (`--shape`, #6754), normalized. Never set with `template`. */
     shape?: ShapeName;
-    /** The starter's design (`--design`, #6754). Never set with `template`. */
-    design?: DesignName;
+    /**
+     * The starter's design (`--design`, #6754; widened to a path #6813 D1/D3):
+     * a recognized name, lowercased, or an absolute directory holding a
+     * `DESIGN.md`, case preserved. Never set with `template`.
+     */
+    design?: string;
     /**
      * True when a scaffold run named neither `--shape` nor `--template` on a
      * terminal: `resolveCliShape` must ask before anything is scaffolded.
@@ -66,6 +70,12 @@ export interface CliOptions {
      * `--sync-architecture`: data-only, one file, an already-scaffolded target.
      */
     syncCatalog: boolean;
+    /**
+     * When set, rewrite the template-owned sections of the target's CLAUDE.md
+     * to the template this create-ailk ships and exit (#6904). The same sync
+     * shape: one file, an already-scaffolded target.
+     */
+    syncClaudeMd: boolean;
     /**
      * When set, a fresh scaffold ALSO gets COMPONENT-CATALOG.md. Off by default
      * so a scaffold that does not ask for the catalog is byte-identical to the