create-ailk 0.6.1 → 0.7.0

package/README.md

@@ -27,11 +27,50 @@ Every recognized module except `marketing` is a paid module, delivered under a
 license key rather than shipped inside this package — see
 [Paid modules require `AILK_LICENSE_KEY`](#paid-modules-require-ailk_license_key).
 
+### Add a purchased module to an existing site
+
+A site scaffolded without a paid module (a Free site whose owner then buys
+Pro, say) gets it with `add-module` — alias `upgrade` — run against the site
+itself, with `AILK_LICENSE_KEY` covering the module:
+
+```bash
+# in an already-scaffolded repo (default target: cwd)
+AILK_LICENSE_KEY=<key> create-ailk add-module docs-blog
+# or point at the repo explicitly
+AILK_LICENSE_KEY=<key> create-ailk upgrade docs-blog ./my-site
+```
+
+It fetches the module's bundle through the same licence gate a scaffold uses
+(no key, or a key that does not cover the module, is refused with the same
+message, before anything is written) and merges it **without overwriting
+anything the site has**:
+
+- a file the site lacks is written;
+- a file the site already has is left as-is — if its content differs from the
+  module's, the report lists it under _Needs manual review_ with the exact
+  change the module wanted, for you to apply by hand;
+- the only edits to existing files are the module's config patches, and only
+  to `package.json` dependency and script keys, `next.config.*` and
+  `jest.config.*` — each reported with its diff.
+
+It then copies in the module's route directories, together with any other
+template route the site is missing (the same set `sync-routes --apply` copies,
+so a core route you deleted comes back and is listed in the report), regenerates `architecture.yaml`
+for the site's modules plus this one, and regenerates the site nav unless you
+have edited it. On a site scaffolded from a template, it also appends the
+module's pages to the site's roster (`TEMPLATE-MANIFEST.json`) — replacing a
+template placeholder page the module takes over, such as the Free `/blog`
+teaser, whose seed is removed only if you have not edited it — and prints the
+result of the roster check (`Page roster check: clean`). Running it again
+changes nothing and reports nothing to add.
+Run `pnpm install` afterwards.
+
 ### Sync `architecture.yaml` after adding a module
 
-When a module is added to an already-scaffolded repo, regenerate its
-`architecture.yaml` in place with `--sync-architecture <csv>` (recognized
-modules are the same set as `--modules`):
+`add-module` above regenerates `architecture.yaml` itself. To regenerate it by
+hand for a module set — after changing modules some other way — use
+`--sync-architecture <csv>` (recognized modules are the same set as
+`--modules`):
 
 ```bash
 # in an already-scaffolded repo (default target: cwd)
@@ -86,7 +125,7 @@ this is the marketing core." A gateable surface's routes (`blog`, `docs`,
 `flows`, …) are checked only when the site carries that surface; a surface
 gated off at scaffold time is listed as skipped, not missing — its absence is
 deliberate, not drift. Add a surface with `--sync-architecture` and the
-`scaffold-page` skill, not with `sync-routes`.
+`add-page` skill, not with `sync-routes`.
 
 **The lib-and-messages dependency contract (#5014).** Some routes import
 files OUTSIDE their own route directory — `sign-in/page.tsx` imports

package/component-catalog.json

@@ -17,7 +17,7 @@
       "importPath": "@working-theory/ui/blocks",
       "rootBarrel": "@working-theory/ui",
       "sourceRoot": "packages/ui/src/blocks",
-      "count": 95
+      "count": 97
     },
     {
       "name": "chrome",
@@ -958,6 +958,17 @@
       "descriptionGrade": "strong",
       "sectionType": null
     },
+    {
+      "name": "ConsentSettingsButton",
+      "tier": "blocks",
+      "sourcePath": "packages/ui/src/blocks/ConsentSettingsButton.tsx",
+      "importPath": "@working-theory/ui/blocks",
+      "exported": false,
+      "description": "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.",
+      "descriptionSource": "doc-comment",
+      "descriptionGrade": "strong",
+      "sectionType": null
+    },
     {
       "name": "ConsentStatement",
       "tier": "blocks",
@@ -1398,6 +1409,17 @@
       "descriptionGrade": "strong",
       "sectionType": null
     },
+    {
+      "name": "PostCard",
+      "tier": "blocks",
+      "sourcePath": "packages/ui/src/blocks/PostCard.tsx",
+      "importPath": "@working-theory/ui/blocks",
+      "exported": true,
+      "description": "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.",
+      "descriptionSource": "doc-comment",
+      "descriptionGrade": "weak",
+      "sectionType": null
+    },
     {
       "name": "PostRow",
       "tier": "blocks",
@@ -3650,6 +3672,13 @@
               "tight"
             ]
           },
+          "measure": {
+            "type": "string",
+            "enum": [
+              "full",
+              "narrow"
+            ]
+          },
           "lightboxCta": {
             "type": "object",
             "properties": {
@@ -4640,7 +4669,8 @@
               "default",
               "mockup",
               "alternating",
-              "split-grid"
+              "split-grid",
+              "steps"
             ]
           },
           "eyebrow": {
@@ -4691,6 +4721,20 @@
               "landscape"
             ]
           },
+          "itemStyle": {
+            "type": "string",
+            "enum": [
+              "card",
+              "plain"
+            ]
+          },
+          "actionsPosition": {
+            "type": "string",
+            "enum": [
+              "header",
+              "below"
+            ]
+          },
           "features": {
             "type": "array",
             "items": {
@@ -5043,6 +5087,9 @@
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "type": "object",
         "properties": {
+          "imagerySlot": {
+            "type": "boolean"
+          },
           "variant": {
             "type": "string",
             "enum": [
@@ -5936,7 +5983,8 @@
               "grid",
               "static",
               "featured",
-              "bylined"
+              "bylined",
+              "quote"
             ]
           },
           "headline": {
@@ -6159,6 +6207,20 @@
               "included-dots"
             ]
           },
+          "cardLayout": {
+            "type": "string",
+            "enum": [
+              "default",
+              "centered"
+            ]
+          },
+          "toggleStyle": {
+            "type": "string",
+            "enum": [
+              "soft",
+              "solid"
+            ]
+          },
           "addonLayout": {
             "type": "string",
             "enum": [
@@ -6889,6 +6951,17 @@
           },
           "closingLine": {
             "type": "string"
+          },
+          "checklist": {
+            "minItems": 1,
+            "maxItems": 5,
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "imagerySlot": {
+            "type": "boolean"
           }
         },
         "required": [
@@ -6909,6 +6982,13 @@
           "headline": {
             "type": "string"
           },
+          "headlineStyle": {
+            "type": "string",
+            "enum": [
+              "heading",
+              "label"
+            ]
+          },
           "logos": {
             "type": "array",
             "items": {
@@ -7837,7 +7917,8 @@
             "type": "string",
             "enum": [
               "with-small-images",
-              "with-large-images"
+              "with-large-images",
+              "with-side-images"
             ]
           },
           "avatarSize": {
@@ -8713,6 +8794,13 @@
               "totalPages",
               "baseUrl"
             ]
+          },
+          "variant": {
+            "type": "string",
+            "enum": [
+              "list",
+              "grid"
+            ]
           }
         },
         "required": [
@@ -9539,6 +9627,12 @@
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "type": "object",
         "properties": {
+          "eyebrow": {
+            "type": "string"
+          },
+          "imagerySlot": {
+            "type": "boolean"
+          },
           "headline": {
             "type": "string"
           },
@@ -9995,6 +10089,16 @@
           "navGroupLabel": {
             "type": "string"
           },
+          "layout": {
+            "type": "string",
+            "enum": [
+              "rail",
+              "article"
+            ]
+          },
+          "updated": {
+            "type": "string"
+          },
           "stats": {
             "minItems": 2,
             "maxItems": 4,
@@ -11441,22 +11545,22 @@
             {
               "path": "typography.display.fontSize",
               "type": "string",
-              "value": "3.75rem"
+              "value": "3.5rem"
             },
             {
               "path": "typography.display.lineHeight",
               "type": "string",
-              "value": "1"
+              "value": "1.1"
             },
             {
               "path": "typography.display.fontWeight",
               "type": "string",
-              "value": "400"
+              "value": "700"
             },
             {
               "path": "typography.display.letterSpacing",
               "type": "string",
-              "value": "-0.05em"
+              "value": "0"
             },
             {
               "path": "typography.display-sm.fontSize",
@@ -11466,42 +11570,42 @@
             {
               "path": "typography.display-sm.lineHeight",
               "type": "string",
-              "value": "1.05"
+              "value": "1.1"
             },
             {
               "path": "typography.display-sm.fontWeight",
               "type": "string",
-              "value": "400"
+              "value": "700"
             },
             {
               "path": "typography.display-sm.letterSpacing",
               "type": "string",
-              "value": "-0.025em"
+              "value": "0"
             },
             {
               "path": "typography.display-lg.fontSize",
               "type": "string",
-              "value": "6rem"
+              "value": "3.5rem"
             },
             {
               "path": "typography.display-lg.lineHeight",
               "type": "string",
-              "value": "1"
+              "value": "1.1"
             },
             {
               "path": "typography.display-lg.fontWeight",
               "type": "string",
-              "value": "400"
+              "value": "700"
             },
             {
               "path": "typography.display-lg.letterSpacing",
               "type": "string",
-              "value": "-0.05em"
+              "value": "0"
             },
             {
               "path": "typography.display-mobile.fontSize",
               "type": "string",
-              "value": "2rem"
+              "value": "2.5rem"
             },
             {
               "path": "typography.display-mobile.lineHeight",
@@ -11511,12 +11615,12 @@
             {
               "path": "typography.display-mobile.fontWeight",
               "type": "string",
-              "value": "500"
+              "value": "700"
             },
             {
               "path": "typography.display-mobile.letterSpacing",
               "type": "string",
-              "value": "-0.02em"
+              "value": "0"
             },
             {
               "path": "typography.subhead-mobile.fontSize",
@@ -11591,7 +11695,7 @@
             {
               "path": "typography.heading-3.fontWeight",
               "type": "string",
-              "value": "600"
+              "value": "700"
             },
             {
               "path": "typography.heading-3.letterSpacing",
@@ -11760,6 +11864,17 @@
             }
           ]
         },
+        {
+          "name": "typographyLg",
+          "leafCount": 1,
+          "leaves": [
+            {
+              "path": "typographyLg.heading-3.fontSize",
+              "type": "string",
+              "value": "2rem"
+            }
+          ]
+        },
         {
           "name": "displayOpticalOffset",
           "leafCount": 1,
@@ -11887,7 +12002,7 @@
         },
         {
           "name": "spacing",
-          "leafCount": 12,
+          "leafCount": 13,
           "leaves": [
             {
               "path": "spacing.controlX",
@@ -11914,6 +12029,11 @@
               "type": "string",
               "value": "4rem"
             },
+            {
+              "path": "spacing.sectionLg",
+              "type": "string",
+              "value": "7rem"
+            },
             {
               "path": "spacing.sectionCompact",
               "type": "string",
@@ -12000,7 +12120,7 @@
         },
         {
           "name": "container",
-          "leafCount": 4,
+          "leafCount": 5,
           "leaves": [
             {
               "path": "container.sm",
@@ -12021,6 +12141,11 @@
               "path": "container.xl",
               "type": "string",
               "value": "1280px"
+            },
+            {
+              "path": "container.measure",
+              "type": "string",
+              "value": "36rem"
             }
           ]
         },

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: **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.
 
-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: **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.
 
-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, **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%**.
 
-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** 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.
 
 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.
 
@@ -118,7 +118,7 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 
 ---
 
-## Blocks (95)
+## Blocks (97)
 
 Intermediate composition tiles — the pieces sections are built from. Compose primitives and panels; never import a section.
 
@@ -147,6 +147,7 @@ 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"` |
 | `ContactFormFields` | Renders the form field grid (Input / Textarea / Select primitives) + submit Button + optional consent text footer. | `import { ContactFormFields } from "@working-theory/ui/blocks"` |
@@ -188,6 +189,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 +531,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;