create-ailk 0.7.0 → 0.8.0

package/component-catalog.md

@@ -15,13 +15,13 @@ The component inventory of `@working-theory/ui` and the shells of `@working-theo
 3. Check the Primitives, Panels and Shells tables too — a low-level control, a collapsible layout container, or a route-level frame lives there, not under Sections or Blocks.
 4. Only then build. If you do build, you are declaring the capability is genuinely absent.
 
-Inventory: **300 component files** across 16 tiers — 54 sections, 97 blocks, 18 chrome, 79 primitives, 6 panels, 5 shells, 5 docs-blog-blocks, 1 docs-blog-chrome, 2 docs-blog-shells, 2 scheduling-sections, 5 scheduling-blocks, 3 signal-collectors-sections, 8 signal-collectors-blocks, 2 commerce-sections, 12 commerce-blocks, 1 commerce-panels. 297 distinct names: `SchedulerEmbed`, `Separator`, `Tabs` exist in more than one tier as genuinely different components, listed once per tier with its own source path.
+Inventory: **303 component files** across 16 tiers — 55 sections, 99 blocks, 18 chrome, 79 primitives, 6 panels, 5 shells, 5 docs-blog-blocks, 1 docs-blog-chrome, 2 docs-blog-shells, 2 scheduling-sections, 5 scheduling-blocks, 3 signal-collectors-sections, 8 signal-collectors-blocks, 2 commerce-sections, 12 commerce-blocks, 1 commerce-panels. 300 distinct names: `SchedulerEmbed`, `Separator`, `Tabs` exist in more than one tier as genuinely different components, listed once per tier with its own source path.
 
-Description coverage: **296/300** components carry a capability description derived from source — 43 from the section registry's hand-authored when-to-use text, 222 from the component's own doc-comment header, 31 from its tier barrel's roster line. **4** have none; they are listed under [Undescribed components](#undescribed-components) rather than given a sentence invented from their name.
+Description coverage: **299/303** components carry a capability description derived from source — 44 from the section registry's hand-authored when-to-use text, 224 from the component's own doc-comment header, 31 from its tier barrel's roster line. **4** have none; they are listed under [Undescribed components](#undescribed-components) rather than given a sentence invented from their name.
 
-Of those, **265** are *strong* — a capability sentence you could match a requirement against — and **31** are *weak*: either one short clause, or a long one that spends itself on wiring (client boundaries, class names, which primitives it composes) instead of on what the thing is for. Weak rows are marked `(weak)` and listed in full under [Weak descriptions](#weak-descriptions). Coverage is 99%, but **findable-without-luck coverage is 88%**.
+Of those, **268** are *strong* — a capability sentence you could match a requirement against — and **31** are *weak*: either one short clause, or a long one that spends itself on wiring (client boundaries, class names, which primitives it composes) instead of on what the thing is for. Weak rows are marked `(weak)` and listed in full under [Weak descriptions](#weak-descriptions). Coverage is 99%, but **findable-without-luck coverage is 88%**.
 
-Per tier, strong out of total: **Sections** 53/54 · **Blocks** 91/97 · **Chrome** 10/18 · **Primitives** 64/79 (4 undescribed) · **Panels** 5/6 · **Shells** 4/5 · **Docs + Blog Blocks** 5/5 · **Docs + Blog Chrome** 1/1 · **Docs + Blog Shells** 0/2 · **Scheduling Sections** 2/2 · **Scheduling Blocks** 5/5 · **Signal-Collectors Sections** 3/3 · **Signal-Collectors Blocks** 7/8 · **Commerce Sections** 2/2 · **Commerce Blocks** 12/12 · **Commerce Panels** 1/1. A tier low on this line is a tier where a capability search is most likely to come up empty on something that exists.
+Per tier, strong out of total: **Sections** 54/55 · **Blocks** 93/99 · **Chrome** 10/18 · **Primitives** 64/79 (4 undescribed) · **Panels** 5/6 · **Shells** 4/5 · **Docs + Blog Blocks** 5/5 · **Docs + Blog Chrome** 1/1 · **Docs + Blog Shells** 0/2 · **Scheduling Sections** 2/2 · **Scheduling Blocks** 5/5 · **Signal-Collectors Sections** 3/3 · **Signal-Collectors Blocks** 7/8 · **Commerce Sections** 2/2 · **Commerce Blocks** 12/12 · **Commerce Panels** 1/1. A tier low on this line is a tier where a capability search is most likely to come up empty on something that exists.
 
 That grade is **mechanical**. It counts what it can measure — how much a description adds beyond the component's own name, how much of it is spent on wiring, whether the extraction came out damaged — and it cannot tell a fluent paragraph about the wrong subject from a useful one. A person reading these tables will find more rows unusable than the weak count admits. Treat it as a floor on the problem, not a measurement of it, and read the source before concluding a capability is absent.
 
@@ -53,7 +53,7 @@ The left column is search vocabulary — how a person phrases the need. It is ha
 
 ---
 
-## Sections (54)
+## Sections (55)
 
 Page-level content bands. Most are MDX-driven (authored by `type` in page frontmatter and dispatched by `SectionRenderer`); a few are composed directly in a route.
 
@@ -66,6 +66,7 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 | `AskAi` | Use above the footer — hands the visitor to a third-party AI seeded with the entity question. Bounded to five measured providers (ChatGPT/Claude/Google AI/Grok/Perplexity), each deep-linked with an authored prompt. The `ticker` variant renders a compact full-width band instead of the default headline/description/provider-row layout. | MDX `type: ask-ai` |
 | `AuthPanel` | A sign-in/sign-up panel with an optional bounded OAuth provider row (google, github) — UI-contract only, no auth backend; submit and provider clicks are callback props the composing page wires up. | MDX `type: auth-panel` · `import { AuthPanel } from "@working-theory/ui/sections"` |
 | `Awards` | A two-column evidence band — headline/CTA left, up to 5 award or press badges right — use for third-party recognition (badges may render as labeled placeholders until real marks are supplied). | MDX `type: awards` |
+| `BeforeAfter` | A before/after comparison — use on a case-study or portfolio page to show what a client had and what they have now: two labeled panels behind a Side-by-side / Before / After selector, each body an image or rows of content, with an optional catalyst column between them and a key-takeaway box below. | MDX `type: before-after` · `import { BeforeAfter } from "@working-theory/ui/sections"` |
 | `BentoGrid` | A mixed-span mosaic of feature cards — use for a visually varied capability overview. | MDX `type: bento-grid` · `import { BentoGrid } from "@working-theory/ui/sections"` |
 | `BlogList` | A blog post list with pagination — use for the blog index page only. | MDX `type: blog-list` · `import { BlogList } from "@working-theory/ui/sections"` |
 | `BlogPost` | A single blog post body with TOC and related posts — use only on the blog-post chassis. | MDX `type: blog-post` · `import { BlogPost } from "@working-theory/ui/sections"` |
@@ -118,7 +119,7 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 
 ---
 
-## Blocks (97)
+## Blocks (99)
 
 Intermediate composition tiles — the pieces sections are built from. Compose primitives and panels; never import a section.
 
@@ -150,6 +151,7 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `ConsentSettingsButton` | Footer "Cookie settings" control. Lets a visitor who already accepted/declined change their mind later, from the footer, without reloading the page. Lives at the BLOCKS tier (not chrome) so `FooterBottomBar` (a block) can render it without an upward import; `BannerConsentIsland` (chrome) imports the exported event constant DOWNWARD, per the component tier hierarchy. | internal — compose from `packages/ui/src/blocks/ConsentSettingsButton.tsx` |
 | `ConsentStatement` | The sentence a person agrees to, with its policy links inline. | `import { ConsentStatement } from "@working-theory/ui/blocks"` |
 | `ContactChannelItem` | Renders one support channel entry: colored icon square + headline + description paragraph + CTA link (with trailing arrow icon). | `import { ContactChannelItem } from "@working-theory/ui/blocks"` |
+| `ContactFallback` | The contact email in place of a contact form. Shown when a site cannot take messages through its form: in production with neither a database nor an email key, the page renders this instead, and `LeadCaptureForm`'s `unavailable` state renders this same markup when a submit is refused — so the two fallbacks are one component. | `import { ContactFallback } from "@working-theory/ui/blocks"` |
 | `ContactFormFields` | Renders the form field grid (Input / Textarea / Select primitives) + submit Button + optional consent text footer. | `import { ContactFormFields } from "@working-theory/ui/blocks"` |
 | `ContactInfoAside` | For ContactForm 'split-with-pattern' variant. Renders address / phone / email contact info rows. Each row: sr-only <dt> label + visible <dd> with Icon + Text. Phone and email render as tel:/mailto: links (click-to-call / click-to-email). | `import { ContactInfoAside } from "@working-theory/ui/blocks"` |
 | `ConversationalIntake` | The UI half of the conversational-intake feature: renders the transcript, closed-question answer pills, a free-text form, a thinking indicator, and Skip — driven entirely through the `NextTurn` interface exported by `./engine` (merged). | `import { ConversationalIntake } from "@working-theory/ui/blocks"` |
@@ -167,6 +169,7 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `FormCard` | Stateless, centered max-w-md form-card chassis: a Card wrapping an optional title + description header, a field-stack body (children), and a footer slot for the primary action + a secondary line below it. The SHARED look composed by both the contact-form section's 'card' variant and the auth-panel section — this block owns none of their field/state machinery, only the surrounding chrome. | `import { FormCard } from "@working-theory/ui/blocks"` |
 | `InviteMemberDialog` | The invite modal — reimplements the ploy.ai "Invite Team Member" capture (Email textbox + Role select, default Member, options Member/Admin, helper "Admins can invite and remove members." + Send Invitation). | `import { InviteMemberDialog } from "@working-theory/ui/blocks"` |
 | `KeyPointsPanel` | ONE shared block composed by two consumers: Hero's `panel` variant (text-left / panel-right) and Pricing's `band-hero` arrangement (header-left / panel-right, tiers below). | internal — compose from `packages/ui/src/blocks/KeyPointsPanel.tsx` |
+| `LeadCaptureForm` | The one contact form every template renders. Submits ONLY through the `action` prop — a Server Action the page binds — so there is no fetch, no URL and no browser-side JSON here. | `import { LeadCaptureForm } from "@working-theory/ui/blocks"` |
 | `LinkCard` | A whole-tile link card: the entire tile IS the anchor (Claude-docs link-card anatomy). Optional leading icon, a title heading, and an optional description paragraph. Hover fill + chrome are intrinsic to the block — never props. | `import { LinkCard } from "@working-theory/ui/blocks"` |
 | `LinkListItem` | Hub-page spoke list row: prose Link + optional description, enlarged to the 44px touch-target floor. Fix: the enlarged-hit-area pattern (same idiom as ShortcutTrigger, SegmentedControl's touchTargetFloor) — `min-h-(control-height-big)` clamps the anchor's clickable box to 44px while `inline-flex items-center` keeps the visible text at its normal prose size. | `import { LinkListItem } from "@working-theory/ui/blocks"` |
 | `ListRow` | The PHONE form of one admin list item. The reference is `apps-paid/admin/design/demos/first-steps/demo.html:475` (`rowDoc`), which lays the row out as: a leading type glyph, a two-line text column with the MUTED META LINE FIRST and the item's name second (every phone screen in the demo agrees), an optional trailing control, and a chevron. | `import { ListRow } from "@working-theory/ui/blocks"` |

package/dist/cli.js

@@ -37,7 +37,7 @@ import { fileURLToPath } from "node:url";
 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 } from "./parse-args.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";
@@ -141,7 +141,9 @@ async function main() {
             readStdin: () => readFileSync(0, "utf8"),
         }));
     }
-    const opts = parseCliArgs(argv);
+    // 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
@@ -209,23 +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 } : {}),
-        ...(opts.license !== undefined ? { license: opts.license } : {}),
-    });
+    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"], {
@@ -238,16 +233,19 @@ async function main() {
         }
     }
     // 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.
-    const licensed = isLicensedInstall({
-        ...(opts.template !== undefined ? { template: opts.template } : {}),
-        modules: opts.modules,
-    });
+    // 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

package/dist/lib/extract-module-bundle.js

@@ -655,6 +655,11 @@ export function installBundleTree(options) {
  * path-safety check is needed here — `srcRoot` is our own staging tree, not
  * attacker-controlled input.
  *
+ * A directory is created only as the parent of a file actually copied, never
+ * for its own sake: a source directory whose every file is excluded (mapped
+ * away) leaves nothing behind at its original path (#6787 — an empty root
+ * `content/en/blog/` reads as an unregistered page type).
+ *
  * `markers`, when given, is substituted into every TEXT file on the way
  * through (#6460) — see `InstallBundleTreeOptions.markers`.
  */
@@ -669,7 +674,6 @@ function copyTree(srcRoot, destRoot, excluded, markers, policy, report) {
             const rel = relative(srcRoot, srcPath);
             const destPath = join(destRoot, rel);
             if (entry.isDirectory()) {
-                mkdirSync(destPath, { recursive: true });
                 stack.push(srcPath);
             }
             else if (entry.isFile()) {

package/dist/lib/module-license-gate.d.ts

@@ -16,8 +16,14 @@
  * `resolvePaidModules` returns immediately, before touching `process.env` or
  * the network, so a bare/all-Free scaffold is provably unaffected by this
  * gate (K1's regression floor).
+ *
+ * Also carries the design gate (#6760): `assertDesignAllowed` refuses a
+ * non-`standard` design at the `free` level, naming the design and the
+ * run's level, before `scaffold()`'s first disk write.
  */
 import type { ModuleName } from "../parse-args.js";
+import type { StarterDesign } from "../template-manifest.js";
+import { type Level } from "./module-tier.js";
 /**
  * Where a refused run sends the buyer. `/pricing`, not `/pro`: there is no
  * `/pro` route and there will not be one (#6439, operator decision OD-2) —
@@ -33,6 +39,18 @@ export declare const CONVERSION_HINT_URL = "https://ailaunchkit.ai/pricing";
 export declare class LicenseRequiredError extends Error {
     constructor(message: string);
 }
+/** Designs every level renders (#6760 D1). Anything else in `STARTER_DESIGNS` is Pro and up. */
+export declare const FREE_DESIGNS: readonly StarterDesign[];
+/** Levels that render any design (#6760 D1) — an allow-list: an unknown level is not in it. */
+export declare const DESIGN_LEVELS: readonly Level[];
+/**
+ * Refuse a non-`standard` design at a level below Pro (#6760 D1, D6). Pure
+ * and synchronous — takes the level `deriveLevel`/`resolveModuleSet` already
+ * resolved; never reads a key or derives a level itself (D2, fail-closed:
+ * both checks below are allow-lists, so an unrecognized `level` refuses
+ * rather than granting it).
+ */
+export declare function assertDesignAllowed(design: StarterDesign | undefined, level: Level): void;
 export interface ResolvePaidModulesOptions {
     /** The requested module set's paid subset (see `module-tier.ts`). */
     paidModules: ModuleName[];
@@ -52,7 +70,20 @@ export interface ResolvePaidModulesOptions {
      * to do. Absent ⟹ a plain `--modules` run, whose messages are unchanged.
      */
     templateName?: string;
+    /**
+     * The key's derived level (#6759 D5), when one was derived on this call's
+     * path. Absent on the `--modules`-keep branch, where no level is derived
+     * (NFR-2) — the refusal then names only the module and its own level,
+     * never the caller's.
+     */
+    level?: Level;
 }
+/**
+ * The message phrase for one module (D5): what level includes it, or that it
+ * is an add-on. Pure — derived from `levelOf`, never from the current run's
+ * own derived level.
+ */
+export declare function levelPhrase(m: ModuleName): string;
 /**
  * Resolve every requested paid module to its fetched bundle bytes, or throw
  * `LicenseRequiredError` naming exactly why the run cannot proceed. Never
@@ -61,3 +92,51 @@ export interface ResolvePaidModulesOptions {
  * BEFORE the scaffold copy — see `programmatic.ts`'s `scaffold()`).
  */
 export declare function resolvePaidModules(options: ResolvePaidModulesOptions): Promise<Map<ModuleName, Uint8Array>>;
+/** Inputs shared by `deriveLevel` and `resolveModuleSet` (D4/D5). */
+export interface GateOptions {
+    /** Defaults to `process.env["AILK_LICENSE_KEY"]`. Injectable for tests. */
+    licenseKey?: string | undefined;
+    /** Forwarded to `fetchModule`; defaults to `AILK_MODULE_REGISTRY_URL` / the built-in default. */
+    registryUrl?: string;
+    /** Forwarded to `fetchModule`; defaults to this package's own version. */
+    version?: string;
+    /** Forwarded to `fetchModule`; defaults to `globalThis.fetch`. Never a live call in tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Derive the key's level from what the registry actually answers (D4) — the
+ * level only chooses which modules to ASK FOR; every byte is still
+ * authorized by the registry per module. Nothing client-side is an
+ * entitlement claim: the JWT is never parsed here.
+ *
+ * No key ⟹ `"free"`, zero network. A present key is shape-checked first,
+ * whichever source it came from (SEC-2). Then: probe every paid member of
+ * `LEVEL_MODULES.pro`, in order — a licence error on any of them is refused
+ * (a key that does not unlock all of Pro is not silently downgraded); any
+ * other failure (404, 5xx, unreachable) is wrapped so the caller sees it
+ * could not determine the level, and is told the escape hatch (`--modules`).
+ * Then probe `multi-tenant` (what Pro Plus adds beyond Pro): a licence error
+ * there is the expected "this key is Pro, not Pro Plus" answer, not a
+ * refusal.
+ */
+export declare function deriveLevel(options: GateOptions): Promise<{
+    level: Level;
+    bundles: Map<ModuleName, Uint8Array>;
+}>;
+/**
+ * The one entry point that turns `--modules` + the key into the effective
+ * module set and its resolved bundles (D5) — `programmatic.ts`'s `scaffold()`
+ * calls this for every run except a named `--template` alias (NFR-4).
+ *
+ * A named list with a non-addition (the KEEP branch, D2) resolves it exactly
+ * as today, with no level derived and no extra request (NFR-2). Otherwise the
+ * level is derived first, the set composed from it, and any named addition
+ * not already fetched during the level probe is resolved on top.
+ */
+export declare function resolveModuleSet(options: GateOptions & {
+    named?: readonly ModuleName[] | undefined;
+}): Promise<{
+    modules: ModuleName[];
+    bundles: Map<ModuleName, Uint8Array>;
+    level?: Level;
+}>;

package/dist/lib/module-license-gate.js

@@ -1,4 +1,6 @@
 import { FetchModuleError, fetchModule } from "./fetch-module.js";
+import { assertLicenseKeyShape } from "./license-key-files.js";
+import { ADD_ONS, LEVEL_LABEL, LEVEL_MODULES, OPT_IN_MODULES, PAID_MODULES, classifyModules, composeModuleSet, levelOf, } from "./module-tier.js";
 /**
  * Where a refused run sends the buyer. `/pricing`, not `/pro`: there is no
  * `/pro` route and there will not be one (#6439, operator decision OD-2) —
@@ -17,6 +19,53 @@ export class LicenseRequiredError extends Error {
         this.name = "LicenseRequiredError";
     }
 }
+/** Designs every level renders (#6760 D1). Anything else in `STARTER_DESIGNS` is Pro and up. */
+export const FREE_DESIGNS = ["standard"];
+/** Levels that render any design (#6760 D1) — an allow-list: an unknown level is not in it. */
+export const DESIGN_LEVELS = ["pro", "pro-plus"];
+/**
+ * Refuse a non-`standard` design at a level below Pro (#6760 D1, D6). Pure
+ * and synchronous — takes the level `deriveLevel`/`resolveModuleSet` already
+ * resolved; never reads a key or derives a level itself (D2, fail-closed:
+ * both checks below are allow-lists, so an unrecognized `level` refuses
+ * rather than granting it).
+ */
+export function assertDesignAllowed(design, level) {
+    if (design === undefined || FREE_DESIGNS.includes(design))
+        return;
+    if (DESIGN_LEVELS.includes(level))
+        return;
+    throw new LicenseRequiredError(`design "${design}" is a Pro feature — this run's licence level is ${LEVEL_LABEL[level]}; pass --license <key> or set AILK_LICENSE_KEY with a Pro or Pro Plus key → ${CONVERSION_HINT_URL}`);
+}
+/**
+ * The message phrase for one module (D5): what level includes it, or that it
+ * is an add-on. Pure — derived from `levelOf`, never from the current run's
+ * own derived level.
+ */
+export function levelPhrase(m) {
+    const level = levelOf(m);
+    if (level === "add-on") {
+        return `"${m}" is an add-on, bought on top of Pro or Pro Plus`;
+    }
+    if (level === "free") {
+        return `"${m}" is included at ${LEVEL_LABEL.free}`;
+    }
+    return `"${m}" is included at ${LEVEL_LABEL[level]}`;
+}
+/** M1 / M1t (D5): the no-key refusal, with or without a named template. */
+function noKeyMessage(paidModules, templateName) {
+    const phrases = paidModules.map((m) => levelPhrase(m)).join("; ");
+    const intro = templateName !== undefined
+        ? `template "${templateName}" needs a licence: ${phrases}`
+        : `no licence key, so this is a Free scaffold: ${phrases}`;
+    return `${intro} — set AILK_LICENSE_KEY first → ${CONVERSION_HINT_URL}`;
+}
+/** M2 (D5): a key the registry rejected for one module. */
+function licenseErrorMessage(err, moduleName, templateName, level) {
+    const templateSuffix = templateName !== undefined ? ` (required by template "${templateName}")` : "";
+    const levelSuffix = level !== undefined ? ` — your licence is at ${LEVEL_LABEL[level]}` : "";
+    return `${err.message}; ${levelPhrase(moduleName)}${templateSuffix}${levelSuffix} → ${CONVERSION_HINT_URL}`;
+}
 /**
  * Resolve every requested paid module to its fetched bundle bytes, or throw
  * `LicenseRequiredError` naming exactly why the run cannot proceed. Never
@@ -33,8 +82,11 @@ export async function resolvePaidModules(options) {
     }
     const token = options.licenseKey ?? process.env["AILK_LICENSE_KEY"];
     if (token === undefined || token.length === 0) {
-        throw new LicenseRequiredError(conversionHint(paidModules, options.templateName));
+        throw new LicenseRequiredError(noKeyMessage(paidModules, options.templateName));
     }
+    // SEC-2 — the `--license` flag and the env var are validated alike,
+    // whichever source this token came from, before it reaches a request.
+    assertLicenseKeyShape(token);
     const bundles = new Map();
     for (const moduleName of paidModules) {
         try {
@@ -55,11 +107,9 @@ export async function resolvePaidModules(options) {
             if (err instanceof FetchModuleError) {
                 if (err.isLicenseError) {
                     // DD5 row 2: the mapped 401/403 already names the module the key
-                    // does not cover; the template is appended so the buyer can see
-                    // WHICH of the things they asked for needs it.
-                    throw new LicenseRequiredError(options.templateName !== undefined
-                        ? `${err.message}, required by template "${options.templateName}" → ${CONVERSION_HINT_URL}`
-                        : `${err.message} → ${CONVERSION_HINT_URL}`);
+                    // does not cover; the template and level are appended so the buyer
+                    // can see WHICH of the things they asked for needs it.
+                    throw new LicenseRequiredError(licenseErrorMessage(err, moduleName, options.templateName, options.level));
                 }
                 // Not a license-gating signal (e.g. 404 "not yet available", or the
                 // registry unreachable) — a generic failure, not the honest-denial
@@ -72,10 +122,108 @@ export async function resolvePaidModules(options) {
     }
     return bundles;
 }
-function conversionHint(paidModules, templateName) {
-    const list = paidModules.join(", ");
-    const requested = templateName !== undefined
-        ? `template "${templateName}" requires Pro module(s) (${list})`
-        : `Pro module(s) requested (${list})`;
-    return `${requested} — set AILK_LICENSE_KEY first → ${CONVERSION_HINT_URL}`;
+function forward(options) {
+    return {
+        ...(options.registryUrl !== undefined ? { registryUrl: options.registryUrl } : {}),
+        ...(options.version !== undefined ? { version: options.version } : {}),
+        ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+    };
+}
+/**
+ * Derive the key's level from what the registry actually answers (D4) — the
+ * level only chooses which modules to ASK FOR; every byte is still
+ * authorized by the registry per module. Nothing client-side is an
+ * entitlement claim: the JWT is never parsed here.
+ *
+ * No key ⟹ `"free"`, zero network. A present key is shape-checked first,
+ * whichever source it came from (SEC-2). Then: probe every paid member of
+ * `LEVEL_MODULES.pro`, in order — a licence error on any of them is refused
+ * (a key that does not unlock all of Pro is not silently downgraded); any
+ * other failure (404, 5xx, unreachable) is wrapped so the caller sees it
+ * could not determine the level, and is told the escape hatch (`--modules`).
+ * Then probe `multi-tenant` (what Pro Plus adds beyond Pro): a licence error
+ * there is the expected "this key is Pro, not Pro Plus" answer, not a
+ * refusal.
+ */
+export async function deriveLevel(options) {
+    const token = options.licenseKey ?? process.env["AILK_LICENSE_KEY"];
+    if (token === undefined || token.length === 0) {
+        return { level: "free", bundles: new Map() };
+    }
+    assertLicenseKeyShape(token);
+    const bundles = new Map();
+    const proModules = LEVEL_MODULES.pro.filter((m) => PAID_MODULES.includes(m));
+    for (const moduleName of proModules) {
+        try {
+            const bytes = await fetchModule({ moduleName, token, ...forward(options) });
+            bundles.set(moduleName, bytes);
+        }
+        catch (err) {
+            if (err instanceof FetchModuleError) {
+                if (err.isLicenseError) {
+                    throw new LicenseRequiredError(licenseErrorMessage(err, moduleName));
+                }
+                throw new FetchModuleError(`could not determine your licence level: ${err.message} — name the modules you want with --modules`);
+            }
+            throw err;
+        }
+    }
+    try {
+        const bytes = await fetchModule({
+            moduleName: "multi-tenant",
+            token,
+            ...forward(options),
+        });
+        bundles.set("multi-tenant", bytes);
+        return { level: "pro-plus", bundles };
+    }
+    catch (err) {
+        if (err instanceof FetchModuleError) {
+            if (err.isLicenseError) {
+                return { level: "pro", bundles };
+            }
+            throw new FetchModuleError(`could not determine your licence level: ${err.message} — name the modules you want with --modules`);
+        }
+        throw err;
+    }
+}
+/**
+ * The one entry point that turns `--modules` + the key into the effective
+ * module set and its resolved bundles (D5) — `programmatic.ts`'s `scaffold()`
+ * calls this for every run except a named `--template` alias (NFR-4).
+ *
+ * A named list with a non-addition (the KEEP branch, D2) resolves it exactly
+ * as today, with no level derived and no extra request (NFR-2). Otherwise the
+ * level is derived first, the set composed from it, and any named addition
+ * not already fetched during the level probe is resolved on top.
+ */
+export async function resolveModuleSet(options) {
+    const namedList = options.named ?? [];
+    const additions = [...ADD_ONS, ...OPT_IN_MODULES];
+    const isKeep = namedList.some((m) => !additions.includes(m));
+    if (isKeep) {
+        const modules = composeModuleSet(namedList, "free");
+        const { paid } = classifyModules(modules);
+        const bundles = await resolvePaidModules({
+            paidModules: paid,
+            licenseKey: options.licenseKey,
+            ...forward(options),
+        });
+        return { modules, bundles };
+    }
+    const { level, bundles } = await deriveLevel(options);
+    const modules = composeModuleSet(namedList, level);
+    const { paid } = classifyModules(modules);
+    const missing = paid.filter((m) => !bundles.has(m));
+    if (missing.length > 0) {
+        const extra = await resolvePaidModules({
+            paidModules: missing,
+            licenseKey: options.licenseKey,
+            level,
+            ...forward(options),
+        });
+        for (const [k, v] of extra)
+            bundles.set(k, v);
+    }
+    return { modules, bundles, level };
 }

package/dist/lib/module-tier.d.ts

@@ -1,19 +1,3 @@
-/**
- * Free vs paid module classification (K1, #5089 — REL-015.3 "AI Launch Kit —
- * Commercial line", D-17 "Flavor 3").
- *
- * The commercial line is decided: the paid modules do NOT ship on public npm
- * — delivery itself is the gate. `create-ailk` scaffolds Free's modules from
- * `templates/` with no key (today's path, unchanged); a paid module is
- * FETCHED from the internal module distribution when `AILK_LICENSE_KEY`
- * verifies (see `fetch-module.ts` + `module-license-gate.ts`).
- *
- * `FREE_MODULES` is the one hand-authored list (today just `marketing`, the
- * always-available default). `PAID_MODULES` is derived from it — every other
- * `RECOGNIZED_MODULES` entry — so adding a new module to the vocabulary
- * (`parse-args.ts`) defaults it to "paid" until someone deliberately adds it
- * to `FREE_MODULES`, rather than silently shipping it free.
- */
 import { type ModuleName } from "../parse-args.js";
 /** Modules scaffolded from `templates/` with no license — today's free path. */
 export declare const FREE_MODULES: readonly ModuleName[];
@@ -24,6 +8,51 @@ export declare const FREE_MODULES: readonly ModuleName[];
  * from `RECOGNIZED_MODULES` silently.
  */
 export declare const PAID_MODULES: readonly ModuleName[];
+/**
+ * The levels a key can be at (#6759 D2). A value, never read from a flag, a
+ * manifest or a key claim — it is always DERIVED, by `deriveLevel`
+ * (`module-license-gate.ts`), from what the registry actually answers.
+ */
+export declare const LEVELS: readonly ["free", "pro", "pro-plus"];
+export type Level = (typeof LEVELS)[number];
+export declare const LEVEL_LABEL: Readonly<Record<Level, string>>;
+/**
+ * Bought per site on top of a paid level — never switched on BY a level
+ * (OFFERINGS §4a). Naming one in `--modules` adds it without trimming
+ * (`composeModuleSet`), and it is refused below Pro naming the level it is
+ * an add-on ON TOP of.
+ */
+export declare const ADD_ONS: readonly ModuleName[];
+/**
+ * Included at Pro and above (the licence manifest's `pro` tier), but not
+ * switched on by default at any level (D1) — an authed app surface
+ * contributing no PUBLIC page to a marketing site. Naming it in `--modules`
+ * adds it without trimming, exactly like an add-on.
+ */
+export declare const OPT_IN_MODULES: readonly ModuleName[];
+/**
+ * What a key at each level switches on with no `--modules` (D2). Derived —
+ * every list is `RECOGNIZED_MODULES.filter(...)`, so declaration order is
+ * preserved and a module added to the vocabulary later lands in `pro` by
+ * derivation (loud: `module-tier.test.ts`'s table test pins the exact sets).
+ */
+export declare const LEVEL_MODULES: Readonly<Record<Level, readonly ModuleName[]>>;
+/**
+ * Which level (or add-on status) a module belongs to (D2). `"free"` for
+ * `FREE_MODULES`, `"add-on"` for `ADD_ONS`, `"pro-plus"` for
+ * `PRO_PLUS_MODULES`, else `"pro"` (`workspace` included — D1). Pure.
+ */
+export declare function levelOf(m: ModuleName): Level | "add-on";
+/**
+ * The pure core of FR-2/FR-3 (D2): compose the effective module set from
+ * what `--modules` named and the key's derived level. Naming any module that
+ * is not an addition (`ADDITIONS`) is a KEEP — it names exactly the set,
+ * unchanged from today (NFR-2), and the level plays no part. Naming only
+ * additions (or nothing) takes the level's default plus those additions.
+ * Never refuses — refusals belong to the gate (`resolveModuleSet`), because
+ * whether a named module is covered is a registry answer, not a table lookup.
+ */
+export declare function composeModuleSet(named: readonly ModuleName[] | undefined, level: Level): ModuleName[];
 export interface ModuleClassification {
     free: ModuleName[];
     paid: ModuleName[];

package/dist/lib/module-tier.js

@@ -14,6 +14,7 @@
  * (`parse-args.ts`) defaults it to "paid" until someone deliberately adds it
  * to `FREE_MODULES`, rather than silently shipping it free.
  */
+import { normalizeModules } from "../module-architecture.js";
 import { RECOGNIZED_MODULES } from "../parse-args.js";
 /** Modules scaffolded from `templates/` with no license — today's free path. */
 export const FREE_MODULES = ["marketing"];
@@ -24,6 +25,81 @@ export const FREE_MODULES = ["marketing"];
  * from `RECOGNIZED_MODULES` silently.
  */
 export const PAID_MODULES = RECOGNIZED_MODULES.filter((m) => !FREE_MODULES.includes(m));
+/**
+ * The levels a key can be at (#6759 D2). A value, never read from a flag, a
+ * manifest or a key claim — it is always DERIVED, by `deriveLevel`
+ * (`module-license-gate.ts`), from what the registry actually answers.
+ */
+export const LEVELS = ["free", "pro", "pro-plus"];
+export const LEVEL_LABEL = {
+    free: "Free",
+    pro: "Pro",
+    "pro-plus": "Pro Plus",
+};
+/**
+ * Bought per site on top of a paid level — never switched on BY a level
+ * (OFFERINGS §4a). Naming one in `--modules` adds it without trimming
+ * (`composeModuleSet`), and it is refused below Pro naming the level it is
+ * an add-on ON TOP of.
+ */
+export const ADD_ONS = ["commerce"];
+/**
+ * Included at Pro and above (the licence manifest's `pro` tier), but not
+ * switched on by default at any level (D1) — an authed app surface
+ * contributing no PUBLIC page to a marketing site. Naming it in `--modules`
+ * adds it without trimming, exactly like an add-on.
+ */
+export const OPT_IN_MODULES = ["workspace"];
+/** The Pro Plus membership: what Pro Plus switches on beyond Pro. */
+const PRO_PLUS_MODULES = ["multi-tenant"];
+/** Named modules that never trim the level default when composing a set (D2). */
+const ADDITIONS = [...ADD_ONS, ...OPT_IN_MODULES];
+const PRO_EXCLUDED = new Set([...ADDITIONS, ...PRO_PLUS_MODULES]);
+/**
+ * What a key at each level switches on with no `--modules` (D2). Derived —
+ * every list is `RECOGNIZED_MODULES.filter(...)`, so declaration order is
+ * preserved and a module added to the vocabulary later lands in `pro` by
+ * derivation (loud: `module-tier.test.ts`'s table test pins the exact sets).
+ */
+export const LEVEL_MODULES = Object.freeze({
+    free: [...FREE_MODULES],
+    pro: RECOGNIZED_MODULES.filter((m) => FREE_MODULES.includes(m) ||
+        (PAID_MODULES.includes(m) && !PRO_EXCLUDED.has(m))),
+    "pro-plus": RECOGNIZED_MODULES.filter((m) => FREE_MODULES.includes(m) ||
+        (PAID_MODULES.includes(m) && !ADDITIONS.includes(m))),
+});
+/**
+ * Which level (or add-on status) a module belongs to (D2). `"free"` for
+ * `FREE_MODULES`, `"add-on"` for `ADD_ONS`, `"pro-plus"` for
+ * `PRO_PLUS_MODULES`, else `"pro"` (`workspace` included — D1). Pure.
+ */
+export function levelOf(m) {
+    if (FREE_MODULES.includes(m))
+        return "free";
+    if (ADD_ONS.includes(m))
+        return "add-on";
+    if (PRO_PLUS_MODULES.includes(m))
+        return "pro-plus";
+    return "pro";
+}
+/**
+ * The pure core of FR-2/FR-3 (D2): compose the effective module set from
+ * what `--modules` named and the key's derived level. Naming any module that
+ * is not an addition (`ADDITIONS`) is a KEEP — it names exactly the set,
+ * unchanged from today (NFR-2), and the level plays no part. Naming only
+ * additions (or nothing) takes the level's default plus those additions.
+ * Never refuses — refusals belong to the gate (`resolveModuleSet`), because
+ * whether a named module is covered is a registry answer, not a table lookup.
+ */
+export function composeModuleSet(named, level) {
+    const namedList = [...(named ?? [])];
+    const keep = namedList.filter((m) => !ADDITIONS.includes(m));
+    if (keep.length > 0) {
+        return normalizeModules(namedList);
+    }
+    const add = namedList.filter((m) => ADDITIONS.includes(m));
+    return normalizeModules([...LEVEL_MODULES[level], ...add]);
+}
 /**
  * Split a requested (already-validated, `ModuleName`) module set into its
  * free and paid subsets, each preserving the input's relative order.