create-ailk 0.30.0 → 0.32.0

package/dist/site-manifest.js

@@ -38,13 +38,10 @@ import { join, relative, sep } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { AddModuleRefusedError } from "./add-module-core.js";
 import { MODULE_SLICES, normalizeModules } from "./module-architecture.js";
-import { SITE_ROSTER_PATH, moduleRosterRows, parseSiteRoster, planRosterAppend, resolveRosterTemplate, } from "./site-roster.js";
+import { SITE_ROSTER_PATH, moduleRosterRows, parseRosterFile, parseSiteRoster, planRosterAppend, resolveRosterTemplate, servedRoutes, withoutUnservedRouteRows, } from "./site-roster.js";
 import { TEMPLATE_MANIFESTS, rosterDeclares, templateTreeDir, } from "./template-manifest.js";
 /** 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)$/;
 /**
  * The generator's row for a content-less route (`build-template-manifest.mjs`:
  * every row renders under the locale layout's MarketingShell, chrome on).
@@ -89,7 +86,10 @@ export function planSiteManifest(opts) {
         templatesDir: opts.templatesDir,
         markers: opts.markers,
     });
-    const appended = plan.next ?? roster.text;
+    // #10774 D4.2 — the template's own code-route rows a spoke does not serve
+    // (`/sign-in`, `/sign-up`) leave with the files the spoke filter dropped.
+    const planned = plan.next ?? roster.text;
+    const appended = withoutUnservedRouteRows(parseRosterFile(planned, roster.path), opts.targetDir).next ?? planned;
     const declared = new Set(JSON.parse(appended).rows.map((row) => row["route"]));
     const extra = [
         ...sampleRows(opts, declared),
@@ -226,42 +226,10 @@ function sampleRows(opts, declared) {
 }
 /** A code-route row for every page route on disk that `declared` does not name. */
 function codeRouteRows(targetDir, declared) {
-    return routesOnDisk(targetDir)
+    return servedRoutes(targetDir)
         .filter((route) => !declared.has(route))
         .map((route) => ({ route, ...CODE_ROUTE_ROW }));
 }
-/**
- * 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.
- */
-function routesOnDisk(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();
-}
 /** Every `.mdx` under `dir`, as sorted `/`-separated paths relative to `base`. */
 function listMdx(dir, base) {
     const out = [];

package/dist/site-roster.d.ts

@@ -20,7 +20,7 @@ export interface RosterRowSlice {
     text: string;
 }
 /** A parsed manifest file, with the `rows` array located in its text. */
-interface RosterFile {
+export interface RosterFile {
     doc: Record<string, unknown>;
     text: string;
     rows: RosterRowSlice[];
@@ -52,6 +52,12 @@ export interface ModuleRosterRow {
     /** A `contentDir` contribution's seeded page form. */
     seeded?: RosterRowSlice;
 }
+/**
+ * Parse a manifest file and locate its `rows` array in the text. The element
+ * spans are cross-checked against `JSON.parse`, so a splice can only ever
+ * move bytes the parser agrees are those rows.
+ */
+export declare function parseRosterFile(text: string, label: string): RosterFile;
 /**
  * The site's roster of record, or `undefined` when the site has none (a
  * scaffold that named no template installs no manifest). A file that is not
@@ -176,6 +182,42 @@ export interface PlanRosterAppendOptions {
  * other row on a contributed route is the site's own and is kept as is.
  */
 export declare function planRosterAppend(opts: PlanRosterAppendOptions): RosterAppendPlan;
+/**
+ * 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 declare function servedRoutes(targetDir: string): string[];
+/**
+ * `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 declare function withoutUnservedRouteRows(file: RosterFile, targetDir: string): {
+    next: string | undefined;
+    dropped: string[];
+};
+/**
+ * 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 declare function readRosterPageRoutes(targetDir: string): string[] | undefined;
+/**
+ * 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 declare function planServedRoster(targetDir: string): {
+    path: string;
+    next: string | undefined;
+    dropped: string[];
+} | undefined;
 export interface SiteRosterCheckOptions {
     targetDir: string;
     siteTemplatesDir: string;
@@ -191,9 +233,10 @@ export interface SiteRosterCheckOptions {
  *      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.
  */
 export declare function siteRosterProblems(opts: SiteRosterCheckOptions): string[];
-export {};

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/topology.d.ts

@@ -215,6 +215,18 @@ export declare const HUB_ORIGIN_ENV_VAR = "AILK_API_URL";
  * the hub issues those.
  */
 export declare function writeHubOriginEnv(targetDir: string, origin: string): void;
+/**
+ * `<name>=<value()>` into `apps/web/.env.local`, unless any env file Next
+ * loads for `apps/web` already assigns `name` (`value` is then never called);
+ * and `.env.local` gitignored either way. `true` when the line was written.
+ */
+export declare function writeWebEnv(targetDir: string, name: string, value: () => string): boolean;
+/**
+ * `<name>=<value()>` into `apps/api/.env` — the one file the API's
+ * `dotenv.config()` reads — under `writeWebEnv`'s never-clobber rule, and
+ * `.env` gitignored either way (#10659 D6). `true` when the line was written.
+ */
+export declare function writeApiEnv(targetDir: string, name: string, value: () => string): boolean;
 /** The env var naming the hub's web origin a hub-mode spoke signs in at (#7894 D11). */
 export declare const HUB_SIGN_IN_URL_ENV_VAR = "AILK_HUB_SIGN_IN_URL";
 /** The env var holding a hub-mode spoke's own cookie key material (#7894 D7, D11). */

package/dist/topology.js

@@ -903,19 +903,32 @@ export function writeHubOriginEnv(targetDir, origin) {
     writeWebEnv(targetDir, HUB_ORIGIN_ENV_VAR, () => origin);
 }
 /**
- * `<name>=<value()>` into the spoke's `apps/web/.env.local`, unless any env
- * file Next loads for `apps/web` already assigns `name` (`value` is then never
- * called); and `.env.local` gitignored either way.
+ * `<name>=<value()>` into `apps/web/.env.local`, unless any env file Next
+ * loads for `apps/web` already assigns `name` (`value` is then never called);
+ * and `.env.local` gitignored either way. `true` when the line was written.
  */
-function writeWebEnv(targetDir, name, value) {
-    const webDir = join(targetDir, "apps", "web");
+export function writeWebEnv(targetDir, name, value) {
+    return writeEnvLine(join(targetDir, "apps", "web"), NEXT_ENV_FILES, ".env.local", targetDir, ENV_LOCAL_IGNORE_LINES, name, value);
+}
+/** The lines that gitignore `apps/api/.env`; `.env` is appended when none is there. */
+const ENV_IGNORE_LINES = new Set([".env", "**/.env", ".env*"]);
+/**
+ * `<name>=<value()>` into `apps/api/.env` — the one file the API's
+ * `dotenv.config()` reads — under `writeWebEnv`'s never-clobber rule, and
+ * `.env` gitignored either way (#10659 D6). `true` when the line was written.
+ */
+export function writeApiEnv(targetDir, name, value) {
+    return writeEnvLine(join(targetDir, "apps", "api"), [".env"], ".env", targetDir, ENV_IGNORE_LINES, name, value);
+}
+/** One app's never-clobber env append, and the root `.gitignore` guard. */
+function writeEnvLine(appDir, files, target, targetDir, ignoreLines, name, value) {
     const assigned = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=\\s*\\S`, "m");
-    const already = NEXT_ENV_FILES.some((file) => {
-        const path = join(webDir, file);
+    const already = files.some((file) => {
+        const path = join(appDir, file);
         return existsSync(path) && assigned.test(readFileSync(path, "utf8"));
     });
     if (!already) {
-        const file = join(webDir, ".env.local");
+        const file = join(appDir, target);
         const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
         writeOwnerOnly(file, appendLine(existing, `${name}=${value()}`));
     }
@@ -923,9 +936,10 @@ function writeWebEnv(targetDir, name, value) {
     const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";
     const covered = ignore
         .split("\n")
-        .some((line) => ENV_LOCAL_IGNORE_LINES.has(line.trim()));
+        .some((line) => ignoreLines.has(line.trim()));
     if (!covered)
-        writeFileSync(ignorePath, appendLine(ignore, ".env.local"));
+        writeFileSync(ignorePath, appendLine(ignore, target));
+    return !already;
 }
 /** The env var naming the hub's web origin a hub-mode spoke signs in at (#7894 D11). */
 export const HUB_SIGN_IN_URL_ENV_VAR = "AILK_HUB_SIGN_IN_URL";

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;