create-ailk 0.21.0 → 0.23.0

package/component-catalog.json

@@ -9,7 +9,7 @@
       "importPath": "@working-theory/ui/sections",
       "rootBarrel": "@working-theory/ui",
       "sourceRoot": "packages/ui/src/sections",
-      "count": 56
+      "count": 57
     },
     {
       "name": "blocks",
@@ -17,7 +17,7 @@
       "importPath": "@working-theory/ui/blocks",
       "rootBarrel": "@working-theory/ui",
       "sourceRoot": "packages/ui/src/blocks",
-      "count": 106
+      "count": 107
     },
     {
       "name": "chrome",
@@ -485,6 +485,17 @@
       "descriptionGrade": "strong",
       "sectionType": "items"
     },
+    {
+      "name": "ItemsFilterIsland",
+      "tier": "sections",
+      "sourcePath": "packages/ui/src/sections/ItemsFilterIsland.tsx",
+      "importPath": "@working-theory/ui/sections",
+      "exported": false,
+      "description": "A search box and facet selects over an items section's cards. Items (a Server Component) renders every card on the server and wraps each in an `ItemsFilterSlot`; the island only decides which slots show. So every card is in the server HTML, and before hydration (or with no JavaScript) every slot is visible.",
+      "descriptionSource": "doc-comment",
+      "descriptionGrade": "strong",
+      "sectionType": null
+    },
     {
       "name": "ItemsTileLinkIsland",
       "tier": "sections",
@@ -837,6 +848,17 @@
       "descriptionGrade": "strong",
       "sectionType": null
     },
+    {
+      "name": "AuthBackLink",
+      "tier": "blocks",
+      "sourcePath": "packages/ui/src/blocks/AuthBackLink.tsx",
+      "importPath": "@working-theory/ui/blocks",
+      "exported": true,
+      "description": "The auth shell's top-start \"← Back to <site>\". A hub's sign-in page renders it when the visitor arrived from a registered spoke, so the cross-domain handoff names where they came from and gives them the way back.",
+      "descriptionSource": "doc-comment",
+      "descriptionGrade": "strong",
+      "sectionType": null
+    },
     {
       "name": "AuthCard",
       "tier": "blocks",
@@ -1415,7 +1437,7 @@
       "sourcePath": "packages/ui/src/blocks/NewsletterFormInline.tsx",
       "importPath": "@working-theory/ui/blocks",
       "exported": true,
-      "description": "Inline email signup form: email Input + submit Button side-by-side at sm+, stacked on mobile (input full-width on its own row, Subscribe below). Manages its own submit state so the parent Newsletter section can remain RSC-oriented (only this block needs the client boundary).",
+      "description": "Inline email signup form: email Input + submit Button side-by-side at md+, stacked on mobile (input full-width on its own row, Subscribe below). Manages its own submit state so the parent Newsletter section can remain RSC-oriented (only this block needs the client boundary).",
       "descriptionSource": "doc-comment",
       "descriptionGrade": "strong",
       "sectionType": null
@@ -4784,6 +4806,30 @@
               "alt"
             ]
           },
+          "avatar": {
+            "type": "object",
+            "properties": {
+              "src": {
+                "type": "string"
+              },
+              "alt": {
+                "type": "string"
+              },
+              "width": {
+                "type": "number"
+              },
+              "height": {
+                "type": "number"
+              },
+              "blurDataURL": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "src",
+              "alt"
+            ]
+          },
           "logoStrip": {
             "type": "object",
             "properties": {
@@ -5324,6 +5370,17 @@
                       "body"
                     ]
                   }
+                },
+                "facets": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 80
+                  }
                 }
               },
               "required": [
@@ -5331,6 +5388,13 @@
               ]
             }
           },
+          "gapAbove": {
+            "type": "string",
+            "enum": [
+              "default",
+              "tight"
+            ]
+          },
           "surface": {
             "type": "string",
             "enum": [
@@ -5349,6 +5413,76 @@
               "card",
               "plain"
             ]
+          },
+          "filter": {
+            "type": "object",
+            "properties": {
+              "searchLabel": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 80
+              },
+              "facets": {
+                "maxItems": 4,
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string",
+                      "pattern": "^[a-z][a-z0-9-]{0,31}$"
+                    },
+                    "label": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 80
+                    },
+                    "allLabel": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 80
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "label",
+                    "allLabel"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "emptyText": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200
+              },
+              "countText": {
+                "type": "object",
+                "properties": {
+                  "one": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 80
+                  },
+                  "other": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 80
+                  }
+                },
+                "required": [
+                  "one",
+                  "other"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "searchLabel",
+              "emptyText",
+              "countText"
+            ],
+            "additionalProperties": false
           }
         },
         "required": [
@@ -5364,7 +5498,8 @@
         "separation",
         "gap",
         "surface",
-        "itemStyle"
+        "itemStyle",
+        "gapAbove"
       ]
     },
     {
@@ -5393,6 +5528,9 @@
           "headline": {
             "type": "string"
           },
+          "subtitle": {
+            "type": "string"
+          },
           "body": {
             "type": "string"
           },
@@ -6753,6 +6891,9 @@
                 "annualBadge": {
                   "type": "string"
                 },
+                "annualCtaHref": {
+                  "type": "string"
+                },
                 "priceSubheadAccent": {
                   "type": "string"
                 },
@@ -6985,6 +7126,9 @@
               "annualBadge": {
                 "type": "string"
               },
+              "annualCtaHref": {
+                "type": "string"
+              },
               "priceSubheadAccent": {
                 "type": "string"
               },
@@ -10713,6 +10857,13 @@
           "hideEventTypeDetails": {
             "type": "boolean"
           },
+          "gapAbove": {
+            "type": "string",
+            "enum": [
+              "default",
+              "tight"
+            ]
+          },
           "fallback": {
             "default": "auto",
             "type": "string",
@@ -10734,7 +10885,8 @@
       "look": [
         "surface",
         "height",
-        "layout"
+        "layout",
+        "gapAbove"
       ]
     },
     {
@@ -11522,13 +11674,19 @@
                 "no-outline",
                 "no-download",
                 "no-print",
-                "no-share"
+                "no-share",
+                "no-zoom",
+                "no-fullscreen"
               ]
             }
           },
           "downloadFilename": {
             "type": "string"
           },
+          "shareUrl": {
+            "type": "string",
+            "format": "uri"
+          },
           "surface": {
             "type": "string",
             "enum": [
@@ -12177,7 +12335,7 @@
       "groups": [
         {
           "name": "colors",
-          "leafCount": 62,
+          "leafCount": 64,
           "leaves": [
             {
               "path": "colors.light.bg",
@@ -12199,6 +12357,11 @@
               "type": "string",
               "value": "#475569"
             },
+            {
+              "path": "colors.light.link",
+              "type": "string",
+              "value": "#2563eb"
+            },
             {
               "path": "colors.light.textMuted",
               "type": "string",
@@ -12354,6 +12517,11 @@
               "type": "string",
               "value": "#94a3b8"
             },
+            {
+              "path": "colors.dark.link",
+              "type": "string",
+              "value": "#60a5fa"
+            },
             {
               "path": "colors.dark.textMuted",
               "type": "string",
@@ -13187,7 +13355,7 @@
         },
         {
           "name": "spacing",
-          "leafCount": 13,
+          "leafCount": 15,
           "leaves": [
             {
               "path": "spacing.controlX",
@@ -13234,6 +13402,16 @@
               "type": "string",
               "value": "1rem"
             },
+            {
+              "path": "spacing.deckLabelLine",
+              "type": "string",
+              "value": "var(--spacing-section-lg)"
+            },
+            {
+              "path": "spacing.deckActionLine",
+              "type": "string",
+              "value": "calc(2 * (var(--control-height-big) + var(--spacing-block-tight)))"
+            },
             {
               "path": "spacing.paragraph",
               "type": "string",

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: **319 component files** across 16 tiers — 56 sections, 106 blocks, 19 chrome, 79 primitives, 6 panels, 8 shells, 5 docs-blog-blocks, 1 docs-blog-chrome, 2 docs-blog-shells, 2 scheduling-sections, 6 scheduling-blocks, 5 signal-collectors-sections, 9 signal-collectors-blocks, 2 commerce-sections, 12 commerce-blocks, 1 commerce-panels. 316 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: **321 component files** across 16 tiers — 57 sections, 107 blocks, 19 chrome, 79 primitives, 6 panels, 8 shells, 5 docs-blog-blocks, 1 docs-blog-chrome, 2 docs-blog-shells, 2 scheduling-sections, 6 scheduling-blocks, 5 signal-collectors-sections, 9 signal-collectors-blocks, 2 commerce-sections, 12 commerce-blocks, 1 commerce-panels. 318 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: **315/319** components carry a capability description derived from source — 44 from the section registry's hand-authored when-to-use text, 236 from the component's own doc-comment header, 35 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: **317/321** components carry a capability description derived from source — 44 from the section registry's hand-authored when-to-use text, 238 from the component's own doc-comment header, 35 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, **281** are *strong* — a capability sentence you could match a requirement against — and **34** 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, **283** are *strong* — a capability sentence you could match a requirement against — and **34** 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** 55/56 · **Blocks** 98/106 · **Chrome** 10/19 · **Primitives** 64/79 (4 undescribed) · **Panels** 5/6 · **Shells** 7/8 · **Docs + Blog Blocks** 5/5 · **Docs + Blog Chrome** 1/1 · **Docs + Blog Shells** 0/2 · **Scheduling Sections** 2/2 · **Scheduling Blocks** 6/6 · **Signal-Collectors Sections** 5/5 · **Signal-Collectors Blocks** 8/9 · **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** 56/57 · **Blocks** 99/107 · **Chrome** 10/19 · **Primitives** 64/79 (4 undescribed) · **Panels** 5/6 · **Shells** 7/8 · **Docs + Blog Blocks** 5/5 · **Docs + Blog Chrome** 1/1 · **Docs + Blog Shells** 0/2 · **Scheduling Sections** 2/2 · **Scheduling Blocks** 6/6 · **Signal-Collectors Sections** 5/5 · **Signal-Collectors Blocks** 8/9 · **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 (56)
+## Sections (57)
 
 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.
 
@@ -93,6 +93,7 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 | `HeroPromptCapture` | The Hero `promptCapture` opt-in's wiring. Composes the two new blocks — `PromptCaptureCard` (the chat-style card) and `SuggestionChipCarousel` (the one-expanded-slot chip row) — and owns the ONE piece of state they share: the typed text. A chip click writes into it; the card renders and edits it; submit carries it onward. | `import { HeroPromptCapture } from "@working-theory/ui/sections"` |
 | `HeroQuickSearch` | Surfaces the existing ⌘K quick-search as an inline trigger inside the hero CTA cluster (Chassis 2). It does NOT re-roll a search input: it composes the SearchInputTrigger primitive (an input-style control at CTA height) plus the Command palette primitive, so there is ONE search mechanism. The nav's compact 24px ⌘K pill stays as-is — the hero reads as a search INPUT, matching the 44px "Get Started" CTA. | internal — compose from `packages/ui/src/sections/HeroQuickSearch.tsx` |
 | `Items` | A general-purpose card/items grid — use for services, use cases, or any homogeneous list of cards. | MDX `type: items` · `import { Items } from "@working-theory/ui/sections"` |
+| `ItemsFilterIsland` | A search box and facet selects over an items section's cards. Items (a Server Component) renders every card on the server and wraps each in an `ItemsFilterSlot`; the island only decides which slots show. So every card is in the server HTML, and before hydration (or with no JavaScript) every slot is visible. | internal — compose from `packages/ui/src/sections/ItemsFilterIsland.tsx` |
 | `ItemsTileLinkIsland` | Makes a whole linked tile card its link's click target. | internal — compose from `packages/ui/src/sections/ItemsTileLinkIsland.tsx` |
 | `LogoCloud` | A customer/partner logo wall — use for trust-by-association social proof. | MDX `type: logoCloud` · `import { LogoCloud } from "@working-theory/ui/sections"` |
 | `MDXContent` | The keystone the docs route and blog both render their compiled MDX through. | `import { MDXContent } from "@working-theory/ui/sections"` |
@@ -120,7 +121,7 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 
 ---
 
-## Blocks (106)
+## Blocks (107)
 
 Intermediate composition tiles — the pieces sections are built from. Compose primitives and panels; never import a section.
 
@@ -136,6 +137,7 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `AskAiCommandGroup` | The ⌘K palette's composable "Ask AI" group; one CommandItem per provider seeding "About <entity>: <query>" (or the entity promptText when the query is empty); composed by the consumer's own CommandDialog. | `import { AskAiCommandGroup } from "@working-theory/ui/blocks"` |
 | `AskAiProviderRow` | The ONE shared provider-link row every ask-AI placement composes — the AskAi section (band + ticker variant) and the Hero `askAi` opt-in all render THIS block, never a per-placement fork. Renders a bounded set of five measured providers, each a deep link seeded with an AUTHORED `promptText` — the prompt is always consumer-supplied data, never derived from page context (headline, entity name, etc.). | `import { AskAiProviderRow } from "@working-theory/ui/blocks"` |
 | `AssetLightbox` | The asset detail lightbox: the image with zoom on the stage, a Details rail with in-place pencil-edit Title and Description, then Filename/Type/Size/Dimensions/Created, then Tags (from the seeded set the caller passes), then Copy link/Replace/Delete. Renders inside a ResponsiveSheet — the SAME field sequence in both layouts (: one field array, walked once, shared by both). | `import { AssetLightbox } from "@working-theory/ui/blocks"` |
+| `AuthBackLink` | The auth shell's top-start "← Back to <site>". A hub's sign-in page renders it when the visitor arrived from a registered spoke, so the cross-domain handoff names where they came from and gives them the way back. | `import { AuthBackLink } from "@working-theory/ui/blocks"` |
 | `AuthCard` | Multi-flow auth card: sign-in, sign-up, invitation, forgot, reset and sent, from one skeleton. One self-contained card renders every auth surface a site needs: signing in, signing up, a closed sign-up that requires an invitation, requesting a password reset, choosing a new password, and the check-your-email state that follows a magic link or a reset request. | `import { AuthCard } from "@working-theory/ui/blocks"` |
 | `AwardBadgePlaceholder` | The labeled placeholder an Awards badge slot renders when no image has been supplied — mirrors MediaPlaceholder's role but in an award-chevron/ laurel badge silhouette rather than a generic photo frame, since an unfilled award slot should read as "an award badge goes here," not "a photo goes here." The shape (a laurel-flanked medallion over a chevron ribbon) is a hand-drawn SVG outline — never a copied G2/Capterra/Apollo asset. | internal — compose from `packages/ui/src/blocks/AwardBadgePlaceholder.tsx` |
 | `BackgroundPattern` | Decorative SVG dot-grid / line pattern for ContactForm section. Decorative block (generalized beyond its original single consumer). Renders an absolutely-positioned decoration behind a section's content. Originally the pattern anchored behind ContactForm's form column; SpotlightPanel composes it as a full-bleed section backdrop (dimmed + blurred, behind a centered card) — same block, a second placement. | `import { BackgroundPattern } from "@working-theory/ui/blocks"` |
@@ -189,7 +191,7 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `NavFlyoutPanel` | Mega-menu body block (feature grid + action bar) for Nav flyouts. Renders the content of a flyout (mega-menu) panel opened by a NavigationMenu trigger in the Nav chrome component. | `import { NavFlyoutPanel } from "@working-theory/ui/blocks"` |
 | `NavSearchTrigger` | ⌘K search trigger control for Nav desktop pill + mobile icon-only surfaces. ⌘K search trigger button for Nav, desktop + mobile. Thin domain wrapper over the ShortcutTrigger primitive: it resolves the i18n "Open search" label and passes the search specifics (Search icon, the ⌘/K shortcut, the onSearchOpen handler) to ShortcutTrigger. | `import { NavSearchTrigger } from "@working-theory/ui/blocks"` |
 | `NewsletterDetail` | One "why subscribe" detail item: colored icon square + headline + description. Vertically arranged (icon top, heading + description below). Used in the right-column 2-up grid of the 'side-by-side-with-details' variant. | `import { NewsletterDetail } from "@working-theory/ui/blocks"` |
-| `NewsletterFormInline` | Inline email signup form: email Input + submit Button side-by-side at sm+, stacked on mobile (input full-width on its own row, Subscribe below). Manages its own submit state so the parent Newsletter section can remain RSC-oriented (only this block needs the client boundary). | `import { NewsletterFormInline } from "@working-theory/ui/blocks"` |
+| `NewsletterFormInline` | Inline email signup form: email Input + submit Button side-by-side at md+, stacked on mobile (input full-width on its own row, Subscribe below). Manages its own submit state so the parent Newsletter section can remain RSC-oriented (only this block needs the client boundary). | `import { NewsletterFormInline } from "@working-theory/ui/blocks"` |
 | `OnboardingChecklist` | Global onboarding launcher: floating "N/5" bubble expanding into a Popover (lg+) / bottom Sheet (<lg) checklist with SegmentedProgress + item rows (ploy-capture recomposition). The global onboarding launcher captured off ploy.ai's app frame (behavior spec: `post-ftu-checklist` — "global onboarding launcher (floating, all pages)"). | `import { OnboardingChecklist } from "@working-theory/ui/blocks"` |
 | `PageHeader` | 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`. *(weak)* | `import { PageHeader } from "@working-theory/ui/blocks"` |
 | `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"` |

package/dist/add-module.js

@@ -35,7 +35,7 @@ import { writeAuthSecretFile } from "./lib/auth-secret-file.js";
 import { appendEnvRows } from "./lib/declared-env.js";
 import { diffTwoStrings, extractModuleBundle, } from "./lib/extract-module-bundle.js";
 import { normalizeModules } from "./module-architecture.js";
-import { PAID_SECTIONS_PATH, writePaidSections } from "./paid-sections.js";
+import { MODULE_FLAGS_PATH, PAID_SECTIONS_PATH, writePaidSections } from "./paid-sections.js";
 import { ParseError, parseModules } from "./parse-args.js";
 import { writeSpokeFlowsReadme } from "./seed-flows.js";
 import { SITE_ROSTER_PATH, moduleRosterRows, planRosterAppend, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
@@ -168,16 +168,20 @@ export async function applyModuleToScaffold(opts) {
             }
             : {}),
     });
-    // #7838 D8 — commerce on a spoke brings the spoke's own checkout, stamped
-    // from the site directory's name (the `projectName` scaffold() defaults to).
-    // A file the site already has is left as it is. #8217 D8 — on a spoke that
-    // signs in through its hub, the billing action and its seam render too, so
-    // re-running add-module commerce gives an existing commerce spoke the action.
+    // #7838 D8 — commerce on a spoke brings the spoke's own checkout — the
+    // standard, copied from the template (#8748 D3) — stamped from the site
+    // directory's name (the `projectName` scaffold() defaults to). A file the
+    // site already has is left as it is. No record row: the record is written
+    // only at scaffold time. #8217 D8 — on a spoke that signs in through its
+    // hub, the billing action and its seam render too, so re-running
+    // add-module commerce gives an existing commerce spoke the action.
     const spokeCommerce = spoke !== undefined && opts.moduleName === "commerce";
     const checkoutRows = spokeCommerce
         ? writeSpokeCheckoutSlice(targetAbs, {
             site: spokeCheckoutSite(basename(targetAbs)),
+            projectName: basename(targetAbs),
             versions: opts.versions,
+            templatesDir: opts.templatesDir,
             signIn: spoke.signIn,
         })
         : [];
@@ -205,16 +209,18 @@ export async function applyModuleToScaffold(opts) {
     // #7536 D3 — the paid-sections registry follows `apps/web/package.json`,
     // which the bundle's `patches` just edited. Generated and always
     // overwritten, like `architecture.yaml` above.
-    const registryPath = join(targetAbs, PAID_SECTIONS_PATH);
-    const registryBefore = existsSync(registryPath)
-        ? readFileSync(registryPath, "utf8")
-        : undefined;
+    // #8843 D10 — its module-presence flags follow the same file, and are
+    // reported the same way when a module turns one on.
+    const generated = [PAID_SECTIONS_PATH, MODULE_FLAGS_PATH].map((path) => {
+        const abs = join(targetAbs, path);
+        return { path, abs, before: existsSync(abs) ? readFileSync(abs, "utf8") : undefined };
+    });
     writePaidSections(targetAbs);
-    const registryChanged = existsSync(registryPath) &&
-        readFileSync(registryPath, "utf8") !== registryBefore;
     const rows = [...report, ...checkoutRows];
-    if (registryChanged)
-        rows.push({ path: PAID_SECTIONS_PATH, action: "written" });
+    for (const { path, abs, before } of generated) {
+        if (existsSync(abs) && readFileSync(abs, "utf8") !== before)
+            rows.push({ path, action: "written" });
+    }
     const navRow = syncNavConfig(targetAbs, current.surfaces, surfaces);
     if (navRow !== undefined)
         rows.push(navRow);

package/dist/add-route.d.ts

@@ -40,17 +40,71 @@ export interface AddRouteResult {
 export declare function addRouteToScaffold(opts: AddRouteOptions): AddRouteResult;
 /** The report `add-route` prints. */
 export declare function formatAddRouteReport(result: AddRouteResult): string;
+/** The route word that selects the magnet mode. */
+export declare const MAGNET_ROUTE = "magnet";
+/**
+ * The header-comment marker every standard magnet page carries — the same
+ * string `flows/[slug]/magnet-page.tsx` exports, which the site's
+ * `structured-data.test.tsx` reads to exempt the pair (#8840 D13).
+ */
+export declare const MAGNET_PAGE_MARKER = "Standard magnet page (#8840)";
+/** Whether `slug` passes `flowSlugSchema`'s rule. */
+export declare function isMagnetFlowSlug(slug: string): boolean;
+export interface AddMagnetOptions {
+    /** The already-scaffolded site. */
+    targetDir: string;
+    /** The site path the landing serves, e.g. `/diagnostic`. */
+    path: string;
+    /** The flow slug the pair is bound to. */
+    flow: string;
+}
+/** One page of the pair: written, or left as the site has it. */
+export interface MagnetReportRow {
+    path: string;
+    action: "written" | "skipped";
+}
+export interface AddMagnetResult {
+    /** Resolved absolute path to the site. */
+    targetDir: string;
+    /** The landing's site path. */
+    path: string;
+    /** The bound flow slug. */
+    flow: string;
+    /** The landing's row, then the walk's. */
+    report: MagnetReportRow[];
+}
+/**
+ * Write a magnet page pair — `apps/web/app/[locale]/<path>/page.tsx` (the
+ * landing) and `<path>/start/page.tsx` (the walk) — bound to one flow slug.
+ * Each page is a few lines over the factories in `flows/[slug]/magnet-page`;
+ * the copy, consent and ending come from the flow's record.
+ *
+ * Every refusal throws `AddRouteRefusedError` before the first write. A page
+ * that already exists is never overwritten: a second run reports both
+ * `skipped`. No `architecture.yaml`, nav or seed changes — the pair is the
+ * site's own, with no `ROUTE_SINCE` key or routes-map row (D13).
+ */
+export declare function addMagnetToScaffold(opts: AddMagnetOptions): AddMagnetResult;
+/** The report `add-route magnet` prints. */
+export declare function formatAddMagnetReport(result: AddMagnetResult): string;
 export interface AddRouteArgs {
     /** The route to add; undefined only with `help`. */
     route: string | undefined;
     /** Positional target directory; undefined = the caller's cwd. */
     target: string | undefined;
     help: boolean;
+    /** `--path`, the magnet mode's site path — set only with `magnet`. */
+    path?: string;
+    /** `--flow`, the magnet mode's flow slug — set only with `magnet`. */
+    flow?: string;
 }
-export declare const ADD_ROUTE_HELP = "create-ailk add-route \u2014 add a route family to an existing site.\n\nUsage:\n  create-ailk add-route <route> [<target-dir>]\n\nArguments:\n  <route>                  One route family, named as --surfaces names it,\n                           e.g. pricing.\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\nCopies the route's pages, writes its seed content, declares it in\narchitecture.yaml and adds its link to the generated nav \u2014 the site a fresh\nscaffold with --surfaces <route> would have been. A file the site already has\nis never overwritten: one whose content differs, a hand-edited nav included,\nis left as-is and listed for manual review with the change the route wanted.\nLike add-module, it also restores any other page route the site carries but\nlacks. A route a module delivers (blog and docs come with docs-blog) is\nrefused; add that module with create-ailk add-module. Running it again changes\nnothing.\n";
+export declare const ADD_ROUTE_HELP = "create-ailk add-route \u2014 add a route family to an existing site.\n\nUsage:\n  create-ailk add-route <route> [<target-dir>]\n  create-ailk add-route magnet --path <path> --flow <slug> [<target-dir>]\n\nArguments:\n  <route>                  One route family, named as --surfaces names it,\n                           e.g. pricing.\n  <target-dir>             An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n\nOptions:\n  --path <path>            magnet only: the site path the landing serves,\n                           one to three kebab-case segments, e.g. /diagnostic.\n  --flow <slug>            magnet only: the flow slug the pages are bound to.\n  --help, -h               Print this message.\n\nCopies the route's pages, writes its seed content, declares it in\narchitecture.yaml and adds its link to the generated nav \u2014 the site a fresh\nscaffold with --surfaces <route> would have been. A file the site already has\nis never overwritten: one whose content differs, a hand-edited nav included,\nis left as-is and listed for manual review with the change the route wanted.\nLike add-module, it also restores any other page route the site carries but\nlacks. A route a module delivers (blog and docs come with docs-blog) is\nrefused; add that module with create-ailk add-module. Running it again changes\nnothing.\n\nadd-route magnet writes a magnet page pair bound to one flow: a landing at\napps/web/app/[locale]/<path>/page.tsx and a full-screen walk at\n<path>/start/page.tsx, each a few lines over the standard magnet pages, so the\ncopy, consent and ending come from the flow's record. It needs the\nsignal-collectors module, and refuses (nothing written) a path the site already\nserves, a one-segment path a LandingPage seed of the same slug owns, a path\nending in start or apply, a reserved first segment (api, v1, flows, account,\nadmin, the sign-in routes, a locale) and a slug the flow API would refuse. A\npage that exists is never overwritten: running it again skips both. It changes\nno architecture.yaml, nav or seed.\n";
 /**
  * Parse the argv AFTER the `add-route` word. Strict `node:util` parseArgs,
  * like `parseAddModuleArgs`; the route itself is validated by
  * `addRouteToScaffold`, which refuses an unknown one naming the recognized.
+ * `--path` and `--flow` belong to the `magnet` route word alone (#8840 D12):
+ * with any other route they are refused (`AddRouteRefusedError`, exit 2),
+ * and `magnet` needs both. Their values are checked by `addMagnetToScaffold`.
  */
 export declare function parseAddRouteArgs(argv: string[]): AddRouteArgs;