create-ailk 0.8.0 → 0.9.0

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 the retired `minimalism-site` 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",

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

package/dist/parse-args.js

@@ -7,6 +7,8 @@
  * On any parse / validation failure: throws ParseError. The orchestrator's
  * top-level catch turns this into a stderr write + non-zero exit.
  */
+import { existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
 import { assertLicenseKeyShape } from "./lib/license-key-files.js";
@@ -95,8 +97,9 @@ Options:
                            Installs that shape's Free starter. A run naming
                            neither --shape nor --template asks for a shape on
                            a terminal, and refuses without one.
-  --design <design>        The look to render the starter in (recognized:
-                           ${RECOGNIZED_DESIGNS.join(", ")}). Defaults to the
+  --design <design>        The look to render the starter in: a design name
+                           (recognized: ${RECOGNIZED_DESIGNS.join(", ")}) or a
+                           directory holding a DESIGN.md. Defaults to the
                            starter's own.
   --template <name>        The site template to install (recognized:
                            ${RECOGNIZED_TEMPLATES.join(", ")}).
@@ -120,8 +123,9 @@ Options:
                            Surfaces the declared architecture does not carry are
                            NOT scaffolded — their routes are absent, so a fresh
                            site never serves a stock page with placeholder
-                           content. Add one later with the \`add-page\`
-                           skill, or re-run with the surface named here.
+                           content. Add one later with
+                           \`create-ailk add-route <surface>\`, or re-run with
+                           the surface named here.
   --sync-architecture <csv> Regenerate architecture.yaml in place in an
                            already-scaffolded repo from the given module set
                            (recognized: ${RECOGNIZED_MODULES.join(", ")}), then
@@ -140,6 +144,12 @@ Options:
                            file, at the target dir (positional arg, else cwd).
                            Bypasses the scaffold path — copies no template, runs
                            no install. Re-run after upgrading create-ailk.
+  --sync-claude-md         Rewrite the AI Launch Kit sections of CLAUDE.md in
+                           an already-scaffolded repo to the template this
+                           create-ailk ships, then exit. Only CLAUDE.md
+                           changes; your Site notes and anything between the
+                           sections are kept byte for byte. Target dir is the
+                           positional arg, else cwd.
   --license <key>          Your licence key: fetch paid modules with it and
                            write it into the scaffold (apps/api/.env and a
                            gitignored ailk.key, both owner-only).
@@ -180,6 +190,7 @@ export function parseCliArgs(argv, env = { interactive: false }) {
                 surfaces: { type: "string" },
                 "sync-architecture": { type: "string" },
                 "sync-catalog": { type: "boolean", default: false },
+                "sync-claude-md": { type: "boolean", default: false },
                 "with-catalog": { type: "boolean", default: false },
                 install: { type: "boolean", default: false },
                 help: { type: "boolean", default: false, short: "h" },
@@ -203,12 +214,18 @@ export function parseCliArgs(argv, env = { interactive: false }) {
     const surfaces = parseSurfaceList(parsed.values.surfaces);
     const syncArchitecture = parsed.values["sync-architecture"];
     const syncCatalog = parsed.values["sync-catalog"] === true;
+    const syncClaudeMd = parsed.values["sync-claude-md"] === true;
     const withCatalog = parsed.values["with-catalog"] === true;
     const license = parseLicense(parsed.values.license);
-    // The two sync modes each exit after rewriting their one file, so asking for
-    // both in one invocation has no coherent meaning.
-    if (syncCatalog && syncArchitecture !== undefined) {
-        throw new ParseError("--sync-catalog and --sync-architecture cannot be combined; run them one at a time");
+    // The sync modes each exit after rewriting their one file, so asking for
+    // more than one in one invocation has no coherent meaning.
+    const syncFlags = [
+        syncCatalog ? "--sync-catalog" : undefined,
+        syncArchitecture !== undefined ? "--sync-architecture" : undefined,
+        syncClaudeMd ? "--sync-claude-md" : undefined,
+    ].filter((f) => f !== undefined);
+    if (syncFlags.length > 1) {
+        throw new ParseError(`${syncFlags.join(" and ")} cannot be combined; run them one at a time`);
     }
     // Validate the sync-architecture value now, through the SAME parseModules
     // path `--modules` uses, so an unknown module throws ParseError at parse time
@@ -228,12 +245,13 @@ export function parseCliArgs(argv, env = { interactive: false }) {
             modules,
             surfaces,
             syncCatalog: false,
+            syncClaudeMd: false,
             withCatalog: false,
             syncArchitecture: undefined,
         };
     }
     // Sync modes: the target dir is optional (positional if given, else cwd).
-    if (syncArchitecture !== undefined || syncCatalog) {
+    if (syncArchitecture !== undefined || syncCatalog || syncClaudeMd) {
         if (parsed.positionals.length > 1) {
             throw new ParseError(`expected at most one target directory, got ${parsed.positionals.length}`);
         }
@@ -247,6 +265,7 @@ export function parseCliArgs(argv, env = { interactive: false }) {
             modules,
             surfaces,
             syncCatalog,
+            syncClaudeMd,
             withCatalog,
             syncArchitecture,
         };
@@ -284,6 +303,7 @@ export function parseCliArgs(argv, env = { interactive: false }) {
         modules,
         surfaces,
         syncCatalog,
+        syncClaudeMd,
         withCatalog,
         syncArchitecture: undefined,
         ...(license !== undefined ? { license } : {}),
@@ -305,15 +325,56 @@ function parseShape(raw) {
     }
     return name;
 }
-/** Validate `--design` (#6754 D2 step 2): trimmed and lowercased. */
+/** `path` is an existing directory. */
+function isExistingDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `dir` (resolved from `raw`) as a design path: an existing directory
+ * holding a `DESIGN.md`, else `ParseError` naming `raw` (#6813 D1 rule 2).
+ */
+function validateDesignDir(dir, raw) {
+    if (!isExistingDir(dir)) {
+        throw new ParseError(`design directory "${raw}" does not exist`);
+    }
+    if (!existsSync(join(dir, "DESIGN.md"))) {
+        throw new ParseError(`design directory "${raw}" holds no DESIGN.md`);
+    }
+    return dir;
+}
+/**
+ * Validate `--design` (#6754 D2 step 2, widened #6813 D1): a recognized
+ * name, or a directory holding a `DESIGN.md`. A value with no `/` or `\` is
+ * classified as a name first (trimmed and lowercased, filesystem never
+ * consulted) — falling back to a path only when it names an existing
+ * directory in `process.cwd()`, so `--design mydesign` and `--design
+ * ./mydesign` can differ. A value with a separator is always a path,
+ * resolved against `process.cwd()`, case preserved. The package's CONTENT is
+ * validated later, in `scaffold()` (`resolveDesign`) — this parser checks
+ * presence only.
+ */
 function parseDesign(raw) {
     if (raw === undefined)
         return undefined;
-    const name = raw.trim().toLowerCase();
-    if (!RECOGNIZED_DESIGNS.includes(name)) {
+    const trimmed = raw.trim();
+    const hasSeparator = trimmed.includes("/") || trimmed.includes("\\");
+    if (!hasSeparator) {
+        const name = trimmed.toLowerCase();
+        if (RECOGNIZED_DESIGNS.includes(name)) {
+            return name;
+        }
+        const dir = resolve(process.cwd(), trimmed);
+        if (isExistingDir(dir)) {
+            return validateDesignDir(dir, raw);
+        }
         throw new ParseError(`unknown design "${raw}". Recognized: ${RECOGNIZED_DESIGNS.join(", ")}`);
     }
-    return name;
+    return validateDesignDir(resolve(process.cwd(), trimmed), raw);
 }
 /** How many answers the prompt takes before it gives up. */
 const PROMPT_ATTEMPTS = 3;