create-ailk 0.3.0 → 0.4.0

package/dist/module-architecture.d.ts

@@ -29,6 +29,39 @@ export interface ArchNamespaces {
     members: Record<string, ArchNamespaceMember>;
     rules: string[];
 }
+/**
+ * One page a site template's roster declares (spec 5478 § D1).
+ *
+ * Both producers emit this same row type: a template's BASE roster
+ * (`TemplateManifest.roster`, template-manifest.ts) and a module's
+ * `pageContributions` below. One vocabulary, so the merge has exactly one
+ * collision key to reconcile rather than two (§ D1/D2).
+ *
+ * Declared HERE rather than in `template-manifest.ts` (§ D3) because
+ * `ModuleSlice` carries it and `template-manifest.ts` already imports
+ * `MODULE_SLICES` + `normalizeModules` from this file — so the dependency
+ * stays a DAG (`parse-args` ← `module-architecture` ← `template-manifest`)
+ * instead of becoming a cycle in the value graph.
+ *
+ * A row carries no nav label: `GATEABLE_SURFACES` already carries
+ * `navLabelKey?` per surface (`surfaces.ts`) and the nav is derived from the
+ * roster (parent spec 5462 § D9), so a label here would be a second authority
+ * for one fact.
+ */
+export interface PageRosterRow {
+    /**
+     * Site-relative route path, e.g. `/blog` or `/flows/[slug]/start`. This is
+     * the row's IDENTITY and the merge's collision key (§ D2): a path claimed by
+     * two sources is refused at build time, never resolved by a precedence rule
+     * (parent § D8).
+     */
+    route: string;
+    /**
+     * Repo-relative seed content this row renders. Absent for an API-backed row
+     * (`/schedule` renders from the scheduling API, not from an MDX file).
+     */
+    content?: readonly string[];
+}
 /**
  * The architecture fragment one module contributes.
  *
@@ -104,6 +137,31 @@ export interface ModuleSlice {
      * which miss eleven and over-mark three.
      */
     ownedFiles?: string[];
+    /**
+     * The page rows and seed content this module contributes to any site
+     * template that takes it (spec 5478; parent spec 5462 § D5) — `ownedFiles`'s
+     * sibling, and a DIFFERENT kind of fact again from every field above.
+     * `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 contribution never carries route CODE. How the route code reaches a
+     * scaffold is a property of the module, not of the contribution (parent
+     * § D6): `docs-blog` and `scheduling` list their route files in `ownedFiles`
+     * so the code rides their own licence-checked bundle, while
+     * `signal-collectors` deliberately does not — its `flows` routes reach a
+     * scaffold from the `templates/` snapshot, retained because
+     * `MODULE_SURFACES` enables the surface (see this file's
+     * `signal-collectors.ownedFiles` comment for why listing them there broke
+     * `sync-routes`, #5366). Both shapes declare their rows here identically.
+     *
+     * Unset for a module that brings no pages to any declared template:
+     * `marketing` (base, no `ownedFiles` and `MODULE_SURFACES.marketing` is
+     * `[]`), and — deferred, not absent — `multi-tenant` and `commerce`, whose
+     * rows are their own instances' to enumerate. An unset field contributes
+     * zero rows openly; it is not a partial merge.
+     */
+    pageContributions?: readonly PageRosterRow[];
     /**
      * Bundle-relative source → scaffold-relative destination (spec 5373 § D7).
      * Every source must be a file the validated tar extraction produced in the

package/dist/module-architecture.js

@@ -266,6 +266,28 @@ export const MODULE_SLICES = {
             "packages/ui/src/chrome/DocsSidebar.tsx",
             "packages/ui/src/chrome/slices/docs-blog.ts",
         ],
+        // pageContributions (spec 5478; parent § D6 shape 1) — the two route
+        // surfaces this module mounts, each with the seed MDX it renders. The
+        // three MDX files are exactly the three on the tree and cannot come from
+        // the `templates/` snapshot: `apps/web/content` is in build-templates.mjs's
+        // EXCLUDE_TEMPLATE_DIRS and `template-overlay/` carries no blog or docs
+        // stub. They ride this module's own bundle, consistent with the route
+        // files above — STAGING them into it is #5481's change to
+        // build-module-bundles.mjs, since `collectModuleFiles` unions `ownedFiles`
+        // with `installMap` keys and nothing else. This unit only DECLARES them.
+        pageContributions: [
+            {
+                route: "/blog",
+                content: [
+                    "apps/web/content/en/blog/index.mdx",
+                    "apps/web/content/en/blog/launching-ailk.mdx",
+                ],
+            },
+            {
+                route: "/docs",
+                content: ["apps/web/content/en/docs/getting-started.mdx"],
+            },
+        ],
         // patches (spec 5418 § 3 D1, Group G) — every Group G row that edits a
         // file the buyer's scaffold already has. Values transcribed verbatim
         // from docs/specs/5365-docs-blog-module-spec.md § 4 Group G via
@@ -387,6 +409,12 @@ export const MODULE_SLICES = {
                     "packages/theme",
                     "packages/ui",
                     "packages/validation",
+                    // The `workspace` module's shared settings components (#5371 req. 6)
+                    // — the scaffolded-site twin of the root architecture.yaml grant on
+                    // `apps_paid.workspace`. Pro Plus inherits Pro's module set, so a
+                    // saas-product scaffold carries both modules and this app composes
+                    // the identical panels apps/web does, with no forked copy.
+                    "packages/workspace-ui",
                 ],
                 may_not_import_from: [
                     "apps/api",
@@ -649,6 +677,90 @@ export const MODULE_SLICES = {
             "apps-paid/workspace/**",
         ],
     },
+    // ── workspace — Pro module: the single-workspace settings shell (D-27/D-49)
+    //
+    // `/workspace` in apps/web's `(authed)` segment — General (rename), Site
+    // (identity / SEO / theme, over the already-shipped apps/api config routes)
+    // and Team (a read-only roster). The three panels live in the shared
+    // `packages/workspace-ui` package so the multi-tenant workspace app (the
+    // Pro Plus app) composes the identical components rather than a fork.
+    //
+    // No `apps` / `namespaces` / `forbiddenPatterns` block: this module
+    // contributes to already-declared apps only (apps/web is BASE; apps/api is
+    // declared by multi-tenant / scheduling / commerce and is snapshotted whole).
+    workspace: {
+        // A PERMISSION, not a physical slice (#5371 D1a) — the identical shape
+        // docs-blog uses for `packages/fumadocs-schema`. `packages/` is never in
+        // SNAPSHOT_DIRS, so the package reaches a buyer as an npm/bundle
+        // dependency under `node_modules/`, never as a `packages/workspace-ui`
+        // source sibling; the `patches` entry below is what puts it in the
+        // buyer's apps/web/package.json.
+        webImports: ["packages/workspace-ui"],
+        packages: {
+            "workspace-ui": {
+                description: "Shared workspace-settings components — the settings shell plus the General / Site / Team panels, presentational only (data + save callbacks as props)",
+                // packages/templates is required because WorkspaceSettingsShell
+                // composes AppShell from @working-theory/templates/shells — the same
+                // composition apps/web's own account page uses.
+                may_import_from: [
+                    "packages/templates",
+                    "packages/theme",
+                    "packages/ui",
+                    "packages/validation",
+                ],
+            },
+        },
+        // SOURCE files only, and only the ones this module physically owns: the
+        // three apps/web route files and the two apps/api route files.
+        //
+        // `packages/workspace-ui/**` is deliberately NOT listed (D1a). It is a
+        // whole package that is paid end to end, whose strip disposition is
+        // carried by architecture.yaml's `commercial_tier_moves_to` field (its
+        // future paid-tree home) rather than by a per-file inventory —
+        // exactly the disposition `packages/fumadocs-schema` carries for
+        // docs-blog. `multi-tenant`'s whole-app glob (above) works because
+        // SNAPSHOT_DIRS physically copies apps wholesale; a package is never in a
+        // snapshot root, so an ownedFiles enumeration would add nothing.
+        //
+        // `packages/api-client/src/workspace.ts` is NOT listed either (D1b):
+        // api-client is a base package every scaffold receives regardless of
+        // `--modules`, and the field doc above names it by name as a shared
+        // package deliberately left out even when genuinely single-purpose. The
+        // wrapper is harmless on a scaffold without this module — its calls 404,
+        // the same non-event any client wrapper produces against an unregistered
+        // route.
+        //
+        // Test companions (`__tests__/`) are never listed — the SOURCE-files-only
+        // rule above.
+        ownedFiles: [
+            "apps/web/app/[locale]/(authed)/workspace/page.tsx",
+            "apps/web/app/[locale]/(authed)/workspace/site/page.tsx",
+            "apps/web/app/[locale]/(authed)/workspace/team/page.tsx",
+            "apps/api/src/routes/workspaces/general.ts",
+            "apps/api/src/routes/workspaces/members.ts",
+        ],
+        // patches — the dependency add that delivers the shared package to the
+        // buyer's apps/web, mirroring docs-blog's own fumadocs-schema merge-keys
+        // op. No next.config.mjs `add-transpile-package` op: the package ships
+        // compiled ESM in dist/ the same way every other @working-theory/*
+        // dependency apps/web already consumes does, and docs-blog's transpile op
+        // exists for the fumadocs SDK boundary, not for the dependency add itself.
+        patches: [
+            {
+                target: "apps/web/package.json",
+                kind: "json",
+                ops: [
+                    {
+                        op: "merge-keys",
+                        path: ["dependencies"],
+                        entries: {
+                            "@working-theory/workspace-ui": "workspace:*",
+                        },
+                    },
+                ],
+            },
+        ],
+    },
     // ── scheduling — full-stack module (provider + routes + booker pages) ────
     //
     // The #4416 scheduling seam, made installable. Three tiers into the
@@ -816,6 +928,14 @@ export const MODULE_SLICES = {
             "apps/web/app/[locale]/schedule/page.tsx",
             "apps/web/app/[locale]/schedule/confirmed/page.tsx",
         ],
+        // pageContributions (spec 5478; parent § D6 shape 1) — the booker and its
+        // confirmation page, whose route files `ownedFiles` above already carries.
+        // Neither row names seed content: both render from the /v1/schedule/*
+        // routes, not from an MDX file.
+        pageContributions: [
+            { route: "/schedule" },
+            { route: "/schedule/confirmed" },
+        ],
     },
     // ── signal-collectors — flows, deliverables, project listings, waitlist
     // signups (D-48, #5366) ───────────────────────────────────────────────
@@ -898,10 +1018,23 @@ export const MODULE_SLICES = {
     // packages/ui: eleven components (D8) plus the NEW slice registration
     // entry point (D8a, mirroring sections/slices/scheduling.ts). Four of the
     // eleven (ProjectListingShelves, ListingPrivacyNotice, ProjectListingCard,
-    // ResultsReveal) have no consumer anywhere in the repo today — grep-
-    // confirmed orphaned exports, not a module-boundary fact; D8 places them
-    // here by subject (project-listing / results-reveal UI) rather than by
-    // reachability, since reachability cannot place an unreached file either.
+    // ResultsReveal) had no consumer anywhere IN THIS REPO at D8 authoring
+    // time — grep-confirmed, a module-boundary fact only in-repo. Three of the
+    // four (ProjectListingShelves, ProjectListingCard, ListingPrivacyNotice —
+    // plus the ListingWindowBand type ProjectListingCard exports) are, in
+    // fact, consumed CROSS-ORG: the samhenry site (salessmyth org) imports all
+    // four from the signal-collectors slice's re-export entry point
+    // (packages/ui/src/sections/slices/signal-collectors.ts, rules/cross-org-
+    // sharing.md), which #5488 additionally re-exports them from so that
+    // consumer can reach them by subpath. "No consumer anywhere in the repo"
+    // was therefore true in-repo and false across the org boundary — not a
+    // reachability fact a repo-scoped grep can see. ResultsReveal remains the
+    // one component of the four with no known consumer anywhere (in-repo or
+    // out) and is NOT re-exported by #5488 — it is not this card's claim to
+    // make it non-orphaned. D8's placement rule (by subject — project-listing
+    // / results-reveal UI — rather than by reachability, since reachability
+    // cannot place an unreached file either) is unchanged and still governs
+    // where all eleven live.
     "signal-collectors": {
         ownedFiles: [
             "apps/api/src/routes/flows/index.ts",
@@ -995,6 +1128,25 @@ export const MODULE_SLICES = {
             "packages/ui/src/blocks/ResultsReveal.tsx",
             "packages/ui/src/sections/slices/signal-collectors.ts",
         ],
+        // pageContributions (spec 5478; parent § D6 shape 2) — the three flow
+        // routes, named exactly as `surfaces.ts`'s ROUTE_SINCE keys name them.
+        // ROWS AND SEED ONLY: unlike docs-blog and scheduling above, this module's
+        // route code is deliberately NOT in `ownedFiles` (see the comment inside
+        // that array). The first two rows' code reaches a scaffold from the
+        // `templates/` snapshot, retained because the `flows` surface is enabled;
+        // the results row's code is `commerce`'s (`commerce.ownedFiles` carries
+        // `results/[payload]/page.tsx` + its two client files below, and
+        // `paidModuleTemplateExclusions` strips every paid module's owned files
+        // from the snapshot unconditionally), so that one row rides a DIFFERENT
+        // module's bundle — recorded in spec 5478 § 8 item 1, whose delivery
+        // consequence is #5481's and #5464's. Declaring the rows here changes none
+        // of it: a contribution is data, and which delivery shape carries the code
+        // is a property of the module, not of the contribution.
+        pageContributions: [
+            { route: "/flows/[slug]" },
+            { route: "/flows/[slug]/start" },
+            { route: "/flows/[slug]/results/[payload]" },
+        ],
     },
     // ── commerce — per-site paid add-on (D-47, amending D-26) ─────────────────
     //

package/dist/parse-args.d.ts

@@ -7,12 +7,19 @@
  * composition is downstream work, so the default (`marketing`) reproduces
  * today's fixed-tree scaffold exactly.
  */
-export declare const RECOGNIZED_MODULES: readonly ["marketing", "docs-blog", "multi-tenant", "scheduling", "signal-collectors", "commerce"];
+export declare const RECOGNIZED_MODULES: readonly ["marketing", "docs-blog", "multi-tenant", "workspace", "scheduling", "signal-collectors", "commerce"];
 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. */
     target: string | undefined;
+    /**
+     * The site template to install (`--template`), validated against
+     * `RECOGNIZED_TEMPLATES` at parse time. Undefined when the flag is absent —
+     * and a run naming no template scaffolds exactly what it did before the
+     * flag existed (spec 5481 § 3 DD3).
+     */
+    template: string | undefined;
     install: boolean;
     help: boolean;
     version: boolean;

package/dist/parse-args.js

@@ -9,6 +9,7 @@
  */
 import { parseArgs } from "node:util";
 import { RECOGNIZED_SURFACES, parseSurfaces } from "./surfaces.js";
+import { RECOGNIZED_TEMPLATES } from "./template-names.js";
 /**
  * The recognized module vocabulary for the `--modules` selector.
  *
@@ -22,6 +23,7 @@ export const RECOGNIZED_MODULES = [
     "marketing",
     "docs-blog",
     "multi-tenant",
+    "workspace",
     "scheduling",
     "signal-collectors",
     "commerce",
@@ -51,6 +53,16 @@ Options:
                            Defaults to \`marketing\`, which reproduces today's
                            scaffold. A module is a composable unit across the
                            three tiers (data · API · presentation).
+  --template <name>        The site template to install (recognized:
+                           ${RECOGNIZED_TEMPLATES.join(", ")}).
+                           A template is a page roster plus seed content and
+                           config — never code. Its required modules are ADDED
+                           to whatever \`--modules\` names, so the two compose.
+                           A template needing only free modules installs from
+                           the tree this package ships, with no key and no
+                           network call; one needing a paid module needs
+                           AILK_LICENSE_KEY to cover every module it requires,
+                           and refuses naming whichever it does not.
   --surfaces <csv>         Comma-separated route surfaces to scaffold IN
                            ADDITION to the core set (/, /about, /contact, /faq,
                            /thanks). Recognized: ${RECOGNIZED_SURFACES.join(", ")}.
@@ -102,6 +114,7 @@ export function parseCliArgs(argv) {
             allowPositionals: true,
             options: {
                 modules: { type: "string" },
+                template: { type: "string" },
                 surfaces: { type: "string" },
                 "sync-architecture": { type: "string" },
                 "sync-catalog": { type: "boolean", default: false },
@@ -119,6 +132,7 @@ export function parseCliArgs(argv) {
     const version = parsed.values.version === true;
     const install = parsed.values.install === true;
     const modules = parseModules(parsed.values.modules);
+    const template = parseTemplate(parsed.values.template);
     const surfaces = parseSurfaceList(parsed.values.surfaces);
     const syncArchitecture = parsed.values["sync-architecture"];
     const syncCatalog = parsed.values["sync-catalog"] === true;
@@ -138,6 +152,7 @@ export function parseCliArgs(argv) {
     if (help || version) {
         return {
             target: undefined,
+            template: undefined,
             install,
             help,
             version,
@@ -155,6 +170,7 @@ export function parseCliArgs(argv) {
         }
         return {
             target: parsed.positionals[0],
+            template,
             install,
             help,
             version,
@@ -173,6 +189,7 @@ export function parseCliArgs(argv) {
     }
     return {
         target: parsed.positionals[0],
+        template,
         install,
         help,
         version,
@@ -183,6 +200,32 @@ export function parseCliArgs(argv) {
         syncArchitecture: undefined,
     };
 }
+/**
+ * Validate the `--template` value against the declared template set
+ * (spec 5481 § 3 DD1).
+ *
+ * Validated HERE, in the parser, so an unrecognized template fails at parse
+ * time as a `ParseError` exactly like an unrecognized module or surface does.
+ * Splitting it out to `programmatic.ts` would make `--template` the one flag
+ * in this CLI whose bad value surfaces somewhere else.
+ *
+ * The names come from `template-names.ts` rather than from
+ * `TEMPLATE_MANIFESTS` itself, and that file's doc comment records the
+ * measured reason: importing the registry here closes a runtime cycle
+ * through `lib/module-tier.ts`. `TEMPLATE_MANIFESTS` remains the registry;
+ * the two sets are asserted equal by the suite.
+ *
+ * @throws ParseError on an undeclared template name, naming the declared set.
+ */
+function parseTemplate(raw) {
+    if (raw === undefined)
+        return undefined;
+    const name = raw.trim();
+    if (!RECOGNIZED_TEMPLATES.includes(name)) {
+        throw new ParseError(`unknown template "${raw}". Recognized: ${RECOGNIZED_TEMPLATES.join(", ")}`);
+    }
+    return name;
+}
 /**
  * Parse + validate the `--surfaces` CSV, re-throwing an unrecognized-surface
  * failure as a ParseError so every CLI parse failure reaches the orchestrator's

package/dist/programmatic.d.ts

@@ -28,6 +28,21 @@ export interface ScaffoldOptions {
      * Ignored at runtime until named presets are implemented.
      */
     preset?: string;
+    /**
+     * The site template to install (`--template`), a `TEMPLATE_MANIFESTS` key.
+     *
+     * Consumed ONLY by the async `scaffold()` below. `scaffoldSync` stays
+     * template-oblivious for exactly the reason it stays licensing-oblivious
+     * (spec 5481 § 3 DD3): a call naming no template takes a code path with no
+     * new statement in it, which is a stronger byte-identity guarantee than a
+     * test asserting the output happens to match.
+     *
+     * What a template DOES change is `modules` — `scaffold()` unions the
+     * template's `requires` with whatever `--modules` named and passes THAT
+     * list to `scaffoldSync` (DD2), so the resolved surfaces, the emitted
+     * `architecture.yaml` and the generated nav are all functions of the union.
+     */
+    template?: string;
     /**
      * Selected modules (recognized: marketing, docs-blog, multi-tenant,
      * scheduling). Defaults to
@@ -70,6 +85,8 @@ export interface ScaffoldOptions {
     licenseKey?: 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. */
+    templateRegistryUrl?: string;
     /** Injected fetch for tests. Never a live network call in CI or in this repo's evidence runs. */
     fetchImpl?: typeof fetch;
 }
@@ -98,9 +115,17 @@ export declare function scaffoldSync(opts: ScaffoldOptions): ScaffoldResult;
  *      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.
+ *   3. `scaffoldSync` — unchanged, today's local `templates/` copy, over the
+ *      EFFECTIVE module set (see 0 below).
  *   4. Merge each resolved paid module's fetched bundle into the freshly
  *      scaffolded tree (`extractModuleBundle`).
+ *   5. Install the named site template LAST (#5481; parent record D9), from
+ *      its fetched bundle or — when it requires only free modules — from the
+ *      `site-templates/` tree this package ships.
+ *
+ * And, ahead of all five when `opts.template` is set (0): resolve the
+ * template and union its `requires` with `opts.modules`, so every step above
+ * runs over the EFFECTIVE module set rather than the requested one.
  *
  * `scaffoldSync` itself stays licensing-oblivious on purpose: every existing
  * synchronous caller (this package's own test suite, overwhelmingly) is

package/dist/programmatic.js

@@ -21,15 +21,26 @@ 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 { extractModuleBundle, installBundleTree, } from "./lib/extract-module-bundle.js";
+import { fetchTemplate } from "./lib/fetch-template.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 { resolveTemplate, templateDelivery } from "./template-manifest.js";
 import { validateTarget } from "./validate.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATES_DIR = resolve(PKG_ROOT, "templates");
+/**
+ * Where a Free site template's files are read from on the keyless path — and
+ * why it is BESIDE `templates/` rather than inside it (parent record D14):
+ * `copyTemplate` copies the whole `templates/` tree into EVERY scaffold, so a
+ * per-template subtree there would land in scaffolds that asked for a
+ * different template, or for none. It reaches the published tarball through
+ * `package.json` `files` instead.
+ */
+const SITE_TEMPLATES_DIR = resolve(PKG_ROOT, "site-templates");
 const VERSIONS_FILE = resolve(PKG_ROOT, "versions.json");
 function readVersionMap() {
     if (!existsSync(VERSIONS_FILE)) {
@@ -114,9 +125,17 @@ export function scaffoldSync(opts) {
  *      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.
+ *   3. `scaffoldSync` — unchanged, today's local `templates/` copy, over the
+ *      EFFECTIVE module set (see 0 below).
  *   4. Merge each resolved paid module's fetched bundle into the freshly
  *      scaffolded tree (`extractModuleBundle`).
+ *   5. Install the named site template LAST (#5481; parent record D9), from
+ *      its fetched bundle or — when it requires only free modules — from the
+ *      `site-templates/` tree this package ships.
+ *
+ * And, ahead of all five when `opts.template` is set (0): resolve the
+ * template and union its `requires` with `opts.modules`, so every step above
+ * runs over the EFFECTIVE module set rather than the requested one.
  *
  * `scaffoldSync` itself stays licensing-oblivious on purpose: every existing
  * synchronous caller (this package's own test suite, overwhelmingly) is
@@ -124,16 +143,59 @@ export function scaffoldSync(opts) {
  * with a paid module in `opts.modules` exercises the gate at all.
  */
 export async function scaffold(opts) {
-    const { paid } = classifyModules(normalizeModules(opts.modules ?? ["marketing"]));
+    // Resolved first, and by the registry rather than re-validated here: the
+    // name already passed `parse-args.ts`, and `resolveTemplate` throws a
+    // `TemplateError` for a programmatic caller that skipped the parser.
+    const template = opts.template !== undefined ? resolveTemplate(opts.template) : undefined;
+    // The effective module set: union(template.requires, parsed --modules),
+    // normalized through `normalizeModules` — the single ordering authority
+    // (parent record D7). Order-independence falls out rather than being
+    // engineered: it returns `RECOGNIZED_MODULES.filter(...)`, declaration-
+    // ordered and deduped, so the same SET in any argument order is the same
+    // list.
+    const modules = normalizeModules([
+        ...(template?.requires ?? []),
+        ...(opts.modules ?? ["marketing"]),
+    ]);
+    const { paid } = classifyModules(modules);
     const bundles = await resolvePaidModules({
         paidModules: paid,
         licenseKey: opts.licenseKey,
+        ...(template !== undefined ? { templateName: template.name } : {}),
         ...(opts.moduleRegistryUrl !== undefined
             ? { registryUrl: opts.moduleRegistryUrl }
             : {}),
         ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
     });
-    const result = scaffoldSync(opts);
+    // The template's OWN bundle, fetched here — before `scaffoldSync` — so the
+    // fourth refusal (the template's bundle unpublished, parent record D17 /
+    // spec 5481 § 3 DD5 row 4) throws with the target still non-existent, like
+    // the three module refusals above it (DD6). It is EXTRACTED last, below.
+    //
+    // The keyless path never reaches this at all: a template requiring only
+    // free modules classifies to an empty paid set, so `resolvePaidModules`
+    // returned at its first branch without reading `process.env` or the
+    // network, and `templateDelivery` sends us past this too (DD7). That is
+    // what makes record D11's no-network guarantee structural rather than
+    // merely likely.
+    const templateBundle = template !== undefined && templateDelivery(template) === "paid"
+        ? await fetchTemplate({
+            templateName: template.name,
+            token: opts.licenseKey ?? process.env["AILK_LICENSE_KEY"] ?? "",
+            ...(opts.templateRegistryUrl !== undefined
+                ? { registryUrl: opts.templateRegistryUrl }
+                : {}),
+            ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+        })
+        : undefined;
+    // `modules` — the union — is what `scaffoldSync` receives, not `opts`
+    // (spec 5481 § 3 DD2). `resolveSurfaces`, `deriveArchitecture` and
+    // `renderNavConfig` are all computed INSIDE `scaffoldSync` from
+    // `opts.modules`, so a union computed for the licence classification alone
+    // would gate correctly and emit the wrong surfaces, the wrong
+    // `architecture.yaml` and the wrong nav — a silent wrong result, not a
+    // failure.
+    const result = scaffoldSync({ ...opts, modules });
     // Threaded to extractModuleBundle for `package.json` patch targets'
     // `workspace:*` substitution (spec 5418 § 3 D2) — the same version map
     // `scaffoldSync` already reads for `copyTemplate`, re-read here since
@@ -147,6 +209,40 @@ export async function scaffold(opts) {
             versions,
         });
     }
+    // The template lands LAST — after `scaffoldSync` and after every module
+    // bundle (parent record D9) — so its content and config files sit on top of
+    // everything derived. It shapes the derived artifacts by DECLARING (its
+    // `requires` are in the union above; its roster rows are what the nav is
+    // generated from), never by landing a code file: the nav is already written
+    // by `scaffoldSync` from `renderNavConfig(enabledSurfaces)`, and record
+    // §5.2 forbids a `.ts` in any `site-templates/` `installMap` destination.
+    //
+    // One install step, two source roots (DD7): an extracted staging dir on the
+    // paid path, `site-templates/<name>/` on disk on the Free one.
+    if (template !== undefined) {
+        if (templateBundle !== undefined) {
+            await extractModuleBundle({
+                bytes: templateBundle,
+                targetDir: result.targetDir,
+                moduleName: template.name,
+                templateRequires: template.requires,
+                versions,
+            });
+        }
+        else {
+            const sourceRoot = join(SITE_TEMPLATES_DIR, template.name);
+            if (!existsSync(sourceRoot)) {
+                throw new Error(`template "${template.name}": ${sourceRoot} is missing — the published package must carry site-templates/ in its "files" list`);
+            }
+            installBundleTree({
+                sourceRoot,
+                targetDir: result.targetDir,
+                name: template.name,
+                templateRequires: template.requires,
+                versions,
+            });
+        }
+    }
     return result;
 }
 // Re-exported so a consumer of the async `scaffold()` above can type its own