create-ailk 0.22.0 → 0.24.0

package/README.md

@@ -214,9 +214,9 @@ as-is, they never fail the check, and `--apply` never overwrites them.
 
 `--apply` only creates route directories that are absent, through the same
 copier a fresh scaffold uses (so the copied files are byte-identical to a fresh
-scaffold's). It never rewrites or deletes an existing file, never writes
-outside `apps/web/app/[locale]/`, runs no install, and a second run is a
-no-op. `--apply` exits 0 on success.
+scaffold's). It never rewrites or deletes an existing file, writes nothing
+outside `apps/web/app/[locale]/` except the local modules those routes import
+(below), runs no install, and a second run is a no-op. `--apply` exits 0 on success.
 
 **Scope.** Every core route (`about`, `contact`, `faq`, `thanks/[slug]`,
 `sign-in`) is always checked, and so is the `(authed)` route GROUP —
@@ -232,17 +232,30 @@ 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
 `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
-`apps/web/lib/auth-env.ts` and `lib/site-brand.tsx`; the `(authed)` group's
-`layout.tsx` imports `apps/web/auth.ts`; `(authed)/account/page.tsx` imports
-`lib/account-config.ts`, `lib/server-api.ts`, and two files from its
-`(authed)/waitlist` sibling (`components/ForbiddenState.tsx`, `format.ts`).
-Copying a route's directory alone would leave those imports dangling in an
-older consumer that never had them. `ROUTE_DEPENDENCIES` in `src/surfaces.ts`
-declares them per route; `sync-routes` copies each one `--apply` finds
-missing (never overwriting — the same rule routes themselves follow) and
-reports it in check mode under an `Also required` heading. `ROUTE_MESSAGE_NAMESPACES`
+**The local-module dependency contract (#5014, #9406).** Some routes import
+files OUTSIDE their own route directory — `purchase/success/page.tsx` imports
+`apps/web/src/lib/commerce-claim.ts`; the `(authed)` group's `layout.tsx`
+imports `apps/web/auth.ts`. Copying a route's directory alone would leave those
+imports dangling in an older consumer that never had them. So `sync-routes`
+resolves every relative import (`./`, `../`) of every file the route would
+copy, and of every helper that brings in turn, against the site first and then
+the template. `ROUTE_DEPENDENCIES` in `src/surfaces.ts` is a declared
+supplement, unioned with what the resolver finds. Each imported module has one
+of three outcomes:
+
+- **Copied** — the site lacks it and the template has it: `--apply` copies it
+  (never overwriting) and check mode lists it under `copies:` and `Also
+  required`.
+- **Left as-is** — the site has it and its copy differs from the template's:
+  it is named under `left as-is (differs from the template)` and never
+  written. The route is still copied; run your type-check afterwards.
+- **Refused** — the import resolves to no file in the site or the template,
+  only to a spoke-excluded file, or to a surface the site does not carry: the
+  route is listed under `cannot resolve:` and `--apply` does not write it, nor
+  its sub-routes, nor a route that imports from it. Its ancestor route is still
+  copied without the refused sub-tree.
+
+`ROUTE_MESSAGE_NAMESPACES`
 does the same for the i18n namespaces a route's copy needs
 (`signIn`, `account`, `waitlistDashboard.gate`) — but CHECK-ONLY: a
 consumer's `apps/web/messages/<locale>.json` already exists and may carry

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",
@@ -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",
@@ -1426,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
@@ -4795,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": {
@@ -5335,6 +5370,17 @@
                       "body"
                     ]
                   }
+                },
+                "facets": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 80
+                  }
                 }
               },
               "required": [
@@ -5342,6 +5388,13 @@
               ]
             }
           },
+          "gapAbove": {
+            "type": "string",
+            "enum": [
+              "default",
+              "tight"
+            ]
+          },
           "surface": {
             "type": "string",
             "enum": [
@@ -5360,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": [
@@ -5375,7 +5498,8 @@
         "separation",
         "gap",
         "surface",
-        "itemStyle"
+        "itemStyle",
+        "gapAbove"
       ]
     },
     {
@@ -6767,6 +6891,9 @@
                 "annualBadge": {
                   "type": "string"
                 },
+                "annualCtaHref": {
+                  "type": "string"
+                },
                 "priceSubheadAccent": {
                   "type": "string"
                 },
@@ -6999,6 +7126,9 @@
               "annualBadge": {
                 "type": "string"
               },
+              "annualCtaHref": {
+                "type": "string"
+              },
               "priceSubheadAccent": {
                 "type": "string"
               },
@@ -10727,6 +10857,13 @@
           "hideEventTypeDetails": {
             "type": "boolean"
           },
+          "gapAbove": {
+            "type": "string",
+            "enum": [
+              "default",
+              "tight"
+            ]
+          },
           "fallback": {
             "default": "auto",
             "type": "string",
@@ -10748,7 +10885,8 @@
       "look": [
         "surface",
         "height",
-        "layout"
+        "layout",
+        "gapAbove"
       ]
     },
     {
@@ -11536,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": [

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: **320 component files** across 16 tiers — 56 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. 317 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: **316/320** components carry a capability description derived from source — 44 from the section registry's hand-authored when-to-use text, 237 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, **282** 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** 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.
+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"` |
@@ -190,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";
@@ -209,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);
@@ -349,7 +351,9 @@ export function formatAddModuleReport(result, moduleName) {
     const lines = [
         `[create-ailk] add-module ${moduleName} → ${result.targetDir}`,
     ];
-    if (result.report.length === 0 && result.routes.applied.length === 0) {
+    if (result.report.length === 0 &&
+        result.routes.applied.length === 0 &&
+        result.routes.refused.length === 0) {
         lines.push(`Nothing to add — the site already carries everything ${moduleName} brings.`);
     }
     if (written.length > 0) {
@@ -385,6 +389,9 @@ export function formatAddModuleReport(result, moduleName) {
         lines.push(`Also copied ${routes.appliedDependencies.length} file(s) those routes import:`);
         lines.push(...routes.appliedDependencies.map((dep) => `  ${dep}`));
     }
+    if (routes.refused.length > 0) {
+        lines.push(`Routes not copied (${routes.refused.length}) — an import does not resolve (run create-ailk sync-routes for the paths): ${routes.refused.join(", ")}`);
+    }
     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}`));

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;