create-ailk 0.7.0 → 0.8.0

package/dist/lib/pro-callout.js

@@ -9,7 +9,7 @@
  * and a licensed install already owns the tier it pitches.
  */
 import { normalizeModules } from "../module-architecture.js";
-import { resolveTemplate } from "../template-manifest.js";
+import { SHAPE_STARTERS, resolveTemplate } from "../template-manifest.js";
 import { classifyModules } from "./module-tier.js";
 export function proCallout() {
     return [
@@ -34,7 +34,15 @@ export const LICENSED_PREREQUISITES_NOTE = "No database and no vendor API key ar
  * `templateDelivery` derives "paid" from `requires` alone.
  */
 export function isLicensedInstall(opts) {
-    const requires = opts.template !== undefined ? resolveTemplate(opts.template).requires : [];
+    // #6757 D6 row 4 — a bare-shape starter's name (the shape itself, passed
+    // here after #6754 D4 item 3 resolves it) is looked up through
+    // SHAPE_STARTERS first; `resolveTemplate` alone throws `unknown template`
+    // for one (NFR-3).
+    const requires = opts.template !== undefined
+        ? Object.prototype.hasOwnProperty.call(SHAPE_STARTERS, opts.template)
+            ? SHAPE_STARTERS[opts.template].requires
+            : resolveTemplate(opts.template).requires
+        : [];
     const modules = normalizeModules([
         ...requires,
         ...(opts.modules ?? ["marketing"]),

package/dist/parse-args.d.ts

@@ -1,3 +1,4 @@
+import type { ScaffoldOptions } from "./programmatic.js";
 /**
  * The recognized module vocabulary for the `--modules` selector.
  *
@@ -9,23 +10,52 @@
  */
 export declare const RECOGNIZED_MODULES: readonly ["marketing", "docs-blog", "multi-tenant", "workspace", "scheduling", "signal-collectors", "commerce"];
 export type ModuleName = (typeof RECOGNIZED_MODULES)[number];
+/**
+ * Shapes a starter can be built from today (`--shape`, #6754 D1).
+ *
+ * Declared HERE rather than imported from `template-manifest.ts` for the
+ * reason `RECOGNIZED_MODULES` is: importing the registry closes the runtime
+ * cycle `template-names.ts`'s header records. `parse-args.test.ts` pins this
+ * list, `RESERVED_SHAPES` and `RECOGNIZED_DESIGNS` to their authorities
+ * (`STARTER_SHAPES`, `STARTER_DESIGNS`, `SHAPE_ROSTERS`).
+ */
+export declare const RECOGNIZED_SHAPES: readonly ["organization-product", "organization-service", "local-business-service", "person-service"];
+export type ShapeName = (typeof RECOGNIZED_SHAPES)[number];
+/** Shapes the contract names but no release builds yet. */
+export declare const RESERVED_SHAPES: readonly ["local-business-product"];
+/** The `--design` vocabulary (#6754 D1) — `STARTER_DESIGNS`, pinned by test. */
+export declare const RECOGNIZED_DESIGNS: readonly ["standard", "minimalism"];
+export type DesignName = (typeof RECOGNIZED_DESIGNS)[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).
+     * `RECOGNIZED_TEMPLATES` at parse time. Undefined when the flag is absent.
+     * The CLI never scaffolds a run naming neither a template nor a shape
+     * (#6754 D2 — refusal R1, or the shape prompt on a terminal).
      */
     template: string | undefined;
+    /** The starter's shape (`--shape`, #6754), normalized. Never set with `template`. */
+    shape?: ShapeName;
+    /** The starter's design (`--design`, #6754). Never set with `template`. */
+    design?: DesignName;
+    /**
+     * True when a scaffold run named neither `--shape` nor `--template` on a
+     * terminal: `resolveCliShape` must ask before anything is scaffolded.
+     */
+    needsShapePrompt: boolean;
     install: boolean;
     help: boolean;
     version: boolean;
-    /** Selected modules (recognized: marketing, docs-blog, multi-tenant, scheduling).
-     *  Defaults to ['marketing'] when the flag is absent. */
-    modules: string[];
+    /**
+     * Selected modules (recognized: marketing, docs-blog, multi-tenant,
+     * scheduling). `undefined` when `--modules` is absent — the key's level
+     * decides (#6759 D3); never read as `['marketing']` here. An empty or
+     * all-empty `--modules` value still names the Free set (`parseModules`).
+     */
+    modules: string[] | undefined;
     /** 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. */
@@ -58,16 +88,54 @@ export interface CliOptions {
 export declare class ParseError extends Error {
     constructor(message: string);
 }
+/** The caller's terminal state (#6754 D2). */
+export interface ParseEnv {
+    /** A human can answer a prompt: `process.stdin.isTTY === true` in cli.ts. */
+    interactive: boolean;
+}
 export declare const helpText: string;
-export declare function parseCliArgs(argv: string[]): CliOptions;
+/**
+ * Parse `create-ailk` argv. `env.interactive` defaults to false —
+ * fail-closed: a caller that does not assert a human is present gets refusal
+ * R1, never a prompt it cannot answer (#6754 D2).
+ */
+export declare function parseCliArgs(argv: string[], env?: ParseEnv): CliOptions;
+/** The streams the shape prompt reads and writes (a `PassThrough` pair in tests). */
+export interface PromptIo {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+}
+/**
+ * Ask once for a shape (#6754 D3): a number 1–4 or a shape name. A bad answer
+ * re-asks, naming what was wrong; the third bad answer, or a closed input,
+ * throws. There is no default — an empty line is a bad answer.
+ */
+export declare function promptForShape(io: PromptIo): Promise<ShapeName>;
+/**
+ * Fill `opts.shape` by prompting when, and only when, `needsShapePrompt` is
+ * set (#6754 D3). Help, version, sync and every run naming a shape or a
+ * template come back unchanged, with nothing written to `io.output`.
+ */
+export declare function resolveCliShape(opts: CliOptions, io: PromptIo): Promise<CliOptions>;
+/**
+ * The one mapping from parsed flags to `scaffold()` options (#6754 D4).
+ * `template`, `shape`, `design` and `license` are each spread only when set,
+ * so a `--template` run hands `scaffold()` the object it did before #6754.
+ *
+ * @throws ParseError when the shape prompt is unresolved or the target is
+ *   unset — an unresolved prompt must never fall through to the bare overlay.
+ */
+export declare function toScaffoldOptions(opts: CliOptions): ScaffoldOptions;
 /**
  * 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.
+ * each against RECOGNIZED_MODULES. Takes a PRESENT value only — an ABSENT
+ * `--modules` flag is `undefined` (#6759 D3: the key's level decides) and
+ * never reaches this function; an all-empty value (`--modules ""`,
+ * `--modules ,`) still names the Free set, spelled inline here.
  *
  * @throws ParseError on an unrecognized module value, naming the recognized set.
  */
-export declare function parseModules(raw: string | undefined): string[];
+export declare function parseModules(raw: string): string[];

package/dist/parse-args.js

@@ -7,6 +7,7 @@
  * On any parse / validation failure: throws ParseError. The orchestrator's
  * top-level catch turns this into a stderr write + non-zero exit.
  */
+import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
 import { assertLicenseKeyShape } from "./lib/license-key-files.js";
 import { RECOGNIZED_SURFACES, parseSurfaces } from "./surfaces.js";
@@ -29,8 +30,33 @@ export const RECOGNIZED_MODULES = [
     "signal-collectors",
     "commerce",
 ];
-/** The default module selection when `--modules` is absent (reproduces today's scaffold). */
-const DEFAULT_MODULES = ["marketing"];
+/**
+ * Shapes a starter can be built from today (`--shape`, #6754 D1).
+ *
+ * Declared HERE rather than imported from `template-manifest.ts` for the
+ * reason `RECOGNIZED_MODULES` is: importing the registry closes the runtime
+ * cycle `template-names.ts`'s header records. `parse-args.test.ts` pins this
+ * list, `RESERVED_SHAPES` and `RECOGNIZED_DESIGNS` to their authorities
+ * (`STARTER_SHAPES`, `STARTER_DESIGNS`, `SHAPE_ROSTERS`).
+ */
+export const RECOGNIZED_SHAPES = [
+    "organization-product",
+    "organization-service",
+    "local-business-service",
+    "person-service",
+];
+/** Shapes the contract names but no release builds yet. */
+export const RESERVED_SHAPES = ["local-business-product"];
+/** The `--design` vocabulary (#6754 D1) — `STARTER_DESIGNS`, pinned by test. */
+export const RECOGNIZED_DESIGNS = ["standard", "minimalism"];
+/** What each shape is, for the prompt (D3). A shape without one is a type error. */
+const SHAPE_DESCRIPTIONS = {
+    "organization-product": "a company selling a product",
+    "organization-service": "a company selling a service",
+    "local-business-service": "a local business selling a service",
+    "person-service": "a person selling their own service",
+};
+const SHAPE_LIST = RECOGNIZED_SHAPES.join(", ");
 export class ParseError extends Error {
     constructor(message) {
         super(message);
@@ -51,11 +77,31 @@ Arguments:
 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).
+                           Trims or ADDS relative to the level your licence
+                           key unlocks (#6759) — it never replaces it. With no
+                           key, the level is Free (\`marketing\`). A Pro key
+                           switches on docs-blog, scheduling and
+                           signal-collectors too; Pro Plus adds multi-tenant.
+                           Naming modules here keeps EXACTLY those, trimming
+                           the level's default. Naming only \`commerce\` (a
+                           per-site add-on) or \`workspace\` (included at Pro,
+                           opt-in) ADDS it on top of the level's default
+                           without trimming. A module your licence does not
+                           include is refused, naming the level that does. A
+                           module is a composable unit across the three tiers
+                           (data · API · presentation).
+  --shape <shape>          The kind of site to build (recognized:
+                           ${SHAPE_LIST}).
+                           Installs that shape's Free starter. A run naming
+                           neither --shape nor --template asks for a shape on
+                           a terminal, and refuses without one.
+  --design <design>        The look to render the starter in (recognized:
+                           ${RECOGNIZED_DESIGNS.join(", ")}). Defaults to the
+                           starter's own.
   --template <name>        The site template to install (recognized:
                            ${RECOGNIZED_TEMPLATES.join(", ")}).
+                           A template already fixes its shape and design, so
+                           it cannot be combined with --shape or --design.
                            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.
@@ -103,8 +149,8 @@ Options:
   --version                Print the scaffolder version.
 
 Examples:
-  pnpm create ailk@latest my-site
-  pnpm create ailk@latest /tmp/test-site --install
+  pnpm create ailk@latest my-site --shape organization-product
+  pnpm create ailk@latest /tmp/test-site --template marketing-site-free --install
 
 Next steps after a successful scaffold:
   cd <target-dir>
@@ -113,7 +159,12 @@ Next steps after a successful scaffold:
 
 Reference: ADR 0007 — \`pnpm create ailk@latest\` is the canonical install path.
 `;
-export function parseCliArgs(argv) {
+/**
+ * Parse `create-ailk` argv. `env.interactive` defaults to false —
+ * fail-closed: a caller that does not assert a human is present gets refusal
+ * R1, never a prompt it cannot answer (#6754 D2).
+ */
+export function parseCliArgs(argv, env = { interactive: false }) {
     let parsed;
     try {
         parsed = parseArgs({
@@ -123,6 +174,8 @@ export function parseCliArgs(argv) {
             options: {
                 modules: { type: "string" },
                 template: { type: "string" },
+                shape: { type: "string" },
+                design: { type: "string" },
                 license: { type: "string" },
                 surfaces: { type: "string" },
                 "sync-architecture": { type: "string" },
@@ -140,8 +193,13 @@ export function parseCliArgs(argv) {
     const help = parsed.values.help === true;
     const version = parsed.values.version === true;
     const install = parsed.values.install === true;
-    const modules = parseModules(parsed.values.modules);
+    // #6759 D3 — an absent flag stays `undefined` (the key's level decides);
+    // only a PRESENT value goes through `parseModules`.
+    const rawModules = parsed.values.modules;
+    const modules = rawModules === undefined ? undefined : parseModules(rawModules);
     const template = parseTemplate(parsed.values.template);
+    const shape = parseShape(parsed.values.shape);
+    const design = parseDesign(parsed.values.design);
     const surfaces = parseSurfaceList(parsed.values.surfaces);
     const syncArchitecture = parsed.values["sync-architecture"];
     const syncCatalog = parsed.values["sync-catalog"] === true;
@@ -163,6 +221,7 @@ export function parseCliArgs(argv) {
         return {
             target: undefined,
             template: undefined,
+            needsShapePrompt: false,
             install,
             help,
             version,
@@ -181,6 +240,7 @@ export function parseCliArgs(argv) {
         return {
             target: parsed.positionals[0],
             template,
+            needsShapePrompt: false,
             install,
             help,
             version,
@@ -197,9 +257,27 @@ export function parseCliArgs(argv) {
     if (parsed.positionals.length > 1) {
         throw new ParseError(`expected exactly one target directory, got ${parsed.positionals.length}`);
     }
+    // R3 — a template already fixes its shape and design.
+    if (template !== undefined && (shape !== undefined || design !== undefined)) {
+        const flags = shape !== undefined && design !== undefined
+            ? "--shape and --design"
+            : shape !== undefined
+                ? "--shape"
+                : "--design";
+        throw new ParseError(`--template cannot be combined with ${flags}: a template already fixes its shape and design. Pass --template alone, or --shape with an optional --design.`);
+    }
+    // R1 — no silent default: with neither a template nor a shape, ask on a
+    // terminal and refuse without one.
+    const needsShapePrompt = template === undefined && shape === undefined;
+    if (needsShapePrompt && !env.interactive) {
+        throw new ParseError(`no shape given, and there is no terminal to ask on. Pass --shape <shape> (one of: ${SHAPE_LIST}), or --template <name>.`);
+    }
     return {
         target: parsed.positionals[0],
         template,
+        ...(shape !== undefined ? { shape } : {}),
+        ...(design !== undefined ? { design } : {}),
+        needsShapePrompt,
         install,
         help,
         version,
@@ -211,6 +289,118 @@ export function parseCliArgs(argv) {
         ...(license !== undefined ? { license } : {}),
     };
 }
+/**
+ * Validate `--shape` (#6754 D2 step 2): trimmed and lowercased. A reserved
+ * shape is refusal R2; any other unrecognized value names the recognized set.
+ */
+function parseShape(raw) {
+    if (raw === undefined)
+        return undefined;
+    const name = raw.trim().toLowerCase();
+    if (RESERVED_SHAPES.includes(name)) {
+        throw new ParseError(`shape "${name}" is not available yet. Choose one of: ${SHAPE_LIST}.`);
+    }
+    if (!RECOGNIZED_SHAPES.includes(name)) {
+        throw new ParseError(`unknown shape "${raw}". Recognized: ${SHAPE_LIST}`);
+    }
+    return name;
+}
+/** Validate `--design` (#6754 D2 step 2): trimmed and lowercased. */
+function parseDesign(raw) {
+    if (raw === undefined)
+        return undefined;
+    const name = raw.trim().toLowerCase();
+    if (!RECOGNIZED_DESIGNS.includes(name)) {
+        throw new ParseError(`unknown design "${raw}". Recognized: ${RECOGNIZED_DESIGNS.join(", ")}`);
+    }
+    return name;
+}
+/** How many answers the prompt takes before it gives up. */
+const PROMPT_ATTEMPTS = 3;
+/**
+ * Ask once for a shape (#6754 D3): a number 1–4 or a shape name. A bad answer
+ * re-asks, naming what was wrong; the third bad answer, or a closed input,
+ * throws. There is no default — an empty line is a bad answer.
+ */
+export async function promptForShape(io) {
+    const width = Math.max(...RECOGNIZED_SHAPES.map((s) => s.length));
+    io.output.write([
+        "Which kind of site is this?",
+        ...RECOGNIZED_SHAPES.map((s, i) => `  ${i + 1}) ${s.padEnd(width)}  ${SHAPE_DESCRIPTIONS[s]}`),
+        "",
+    ].join("\n"));
+    const noShape = new ParseError(`no shape chosen. Re-run with --shape <shape> (one of: ${SHAPE_LIST}).`);
+    const rl = createInterface({ input: io.input, terminal: false });
+    // The async iterator buffers every line, so an answer typed (or piped)
+    // ahead of its question is never dropped, and a closed input ends it.
+    const lines = rl[Symbol.asyncIterator]();
+    try {
+        for (let attempt = 0; attempt < PROMPT_ATTEMPTS; attempt++) {
+            io.output.write(`Shape [1-${RECOGNIZED_SHAPES.length} or name]: `);
+            const next = await lines.next();
+            if (next.done === true)
+                throw noShape;
+            const answer = next.value;
+            const picked = pickShape(answer);
+            if (picked !== undefined)
+                return picked;
+            const shown = answer.trim();
+            io.output.write(shown === ""
+                ? "No answer given.\n"
+                : `"${shown}" is not a shape. Answer 1-${RECOGNIZED_SHAPES.length} or a shape name.\n`);
+        }
+        throw noShape;
+    }
+    finally {
+        rl.close();
+    }
+}
+/** A prompt answer as a shape, or undefined when it names none. */
+function pickShape(answer) {
+    const value = answer.trim().toLowerCase();
+    if (/^[0-9]+$/.test(value))
+        return RECOGNIZED_SHAPES[Number(value) - 1];
+    return RECOGNIZED_SHAPES.includes(value)
+        ? value
+        : undefined;
+}
+/**
+ * Fill `opts.shape` by prompting when, and only when, `needsShapePrompt` is
+ * set (#6754 D3). Help, version, sync and every run naming a shape or a
+ * template come back unchanged, with nothing written to `io.output`.
+ */
+export async function resolveCliShape(opts, io) {
+    if (!opts.needsShapePrompt)
+        return opts;
+    const shape = await promptForShape(io);
+    return { ...opts, shape, needsShapePrompt: false };
+}
+/**
+ * The one mapping from parsed flags to `scaffold()` options (#6754 D4).
+ * `template`, `shape`, `design` and `license` are each spread only when set,
+ * so a `--template` run hands `scaffold()` the object it did before #6754.
+ *
+ * @throws ParseError when the shape prompt is unresolved or the target is
+ *   unset — an unresolved prompt must never fall through to the bare overlay.
+ */
+export function toScaffoldOptions(opts) {
+    if (opts.needsShapePrompt) {
+        throw new ParseError(`no shape given. Pass --shape <shape> (one of: ${SHAPE_LIST}), or --template <name>.`);
+    }
+    if (opts.target === undefined) {
+        throw new ParseError("missing target directory. Usage: pnpm create ailk@latest <target-dir>");
+    }
+    return {
+        targetDir: opts.target,
+        surfaces: opts.surfaces,
+        withCatalog: opts.withCatalog,
+        ...(opts.modules !== undefined ? { modules: opts.modules } : {}),
+        ...(opts.template !== undefined ? { template: opts.template } : {}),
+        ...(opts.shape !== undefined ? { shape: opts.shape } : {}),
+        ...(opts.design !== undefined ? { design: opts.design } : {}),
+        ...(opts.license !== undefined ? { license: opts.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.
@@ -270,20 +460,20 @@ function parseSurfaceList(raw) {
  * 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.
+ * each against RECOGNIZED_MODULES. Takes a PRESENT value only — an ABSENT
+ * `--modules` flag is `undefined` (#6759 D3: the key's level decides) and
+ * never reaches this function; an all-empty value (`--modules ""`,
+ * `--modules ,`) still names the Free set, spelled inline here.
  *
  * @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];
+        return ["marketing"];
     for (const m of requested) {
         if (!RECOGNIZED_MODULES.includes(m)) {
             throw new ParseError(`unknown module "${m}". Recognized: ${RECOGNIZED_MODULES.join(", ")}`);

package/dist/programmatic.d.ts

@@ -20,7 +20,7 @@ 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";
+import { type StarterDesign, type StarterShape } from "./template-manifest.js";
 export interface ScaffoldOptions {
     /** Absolute or relative path to the target directory. Must not exist or be empty. */
     targetDir: string;
@@ -36,9 +36,10 @@ export interface ScaffoldOptions {
      *
      * 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.
+     * (spec 5481 § 3 DD3): a call naming neither a template nor a `shape`
+     * takes a code path with no new statement in it — the bare overlay, the
+     * library's default. The CLI never takes that path (#6754 D2: it refuses a
+     * run naming neither, or asks for a shape on a terminal).
      *
      * What a template DOES change is `modules` — `scaffold()` unions the
      * template's `requires` with whatever `--modules` named and passes THAT
@@ -46,6 +47,13 @@ export interface ScaffoldOptions {
      * `architecture.yaml` and the generated nav are all functions of the union.
      */
     template?: string;
+    /**
+     * The starter shape to install (`--shape`, #6754 D5): `scaffold()` resolves
+     * it to the one template of that shape whose delivery is `free`, then runs
+     * exactly as a `template` naming it would. Mutually exclusive with
+     * `template`. A shape with no Free starter yet is refused (D6).
+     */
+    shape?: StarterShape;
     /**
      * Selected modules (recognized: marketing, docs-blog, multi-tenant,
      * scheduling). Defaults to
@@ -112,10 +120,11 @@ export interface ScaffoldOptions {
     /**
      * 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
+     * `design`; a caller may name one to OVERRIDE the template's — the
      * 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.
+     * DD-4), and the CLI's `--design` beside `--shape` (#6754). Unset (every
+     * existing `scaffoldSync` caller) resolves exactly as before. Gated
+     * (#6760): a design outside `FREE_DESIGNS` needs a Pro or Pro Plus level.
      */
     design?: StarterDesign;
 }
@@ -126,6 +135,21 @@ export interface ScaffoldResult {
     filesCreated: number;
     /** The gateable route surfaces this scaffold declares (sorted). */
     surfaces: string[];
+    /**
+     * The starter this scaffold resolved (#6754 D5) — set whenever a template
+     * was resolved, from `template` or from `shape`; absent for the bare overlay.
+     */
+    starter?: {
+        template: string;
+        shape: StarterShape;
+        design: StarterDesign;
+    };
+    /**
+     * The effective module set this scaffold installed (#6759 D6) — what
+     * `scaffoldSync` actually received, never the requested `--modules` alone:
+     * a keyed run with no `--modules` carries the key's derived level here.
+     */
+    modules: ModuleName[];
 }
 /**
  * Scaffold an AI Launch Kit starter project into targetDir (synchronous).
@@ -152,8 +176,14 @@ export declare function scaffoldSync(opts: ScaffoldOptions): ScaffoldResult;
  *      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
+ * Between 2 and 3, `assertDesignAllowed` (#6760) refuses a design the caller
+ * CHOSE (`opts.design`) for a level below Pro, HERE, also before anything is
+ * written to disk. A template's own declared design is never gated (#6778
+ * option (c)): the template's `requires` already decide its level.
+ *
+ * And, ahead of all five when `opts.template` (or `opts.shape`, #6754 D5) 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