create-ailk 0.6.1 → 0.8.0

package/dist/category-profile.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The category profile (#6640; starter-template contract § D) — one YAML
+ * document per leaf category slug at `category-profiles/<slug>.yaml`, the data
+ * the `fill-page` skill reads to make one starter speak for one business type.
+ *
+ * Dependency-free by design: `create-ailk` ships `tar` as its only runtime
+ * dependency, so this is a hand-written validator in the style of
+ * `resolveTemplate`/`TemplateError`, not a Zod schema. The caller parses the
+ * YAML and injects the registries (page types, leaf categories); nothing here
+ * imports a workspace package at run time.
+ */
+import type { StarterShape } from "./template-manifest.js";
+/**
+ * The contract's shape table, as data: each shape's primary node, the
+ * secondaries it allows, and whether it is reserved. Keyed by the manifest's
+ * own `StarterShape`, so a shape added there without a row here fails
+ * type-check.
+ */
+export declare const CATEGORY_PROFILE_SHAPES: {
+    readonly "organization-product": {
+        readonly primary: "Organization";
+        readonly secondaries: readonly ["SoftwareApplication"];
+        readonly reserved: false;
+    };
+    readonly "organization-service": {
+        readonly primary: "Organization";
+        readonly secondaries: readonly [];
+        readonly reserved: false;
+    };
+    readonly "local-business-service": {
+        readonly primary: "LocalBusiness";
+        readonly secondaries: readonly ["Person"];
+        readonly reserved: false;
+    };
+    readonly "local-business-product": {
+        readonly primary: "LocalBusiness";
+        readonly secondaries: readonly [];
+        readonly reserved: true;
+    };
+    readonly "person-service": {
+        readonly primary: "Person";
+        readonly secondaries: readonly ["Organization"];
+        readonly reserved: false;
+    };
+};
+/**
+ * schema.org's `LocalBusiness` subtree, `LocalBusiness` itself included — the
+ * closure of the `LocalBusiness` union in `schema-dts`. A literal so `src/`
+ * needs no type package at run time; `category-profile.test.ts` proves it
+ * set-equal to the `schema-dts` closure, so it cannot drift silently.
+ */
+export declare const LOCAL_BUSINESS_TYPES: ReadonlySet<string>;
+export declare const OFFERING_PRICING: readonly ["quote", "fixed", "hourly", "subscription"];
+export declare const PROOF_KINDS: readonly ["credential", "reviews", "before-after", "response-time", "guarantee", "experience"];
+export declare const CONTENT_POSTURES: readonly ["instructions", "sample"];
+export interface CategoryOffering {
+    name: string;
+    job: string;
+    pricing: (typeof OFFERING_PRICING)[number];
+}
+export interface CategoryProof {
+    kind: (typeof PROOF_KINDS)[number];
+    label: string;
+}
+export type CategoryRosterDelta = {
+    op: "add";
+    route: string;
+    pageType: string;
+    reason: string;
+} | {
+    op: "drop";
+    route: string;
+    reason: string;
+};
+export interface CategoryIntakeItem {
+    id: string;
+    ask: string;
+    /** The section types an answer to this question can fill. */
+    fills: string[];
+}
+export interface CategoryProfile {
+    slug: string;
+    shape: StarterShape;
+    /** The schema.org subtype of the primary node; only on `local-business-*`. */
+    subtype?: string;
+    secondary?: string;
+    offerings: CategoryOffering[];
+    proof: CategoryProof[];
+    vocabulary: {
+        problem: string[];
+        service: string[];
+        outcome: string[];
+    };
+    roster: CategoryRosterDelta[];
+    /** Nav label → replacement label. Declared, not yet applied to a scaffold. */
+    nav: Record<string, string>;
+    content_posture: (typeof CONTENT_POSTURES)[number];
+    intake: CategoryIntakeItem[];
+}
+/** A recorded tier-2 intake — `content/_intake.yaml`. */
+export interface CategoryIntake {
+    answers: Record<string, string | string[] | null>;
+}
+export interface ParseCategoryProfileOptions {
+    /** The file's basename without `.yaml`; the profile's `slug` must equal it. */
+    fileSlug: string;
+    /** Registered page-type keys (the schema registry). */
+    pageTypes: ReadonlySet<string>;
+    /** Leaf category slugs (the category registry). */
+    categories: ReadonlySet<string>;
+}
+/** Thrown on an invalid profile or intake; the message names the failing field path. */
+export declare class CategoryProfileError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a parsed category profile.
+ * @throws CategoryProfileError naming the failing field path.
+ */
+export declare function parseCategoryProfile(raw: unknown, options: ParseCategoryProfileOptions): CategoryProfile;
+/**
+ * Validate a recorded intake (`content/_intake.yaml`) against its profile.
+ * Unknown ids fail; an id the file omits is returned as `null` (unanswered).
+ * @throws CategoryProfileError naming the failing field path.
+ */
+export declare function parseIntake(raw: unknown, profile: CategoryProfile): CategoryIntake;

package/dist/category-profile.js

@@ -0,0 +1,262 @@
+/**
+ * The contract's shape table, as data: each shape's primary node, the
+ * secondaries it allows, and whether it is reserved. Keyed by the manifest's
+ * own `StarterShape`, so a shape added there without a row here fails
+ * type-check.
+ */
+export const CATEGORY_PROFILE_SHAPES = {
+    "organization-product": {
+        primary: "Organization",
+        secondaries: ["SoftwareApplication"],
+        reserved: false,
+    },
+    "organization-service": {
+        primary: "Organization",
+        secondaries: [],
+        reserved: false,
+    },
+    "local-business-service": {
+        primary: "LocalBusiness",
+        secondaries: ["Person"],
+        reserved: false,
+    },
+    "local-business-product": {
+        primary: "LocalBusiness",
+        secondaries: [],
+        reserved: true,
+    },
+    "person-service": {
+        primary: "Person",
+        secondaries: ["Organization"],
+        reserved: false,
+    },
+};
+/**
+ * schema.org's `LocalBusiness` subtree, `LocalBusiness` itself included — the
+ * closure of the `LocalBusiness` union in `schema-dts`. A literal so `src/`
+ * needs no type package at run time; `category-profile.test.ts` proves it
+ * set-equal to the `schema-dts` closure, so it cannot drift silently.
+ */
+export const LOCAL_BUSINESS_TYPES = new Set([
+    "AccountingService", "AdultEntertainment", "AmusementPark", "AnimalShelter",
+    "ArchiveOrganization", "ArtGallery", "Attorney", "AutoBodyShop", "AutoDealer",
+    "AutoPartsStore", "AutoRental", "AutoRepair", "AutoWash", "AutomatedTeller",
+    "AutomotiveBusiness", "Bakery", "BankOrCreditUnion", "BarOrPub", "BeautySalon",
+    "BedAndBreakfast", "BikeStore", "BookStore", "BowlingAlley", "Brewery",
+    "CafeOrCoffeeShop", "Campground", "Casino", "ChildCare", "ClothingStore",
+    "ComedyClub", "CommunityHealth", "ComputerStore", "ConvenienceStore",
+    "CovidTestingFacility", "DaySpa", "Dentist", "DepartmentStore", "Dermatology",
+    "DietNutrition", "Distillery", "DryCleaningOrLaundry", "Electrician",
+    "ElectronicsStore", "Emergency", "EmergencyService", "EmploymentAgency",
+    "EntertainmentBusiness", "ExerciseGym", "FastFoodRestaurant", "FinancialService",
+    "FireStation", "Florist", "FoodEstablishment", "FurnitureStore", "GardenStore",
+    "GasStation", "GeneralContractor", "Geriatric", "GolfCourse", "GovernmentOffice",
+    "GroceryStore", "Gynecologic", "HVACBusiness", "HairSalon", "HardwareStore",
+    "HealthAndBeautyBusiness", "HealthClub", "HobbyShop", "HomeAndConstructionBusiness",
+    "HomeGoodsStore", "Hospital", "Hostel", "Hotel", "HousePainter", "IceCreamShop",
+    "IndividualPhysician", "InsuranceAgency", "InternetCafe", "JewelryStore",
+    "LegalService", "Library", "LiquorStore", "LocalBusiness", "Locksmith",
+    "LodgingBusiness", "MedicalBusiness", "MedicalClinic", "MensClothingStore",
+    "Midwifery", "MobilePhoneStore", "Motel", "MotorcycleDealer", "MotorcycleRepair",
+    "MovieRentalStore", "MovieTheater", "MovingCompany", "MusicStore", "NailSalon",
+    "NightClub", "Notary", "Nursing", "Obstetric", "OfficeEquipmentStore", "Oncologic",
+    "Optician", "Optometric", "Otolaryngologic", "OutletStore", "PawnShop", "Pediatric",
+    "PetStore", "Pharmacy", "Physician", "PhysiciansOffice", "Physiotherapy",
+    "PlasticSurgery", "Plumber", "Podiatric", "PoliceStation", "PostOffice",
+    "PrimaryCare", "ProfessionalService", "Psychiatric", "PublicHealth",
+    "PublicSwimmingPool", "RadioStation", "RealEstateAgent", "RecyclingCenter",
+    "Resort", "Restaurant", "RoofingContractor", "SelfStorage", "ShoeStore",
+    "ShoppingCenter", "SkiResort", "SportingGoodsStore", "SportsActivityLocation",
+    "SportsClub", "StadiumOrArena", "Store", "TattooParlor", "TelevisionStation",
+    "TennisComplex", "TireShop", "TouristInformationCenter", "ToyStore",
+    "TravelAgency", "VacationRental", "WholesaleStore", "Winery",
+]);
+export const OFFERING_PRICING = ["quote", "fixed", "hourly", "subscription"];
+export const PROOF_KINDS = [
+    "credential",
+    "reviews",
+    "before-after",
+    "response-time",
+    "guarantee",
+    "experience",
+];
+export const CONTENT_POSTURES = ["instructions", "sample"];
+/** Thrown on an invalid profile or intake; the message names the failing field path. */
+export class CategoryProfileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CategoryProfileError";
+    }
+}
+function fail(path, message) {
+    throw new CategoryProfileError(`${path}: ${message}`);
+}
+function object(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail(path, "must be a mapping");
+    }
+    return value;
+}
+function keys(value, path, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            fail(path === "" ? key : `${path}.${key}`, "unknown key");
+    }
+    for (const key of required) {
+        if (!(key in value))
+            fail(path === "" ? key : `${path}.${key}`, "is required");
+    }
+}
+function string(value, path) {
+    if (typeof value !== "string" || value.trim() === "")
+        fail(path, "must be a non-empty string");
+    return value;
+}
+function oneOf(value, allowed, path) {
+    if (!allowed.includes(value)) {
+        fail(path, `must be one of ${allowed.join(", ")} (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+function list(value, path, nonEmpty) {
+    if (!Array.isArray(value))
+        fail(path, "must be a list");
+    if (nonEmpty && value.length === 0)
+        fail(path, "must not be empty");
+    return value;
+}
+function strings(value, path) {
+    return list(value, path, true).map((item, i) => string(item, `${path}[${i}]`));
+}
+/**
+ * Validate a parsed category profile.
+ * @throws CategoryProfileError naming the failing field path.
+ */
+export function parseCategoryProfile(raw, options) {
+    const doc = object(raw, "(profile)");
+    keys(doc, "", ["slug", "shape", "offerings", "proof", "vocabulary", "roster", "nav", "content_posture", "intake"], ["subtype", "secondary"]);
+    const slug = string(doc.slug, "slug");
+    if (!options.categories.has(slug))
+        fail("slug", `"${slug}" is not a leaf category slug`);
+    if (slug !== options.fileSlug) {
+        fail("slug", `"${slug}" does not match its file name "${options.fileSlug}.yaml"`);
+    }
+    const shapes = Object.keys(CATEGORY_PROFILE_SHAPES);
+    const shape = oneOf(doc.shape, shapes, "shape");
+    const shapeRow = CATEGORY_PROFILE_SHAPES[shape];
+    if (shapeRow.reserved)
+        fail("shape", `"${shape}" is reserved and not yet built`);
+    let subtype;
+    if (shapeRow.primary === "LocalBusiness") {
+        subtype = string(doc.subtype, "subtype");
+        if (!LOCAL_BUSINESS_TYPES.has(subtype)) {
+            fail("subtype", `"${subtype}" is not a schema.org LocalBusiness subtype`);
+        }
+    }
+    else if (doc.subtype !== undefined) {
+        fail("subtype", `is only valid on a local-business-* shape, not "${shape}"`);
+    }
+    let secondary;
+    if (doc.secondary !== undefined) {
+        if (shapeRow.secondaries.length === 0)
+            fail("secondary", `is not allowed on "${shape}"`);
+        secondary = oneOf(doc.secondary, shapeRow.secondaries, "secondary");
+    }
+    const offerings = list(doc.offerings, "offerings", true).map((item, i) => {
+        const path = `offerings[${i}]`;
+        const o = object(item, path);
+        keys(o, path, ["name", "job", "pricing"]);
+        return {
+            name: string(o.name, `${path}.name`),
+            job: string(o.job, `${path}.job`),
+            pricing: oneOf(o.pricing, OFFERING_PRICING, `${path}.pricing`),
+        };
+    });
+    const proof = list(doc.proof, "proof", true).map((item, i) => {
+        const path = `proof[${i}]`;
+        const p = object(item, path);
+        keys(p, path, ["kind", "label"]);
+        return { kind: oneOf(p.kind, PROOF_KINDS, `${path}.kind`), label: string(p.label, `${path}.label`) };
+    });
+    const vocab = object(doc.vocabulary, "vocabulary");
+    keys(vocab, "vocabulary", ["problem", "service", "outcome"]);
+    const vocabulary = {
+        problem: strings(vocab.problem, "vocabulary.problem"),
+        service: strings(vocab.service, "vocabulary.service"),
+        outcome: strings(vocab.outcome, "vocabulary.outcome"),
+    };
+    const roster = list(doc.roster ?? [], "roster", false).map((item, i) => {
+        const path = `roster[${i}]`;
+        const r = object(item, path);
+        const op = oneOf(r.op, ["add", "drop"], `${path}.op`);
+        const route = string(r.route, `${path}.route`);
+        if (!route.startsWith("/"))
+            fail(`${path}.route`, `must start with "/"`);
+        if (op === "drop") {
+            keys(r, path, ["op", "route", "reason"]);
+            return { op, route, reason: string(r.reason, `${path}.reason`) };
+        }
+        keys(r, path, ["op", "route", "pageType", "reason"]);
+        const pageType = string(r.pageType, `${path}.pageType`);
+        if (!options.pageTypes.has(pageType)) {
+            fail(`${path}.pageType`, `"${pageType}" is not a registered page type`);
+        }
+        return { op, route, pageType, reason: string(r.reason, `${path}.reason`) };
+    });
+    const navDoc = doc.nav === null ? {} : object(doc.nav, "nav");
+    const nav = Object.fromEntries(Object.entries(navDoc).map(([from, to]) => [from, string(to, `nav.${from}`)]));
+    const ids = new Set();
+    const intake = list(doc.intake, "intake", true).map((item, i) => {
+        const path = `intake[${i}]`;
+        const q = object(item, path);
+        keys(q, path, ["id", "ask", "fills"]);
+        const id = string(q.id, `${path}.id`);
+        if (ids.has(id))
+            fail(`${path}.id`, `"${id}" is not unique`);
+        ids.add(id);
+        return { id, ask: string(q.ask, `${path}.ask`), fills: strings(q.fills, `${path}.fills`) };
+    });
+    return {
+        slug,
+        shape,
+        ...(subtype !== undefined ? { subtype } : {}),
+        ...(secondary !== undefined ? { secondary } : {}),
+        offerings,
+        proof,
+        vocabulary,
+        roster,
+        nav,
+        content_posture: oneOf(doc.content_posture, CONTENT_POSTURES, "content_posture"),
+        intake,
+    };
+}
+/**
+ * Validate a recorded intake (`content/_intake.yaml`) against its profile.
+ * Unknown ids fail; an id the file omits is returned as `null` (unanswered).
+ * @throws CategoryProfileError naming the failing field path.
+ */
+export function parseIntake(raw, profile) {
+    const doc = object(raw, "(intake)");
+    keys(doc, "", ["answers"]);
+    const given = doc.answers === null ? {} : object(doc.answers, "answers");
+    const known = new Set(profile.intake.map((q) => q.id));
+    for (const id of Object.keys(given)) {
+        if (!known.has(id))
+            fail(`answers.${id}`, "is not an intake id of this profile");
+    }
+    const answers = {};
+    for (const { id } of profile.intake) {
+        const value = given[id];
+        const path = `answers.${id}`;
+        if (value === undefined || value === null)
+            answers[id] = null;
+        else if (typeof value === "string")
+            answers[id] = value.trim() === "" ? null : value;
+        else if (Array.isArray(value))
+            answers[id] = value.map((v, i) => string(v, `${path}[${i}]`));
+        else
+            fail(path, "must be a string, a list of strings, or null");
+    }
+    return { answers };
+}

package/dist/cli.js

@@ -3,8 +3,12 @@
  * `create-ailk` — entry point.
  *
  * Orchestration:
- *   0. on a `sync-routes` subcommand: parse its own argv, run syncRoutesSync(),
+ *   0. on an `add-module` / `upgrade` subcommand: parse its own argv, run
+ *      addModule(), print the report, exit (2 on a refusal it names)
+ *      on a `sync-routes` subcommand: parse its own argv, run syncRoutesSync(),
  *      print the report, exit (1 iff routes are missing in check mode)
+ *      on a `license set` subcommand: write the key into the scaffold, push it
+ *      to a linked Vercel project and redeploy, exit (#6683 D9)
  *   1. parse argv → CliOptions
  *   2. on --help: print helpText, exit 0
  *   3. on --version: print version, exit 0
@@ -30,9 +34,11 @@ import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { proCallout } from "./lib/pro-callout.js";
-import { helpText, parseCliArgs, parseModules } from "./parse-args.js";
-import { formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncRoutesSync, } from "./programmatic.js";
+import { ADD_MODULE_HELP, AddModuleRefusedError, formatAddModuleReport, parseAddModuleArgs, } from "./add-module.js";
+import { FREE_PREREQUISITES_NOTE, LICENSED_PREREQUISITES_NOTE, isLicensedInstall, proCallout, } from "./lib/pro-callout.js";
+import { LICENSE_SET_HELP, runLicenseSet } from "./license-set.js";
+import { helpText, parseCliArgs, parseModules, resolveCliShape, toScaffoldOptions, } from "./parse-args.js";
+import { addModule, formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncRoutesSync, } from "./programmatic.js";
 import { CORE_SURFACE_PATHS, SURFACE_ALIASES } from "./surfaces.js";
 import { SYNC_ROUTES_HELP, formatSyncRoutesReport, parseSyncRoutesArgs, } from "./sync-routes.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -83,6 +89,32 @@ function readScaffoldPrerequisites(targetAbs) {
 }
 async function main() {
     const argv = process.argv.slice(2);
+    // `add-module` (alias `upgrade`, #6653): apply a purchased module to an
+    // existing site. Its own argv shape, like `sync-routes` below. A refusal it
+    // names (a free module, a patch outside the config allowlist, an unreadable
+    // architecture.yaml) exits 2; anything else — the licence gate included —
+    // falls through to the top-level catch, exit 1, as a scaffold would.
+    if (argv[0] === "add-module" || argv[0] === "upgrade") {
+        const args = parseAddModuleArgs(argv.slice(1));
+        if (args.help || args.module === undefined) {
+            process.stdout.write(ADD_MODULE_HELP);
+            process.exit(0);
+        }
+        try {
+            const result = await addModule({
+                targetDir: args.target ?? process.cwd(),
+                moduleName: args.module,
+            });
+            process.stdout.write(formatAddModuleReport(result, args.module));
+        }
+        catch (err) {
+            if (!(err instanceof AddModuleRefusedError))
+                throw err;
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(err.exitCode);
+        }
+        process.exit(0);
+    }
     // Subcommand dispatch, ahead of the flag parser: `sync-routes` has its own
     // argv shape (#4986). Check mode exits 1 iff a template route is missing;
     // locally modified routes are reported but do not fail; --apply exits 0.
@@ -99,7 +131,19 @@ async function main() {
         process.stdout.write(formatSyncRoutesReport(result, args.apply));
         process.exit(!args.apply && result.missing.length > 0 ? 1 : 0);
     }
-    const opts = parseCliArgs(argv);
+    // `license set <key|-> [dir]` (#6683 D9): its own argv shape, ahead of the
+    // flag parser like `sync-routes`. The key reaches `vercel` on stdin only.
+    if (argv[0] === "license" && argv[1] === "set") {
+        process.exit(runLicenseSet(argv.slice(2), {
+            cwd: process.cwd(),
+            stdout: (text) => process.stdout.write(text),
+            stderr: (text) => process.stderr.write(text),
+            readStdin: () => readFileSync(0, "utf8"),
+        }));
+    }
+    // No silent default (#6754 D2/D3): a scaffold run naming neither --shape
+    // nor --template asks for a shape on a terminal and is refused without one.
+    const opts = await resolveCliShape(parseCliArgs(argv, { interactive: process.stdin.isTTY === true }), { input: process.stdin, output: process.stdout });
     // Deprecation notice for a retired `--surfaces` id (#5563 D2). `surfaces.ts`
     // stays pure — `canonicalizeSurface` only resolves the alias — so this is
     // the one place that prints: compare the raw `--surfaces` argv token
@@ -118,7 +162,13 @@ async function main() {
         }
     }
     if (opts.help) {
-        process.stdout.write(helpText + "\n" + SYNC_ROUTES_HELP);
+        process.stdout.write(helpText +
+            "\n" +
+            SYNC_ROUTES_HELP +
+            "\n" +
+            ADD_MODULE_HELP +
+            "\n" +
+            LICENSE_SET_HELP);
         process.exit(0);
     }
     if (opts.version) {
@@ -161,22 +211,16 @@ async function main() {
     // scaffold() gates + fetches any requested paid module (K1, #5089) and any
     // named site template's own bundle (#5481), then validates and copies the
     // local template — throws ValidationError or LicenseRequiredError on
-    // rejection (caught at top level below). Neither AILK_LICENSE_KEY nor
-    // either registry URL is read, and no network call is made, when the
-    // effective module set names no paid module — the regression floor, which
-    // `--template marketing-site-free` deliberately rides (record D11): its
+    // rejection (caught at top level below). The network invariant (#6759 D6):
+    // no key → no request at all; a key with no --modules → the D4 level probe
+    // (3-4 requests); an explicit --modules list → requests only for the paid
+    // modules it names, exactly as before this card. `--template
+    // marketing-site-free` still rides the no-key case (record D11): its
     // `requires` is all-free, so it installs from the shipped
     // `site-templates/` tree with no key and no request.
-    const { targetDir: targetAbs, surfaces } = await scaffold({
-        targetDir: opts.target,
-        modules: opts.modules,
-        surfaces: opts.surfaces,
-        withCatalog: opts.withCatalog,
-        // Spread rather than passed as `undefined` so a run naming no template
-        // hands `scaffold()` exactly the option object it got before the flag
-        // existed (spec 5481 § 3 DD3's byte-identity floor).
-        ...(opts.template !== undefined ? { template: opts.template } : {}),
-    });
+    const { targetDir: targetAbs, surfaces, starter, modules: effectiveModules, } = await scaffold(toScaffoldOptions(opts));
+    // The starter scaffold() resolved — from --template, or from --shape (#6754 D4).
+    const templateName = starter?.template ?? opts.template;
     if (opts.install) {
         // Hard-coded argv. User input only flows through `cwd`, never the command.
         const result = spawnSync("pnpm", ["install"], {
@@ -188,19 +232,28 @@ async function main() {
             throw new Error(`pnpm install failed in ${targetAbs} (exit ${result.status}). Run it manually after fixing the issue.`);
         }
     }
-    // Next-steps message.
+    // Next-steps message. A licensed install (#6480) is not told it needs no
+    // licence key, and is not pitched the Pro tier it already owns. Reads the
+    // EFFECTIVE module set (#6759 D6) — result.modules already carries any
+    // template's requires and the key's derived level, so it stays correct for
+    // a keyed default scaffold, which opts.modules alone would not have shown.
+    const licensed = isLicensedInstall({ modules: effectiveModules });
     const lines = [
         "",
-        opts.template !== undefined
-            ? `Scaffolded AI Launch Kit starter from the "${opts.template}" template.`
+        templateName !== undefined
+            ? `Scaffolded AI Launch Kit starter from the "${templateName}" template.`
             : "Scaffolded AI Launch Kit starter.",
+        ...(starter !== undefined
+            ? [`Starter: shape ${starter.shape}, design ${starter.design}.`]
+            : []),
         "",
     ];
     // Prerequisites (#6440 AC4) — every one the scaffold enforces, and nothing
     // it does not. A starter reaches `pnpm dev` AND `pnpm build` on a toolchain
     // alone: the Prisma client is generated by `database`'s own `postinstall`,
-    // so there is no generator step to remember, and no database, licence key or
-    // vendor API key gates either command. Saying so is the point — the previous
+    // so there is no generator step to remember, and no database or vendor API
+    // key gates either command (a free install also says no licence key does;
+    // a licensed one, #6480, does not). Saying so is the point — the previous
     // output named no prerequisites at all, which left a customer to discover
     // the toolchain floor from a failure.
     const prereqs = readScaffoldPrerequisites(targetAbs);
@@ -210,7 +263,12 @@ async function main() {
     ].filter((part) => part !== undefined);
     if (toolchain.length > 0) {
         lines.push(`Prerequisites: ${toolchain.join(" and ")} — that is all.`);
-        lines.push("No database, no licence key and no vendor API key are needed to run or build this site.");
+        lines.push(licensed ? LICENSED_PREREQUISITES_NOTE : FREE_PREREQUISITES_NOTE);
+        lines.push("");
+    }
+    // Only when asked for (#6683 D9) — a run without --license is unchanged.
+    if (opts.license !== undefined) {
+        lines.push("Licence key written to apps/api/.env and ailk.key (owner-only, gitignored).");
         lines.push("");
     }
     lines.push("Next steps:");
@@ -226,15 +284,17 @@ async function main() {
     lines.push("");
     lines.push(`Route surfaces: ${CORE_SURFACE_PATHS.join(", ")}` +
         (surfaces.length > 0 ? ` + ${surfaces.join(", ")}` : ""));
-    lines.push("Add another with the `scaffold-page` skill, or re-run with --surfaces <id>.");
+    lines.push("Add another with the `add-page` skill, or re-run with --surfaces <id>.");
     // Only when asked for. The default scaffold's output is unchanged.
     if (opts.withCatalog) {
         lines.push("Component catalog: COMPONENT-CATALOG.md — search it by capability before building a component.");
     }
     lines.push("Reference: ADR 0007 — pnpm create ailk@latest is the canonical install path.");
     lines.push("");
-    lines.push(proCallout());
-    lines.push("");
+    if (!licensed) {
+        lines.push(proCallout());
+        lines.push("");
+    }
     process.stdout.write(lines.join("\n"));
 }
 main().catch((err) => {

package/dist/index.d.ts

@@ -5,9 +5,11 @@
  */
 export { copyTemplate, type CopyTemplateOptions } from "./copy.js";
 export { parseCliArgs, parseModules, ParseError, helpText, RECOGNIZED_MODULES, type ModuleName, type CliOptions, } from "./parse-args.js";
-export { CATALOG_TARGET_PATH, FREE_MODULES, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncRoutesSync, type ResolvePaidModulesOptions, type ScaffoldOptions, type ScaffoldResult, type SyncArchitectureOptions, type SyncArchitectureResult, type SyncCatalogResult, type SyncRoutesSyncOptions, } from "./programmatic.js";
+export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncRoutesSync, type AddModuleOptions, type ResolvePaidModulesOptions, type ScaffoldOptions, type ScaffoldResult, type SyncArchitectureOptions, type SyncArchitectureResult, type SyncCatalogResult, type SyncRoutesSyncOptions, } from "./programmatic.js";
 export { DEFAULT_AILK_MODULE_REGISTRY_URL, FetchModuleError, fetchModule, type FetchModuleOptions, } from "./lib/fetch-module.js";
-export { extractModuleBundle, type ExtractModuleBundleOptions, } from "./lib/extract-module-bundle.js";
+export { extractModuleBundle, type ExistingFilePolicy, type ExtractModuleBundleOptions, type InstallReportRow, } from "./lib/extract-module-bundle.js";
+export { ADD_MODULE_HELP, AddModuleRefusedError, applyModuleToScaffold, formatAddModuleReport, parseAddModuleArgs, type AddModuleReportRow, type AddModuleResult, type ApplyModuleOptions, } from "./add-module.js";
+export { SITE_ROSTER_PATH, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
 export { SYNC_ROUTES_HELP, formatSyncRoutesReport, listTemplateRouteDirs, parseSyncRoutesArgs, syncRoutes, type RouteReport, type SyncRoutesOptions, type SyncRoutesResult, } from "./sync-routes.js";
 export { deriveArchitecture } from "./derive-architecture.js";
 export { CORE_ROUTE_DIRS, CORE_SURFACE_PATHS, NAV_CONFIG_PATH, GATEABLE_SURFACES, MODULE_SURFACES, RECOGNIZED_SURFACES, ROUTE_SINCE, SurfaceError, excludedContentPaths, excludedRoutePaths, parseSurfaces, renderNavConfig, resolveSurfaces, surfaceForRouteDir, type Surface, } from "./surfaces.js";

package/dist/index.js

@@ -5,12 +5,17 @@
  */
 export { copyTemplate } from "./copy.js";
 export { parseCliArgs, parseModules, ParseError, helpText, RECOGNIZED_MODULES, } from "./parse-args.js";
-export { CATALOG_TARGET_PATH, FREE_MODULES, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncRoutesSync, } from "./programmatic.js";
+export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, LicenseRequiredError, PAID_MODULES, classifyModules, formatSurfaceDrift, scaffold, scaffoldSync, syncArchitectureSync, syncCatalogSync, syncRoutesSync, } from "./programmatic.js";
 // The paid-module fetch/extract primitives (K1, #5089 — Flavor 3). Exported
 // so tooling (and this repo's own evidence-run scripts) can drive the fetch
 // path directly without re-implementing its shape.
 export { DEFAULT_AILK_MODULE_REGISTRY_URL, FetchModuleError, fetchModule, } from "./lib/fetch-module.js";
 export { extractModuleBundle, } from "./lib/extract-module-bundle.js";
+// `create-ailk add-module` (#6653) — apply a purchased module to an existing
+// site in place. The pure core, beside `sync-routes`'s.
+export { ADD_MODULE_HELP, AddModuleRefusedError, applyModuleToScaffold, formatAddModuleReport, parseAddModuleArgs, } from "./add-module.js";
+// The site's page roster of record and its install-diff check (#6682).
+export { SITE_ROSTER_PATH, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
 // `create-ailk sync-routes` (#4986) — the template-route drift check + copy.
 // The pure module is exported so tooling can run it against any template dir.
 export { SYNC_ROUTES_HELP, formatSyncRoutesReport, listTemplateRouteDirs, parseSyncRoutesArgs, syncRoutes, } from "./sync-routes.js";