create-ailk 0.31.0 → 0.32.0

package/dist/site-roster.js

@@ -19,7 +19,9 @@
  *   - `planRosterAppend` — the next `rows`, spliced into the file's text so
  *     every untouched byte stays prettier's;
  *   - `siteRosterProblems` — the scaffold-grained twin of the generator's
- *     `--check`, which cannot target a site.
+ *     `--check`, which cannot target a site;
+ *   - `planServedRoster` — the roster without the code-route rows no page
+ *     file serves (#10774), which `update` writes.
  *
  * Pure module: no `import.meta.url`. Package-rooted directories are supplied
  * by the caller, the same split as `add-module.ts` / `programmatic.ts`.
@@ -46,6 +48,9 @@ export const SITE_ROSTER_PATH = ".ailk-site-manifest.json";
 export const LEGACY_SITE_ROSTER_PATH = "TEMPLATE-MANIFEST.json";
 /** Prettier's default print width — the generator formats the manifest with it. */
 const PRINT_WIDTH = 80;
+/** Where the site's App Router pages live. */
+const ROUTE_ROOT = join("apps", "web", "app", "[locale]");
+const PAGE_FILE = /^page\.(tsx|ts|jsx|js|mdx)$/;
 // ── A string-aware JSON scanner, for the text splice ──────────────────────
 function skipWhitespace(text, i) {
     while (i < text.length && /\s/.test(text[i]))
@@ -120,7 +125,7 @@ function arrayElements(text, open) {
  * spans are cross-checked against `JSON.parse`, so a splice can only ever
  * move bytes the parser agrees are those rows.
  */
-function parseRosterFile(text, label) {
+export function parseRosterFile(text, label) {
     const refuse = (why) => new AddModuleRefusedError(`${label} ${why}, so the page roster is unknown`);
     let doc;
     try {
@@ -538,6 +543,7 @@ export function planRosterAppend(opts) {
     const refs = opts.references.filter((ref) => inSet.has(ref.module));
     const contributed = new Set(refs.map((ref) => ref.contribution.route));
     const shipped = readShippedManifest(opts.siteTemplatesDir, roster.template.name);
+    const unserved = unservedRouteRow(targetDir);
     const templateRows = [];
     const moduleRows = new Map();
     const superseded = [];
@@ -567,7 +573,12 @@ export function planRosterAppend(opts) {
                 next.push(...kept);
             }
             else {
-                next.push(expectedRow(ref, targetDir));
+                const row = expectedRow(ref, targetDir);
+                // #10774 D4.1 — a contribution whose page file the site lacks (a
+                // spoke's `/appointments`) is not the site's to declare.
+                if (unserved?.(row.value) === true)
+                    continue;
+                next.push(row);
                 appended.push(route);
             }
         }
@@ -616,6 +627,104 @@ function spliceRows(file, rows) {
         : `${lead}${rows.map((r) => r.text).join(`,${lead}`)}${trail}`;
     return text.slice(0, open + 1) + body + text.slice(close);
 }
+// ── #10774 D4: a code-route row names a route the site serves ─────────────
+/**
+ * Every route the site's App Router serves from a page file, sorted: route
+ * groups `(x)` dropped, a trailing optional catch-all `[[...x]]` folded into
+ * its parent (docs-blog's `/blog/[[...slug]]` serves `/blog`). The root
+ * content renderers (`/[slug]`, `/[slug]/[detail]`) are not routes of their
+ * own — they are how the content rows render — so they are left out.
+ */
+export function servedRoutes(targetDir) {
+    const root = join(targetDir, ROUTE_ROOT);
+    const routes = new Set();
+    const stack = existsSync(root) ? [root] : [];
+    for (let cur = stack.pop(); cur !== undefined; cur = stack.pop()) {
+        const entries = readdirSync(cur, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                stack.push(join(cur, entry.name));
+        }
+        if (!entries.some((entry) => entry.isFile() && PAGE_FILE.test(entry.name))) {
+            continue;
+        }
+        const segments = relative(root, cur)
+            .split(sep)
+            .filter((segment) => segment !== "" && !/^\(.+\)$/.test(segment));
+        const last = segments[segments.length - 1];
+        if (last !== undefined && /^\[\[\.\.\..+\]\]$/.test(last))
+            segments.pop();
+        if (segments[0]?.startsWith("["))
+            continue;
+        routes.add(`/${segments.join("/")}`);
+    }
+    return [...routes].sort();
+}
+/**
+ * Whether a row is a code-route row no page file of the site serves — or
+ * `undefined` when the site has no route tree (a roster-only fixture, a web
+ * app elsewhere), where no row is judged. A route whose first segment is
+ * dynamic is never judged either: the root renderers are not in
+ * `servedRoutes`.
+ */
+function unservedRouteRow(targetDir) {
+    if (!existsSync(join(targetDir, ROUTE_ROOT)))
+        return undefined;
+    const served = new Set(servedRoutes(targetDir));
+    return (row) => {
+        const route = row["route"];
+        return (row["kind"] === "route" &&
+            typeof route === "string" &&
+            !route.split("/").filter(Boolean)[0]?.startsWith("[") &&
+            !served.has(route));
+    };
+}
+/**
+ * `file`'s next text with its unserved code-route rows removed — every other
+ * byte verbatim — and the dropped routes in file order; `next` is undefined
+ * when none is dropped.
+ */
+export function withoutUnservedRouteRows(file, targetDir) {
+    const unserved = unservedRouteRow(targetDir);
+    const dropped = file.rows.filter((row) => unserved?.(row.value) === true);
+    if (dropped.length === 0)
+        return { next: undefined, dropped: [] };
+    return {
+        next: spliceRows(file, file.rows.filter((row) => !dropped.includes(row))),
+        dropped: dropped.map((row) => row.value["route"]),
+    };
+}
+/** The site's roster file, read without resolving its template, or undefined when it has none. */
+function readRosterFile(targetDir) {
+    const path = [SITE_ROSTER_PATH, LEGACY_SITE_ROSTER_PATH].find((name) => existsSync(join(targetDir, name)));
+    if (path === undefined)
+        return undefined;
+    return { ...parseRosterFile(readFileSync(join(targetDir, path), "utf8"), path), path };
+}
+/**
+ * The routes of the site roster's page rows — the rows that carry content —
+ * or undefined when it has none. A code-route row is left out: it records a
+ * route already on disk (signal-collectors' `/careers/apply` walk under the
+ * unrelated careers segment), never a surface the site serves. The template
+ * is not resolved, so a retired template name reads as any other.
+ * @throws AddModuleRefusedError when the file's `rows` cannot be located.
+ */
+export function readRosterPageRoutes(targetDir) {
+    return readRosterFile(targetDir)
+        ?.rows.filter((row) => row.value["kind"] === "page")
+        .map((row) => row.value["route"]);
+}
+/**
+ * The site roster with its unserved code-route rows removed, or undefined
+ * when the site has no roster.
+ * @throws AddModuleRefusedError when the file's `rows` cannot be located.
+ */
+export function planServedRoster(targetDir) {
+    const file = readRosterFile(targetDir);
+    if (file === undefined)
+        return undefined;
+    return { path: file.path, ...withoutUnservedRouteRows(file, targetDir) };
+}
 /** Every `content/en/**.mdx` some layer installs into a site of this template and module set. */
 function layerInstalledSeeds(template, modules, opts, surfaces) {
     const out = new Set();
@@ -670,7 +779,9 @@ function layerInstalledSeeds(template, modules, opts, surfaces) {
  *      the shipped reference row;
  *   3. an installed seed — one some layer lands, present in the site — that
  *      the effective roster does not declare. A page the customer wrote is
- *      installed by no layer and is never reported.
+ *      installed by no layer and is never reported;
+ *   4. a code-route row no page file serves (#10774). A module contribution
+ *      whose page file the site lacks is not expected under 2.
  *
  * A site with no roster (a template-less scaffold) has no problems.
  */
@@ -695,6 +806,13 @@ export function siteRosterProblems(opts) {
             problems.push(`${route}: appears on more than one row`);
         seen.add(route);
     }
+    // #10774 D4.4 — a code-route row no page file serves.
+    const unserved = unservedRouteRow(opts.targetDir);
+    for (const row of roster.rows) {
+        if (unserved?.(row.value) === true) {
+            problems.push(`${row.value["route"]}: a route row, but no page file serves it`);
+        }
+    }
     const contributions = new Map();
     // #10040 D3 — a site that dropped `marketing` carries no public route tree,
     // so no module's public pages are expected on its roster either.
@@ -711,6 +829,8 @@ export function siteRosterProblems(opts) {
             const route = ref.contribution.route;
             contributions.set(route, ref.contribution);
             const wanted = expectedRow(ref, opts.targetDir).value;
+            if (unserved?.(wanted) === true)
+                continue;
             const rows = roster.rows.filter((r) => r.value["route"] === route);
             if (rows.length === 0) {
                 problems.push(`${route}: no row, but module "${moduleName}" contributes it`);

package/dist/surfaces.d.ts

@@ -136,6 +136,14 @@ export declare function resolveSurfaces(modules?: string[], explicit?: string[])
  * on Windows too.
  */
 export declare function excludedRoutePaths(enabled: string[]): string[];
+/**
+ * The module-less gateable surfaces a roster's `routes` name (#5469 D10,
+ * #10774 D2), in `GATEABLE_SURFACES` order. A route names a surface when its
+ * first path segment is one of the surface's top-level route directories
+ * (`/pricing` → `apps/web/app/[locale]/pricing`). A module-owned surface is
+ * never named: it comes only with its module (#5365 FR5).
+ */
+export declare function surfacesNamedByRoutes(routes: readonly string[]): string[];
 /**
  * The content directories belonging to gateable surfaces that are NOT enabled,
  * with `<locale>` left in place for the caller to expand.

package/dist/surfaces.js

@@ -540,6 +540,22 @@ export function excludedRoutePaths(enabled) {
     }
     return out.sort();
 }
+/**
+ * The module-less gateable surfaces a roster's `routes` name (#5469 D10,
+ * #10774 D2), in `GATEABLE_SURFACES` order. A route names a surface when its
+ * first path segment is one of the surface's top-level route directories
+ * (`/pricing` → `apps/web/app/[locale]/pricing`). A module-owned surface is
+ * never named: it comes only with its module (#5365 FR5).
+ */
+export function surfacesNamedByRoutes(routes) {
+    const routeRoot = "apps/web/app/[locale]";
+    const moduleOwned = new Set(Object.values(MODULE_SURFACES).flat());
+    const topSegments = new Set(routes
+        .map((route) => route.split("/").filter(Boolean)[0])
+        .filter((segment) => segment !== undefined));
+    return GATEABLE_SURFACES.filter((surface) => !moduleOwned.has(surface.id) &&
+        surface.routes.some((dir) => topSegments.has(dir.slice(routeRoot.length + 1)))).map((surface) => surface.id);
+}
 /**
  * The content directories belonging to gateable surfaces that are NOT enabled,
  * with `<locale>` left in place for the caller to expand.

package/dist/update.d.ts

@@ -1,3 +1,4 @@
+import { type MdxParse } from "./mdx-braces.js";
 import type { WorkspaceVersionMap } from "./substitute.js";
 /** A refusal the CLI exits 2 on, thrown before anything is written. */
 export declare class UpdateRefusedError extends Error {
@@ -23,6 +24,11 @@ export interface UpdateSiteOptions {
      * at. A site already on both boot sets, or a spoke, never reads it.
      */
     versions?: WorkspaceVersionMap;
+    /**
+     * The MDX parser the brace pass verifies an escape with (#10773 D5);
+     * `null` acts as "not installed". Absent: `loadSiteMdxParse(targetDir)`.
+     */
+    mdxParse?: MdxParse | null;
 }
 export interface UpdateResult {
     targetDir: string;
@@ -58,8 +64,14 @@ export interface UpdateResult {
     envRowsAdded?: string[];
     /** Record rows dropped because the path is no longer recordable (#10173). */
     droppedRows?: string[];
+    /** The module-less surfaces the roster names that `architecture.yaml` now declares (#10774 D3). */
+    surfacesDeclared?: string[];
+    /** The roster's code-route rows dropped because no page file serves them, in roster order (#10774 D4). */
+    rosterRowsDropped?: string[];
     /** The mdx-body pages under `content/` given a `# ` heading this run (#7495). */
     headingsAdded: string[];
+    /** The mdx-body pages under `content/` whose bare `{` were escaped this run (#10773). */
+    bracesEscaped: string[];
     backfilled?: {
         version: string;
         files: number;
@@ -83,12 +95,20 @@ export declare function mergeMessagesAdditively(ours: string, theirs: string): {
     reason: string;
 };
 export declare function updateSite(opts: UpdateSiteOptions): Promise<UpdateResult>;
+/**
+ * The site's own MDX parser (#10773 D5): `@mdx-js/mdx` resolved through the
+ * `next-mdx-remote` its `apps/web` renders with — never create-ailk's own
+ * copy, and never fetched. `undefined` when it is not installed or fails to
+ * load; never throws.
+ */
+export declare function loadSiteMdxParse(targetDir: string): Promise<MdxParse | undefined>;
+export type { MdxParse } from "./mdx-braces.js";
 /** The printed report (D9): one section per non-empty list, in order. */
 export declare function formatUpdateReport(result: UpdateResult): string;
 export interface UpdateArgs {
     target: string | undefined;
     help: boolean;
 }
-export declare const UPDATE_HELP = "create-ailk update \u2014 bring template fixes into a site's copied app code.\n\nUsage:\n  create-ailk update [<target-dir>]\n\nArguments:\n  <target-dir>             The existing site. Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nReads .ailk-template-files.json (written beside .ailk-site-manifest.json by\nevery template scaffold) to tell an untouched copy from an edit. An\nuntouched apps/web, apps/api or apps/mcp file, or a root tools/jest file the\napp jest configs require, whose template copy changed is overwritten. An\nedited file whose template copy also changed is three-way merged with\n`git` (git must be on PATH); a conflict leaves the file alone and is\nlisted under \"Needs review\"; an apps/web/messages catalog instead gains the\ntemplate's new keys and keeps every value it has, and is reviewed only when a\nkey is an object on one side and a value on the other. Every template file,\ntest or not, that imports a file left under \"Needs review\" or \"Skipped\" (by a\nrelative or @/ import, transitively) is held at the site's version with it,\nits record entry is not advanced, and it is listed under \"Held back with\n<file>\" \u2014 reconcile the file, then run update again to bring it forward. A\nwritten file whose import names a file the site will not have is held the\nsame way, under \"Held back with <file> (not in this site)\". Every other file\nin the run still updates. When project.yaml has an env_contract block, each\nenv var the written files read that has no row gains one; no row is edited.\nA record row at a path create-ailk no longer records is dropped and listed.\nA site with no record gets one on its first run, from the version its\n.ailk-site-manifest.json already records. A site scaffolded before\n@working-theory/mcp-server has its copied apps/mcp moved to the boot set:\nthe server and each module's paid MCP pack join apps/mcp/package.json, the\ncopied server files go, and apps/mcp/src/lib/paid-tools.generated.ts is\nrewritten on every run. A site scaffolded before @working-theory/api has its\ncopied apps/api moved to the boot file: the app becomes @working-theory/app-api,\nthe package and the six @working-theory/api-<module> packages join\napps/api/package.json, its bins and build:vercel delegate to the package, and\nthe copied server files go. Run `pnpm install` after either move, since the\napp's package.json gained dependencies. Each mdx-body page in content/ with no\n'# ' heading gets its title and description written into its body as its\nheading and intro, listed under \"Page heading added\"; a page with one heading\nis left as it is, and one with several, or one whose frontmatter it cannot\nread, is listed under \"Needs review\". Commit before running, and review the\ndiff after.\n";
+export declare const UPDATE_HELP = "create-ailk update \u2014 bring template fixes into a site's copied app code.\n\nUsage:\n  create-ailk update [<target-dir>]\n\nArguments:\n  <target-dir>             The existing site. Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nReads .ailk-template-files.json (written beside .ailk-site-manifest.json by\nevery template scaffold) to tell an untouched copy from an edit. An\nuntouched apps/web, apps/api or apps/mcp file, or a root tools/jest file the\napp jest configs require, whose template copy changed is overwritten. An\nedited file whose template copy also changed is three-way merged with\n`git` (git must be on PATH); a conflict leaves the file alone and is\nlisted under \"Needs review\"; an apps/web/messages catalog instead gains the\ntemplate's new keys and keeps every value it has, and is reviewed only when a\nkey is an object on one side and a value on the other. Every template file,\ntest or not, that imports a file left under \"Needs review\" or \"Skipped\" (by a\nrelative or @/ import, transitively) is held at the site's version with it,\nits record entry is not advanced, and it is listed under \"Held back with\n<file>\" \u2014 reconcile the file, then run update again to bring it forward. A\nwritten file whose import names a file the site will not have is held the\nsame way, under \"Held back with <file> (not in this site)\". Every other file\nin the run still updates. When project.yaml has an env_contract block, each\nenv var the written files read that has no row gains one; no row is edited.\nA record row at a path create-ailk no longer records is dropped and listed.\nA surface the site's .ailk-site-manifest.json names a page on but\narchitecture.yaml does not declare (one no module owns, such as projects)\ngets its route files added and is declared, listed under \"Surfaces declared\nfrom the roster\". A code-route row of that roster no page file serves is\ndropped, listed under \"Roster rows dropped, no route serves them\".\nA site with no record gets one on its first run, from the version its\n.ailk-site-manifest.json already records. A site scaffolded before\n@working-theory/mcp-server has its copied apps/mcp moved to the boot set:\nthe server and each module's paid MCP pack join apps/mcp/package.json, the\ncopied server files go, and apps/mcp/src/lib/paid-tools.generated.ts is\nrewritten on every run. A site scaffolded before @working-theory/api has its\ncopied apps/api moved to the boot file: the app becomes @working-theory/app-api,\nthe package and the six @working-theory/api-<module> packages join\napps/api/package.json, its bins and build:vercel delegate to the package, and\nthe copied server files go. Run `pnpm install` after either move, since the\napp's package.json gained dependencies. Each mdx-body page in content/ with no\n'# ' heading gets its title and description written into its body as its\nheading and intro, listed under \"Page heading added\"; a page with one heading\nis left as it is, and one with several, or one whose frontmatter it cannot\nread, is listed under \"Needs review\". Each bare { on an mdx-body page is\nescaped as \\{ when the site's own MDX parser then reads the page clean, listed\nunder \"Placeholder brace escaped\"; a page it cannot escape safely, or any page\nwith one while the site's dependencies are not installed, is listed under\n\"Needs review\". Commit before running, and review the diff after.\n";
 /** Parse the argv AFTER the `update` word. Strict `node:util` parseArgs, like `parseAdoptArgs`. */
 export declare function parseUpdateArgs(argv: string[]): UpdateArgs;

package/dist/update.js

@@ -36,29 +36,35 @@
  * before the first write. Last, every mdx-body page in the site's `content/`
  * with no `# ` heading gets its title and description written into its body
  * (#7495, `body-heading.ts`); a page with one or more headings is never
- * touched, and `content/` is never recorded.
+ * touched, and `content/` is never recorded. Then every bare `{` on an
+ * mdx-body page is escaped as `\{`, kept only when the site's own MDX parser
+ * reads the page clean (#10773, `mdx-braces.ts`).
  *
  * Pure module: no `import.meta.url` — the CLI supplies `templatesDir`, the
  * `adopt.ts` / `add-route.ts` split.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, rmdirSync, statSync, writeFileSync, } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import { AddModuleRefusedError, readArchitectureHeader } from "./add-module-core.js";
-import { headingViolations, mdxBodyRule, migrateBodyHeadings } from "./body-heading.js";
+import { headingViolations, mdxBodyPages, mdxBodyRule, migrateBodyHeadings } from "./body-heading.js";
 import { buildScaffoldMarkers, isExcluded, isTextFile, renderTemplateFile, templateDestination } from "./copy.js";
+import { deriveArchitecture } from "./derive-architecture.js";
 import { EnvContractError, planEnvRows, readEnvContract, readManifestTopology, } from "./lib/declared-env.js";
 import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { fetchTemplateSnapshot } from "./lib/fetch-template-snapshot.js";
 import { exportsName, listFilesUnder, namedImportsOf } from "./lib/import-graph.js";
 import { mergeThreeWay } from "./lib/merge-three-way.js";
 import { publicTreeRemoved } from "./lib/site-modules.js";
+import { escapeBareBraces, findBareBraces } from "./mdx-braces.js";
 import { MODULE_SLICES } from "./module-architecture.js";
 import { MODULE_FLAGS_PATH, PAID_MCP_TOOLS_PATH, writeModuleFlags, writePaidMcpTools, } from "./paid-sections.js";
 import { ParseError } from "./parse-args.js";
-import { SITE_ROSTER_PATH } from "./site-roster.js";
+import { SITE_ROSTER_PATH, planServedRoster, readRosterPageRoutes } from "./site-roster.js";
 import { SPOKE_CHECKOUT_TEMPLATE_PATHS } from "./spoke-checkout.js";
-import { excludedRoutePaths, isRemovedPublicRoutePath } from "./surfaces.js";
+import { GATEABLE_SURFACES, excludedRoutePaths, isRemovedPublicRoutePath, resolveSurfaces, surfacesNamedByRoutes, } from "./surfaces.js";
 import { DATABASE_BOOT_FILES, ROOT_TOOL_FILES, TEMPLATE_RECORD_PATH, isRecordable, parseTemplateRecord, serializeTemplateRecord, sha256Hex, } from "./template-record.js";
 import { MCP_SEAM_PATH, MCP_SERVER_HUB, TopologyError, isSpokeExcluded, readSpokeShape, spokeExclusions, } from "./topology.js";
 /** A refusal the CLI exits 2 on, thrown before anything is written. */
@@ -930,6 +936,35 @@ export async function updateSite(opts) {
         throw err;
     }
     const excludedRoutes = excludedRoutePaths(header.surfaces);
+    // #10774 D3 — a module-less surface the roster's page rows name but the header omits
+    // (the /projects pair a 0.19.0 scaffold rostered without its route) is in
+    // scope for the add loop only, and declared after the writes (even when an
+    // add is held back, #10173: the next run adds it). The
+    // roster is read even when it brings nothing, so an unreadable one is
+    // refused here, before the first write, not at the drop after it.
+    let rosterRoutes;
+    try {
+        rosterRoutes = readRosterPageRoutes(targetDir) ?? [];
+    }
+    catch (err) {
+        if (err instanceof AddModuleRefusedError)
+            throw new UpdateRefusedError(err.message);
+        throw err;
+    }
+    const declaredByRoster = publicTreeRemoved(targetDir)
+        ? []
+        : surfacesNamedByRoutes(rosterRoutes).filter((surface) => !header.surfaces.includes(surface));
+    const addExcludedRoutes = excludedRoutePaths([...header.surfaces, ...declaredByRoster]);
+    const declaredRouteDirs = GATEABLE_SURFACES.filter((surface) => declaredByRoster.includes(surface.id)).flatMap((surface) => surface.routes);
+    let declaredArchitecture;
+    if (declaredByRoster.length > 0) {
+        try {
+            declaredArchitecture = deriveArchitecture(header.modules, resolveSurfaces(header.modules, [...header.surfaces, ...declaredByRoster]), spoke !== undefined ? { topology: "spoke", mcp: existsSync(join(targetDir, "apps", "mcp")) } : {});
+        }
+        catch (err) {
+            throw new UpdateRefusedError(`architecture.yaml's \`# Surfaces:\` header cannot declare ${declaredByRoster.join(", ")}: ${err.message}`);
+        }
+    }
     const spokeExclusionList = spoke !== undefined ? spokeExclusions(opts.templatesDir, spoke) : undefined;
     // #8748 D3 — the standard spoke checkout is a commerce spoke's alone.
     const sellsAsSpoke = spoke !== undefined && header.modules.includes("commerce");
@@ -937,10 +972,10 @@ export async function updateSite(opts) {
     // never touched: its boot paths are out of scope, reported under the guard.
     const databaseIsPackage = existsSync(join(targetDir, "database", "package.json"));
     const bootFileGuarded = (destRel) => databaseIsPackage && DATABASE_BOOT_FILES.includes(destRel);
-    const outOfScope = (destRel) => {
+    const outOfScope = (destRel, excluded = excludedRoutes) => {
         if (bootFileGuarded(destRel))
             return true;
-        if (isExcluded(destRel, excludedRoutes))
+        if (isExcluded(destRel, excluded))
             return true;
         if (!sellsAsSpoke && isExcluded(destRel, SPOKE_CHECKOUT_TEMPLATE_PATHS))
             return true;
@@ -1232,9 +1267,11 @@ export async function updateSite(opts) {
             }
             continue;
         }
-        if (outOfScope(path))
+        if (outOfScope(path, addExcludedRoutes))
             continue; // rule i/ii
-        const highest = highestMissingAncestor(path, targetDir);
+        // #10774 D3 — a surface this run declares was never copied, so its
+        // missing directory is no owner's deletion: rule iii does not apply.
+        const highest = isExcluded(path, declaredRouteDirs) ? undefined : highestMissingAncestor(path, targetDir);
         if (highest !== undefined && containsKnownPath(highest, knownPaths))
             continue; // rule iii
         writes.push({ path, bytes: Buffer.from(newBytes) });
@@ -1484,6 +1521,15 @@ export async function updateSite(opts) {
     if (recordChanged) {
         writeFileSync(recordPath, serializeTemplateRecord({ schema: 1, projectName: record.projectName, files: nextFiles }));
     }
+    // #10774 D3 — the surfaces the roster named are declared, as add-route
+    // declares one: the whole generated file, re-derived.
+    if (declaredArchitecture !== undefined)
+        writeFileSync(archPath, declaredArchitecture);
+    // #10774 D4.3 — the roster's code-route rows no page file serves, read
+    // after the writes so a route this run added counts as served.
+    const servedRoster = planServedRoster(targetDir);
+    if (servedRoster?.next !== undefined)
+        writeFileSync(join(targetDir, servedRoster.path), servedRoster.next);
     // #8843 D10 — the module-presence flags are generated, never copied
     // (REGENERATED_APP_PATHS): render them from this site's own
     // apps/web/package.json on every run, so a site updated onto a layout
@@ -1570,6 +1616,34 @@ export async function updateSite(opts) {
     for (const { path, reason } of headings.refused) {
         review.push({ path: sitePath(path), reason: `no '# ' heading added: ${reason}` });
     }
+    // #10773 D6 — a bare `{` on an mdx-body page is MDX code: the page fails or
+    // drops it. Escape every one, after the heading pass so its writes are read
+    // too, keeping a page's write only when the site's own parser reads it clean.
+    const parse = opts.mdxParse === undefined ? await loadSiteMdxParse(targetDir) : opts.mdxParse ?? undefined;
+    const bracesEscaped = [];
+    for (const { path, raw, bodyStart } of mdxBodyPages(contentDir, rule)) {
+        // Blank lines in place of the frontmatter, so every line named is the file's.
+        const pad = "\n".repeat(raw.slice(0, bodyStart).split("\n").length - 1);
+        const body = pad + raw.slice(bodyStart);
+        if (parse === undefined) {
+            const lines = findBareBraces(body).map((brace) => brace.line);
+            if (lines.length === 0)
+                continue;
+            review.push({
+                path: sitePath(path),
+                reason: `${lines.length} bare {…} at line ${[...new Set(lines)].join(", ")}; not escaped: the site's MDX parser is not installed — run pnpm install, then update again`,
+            });
+            continue;
+        }
+        const escape = escapeBareBraces(body, parse);
+        if (escape.kind === "escaped") {
+            writeFileSync(path, raw.slice(0, bodyStart) + escape.text.slice(pad.length));
+            bracesEscaped.push(sitePath(path));
+        }
+        else if (escape.kind === "refused") {
+            review.push({ path: sitePath(path), reason: `bare {…} not escaped: ${escape.reason}` });
+        }
+    }
     return {
         targetDir,
         version,
@@ -1578,11 +1652,48 @@ export async function updateSite(opts) {
         skipped,
         heldBack,
         headingsAdded: headings.written.map(sitePath),
+        bracesEscaped,
         ...(backfilled !== undefined ? { backfilled } : {}),
         ...(envRowsAdded.length > 0 ? { envRowsAdded } : {}),
         ...(droppedRows.length > 0 ? { droppedRows: droppedRows.sort() } : {}),
+        ...(declaredByRoster.length > 0 ? { surfacesDeclared: declaredByRoster } : {}),
+        ...(servedRoster !== undefined && servedRoster.dropped.length > 0
+            ? { rosterRowsDropped: servedRoster.dropped }
+            : {}),
     };
 }
+/** Whether a `node_modules` at or above `dir` holds `pkg` — so `resolve` never falls back to NODE_PATH. */
+function installedAbove(dir, pkg) {
+    for (let at = dir;; at = dirname(at)) {
+        if (existsSync(join(at, "node_modules", pkg, "package.json")))
+            return true;
+        if (dirname(at) === at)
+            return false;
+    }
+}
+/**
+ * The site's own MDX parser (#10773 D5): `@mdx-js/mdx` resolved through the
+ * `next-mdx-remote` its `apps/web` renders with — never create-ailk's own
+ * copy, and never fetched. `undefined` when it is not installed or fails to
+ * load; never throws.
+ */
+export async function loadSiteMdxParse(targetDir) {
+    try {
+        const web = join(resolve(targetDir), "apps", "web");
+        if (!installedAbove(web, "next-mdx-remote"))
+            return undefined;
+        const remote = createRequire(join(web, "package.json")).resolve("next-mdx-remote/package.json");
+        const entry = createRequire(remote).resolve("@mdx-js/mdx");
+        const mdx = (await import(pathToFileURL(entry).href));
+        const createProcessor = mdx.createProcessor;
+        if (typeof createProcessor !== "function")
+            return undefined;
+        return (body) => createProcessor().parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The printed report (D9): one section per non-empty list, in order. */
 export function formatUpdateReport(result) {
     const lines = [`[create-ailk] update → ${result.targetDir}`];
@@ -1596,6 +1707,7 @@ export function formatUpdateReport(result) {
         ["Removed", result.removed],
         ["Already current", result.current],
         ["Page heading added", result.headingsAdded],
+        ["Placeholder brace escaped", result.bracesEscaped],
     ];
     for (const [label, paths] of sections) {
         if (paths.length === 0)
@@ -1620,6 +1732,14 @@ export function formatUpdateReport(result) {
         lines.push(`Dropped from ${TEMPLATE_RECORD_PATH}, no longer recorded (${result.droppedRows.length}):`);
         lines.push(...result.droppedRows.map((path) => `  ${path}`));
     }
+    if (result.surfacesDeclared !== undefined) {
+        lines.push(`Surfaces declared from the roster (${result.surfacesDeclared.length}):`);
+        lines.push(...result.surfacesDeclared.map((surface) => `  ${surface}`));
+    }
+    if (result.rosterRowsDropped !== undefined) {
+        lines.push(`Roster rows dropped, no route serves them (${result.rosterRowsDropped.length}):`);
+        lines.push(...result.rosterRowsDropped.map((route) => `  ${route}`));
+    }
     if (result.skipped.length > 0) {
         lines.push(`Skipped (${result.skipped.length}):`);
         lines.push(...result.skipped.map((row) => `  ${row.path} — ${row.reason}`));
@@ -1631,10 +1751,13 @@ export function formatUpdateReport(result) {
         result.removed.length === 0 &&
         result.current.length === 0 &&
         result.headingsAdded.length === 0 &&
+        result.bracesEscaped.length === 0 &&
         result.review.length === 0 &&
         result.skipped.length === 0 &&
         result.envRowsAdded === undefined &&
-        result.droppedRows === undefined;
+        result.droppedRows === undefined &&
+        result.surfacesDeclared === undefined &&
+        result.rosterRowsDropped === undefined;
     if (nothingHappened) {
         return `[create-ailk] Already up to date (create-ailk ${result.version}).\n`;
     }
@@ -1677,6 +1800,11 @@ same way, under "Held back with <file> (not in this site)". Every other file
 in the run still updates. When project.yaml has an env_contract block, each
 env var the written files read that has no row gains one; no row is edited.
 A record row at a path create-ailk no longer records is dropped and listed.
+A surface the site's .ailk-site-manifest.json names a page on but
+architecture.yaml does not declare (one no module owns, such as projects)
+gets its route files added and is declared, listed under "Surfaces declared
+from the roster". A code-route row of that roster no page file serves is
+dropped, listed under "Roster rows dropped, no route serves them".
 A site with no record gets one on its first run, from the version its
 .ailk-site-manifest.json already records. A site scaffolded before
 @working-theory/mcp-server has its copied apps/mcp moved to the boot set:
@@ -1691,8 +1819,11 @@ app's package.json gained dependencies. Each mdx-body page in content/ with no
 '# ' heading gets its title and description written into its body as its
 heading and intro, listed under "Page heading added"; a page with one heading
 is left as it is, and one with several, or one whose frontmatter it cannot
-read, is listed under "Needs review". Commit before running, and review the
-diff after.
+read, is listed under "Needs review". Each bare { on an mdx-body page is
+escaped as \\{ when the site's own MDX parser then reads the page clean, listed
+under "Placeholder brace escaped"; a page it cannot escape safely, or any page
+with one while the site's dependencies are not installed, is listed under
+"Needs review". Commit before running, and review the diff after.
 `;
 /** Parse the argv AFTER the `update` word. Strict `node:util` parseArgs, like `parseAdoptArgs`. */
 export function parseUpdateArgs(argv) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,8 +28,8 @@
     "tar": "^7.5.21"
   },
   "devDependencies": {
-    "@working-theory/schema": "0.54.0",
-    "@working-theory/templates": "0.54.0"
+    "@working-theory/schema": "0.55.0",
+    "@working-theory/templates": "0.55.0"
   },
   "repository": {
     "type": "git",

package/templates/.github/workflows/ci.yml

@@ -69,6 +69,8 @@ jobs:
       - run: pnpm claude-md:check
       # A new page file on a site whose pages come from the database (#10660).
       - run: pnpm content-source:check
+      # A bare { on an mdx-body page, which fails the page or drops it (#10773).
+      - run: pnpm mdx-body:check
 
       - run: pnpm test
 

package/templates/apps/mcp/.env.example

@@ -91,9 +91,15 @@ MCP_ABUSE_BLOCKED_USER_AGENTS=
 # (the Artifact store — the server resolves its own single workspace at
 # bootstrap; a deployment that isn't unambiguously one-workspace serves no
 # content rather than guessing).
+# On a SPOKE (#10658), CONTENT_ADAPTER=database reads this spoke's own
+# published pages through the hub at AILK_API_URL under AILK_SPOKE_KEY (below),
+# with no DATABASE_URL — set it once the spoke's page files are removed. A
+# spoke whose key will not be sent (unset, not https or loopback, or no
+# AILK_API_URL) serves no content; the boot writes one stderr line saying
+# which way it went.
 # CONTENT_ADAPTER=mdx
 
-# Required ONLY when CONTENT_ADAPTER=database.
+# Required ONLY on a hub's CONTENT_ADAPTER=database — never on a spoke.
 # DATABASE_URL=
 
 # ── Spoke key ─────────────────────────────────────────────────────────────────

package/templates/apps/web/__tests__/setup.ts

@@ -1,4 +1,5 @@
 import { TextDecoder, TextEncoder } from "node:util";
+import { deserialize, serialize } from "node:v8";
 
 import "@testing-library/jest-dom";
 
@@ -17,6 +18,14 @@ if (typeof globalThis.TextEncoder === "undefined") {
   (globalThis as unknown as { TextDecoder: unknown }).TextDecoder = TextDecoder;
 }
 
+// #10704 D3 — nor `structuredClone`, which Node exposes only as a global. The
+// database render path clones a page's words with it (`@working-theory/
+// validation`'s `words-codec.ts`); the v8 round trip clones the same plain data.
+if (typeof globalThis.structuredClone === "undefined") {
+  globalThis.structuredClone = (<T>(value: T): T =>
+    deserialize(serialize(value)) as T) as typeof structuredClone;
+}
+
 // SOFT_LOCK_OK: #6510 (D1) — jsdom does not implement ResizeObserver.
 // BannerConsentIsland (the layout's always-mounted consent Banner,
 // placement="bottom") now constructs one when reserveSpace is set — the

package/templates/apps/web/app/[locale]/[slug]/[detail]/__tests__/page.test.tsx

@@ -105,6 +105,9 @@ import { notFound } from "next/navigation";
 import { listingExtension } from "../../../../../lib/listings";
 import DetailPage, { generateMetadata } from "../page";
 
+// #10704 — a fixture suite: its content is shaped for the mdx source, whatever the site serves from.
+process.env.CONTENT_ADAPTER = "mdx";
+
 const mockNotFound = notFound as jest.MockedFunction<typeof notFound>;
 
 function makeSource(slug: string) {

package/templates/apps/web/app/[locale]/[slug]/__tests__/page.test.tsx

@@ -45,6 +45,9 @@ jest.mock("@working-theory/ui", () => ({
 import { notFound } from "next/navigation";
 import SlugPage from "../page";
 
+// #10704 — a fixture suite: its content is shaped for the mdx source, whatever the site serves from.
+process.env.CONTENT_ADAPTER = "mdx";
+
 const mockNotFound = notFound as jest.MockedFunction<typeof notFound>;
 
 function makeSource(slug: string, schema?: Record<string, unknown>) {