create-ailk 0.8.0 → 0.10.0

package/dist/claude-md.js

@@ -0,0 +1,334 @@
+/**
+ * The scaffold's root `CLAUDE.md` as marked, self-hashing regions (#6904).
+ *
+ * A rendered `CLAUDE.md` is a run of template-owned regions, each opened by
+ * `<!-- ailk:template id="<id>" sha256="<hex>" -->` and closed by
+ * `<!-- /ailk:template id="<id>" -->`, followed by one `<!-- ailk:site -->`
+ * line that opens the site-owned section running to end of file (spec D1).
+ * Each begin marker records the SHA-256 of its own body (D2), so the drift
+ * check needs only the file.
+ *
+ * This is the core `--sync-claude-md` (`syncClaudeMdSync`, programmatic.ts)
+ * and the tests use. The scaffold's own drift check,
+ * `template-overlay/tools/check-claude-md.ts`, reimplements `findDrift` +
+ * `formatDrift` because a scaffold does not carry this source; the
+ * `claude-md-sync` suite holds the two to identical verdicts.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { buildScaffoldMarkers } from "./copy.js";
+import { substituteMarkers } from "./substitute.js";
+/** The drift check a scaffold ships (`template-overlay/tools/`). */
+export const CLAUDE_MD_CHECK_PATH = "tools/check-claude-md.ts";
+/**
+ * SHA-256 of every `templates/CLAUDE.md` a published create-ailk shipped
+ * before markers existed, with `{{PROJECT_NAME}}` unsubstituted (spec § 1.7,
+ * D4). An unmarked scaffold `CLAUDE.md` that hashes to one of these after
+ * undoing the name substitution was never edited by its owner.
+ */
+export const LEGACY_TEMPLATE_SHA256 = [
+    // 0.1.1 – 0.6.0
+    "a47dd9f391f6773f44aa7d7a42aa936bf22dd5fd5e8420f5001340239aea5aae",
+    // 0.6.1
+    "32c6e3278b5a4663562a2af307e56c3d9b6e74b4e34af02b033975eefe50b5db",
+    // 0.7.0, 0.8.0
+    "9ce9295be23c7b5e2f87357c78753e6f609a551bf74c8b5f5e463897f523ee89",
+];
+const BEGIN_RE = /^<!-- ailk:template id="([^"]*)"(?: sha256="([^"]*)")? -->$/;
+const END_RE = /^<!-- \/ailk:template id="([^"]*)" -->$/;
+const SITE_LINE = "<!-- ailk:site -->";
+const ID_RE = /^[a-z][a-z0-9-]*$/;
+const SHA_RE = /^[0-9a-f]{64}$/;
+/** SHA-256, lowercase hex, of a region body with every CRLF folded to LF (D2). */
+export function hashBody(body) {
+    return createHash("sha256").update(body.replace(/\r\n/g, "\n"), "utf8").digest("hex");
+}
+/** Parse a `CLAUDE.md` against the D1 grammar. Never throws. */
+export function parseClaudeMd(text) {
+    const regions = [];
+    const faults = [];
+    const seen = new Set();
+    let open;
+    let siteStart;
+    let marked = false;
+    let pos = 0;
+    while (pos < text.length) {
+        const nl = text.indexOf("\n", pos);
+        const next = nl === -1 ? text.length : nl + 1;
+        const line = text.slice(pos, nl === -1 ? text.length : nl).replace(/\r$/, "");
+        if (line === SITE_LINE) {
+            marked = true;
+            siteStart = pos;
+            break;
+        }
+        const begin = BEGIN_RE.exec(line);
+        const end = END_RE.exec(line);
+        if (begin) {
+            marked = true;
+            const id = begin[1] ?? "";
+            const sha = begin[2];
+            if (!ID_RE.test(id))
+                faults.push(`invalid section id "${id}"`);
+            if (sha !== undefined && !SHA_RE.test(sha))
+                faults.push(`section "${id}" has a malformed sha256`);
+            if (open) {
+                faults.push(`nested region: section "${id}" opens inside section "${open.id}"`);
+            }
+            else {
+                if (seen.has(id))
+                    faults.push(`duplicate section id "${id}"`);
+                seen.add(id);
+                open = { id, sha256: sha, start: pos, bodyStart: next };
+            }
+        }
+        else if (end) {
+            marked = true;
+            const id = end[1] ?? "";
+            if (!open) {
+                faults.push(`unbalanced marker: end of section "${id}" has no begin marker`);
+            }
+            else if (open.id !== id) {
+                faults.push(`unbalanced marker: section "${open.id}" is closed by an end marker for "${id}"`);
+                open = undefined;
+            }
+            else {
+                regions.push({
+                    id,
+                    sha256: open.sha256,
+                    start: open.start,
+                    end: next,
+                    body: text.slice(open.bodyStart, pos),
+                });
+                open = undefined;
+            }
+        }
+        else if (/^<!-- \/?ailk:template\b/.test(line)) {
+            marked = true;
+            faults.push(`malformed marker line: ${line}`);
+        }
+        pos = next;
+    }
+    if (open)
+        faults.push(`unbalanced marker: section "${open.id}" has no end marker`);
+    if (marked && siteStart === undefined)
+        faults.push("no ailk:site marker");
+    return { regions, siteStart, faults, marked };
+}
+/**
+ * Render the committed template for a project (D2): substitute the scaffold
+ * markers, then stamp each begin marker with its body's hash. LF output.
+ *
+ * @throws Error when the template is malformed or a begin marker already
+ *   carries a hash — a hash is never committed by hand.
+ */
+export function renderClaudeMd(templateText, projectName) {
+    const text = substituteMarkers(templateText.replace(/\r\n/g, "\n"), buildScaffoldMarkers(projectName));
+    const parsed = parseClaudeMd(text);
+    if (parsed.faults.length > 0) {
+        throw new Error(`templates/CLAUDE.md is malformed: ${parsed.faults.join("; ")}`);
+    }
+    let out = text;
+    for (const region of [...parsed.regions].reverse()) {
+        if (region.sha256 !== undefined) {
+            throw new Error(`templates/CLAUDE.md: section "${region.id}" carries a sha256 — the render stamps it`);
+        }
+        const lineEnd = out.indexOf("\n", region.start) + 1;
+        const stamped = `<!-- ailk:template id="${region.id}" sha256="${hashBody(region.body)}" -->\n`;
+        out = out.slice(0, region.start) + stamped + out.slice(lineEnd);
+    }
+    return out;
+}
+/**
+ * The drift verdict for a rendered file (D6). `undefined` = no file. The
+ * reference implementation `tools/check-claude-md.ts` is held to.
+ */
+export function findDrift(text) {
+    if (text === undefined)
+        return { state: "missing", edited: [], faults: [] };
+    const parsed = parseClaudeMd(text);
+    if (!parsed.marked)
+        return { state: "unmarked", edited: [], faults: [] };
+    const faults = [...parsed.faults];
+    const edited = [];
+    for (const region of parsed.regions) {
+        if (region.sha256 === undefined) {
+            faults.push(`begin marker of section "${region.id}" has no sha256`);
+        }
+        else if (SHA_RE.test(region.sha256) && region.sha256 !== hashBody(region.body)) {
+            // A malformed hash is already a parse fault, not an edit.
+            edited.push(region.id);
+        }
+    }
+    return { state: "marked", edited, faults };
+}
+/** The drift check's output lines; empty means the file passes. */
+export function formatDrift(drift) {
+    if (drift.state === "missing")
+        return ["CLAUDE.md: missing"];
+    if (drift.state === "unmarked") {
+        return ["CLAUDE.md: no ailk:template markers — run pnpm create ailk@latest --sync-claude-md"];
+    }
+    return [
+        ...drift.faults.map((f) => `CLAUDE.md: ${f}`),
+        ...drift.edited.map((id) => `CLAUDE.md: template section "${id}" was edited by hand — move your change to Site notes, then run pnpm create ailk@latest --sync-claude-md`),
+    ];
+}
+/**
+ * Rewrite a marked file's template-owned regions to a rendered template (D3).
+ * Every character outside a region — the gaps and the whole site section —
+ * is copied through unchanged, except the one blank line a retired region
+ * takes with it. Regions and inserted separators are written in the file's
+ * own line ending, so a CRLF checkout stays CRLF and syncs idempotently.
+ *
+ * @throws Error naming the fault when the file is structurally malformed.
+ */
+export function mergeClaudeMd(fileText, renderedText) {
+    const file = parseClaudeMd(fileText);
+    if (file.faults.length > 0 || file.siteStart === undefined) {
+        const faults = file.faults.length > 0 ? file.faults : ["no ailk:site marker"];
+        throw new Error(`CLAUDE.md: ${faults.join("; ")} — fix the markers by hand, then re-run --sync-claude-md`);
+    }
+    const first = file.regions[0];
+    const eol = first !== undefined && fileText[fileText.indexOf("\n", first.start) - 1] === "\r" ? "\r\n" : "\n";
+    const blank = (text) => text === "\n" || text === "\r\n";
+    const rendered = parseClaudeMd(renderedText);
+    const renderedById = new Map(rendered.regions.map((r) => [r.id, renderedText.slice(r.start, r.end).replace(/\n/g, eol)]));
+    const result = { text: "", updated: [], added: [], removed: [], overwritten: [] };
+    // The pre-site text as gap / region pieces, with each region already
+    // replaced (or dropped, when the template retired it).
+    const pieces = [];
+    let pos = 0;
+    let dropBlank = false;
+    for (const region of file.regions) {
+        const gap = fileText.slice(pos, region.start);
+        pieces.push({ text: dropBlank && blank(gap) ? "" : gap });
+        dropBlank = false;
+        pos = region.end;
+        const next = renderedById.get(region.id);
+        if (next === undefined) {
+            // A retired region takes the one blank line that separated it from its
+            // neighbour with it (the inverse of an insert), so the result matches
+            // a fresh render. Any other gap text is kept.
+            result.removed.push(region.id);
+            const kept = pieces.some((p) => p.region !== undefined);
+            const prev = pieces[pieces.length - 1];
+            if (kept && prev !== undefined && blank(prev.text))
+                prev.text = "";
+            else
+                dropBlank = !kept;
+            continue;
+        }
+        const current = fileText.slice(region.start, region.end);
+        if (region.sha256 !== hashBody(region.body))
+            result.overwritten.push(region.id);
+        if (next !== current)
+            result.updated.push(region.id);
+        pieces.push({ region: region.id, text: next });
+    }
+    const tail = fileText.slice(pos, file.siteStart);
+    pieces.push({ text: dropBlank && blank(tail) ? "" : tail });
+    // Insert each region the file lacks after its nearest preceding region
+    // in template order, one blank line apart (D3 step 5).
+    const order = rendered.regions.map((r) => r.id);
+    for (const [i, id] of order.entries()) {
+        if (pieces.some((p) => p.region === id))
+            continue;
+        const text = renderedById.get(id) ?? "";
+        const before = order
+            .slice(0, i)
+            .reverse()
+            .map((prev) => pieces.findIndex((p) => p.region === prev))
+            .find((idx) => idx !== -1);
+        if (before !== undefined) {
+            pieces.splice(before + 1, 0, { text: eol }, { region: id, text });
+        }
+        else {
+            const first = pieces.findIndex((p) => p.region !== undefined);
+            pieces.splice(first === -1 ? pieces.length : first, 0, { region: id, text }, { text: eol });
+        }
+        result.added.push(id);
+    }
+    result.text = pieces.map((p) => p.text).join("") + fileText.slice(file.siteStart);
+    return result;
+}
+/**
+ * True when an unmarked `CLAUDE.md` is a published template the owner never
+ * changed (D4): with some candidate project name un-substituted, it hashes to
+ * a `LEGACY_TEMPLATE_SHA256` entry. A miss is always safe — it refuses.
+ */
+export function isUneditedLegacy(text, names) {
+    const folded = text.replace(/\r\n/g, "\n");
+    return names
+        .filter((name) => name.length > 0)
+        .some((name) => {
+        const hash = createHash("sha256")
+            .update(folded.split(name).join("{{PROJECT_NAME}}"), "utf8")
+            .digest("hex");
+        return LEGACY_TEMPLATE_SHA256.includes(hash);
+    });
+}
+/**
+ * `--sync-claude-md` (D3): the `syncCatalogSync` shape — validate the target
+ * is an existing scaffold, write at most its `CLAUDE.md`, spawn nothing. An
+ * unmarked file is replaced only when it is an unedited published template
+ * (D4); anything else unmarked, or a structural fault, is refused with
+ * nothing written.
+ */
+export function syncClaudeMd(opts) {
+    const targetAbs = resolve(opts.targetDir);
+    if (!existsSync(targetAbs)) {
+        throw new Error(`sync target does not exist: ${targetAbs}. Point --sync-claude-md at an already-scaffolded repo.`);
+    }
+    if (!statSync(targetAbs).isDirectory()) {
+        throw new Error(`sync target is not a directory: ${targetAbs}`);
+    }
+    if (!existsSync(join(targetAbs, "architecture.yaml"))) {
+        throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
+    }
+    const pkg = readJsonObject(join(targetAbs, "package.json"));
+    const pkgName = typeof pkg?.["name"] === "string" ? pkg["name"] : "";
+    const scripts = pkg?.["scripts"];
+    const hasScript = typeof scripts === "object" && scripts !== null && "claude-md:check" in scripts;
+    const rendered = renderClaudeMd(opts.templateText, pkgName || basename(targetAbs));
+    const claudeMdPath = join(targetAbs, "CLAUDE.md");
+    const base = {
+        targetDir: targetAbs,
+        claudeMdPath,
+        updated: [],
+        added: [],
+        removed: [],
+        overwritten: [],
+        missingDriftCheck: !hasScript || !existsSync(join(targetAbs, CLAUDE_MD_CHECK_PATH)),
+    };
+    if (!existsSync(claudeMdPath)) {
+        writeFileSync(claudeMdPath, rendered);
+        return { ...base, action: "created" };
+    }
+    const current = readFileSync(claudeMdPath, "utf8");
+    if (!parseClaudeMd(current).marked) {
+        if (!isUneditedLegacy(current, [pkgName, basename(targetAbs)])) {
+            throw new Error(`${claudeMdPath} has no ailk:template markers and is not an unedited AI Launch Kit template, so --sync-claude-md will not overwrite it. ` +
+                "Copy anything you added out of CLAUDE.md, delete it, run --sync-claude-md again (it then writes a fresh file), and paste your notes under Site notes.");
+        }
+        writeFileSync(claudeMdPath, rendered);
+        return { ...base, action: "replaced-legacy" };
+    }
+    const { text, updated, added, removed, overwritten } = mergeClaudeMd(current, rendered);
+    const changed = text !== current;
+    if (changed)
+        writeFileSync(claudeMdPath, text);
+    return { ...base, action: changed ? "updated" : "unchanged", updated, added, removed, overwritten };
+}
+/** A JSON file's top-level object, or undefined when absent or unreadable. */
+function readJsonObject(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return typeof value === "object" && value !== null && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cli.js

@@ -5,10 +5,14 @@
  * Orchestration:
  *   0. on an `add-module` / `upgrade` subcommand: parse its own argv, run
  *      addModule(), print the report, exit (2 on a refusal it names)
+ *      on an `add-route` subcommand: add one route surface to an existing
+ *      site, print the report, exit (2 on a refusal it names) (#6947)
  *      on a `sync-routes` subcommand: parse its own argv, run syncRoutesSync(),
  *      print the report, exit (1 iff routes are missing in check mode)
  *      on a `license set` subcommand: write the key into the scaffold, push it
  *      to a linked Vercel project and redeploy, exit (#6683 D9)
+ *      on an `apply-design` subcommand: rewrite an existing site's look,
+ *      print the changed-file report, exit (#6819)
  *   1. parse argv → CliOptions
  *   2. on --help: print helpText, exit 0
  *   3. on --version: print version, exit 0
@@ -31,14 +35,19 @@
  * synchronous as before.
  */
 import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ADD_MODULE_HELP, AddModuleRefusedError, formatAddModuleReport, parseAddModuleArgs, } from "./add-module.js";
+import { ADD_ROUTE_HELP, AddRouteRefusedError, addRouteToScaffold, formatAddRouteReport, parseAddRouteArgs, } from "./add-route.js";
+import { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";
+import { CLAUDE_MD_CHECK_PATH } from "./claude-md.js";
+import { buildScaffoldMarkers } from "./copy.js";
+import { assertReleased } from "./lib/module-license-gate.js";
 import { FREE_PREREQUISITES_NOTE, LICENSED_PREREQUISITES_NOTE, isLicensedInstall, proCallout, } from "./lib/pro-callout.js";
 import { LICENSE_SET_HELP, runLicenseSet } from "./license-set.js";
 import { helpText, parseCliArgs, parseModules, resolveCliShape, toScaffoldOptions, } from "./parse-args.js";
-import { addModule, formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncRoutesSync, } from "./programmatic.js";
+import { addModule, formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, syncRoutesSync, } from "./programmatic.js";
 import { CORE_SURFACE_PATHS, SURFACE_ALIASES } from "./surfaces.js";
 import { SYNC_ROUTES_HELP, formatSyncRoutesReport, parseSyncRoutesArgs, } from "./sync-routes.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -47,6 +56,13 @@ function readPackageVersion() {
     const raw = readFileSync(PKG_JSON, "utf8");
     return JSON.parse(raw).version;
 }
+/** The workspace version map `build-templates` wrote; empty before the first build. */
+function readVersionMap() {
+    const path = resolve(PKG_ROOT, "versions.json");
+    if (!existsSync(path))
+        return {};
+    return JSON.parse(readFileSync(path, "utf8"));
+}
 /** Raw value of a `--flag <value>` or `--flag=<value>` argv entry, if present. */
 function readRawFlagValue(argv, flag) {
     for (let i = 0; i < argv.length; i++) {
@@ -115,6 +131,36 @@ async function main() {
         }
         process.exit(0);
     }
+    // `add-route <route> [dir]` (#6947): add a route surface the site was
+    // scaffolded without — add-module's route, architecture and nav steps with
+    // no licence and no bundle. A refusal it names (an unknown route, one a
+    // module delivers, an unreadable architecture.yaml) exits 2.
+    if (argv[0] === "add-route") {
+        const args = parseAddRouteArgs(argv.slice(1));
+        if (args.help || args.route === undefined) {
+            process.stdout.write(ADD_ROUTE_HELP);
+            process.exit(0);
+        }
+        const targetDir = resolve(args.target ?? process.cwd());
+        try {
+            const result = addRouteToScaffold({
+                targetDir,
+                route: args.route,
+                versions: readVersionMap(),
+                markers: buildScaffoldMarkers(basename(targetDir)),
+                templatesDir: resolve(PKG_ROOT, "templates"),
+                siteTemplatesDir: resolve(PKG_ROOT, "site-templates"),
+            });
+            process.stdout.write(formatAddRouteReport(result));
+        }
+        catch (err) {
+            if (!(err instanceof AddRouteRefusedError))
+                throw err;
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(err.exitCode);
+        }
+        process.exit(0);
+    }
     // Subcommand dispatch, ahead of the flag parser: `sync-routes` has its own
     // argv shape (#4986). Check mode exits 1 iff a template route is missing;
     // locally modified routes are reported but do not fail; --apply exits 0.
@@ -141,9 +187,38 @@ async function main() {
             readStdin: () => readFileSync(0, "utf8"),
         }));
     }
+    // `apply-design <name|path> [--target <dir>]` (#6819): rewrite an existing
+    // site's look only. Every refusal — the licence gate included — reaches
+    // the top-level catch, exit 1, as a scaffold-time design refusal does.
+    if (argv[0] === "apply-design") {
+        const args = parseApplyDesignArgs(argv.slice(1));
+        if (args.help || args.design === undefined) {
+            process.stdout.write(APPLY_DESIGN_HELP);
+            process.exit(0);
+        }
+        const result = await applyDesign({
+            design: args.design,
+            targetDir: args.target ?? process.cwd(),
+            designsDir: resolve(PKG_ROOT, "site-templates", "designs"),
+            siteTemplatesDir: resolve(PKG_ROOT, "site-templates"),
+            catalogPath: resolve(PKG_ROOT, "component-catalog.json"),
+        });
+        process.stdout.write(formatApplyDesignReport(result));
+        process.exit(0);
+    }
     // No silent default (#6754 D2/D3): a scaffold run naming neither --shape
     // nor --template asks for a shape on a terminal and is refused without one.
-    const opts = await resolveCliShape(parseCliArgs(argv, { interactive: process.stdin.isTTY === true }), { input: process.stdin, output: process.stdout });
+    // A --design or --modules outside the release scope is refused before that
+    // prompt asks anything (#6984); scaffold() checks the full run again.
+    const parsed = parseCliArgs(argv, { interactive: process.stdin.isTTY === true });
+    if (parsed.needsShapePrompt && !parsed.help && !parsed.version) {
+        assertReleased("designs", [parsed.design]);
+        assertReleased("modules", parsed.modules ?? []);
+    }
+    const opts = await resolveCliShape(parsed, {
+        input: process.stdin,
+        output: process.stdout,
+    });
     // Deprecation notice for a retired `--surfaces` id (#5563 D2). `surfaces.ts`
     // stays pure — `canonicalizeSurface` only resolves the alias — so this is
     // the one place that prints: compare the raw `--surfaces` argv token
@@ -168,6 +243,10 @@ async function main() {
             "\n" +
             ADD_MODULE_HELP +
             "\n" +
+            ADD_ROUTE_HELP +
+            "\n" +
+            APPLY_DESIGN_HELP +
+            "\n" +
             LICENSE_SET_HELP);
         process.exit(0);
     }
@@ -186,6 +265,26 @@ async function main() {
             `[create-ailk] Search it by CAPABILITY before building a component — it indexes every @working-theory/ui section, block and chrome component by what it does.\n`);
         process.exit(0);
     }
+    // CLAUDE.md sync mode (#6904 D3): rewrite the template-owned sections of an
+    // already-scaffolded repo's CLAUDE.md, then exit. One file, nothing else.
+    if (opts.syncClaudeMd) {
+        const r = syncClaudeMdSync({ targetDir: opts.target ?? process.cwd() });
+        const lines = [`[create-ailk] ${r.claudeMdPath}: ${r.action}`];
+        if (r.updated.length > 0)
+            lines.push(`[create-ailk] Updated sections: ${r.updated.join(", ")}`);
+        if (r.added.length > 0)
+            lines.push(`[create-ailk] Added sections: ${r.added.join(", ")}`);
+        if (r.removed.length > 0)
+            lines.push(`[create-ailk] Removed sections: ${r.removed.join(", ")}`);
+        if (r.overwritten.length > 0) {
+            lines.push(`[create-ailk] Replaced hand-edits in: ${r.overwritten.join(", ")} — the previous text is in git; move anything you need into Site notes.`);
+        }
+        if (r.missingDriftCheck) {
+            lines.push(`[create-ailk] This site has no CLAUDE.md drift check yet — copy ${CLAUDE_MD_CHECK_PATH} from a fresh scaffold and add "claude-md:check": "tsx ${CLAUDE_MD_CHECK_PATH}" to package.json scripts and preflight.`);
+        }
+        process.stdout.write(lines.join("\n") + "\n");
+        process.exit(0);
+    }
     // Sync mode: regenerate architecture.yaml in an already-scaffolded repo from
     // the module set, then exit — bypassing the scaffold / --install / next-steps
     // path entirely (spec #3561 D2). Data-only and non-destructive: only
@@ -284,7 +383,7 @@ async function main() {
     lines.push("");
     lines.push(`Route surfaces: ${CORE_SURFACE_PATHS.join(", ")}` +
         (surfaces.length > 0 ? ` + ${surfaces.join(", ")}` : ""));
-    lines.push("Add another with the `add-page` skill, or re-run with --surfaces <id>.");
+    lines.push("Add another with `create-ailk add-route <id>`, or re-run with --surfaces <id>.");
     // Only when asked for. The default scaffold's output is unchanged.
     if (opts.withCatalog) {
         lines.push("Component catalog: COMPONENT-CATALOG.md — search it by capability before building a component.");

package/dist/derive-architecture.js

@@ -130,12 +130,6 @@ function appToYaml(app) {
     }
     return m;
 }
-function packageToYaml(pkg) {
-    return {
-        description: pkg.description,
-        may_import_from: [...pkg.may_import_from].sort(),
-    };
-}
 function namespacesToYaml(ns) {
     const members = {};
     const sortedMembers = Object.entries(ns.members).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
@@ -170,37 +164,50 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
     const enabledSurfaces = surfaces === undefined
         ? resolveSurfaces(selected)
         : [...new Set(surfaces)].sort();
-    // apps/web (BASE) — may_import_from filled from the selected modules' webImports.
-    const webImports = sortedUnion(...slices.map((s) => s.webImports));
-    const apps = {
+    // The apps a scaffold ships on disk: web, api and mcp always (BASE), plus
+    // any a module brings (admin, with multi-tenant). A module's own `api`/`mcp`
+    // block replaces the base one. Canonical order web → api → mcp → admin.
+    // `admin` was `workspace` until #5637 renamed the owner surface; the slice's
+    // key was renamed there and this list was not, which dropped the Admin app
+    // from every derived architecture without failing anything but its own test.
+    const declared = {
         web: {
-            path: ARCHITECTURE_BASE.web.path,
-            description: ARCHITECTURE_BASE.web.description,
-            may_import_from: webImports,
-            may_not_import_from: [...ARCHITECTURE_BASE.web.may_not_import_from].sort(),
-            forbidden_patterns: ARCHITECTURE_BASE.web.forbidden_patterns.map(forbiddenToYaml),
+            ...ARCHITECTURE_BASE.web,
+            may_not_import_from: [...ARCHITECTURE_BASE.web.may_not_import_from],
+            may_import_from: sortedUnion(...slices.map((s) => s.webImports)),
         },
+        ...ARCHITECTURE_BASE.apps,
     };
-    // Additional apps (api, mcp, admin) in canonical order. `admin` was
-    // `workspace` until #5637 renamed the owner surface; the slice's key was
-    // renamed there and this list was not, which dropped the Admin app from
-    // every derived architecture without failing anything but its own test.
-    const extraApps = {};
     for (const s of slices)
-        Object.assign(extraApps, s.apps ?? {});
-    for (const key of ["api", "mcp", "admin"]) {
-        const a = extraApps[key];
-        if (a)
-            apps[key] = appToYaml(a);
-    }
-    // packages — sorted union across the selected slices.
-    const packagesRaw = {};
-    for (const s of slices)
-        Object.assign(packagesRaw, s.packages ?? {});
-    const packages = {};
-    const sortedPackages = Object.entries(packagesRaw).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
-    for (const [key, pkg] of sortedPackages) {
-        packages[key] = packageToYaml(pkg);
+        Object.assign(declared, s.apps ?? {});
+    // A scaffold carries no `packages/` tree — `@working-theory/*` install from
+    // npm — so an entry naming a monorepo folder is dropped rather than shipped
+    // as a rule the linter can never apply (#6940). What survives names a path
+    // the scaffold has: a declared app, or `database/`.
+    const roots = [
+        "database",
+        ...Object.values(declared).map((a) => a.path),
+    ];
+    const inScaffold = (p) => {
+        const path = p.endsWith("/**") ? p.slice(0, -3) : p;
+        return roots.some((r) => path === r || path.startsWith(`${r}/`));
+    };
+    const scoped = (p) => {
+        const { paths_excluded, ...rest } = p;
+        const kept = (paths_excluded ?? []).filter(inScaffold);
+        return kept.length > 0 ? { ...rest, paths_excluded: kept } : rest;
+    };
+    const apps = {};
+    for (const key of ["web", "api", "mcp", "admin"]) {
+        const a = declared[key];
+        if (!a)
+            continue;
+        apps[key] = appToYaml({
+            ...a,
+            may_import_from: a.may_import_from.filter(inScaffold),
+            may_not_import_from: a.may_not_import_from.filter(inScaffold),
+            forbidden_patterns: mergeForbidden([...ARCHITECTURE_BASE.appForbiddenPatterns], a.forbidden_patterns ?? []).map(scoped),
+        });
     }
     // namespaces — present only if a data-tier module contributes one.
     const nsSlice = slices.find((s) => s.namespaces)?.namespaces;
@@ -208,11 +215,10 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
     const extraForbidden = [];
     for (const s of slices)
         extraForbidden.push(...(s.forbiddenPatterns ?? []));
-    const forbidden = mergeForbidden([...ARCHITECTURE_BASE.forbiddenPatterns], extraForbidden);
+    const forbidden = mergeForbidden([...ARCHITECTURE_BASE.forbiddenPatterns], extraForbidden).map(scoped);
     const doc = {
         version: ARCHITECTURE_BASE.version,
         composition_model: {
-            reference: ARCHITECTURE_BASE.composition_model.reference,
             tiers: { ...ARCHITECTURE_BASE.composition_model.tiers },
         },
         surfaces: {
@@ -221,7 +227,6 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
             available: [...RECOGNIZED_SURFACES],
         },
         apps,
-        packages,
         ...(nsSlice ? { namespaces: namespacesToYaml(nsSlice) } : {}),
         forbidden_patterns: forbidden.map(forbiddenToYaml),
     };