create-ailk 0.28.0 → 0.29.0

package/dist/update.js

@@ -10,10 +10,16 @@
  * version's copy — read from this package's own `templates/` when that is
  * the running version, else re-materialised from the published npm tarball
  * (`lib/fetch-template-snapshot.ts`) — and the running version's copy. A
- * conflict leaves the file untouched and is listed under "Needs review". Every
- * template test that imports a file left under review or skipped is held at
- * the site's version with it, so a run never leaves a test newer than the
- * code it exercises (#8704). A site with no record gets one backfilled from
+ * conflict leaves the file untouched and is listed under "Needs review" — but
+ * a `apps/web/messages/` catalog takes the template's new keys and keeps the
+ * site's values, reviewed only on a key-level conflict (#10173). Every
+ * template file this run would write that imports, transitively, a file left
+ * under review or skipped — or a file the site will not have — is held at the
+ * site's version with it, so a run never writes code newer than what it
+ * imports (#8704 for tests, #10173 for the rest). The env vars the written
+ * files read gain `project.yaml` `env_contract` rows (#10172), and a record
+ * row at a path no longer recorded is dropped, not refused (#10173). A site
+ * with no record gets one backfilled from
  * `.ailk-site-manifest.json`'s `patternVersion` on its first run — one row
  * per in-scope path of that version's snapshot, on disk or not (#9527) —
  * then updates normally. A site scaffolded before `@working-theory/mcp-server`
@@ -35,13 +41,16 @@
  * Pure module: no `import.meta.url` — the CLI supplies `templatesDir`, the
  * `adopt.ts` / `add-route.ts` split.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, rmdirSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, rmdirSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { AddModuleRefusedError, readArchitectureHeader } from "./add-module-core.js";
 import { headingViolations, mdxBodyRule, migrateBodyHeadings } from "./body-heading.js";
 import { buildScaffoldMarkers, isExcluded, isTextFile, renderTemplateFile, templateDestination } from "./copy.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 { MODULE_SLICES } from "./module-architecture.js";
@@ -170,6 +179,7 @@ function containsKnownPath(prefix, knownPaths) {
 const TEST_FILE = /(^|\/)__tests__\/|\.(test|spec)\.[cm]?[jt]sx?$/;
 /** Module specifiers `import`/`export … from`, `import()`, `require()` and `jest.mock()` name. */
 const IMPORT_SPECIFIER = /\bfrom\s*["']([^"']+)["']|\bimport\s*["']([^"']+)["']|\b(?:import|require|jest\.mock|jest\.requireActual)\s*\(\s*["']([^"']+)["']/g;
+const WEB_ROOT = "apps/web/";
 const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
 /**
  * The record-style paths a relative specifier in `fromPath` can resolve to:
@@ -177,8 +187,10 @@ const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs"
  * swapped for its TypeScript source, and as a directory's `index.*`.
  */
 function relativeImportCandidates(fromPath, specifier) {
-    const parts = fromPath.split("/").slice(0, -1);
-    for (const segment of specifier.split("/")) {
+    // `@/x` is apps/web's `x` — its tsconfig `paths`; no other app declares one.
+    const alias = specifier.startsWith("@/") && fromPath.startsWith(WEB_ROOT);
+    const parts = alias ? ["apps", "web"] : fromPath.split("/").slice(0, -1);
+    for (const segment of (alias ? specifier.slice(2) : specifier).split("/")) {
         if (segment === "" || segment === ".")
             continue;
         if (segment === "..")
@@ -196,13 +208,24 @@ function relativeImportCandidates(fromPath, specifier) {
     out.push(...RESOLVE_EXTENSIONS.map((ext) => `${target}/index${ext}`));
     return out;
 }
-/** The files of `held` that `text`, the source of `fromPath`, imports by relative specifier. */
-function importedHeldFiles(fromPath, text, held) {
+/** Whether `specifier` names a site file: relative, or `@/` from an apps/web file. */
+function isLocal(fromPath, specifier) {
+    return specifier.startsWith(".") || (specifier.startsWith("@/") && fromPath.startsWith(WEB_ROOT));
+}
+/** The local module specifiers `text` names. */
+function localSpecifiers(fromPath, text) {
     const out = new Set();
     for (const match of text.matchAll(IMPORT_SPECIFIER)) {
         const specifier = match[1] ?? match[2] ?? match[3];
-        if (specifier === undefined || !specifier.startsWith("."))
-            continue;
+        if (specifier !== undefined && isLocal(fromPath, specifier))
+            out.add(specifier);
+    }
+    return [...out];
+}
+/** The files of `held` that `text`, the source of `fromPath`, imports by local specifier. */
+function importedHeldFiles(fromPath, text, held) {
+    const out = new Set();
+    for (const specifier of localSpecifiers(fromPath, text)) {
         for (const candidate of relativeImportCandidates(fromPath, specifier)) {
             if (held.has(candidate))
                 out.add(candidate);
@@ -210,6 +233,57 @@ function importedHeldFiles(fromPath, text, held) {
     }
     return [...out];
 }
+/** The `apps/web/messages/` catalogs next-intl loads by locale, never by import. */
+const MESSAGES_JSON = /^apps\/web\/messages\/(?:[^/]+\/)*[^/]+\.json$/;
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The site's messages catalog with every key the template's copy has and it
+ * lacks (#10173): the site's values always win, nothing is removed, and the
+ * keys it gains follow its own. A key that is an object on one side and a
+ * value on the other is a conflict, and nothing is merged.
+ */
+export function mergeMessagesAdditively(ours, theirs) {
+    let oursDoc;
+    let theirsDoc;
+    try {
+        oursDoc = JSON.parse(ours);
+        theirsDoc = JSON.parse(theirs);
+    }
+    catch (err) {
+        return { status: "invalid", reason: `not JSON: ${err.message}` };
+    }
+    if (!isPlainObject(oursDoc) || !isPlainObject(theirsDoc)) {
+        return { status: "invalid", reason: "the root is not an object" };
+    }
+    const conflicts = [];
+    let added = 0;
+    const walk = (o, t, at) => {
+        for (const [key, value] of Object.entries(t)) {
+            if (UNSAFE_KEYS.has(key))
+                continue; // never written through, so never a prototype change
+            const path = at === "" ? key : `${at}.${key}`;
+            if (!Object.prototype.hasOwnProperty.call(o, key)) {
+                o[key] = value;
+                added++;
+                continue;
+            }
+            const mine = o[key];
+            if (isPlainObject(mine) && isPlainObject(value))
+                walk(mine, value, path);
+            else if (isPlainObject(mine) || isPlainObject(value))
+                conflicts.push(path);
+        }
+    };
+    walk(oursDoc, theirsDoc, "");
+    if (conflicts.length > 0)
+        return { status: "conflict", keys: conflicts };
+    const indent = /\n(\t| +)"/.exec(ours)?.[1] ?? 2;
+    const text = JSON.stringify(oursDoc, null, indent) + (ours.endsWith("\n") ? "\n" : "");
+    return { status: "merged", text: added === 0 ? ours : text, added };
+}
 // ── The MCP move (#9567): a copied apps/mcp becomes the boot set ──────────
 const MCP_SERVER_PACKAGE = "@working-theory/mcp-server";
 const MCP_PACKAGE_JSON = "apps/mcp/package.json";
@@ -789,9 +863,14 @@ export async function updateSite(opts) {
     const recordPath = join(targetDir, TEMPLATE_RECORD_PATH);
     let record;
     let backfillPatternVersion;
+    // #10173 — a row at a path a later create-ailk no longer records (a
+    // generated file) is dropped and reported, never a refusal of the run.
+    const droppedRows = [];
     if (existsSync(recordPath)) {
         try {
-            record = parseTemplateRecord(readFileSync(recordPath, "utf8"));
+            record = parseTemplateRecord(readFileSync(recordPath, "utf8"), {
+                onUnrecordable: (key) => droppedRows.push(key),
+            });
         }
         catch (err) {
             throw new UpdateRefusedError(err.message);
@@ -1081,6 +1160,26 @@ export async function updateSite(opts) {
             nextFiles[path] = { sha256: newHash, version };
             merged.push(path);
         }
+        else if (mergeResult.status === "conflict" && MESSAGES_JSON.test(path)) {
+            // #10173 — a messages catalog takes the template's new keys and keeps
+            // every value the site has; only a key-level conflict is reviewed.
+            const additive = mergeMessagesAdditively(diskBytes.toString("utf8"), Buffer.from(newBytes).toString("utf8"));
+            if (additive.status === "conflict") {
+                review.push({
+                    path,
+                    reason: `conflicts with the template change ${rec.version} → ${version} at key ${additive.keys.join(", ")}`,
+                });
+            }
+            else if (additive.status === "invalid") {
+                review.push({ path, reason: `the additive pass could not run: ${additive.reason}` });
+            }
+            else {
+                if (additive.added > 0)
+                    writes.push({ path, bytes: Buffer.from(additive.text, "utf8") });
+                nextFiles[path] = { sha256: newHash, version };
+                merged.push(path);
+            }
+        }
         else if (mergeResult.status === "conflict") {
             review.push({
                 path,
@@ -1151,46 +1250,209 @@ export async function updateSite(opts) {
     // exercising the held file is enough. A held test-support file
     // (`__tests__/fixtures.ts`) holds the tests importing it in turn, until no
     // further test is held.
+    //
+    // #10173 — the same holds for every other template file this run would
+    // write: one importing a held file stays at the site's version (or, when
+    // new, is not added), so the written tree never imports an export the held
+    // file lacks. A written file whose relative import names a file the site
+    // will not have once the run lands is held too, under that missing path.
+    // Only the bytes being written are read for a non-test file: the site's
+    // own copy already compiles against what it has.
     const heldFiles = new Set([...review, ...skipped].map((row) => row.path));
+    // The files left alone outright, before any hold-back joins them.
+    const leftAlone = new Set(heldFiles);
+    const writtenBytes = new Map(writes.map((w) => [w.path, w.bytes]));
+    // The moves' removals (#9567, #9566) land too: never code that stays.
+    const deleting = new Set([...deletes, ...(mcpMove?.deletes ?? []), ...(apiMove?.deletes ?? [])]);
+    const adding = new Set(added);
     const heldBackByFile = new Map();
-    const heldTests = new Set();
-    const moving = [...updated, ...merged, ...added, ...removed, ...current]
-        .filter((path) => TEST_FILE.test(path))
+    const heldPaths = new Set();
+    const moving = [...new Set([...updated, ...merged, ...added, ...removed, ...current])].sort();
+    const isFileCache = new Map();
+    const isFileOnDisk = (path) => {
+        let hit = isFileCache.get(path);
+        if (hit === undefined) {
+            try {
+                hit = statSync(join(targetDir, ...path.split("/"))).isFile();
+            }
+            catch {
+                hit = false;
+            }
+            isFileCache.set(path, hit);
+        }
+        return hit;
+    };
+    // What the run rewrites after the record's writes, never from the template.
+    const rewrittenLater = new Set([
+        MODULE_FLAGS_PATH,
+        PAID_MCP_TOOLS_PATH,
+        ...(mcpMove?.seam !== undefined ? [MCP_SEAM_PATH] : []),
+    ]);
+    /** Whether `path` is a file once this run's writes and deletes, less the held ones, land. */
+    const presentAfter = (path) => {
+        if (heldPaths.has(path))
+            return isFileOnDisk(path);
+        if (adding.has(path) || rewrittenLater.has(path))
+            return true;
+        if (deleting.has(path))
+            return false;
+        return isFileOnDisk(path);
+    };
+    const sourcesOf = new Map();
+    for (const path of moving) {
+        const writing = writtenBytes.get(path);
+        const written = writing !== undefined ? writing.toString("utf8") : undefined;
+        const newBytes = newMap.get(path);
+        const newText = newBytes !== undefined ? Buffer.from(newBytes).toString("utf8") : undefined;
+        const all = [];
+        if (TEST_FILE.test(path)) {
+            const abs = join(targetDir, ...path.split("/"));
+            if (existsSync(abs))
+                all.push(readFileSync(abs, "utf8"));
+            if (newText !== undefined)
+                all.push(newText);
+            if (written !== undefined)
+                all.push(written);
+        }
+        else {
+            const text = written ?? newText;
+            if (text !== undefined)
+                all.push(text);
+        }
+        sourcesOf.set(path, { all, written });
+    }
+    const SOURCE_FILE = /\.[cm]?[jt]sx?$/;
+    const hold = (path, file, missing) => {
+        const entry = heldBackByFile.get(file) ?? { tests: [], importers: [], missing };
+        const list = TEST_FILE.test(path) ? entry.tests : entry.importers;
+        if (!list.includes(path))
+            list.push(path);
+        heldBackByFile.set(file, entry);
+    };
+    const importsCache = new Map();
+    const namedImportsAt = (path, text) => {
+        let hit = importsCache.get(path);
+        if (hit === undefined)
+            importsCache.set(path, (hit = namedImportsOf(text)));
+        return hit;
+    };
+    const textCache = new Map();
+    const diskText = (path) => {
+        if (!textCache.has(path)) {
+            textCache.set(path, isFileOnDisk(path) ? readFileSync(join(targetDir, ...path.split("/")), "utf8") : undefined);
+        }
+        return textCache.get(path);
+    };
+    // Every app source file this run does not write: the code that keeps the
+    // site's version and must still find what it imports.
+    const stayingFiles = [...listFilesUnder(targetDir, ["apps/web", "apps/api", "apps/mcp"])]
+        .filter((path) => !writtenBytes.has(path) && !deleting.has(path))
         .sort();
-    for (let grew = heldFiles.size > 0; grew;) {
+    let grew = true;
+    const holdPath = (path) => {
+        heldPaths.add(path);
+        heldFiles.add(path);
+        grew = true;
+    };
+    while (grew) {
         grew = false;
         for (const path of moving) {
-            if (heldTests.has(path))
+            if (heldPaths.has(path))
                 continue;
-            const sources = [];
-            const abs = join(targetDir, ...path.split("/"));
-            if (existsSync(abs))
-                sources.push(readFileSync(abs, "utf8"));
-            const newBytes = newMap.get(path);
-            if (newBytes !== undefined)
-                sources.push(Buffer.from(newBytes).toString("utf8"));
-            const imported = new Set(sources.flatMap((text) => importedHeldFiles(path, text, heldFiles)));
-            if (imported.size === 0)
+            const { all, written } = sourcesOf.get(path);
+            const imported = new Set(all.flatMap((text) => importedHeldFiles(path, text, heldFiles)));
+            const missing = new Set();
+            if (written !== undefined && !TEST_FILE.test(path)) {
+                for (const specifier of localSpecifiers(path, written)) {
+                    const candidates = relativeImportCandidates(path, specifier);
+                    if (candidates.some((c) => heldFiles.has(c) || presentAfter(c)))
+                        continue;
+                    // A dot-directory (`.source/`, `.next/`) is build output the site
+                    // generates, never a file update could have carried.
+                    if (/(^|\/)\.[^./][^/]*\//.test(candidates[0]))
+                        continue;
+                    missing.add(candidates[0]);
+                }
+            }
+            // A named import the file it resolves to — staying at the site's
+            // version — does not export (a regenerated nav-config, say).
+            const lacking = new Set();
+            if (written !== undefined) {
+                for (const { specifier, names } of namedImportsOf(written)) {
+                    if (!isLocal(path, specifier))
+                        continue;
+                    const target = relativeImportCandidates(path, specifier).find(isFileOnDisk);
+                    if (target === undefined || heldFiles.has(target) || rewrittenLater.has(target))
+                        continue;
+                    if (writtenBytes.has(target) && !heldPaths.has(target))
+                        continue;
+                    if (deleting.has(target))
+                        continue; // the missing check above owns it
+                    if (!SOURCE_FILE.test(target))
+                        continue;
+                    const text = diskText(target);
+                    if (text !== undefined && names.some((name) => !exportsName(text, name)))
+                        lacking.add(target);
+                }
+            }
+            if (imported.size === 0 && missing.size === 0 && lacking.size === 0)
+                continue;
+            holdPath(path);
+            for (const file of imported)
+                hold(path, file, false);
+            for (const file of missing)
+                hold(path, file, true);
+            for (const file of lacking)
+                hold(path, file, false);
+        }
+        // The reverse: a file staying at the site's version imports, by name,
+        // something the written copy of its target no longer exports.
+        for (const staying of [...stayingFiles, ...heldPaths]) {
+            const text = diskText(staying);
+            if (text === undefined)
+                continue;
+            // A file left alone keeps the code it was written against: every
+            // template file it imports stays with it, whatever that file exports.
+            if (leftAlone.has(staying)) {
+                for (const specifier of localSpecifiers(staying, text)) {
+                    const target = relativeImportCandidates(staying, specifier).find((c) => writtenBytes.has(c) && !heldPaths.has(c));
+                    if (target === undefined || !SOURCE_FILE.test(target))
+                        continue;
+                    holdPath(target);
+                    hold(target, staying, false);
+                }
                 continue;
-            heldTests.add(path);
-            heldFiles.add(path);
-            grew = true;
-            for (const file of imported) {
-                heldBackByFile.set(file, [...(heldBackByFile.get(file) ?? []), path]);
+            }
+            for (const { specifier, names } of namedImportsAt(staying, text)) {
+                if (!isLocal(staying, specifier))
+                    continue;
+                const target = relativeImportCandidates(staying, specifier).find((c) => writtenBytes.has(c) && !heldPaths.has(c));
+                if (target === undefined || !SOURCE_FILE.test(target))
+                    continue;
+                const next = writtenBytes.get(target).toString("utf8");
+                if (names.every((name) => exportsName(next, name)))
+                    continue;
+                holdPath(target);
+                hold(target, staying, false);
             }
         }
     }
-    for (const path of heldTests) {
+    for (const path of heldPaths) {
         const recorded = record.files[path];
         if (recorded !== undefined)
             nextFiles[path] = recorded;
         else
             delete nextFiles[path];
     }
-    const notHeld = (path) => !heldTests.has(path);
+    const notHeld = (path) => !heldPaths.has(path);
     const heldBack = [...heldBackByFile.entries()]
         .sort(([a], [b]) => a.localeCompare(b))
-        .map(([file, tests]) => ({ file, tests }));
+        .map(([file, { tests, importers, missing }]) => ({
+        file,
+        tests: tests.sort(),
+        ...(importers.length > 0 ? { importers: importers.sort() } : {}),
+        ...(missing ? { missing: true } : {}),
+    }));
     // ── Apply: writes and removals, then the record (D4 Order) ───────────
     // #9566 — the API move's removals first: a retired file at a boot-set
     // path is overwritten by the write that follows, never deleted after it.
@@ -1216,7 +1478,9 @@ export async function updateSite(opts) {
         removed: removed.filter(notHeld),
         current: current.filter(notHeld),
     };
-    const recordChanged = backfilled !== undefined || Object.values(moved).some((paths) => paths.length > 0);
+    const recordChanged = backfilled !== undefined ||
+        droppedRows.length > 0 ||
+        Object.values(moved).some((paths) => paths.length > 0);
     if (recordChanged) {
         writeFileSync(recordPath, serializeTemplateRecord({ schema: 1, projectName: record.projectName, files: nextFiles }));
     }
@@ -1262,6 +1526,35 @@ export async function updateSite(opts) {
         writeFileSync(join(targetDir, ...WEB_PACKAGE_JSON.split("/")), webPackageJson);
         moved.updated.push(WEB_PACKAGE_JSON);
     }
+    // #10172 — the env vars the written files read get an env_contract row
+    // when the site's project.yaml has a block and no row for them, so the
+    // code update brings never fails `env:declared`. Rows are appended, never
+    // edited; a hub with no block is not checked and gains none.
+    const envRowsAdded = [];
+    const projectYamlPath = join(targetDir, "project.yaml");
+    const writtenPaths = new Set(writes.map((w) => w.path).filter(notHeld));
+    if (writtenPaths.size > 0 && existsSync(projectYamlPath)) {
+        const yamlText = readFileSync(projectYamlPath, "utf8");
+        const topology = readManifestTopology(targetDir);
+        if (readEnvContract(yamlText).present && "topology" in topology) {
+            try {
+                const plan = planEnvRows(targetDir, yamlText, {
+                    topology: topology.topology,
+                    catalog: ENV_CATALOG,
+                    onlyFiles: writtenPaths,
+                });
+                if (plan.added.length > 0) {
+                    writeFileSync(projectYamlPath, plan.text);
+                    envRowsAdded.push(...plan.added);
+                }
+            }
+            catch (err) {
+                if (!(err instanceof EnvContractError))
+                    throw err;
+                review.push({ path: "project.yaml", reason: `no env_contract rows added: ${err.message}` });
+            }
+        }
+    }
     // #7495 D6 — the page body owns its H1: give every heading-less mdx-body
     // page its title and description, read the rule after the writes so a
     // route this run added counts. Its rows join `review` after `heldFiles`
@@ -1286,6 +1579,8 @@ export async function updateSite(opts) {
         heldBack,
         headingsAdded: headings.written.map(sitePath),
         ...(backfilled !== undefined ? { backfilled } : {}),
+        ...(envRowsAdded.length > 0 ? { envRowsAdded } : {}),
+        ...(droppedRows.length > 0 ? { droppedRows: droppedRows.sort() } : {}),
     };
 }
 /** The printed report (D9): one section per non-empty list, in order. */
@@ -1312,9 +1607,18 @@ export function formatUpdateReport(result) {
         lines.push(`Needs review (${result.review.length}):`);
         lines.push(...result.review.map((row) => `  ${row.path} — ${row.reason}`));
     }
-    for (const { file, tests } of result.heldBack) {
-        lines.push(`Held back with ${file} (${tests.length}):`);
-        lines.push(...tests.map((path) => `  ${path}`));
+    for (const { file, tests, importers = [], missing } of result.heldBack) {
+        const held = [...tests, ...importers].sort();
+        lines.push(`Held back with ${file}${missing ? " (not in this site)" : ""} (${held.length}):`);
+        lines.push(...held.map((path) => `  ${path}`));
+    }
+    if (result.envRowsAdded !== undefined) {
+        lines.push(`project.yaml env_contract rows added (${result.envRowsAdded.length}):`);
+        lines.push(...result.envRowsAdded.map((name) => `  ${name}`));
+    }
+    if (result.droppedRows !== undefined) {
+        lines.push(`Dropped from ${TEMPLATE_RECORD_PATH}, no longer recorded (${result.droppedRows.length}):`);
+        lines.push(...result.droppedRows.map((path) => `  ${path}`));
     }
     if (result.skipped.length > 0) {
         lines.push(`Skipped (${result.skipped.length}):`);
@@ -1328,7 +1632,9 @@ export function formatUpdateReport(result) {
         result.current.length === 0 &&
         result.headingsAdded.length === 0 &&
         result.review.length === 0 &&
-        result.skipped.length === 0;
+        result.skipped.length === 0 &&
+        result.envRowsAdded === undefined &&
+        result.droppedRows === undefined;
     if (nothingHappened) {
         return `[create-ailk] Already up to date (create-ailk ${result.version}).\n`;
     }
@@ -1359,11 +1665,18 @@ untouched apps/web, apps/api or apps/mcp file, or a root tools/jest file the
 app jest configs require, whose template copy changed is overwritten. An
 edited file whose template copy also changed is three-way merged with
 \`git\` (git must be on PATH); a conflict leaves the file alone and is
-listed under "Needs review". Every template test that imports a file
-left under "Needs review" or "Skipped" (by a relative import) is held at the
-site's version with it, its record entry is not advanced, and it is listed
-under "Held back with <file>" — reconcile the file, then run update again to
-bring its tests forward. Every other file in the run still updates.
+listed under "Needs review"; an apps/web/messages catalog instead gains the
+template's new keys and keeps every value it has, and is reviewed only when a
+key is an object on one side and a value on the other. Every template file,
+test or not, that imports a file left under "Needs review" or "Skipped" (by a
+relative or @/ import, transitively) is held at the site's version with it,
+its record entry is not advanced, and it is listed under "Held back with
+<file>" — reconcile the file, then run update again to bring it forward. A
+written file whose import names a file the site will not have is held the
+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 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.28.0",
+  "version": "0.29.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.50.0",
-    "@working-theory/templates": "0.50.0"
+    "@working-theory/schema": "0.51.0",
+    "@working-theory/templates": "0.51.0"
   },
   "repository": {
     "type": "git",

package/templates/apps/api/CLAUDE.md

@@ -119,7 +119,7 @@ Routes are versioned under `/v1/*`:
 
 **`AILK_OPERATOR_EMAIL` is REQUIRED for a `workspace`-module deployment** (#5515 item 1), exactly as it already is for the review dashboard. On a build with the `workspace` module and WITHOUT `multi-tenant`, `server.ts`'s `tenantPreHandlerForBuild()` selects the base guard (`src/middleware/default-tenant.ts` → `resolveDefaultTenantForOperator`), which fails CLOSED when the pin is unset: every `/v1/workspaces/*` route answers 403 to everyone — so the module's Admin pages (`apps/web/app/[locale]/(authed)/admin*`, renamed from `workspace` by #5637) render their shared `ForbiddenState` — and — the reason this matters — the TOFU operator bind (`services/default-tenant.ts#bindOperatorMembership`, #3631) is never reached, so the first account to load the settings page cannot seat ITSELF as the sole owner off a plain GET. With `multi-tenant` present, a session that has activated a workspace resolves from it and its Membership, unchanged; a session with NO active workspace (every `apps/web` request) goes through the same `resolveDefaultTenantForOperator`, so on a one-workspace deployment the pin is REQUIRED there too — unset, nobody is seated and those requests answer 403 (#7523). The `kind: "all"` waitlist read likewise needs the caller to BE the pin, not merely a sentinel-org owner. `.env.example` § Single-tenant operator pin carries the operator-facing copy; `src/middleware/__tests__/default-tenant.test.ts` § "#5515 item 1" is the objective record.
 
-The workspace site-config routes are **identity-bound tenant routes** (guarded by the tenant preHandler; the write scope is the caller's active workspace, never a body-supplied id). Like the sibling `/v1/workspaces/*` routes they have **no anonymous MCP twin** — the OSS MCP surface is identity-blind (`apps/mcp/CLAUDE.md`), so the "1:1 MCP tool" rule above does not apply to them; the tenant-scoped authed MCP surface is tracked in #3591. The `/v1/billing/*` and `/v1/waitlist-experiments/*` routes are the same shape — identity-bound tenant routes, admin/settings-facing rather than agent-facing, no MCP twin.
+The workspace site-config routes are **identity-bound tenant routes** (guarded by the tenant preHandler; the scope is the workspace the request names — the path's `:workspaceId`, or on a route with none the required `x-ailk-workspace-scope` header — checked against the caller's Membership on every request, never a body-supplied id and never the session's old active-workspace pointer, #10165). Like the sibling `/v1/workspaces/*` routes they have **no anonymous MCP twin** — the OSS MCP surface is identity-blind (`apps/mcp/CLAUDE.md`), so the "1:1 MCP tool" rule above does not apply to them; the tenant-scoped authed MCP surface is tracked in #3591. The `/v1/billing/*` and `/v1/waitlist-experiments/*` routes are the same shape — identity-bound tenant routes, admin/settings-facing rather than agent-facing, no MCP twin.
 
 AEO Layer 1 scoring runs both ways: locally as a CLI command (`ailk audit`, filesystem content-root input) AND behind the anonymous `/v1/aeo/score` HTTP endpoint above (external-URL input, #4666) — the CLI's content-root audit and the route's crawler-fed score are two different input paths over the same underlying scorer, not a contradiction.
 

package/templates/apps/mcp/CLAUDE.md

@@ -124,16 +124,18 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
 **Maintenance (2):** `audit`, `create_project` (stdio only, #9965 D13)
 **Flow (2):** `get_flow`, `submit_flow_step` — module-gated (`module: "signal-collectors"`, D-48, #5366) and licence-feature-tagged (`feature: "flows-deliverables"`, #7136): identity-blind like every tool in this list, registered only when the signal-collectors module is present, and gated on the deployment's `flows-deliverables` licence feature under `MCP_FEATURE_GATE_MODE`, the same shape Booking below has. `submit_flow_step` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP`, default 50 — #8071)
 **Booking (4):** `list_availability`, `get_event_meta`, `list_meetings`, `create_booking` — module-gated (`module: "scheduling"`) and licence-feature-tagged (`feature: "scheduling"`, #7136), gated on the deployment's `scheduling` licence feature under `MCP_FEATURE_GATE_MODE`. `create_booking` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_CREATE_BOOKING_DAILY_CAP`, default 20, and an `attendee.email` format check — #8071). `list_meetings` (#8843 D5) twins `GET /v1/schedule/meetings`: it takes no argument and returns the site's Live meetings — slug, visibility, position and whether each can be booked, plus a bookable one's calLink, title, length, description and price; `private` means unlisted, not secret
+**Redirect (1):** `get_redirect` (#10202 D8) — module-gated (`module: "content-write"`) and licence-feature-tagged (`feature: "workspace"`, the content-write claim), gated on the deployment's `workspace` licence feature under `MCP_FEATURE_GATE_MODE`. It twins `GET /v1/redirects`: given an old site path (and an optional locale) it returns where the site permanently redirects it — `{ from, to, permanent: true }` — or the route's not-found body. Its handler rides `@working-theory/mcp-workspace`'s anonymous `tools` (`redirect.ts`), the pack the `workspace` and `multi-tenant` modules carry, and calls the module-level `apiClient` with no agent key
 
-### Why the parity test counts 21 and a keyless server registers 19 (20 over stdio once Free is released)
+### Why the parity test counts 22 and a keyless server registers 20 (21 over stdio once Free is released)
 
-- **21 in the `TOOLS` array / parity test**: the `TOOLS` array in
-  `packages/metadata/src/mcp-tool-catalog.ts` defines 21 anonymous tools; the
-  parity test counts that full array. It also holds the thirty-one signed-in
-  workspace tools (#3591), which no anonymous view returns — see § The
+- **22 in the `TOOLS` array / parity test**: the `TOOLS` array in
+  `packages/metadata/src/mcp-tool-catalog.ts` defines 22 anonymous tools; the
+  parity test counts that full array. It also holds the thirty-three signed-in
+  workspace tools (#3591; the content-suggestion pair `draft_page_suggestions`
+  and `decide_page_suggestion` since #10218), which no anonymous view returns — see § The
   signed-in workspace surface below.
-- **19 registered on a KEYLESS deployment, 20 on a commerce-claimed one,
-  while the Free level is held or over HTTP — 20 and 21 over stdio once it is
+- **20 registered on a KEYLESS deployment, 21 on a commerce-claimed one,
+  while the Free level is held or over HTTP — 21 and 22 over stdio once it is
   released** (#5971, #9534, #9965 D13): `createMcpServer` (`apps/mcp/src/server.ts`) registers
   `getMcpToolRegistrations()` minus the topology seam's `UNSERVED_MCP_TOOLS`,
   minus `create_project` while create-ailk's `release-scope.json` holds
@@ -143,16 +145,16 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
   `addon`-tagged tool whose claim this deployment does not hold.
   `start_purchase` carries `addon: "commerce"`, so it is the one entry whose
   presence depends on the licence — one fewer without the claim.
-- **19 free anonymous tools while Free is held or over HTTP (20 over stdio once released)**: since #5853 retired the three content-write
+- **20 anonymous tools while Free is held or over HTTP (21 over stdio once released)**: since #5853 retired the three content-write
   tools, every registered tool remains anonymous — call-time gating checks a
-  licence claim, never an identity. The six carrying `tier: "pro"`
+  licence claim, never an identity. The seven carrying `tier: "pro"`
   (`get_flow`, `submit_flow_step`, `list_availability`, `get_event_meta`,
-  `list_meetings`, `create_booking`) are gated at REGISTRATION **and at call time** (#7315):
+  `list_meetings`, `create_booking`, `get_redirect`) are gated at REGISTRATION **and at call time** (#7315):
   each needs its module, and each catalog row names the licence `feature:`
   that entitles it. `start_purchase` is gated at call time by both this
   server-wide gate and its own Gate 2 in `tools/purchase.ts`.
   `MCP_FEATURE_GATE_MODE` (`packages/metadata`) decides what an unheld
-  feature does. In `"warn"` mode (this release) the six register on module
+  feature does. In `"warn"` mode (this release) the seven register on module
   presence alone, and the boot (`bootMcp()`) logs one warning (stderr) per tool
   served without its feature. In `"refuse"` mode (the next release) they
   also need the deployment's licence to hold the feature, and
@@ -283,7 +285,9 @@ Example (lead routing):
 - Don't add a tool without the matching `apps/api` endpoint.
 - Don't put business logic in tool handlers — they're adapters.
 
-Last updated: 2026-10-26 — #9965 (D12, D13): `create_project` is served over stdio only — the HTTP transport, the default, never registers it, and the web manifest always drops it — and `trustOneHop` trusts its hop only on Vercel — verified against `packages/mcp-server/src/{server,run,serverless-app}.ts` and `apps/web/app/.well-known/mcp.json/route.ts`.
+Last updated: 2026-10-29 — #10202 (D8): `get_redirect` (`mcp-workspace`'s `redirect.ts`, the pack's first anonymous handler) twins `GET /v1/redirects` under `module: "content-write"` and `feature: "workspace"` — 22 in `TOOLS`, 20 registered keyless and 21 commerce-claimed while Free is held, seven `tier: "pro"` — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts` and `tests/parity/api-parity/kinds/site.ts`.
+
+Prior: 2026-10-26 — #9965 (D12, D13): `create_project` is served over stdio only — the HTTP transport, the default, never registers it, and the web manifest always drops it — and `trustOneHop` trusts its hop only on Vercel — verified against `packages/mcp-server/src/{server,run,serverless-app}.ts` and `apps/web/app/.well-known/mcp.json/route.ts`.
 
 Prior: 2026-10-24 — #9749: `get_slack_connection_status` (`mcp-workspace`'s `slack_connection.ts`) and `get_prospect_channel_settings` / `set_prospect_channel_settings` (`mcp-scheduling`'s `prospect_channel_settings.ts`, the first signed-in handlers outside `mcp-workspace`) twin the Slack status read and the prospect-channel settings pair — the signed-in workspace surface is thirty-one tools — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts`, `packages-paid/mcp-scheduling/src/index.ts` and `tests/parity/api-parity/kinds/site.ts`.