create-ailk 0.31.0 → 0.32.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,10 +656,15 @@ 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` →
+`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`); 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

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/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 {};

package/dist/language-import.js

@@ -88,7 +88,7 @@ function entriesOf(section) {
             if (!str(raw["question"]) || !str(raw["answer"]))
                 return undefined;
             entries.push({
-                key: raw["question"],
+                key: JSON.stringify([raw["question"], raw["answer"]]),
                 words: { question: raw["question"], answer: raw["answer"] },
                 kicker: raw["kicker"] !== undefined,
             });
@@ -113,12 +113,13 @@ export function withLanguage(adapters, options) {
     let state = "unprobed";
     let offStatus;
     const items = new Map();
-    /** In-run FAQ slug claims, so two questions never share a slug (D2); a term's slug is its key. */
+    /** In-run FAQ slug claims, so two items never share a slug (D2, #10778 D2); a term's slug is its key. */
     const claimed = new Map();
     const occurrences = [];
     const homes = [];
     const kickers = [];
     const displaced = [];
+    const collisions = [];
     async function call(method, url, body) {
         for (let retry = 0;; retry++) {
             let response;
@@ -208,9 +209,11 @@ export function withLanguage(adapters, options) {
                 throw new Error(`language: ${kind}/${known.slug}: ${known.failed}`);
             if (home && !known.winner.home) {
                 // D3 — the home page outranks a page read before it; an item this run
-                // created takes its words, and a found one is never written (D4).
+                // created takes its words unless they are already its own (#10778 D4),
+                // and a found one is never written (D4).
+                const rewords = known.created && options.apply && !same(known.winner.words, entry.words);
                 known.winner = { page, words: entry.words, home: true };
-                if (known.created && options.apply)
+                if (rewords)
                     await write(known, entry.words, known.version ?? null);
             }
             return known;
@@ -221,15 +224,22 @@ export function withLanguage(adapters, options) {
             stored = await read(kind, slug);
         }
         else {
-            const first = faqSlug(entry.key);
+            const question = entry.words["question"];
+            const first = faqSlug(question);
             let skipped;
+            let collided;
             for (let n = 1;; n++) {
                 const candidate = n === 1 ? first : `${first}-${n}`;
+                // Claimed in this run by another pair: the same question answered otherwise
+                // is a collision (#10778 D2), another question that slugs alike is not.
                 const holder = claimed.get(candidate);
-                if (holder !== undefined && holder !== entry.key)
+                if (holder !== undefined) {
+                    if (holder.winner.words["question"] === question)
+                        collided ??= { slug: candidate, from: holder.winner.page };
                     continue;
+                }
                 stored = await read(kind, candidate);
-                if (stored !== null && stored.words["question"] !== entry.key) {
+                if (stored !== null && stored.words["question"] !== question) {
                     skipped ??= candidate;
                     continue;
                 }
@@ -238,9 +248,9 @@ export function withLanguage(adapters, options) {
             }
             if (skipped !== undefined)
                 displaced.push({ slug: skipped, next: slug });
+            if (collided !== undefined)
+                collisions.push({ ...collided, page, next: slug });
         }
-        if (kind === "faq")
-            claimed.set(slug, entry.key);
         const item = {
             kind,
             slug,
@@ -249,6 +259,8 @@ export function withLanguage(adapters, options) {
             ...(stored !== null && { stored }),
         };
         items.set(mapKey, item);
+        if (kind === "faq")
+            claimed.set(slug, item);
         if (stored === null)
             await write(item, entry.words, null);
         return item;
@@ -355,7 +367,9 @@ export function withLanguage(adapters, options) {
                 const key = `${PREFIX[item.kind]}${item.slug}`;
                 const live = item.created || item.stored.live;
                 if (item.kind === home.kind && item.failed === undefined && live && !home.shown.has(key)) {
-                    topUps.push({ kind: item.kind, slug: item.slug, page: `/${home.slug}` });
+                    const shown = item.created ? item.winner.words : (item.stored.published ?? {});
+                    const name = shown[item.kind === "faq" ? "question" : "term"] ?? "";
+                    topUps.push({ kind: item.kind, slug: item.slug, page: `/${home.slug}`, name });
                 }
             }
         }
@@ -371,6 +385,7 @@ export function withLanguage(adapters, options) {
             topUps,
             droppedKickers: kickers,
             displaced,
+            collisions,
         };
     }
     return {
@@ -421,13 +436,14 @@ export function languageCountsLine(result, apply) {
     const { created, unchanged, kept, failed } = result.counts;
     return `language: ${apply ? "created" : "create"} ${created} · unchanged ${unchanged} · kept ${kept} · failed ${failed}`;
 }
-/** 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 function languageLines(result, apply) {
     const verb = (r) => (!apply && r === "created" ? "create" : r);
     return [
         ...result.items.map((i) => `language: ${i.kind}/${i.slug}: ${verb(i.result)}${i.reason === undefined ? "" : ` — ${i.reason}`}`),
         languageCountsLine(result, apply),
         ...result.renderChanges.map(renderChangeLine),
+        ...result.collisions.map((c) => `language: faq/${c.slug} on ${c.page}: not merged — ${c.from} answers the same question otherwise; ${c.page} pins faq/${c.next}`),
         ...result.topUps.map((t) => `language: ${t.kind}/${t.slug}: now also on ${t.page}`),
         ...result.droppedKickers.map((k) => `language: faq/${k.slug}: kicker dropped`),
         ...result.displaced.map((d) => `language: faq/${d.slug}: the workspace holds a different question here; the file's is ${d.next}`),

package/dist/lib/import-mdx.js

@@ -61,6 +61,8 @@ const FRONTMATTER_PACKAGE = "gray-matter";
 const LOCALE = /^[a-z]{2}(-[A-Z]{2})?$/;
 /** `SLUG_PATTERN` in the adapter's `errors.ts`, restated: no runtime dep. */
 const SLUG = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+/** A `parent`'s shape (`ServiceFieldsSchema` in the adapter's `types.ts`), restated: no runtime dep. */
+const PARENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** Each editorial directory's page type and index type (`runtime-source.ts`). */
 const EDITORIAL_TYPES = {
     blog: { page: "BlogPosting", index: "BlogList" },
@@ -166,10 +168,13 @@ function mdxFiles(root, prefix = []) {
             : [];
     });
 }
+/** Type, then slug, then a page with no `parent` before a series leaf (#10775 D4). */
 function byTypeThenSlug(a, b) {
     if (a.type !== b.type)
         return a.type < b.type ? -1 : 1;
-    return a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0;
+    if (a.slug !== b.slug)
+        return a.slug < b.slug ? -1 : 1;
+    return Number(a.parent !== undefined) - Number(b.parent !== undefined);
 }
 function byPath(a, b) {
     return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
@@ -239,9 +244,11 @@ function plan(contentRoot, types, defaultLocale) {
     };
 }
 /**
- * The editorial walk (#10701 D2–D3): `L/{blog,docs}/<slug>.mdx` and
+ * The editorial walk (#10701 D2–D3, #10775 D2): `L/{blog,docs}/<slug>.mdx` and
  * `<slug>/index.mdx` are posts and docs, the directory's own `index.mdx` its
- * index page; anything deeper is no page the store can address.
+ * index page, and `L/blog/<series>/<post>.mdx` or `<post>/index.mdx` a post
+ * whose `parent` is the series. Every other file is skipped with the rule it
+ * failed.
  */
 function planEditorial(editorialRoot, types, defaultLocale) {
     const pages = [];
@@ -254,7 +261,7 @@ function planEditorial(editorialRoot, types, defaultLocale) {
     // Sorted by path first, so within one directory `<slug>.mdx` comes before
     // `<slug>/index.mdx` and holds the address (`.` sorts before `/`).
     for (const { segments, link, path } of found.sort(byPath)) {
-        const [locale, dir, file, nested] = segments;
+        const [locale, dir, file, nested, leafFile] = segments;
         const kinds = dir !== undefined && Object.hasOwn(EDITORIAL_TYPES, dir)
             ? EDITORIAL_TYPES[dir]
             : undefined;
@@ -266,31 +273,52 @@ function planEditorial(editorialRoot, types, defaultLocale) {
             skip(path, `locale ${locale} is not imported (only ${defaultLocale})`);
             continue;
         }
+        if (kinds === undefined || locale !== defaultLocale) {
+            skip(path, `not a post or doc: only ${defaultLocale}/blog and ${defaultLocale}/docs are walked`);
+            continue;
+        }
         let type;
         let slug;
-        if (kinds !== undefined && locale === defaultLocale) {
-            if (segments.length === 3 && file === "index.mdx") {
-                type = kinds.index;
-                slug = INDEX_SLUG;
-            }
-            else if (segments.length === 3) {
-                type = kinds.page;
-                slug = file.slice(0, -".mdx".length);
-            }
-            else if (segments.length === 4 && nested === "index.mdx") {
-                type = kinds.page;
-                slug = file;
-            }
+        let parent;
+        if (segments.length === 3 && file === "index.mdx") {
+            type = kinds.index;
+            slug = INDEX_SLUG;
+        }
+        else if (segments.length === 3) {
+            type = kinds.page;
+            slug = file.slice(0, -".mdx".length);
+        }
+        else if (segments.length === 4 && nested === "index.mdx") {
+            type = kinds.page;
+            slug = file;
         }
-        if (type === undefined || slug === undefined) {
-            skip(path, `not a post or doc: the editorial walk reads ${defaultLocale}/{blog,docs}/<slug>.mdx and ${defaultLocale}/{blog,docs}/<slug>/index.mdx`);
+        else if (dir === "docs") {
+            skip(path, "a nested doc: a doc is docs/<slug>.mdx or docs/<slug>/index.mdx");
+            continue;
+        }
+        else if (file === "category") {
+            skip(path, "under blog/category: /blog/category/<tag> is the blog's category index, so no post is served there");
+            continue;
+        }
+        else if (segments.length === 4 ||
+            (segments.length === 5 && leafFile === "index.mdx")) {
+            type = kinds.page;
+            slug = segments.length === 4 ? nested.slice(0, -".mdx".length) : nested;
+            parent = file;
+        }
+        else {
+            skip(path, "too deep: a post is blog/<slug>.mdx, blog/<slug>/index.mdx, or one series down at blog/<series>/<post>.mdx or blog/<series>/<post>/index.mdx");
             continue;
         }
         const invalid = !SLUG.test(slug)
             ? `not a valid slug: ${slug}`
-            : !types.includes(type)
-                ? `the site's adapter has no type ${type}`
-                : undefined;
+            : parent !== undefined && !PARENT.test(parent)
+                ? `not a valid series: ${parent} (a parent is lowercase words joined by single hyphens)`
+                : parent === slug
+                    ? `a post cannot share its series' slug: ${slug}`
+                    : !types.includes(type)
+                        ? `the site's adapter has no type ${type}`
+                        : undefined;
         pages.push({
             root: "editorial",
             path,
@@ -298,6 +326,7 @@ function planEditorial(editorialRoot, types, defaultLocale) {
             slug,
             localeTree: true,
             ...(invalid !== undefined && { invalid }),
+            ...(parent !== undefined && { parent }),
         });
     }
     return { pages: pages.sort(byTypeThenSlug), skipped };
@@ -312,7 +341,8 @@ function dateString(value) {
 /**
  * An editorial file as the adapter would return a page (#10701 D4): its
  * fumadocs frontmatter mapped to the stored vocabulary, the path deciding the
- * type and slug, and the keys not sent named.
+ * type and slug — and, for a blog page, its `parent` (#10775 D3) — and the
+ * keys not sent named.
  */
 function editorialSource(page, parsed) {
     const frontmatter = {
@@ -320,8 +350,9 @@ function editorialSource(page, parsed) {
         slug: page.slug,
     };
     const dropped = [];
+    const blog = page.type === "BlogPosting" || page.type === "BlogList";
     for (const [key, value] of Object.entries(parsed.data)) {
-        const stored = Object.hasOwn(EDITORIAL_FIELDS, key)
+        const stored = Object.hasOwn(EDITORIAL_FIELDS, key) && !(blog && key === "parent")
             ? EDITORIAL_FIELDS[key]
             : undefined;
         if (stored !== undefined)
@@ -329,6 +360,8 @@ function editorialSource(page, parsed) {
         else if (!EDITORIAL_IGNORED.has(key))
             dropped.push(key);
     }
+    if (page.parent !== undefined)
+        frontmatter["parent"] = page.parent;
     return {
         source: { frontmatter, body: parsed.content },
         dropped: dropped.sort(),