create-ailk 0.6.1 → 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: **298 component files** across 16 tiers — 54 sections, 95 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. 295 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: **294/298** components carry a capability description derived from source — 43 from the section registry's hand-authored when-to-use text, 220 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, **264** are *strong* — a capability sentence you could match a requirement against — and **30** 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 89%**.
+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** 90/95 · **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 (95)
+## Blocks (99)
 
 Intermediate composition tiles — the pieces sections are built from. Compose primitives and panels; never import a section.
 
@@ -147,8 +148,10 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `ComparisonMatrix` | Full feature × tier comparison matrix for the Pricing 'with-comparison-table' variant. Renders N collapsible ComparisonGroups, each containing M feature rows with per-tier values. | `import { ComparisonMatrix } from "@working-theory/ui/blocks"` |
 | `Composer` | The chat input, per the ploy.ai capture contract. | `import { Composer } from "@working-theory/ui/blocks"` |
 | `ConsentGroup` | The composite control for the `consent` field kind: one real checkbox per consent purpose, each with its statement and inline policy links, inside one fieldset. | `import { ConsentGroup } from "@working-theory/ui/blocks"` |
+| `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"` |
@@ -166,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"` |
@@ -188,6 +192,7 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `PageHeaderSwitcher` | Header-owned context-switcher island (DropdownMenu-backed). Header-owned segment switcher rendered inside PageHeader's `switcher` slot. Composes DropdownMenu (Radix-backed — positioning, click-outside, Escape, focus management, and roving keyboard nav all come for free). | `import { PageHeaderSwitcher } from "@working-theory/ui/blocks"` |
 | `PairingCard` | Quiet card naming a matched WaitlistRecommendation pairing: both resolved offer names + the resolved reason, joined against a caller-supplied offers[] by key. | `import { PairingCard } from "@working-theory/ui/blocks"` |
 | `PhoneNumberField` | Single-box combo phone input for the "tel" field kind (supersedes the two-segment country-Select + number-Input layout). | `import { PhoneNumberField } from "@working-theory/ui/blocks"` |
+| `PostCard` | Same props as PostRow, a vertical arrangement. A single linked blog-index card (cover · date · reading time · title · excerpt · "Read more"). Tier 3 block; composes MediaFigure + primitives. RSC default. *(weak)* | `import { PostCard } from "@working-theory/ui/blocks"` |
 | `PostRow` | A single horizontal row in the two-column blog index: a landscape cover thumbnail (left) followed by the post's title · excerpt · author+date meta · tag list. The WHOLE row is one link (aria-labelled by the title, so screen readers announce the post title rather than the concatenated row content). | `import { PostRow } from "@working-theory/ui/blocks"` |
 | `PricingExtraTierRow` | Compact horizontal extra-tier row for the Pricing 'two-tiers-with-extra-tier' variant. Renders plan name + description on the left and a CTA on the right. Structurally different from PricingTierCard (no price display in this variant). | `import { PricingExtraTierRow } from "@working-theory/ui/blocks"` |
 | `PricingTierCard` | Single pricing tier card (all 4 Pricing variants). Renders a single pricing tier: plan name + optional badge, description, price display, CTA button, and feature checklist. | `import { PricingTierCard } from "@working-theory/ui/blocks"` |
@@ -529,13 +534,14 @@ Import: `import { X } from "@working-theory/ui-commerce";` (or from the `@workin
 
 ## Weak descriptions
 
-These 30 components have a description that is accurate but does not do the job well: too short to match against, or long but spent on implementation. A capability search reaches them only if the searcher's word happens to be in it, so they are the most likely place for this catalog to repeat the failure it was built to fix. Read the source before concluding the capability is absent — and if you own one of these components, its header is the fix.
+These 31 components have a description that is accurate but does not do the job well: too short to match against, or long but spent on implementation. A capability search reaches them only if the searcher's word happens to be in it, so they are the most likely place for this catalog to repeat the failure it was built to fix. Read the source before concluding the capability is absent — and if you own one of these components, its header is the fix.
 
 | Component | Tier | What the source gives us |
 | --- | --- | --- |
 | `DocumentViewerClient` | sections | The interactive shell for DocumentViewer. Split out of DocumentViewer.tsx (which stays RSC) for the same reason AlertSection composes AlertSectionDismissIsland: interactivity is contained to one client island. |
 | `AgentContextCard` | blocks | Capability-bearing block that renders agent provenance. RSC note: no hooks or browser APIs — server-renderable by default. |
 | `PageHeader` | blocks | RSC. Page-level header composing the Breadcrumb primitive for the left-side wayfinding trail, a generic right-side `actions` slot, and an optional `switcher` slot for header-owned segment switching. Fills AppShell's `header` slot (AdminShell and similar). No accent bar. No tab API. No named action props — the caller assembles whatever button/menu nodes it needs and passes them as `actions`. |
+| `PostCard` | blocks | Same props as PostRow, a vertical arrangement. A single linked blog-index card (cover · date · reading time · title · excerpt · "Read more"). Tier 3 block; composes MediaFigure + primitives. RSC default. |
 | `PricingTierCardSeatControl` | blocks | Seat-count range picker for the Team tier card. Renders a Select primitive that lets the user choose an "Up to N seats" option from a caller-supplied list of numbers. The parent PricingTierCard stays a pure RSC; only this tiny island is hydrated. Pattern mirrors PageHeaderSwitcher.tsx: small "use client" island imported by an otherwise-server-rendered parent, keeping the client bundle minimal. |
 | `SinglePriceCard` | blocks | 2-column split card for the Pricing 'single-price-with-details' variant. |
 | `SocialIcons` | blocks | Horizontal row of social icon links. Renders brand icons (via Icon primitive + simple-icons paths) inside accessible Link primitives. Each platform link gets an aria-label. Shared by company-mission, simple-centered, and newsletter-below footer variants, and composed by TeamMemberCard for member social links. |

package/dist/add-module-core.d.ts

@@ -0,0 +1,22 @@
+import type { ModuleName } from "./parse-args.js";
+/**
+ * A refusal the CLI exits 2 on — a request this command will not carry out
+ * as asked (a bundle patching outside the allowlist, an `architecture.yaml`
+ * it cannot read the module set from, a free module), as distinct from a
+ * failure. Thrown before anything is written.
+ */
+export declare class AddModuleRefusedError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+/**
+ * The site's current module set and declared surfaces, read back off the
+ * generated `architecture.yaml` header (`deriveArchitecture`'s `# Modules:` /
+ * `# Surfaces:` lines). Refuses rather than guesses when either line is
+ * absent or names an unknown module — regenerating from the added module
+ * alone would silently drop every other module's boundaries.
+ */
+export declare function readArchitectureHeader(archYaml: string): {
+    modules: ModuleName[];
+    surfaces: string[];
+};

package/dist/add-module-core.js

@@ -0,0 +1,50 @@
+/**
+ * The two `add-module` symbols `site-roster.ts` needs as well (#6682 D1):
+ * the refusal type and the `architecture.yaml` header reader. They live
+ * here rather than in `add-module.ts` because `add-module.ts` imports
+ * `site-roster.ts` — reading them from `add-module.ts` would close an import
+ * cycle (`import/no-cycle`). `add-module.ts` re-exports both, so every
+ * existing import of them from `add-module.js` is unchanged.
+ */
+import { normalizeModules } from "./module-architecture.js";
+/**
+ * A refusal the CLI exits 2 on — a request this command will not carry out
+ * as asked (a bundle patching outside the allowlist, an `architecture.yaml`
+ * it cannot read the module set from, a free module), as distinct from a
+ * failure. Thrown before anything is written.
+ */
+export class AddModuleRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "AddModuleRefusedError";
+    }
+}
+/**
+ * The site's current module set and declared surfaces, read back off the
+ * generated `architecture.yaml` header (`deriveArchitecture`'s `# Modules:` /
+ * `# Surfaces:` lines). Refuses rather than guesses when either line is
+ * absent or names an unknown module — regenerating from the added module
+ * alone would silently drop every other module's boundaries.
+ */
+export function readArchitectureHeader(archYaml) {
+    const modulesLine = /^# Modules: (.+)$/m.exec(archYaml)?.[1];
+    const surfacesLine = /^# Surfaces: (.+)$/m.exec(archYaml)?.[1];
+    if (modulesLine === undefined || surfacesLine === undefined) {
+        throw new AddModuleRefusedError("architecture.yaml has no `# Modules:` / `# Surfaces:` header, so the site's current module set is unknown. Regenerate it with `create-ailk --sync-architecture <modules>` first.");
+    }
+    let modules;
+    try {
+        modules = normalizeModules(modulesLine.split(","));
+    }
+    catch (err) {
+        throw new AddModuleRefusedError(`architecture.yaml's \`# Modules:\` header is not a module list: ${err.message}`);
+    }
+    const surfaces = surfacesLine.trim() === "core only"
+        ? []
+        : surfacesLine
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    return { modules, surfaces };
+}

package/dist/add-module.d.ts

@@ -0,0 +1,89 @@
+import { AddModuleRefusedError, readArchitectureHeader } from "./add-module-core.js";
+import { type InstallReportRow } from "./lib/extract-module-bundle.js";
+import { type ModulePatch } from "./module-architecture.js";
+import { type ModuleName } from "./parse-args.js";
+import type { MarkerMap, WorkspaceVersionMap } from "./substitute.js";
+import { type SyncRoutesResult } from "./sync-routes.js";
+export { AddModuleRefusedError, readArchitectureHeader };
+/**
+ * One report row: a bundle file written, patched or skipped, or a seed the
+ * roster append removed (a superseded template row's untouched seed, #6682 D4).
+ */
+export type AddModuleReportRow = InstallReportRow | {
+    path: string;
+    action: "removed";
+};
+/**
+ * Refuse a bundle whose `patches` reach past the plus-config allowlist
+ * (#6653 D3), matched on the target's basename so any depth qualifies:
+ * `package.json` (only `merge-keys`/`append-unique` on a dependency or script
+ * key), `next.config.*`, `jest.config.*`. Runs inside `installBundleTree`
+ * after the patches validate and before any is computed or written.
+ */
+export declare function checkPlusConfigPatches(patches: readonly ModulePatch[]): void;
+export interface ApplyModuleOptions {
+    /** The already-scaffolded site (validated by the caller). */
+    targetDir: string;
+    moduleName: ModuleName;
+    /** The module's fetched bundle — this function never fetches. */
+    bundleBytes: Uint8Array;
+    /** Workspace version map, for `workspace:*` in patch targets and route copies. */
+    versions: WorkspaceVersionMap;
+    /** The scaffold's marker map (`buildScaffoldMarkers`). */
+    markers: MarkerMap;
+    /** The package's `templates/` dir, for the route sync and the roster check. */
+    templatesDir: string;
+    /** The package's `site-templates/` dir — the shipped manifests the roster rows are read from. */
+    siteTemplatesDir: string;
+}
+export interface AddModuleResult {
+    /** Resolved absolute path to the site. */
+    targetDir: string;
+    /** The module set `architecture.yaml` now declares. */
+    modules: ModuleName[];
+    /** One row per file written, patched, skipped or removed — empty when nothing changed. */
+    report: AddModuleReportRow[];
+    /** The route sync run over the module's surfaces. */
+    routes: SyncRoutesResult;
+    /** The page-roster append (#6682). `none` = the site has no `.ailk-site-manifest.json` (nor a pre-#6658 root `TEMPLATE-MANIFEST.json`). */
+    roster: {
+        state: "appended" | "unchanged" | "none";
+        /** Routes appended to the roster. */
+        appended: string[];
+        /** Superseded seeds removed. */
+        removed: string[];
+        /** `siteRosterProblems` after the append — empty means clean. */
+        problems: string[];
+        /**
+         * The site-relative roster file read and written — `SITE_ROSTER_PATH`, or
+         * a pre-#6658 site's root `TEMPLATE-MANIFEST.json`.
+         */
+        path: string;
+    };
+}
+/**
+ * Merge one module's bundle onto an existing site, sync its routes,
+ * regenerate `architecture.yaml` and the nav, then append the module's pages
+ * to the site's roster. Every refusal — an unreadable header or roster, a
+ * module row no shipped manifest carries, a patch outside the allowlist, a
+ * patch conflict, an unsafe bundle — throws before the first write (the header
+ * and roster are read first; `extractModuleBundle` validates and computes
+ * everything before it copies).
+ */
+export declare function applyModuleToScaffold(opts: ApplyModuleOptions): Promise<AddModuleResult>;
+/** The report `add-module` prints. */
+export declare function formatAddModuleReport(result: AddModuleResult, moduleName: string): string;
+export interface AddModuleArgs {
+    /** The module to add; undefined only with `help`. */
+    module: ModuleName | undefined;
+    /** Positional target directory; undefined = the caller's cwd. */
+    target: string | undefined;
+    help: boolean;
+}
+export declare const ADD_MODULE_HELP = "create-ailk add-module \u2014 add a purchased module to an existing site.\n\nUsage:\n  create-ailk add-module <module> [<target-dir>]\n  create-ailk upgrade <module> [<target-dir>]\n\nArguments:\n  <module>                 One paid module, e.g. docs-blog. Needs\n                           AILK_LICENSE_KEY covering it.\n  <target-dir>             An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nWrites the module's files the site lacks and never overwrites one it has: a\nfile whose content differs is left as-is and listed for manual review with the\nchange the module wanted. Only package.json dependency/script keys,\nnext.config.* and jest.config.* are patched. Then copies the module's routes\nand regenerates architecture.yaml. Running it again changes nothing.\n";
+/**
+ * Parse the argv AFTER the `add-module` / `upgrade` word. Strict
+ * `node:util` parseArgs, like `parseSyncRoutesArgs`; the module is validated
+ * the same way one `--modules` entry is.
+ */
+export declare function parseAddModuleArgs(argv: string[]): AddModuleArgs;

package/dist/add-module.js

@@ -0,0 +1,334 @@
+/**
+ * `create-ailk add-module <module>` (alias `upgrade`) — apply a purchased
+ * module to a site that was scaffolded without it, in place (#6653).
+ *
+ * A Free customer who buys Pro already has a site. `scaffold()` merges a
+ * module bundle only onto a fresh tree; this merges one onto a tree someone
+ * has lived in, under the plus-config policy (operator-disposed 2026-09-24):
+ *
+ *   - a file the tree lacks is written;
+ *   - a file the tree has is never overwritten — when its bytes differ from
+ *     the bundle's it is reported `skipped` with the exact change the bundle
+ *     wanted (a manual-review item), and when they match it is not reported;
+ *   - the bundle's `patches` are the only edits to an existing file, and only
+ *     to the config allowlist: `package.json` dependency/script keys,
+ *     `next.config.*`, `jest.config.*`.
+ *
+ * Then the module's route surfaces are synced in (`syncRoutes` with the
+ * module's surfaces forced carried), `architecture.yaml` is regenerated from
+ * the site's current module set plus this one, and the generated nav follows
+ * the new surfaces unless the site has edited it. Run twice, the second run
+ * changes nothing and reports nothing.
+ *
+ * Pure module: no `import.meta.url`, so jest can import it directly — the
+ * package-rooted inputs (`templatesDir`, `versions`) and the fetched bundle
+ * bytes are supplied by `programmatic.ts`'s `addModule`, the same split as
+ * `sync-routes.ts` / `syncRoutesSync`.
+ */
+import { existsSync, readFileSync, readdirSync, rmSync, rmdirSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { AddModuleRefusedError, readArchitectureHeader, } from "./add-module-core.js";
+import { deriveArchitecture } from "./derive-architecture.js";
+import { diffTwoStrings, extractModuleBundle, } from "./lib/extract-module-bundle.js";
+import { normalizeModules } from "./module-architecture.js";
+import { ParseError, parseModules } from "./parse-args.js";
+import { SITE_ROSTER_PATH, moduleRosterRows, planRosterAppend, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
+import { MODULE_SURFACES, NAV_CONFIG_PATH, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
+import { syncRoutes } from "./sync-routes.js";
+export { AddModuleRefusedError, readArchitectureHeader };
+/** `package.json` paths a `json` patch may write under the plus-config policy. */
+const PACKAGE_JSON_PATCH_KEYS = new Set([
+    "dependencies",
+    "devDependencies",
+    "scripts",
+]);
+/**
+ * Refuse a bundle whose `patches` reach past the plus-config allowlist
+ * (#6653 D3), matched on the target's basename so any depth qualifies:
+ * `package.json` (only `merge-keys`/`append-unique` on a dependency or script
+ * key), `next.config.*`, `jest.config.*`. Runs inside `installBundleTree`
+ * after the patches validate and before any is computed or written.
+ */
+export function checkPlusConfigPatches(patches) {
+    for (const patch of patches) {
+        const name = basename(patch.target);
+        if (name === "package.json") {
+            for (const op of patch.ops) {
+                const allowed = (op.op === "merge-keys" || op.op === "append-unique") &&
+                    op.path.length > 0 &&
+                    PACKAGE_JSON_PATCH_KEYS.has(op.path[0]);
+                if (!allowed) {
+                    throw new AddModuleRefusedError(`the module bundle patches ${patch.target} outside its dependency and script keys — add-module only patches dependencies, devDependencies and scripts there`);
+                }
+            }
+            continue;
+        }
+        if (/^next\.config\.[^/]+$/.test(name) ||
+            /^jest\.config\.[^/]+$/.test(name)) {
+            continue;
+        }
+        throw new AddModuleRefusedError(`the module bundle patches ${patch.target}, which is outside the config files add-module may edit (package.json, next.config.*, jest.config.*)`);
+    }
+}
+/**
+ * Merge one module's bundle onto an existing site, sync its routes,
+ * regenerate `architecture.yaml` and the nav, then append the module's pages
+ * to the site's roster. Every refusal — an unreadable header or roster, a
+ * module row no shipped manifest carries, a patch outside the allowlist, a
+ * patch conflict, an unsafe bundle — throws before the first write (the header
+ * and roster are read first; `extractModuleBundle` validates and computes
+ * everything before it copies).
+ */
+export async function applyModuleToScaffold(opts) {
+    const targetAbs = resolve(opts.targetDir);
+    const archPath = join(targetAbs, "architecture.yaml");
+    const current = readArchitectureHeader(readFileSync(archPath, "utf8"));
+    const modules = normalizeModules([...current.modules, opts.moduleName]);
+    // Resolved before the first write: a header surface that is unknown, or
+    // belongs to a module the site does not carry, is a refusal with the tree
+    // untouched — not a failure after the bundle has landed.
+    let surfaces;
+    try {
+        surfaces = resolveSurfaces(modules, current.surfaces);
+    }
+    catch (err) {
+        throw new AddModuleRefusedError(`architecture.yaml's \`# Surfaces:\` header cannot be carried forward: ${err.message}`);
+    }
+    // The roster and every module row it may need, likewise before the first
+    // write. A template-less site has no roster and needs none.
+    const siteRoster = readSiteRoster(targetAbs);
+    const references = siteRoster === undefined
+        ? []
+        : modules.flatMap((m) => moduleRosterRows(m, opts.siteTemplatesDir));
+    const { report } = await extractModuleBundle({
+        bytes: opts.bundleBytes,
+        targetDir: targetAbs,
+        moduleName: opts.moduleName,
+        versions: opts.versions,
+        markers: opts.markers,
+        existingFilePolicy: "skip-existing",
+        checkPatches: checkPlusConfigPatches,
+    });
+    const routes = syncRoutes({
+        targetDir: targetAbs,
+        templatesDir: opts.templatesDir,
+        versions: opts.versions,
+        apply: true,
+        forceSurfaces: MODULE_SURFACES[opts.moduleName] ?? [],
+    });
+    // The same composition `syncArchitectureSync` writes — a pure function of
+    // the module set, so an unchanged set rewrites identical bytes.
+    writeFileSync(archPath, deriveArchitecture(modules, surfaces));
+    const rows = [...report];
+    const navRow = syncNavConfig(targetAbs, current.surfaces, surfaces);
+    if (navRow !== undefined)
+        rows.push(navRow);
+    const roster = {
+        state: "none",
+        appended: [],
+        removed: [],
+        problems: [],
+        path: siteRoster?.path ?? SITE_ROSTER_PATH,
+    };
+    if (siteRoster !== undefined) {
+        // After the bundle has landed: a `contentDir` row's form follows the
+        // seeds now on disk.
+        const plan = planRosterAppend({
+            targetDir: targetAbs,
+            roster: siteRoster,
+            modules,
+            references,
+            siteTemplatesDir: opts.siteTemplatesDir,
+            templatesDir: opts.templatesDir,
+            markers: opts.markers,
+        });
+        for (const seed of plan.seeds) {
+            if (seed.remove) {
+                const abs = join(targetAbs, seed.path);
+                rmSync(abs);
+                if (readdirSync(dirname(abs)).length === 0)
+                    rmdirSync(dirname(abs));
+                rows.push({ path: seed.path, action: "removed" });
+                roster.removed.push(seed.path);
+            }
+            else {
+                rows.push({ path: seed.path, action: "skipped", wanted: seed.wanted });
+            }
+        }
+        if (plan.next !== undefined) {
+            writeFileSync(join(targetAbs, siteRoster.path), plan.next);
+            rows.push({
+                path: siteRoster.path,
+                action: "patched",
+                change: diffTwoStrings(siteRoster.path, siteRoster.text, plan.next, true),
+            });
+        }
+        roster.state = plan.next === undefined ? "unchanged" : "appended";
+        roster.appended = plan.appended;
+        roster.problems = siteRosterProblems({
+            targetDir: targetAbs,
+            siteTemplatesDir: opts.siteTemplatesDir,
+            templatesDir: opts.templatesDir,
+        });
+    }
+    return { targetDir: targetAbs, modules, report: rows, routes, roster };
+}
+/**
+ * Regenerate the site nav (`scaffoldSync` writes it from the surface set) for
+ * the new surfaces — but only when the site's copy is still exactly what the
+ * OLD surface set generates. An edited nav is the customer's file: left as-is
+ * and reported `skipped` with the change, like any other.
+ */
+function syncNavConfig(targetAbs, before, after) {
+    const navPath = join(targetAbs, NAV_CONFIG_PATH);
+    const wanted = renderNavConfig(after);
+    const existing = existsSync(navPath)
+        ? readFileSync(navPath, "utf8")
+        : undefined;
+    if (existing === wanted)
+        return undefined;
+    if (existing === undefined || existing === renderNavConfig(before)) {
+        writeFileSync(navPath, wanted);
+        return { path: NAV_CONFIG_PATH, action: "written" };
+    }
+    return {
+        path: NAV_CONFIG_PATH,
+        action: "skipped",
+        wanted: diffTwoStrings(NAV_CONFIG_PATH, existing, wanted, true),
+    };
+}
+/** Indent a multi-line diff under its report row. */
+function indent(text) {
+    return text.split("\n").map((line) => `      ${line}`);
+}
+/** The report `add-module` prints. */
+export function formatAddModuleReport(result, moduleName) {
+    const written = result.report.filter((row) => row.action === "written");
+    const patched = result.report.filter((row) => row.action === "patched");
+    const skipped = result.report.filter((row) => row.action === "skipped");
+    const removed = result.report.filter((row) => row.action === "removed");
+    const lines = [
+        `[create-ailk] add-module ${moduleName} → ${result.targetDir}`,
+    ];
+    if (result.report.length === 0 && result.routes.applied.length === 0) {
+        lines.push(`Nothing to add — the site already carries everything ${moduleName} brings.`);
+    }
+    if (written.length > 0) {
+        lines.push(`Written (${written.length}):`);
+        lines.push(...written.map((row) => `  ${row.path}`));
+    }
+    if (patched.length > 0) {
+        lines.push(`Patched (${patched.length}):`);
+        for (const row of patched) {
+            lines.push(`  ${row.path}`);
+            if (row.action === "patched")
+                lines.push(...indent(row.change));
+        }
+    }
+    if (removed.length > 0) {
+        lines.push(`Removed (${removed.length}):`);
+        lines.push(...removed.map((row) => `  ${row.path}`));
+    }
+    if (skipped.length > 0) {
+        lines.push(`Needs manual review (${skipped.length}) — the site's copy differs from the module's and was left untouched. Apply the change by hand if you want it:`);
+        for (const row of skipped) {
+            lines.push(`  ${row.path}`);
+            if (row.action === "skipped")
+                lines.push(...indent(row.wanted));
+        }
+    }
+    const { routes } = result;
+    if (routes.applied.length > 0) {
+        lines.push(`Routes copied (${routes.applied.length}):`);
+        lines.push(...routes.applied.map((route) => `  ${route}`));
+    }
+    if (routes.appliedDependencies.length > 0) {
+        lines.push(`Also copied ${routes.appliedDependencies.length} file(s) those routes import:`);
+        lines.push(...routes.appliedDependencies.map((dep) => `  ${dep}`));
+    }
+    if (routes.missingMessageNamespaces.length > 0) {
+        lines.push("Also required — message namespace(s) not found in apps/web/messages/en.json (add manually, not auto-merged):");
+        lines.push(...routes.missingMessageNamespaces.map((ns) => `  ${ns}`));
+    }
+    lines.push(`architecture.yaml modules: ${result.modules.join(", ")}`);
+    lines.push(...formatRoster(result.roster, moduleName));
+    if (written.length > 0 || patched.length > 0 || routes.applied.length > 0) {
+        lines.push("Next: pnpm install, then pnpm build.");
+    }
+    return lines.join("\n") + "\n";
+}
+/** The page-roster lines of the report (#6682 D7). */
+function formatRoster(roster, moduleName) {
+    if (roster.state === "none") {
+        return [
+            `Page roster: none. This site was scaffolded without a template, so it has no ${SITE_ROSTER_PATH} to append to.`,
+        ];
+    }
+    const lines = [
+        roster.state === "appended" && roster.appended.length === 0
+            ? `Page roster: reordered ${roster.path}'s rows into template-then-module order`
+            : roster.state === "appended"
+                ? `Page roster: appended ${roster.appended.length} row(s) to ${roster.path}: ${roster.appended.join(", ")}`
+                : `Page roster: ${roster.path} already carries ${moduleName}'s rows`,
+    ];
+    if (roster.problems.length === 0) {
+        lines.push("Page roster check: clean");
+    }
+    else {
+        lines.push(`Page roster check: ${roster.problems.length} problem(s)`);
+        lines.push(...roster.problems.map((p) => `  ${p}`));
+    }
+    return lines;
+}
+export const ADD_MODULE_HELP = `create-ailk add-module — add a purchased module to an existing site.
+
+Usage:
+  create-ailk add-module <module> [<target-dir>]
+  create-ailk upgrade <module> [<target-dir>]
+
+Arguments:
+  <module>                 One paid module, e.g. docs-blog. Needs
+                           AILK_LICENSE_KEY covering it.
+  <target-dir>             An already-scaffolded repo (contains
+                           architecture.yaml). Defaults to the current dir.
+
+Options:
+  --help, -h               Print this message.
+
+Writes the module's files the site lacks and never overwrites one it has: a
+file whose content differs is left as-is and listed for manual review with the
+change the module wanted. Only package.json dependency/script keys,
+next.config.* and jest.config.* are patched. Then copies the module's routes
+and regenerates architecture.yaml. Running it again changes nothing.
+`;
+/**
+ * Parse the argv AFTER the `add-module` / `upgrade` word. Strict
+ * `node:util` parseArgs, like `parseSyncRoutesArgs`; the module is validated
+ * the same way one `--modules` entry is.
+ */
+export function parseAddModuleArgs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", default: false, short: "h" },
+        },
+    });
+    const help = parsed.values.help === true;
+    const [raw, target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`expected a module and at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    if (raw === undefined) {
+        if (help)
+            return { module: undefined, target: undefined, help };
+        throw new ParseError("add-module needs a module name, e.g. `create-ailk add-module docs-blog`");
+    }
+    const modules = parseModules(raw);
+    if (modules.length !== 1) {
+        throw new ParseError(`add-module takes exactly one module, got "${raw}" — run it once per module`);
+    }
+    return { module: modules[0], target, help };
+}