create-ailk 0.1.0 → 0.2.0

package/dist/parse-args.d.ts

@@ -1,3 +1,14 @@
+/**
+ * The recognized module vocabulary for the `--modules` selector.
+ *
+ * A MODULE is a composable, potentially full-stack unit AILK's three-tier app
+ * is composed from (see architecture.yaml `composition_model`). At the MVP
+ * plumbing layer only the selection is threaded through; per-module template
+ * composition is downstream work, so the default (`marketing`) reproduces
+ * today's fixed-tree scaffold exactly.
+ */
+export declare const RECOGNIZED_MODULES: readonly ["marketing", "docs", "multi-tenant", "scheduling"];
+export type ModuleName = (typeof RECOGNIZED_MODULES)[number];
 export interface CliOptions {
     /** Positional target directory (the dir to scaffold into). Optional only
      *  when `help` or `version` is set. */
@@ -5,9 +16,44 @@ export interface CliOptions {
     install: boolean;
     help: boolean;
     version: boolean;
+    /** Selected modules (recognized: marketing, docs, multi-tenant, scheduling).
+     *  Defaults to ['marketing'] when the flag is absent. */
+    modules: string[];
+    /** Explicitly requested route surfaces (`--surfaces`). Empty when the flag is
+     *  absent — the module set alone then decides (see surfaces.ts
+     *  `resolveSurfaces`). Validated, lowercased, deduped and sorted. */
+    surfaces: string[];
+    /**
+     * When set, regenerate the target's COMPONENT-CATALOG.md in place from the
+     * catalog this create-ailk ships (catalog-sync mode) and exit. Mirrors
+     * `--sync-architecture`: data-only, one file, an already-scaffolded target.
+     */
+    syncCatalog: 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
+     * pre-#4636 output.
+     */
+    withCatalog: boolean;
+    /** When set, the raw `--sync-architecture <csv>` value: regenerate the
+     *  target's architecture.yaml in place from this module set (sync mode). The
+     *  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;
 }
 export declare class ParseError extends Error {
     constructor(message: string);
 }
-export declare const helpText = "create-ailk \u2014 scaffold a new AI Launch Kit site.\n\nUsage:\n  pnpm create ailk@latest <target-dir> [options]\n  npx create-ailk <target-dir> [options]\n\nArguments:\n  <target-dir>             The directory to scaffold into. Must not exist OR\n                           must be empty. Path-traversal segments (..) are\n                           rejected.\n\nOptions:\n  --install                After scaffolding, run `pnpm install` in the\n                           target directory. Off by default.\n  --help, -h               Print this message.\n  --version                Print the scaffolder version.\n\nExamples:\n  pnpm create ailk@latest my-site\n  pnpm create ailk@latest /tmp/test-site --install\n\nNext steps after a successful scaffold:\n  cd <target-dir>\n  pnpm install\n  pnpm dev\n\nReference: ADR 0007 \u2014 `pnpm create ailk@latest` is the canonical install path.\n";
+export declare const helpText: string;
 export declare function parseCliArgs(argv: string[]): CliOptions;
+/**
+ * Parse a module CSV (the `--modules` or `--sync-architecture` value) into a
+ * validated, normalized string[].
+ *
+ * Splits on `,`, trims and lowercases each entry, drops empties, and validates
+ * each against RECOGNIZED_MODULES. An absent flag (or an all-empty value)
+ * defaults to DEFAULT_MODULES (`['marketing']`) — reproducing today's scaffold.
+ *
+ * @throws ParseError on an unrecognized module value, naming the recognized set.
+ */
+export declare function parseModules(raw: string | undefined): string[];

package/dist/parse-args.js

@@ -8,6 +8,24 @@
  * top-level catch turns this into a stderr write + non-zero exit.
  */
 import { parseArgs } from "node:util";
+import { RECOGNIZED_SURFACES, parseSurfaces } from "./surfaces.js";
+/**
+ * The recognized module vocabulary for the `--modules` selector.
+ *
+ * A MODULE is a composable, potentially full-stack unit AILK's three-tier app
+ * is composed from (see architecture.yaml `composition_model`). At the MVP
+ * plumbing layer only the selection is threaded through; per-module template
+ * composition is downstream work, so the default (`marketing`) reproduces
+ * today's fixed-tree scaffold exactly.
+ */
+export const RECOGNIZED_MODULES = [
+    "marketing",
+    "docs",
+    "multi-tenant",
+    "scheduling",
+];
+/** The default module selection when `--modules` is absent (reproduces today's scaffold). */
+const DEFAULT_MODULES = ["marketing"];
 export class ParseError extends Error {
     constructor(message) {
         super(message);
@@ -26,6 +44,37 @@ Arguments:
                            rejected.
 
 Options:
+  --modules <csv>          Comma-separated list of modules to compose the site
+                           from (recognized: ${RECOGNIZED_MODULES.join(", ")}).
+                           Defaults to \`marketing\`, which reproduces today's
+                           scaffold. A module is a composable unit across the
+                           three tiers (data · API · presentation).
+  --surfaces <csv>         Comma-separated route surfaces to scaffold IN
+                           ADDITION to the core set (/, /about, /contact, /faq,
+                           /thanks). Recognized: ${RECOGNIZED_SURFACES.join(", ")}.
+                           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\`
+                           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
+                           (recognized: ${RECOGNIZED_MODULES.join(", ")}), then
+                           exit. Data-only: rewrites only architecture.yaml, at
+                           the target dir (positional arg, else cwd). Bypasses
+                           the scaffold path — copies no template, runs no
+                           install.
+  --with-catalog           Also write COMPONENT-CATALOG.md — the capability-
+                           indexed index of every @working-theory/ui component,
+                           so a worker in the scaffolded repo can check what
+                           already exists before building it. Off by default; a
+                           scaffold without it is unchanged.
+  --sync-catalog           Refresh COMPONENT-CATALOG.md in place in an already-
+                           scaffolded repo from the catalog this create-ailk
+                           ships, then exit. Data-only: rewrites only that one
+                           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.
   --install                After scaffolding, run \`pnpm install\` in the
                            target directory. Off by default.
   --help, -h               Print this message.
@@ -50,6 +99,11 @@ export function parseCliArgs(argv) {
             strict: true,
             allowPositionals: true,
             options: {
+                modules: { type: "string" },
+                surfaces: { type: "string" },
+                "sync-architecture": { type: "string" },
+                "sync-catalog": { type: "boolean", default: false },
+                "with-catalog": { type: "boolean", default: false },
                 install: { type: "boolean", default: false },
                 help: { type: "boolean", default: false, short: "h" },
                 version: { type: "boolean", default: false },
@@ -62,9 +116,52 @@ export function parseCliArgs(argv) {
     const help = parsed.values.help === true;
     const version = parsed.values.version === true;
     const install = parsed.values.install === true;
-    // When help or version is set, target is optional.
+    const modules = parseModules(parsed.values.modules);
+    const surfaces = parseSurfaceList(parsed.values.surfaces);
+    const syncArchitecture = parsed.values["sync-architecture"];
+    const syncCatalog = parsed.values["sync-catalog"] === true;
+    const withCatalog = parsed.values["with-catalog"] === true;
+    // 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");
+    }
+    // Validate the sync-architecture value now, through the SAME parseModules
+    // path `--modules` uses, so an unknown module throws ParseError at parse time
+    // (cli.ts re-parses the raw value to the module list in sync mode).
+    if (syncArchitecture !== undefined) {
+        parseModules(syncArchitecture);
+    }
+    // When help or version is set, target is optional (help/version win).
     if (help || version) {
-        return { target: undefined, install, help, version };
+        return {
+            target: undefined,
+            install,
+            help,
+            version,
+            modules,
+            surfaces,
+            syncCatalog: false,
+            withCatalog: false,
+            syncArchitecture: undefined,
+        };
+    }
+    // Sync modes: the target dir is optional (positional if given, else cwd).
+    if (syncArchitecture !== undefined || syncCatalog) {
+        if (parsed.positionals.length > 1) {
+            throw new ParseError(`expected at most one target directory, got ${parsed.positionals.length}`);
+        }
+        return {
+            target: parsed.positionals[0],
+            install,
+            help,
+            version,
+            modules,
+            surfaces,
+            syncCatalog,
+            withCatalog,
+            syncArchitecture,
+        };
     }
     if (parsed.positionals.length === 0) {
         throw new ParseError("missing target directory. Usage: pnpm create ailk@latest <target-dir>");
@@ -77,5 +174,49 @@ export function parseCliArgs(argv) {
         install,
         help,
         version,
+        modules,
+        surfaces,
+        syncCatalog,
+        withCatalog,
+        syncArchitecture: undefined,
     };
 }
+/**
+ * Parse + validate the `--surfaces` CSV, re-throwing an unrecognized-surface
+ * failure as a ParseError so every CLI parse failure reaches the orchestrator's
+ * top-level catch through ONE error type.
+ */
+function parseSurfaceList(raw) {
+    try {
+        return parseSurfaces(raw);
+    }
+    catch (err) {
+        throw new ParseError(err.message);
+    }
+}
+/**
+ * Parse a module CSV (the `--modules` or `--sync-architecture` value) into a
+ * validated, normalized string[].
+ *
+ * Splits on `,`, trims and lowercases each entry, drops empties, and validates
+ * each against RECOGNIZED_MODULES. An absent flag (or an all-empty value)
+ * defaults to DEFAULT_MODULES (`['marketing']`) — reproducing today's scaffold.
+ *
+ * @throws ParseError on an unrecognized module value, naming the recognized set.
+ */
+export function parseModules(raw) {
+    if (raw === undefined)
+        return [...DEFAULT_MODULES];
+    const requested = raw
+        .split(",")
+        .map((m) => m.trim().toLowerCase())
+        .filter(Boolean);
+    if (requested.length === 0)
+        return [...DEFAULT_MODULES];
+    for (const m of requested) {
+        if (!RECOGNIZED_MODULES.includes(m)) {
+            throw new ParseError(`unknown module "${m}". Recognized: ${RECOGNIZED_MODULES.join(", ")}`);
+        }
+    }
+    return requested;
+}

package/dist/programmatic.d.ts

@@ -15,6 +15,9 @@
  *   import { scaffoldSync } from './programmatic.js';
  *   const result = scaffoldSync({ targetDir: '/tmp/my-site', projectName: 'my-site' });
  */
+import { CATALOG_TARGET_PATH } from "./component-catalog.js";
+import { type ModuleName } from "./parse-args.js";
+import { type SyncRoutesResult } from "./sync-routes.js";
 export interface ScaffoldOptions {
     /** Absolute or relative path to the target directory. Must not exist or be empty. */
     targetDir: string;
@@ -25,12 +28,57 @@ export interface ScaffoldOptions {
      * Ignored at runtime until named presets are implemented.
      */
     preset?: string;
+    /**
+     * Selected modules (recognized: marketing, docs, multi-tenant). Defaults to
+     * ['marketing']. The scaffolder does NOT yet vary the copied template tree by
+     * module (per-module template composition is downstream work), so the copied
+     * files are today's fixed-tree scaffold — BUT the derived `architecture.yaml`
+     * (its code-boundary config) IS a function of this set (spec #3787), written
+     * at the target root after the template copy.
+     *
+     * As of #4154 the module set ALSO selects route surfaces (via
+     * `surfaces.ts` `MODULE_SURFACES`), so the copied tree is no longer
+     * module-invariant: a surface no module carries is not scaffolded at all.
+     */
+    modules?: string[];
+    /**
+     * Route surfaces to scaffold IN ADDITION to the core set (`--surfaces`).
+     * Omitted ⟹ the module set alone decides. Every gateable surface not in the
+     * resolved set has its route directories skipped by the copy, so its routes
+     * are ABSENT from the output rather than serving placeholder content (#4154).
+     */
+    surfaces?: string[];
+    /**
+     * Also write COMPONENT-CATALOG.md at the target root (`--with-catalog`).
+     * Defaults to false: a scaffold that does not ask for the catalog produces
+     * byte-identical output to the pre-#4636 scaffolder.
+     */
+    withCatalog?: boolean;
+    /**
+     * Licensed module delivery (K1, #5089 — Flavor 3). Consumed ONLY by the
+     * async `scaffold()` below — `scaffoldSync` remains oblivious to licensing
+     * entirely, so every existing synchronous caller (the vast majority of this
+     * package's own tests) is untouched by this card.
+     *
+     * `licenseKey` defaults to `process.env["AILK_LICENSE_KEY"]`; `fetchImpl`
+     * defaults to `globalThis.fetch` (injectable so tests — and this repo's own
+     * evidence runs — never make a live network call). Both are ignored
+     * entirely when `modules` names no paid module (the regression floor: a
+     * bare/all-Free scaffold reads neither).
+     */
+    licenseKey?: string;
+    /** Overrides `AILK_MODULE_REGISTRY_URL` / the built-in module-distribution default. */
+    moduleRegistryUrl?: string;
+    /** Injected fetch for tests. Never a live network call in CI or in this repo's evidence runs. */
+    fetchImpl?: typeof fetch;
 }
 export interface ScaffoldResult {
     /** Resolved absolute path to the scaffolded directory. */
     targetDir: string;
     /** Number of files written. */
     filesCreated: number;
+    /** The gateable route surfaces this scaffold declares (sorted). */
+    surfaces: string[];
 }
 /**
  * Scaffold an AI Launch Kit starter project into targetDir (synchronous).
@@ -42,8 +90,117 @@ export declare function scaffoldSync(opts: ScaffoldOptions): ScaffoldResult;
 /**
  * Scaffold an AI Launch Kit starter project into targetDir (async wrapper).
  *
- * Wraps scaffoldSync for callers that prefer Promise-based APIs. The
- * underlying I/O is synchronous; the async signature is provided for
- * compatibility with async callers (e.g. the MCP tool handler via subprocess).
+ * The ONLY entry point that resolves paid modules (K1, #5089 — Flavor 3):
+ *
+ *   1. Classify the requested module set into free / paid (`module-tier.ts`).
+ *   2. `resolvePaidModules` — zero-paid-modules returns instantly with no key
+ *      read and no network call (the regression floor). A paid module with
+ *      no key, or a licence the module distribution rejects, throws
+ *      `LicenseRequiredError` HERE — before anything is written to disk.
+ *   3. `scaffoldSync` — unchanged, today's local `templates/` copy.
+ *   4. Merge each resolved paid module's fetched bundle into the freshly
+ *      scaffolded tree (`extractModuleBundle`).
+ *
+ * `scaffoldSync` itself stays licensing-oblivious on purpose: every existing
+ * synchronous caller (this package's own test suite, overwhelmingly) is
+ * unaffected by this card — only a caller that goes through THIS function
+ * with a paid module in `opts.modules` exercises the gate at all.
  */
 export declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;
+export { LicenseRequiredError, type ResolvePaidModulesOptions, } from "./lib/module-license-gate.js";
+export { FREE_MODULES, PAID_MODULES, classifyModules } from "./lib/module-tier.js";
+export type { ModuleName };
+export interface SyncArchitectureOptions {
+    /**
+     * The already-scaffolded repo to sync (absolute or relative). It MUST exist
+     * and contain an `architecture.yaml` — the inverse of scaffold's empty-target
+     * rule (spec D3), so this path does NOT reuse `validateTarget`.
+     */
+    targetDir: string;
+    /** The module set to regenerate architecture.yaml from (validated upstream). */
+    modules: string[];
+    /** Route surfaces to declare in addition to the module-derived set (#4154). */
+    surfaces?: string[];
+}
+export interface SyncArchitectureResult {
+    /** Resolved absolute path to the synced directory. */
+    targetDir: string;
+    /** The gateable route surfaces the regenerated architecture.yaml declares. */
+    surfaces: string[];
+    /**
+     * Surface drift — route and content directories that EXIST in the target but
+     * belong to a surface the regenerated declaration does not carry. Reported,
+     * never removed: deleting files in an already-scaffolded repo is the
+     * operator's call, made as one reviewable commit (spec #4154 D5). Repo-
+     * relative, sorted.
+     */
+    undeclared: string[];
+}
+/**
+ * Regenerate an already-scaffolded repo's `architecture.yaml` in place from a
+ * module set (the "module added later" sync path — spec #3561).
+ *
+ * Mirrors scaffoldSync's architecture-write step MINUS the template copy: it
+ * overwrites exactly the one `architecture.yaml` file at the target root via
+ * the shipped, byte-deterministic `deriveArchitecture`, so a synced repo's
+ * config is identical to a fresh scaffold's for the same module set. Data-only
+ * and non-destructive: no template re-copy, no subprocess, no other file
+ * touched.
+ *
+ * Validates the target is an EXISTING scaffolded dir (an existing directory
+ * containing `architecture.yaml`) — the inverse of `validateTarget` (D3).
+ * Throws Error on a missing target, a non-directory target, or a directory with
+ * no `architecture.yaml`; the CLI's top-level catch turns that into a
+ * `[create-ailk] <message>` stderr write + exit 1.
+ */
+export declare function syncArchitectureSync(opts: SyncArchitectureOptions): SyncArchitectureResult;
+export interface SyncCatalogResult {
+    /** Resolved absolute path to the synced directory. */
+    targetDir: string;
+    /** Absolute path of the file written. */
+    catalogPath: string;
+}
+/**
+ * Refresh an already-scaffolded repo's `COMPONENT-CATALOG.md` in place from the
+ * catalog this create-ailk ships (#4636).
+ *
+ * The same shape as `syncArchitectureSync`, with a different artifact: validate
+ * the target is an existing scaffolded dir, overwrite exactly one file, touch
+ * nothing else, spawn nothing. The catalog is regenerated from `packages/ui` at
+ * publish time, so re-running this after upgrading create-ailk is how a site
+ * picks up components added since it was scaffolded.
+ */
+export declare function syncCatalogSync(opts: {
+    targetDir: string;
+}): SyncCatalogResult;
+export interface SyncRoutesSyncOptions {
+    /** The already-scaffolded repo to sync (absolute or relative). */
+    targetDir: string;
+    /** Copy the missing route directories in. Default false = check only. */
+    apply?: boolean;
+}
+/**
+ * Compare an already-scaffolded repo's route tree with the template this
+ * create-ailk ships and, with `apply`, copy in the route dirs it is missing
+ * (`create-ailk sync-routes`, #4986).
+ *
+ * The same shape as `syncArchitectureSync` / `syncCatalogSync`: validate the
+ * target is an existing scaffolded dir, spawn nothing, touch nothing else. The
+ * one difference is what it writes — not a regenerated file but the ABSENT
+ * route directories, copied through the scaffold's own `copyTemplate` with the
+ * scaffold's own markers, so a synced route is byte-identical to a fresh
+ * scaffold's. No other template file is re-copied; a route the site changed is
+ * reported and left as-is; nothing is deleted. The logic lives in
+ * `sync-routes.ts` (a pure module jest imports directly); this wrapper only
+ * supplies the package's `templates/` dir and version map.
+ */
+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";
+/** Re-exported so the CLI can name the file it wrote without duplicating it. */
+export { CATALOG_TARGET_PATH };
+/**
+ * Render the surface-drift report the CLI prints after a sync run. Returns an
+ * empty string when there is no drift, so the caller can skip the write.
+ */
+export declare function formatSurfaceDrift(undeclared: string[]): string;

package/dist/programmatic.js

@@ -15,10 +15,18 @@
  *   import { scaffoldSync } from './programmatic.js';
  *   const result = scaffoldSync({ targetDir: '/tmp/my-site', projectName: 'my-site' });
  */
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CATALOG_TARGET_PATH, writeComponentCatalog, } from "./component-catalog.js";
 import { copyTemplate } from "./copy.js";
+import { deriveArchitecture } from "./derive-architecture.js";
+import { extractModuleBundle } from "./lib/extract-module-bundle.js";
+import { resolvePaidModules } from "./lib/module-license-gate.js";
+import { classifyModules } from "./lib/module-tier.js";
+import { normalizeModules } from "./module-architecture.js";
+import { NAV_CONFIG_PATH, excludedRoutePaths, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
+import { syncRoutes } from "./sync-routes.js";
 import { validateTarget } from "./validate.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATES_DIR = resolve(PKG_ROOT, "templates");
@@ -63,27 +71,208 @@ export function scaffoldSync(opts) {
     // Validate target — throws ValidationError on rejection.
     const targetAbs = validateTarget(opts.targetDir);
     const projectName = opts.projectName ?? basename(targetAbs);
+    // The declared route surface (#4154). Resolved BEFORE the copy: it decides
+    // both which route directories are skipped and what architecture.yaml records.
+    const enabledSurfaces = resolveSurfaces(opts.modules ?? ["marketing"], opts.surfaces ?? []);
     const versions = readVersionMap();
     copyTemplate({
         templatesDir: TEMPLATES_DIR,
         targetDir: targetAbs,
         versions,
+        excludePaths: excludedRoutePaths(enabledSurfaces),
         markers: {
             PROJECT_NAME: projectName,
             COMPANY_NAME: "Your Company",
             COMPANY_DOMAIN: "example.com",
         },
     });
+    // Derive + write the module-set-driven architecture.yaml (spec #3787). This
+    // is the single source of the scaffolded site's code-boundary config and
+    // closes the dangling `architecture_rules: architecture.yaml` reference in
+    // the scaffolded project.yaml. Written AFTER the template copy, at the target
+    // root — a deterministic function of the selected module set.
+    writeFileSync(join(targetAbs, "architecture.yaml"), deriveArchitecture(opts.modules ?? ["marketing"], enabledSurfaces));
+    // Regenerate the site nav from the same surface set (#4154). The nav is a
+    // static list the layout renders into the header AND the footer, so leaving
+    // the template's copy in place would link /docs and /blog sitewide in a
+    // scaffold that carries neither route.
+    writeFileSync(join(targetAbs, NAV_CONFIG_PATH), renderNavConfig(enabledSurfaces));
+    // Opt-in only (#4636). Every write above this line is unconditional, so a
+    // scaffold with `withCatalog` unset touches exactly the files it did before.
+    if (opts.withCatalog === true)
+        writeComponentCatalog(targetAbs);
     const filesCreated = countFiles(targetAbs);
-    return { targetDir: targetAbs, filesCreated };
+    return { targetDir: targetAbs, filesCreated, surfaces: enabledSurfaces };
 }
 /**
  * Scaffold an AI Launch Kit starter project into targetDir (async wrapper).
  *
- * Wraps scaffoldSync for callers that prefer Promise-based APIs. The
- * underlying I/O is synchronous; the async signature is provided for
- * compatibility with async callers (e.g. the MCP tool handler via subprocess).
+ * The ONLY entry point that resolves paid modules (K1, #5089 — Flavor 3):
+ *
+ *   1. Classify the requested module set into free / paid (`module-tier.ts`).
+ *   2. `resolvePaidModules` — zero-paid-modules returns instantly with no key
+ *      read and no network call (the regression floor). A paid module with
+ *      no key, or a licence the module distribution rejects, throws
+ *      `LicenseRequiredError` HERE — before anything is written to disk.
+ *   3. `scaffoldSync` — unchanged, today's local `templates/` copy.
+ *   4. Merge each resolved paid module's fetched bundle into the freshly
+ *      scaffolded tree (`extractModuleBundle`).
+ *
+ * `scaffoldSync` itself stays licensing-oblivious on purpose: every existing
+ * synchronous caller (this package's own test suite, overwhelmingly) is
+ * unaffected by this card — only a caller that goes through THIS function
+ * with a paid module in `opts.modules` exercises the gate at all.
  */
 export async function scaffold(opts) {
-    return scaffoldSync(opts);
+    const { paid } = classifyModules(normalizeModules(opts.modules ?? ["marketing"]));
+    const bundles = await resolvePaidModules({
+        paidModules: paid,
+        licenseKey: opts.licenseKey,
+        ...(opts.moduleRegistryUrl !== undefined
+            ? { registryUrl: opts.moduleRegistryUrl }
+            : {}),
+        ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    const result = scaffoldSync(opts);
+    for (const [moduleName, bytes] of bundles) {
+        await extractModuleBundle({
+            bytes,
+            targetDir: result.targetDir,
+            moduleName,
+        });
+    }
+    return result;
+}
+// Re-exported so a consumer of the async `scaffold()` above can type its own
+// wrapper (e.g. the MCP scaffold-site tool) without reaching into `lib/`.
+export { LicenseRequiredError, } from "./lib/module-license-gate.js";
+export { FREE_MODULES, PAID_MODULES, classifyModules } from "./lib/module-tier.js";
+/**
+ * Regenerate an already-scaffolded repo's `architecture.yaml` in place from a
+ * module set (the "module added later" sync path — spec #3561).
+ *
+ * Mirrors scaffoldSync's architecture-write step MINUS the template copy: it
+ * overwrites exactly the one `architecture.yaml` file at the target root via
+ * the shipped, byte-deterministic `deriveArchitecture`, so a synced repo's
+ * config is identical to a fresh scaffold's for the same module set. Data-only
+ * and non-destructive: no template re-copy, no subprocess, no other file
+ * touched.
+ *
+ * Validates the target is an EXISTING scaffolded dir (an existing directory
+ * containing `architecture.yaml`) — the inverse of `validateTarget` (D3).
+ * Throws Error on a missing target, a non-directory target, or a directory with
+ * no `architecture.yaml`; the CLI's top-level catch turns that into a
+ * `[create-ailk] <message>` stderr write + exit 1.
+ */
+export function syncArchitectureSync(opts) {
+    const targetAbs = resolve(opts.targetDir);
+    if (!existsSync(targetAbs)) {
+        throw new Error(`sync target does not exist: ${targetAbs}. Point --sync-architecture at an already-scaffolded repo.`);
+    }
+    if (!statSync(targetAbs).isDirectory()) {
+        throw new Error(`sync target is not a directory: ${targetAbs}`);
+    }
+    const archPath = join(targetAbs, "architecture.yaml");
+    if (!existsSync(archPath)) {
+        throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
+    }
+    const enabledSurfaces = resolveSurfaces(opts.modules, opts.surfaces ?? []);
+    writeFileSync(archPath, deriveArchitecture(opts.modules, enabledSurfaces));
+    return {
+        targetDir: targetAbs,
+        surfaces: enabledSurfaces,
+        undeclared: findUndeclaredSurfacePaths(targetAbs, enabledSurfaces),
+    };
+}
+/**
+ * List the ROUTE directories present in an already-scaffolded repo that belong
+ * to a gateable surface the given declaration does not carry.
+ *
+ * This is the adoption path for a site scaffolded before #4154 (spec D5): the
+ * sync run declares what the site actually has, then names what is left over so
+ * the operator can remove it in one reviewable commit. It is READ-ONLY — it
+ * stats paths and returns strings, and never writes or deletes.
+ *
+ * Routes only, deliberately. A surface's content directories are informational
+ * (`Surface.content`), not drift: `apps/web/content/<locale>/{blog,docs}` must
+ * exist in EVERY scaffold — `source.config.ts` resolves those paths at build
+ * time whether or not the route is mounted — so sweeping content here would
+ * tell every operator to delete directories the build requires.
+ */
+function findUndeclaredSurfacePaths(targetAbs, enabled) {
+    return excludedRoutePaths(enabled)
+        .filter((rel) => existsSync(join(targetAbs, rel)))
+        .sort();
+}
+/**
+ * Refresh an already-scaffolded repo's `COMPONENT-CATALOG.md` in place from the
+ * catalog this create-ailk ships (#4636).
+ *
+ * The same shape as `syncArchitectureSync`, with a different artifact: validate
+ * the target is an existing scaffolded dir, overwrite exactly one file, touch
+ * nothing else, spawn nothing. The catalog is regenerated from `packages/ui` at
+ * publish time, so re-running this after upgrading create-ailk is how a site
+ * picks up components added since it was scaffolded.
+ */
+export function syncCatalogSync(opts) {
+    const targetAbs = resolve(opts.targetDir);
+    if (!existsSync(targetAbs)) {
+        throw new Error(`sync target does not exist: ${targetAbs}. Point --sync-catalog at an already-scaffolded repo.`);
+    }
+    if (!statSync(targetAbs).isDirectory()) {
+        throw new Error(`sync target is not a directory: ${targetAbs}`);
+    }
+    if (!existsSync(join(targetAbs, "architecture.yaml"))) {
+        throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
+    }
+    return {
+        targetDir: targetAbs,
+        catalogPath: writeComponentCatalog(targetAbs),
+    };
+}
+/**
+ * Compare an already-scaffolded repo's route tree with the template this
+ * create-ailk ships and, with `apply`, copy in the route dirs it is missing
+ * (`create-ailk sync-routes`, #4986).
+ *
+ * The same shape as `syncArchitectureSync` / `syncCatalogSync`: validate the
+ * target is an existing scaffolded dir, spawn nothing, touch nothing else. The
+ * one difference is what it writes — not a regenerated file but the ABSENT
+ * route directories, copied through the scaffold's own `copyTemplate` with the
+ * scaffold's own markers, so a synced route is byte-identical to a fresh
+ * scaffold's. No other template file is re-copied; a route the site changed is
+ * reported and left as-is; nothing is deleted. The logic lives in
+ * `sync-routes.ts` (a pure module jest imports directly); this wrapper only
+ * supplies the package's `templates/` dir and version map.
+ */
+export function syncRoutesSync(opts) {
+    return syncRoutes({
+        ...opts,
+        templatesDir: TEMPLATES_DIR,
+        versions: readVersionMap(),
+    });
+}
+/** Re-exported so the CLI can name the file it wrote without duplicating it. */
+export { CATALOG_TARGET_PATH };
+/**
+ * Render the surface-drift report the CLI prints after a sync run. Returns an
+ * empty string when there is no drift, so the caller can skip the write.
+ */
+export function formatSurfaceDrift(undeclared) {
+    if (undeclared.length === 0)
+        return "";
+    const lines = [
+        "",
+        `[create-ailk] ${undeclared.length} path(s) belong to route surfaces this architecture.yaml does not declare:`,
+        ...undeclared.map((p) => `  ${p}`),
+        "",
+        "These are NOT removed automatically. Either declare the surface",
+        "(re-run with --surfaces <id>) or delete the paths above — a scaffolded",
+        "site that keeps them serves routes its declared architecture does not carry.",
+        "",
+        "Content that fed those routes may be orphaned too: content whose route is",
+        "gone still appears in /sitemap.xml and /llms.txt, advertising URLs that 404.",
+        "",
+    ];
+    return lines.join("\n");
 }