create-ailk 0.6.0 → 0.7.0

package/dist/license-set.d.ts

@@ -0,0 +1,34 @@
+export interface LicenseSetRunResult {
+    /** Exit status; null when the process never ran or was killed. */
+    status: number | null;
+    /** Set when the process could not be spawned (e.g. `ENOENT`). */
+    error?: NodeJS.ErrnoException;
+}
+/**
+ * Runs `vercel <args>`. The command itself is fixed — a runner is never
+ * handed one to run, per the package's hard-coded-command invariant
+ * (security.test.ts).
+ * `input`, when given, is written to the child's stdin.
+ */
+export type LicenseSetRunner = (args: readonly string[], options: {
+    cwd: string;
+    input?: string;
+}) => LicenseSetRunResult;
+export interface LicenseSetIO {
+    /** Resolves a relative or absent `[dir]`. */
+    cwd: string;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    /** Reads all of stdin — used only by the `-` form. */
+    readStdin: () => string;
+    /** Defaults to `spawnSync` with `shell: false` (see `defaultRunner`). */
+    runner?: LicenseSetRunner;
+}
+export declare const LICENSE_SET_HELP = "create-ailk license set \u2014 put your licence key into an existing site.\n\nUsage:\n  pnpm create ailk@latest license set <key> [<target-dir>]\n  pnpm create ailk@latest license set - [<target-dir>] < key.txt\n\nArguments:\n  <key>                    Your licence key, or `-` to read it from stdin\n                           (keeps it out of your shell history).\n  <target-dir>             An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n\nWrites the key to ailk.key and apps/api/.env (owner-only, gitignored). When the\nsite (or apps/api, or apps/web) is linked to Vercel, it also replaces the\nproduction AILK_LICENSE_KEY variable and redeploys.\n";
+/** `spawnSync`, never through a shell; stdin piped only when there is input. */
+export declare const defaultRunner: LicenseSetRunner;
+/**
+ * Run `license set` with `argv` = everything after the `license set` words.
+ * Returns the process exit code; never throws for an expected failure.
+ */
+export declare function runLicenseSet(argv: string[], io: LicenseSetIO): number;

package/dist/license-set.js

@@ -0,0 +1,194 @@
+/**
+ * `create-ailk license set <key|-> [dir]` — put a licence key into an existing
+ * scaffold and, when it is Vercel-linked, into production (#6683 § 3 D9).
+ *
+ * The one-liner a buyer runs is `pnpm create ailk@latest license set <key>`:
+ * `create-ailk` is the public CLI they already have (§ 1.8).
+ *
+ *   1. The target (default: cwd) must contain `architecture.yaml` — the
+ *      `sync-routes` precondition — else exit 1 with nothing written.
+ *   2. `writeLicenseKeyFiles` — `ailk.key` + `apps/api/.env`, both 0600 and
+ *      gitignored; the same writer `--license` uses.
+ *   3. For each of `<dir>`, `<dir>/apps/api`, `<dir>/apps/web` holding
+ *      `.vercel/project.json`, with that directory as `cwd`:
+ *        a. print the linked `projectId` about to change (SEC-13);
+ *        b. list `ailk.key` and `.env` in its `.vercelignore` — a CLI deploy
+ *           uploads the local tree, which `.gitignore` does not govern (SEC-10);
+ *        c. `vercel env rm AILK_LICENSE_KEY production --yes` (failure
+ *           tolerated: the variable may not exist yet);
+ *        d. `vercel env add AILK_LICENSE_KEY production`, the key on STDIN;
+ *        e. `vercel deploy --prod --yes`.
+ *
+ * The key is never an argv element of a spawned process and never appears in
+ * an error (SEC-11). `vercel` missing → exit 1 naming what was written and the
+ * exact manual commands; a failed `env add` after `env rm` → exit 1 saying the
+ * production variable is now UNSET, with the command that finishes the job.
+ * No Vercel link → exit 0 after the local write.
+ *
+ * Pure module (no `import.meta.url`): every effect on the outside world —
+ * output, stdin, the process runner — is injected, so jest drives it directly.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { LICENSE_ENV_FILE, LICENSE_ENV_VAR, LICENSE_KEY_FILE, assertLicenseKeyShape, writeLicenseKeyFiles, } from "./lib/license-key-files.js";
+export const LICENSE_SET_HELP = `create-ailk license set — put your licence key into an existing site.
+
+Usage:
+  pnpm create ailk@latest license set <key> [<target-dir>]
+  pnpm create ailk@latest license set - [<target-dir>] < key.txt
+
+Arguments:
+  <key>                    Your licence key, or \`-\` to read it from stdin
+                           (keeps it out of your shell history).
+  <target-dir>             An already-scaffolded repo (contains
+                           architecture.yaml). Defaults to the current dir.
+
+Writes the key to ailk.key and apps/api/.env (owner-only, gitignored). When the
+site (or apps/api, or apps/web) is linked to Vercel, it also replaces the
+production AILK_LICENSE_KEY variable and redeploys.
+`;
+const LINK_DIRS = [".", join("apps", "api"), join("apps", "web")];
+const VERCELIGNORE_LINES = [LICENSE_KEY_FILE, ".env"];
+const ENV_RM = ["env", "rm", LICENSE_ENV_VAR, "production", "--yes"];
+const ENV_ADD = ["env", "add", LICENSE_ENV_VAR, "production"];
+const DEPLOY = ["deploy", "--prod", "--yes"];
+/** `spawnSync`, never through a shell; stdin piped only when there is input. */
+export const defaultRunner = (args, options) => {
+    const res = spawnSync("vercel", [...args], {
+        cwd: options.cwd,
+        shell: false,
+        stdio: [options.input !== undefined ? "pipe" : "inherit", "inherit", "inherit"],
+        ...(options.input !== undefined ? { input: options.input } : {}),
+    });
+    return {
+        status: res.status,
+        ...(res.error !== undefined
+            ? { error: res.error }
+            : {}),
+    };
+};
+class LicenseSetError extends Error {
+}
+/**
+ * Hand-parsed rather than through `node:util` `parseArgs`: its errors quote
+ * the offending token, and the token here may be the key.
+ */
+function parseLicenseSetArgs(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        return { help: true, key: undefined, target: undefined };
+    }
+    if (argv.length > 2) {
+        throw new LicenseSetError(`expected <key|-> and at most one target directory, got ${argv.length} arguments`);
+    }
+    return { help: false, key: argv[0], target: argv[1] };
+}
+/** Append whichever of `lines` the file does not already list. */
+function ensureVercelIgnore(dir) {
+    const path = join(dir, ".vercelignore");
+    const text = existsSync(path) ? readFileSync(path, "utf8") : "";
+    const present = new Set(text.split("\n").map((l) => l.trim()));
+    const missing = VERCELIGNORE_LINES.filter((l) => !present.has(l) && !present.has(`/${l}`));
+    if (missing.length === 0)
+        return;
+    const sep = text.length === 0 || text.endsWith("\n") ? "" : "\n";
+    writeFileSync(path, `${text}${sep}${missing.join("\n")}\n`);
+}
+function readProjectId(dir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(dir, ".vercel", "project.json"), "utf8"));
+        if (typeof raw.projectId === "string" && raw.projectId.length > 0) {
+            return raw.projectId;
+        }
+    }
+    catch {
+        // fall through
+    }
+    throw new LicenseSetError(`${join(dir, ".vercel", "project.json")} has no readable projectId; run \`vercel link\` there, then re-run.`);
+}
+/** The exact commands that finish the push by hand, from `dir`. */
+function manualCommands(dir, keyFile, from) {
+    const keyRel = relative(dir, keyFile) || LICENSE_KEY_FILE;
+    const lines = [`  cd ${dir}`];
+    if (from === "rm")
+        lines.push(`  vercel ${ENV_RM.join(" ")}`);
+    lines.push(`  tr -d '\\n' < ${keyRel} | vercel ${ENV_ADD.join(" ")}`);
+    lines.push(`  vercel ${DEPLOY.join(" ")}`);
+    return lines.join("\n");
+}
+/**
+ * Run `license set` with `argv` = everything after the `license set` words.
+ * Returns the process exit code; never throws for an expected failure.
+ */
+export function runLicenseSet(argv, io) {
+    const runner = io.runner ?? defaultRunner;
+    const fail = (message) => {
+        io.stderr(`[create-ailk] license set: ${message}\n`);
+        return 1;
+    };
+    let args;
+    try {
+        args = parseLicenseSetArgs(argv);
+    }
+    catch (err) {
+        return fail(`${err.message}\n\n${LICENSE_SET_HELP}`);
+    }
+    if (args.help) {
+        io.stdout(LICENSE_SET_HELP);
+        return 0;
+    }
+    if (args.key === undefined) {
+        return fail(`missing <key>.\n\n${LICENSE_SET_HELP}`);
+    }
+    const key = args.key === "-" ? io.readStdin().trim() : args.key;
+    try {
+        assertLicenseKeyShape(key);
+    }
+    catch (err) {
+        return fail(err.message);
+    }
+    const target = resolve(io.cwd, args.target ?? ".");
+    if (!existsSync(join(target, "architecture.yaml"))) {
+        return fail(`not a scaffolded repo: no architecture.yaml at ${target}. Run it from your site's root, or pass the site's directory.`);
+    }
+    writeLicenseKeyFiles(target, key);
+    const keyFile = join(target, LICENSE_KEY_FILE);
+    const written = `Wrote ${LICENSE_KEY_FILE} and ${LICENSE_ENV_FILE.split("\\").join("/")} in ${target}`;
+    io.stdout(`[create-ailk] ${written} (owner-only, gitignored).\n`);
+    const linked = LINK_DIRS.map((d) => join(target, d)).filter((d) => existsSync(join(d, ".vercel", "project.json")));
+    if (linked.length === 0) {
+        io.stdout("[create-ailk] No Vercel link found (.vercel/project.json); nothing pushed. Set AILK_LICENSE_KEY on your host yourself if you deploy elsewhere.\n");
+        return 0;
+    }
+    for (const dir of linked) {
+        let projectId;
+        try {
+            projectId = readProjectId(dir);
+        }
+        catch (err) {
+            return fail(err.message);
+        }
+        io.stdout(`[create-ailk] Updating ${LICENSE_ENV_VAR} (production) on Vercel project ${projectId}, linked at ${dir}\n`);
+        ensureVercelIgnore(dir);
+        const rm = runner(ENV_RM, { cwd: dir });
+        if (rm.error?.code === "ENOENT") {
+            return fail(`the vercel CLI was not found. ${written}; nothing was pushed. Install it (npm i -g vercel), or finish by hand:\n${manualCommands(dir, keyFile, "rm")}`);
+        }
+        // `rm` may fail because the variable never existed — tolerated — but then
+        // it removed nothing, and the message below must not say it did.
+        const removed = rm.error === undefined && rm.status === 0;
+        const add = runner(ENV_ADD, { cwd: dir, input: key });
+        if (add.error !== undefined || add.status !== 0) {
+            const state = removed
+                ? `The production variable ${LICENSE_ENV_VAR} is now UNSET there (the old value was removed).`
+                : `The production variable ${LICENSE_ENV_VAR} was not changed (removing the old value also failed).`;
+            return fail(`\`vercel ${ENV_ADD.join(" ")}\` failed on project ${projectId}. ${state} Finish with:\n${manualCommands(dir, keyFile, removed ? "add" : "rm")}`);
+        }
+        const deploy = runner(DEPLOY, { cwd: dir });
+        if (deploy.error !== undefined || deploy.status !== 0) {
+            return fail(`\`vercel ${DEPLOY.join(" ")}\` failed on project ${projectId}. ${LICENSE_ENV_VAR} is set in production; redeploy with:\n  cd ${dir}\n  vercel ${DEPLOY.join(" ")}`);
+        }
+    }
+    io.stdout("[create-ailk] Licence key set and production redeployed.\n");
+    return 0;
+}

package/dist/module-architecture.d.ts

@@ -61,6 +61,14 @@ export interface PageRosterRow {
      * (`/meet` renders from the scheduling API, not from an MDX file).
      */
     content?: readonly string[];
+    /**
+     * Scaffold-relative seed DIRECTORY a dynamic detail row serves, e.g.
+     * `content/en/Service` under `/services/[slug]` (#6646 disposition (a)).
+     * `content` names files; a detail route whose seeds are a whole directory
+     * declares the directory instead. Every `.mdx` under it is a declared page,
+     * so it installs; a seed no row names does not.
+     */
+    contentDir?: string;
 }
 /**
  * The architecture fragment one module contributes.
@@ -144,6 +152,8 @@ export interface ModuleSlice {
      * `ownedFiles` names which files in THIS monorepo physically belong to the
      * module; `pageContributions` names which PAGES the module brings to a
      * template's roster. `template-manifest.ts`'s `mergeRoster` reads it.
+     * A row's `contentDir` names seeds a TEMPLATE supplies, not the module:
+     * the module's bundle stages only `content` files (#6646).
      *
      * A contribution never carries route CODE. How the route code reaches a
      * scaffold is a property of the module, not of the contribution (parent
@@ -399,3 +409,13 @@ export declare function normalizeModules(modules: string[]): ModuleName[];
 export declare function coOwnedModuleDestinations(): ReadonlySet<string>;
 export declare const EXCLUDE_TEMPLATE_DIRS: readonly string[];
 export declare function paidModuleTemplateExclusions(snapshotRoots: readonly string[], repoRoot: string): string[];
+/** The scaffold's architecture linter, relative to the site root (#6649). */
+export declare const ARCHITECTURE_LINT_PATH = "tools/lint-architecture.ts";
+/**
+ * What a scaffold needs so its `architecture.yaml` is enforced rather than
+ * declared (#6649): the linter, the `architecture` + `preflight` root scripts
+ * that run it, and a `.claude/settings.json` PostToolUse hook on Edit|Write
+ * that runs it in-session. Returns one line per missing piece — empty means
+ * all present. `verify-scaffold.mjs` fails on a non-empty result.
+ */
+export declare function missingArchitectureEnforcement(siteDir: string): string[];

package/dist/module-architecture.js

@@ -21,7 +21,8 @@
  * `architecture.yaml` template files — a fixed template IS the drift this
  * removes.
  */
-import { sep } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, sep } from "node:path";
 import { importClosure } from "./lib/import-graph.js";
 import { PAID_MODULES } from "./lib/module-tier.js";
 import { RECOGNIZED_MODULES } from "./parse-args.js";
@@ -149,6 +150,15 @@ const ASSET_STORE_FILES = [
     "apps/api/src/routes/assets/manage.ts",
     "apps/api/src/lib/asset-store.ts",
 ];
+/**
+ * The auth-adapter exception (#587 in the AILK repo's own architecture.yaml):
+ * the base apps/web hands Better Auth its Prisma client from
+ * `lib/prisma-for-auth.ts`, whatever modules are selected. Every slice that
+ * contributes `webImports` — and so makes apps/web's allowlist non-empty —
+ * names it, so no module set yields an allowlist the scaffold's own
+ * tools/lint-architecture.ts fails on (#6649).
+ */
+const WEB_AUTH_ADAPTER_IMPORT = "database";
 /**
  * The per-module slices. Authored for every `RECOGNIZED_MODULES` value; only
  * `marketing` (the default) is validated end-to-end against a golden.
@@ -157,6 +167,7 @@ export const MODULE_SLICES = {
     // ── marketing — thin presentation module (the default) ───────────────────
     marketing: {
         webImports: [
+            WEB_AUTH_ADAPTER_IMPORT,
             "packages/content-adapters",
             "packages/jsonld",
             "packages/metadata",
@@ -236,7 +247,7 @@ export const MODULE_SLICES = {
     },
     // ── docs-blog — Pro module: both fumadocs surfaces (D-46) ────────────────
     "docs-blog": {
-        webImports: ["packages/fumadocs-schema"],
+        webImports: [WEB_AUTH_ADAPTER_IMPORT, "packages/fumadocs-schema"],
         packages: {
             "fumadocs-schema": {
                 description: "Fumadocs ↔ schema.org bridge — BlogList / DocsPage JSON-LD from Fumadocs MDX",
@@ -376,7 +387,10 @@ export const MODULE_SLICES = {
                         path: ["scripts"],
                         entries: {
                             prebuild: "fumadocs-mdx",
-                            pretypecheck: "fumadocs-mdx",
+                            // `pretype-check`, not `pretypecheck`: pnpm runs `pre<name>`
+                            // only before a script named `<name>`, and the scaffold's is
+                            // `type-check` (#6680).
+                            "pretype-check": "fumadocs-mdx",
                             pretest: "fumadocs-mdx",
                         },
                     },
@@ -795,7 +809,7 @@ export const MODULE_SLICES = {
         // dependency under `node_modules/`, never as a `packages/admin-ui`
         // source sibling; the `patches` entry below is what puts it in the
         // buyer's apps/web/package.json.
-        webImports: ["packages/admin-ui"],
+        webImports: [WEB_AUTH_ADAPTER_IMPORT, "packages/admin-ui"],
         packages: {
             "admin-ui": {
                 description: "Shared Admin-settings components — the settings shell plus the General / Site / Team panels, presentational only (data + save callbacks as props)",
@@ -892,12 +906,9 @@ export const MODULE_SLICES = {
     // all, and no scheduling value is ever published to the browser as a
     // `NEXT_PUBLIC_` variable.
     //
-    // NOTE — a scaffolded site cannot run these yet. It receives
-    // `architecture.yaml` and a `package.json` whose `architecture` script names
-    // `tools/lint-architecture.ts`, but `build-templates.mjs` snapshots only
-    // `apps/` and `database/`, so `tools/` is absent. The rules are declarative
-    // there until the scaffold ships its linter; they ARE enforced in the AILK
-    // repo, whose own architecture.yaml carries the same four.
+    // A scaffolded site enforces these with its own `tools/lint-architecture.ts`
+    // (template-overlay/, #6649) via `pnpm architecture`; the AILK repo's own
+    // architecture.yaml carries the same four.
     //
     // The `api` block is a VERBATIM copy of multi-tenant's, deliberately. Two
     // reasons: `deriveArchitecture` merges app blocks with `Object.assign`, so
@@ -1434,8 +1445,10 @@ export const MODULE_SLICES = {
             { route: "/flows/[slug]/results/[payload]" },
             // #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.
-            { route: "/reports/[slug]" },
+            // 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).
+            { route: "/reports/[slug]", contentDir: "content/en/ReportPage" },
         ],
         // installMap (#5618 D6.3) — the module's ten sample files, moved here out
         // of `site-templates/marketing-site/` so the module OWNS its samples
@@ -1451,13 +1464,13 @@ export const MODULE_SLICES = {
         //
         // 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
-        // are self-addressed because no `pageContributions` row declares
-        // `/projects`, `/projects/[slug]` or `/thanks/[slug]` yet (spec § 7
-        // finding 7 — declaring them changes the enabled-surface set and so the
-        // Pro scaffold's file set, a separate decision). Once those rows exist
-        // the six move to `pageContributions[].content` with no further
-        // migration. `generate-sample-report.py` keeps its root-level
-        // destination (finding 1 — AC7 forbids changing the Pro file set).
+        // 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).
+        // `generate-sample-report.py` keeps its root-level destination
+        // (finding 1 — AC7 forbids changing the Pro file set).
         installMap: {
             "packages/create-ailk/module-templates/signal-collectors/content/en/ProjectsList/projects.mdx": "content/en/ProjectsList/projects.mdx",
             "packages/create-ailk/module-templates/signal-collectors/content/en/Project/fit-check-funnel.mdx": "content/en/Project/fit-check-funnel.mdx",
@@ -1801,3 +1814,48 @@ export function paidModuleTemplateExclusions(snapshotRoots, repoRoot) {
     // question with the same resolution this answer was computed with (#5701).
     return [...importClosure(repoRoot, [...roots], seeds)].sort();
 }
+/** The scaffold's architecture linter, relative to the site root (#6649). */
+export const ARCHITECTURE_LINT_PATH = "tools/lint-architecture.ts";
+/**
+ * What a scaffold needs so its `architecture.yaml` is enforced rather than
+ * declared (#6649): the linter, the `architecture` + `preflight` root scripts
+ * that run it, and a `.claude/settings.json` PostToolUse hook on Edit|Write
+ * that runs it in-session. Returns one line per missing piece — empty means
+ * all present. `verify-scaffold.mjs` fails on a non-empty result.
+ */
+export function missingArchitectureEnforcement(siteDir) {
+    const missing = [];
+    if (!existsSync(join(siteDir, ARCHITECTURE_LINT_PATH))) {
+        missing.push(ARCHITECTURE_LINT_PATH);
+    }
+    const readJson = (rel) => {
+        const p = join(siteDir, rel);
+        if (!existsSync(p))
+            return undefined;
+        try {
+            return JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const scripts = readJson("package.json")
+        ?.scripts ?? {};
+    if (!scripts.architecture?.includes(ARCHITECTURE_LINT_PATH)) {
+        missing.push(`package.json scripts.architecture (runs ${ARCHITECTURE_LINT_PATH})`);
+    }
+    if (!scripts.preflight?.includes("pnpm architecture")) {
+        missing.push("package.json scripts.preflight (runs pnpm architecture)");
+    }
+    const postToolUse = readJson(".claude/settings.json")?.hooks?.PostToolUse ?? [];
+    const hooked = postToolUse.some((entry) => {
+        const tools = (entry.matcher ?? "").split("|");
+        return (tools.includes("Edit") &&
+            tools.includes("Write") &&
+            (entry.hooks ?? []).some((h) => /\bpnpm\b.*\barchitecture\b/.test(h.command ?? "")));
+    });
+    if (!hooked) {
+        missing.push(".claude/settings.json PostToolUse hook on Edit|Write (runs pnpm architecture)");
+    }
+    return missing;
+}

package/dist/parse-args.d.ts

@@ -47,6 +47,13 @@ export interface CliOptions {
      *  value is validated through `parseModules` at parse time; cli.ts re-parses
      *  it to the module list. Undefined when the flag is absent (scaffold mode). */
     syncArchitecture: string | undefined;
+    /**
+     * The licence key (`--license <key>`, #6683 D9), shape-checked at parse
+     * time. When set, `scaffold()` fetches paid bundles with it and writes it
+     * into the new scaffold (`ailk.key` + `apps/api/.env`). Absent when the
+     * flag is.
+     */
+    license?: string;
 }
 export declare class ParseError extends Error {
     constructor(message: string);

package/dist/parse-args.js

@@ -8,6 +8,7 @@
  * top-level catch turns this into a stderr write + non-zero exit.
  */
 import { parseArgs } from "node:util";
+import { assertLicenseKeyShape } from "./lib/license-key-files.js";
 import { RECOGNIZED_SURFACES, parseSurfaces } from "./surfaces.js";
 import { RECOGNIZED_TEMPLATES } from "./template-names.js";
 /**
@@ -73,7 +74,7 @@ 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 \`scaffold-page\`
+                           content. Add one later with the \`add-page\`
                            skill, 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
@@ -93,6 +94,9 @@ 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.
+  --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).
   --install                After scaffolding, run \`pnpm install\` in the
                            target directory. Off by default.
   --help, -h               Print this message.
@@ -119,6 +123,7 @@ export function parseCliArgs(argv) {
             options: {
                 modules: { type: "string" },
                 template: { type: "string" },
+                license: { type: "string" },
                 surfaces: { type: "string" },
                 "sync-architecture": { type: "string" },
                 "sync-catalog": { type: "boolean", default: false },
@@ -141,6 +146,7 @@ export function parseCliArgs(argv) {
     const syncArchitecture = parsed.values["sync-architecture"];
     const syncCatalog = parsed.values["sync-catalog"] === 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) {
@@ -202,8 +208,24 @@ export function parseCliArgs(argv) {
         syncCatalog,
         withCatalog,
         syncArchitecture: undefined,
+        ...(license !== undefined ? { license } : {}),
     };
 }
+/**
+ * Shape-check the `--license` value through the one validator `license set`
+ * also uses, re-thrown as a ParseError. The message never repeats the value.
+ */
+function parseLicense(raw) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        assertLicenseKeyShape(raw);
+    }
+    catch (err) {
+        throw new ParseError(`--license: ${err.message}`);
+    }
+    return raw;
+}
 /**
  * Validate the `--template` value against the declared template set
  * (spec 5481 § 3 DD1).

package/dist/programmatic.d.ts

@@ -15,10 +15,12 @@
  *   import { scaffoldSync } from './programmatic.js';
  *   const result = scaffoldSync({ targetDir: '/tmp/my-site', projectName: 'my-site' });
  */
+import { type AddModuleResult } from "./add-module.js";
 import { CATALOG_TARGET_PATH } from "./component-catalog.js";
 import { type ModuleName } from "./parse-args.js";
 import { type TemplateLayout } from "./site-chrome.js";
 import { type SyncRoutesResult } from "./sync-routes.js";
+import { type StarterDesign } from "./template-manifest.js";
 export interface ScaffoldOptions {
     /** Absolute or relative path to the target directory. Must not exist or be empty. */
     targetDir: string;
@@ -84,6 +86,14 @@ export interface ScaffoldOptions {
      * bare/all-Free scaffold reads neither).
      */
     licenseKey?: string;
+    /**
+     * The buyer's licence key (`--license`, #6683 D9). Takes precedence over
+     * `licenseKey` and `AILK_LICENSE_KEY` for bundle fetches, and — unlike
+     * them — is PERSISTED: after a successful scaffold it is written to the
+     * target's `ailk.key` and `apps/api/.env` (`writeLicenseKeyFiles`). Unset,
+     * the scaffold is byte-identical to one made before the option existed.
+     */
+    license?: string;
     /** Overrides `AILK_MODULE_REGISTRY_URL` / the built-in module-distribution default. */
     moduleRegistryUrl?: string;
     /** Overrides `AILK_TEMPLATE_REGISTRY_URL` / the built-in template-distribution default. */
@@ -99,6 +109,15 @@ export interface ScaffoldOptions {
      * caller) writes the same defaults `site-chrome.ts` always has.
      */
     layout?: TemplateLayout;
+    /**
+     * The design whose layout knobs fill what `layout` leaves unset (#6638,
+     * `DESIGN_LAYOUTS`). `scaffold()` sets it from the resolved template's
+     * `design`; a caller may name one to OVERRIDE the template's — the CI-only
+     * shape × design pairing `verify-scaffold.mjs --design` renders (#6638
+     * DD-4). No CLI flag sets it. Unset (every existing `scaffoldSync` caller)
+     * resolves exactly as before.
+     */
+    design?: StarterDesign;
 }
 export interface ScaffoldResult {
     /** Resolved absolute path to the scaffolded directory. */
@@ -233,6 +252,33 @@ export interface SyncRoutesSyncOptions {
 export declare function syncRoutesSync(opts: SyncRoutesSyncOptions): SyncRoutesResult;
 /** Re-exported beside the other sync results so consumers see one surface. */
 export type { RouteReport, SyncRoutesResult } from "./sync-routes.js";
+export interface AddModuleOptions {
+    /** The already-scaffolded site (absolute or relative). */
+    targetDir: string;
+    /** The module to add (validated upstream by `parseAddModuleArgs`). */
+    moduleName: ModuleName;
+    /** Defaults to `process.env["AILK_LICENSE_KEY"]`, as for `scaffold()`. */
+    licenseKey?: string;
+    /** Defaults to `AILK_MODULE_REGISTRY_URL` / the built-in default. */
+    moduleRegistryUrl?: string;
+    /** Defaults to `globalThis.fetch`. Never a live call in tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Apply a purchased module to an already-scaffolded site in place
+ * (`create-ailk add-module`, #6653). The thin package-rooted wrapper around
+ * `add-module.ts`'s `applyModuleToScaffold`, the `syncRoutesSync` split:
+ *
+ *   1. the target must be an existing scaffold — the same check as the sync
+ *      subcommands above;
+ *   2. a free module is refused before any key read or network call — it
+ *      ships with every scaffold, there is no bundle to add;
+ *   3. `resolvePaidModules` — the SAME gate `scaffold()` runs, so a missing
+ *      key or a key that does not cover the module is refused with the
+ *      scaffold-time message, before anything is written;
+ *   4. the fetched bundle is merged under the plus-config policy.
+ */
+export declare function addModule(opts: AddModuleOptions): Promise<AddModuleResult>;
 /** Re-exported so the CLI can name the file it wrote without duplicating it. */
 export { CATALOG_TARGET_PATH };
 /**