create-ailk 0.31.0 → 0.33.0

package/README.md

@@ -393,6 +393,15 @@ merge-file` against the recorded version's own copy as the base. A clean
   **Added**, unless it sits under a route or directory the site deliberately
   does not carry (a gated-off surface, a spoke exclusion, or a directory you
   deleted entirely) — those are left alone.
+- A surface no module owns (such as `projects`) that a page row of the
+  site's `.ailk-site-manifest.json` names, but `architecture.yaml` does not
+  declare, is in scope for adding: its route files are **Added** and
+  recorded, and `architecture.yaml` is regenerated to declare it. Reported
+  as **Surfaces declared from the roster**.
+- A code-route row (`kind: "route"`) of `.ailk-site-manifest.json` that no
+  page file under `apps/web/app/[locale]/` serves (a spoke's `/sign-in`) is
+  dropped from the roster after the writes, every other byte of the file
+  kept. Reported as **Roster rows dropped, no route serves them**.
 
 A file outside the gated-off surfaces and spoke exclusions the site's scope
 no longer covers is **Skipped**, as is one that exists on disk but was never
@@ -425,7 +434,8 @@ never a shell. Fetching an old template version (when it is not the running
 package's own) reads the public npm registry at
 `https://registry.npmjs.org`, overridable with `AILK_NPM_REGISTRY_URL` for a
 mirror. `update` never touches content, except to give an mdx-body page
-with no `# ` heading its title and description (below), nor env files,
+with no `# ` heading its title and description and to escape a bare `{` on
+an mdx-body page (both below), nor env files,
 `.claude/`, lockfiles or any `package.json` — those stay `add-module`'s and
 the consumer version bump's job. Commit before running `update`, and review the diff after: a
 clean merge is still worth reading.
@@ -444,6 +454,27 @@ folded `>` block, say), is listed under **Needs review** for you to fix.
 Which pages are mdx-body is read from your own `apps/web/app` routes, and the
 step runs again harmlessly on every update.
 
+**Placeholder braces (#10773).** MDX reads a `{` in a page body as
+JavaScript, so on an mdx-body page a bare placeholder such as
+`{First engagement}` fails the page with a 500, and one that parses
+(`{Tagline}`) renders as nothing. After the heading step, `update` writes a
+`\` before every bare `{` on each mdx-body page — never in frontmatter, fenced
+or inline code, a JSX tag or a `{/* … */}` comment — and keeps the page's
+change only when your site's own MDX parser (the `@mdx-js/mdx` its
+`next-mdx-remote` uses) then reads the page with no expression left but
+comments. Each such page is listed under **Placeholder brace escaped**; one
+byte per brace changes and nothing else. A page it cannot escape safely (a
+mangled `{/ … /}` comment, or another MDX error the escape does not reach)
+is left alone and listed under **Needs review** with the line, and so is
+every page with a bare brace while the site's dependencies are not installed
+(run `pnpm install`, then `update` again). A fresh scaffold also runs
+`pnpm mdx-body:check` in `preflight` and CI, which names each bare brace by
+file, line and column before a deploy. A site scaffolded before it gains the
+check by copying `tools/check-mdx-body.ts`, `tools/mdx-braces.ts` and
+`tools/body-heading.ts` from a fresh scaffold and adding
+`"mdx-body:check": "tsx tools/check-mdx-body.ts"` to its `package.json`
+scripts and `preflight`.
+
 ### Adopting an existing site
 
 A site that create-ailk did not scaffold, or that was scaffolded before
@@ -625,13 +656,24 @@ a workspace: each `content/en/<Type>/<slug>.mdx` page, and each legacy
 
 When the site has the docs-blog tree `apps/web/content`, its posts and docs
 are imported too (#10701): `apps/web/content/en/blog/<slug>.mdx` and
-`blog/<slug>/index.mdx` become `BlogPosting/<slug>`, the same under `docs`
-become `DocsDetail/<slug>`, and each directory's own `index.mdx` becomes its
-`BlogList/index` or `DocsList/index` — replacing a `content/` teaser of that
-type. Their fumadocs frontmatter is mapped to the stored fields (`date` →
-`publishedAt`, `updated` → `updatedAt`); keys the store does not keep from a
-caller (`featured`, `sidebar`, `tags`) are not sent, and `--apply` names them
-in one line per file. Each outcome carries `root: "content"` or
+`blog/<slug>/index.mdx` become `BlogPosting/<slug>`, or one series down,
+`blog/<series>/<post>.mdx` (or `<post>/index.mdx`), as a `BlogPosting/<post>`
+whose `parent` is the series (#10775) — served at `/blog/<series>/<post>`, the
+URL its file serves at; the same under `docs` become `DocsDetail/<slug>`, and
+each directory's own `index.mdx` becomes its `BlogList/index` or
+`DocsList/index` — replacing a `content/` teaser of that type. A blog post's
+`parent` comes from its path, never its frontmatter, and a file the walk skips
+is listed with the rule it failed. Their fumadocs frontmatter is mapped to
+the stored fields (`date` →
+`publishedAt`, `updated` → `updatedAt`); every other key — the template's
+`featured` and `sidebar`, or a site's own such as `imageAlt` or `sources` —
+is sent in the page's `siteFields` under its own name, and a blog post's
+`tags` are sent as its categories (#10806). A key the store cannot keep is
+named with its reason under `--apply`, in one line per file:
+`<path>: not imported — <key> (<reason>); …`. A hub that predates site
+fields and drops them is named too: `<path>: not kept by the hub: <keys> (…)`.
+`export-content` writes `siteFields` back as top-level frontmatter keys.
+Each outcome carries `root: "content"` or
 `root: "editorial"`, and an editorial line is printed prefixed `editorial: `.
 
 ```bash

package/component-catalog.json

@@ -17,7 +17,7 @@
       "importPath": "@working-theory/ui/blocks",
       "rootBarrel": "@working-theory/ui",
       "sourceRoot": "packages/ui/src/blocks",
-      "count": 107
+      "count": 108
     },
     {
       "name": "chrome",
@@ -1695,6 +1695,17 @@
       "descriptionGrade": "strong",
       "sectionType": null
     },
+    {
+      "name": "ScoreBar",
+      "tier": "blocks",
+      "sourcePath": "packages/ui/src/blocks/ScoreBar.tsx",
+      "importPath": "@working-theory/ui/blocks",
+      "exported": true,
+      "description": "One labelled score bar on a scored magnet's results page: a label (the overall score's, or a dimension's name), the points out of the most a respondent could score, the Level name that share falls in, and one bar filled to the evaluator's own `pct` (`evaluateWaitlistScoring` returns `{ points, max, pct, level }` for the total and per dimension).",
+      "descriptionSource": "doc-comment",
+      "descriptionGrade": "strong",
+      "sectionType": null
+    },
     {
       "name": "SectionActionRow",
       "tier": "blocks",

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: **324 component files** across 16 tiers — 60 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. 321 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: **325 component files** across 16 tiers — 60 sections, 108 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. 322 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: **320/324** components carry a capability description derived from source — 45 from the section registry's hand-authored when-to-use text, 240 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: **321/325** components carry a capability description derived from source — 45 from the section registry's hand-authored when-to-use text, 241 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, **286** 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, **287** 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** 59/60 · **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** 59/60 · **Blocks** 100/108 · **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.
 
@@ -124,7 +124,7 @@ Import: `import { X } from "@working-theory/ui/sections";` (or from the `@workin
 
 ---
 
-## Blocks (107)
+## Blocks (108)
 
 Intermediate composition tiles — the pieces sections are built from. Compose primitives and panels; never import a section.
 
@@ -215,6 +215,7 @@ Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-
 | `ResponsiveSheet` | ONE component, TWO forms, ONE open pair. Renders its `children` as a Radix Dialog at `md` (768px, --breakpoint-md) and up, and as a full-screen Radix Sheet below it — never both at once. | `import { ResponsiveSheet } from "@working-theory/ui/blocks"` |
 | `RowGroup` | The bordered box that groups ListRows with hairline dividers. The reference is `packages-paid/admin/design/demos/first-steps/demo.html`'s `.box` (`background:var(--bg);border:1px solid var(--border); border-radius:6px;overflow:hidden`) with `.row{border-top:…}` and `.row:first-child{border-top:0}` — i.e. hairlines BETWEEN rows, none above the first. | `import { RowGroup } from "@working-theory/ui/blocks"` |
 | `SchedulerEmbed` | A declarative third-party booking iframe. Renders a full-width, border-0, lazy-loaded <iframe> at `src` with a graceful loading skeleton (shown until the iframe's own `load` event fires) and a timeout-gated plain-link fallback beneath it — for environments that block third-party frames (ad blockers, a strict CSP `frame-src`) where the iframe may load blank or never load at all. | `import { SchedulerEmbed } from "@working-theory/ui/blocks"` · `packages/ui/src/blocks/SchedulerEmbed.tsx` |
+| `ScoreBar` | One labelled score bar on a scored magnet's results page: a label (the overall score's, or a dimension's name), the points out of the most a respondent could score, the Level name that share falls in, and one bar filled to the evaluator's own `pct` (`evaluateWaitlistScoring` returns `{ points, max, pct, level }` for the total and per dimension). | `import { ScoreBar } from "@working-theory/ui/blocks"` |
 | `SectionActionRow` | The bottom-anchored, centered action row a section places BENEATH its own content, at the 44×44px target-size floor. It is the block form of the placement established for `stair-steps`: a bounded 1-2 action list rendered after the section body rather than inside the section header. | `import { SectionActionRow } from "@working-theory/ui/blocks"` |
 | `SectionHeader` | Alignment-parameterized section header (eyebrow/subtitle/description/supportLink). The same component serves two ranks (headingLevel="section" \| "subsection") and three alignments (align="start" \| "center" \| "end"). It knows nothing about columns/splits/carousels — it is width-flexible and fills whatever container the section places it in. | `import { SectionHeader } from "@working-theory/ui/blocks"` |
 | `ShareBar` | The reader-facing counterpart to DocsActionBar. Both surfaces share the same SplitButton *affordance + slot* (outline variant, right-justified on the post title row) but fill it with different actions: DocsActionBar carries the AI-ingestion set (Copy page + Open in …), ShareBar carries the social-share set (X · LinkedIn · Bluesky · Copy link). One primitive, two configs. | `import { ShareBar } from "@working-theory/ui/blocks"` |

package/dist/body-heading.d.ts

@@ -41,6 +41,19 @@ export interface BodyHeadingPlan {
 }
 /** What `migrateBodyHeadings` would write, and the heading-less pages it cannot. Never throws for a page. */
 export declare function planBodyHeadings(contentDir: string, rule: MdxBodyRule): BodyHeadingPlan;
+export interface MdxBodyPage {
+    path: string;
+    /** The file's text. */
+    raw: string;
+    /** Offset of the body in `raw`; 0 for a page with no frontmatter. */
+    bodyStart: number;
+}
+/**
+ * Every page under `contentDir` that renders as mdx-body (#10773 D6): the
+ * `rulePages` walk, less an `unless-sections` page whose `sections` is
+ * non-empty or unreadable. An unreadable file is skipped. Sorted by path.
+ */
+export declare function mdxBodyPages(contentDir: string, rule: MdxBodyRule): MdxBodyPage[];
 /** Every mdx-body page whose body does not have exactly one `# ` heading. */
 export declare function headingViolations(contentDir: string, rule: MdxBodyRule): Array<{
     path: string;

package/dist/body-heading.js

@@ -14,7 +14,9 @@
  * - how many `# ` headings a body has (`countBodyHeadings`);
  * - the codemod that gives a page with none `# <title>` and its description
  *   paragraph (`addBodyHeading`, `planBodyHeadings`, `migrateBodyHeadings`).
- *   A page with one or more headings is never written.
+ *   A page with one or more headings is never written;
+ * - the mdx-body pages of a content tree, with their bodies (`mdxBodyPages`),
+ *   which the bare-brace pass and check read (#10773).
  *
  * Frontmatter is read with a dependency-free subset of YAML for the three
  * keys it needs — `create-ailk` ships exactly one runtime dependency (`tar`),
@@ -358,9 +360,13 @@ export function planBodyHeadings(contentDir, rule) {
     }
     return plan;
 }
-/** Every mdx-body page whose body does not have exactly one `# ` heading. */
-export function headingViolations(contentDir, rule) {
-    const violations = [];
+/**
+ * Every page under `contentDir` that renders as mdx-body (#10773 D6): the
+ * `rulePages` walk, less an `unless-sections` page whose `sections` is
+ * non-empty or unreadable. An unreadable file is skipped. Sorted by path.
+ */
+export function mdxBodyPages(contentDir, rule) {
+    const pages = [];
     for (const { path, type } of rulePages(contentDir, rule)) {
         let raw;
         try {
@@ -379,7 +385,15 @@ export function headingViolations(contentDir, rule) {
                 continue;
             }
         }
-        const count = countBodyHeadings(split === undefined ? raw : raw.slice(split.bodyStart));
+        pages.push({ path, raw, bodyStart: split?.bodyStart ?? 0 });
+    }
+    return pages;
+}
+/** Every mdx-body page whose body does not have exactly one `# ` heading. */
+export function headingViolations(contentDir, rule) {
+    const violations = [];
+    for (const { path, raw, bodyStart } of mdxBodyPages(contentDir, rule)) {
+        const count = countBodyHeadings(raw.slice(bodyStart));
         if (count !== 1)
             violations.push({ path, count });
     }

package/dist/cutover.d.ts

@@ -1,6 +1,7 @@
 import { type WordsCodec, type WorkspaceRow } from "./inventory.js";
 import { type LanguageImportResult } from "./language-import.js";
 import { type ImportMdxOutcome, type ImportMdxResult, type MdxAdapterModule } from "./lib/import-mdx.js";
+import { type ChromiumLike } from "./lib/render-comparison.js";
 export declare const CUTOVER_STEPS: readonly ["import", "publish", "inventory", "comparison", "set-env", "deploy", "verify", "remove-files"];
 export type CutoverStep = (typeof CUTOVER_STEPS)[number];
 export declare const ENV_TARGETS: readonly ["preview", "production"];
@@ -46,6 +47,8 @@ export interface CutoverDeps {
         sweep: string[];
         screenshots: boolean;
         dir: string;
+        /** Step 1's kind-pull top-ups, left out of their page's after side (#10753). */
+        topUps: LanguageImportResult["topUps"];
     }) => Promise<{
         pass: boolean;
         summary: string;
@@ -74,6 +77,8 @@ export interface CutoverOptions {
     codec?: WordsCodec;
     /** Injectable for tests: names the run's directory. */
     now?: () => Date;
+    /** Injectable for tests; defaults to the site's installed Playwright Chromium. */
+    chromium?: ChromiumLike;
     deps?: Partial<CutoverDeps>;
     onLine?: (line: string) => void;
 }
@@ -105,5 +110,5 @@ export interface CutoverArgs {
     workspaceId: string | undefined;
     help: boolean;
 }
-export declare const CUTOVER_HELP = "create-ailk cutover \u2014 move a site from its page files to its database, one checked step at a time.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk cutover [<dir>] --before <origin> --after <origin> [--apply] [--env-target preview|production] [--docs-path <path>] [--pixel-tolerance <ratio>] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                      The site. Defaults to the current dir.\n\nOptions:\n  --before <origin>          The site served from its files.\n  --after <origin>           A deployment reading the database (a preview\n                             with CONTENT_ADAPTER=database).\n  --apply                    Run the steps. Without it the command plans\n                             them: it sends only reads, spawns nothing and\n                             writes nothing.\n  --env-target <target>      preview (the default) or production \u2014 where\n                             step 5 sets CONTENT_ADAPTER and step 6 deploys.\n  --docs-path <path>         Where the site serves its docs. Default /docs.\n  --pixel-tolerance <ratio>  The share of a screenshot's pixels that may\n                             differ. Default 0.\n  --api-url <origin>         The API origin that holds the workspace \u2014 on a\n                             spoke, its hub's. Else AILK_API_URL.\n  --workspace <wksp_id>      The workspace. Else AILK_WORKSPACE_ID.\n  -h, --help                 Show this help.\n\nSteps, in this order; the first that fails stops the run:\n  1 import        create-ailk migrate-content <dir> --apply; stops, before\n                  writing, when the import would change a page's render\n  2 publish       every imported page is published (publish in Admin)\n  3 inventory     create-ailk inventory <dir> --origin <before>; audit passes\n  4 comparison    text, JSON-LD and screenshots per frozen page, before and\n                  after, at 1440 and 390 wide; every frozen URL answers 200\n  5 set env       vercel env add CONTENT_ADAPTER <target> = database (apps/web)\n  6 deploy        vercel deploy [--prod] (apps/web)\n  7 verify        text and JSON-LD per frozen page on the deployment; 200s\n  8 remove files  git rm --quiet -- <the imported files> (staged, not committed)\n\nEach run writes .ailk-cutover/runs/<UTC time>/run.json and the comparison's\nevidence beside it (gitignored). The comparison needs Playwright's Chromium:\npnpm add -D @playwright/test && pnpm exec playwright install chromium. When VERCEL_AUTOMATION_BYPASS_SECRET is set,\nrequests to --after and the deployment carry it. The agent key needs the\ncontent-edit grant; on a spoke, AILK_SPOKE_KEY is needed too. The rollback\nis create-ailk export-content (docs/internal/runbooks/site-cutover.md).\nExit 0 when every step passed (a dry run: when the import plan has no\nfailed page), 1 when one failed, 2 on a refusal.\n";
+export declare const CUTOVER_HELP = "create-ailk cutover \u2014 move a site from its page files to its database, one checked step at a time.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk cutover [<dir>] --before <origin> --after <origin> [--apply] [--env-target preview|production] [--docs-path <path>] [--pixel-tolerance <ratio>] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                      The site. Defaults to the current dir.\n\nOptions:\n  --before <origin>          The site served from its files.\n  --after <origin>           A deployment reading the database (a preview\n                             with CONTENT_ADAPTER=database).\n  --apply                    Run the steps. Without it the command plans\n                             them: it sends only reads, spawns nothing and\n                             writes nothing.\n  --env-target <target>      preview (the default) or production \u2014 where\n                             step 5 sets CONTENT_ADAPTER and step 6 deploys.\n  --docs-path <path>         Where the site serves its docs. Default /docs.\n  --pixel-tolerance <ratio>  The share of a screenshot's pixels that may\n                             differ. Default 0.\n  --api-url <origin>         The API origin that holds the workspace \u2014 on a\n                             spoke, its hub's. Else AILK_API_URL.\n  --workspace <wksp_id>      The workspace. Else AILK_WORKSPACE_ID.\n  -h, --help                 Show this help.\n\nSteps, in this order; the first that fails stops the run:\n  1 import        create-ailk migrate-content <dir> --apply; stops, before\n                  writing, when the import would change a page's render\n  2 publish       every imported page is published (publish in Admin)\n  3 inventory     create-ailk inventory <dir> --origin <before>; audit passes\n  4 comparison    text, JSON-LD and screenshots per frozen page, before and\n                  after, at 1440 and 390 wide; every frozen URL answers 200;\n                  /faq's and /glossary's kind-pull top-ups from step 1 are\n                  left out of the compare\n  5 set env       vercel env add CONTENT_ADAPTER <target> = database (apps/web)\n  6 deploy        vercel deploy [--prod] (apps/web)\n  7 verify        text and JSON-LD per frozen page on the deployment; 200s\n  8 remove files  git rm --quiet -- <the imported files> (staged, not committed)\n\nEach run writes .ailk-cutover/runs/<UTC time>/run.json and the comparison's\nevidence beside it (gitignored). The comparison needs Playwright's Chromium:\npnpm add -D @playwright/test && pnpm exec playwright install chromium. When VERCEL_AUTOMATION_BYPASS_SECRET is set,\nrequests to --after and the deployment carry it. The agent key needs the\ncontent-edit grant; on a spoke, AILK_SPOKE_KEY is needed too. The rollback\nis create-ailk export-content (docs/internal/runbooks/site-cutover.md).\nExit 0 when every step passed (a dry run: when the import plan has no\nfailed page), 1 when one failed, 2 on a refusal.\n";
 export declare function parseCutoverArgs(argv: string[]): CutoverArgs;

package/dist/cutover.js

@@ -95,6 +95,13 @@ const vercelEnvArgs = (target) => ({
     ls: ["env", "ls", target],
 });
 const deployArgs = (target) => (target === "production" ? ["deploy", "--prod"] : ["deploy"]);
+/** `/faq: faq/a, faq/b; /glossary: term/c`, pages and keys in `topUps` order. */
+function topUpsLine(topUps) {
+    const byPage = new Map();
+    for (const t of topUps)
+        byPage.set(t.page, [...(byPage.get(t.page) ?? []), `${t.kind}/${t.slug}`]);
+    return [...byPage].map(([page, keys]) => `${page}: ${keys.join(", ")}`).join("; ");
+}
 // ── The command (D7) ────────────────────────────────────────────────────────
 export async function cutover(opts) {
     const targetDir = resolve(opts.targetDir);
@@ -165,7 +172,7 @@ export async function cutover(opts) {
             };
         },
         compare: async (o) => {
-            const chromium = loadChromium([targetDir, process.cwd()]);
+            const chromium = opts.chromium ?? loadChromium([targetDir, process.cwd()]);
             if (chromium === undefined) {
                 return { pass: false, summary: `no Playwright Chromium found — ${PLAYWRIGHT_INSTALL_HINT}` };
             }
@@ -181,12 +188,15 @@ export async function cutover(opts) {
                 dir: o.dir,
                 fetch,
                 onLine: (line) => onLine(`  ${line}`),
+                exclude: o.topUps.reduce((by, { page, ...item }) => ({ ...by, [page]: [...(by[page] ?? []), item] }), {}),
             });
             const differing = report.pages.filter((p) => !p.pass).map((p) => p.path);
             const not200 = report.sweep.results.filter((r) => r.status !== 200).length;
+            const excludedOn = new Set(report.pages.filter((p) => p.excluded !== undefined).map((p) => p.path));
+            const excluded = o.topUps.filter((t) => excludedOn.has(t.page));
             return {
                 pass: report.pass,
-                summary: `${report.pages.length - differing.length}/${report.pages.length} page(s) the same; sweep: ${not200} of ${report.sweep.results.length} not 200${differing.length > 0 ? `; differs: ${differing.join(", ")}` : ""}`,
+                summary: `${report.pages.length - differing.length}/${report.pages.length} page(s) the same; sweep: ${not200} of ${report.sweep.results.length} not 200${differing.length > 0 ? `; differs: ${differing.join(", ")}` : ""}${excluded.length > 0 ? `; excluded kind-pull top-ups: ${topUpsLine(excluded)}` : ""}`,
             };
         },
         run: spawnRunner,
@@ -215,6 +225,7 @@ export async function cutover(opts) {
         : `Planning the cutover of ${opts.targetDir}: ${before} (files) → ${after} (database), env target ${target}. Nothing is written or spawned without --apply.`);
     // State the steps hand on.
     let outcomes = [];
+    let topUps = [];
     let deployed;
     const STEP = {
         import: async () => {
@@ -234,6 +245,7 @@ export async function cutover(opts) {
             }
             const { result, language } = await deps.migrate({ apply });
             outcomes = result.pages;
+            topUps = language?.topUps ?? [];
             const { created, updated, unchanged, skipped, failed } = result.counts;
             const counts = `created ${created} · updated ${updated} · unchanged ${unchanged} · skipped ${skipped} · failed ${failed}`;
             const changed = changes(language);
@@ -286,13 +298,16 @@ export async function cutover(opts) {
                 return {
                     ok: true,
                     command,
-                    evidence: [frozen === undefined ? "every URL the inventory freezes" : `${frozen.pages.length} page(s), ${frozen.sweep.length} URL(s) swept`],
+                    evidence: [
+                        frozen === undefined ? "every URL the inventory freezes" : `${frozen.pages.length} page(s), ${frozen.sweep.length} URL(s) swept`,
+                        ...(topUps.length > 0 ? [`would exclude kind-pull top-ups: ${topUpsLine(topUps)}`] : []),
+                    ],
                 };
             }
             if (frozen === undefined)
                 return { ok: false, command, evidence: ["no frozen inventory"] };
             const dir = join(runDir, "comparison");
-            const { pass, summary } = await deps.compare({ after, ...frozen, screenshots: true, dir });
+            const { pass, summary } = await deps.compare({ after, ...frozen, screenshots: true, dir, topUps });
             return { ok: pass, command, evidence: [summary, `${dir}/comparison.md`] };
         },
         "set-env": async () => {
@@ -335,7 +350,7 @@ export async function cutover(opts) {
             if (frozen === undefined)
                 return { ok: false, command, evidence: ["no frozen inventory"] };
             const dir = join(runDir, "verify");
-            const { pass, summary } = await deps.compare({ after: deployed, ...frozen, screenshots: false, dir });
+            const { pass, summary } = await deps.compare({ after: deployed, ...frozen, screenshots: false, dir, topUps });
             return { ok: pass, command, evidence: [summary, `${dir}/comparison.md`] };
         },
         "remove-files": async () => {
@@ -428,7 +443,9 @@ Steps, in this order; the first that fails stops the run:
   2 publish       every imported page is published (publish in Admin)
   3 inventory     create-ailk inventory <dir> --origin <before>; audit passes
   4 comparison    text, JSON-LD and screenshots per frozen page, before and
-                  after, at 1440 and 390 wide; every frozen URL answers 200
+                  after, at 1440 and 390 wide; every frozen URL answers 200;
+                  /faq's and /glossary's kind-pull top-ups from step 1 are
+                  left out of the compare
   5 set env       vercel env add CONTENT_ADAPTER <target> = database (apps/web)
   6 deploy        vercel deploy [--prod] (apps/web)
   7 verify        text and JSON-LD per frozen page on the deployment; 200s

package/dist/export-content.d.ts

@@ -6,8 +6,11 @@ export declare class ExportContentRefusedError extends Error {
     constructor(message: string);
 }
 export declare const SPOKE_HINT = "the site's read does not serve this workspace's published version \u2014 is the spoke at --store database?";
-/** The site-relative file a stored page is written to, and whether it is editorial. */
-export declare function fileFor(targetDir: string, type: string, slug: string, locale: string): {
+/**
+ * The site-relative file a stored page is written to, and whether it is
+ * editorial. A blog post's `parent` is its series' directory (#10811 D1).
+ */
+export declare function fileFor(targetDir: string, type: string, slug: string, locale: string, parent?: string): {
     path: string;
     editorial: boolean;
 };
@@ -51,5 +54,5 @@ export interface ExportContentArgs {
     workspaceId: string | undefined;
     help: boolean;
 }
-export declare const EXPORT_CONTENT_HELP = "create-ailk export-content \u2014 write every published page back to its content file.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk export-content [<dir>] [--dry-run] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                    The site. Defaults to the current dir.\n\nOptions:\n  --dry-run                Print what would be written, and write nothing.\n  --api-url <origin>       The API origin that holds the workspace \u2014 on a\n                           spoke, its hub's. Else AILK_API_URL.\n  --workspace <wksp_id>    The workspace. Else AILK_WORKSPACE_ID.\n  -h, --help               Show this help.\n\nThe rollback for a cutover: every page the workspace list reports published\nin the default locale is written to the file migrate-content reads it from\n\u2014 content/en/<Type>/<slug>.mdx (or the legacy content/<Type>/<slug>.mdx that\nexists), apps/web/content/en/blog/<slug>.mdx for a post and the same under\ndocs for a docs page \u2014 with its words moved back into its sections, so a\nre-run of migrate-content reports every page unchanged. Published edits are\nkept. A page with a draft ahead of its published version fails by name:\npublish or revert it in Admin, then re-run. The site's own API read must\nserve the workspace's published version (on a spoke, the hub's row at\n--store database). Each page prints created, written, unchanged or failed.\nThe agent key needs the content-edit grant; on a spoke, AILK_SPOKE_KEY is\nneeded too. Exit 0 when no page failed, 1 when any did, 2 on a refusal.\n";
+export declare const EXPORT_CONTENT_HELP = "create-ailk export-content \u2014 write every published page back to its content file.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk export-content [<dir>] [--dry-run] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                    The site. Defaults to the current dir.\n\nOptions:\n  --dry-run                Print what would be written, and write nothing.\n  --api-url <origin>       The API origin that holds the workspace \u2014 on a\n                           spoke, its hub's. Else AILK_API_URL.\n  --workspace <wksp_id>    The workspace. Else AILK_WORKSPACE_ID.\n  -h, --help               Show this help.\n\nThe rollback for a cutover: every page the workspace list reports published\nin the default locale is written to the file migrate-content reads it from\n\u2014 content/en/<Type>/<slug>.mdx (or the legacy content/<Type>/<slug>.mdx that\nexists), apps/web/content/en/blog/<slug>.mdx for a post,\napps/web/content/en/blog/<series>/<slug>.mdx for a post in a series and the\nsame under docs for a docs page; a post or doc goes to whichever of\n<slug>.mdx or <slug>/index.mdx is on disk, <slug>.mdx when neither is \u2014 with\nits words moved back into its sections, so a re-run of migrate-content\nreports every page unchanged. Published edits are\nkept. A page with a draft ahead of its published version fails by name:\npublish or revert it in Admin, then re-run. The site's own API read must\nserve the workspace's published version (on a spoke, the hub's row at\n--store database). Each page prints created, written, unchanged or failed.\nThe agent key needs the content-edit grant; on a spoke, AILK_SPOKE_KEY is\nneeded too. Exit 0 when no page failed, 1 when any did, 2 on a refusal.\n";
 export declare function parseExportContentArgs(argv: string[]): ExportContentArgs;

package/dist/export-content.js

@@ -24,7 +24,7 @@
  *
  * Pure module: no `import.meta.url`, so jest imports it directly.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { listWorkspacePages, loadSiteWordsCodec, readDraftPage, readPublishedPage, readSiteLocales, resolveWorkspaceAccess, } from "./inventory.js";
@@ -52,21 +52,32 @@ const EDITORIAL_DIRS = {
 const EDITORIAL_RENAMES = { publishedAt: "date", updatedAt: "updated" };
 /** Keys an editorial file does not carry: its path decides both. */
 const EDITORIAL_DROPPED = new Set(["type", "slug"]);
+/**
+ * Never written from `siteFields` (#10806 D6): a mapped fumadocs key, an
+ * address key, the strip marker, or a prototype name.
+ */
+const NOT_SITE_FIELDS = new Set(["date", "updated", "type", "slug", "oss", "siteFields", "__proto__"]);
 const INDEX_SLUG = "index";
 /** The store's address shapes, restated (create-ailk has no runtime dep): a path built from them stays in the site. */
 const TYPE_SHAPE = /^[A-Z][A-Za-z]*$/;
 const SLUG_SHAPE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 const LOCALE_SHAPE = /^[a-z]{2}(-[A-Z]{2})?$/;
+/** A blog series' shape (`PARENT` in `lib/import-mdx.ts`), restated: a directory built from it stays in the blog. */
+const SERIES_SHAPE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** A pinned item's read times out as the kit's other reads do (`inventory.ts`). */
 const ITEM_READ_TIMEOUT_MS = 15_000;
 export const SPOKE_HINT = "the site's read does not serve this workspace's published version — is the spoke at --store database?";
 // ── File addressing (D6) ────────────────────────────────────────────────────
-/** The site-relative file a stored page is written to, and whether it is editorial. */
-export function fileFor(targetDir, type, slug, locale) {
+/**
+ * The site-relative file a stored page is written to, and whether it is
+ * editorial. A blog post's `parent` is its series' directory (#10811 D1).
+ */
+export function fileFor(targetDir, type, slug, locale, parent) {
     const exists = (path) => existsSync(join(targetDir, path));
     const editorial = EDITORIAL_DIRS[type];
     if (editorial !== undefined && editorial.index === (slug === INDEX_SLUG)) {
-        const base = `apps/web/content/${locale}/${editorial.dir}`;
+        const series = type === "BlogPosting" && parent !== undefined ? `/${parent}` : "";
+        const base = `apps/web/content/${locale}/${editorial.dir}${series}`;
         if (editorial.index)
             return { path: `${base}/index.mdx`, editorial: true };
         // The importer reads `<slug>.mdx` first and `<slug>/index.mdx` (#10701);
@@ -88,11 +99,20 @@ export function recombine(content, sections, codec, editorial, pinned) {
     const { body: rawBody, ...rest } = content;
     let body = typeof rawBody === "string" ? rawBody : "";
     const frontmatter = {};
-    for (const [key, value] of Object.entries(rest)) {
+    const { siteFields, ...stored } = rest;
+    for (const [key, value] of Object.entries(editorial ? stored : rest)) {
         if (editorial && EDITORIAL_DROPPED.has(key))
             continue;
         frontmatter[editorial ? (EDITORIAL_RENAMES[key] ?? key) : key] = value;
     }
+    // #10806 D6 — an editorial page's site fields are its file's own keys, after
+    // the mapped ones; a mapped key always wins.
+    if (editorial && siteFields !== null && typeof siteFields === "object" && !Array.isArray(siteFields)) {
+        for (const [key, value] of Object.entries(siteFields)) {
+            if (!Object.hasOwn(frontmatter, key) && !NOT_SITE_FIELDS.has(key))
+                frontmatter[key] = value;
+        }
+    }
     if (sections !== undefined && sections.length > 0) {
         const applied = codec.applyWords(body, sections);
         if (applied.issues.length > 0) {
@@ -170,6 +190,15 @@ export async function exportContent(opts) {
         if (draft.version !== row.publishedVersionId) {
             return failed("the draft read is not the published version; re-run");
         }
+        // #10811 D4 — a blog post's series becomes a directory, so it must be one
+        // the importer reads back; the API's value is not printed.
+        const stored = type === "BlogPosting" ? draft.content["parent"] : undefined;
+        const parent = typeof stored === "string" && SERIES_SHAPE.test(stored) && stored !== slug && stored !== "category"
+            ? stored
+            : undefined;
+        if (stored !== undefined && parent === undefined) {
+            return failed("its series is not one a file can be written under (lowercase words joined by single hyphens, not its own slug, not category)");
+        }
         const published = await readPublishedPage(access, fetch, type, slug, locale);
         if (!published.found || published.publishedVersionId !== row.publishedVersionId) {
             return failed(SPOKE_HINT);
@@ -177,8 +206,18 @@ export async function exportContent(opts) {
         const pinned = await pinnedItems(published.sections ?? [], locale);
         if (typeof pinned === "string")
             return failed(pinned);
-        const { path, editorial } = fileFor(targetDir, type, slug, locale);
-        const file = recombine(draft.content, published.sections, codec, editorial, pinned);
+        const { path, editorial } = fileFor(targetDir, type, slug, locale, parent);
+        let content = draft.content;
+        if (parent !== undefined && editorial) {
+            const holder = addressHolder(slug, parent);
+            if (holder !== undefined) {
+                return failed(`${holder} would hold this post's address on import; remove it, then re-run`, path);
+            }
+            // #10811 D3 — the path carries the series, as it carries type and slug.
+            const { parent: _series, ...unparented } = content;
+            content = unparented;
+        }
+        const file = recombine(content, published.sections, codec, editorial, pinned);
         if ("reason" in file)
             return failed(file.reason, path);
         const absolute = join(targetDir, path);
@@ -190,6 +229,33 @@ export async function exportContent(opts) {
         }
         return { type, slug, file: path, result };
     }
+    /**
+     * The first other file, in path order, that the editorial walk reads as
+     * this series post's `BlogPosting/<slug>` (#10811 D5): the top-level forms,
+     * or the same post under another series. The walk skips `category`, `_`
+     * entries and symbolic links, and refuses a series not in its shape or
+     * named after its own post, so none of those holds the address.
+     */
+    function addressHolder(slug, parent) {
+        const blog = `apps/web/content/${locale}/blog`;
+        const series = existsSync(join(targetDir, blog))
+            ? readdirSync(join(targetDir, blog), { withFileTypes: true })
+                .filter((d) => d.isDirectory() && SERIES_SHAPE.test(d.name) && ![parent, slug, "category"].includes(d.name))
+                .map((d) => `${blog}/${d.name}`)
+            : [];
+        // Every directory below `blog` a real directory and the file a real file.
+        const walked = (path) => {
+            const parts = path.slice(blog.length + 1).split("/");
+            return parts.every((_, i) => {
+                const stat = lstatSync(join(targetDir, blog, ...parts.slice(0, i + 1)), { throwIfNoEntry: false });
+                return i === parts.length - 1 ? stat?.isFile() === true : stat?.isDirectory() === true;
+            });
+        };
+        return [blog, ...series]
+            .flatMap((dir) => [`${dir}/${slug}.mdx`, `${dir}/${slug}/index.mdx`])
+            .filter(walked)
+            .sort()[0];
+    }
     /**
      * The Live words of every item the page's faq / glossary-index sections pin
      * (#10735 D9), by kind and slug — `undefined` when none pins — or why the
@@ -261,9 +327,12 @@ Options:
 The rollback for a cutover: every page the workspace list reports published
 in the default locale is written to the file migrate-content reads it from
 — content/en/<Type>/<slug>.mdx (or the legacy content/<Type>/<slug>.mdx that
-exists), apps/web/content/en/blog/<slug>.mdx for a post and the same under
-docs for a docs page — with its words moved back into its sections, so a
-re-run of migrate-content reports every page unchanged. Published edits are
+exists), apps/web/content/en/blog/<slug>.mdx for a post,
+apps/web/content/en/blog/<series>/<slug>.mdx for a post in a series and the
+same under docs for a docs page; a post or doc goes to whichever of
+<slug>.mdx or <slug>/index.mdx is on disk, <slug>.mdx when neither is — with
+its words moved back into its sections, so a re-run of migrate-content
+reports every page unchanged. Published edits are
 kept. A page with a draft ahead of its published version fails by name:
 publish or revert it in Admin, then re-run. The site's own API read must
 serve the workspace's published version (on a spoke, the hub's row at

package/dist/language-import.d.ts

@@ -8,7 +8,9 @@
  * `withLanguage` wraps the site's adapter module: the wrapped
  * `getPageSource` reads the page, makes sure every item on it exists (created
  * Live when this run creates it), and returns the frontmatter with those
- * sections rewritten as `faq:<slug>` / `term:<slug>` pins. The importer then
+ * sections rewritten as `faq:<slug>` / `term:<slug>` pins. An FAQ item is one
+ * question AND its answer (#10778), so a page that answers another page's
+ * question otherwise gets its own item, reported as a collision. The importer then
  * writes the page as it writes any other, so the pass covers exactly the
  * pages the importer reads, and every item a page pins exists before its
  * layout is written. An item write that fails throws, which fails that page.
@@ -59,11 +61,15 @@ export interface LanguageImportResult {
         page: string;
         from: string;
     }[];
-    /** An imported item the home page's kind pull now also lists (#10734 D3); not a render change. */
+    /**
+     * An imported item the home page's kind pull now also lists (#10734 D3); not
+     * a render change. `name` is the question or term the read renders it with.
+     */
     topUps: {
         kind: LanguageItemKind;
         slug: string;
         page: string;
+        name: string;
     }[];
     /** An FAQ whose source carried a `kicker`, which a Language FAQ has no field for (#10750). */
     droppedKickers: {
@@ -75,6 +81,13 @@ export interface LanguageImportResult {
         slug: string;
         next: string;
     }[];
+    /** A page's FAQ whose question another page answers otherwise, so it got its own item (#10778). */
+    collisions: {
+        slug: string;
+        page: string;
+        from: string;
+        next: string;
+    }[];
 }
 /** The pass, and what it decided once the importer is done. */
 export interface LanguagePass {
@@ -109,6 +122,6 @@ export declare function languageOffLine(status: number): string;
 export declare function renderChangeLine(c: LanguageImportResult["renderChanges"][number]): string;
 /** The counts line, in the dry run's verbs or `--apply`'s. */
 export declare function languageCountsLine(result: LanguageImportResult, apply: boolean): string;
-/** Every line D7 prints, in order: items, counts, render changes, top-ups, dropped kickers, displacements. */
+/** Every line D7 prints, in order: items, counts, render changes, collisions, top-ups, dropped kickers, displacements. */
 export declare function languageLines(result: LanguageImportResult, apply: boolean): string[];
 export {};