create-ailk 0.30.0 → 0.32.0

package/dist/update.js

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

package/package.json

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

package/templates/.claude/cloudparity-repo-hooks.json

@@ -5,6 +5,11 @@
       "matcher": "Edit|Write",
       "command": "bash .claude/hooks/template-guard.sh"
     },
+    {
+      "event": "PreToolUse",
+      "matcher": "Edit|Write",
+      "command": "bash .claude/hooks/content-source-guard.sh"
+    },
     {
       "event": "PostToolUse",
       "matcher": "Edit|Write",

package/templates/.claude/hooks/content-source-guard.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# PreToolUse (Edit|Write): refuse a new page file on a site whose pages come
+# from the database. When CONTENT_ADAPTER=database — in the environment or in
+# one of Next's eight env files under apps/web/ — a call whose file_path is a
+# content/en/**/*.mdx that does not exist yet is refused (exit 2); the refusal
+# on stderr names the MCP tools that change a page instead. An existing page
+# file, any other path and a files site pass silently. The same rule and the
+# same message as tools/check-content-source.ts, which the preflight runs.
+# Pure bash and awk — nothing a scaffold has to install. Registered in
+# .claude/settings.json and declared in .claude/cloudparity-repo-hooks.json;
+# keep the two in step.
+export LC_ALL=C
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+IFS= read -r -d '' input
+[[ $input =~ \"file_path\"[[:space:]]*:[[:space:]]*\"([^\"\\]*)\" ]] || exit 0
+rel=${BASH_REMATCH[1]}
+case $rel in
+  "$PWD"/*) rel=${rel#"$PWD"/} ;;
+  /*) exit 0 ;;
+  ./*) rel=${rel#./} ;;
+esac
+case "/$rel/" in
+  */./*|*/../*|*//*) exit 0 ;;
+esac
+# `*` crosses `/` in a case pattern, so this is content/en/**/*.mdx.
+case $rel in
+  content/en/*.mdx) ;;
+  *) exit 0 ;;
+esac
+[ ! -e "$rel" ] || exit 0
+
+# The source rule: the environment, else the first env file whose last
+# CONTENT_ADAPTER assignment reads exactly `database`.
+source_name=
+if [ "${CONTENT_ADAPTER-}" = database ]; then
+  source_name="the environment"
+else
+  for name in .env .env.local .env.development .env.development.local \
+    .env.production .env.production.local .env.test .env.test.local; do
+    file=apps/web/$name
+    [ -f "$file" ] || continue
+    value=$(awk -v sq="'" '
+      /^[ \t]*(export[ \t]+)?CONTENT_ADAPTER[ \t]*=/ {
+        v = substr($0, index($0, "=") + 1)
+        n = length(v); quote = ""; cut = n
+        for (i = 1; i <= n; i++) {
+          c = substr(v, i, 1)
+          if (quote != "") { if (c == quote) quote = ""; continue }
+          if (c == "\"" || c == sq) { quote = c; continue }
+          if (c == "#" && i > 1 && substr(v, i - 1, 1) ~ /[ \t]/) { cut = i - 1; break }
+        }
+        v = substr(v, 1, cut)
+        sub(/^[ \t\r]+/, "", v); sub(/[ \t\r]+$/, "", v)
+        f = substr(v, 1, 1)
+        if (length(v) >= 2 && (f == "\"" || f == sq) && substr(v, length(v), 1) == f) {
+          v = substr(v, 2, length(v) - 2)
+        }
+        last = v
+      }
+      END { print last }
+    ' "$file")
+    if [ "$value" = database ]; then
+      source_name=$file
+      break
+    fi
+  done
+fi
+[ -n "$source_name" ] || exit 0
+
+printf '%s\n' >&2 \
+  "content-source: $rel is a page file, but this site's pages come from the database (CONTENT_ADAPTER=database in $source_name), so the site never reads it." \
+  "Change a page through the site's MCP tools instead: save_draft writes the draft and publish_draft publishes it; read_content returns the current page." \
+  "Pages and layout: words live in the database, layout stays in code (CLAUDE.md § Content)."
+exit 2

package/templates/.claude/settings.json

@@ -9,6 +9,15 @@
             "command": "bash .claude/hooks/template-guard.sh"
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/content-source-guard.sh"
+          }
+        ]
       }
     ],
     "PostToolUse": [

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

@@ -67,6 +67,10 @@ jobs:
       # A hand-edit inside a template-owned section of CLAUDE.md — the same
       # check `pnpm preflight` runs locally.
       - run: pnpm claude-md:check
+      # A new page file on a site whose pages come from the database (#10660).
+      - run: pnpm content-source:check
+      # A bare { on an mdx-body page, which fails the page or drops it (#10773).
+      - run: pnpm mdx-body:check
 
       - run: pnpm test
 

package/templates/CLAUDE.md

@@ -178,6 +178,11 @@ sections:
 Copy an existing file in the same folder, then change it. Text in `{braces}`
 is placeholder copy. Don't invent a `type` that `@working-theory/schema`
 doesn't export.
+
+Where a page lives depends on `CONTENT_ADAPTER` in `apps/web/.env.local`.
+Unset or `mdx` (the default): the file above. `database`: the database —
+change a page with the MCP tools `save_draft` then `publish_draft`; a new
+file under `content/en/` is refused by a hook and by `pnpm preflight`.
 <!-- /ailk:template id="content" -->
 
 <!-- ailk:template id="hard-floors" -->

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

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

package/templates/apps/mcp/CLAUDE.md

@@ -187,7 +187,7 @@ here. Spec: `docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md` D13–D16.
 - **apps/mcp checks only the key's shape.** The key is attached as the SDK's `req.auth` for that
   request alone and reaches a tool as `extra.authInfo.token`. apps/api is the one place it is
   checked, and its tenant guard and the caller's clamped role decide every answer.
-- **Thirty-eight tools, each a `twin`.** The catalog rows carry `surface: "workspace"`, `tier: "pro"`
+- **Thirty-nine tools, each a `twin`.** The catalog rows carry `surface: "workspace"`, `tier: "pro"`
   and `modulesAnyOf` (the modules any one of which registers the tool — its twin route's gate):
   `get_agent_context`, (#9683) `get_workspace_knowledge` — twin of `GET
   /v1/workspaces/:workspaceId/knowledge`: the business's shown offerings, live magnets, listed
@@ -209,7 +209,7 @@ here. Spec: `docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md` D13–D16.
   tools, `list_proposals` and `create_proposal`, twinning `GET`/`POST
   /v1/workspaces/:workspaceId/people/:personId/proposals` with the same grant: a proposal is
   private to one client, `payments` says whether approval leads to a Stripe page, and an agent's
-  price is refused `proposal_needs_person` (a person prices) — and (#9681) the four person-thread tools, `get_person_thread`, `set_person_thread_state`, `list_external_threads` and `add_external_thread`, twinning `GET`/`PATCH …/people/:personId/thread` and `GET`/`POST …/people/:personId/external-threads`: a client's whole thread page by page with its read/archived/resolved state, and pointers to email and Slack threads (never message text); reading needs the `people-read` grant, writing also `inbox-act`, and the client erasure route has no tool, by decision — and (#9682) the three person-memory tools, `list_person_memories`, `get_person_memory` and `propose_person_memory`, twinning `GET …/people/:personId/memories`, `GET …/memories/:path` and `POST …/memories`: an agent reads only live, unexpired memories (confirmed by a person, read within 180 days) and its proposal is never live — a new path is a draft, a confirmed one gets a pending version — needing the `people-read` or `people-memory-propose` grant to read and `people-memory-propose` to propose; the six person-only memory routes (edit, delete, confirm, redact, the versions list, restore) have no tool, by decision — and (#9749) `get_slack_connection_status`, twin of `GET /v1/workspaces/:workspaceId/slack-connection` (registered with `workspace`/`multi-tenant`, its route's `TENANCY` row: whether the Organization's Slack is connected, its team name and the date, never a credential; connect and disconnect are a person's act and have no tool, by decision), and `get_prospect_channel_settings` / `set_prospect_channel_settings`, twins of `GET`/`PUT …/prospect-channel` (registered with `scheduling`, their routes' module): the update replaces every field, needs the `meeting-types-manage` grant, is refused `slack_not_connected` while the Organization has no Slack connection, and an agent may change only `enabled`, `channelPrefix` and `archiveDays` — a change to `memberIds` or `welcomeTemplate` is refused `prospect_channel_needs_person` — and (#10218) the content-suggestion pair, `draft_page_suggestions` and `decide_page_suggestion` — and (#10336) the draft pair, `save_draft` and `read_report`, twinning `PATCH`/`GET …/content/:type/:slug` with the `content-edit` grant: `save_draft` takes the page's `content` whole as the PATCH body and its `version` as `X-Draft-Version`, writes a draft version that never goes live (no tool publishes; a person does), and answers 409 `conflict` with `currentVersion` when the draft moved; `read_report` returns the draft tip, the version a save must send, its open suggestions and the route's check report (`ready`, `needs repair` or `needs your words`), computed by the route and never by the tool — and (#10345) the knowledge-base pair, `read_knowledge` and `read_knowledge_doc`, twinning `GET …/knowledge-base` and `GET …/knowledge-base/:type/:slug` with no grant (`docs-read` is every role's): the docs a named member may read (`userId`, by default the agent's own person), at the lower of the agent's person's role and that member's, so naming someone only narrows; Live does not gate them and a disabled doc never appears; `filter: "workspace-memory"` answers the always-loaded set with its `totalTokens` and an 8000-token `warning`. No workspace tool sets Live, widens Audience or re-enables a doc — those routes answer an agent 403 `agent_refused`, which reaches a tool as the code and status. Each takes its route's params, query and body and returns the route's
+  price is refused `proposal_needs_person` (a person prices) — and (#9681) the four person-thread tools, `get_person_thread`, `set_person_thread_state`, `list_external_threads` and `add_external_thread`, twinning `GET`/`PATCH …/people/:personId/thread` and `GET`/`POST …/people/:personId/external-threads`: a client's whole thread page by page with its read/archived/resolved state, and pointers to email and Slack threads (never message text); reading needs the `people-read` grant, writing also `inbox-act`, and the client erasure route has no tool, by decision — and (#9682) the three person-memory tools, `list_person_memories`, `get_person_memory` and `propose_person_memory`, twinning `GET …/people/:personId/memories`, `GET …/memories/:path` and `POST …/memories`: an agent reads only live, unexpired memories (confirmed by a person, read within 180 days) and its proposal is never live — a new path is a draft, a confirmed one gets a pending version — needing the `people-read` or `people-memory-propose` grant to read and `people-memory-propose` to propose; the six person-only memory routes (edit, delete, confirm, redact, the versions list, restore) have no tool, by decision — and (#9749) `get_slack_connection_status`, twin of `GET /v1/workspaces/:workspaceId/slack-connection` (registered with `workspace`/`multi-tenant`, its route's `TENANCY` row: whether the Organization's Slack is connected, its team name and the date, never a credential; connect and disconnect are a person's act and have no tool, by decision), and `get_prospect_channel_settings` / `set_prospect_channel_settings`, twins of `GET`/`PUT …/prospect-channel` (registered with `scheduling`, their routes' module): the update replaces every field, needs the `meeting-types-manage` grant, is refused `slack_not_connected` while the Organization has no Slack connection, and an agent may change only `enabled`, `channelPrefix` and `archiveDays` — a change to `memberIds` or `welcomeTemplate` is refused `prospect_channel_needs_person` — and (#10218) the content-suggestion pair, `draft_page_suggestions` and `decide_page_suggestion` — and (#10336) the draft pair, `save_draft` and `read_report`, twinning `PATCH`/`GET …/content/:type/:slug` with the `content-edit` grant: `save_draft` takes the page's `content` whole as the PATCH body and its `version` as `X-Draft-Version`, writes a draft version that never goes live, and answers 409 `conflict` with `currentVersion` when the draft moved; `read_report` returns the draft tip, the version a save must send, its open suggestions and the route's check report (`ready`, `needs repair` or `needs your words`), computed by the route and never by the tool — and (#10661) `publish_draft`, twinning `POST …/content/:type/:slug/publish` with the `content-publish` grant: it publishes the draft tip (or a named version) exactly as a person holding that permission does, an agent without the grant is refused 403 `agent_refused` before anything is read, and it never widens Audience or re-enables a doc — and (#10345) the knowledge-base pair, `read_knowledge` and `read_knowledge_doc`, twinning `GET …/knowledge-base` and `GET …/knowledge-base/:type/:slug` with no grant (`docs-read` is every role's): the docs a named member may read (`userId`, by default the agent's own person), at the lower of the agent's person's role and that member's, so naming someone only narrows; Live does not gate them and a disabled doc never appears; `filter: "workspace-memory"` answers the always-loaded set with its `totalTokens` and an 8000-token `warning` — and (#10733) the five Language tools, `list_language_items`, `get_language_item`, `save_language_item`, `set_language_item_live` and `list_language_item_pages`, twinning `GET …/language`, `GET`/`PUT …/language/:kind/:slug`, `POST …/language/:kind/:slug/live` and `GET …/language/:kind/:slug/appears-on` (`mcp-workspace`'s `language.ts`): a workspace's glossary terms, FAQs and keywords; reading needs no grant, saving the `content-edit` grant (`version: null` creates, a tip id updates, 409 `slug_taken` / `stale` otherwise) and the Live switch `content-publish` with the `version` the person reviewed; tags are the hub's and never written by a tool; a keyword is vocabulary and is never shown to visitors; the delete route is a person's write (FEAT-101 Disable) and has no tool, by decision. No workspace tool widens Audience or re-enables a doc, and only `publish_draft` and `set_language_item_live`, with the `content-publish` grant, set Live — the access and Language delete routes answer every agent 403 `agent_refused`, and the publish and Live routes an agent without the grant, which reaches a tool as the code and status. Each takes its route's params, query and body and returns the route's
   `data`. They are in the parity guard like every other tool, and never in
   `/.well-known/mcp.json`.
 - **The OAuth bearer branch (#10391).** When `BETTER_AUTH_URL` (the site's origin, its OAuth
@@ -230,7 +230,7 @@ here. Spec: `docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md` D13–D16.
   a spoke has no authorization server, so it leaves `BETTER_AUTH_URL` unset. `/mcp` is untouched.
 - **Handlers forward, nothing else.** `workspace-server.ts` resolves each tool from
   `@working-theory/mcp-workspace`'s `workspaceTools` (`agent_context.ts`, `knowledge.ts`, `inbox_messages.ts`,
-  `inbox_submissions.ts`, `inbox_applications.ts`, `people_list.ts`, `person_notes.ts`, `person_thread.ts`, `person_memory.ts`, `proposals.ts`, `slack_connection.ts`, `page_suggestions.ts`, `content_draft.ts`, `knowledge_base.ts`, all
+  `inbox_submissions.ts`, `inbox_applications.ts`, `people_list.ts`, `person_notes.ts`, `person_thread.ts`, `person_memory.ts`, `proposals.ts`, `slack_connection.ts`, `page_suggestions.ts`, `content_draft.ts`, `content_publish.ts`, `knowledge_base.ts`, all
   `// oss: false`) and, for the two prospect-channel settings tools, `@working-theory/mcp-scheduling`'s
   `workspaceTools` (`prospect_channel_settings.ts`, #9749 — the pack the scheduling module carries, so a
   scheduling-only build serves what it lists), loaded through the site's generated registry, as `server.ts` resolves the
@@ -313,7 +313,11 @@ 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-31 — #10391 (D2–D6): `/mcp/workspace` gains the OAuth bearer branch beside the agent key — one `token-info` lookup per request, the `WWW-Authenticate` challenge and the RFC 9728 protected-resource document, on only with `BETTER_AUTH_URL` and `MCP_PUBLIC_HTTP_URL` — verified against `packages/mcp-server/src/{http-transport,oauth-bearer}.ts`.
+Last updated: 2026-11-02 — #10733 (D7, D8): the five Language twins (`mcp-workspace`'s `language.ts`) twin the Language collection's list, read, save, Live and appears-on routes; the person-only delete has no tool — the signed-in workspace surface gains five tools — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts`, `packages-paid/api-workspace/src/routes/workspaces/language.ts` and `tests/parity/api-parity/kinds/site.ts`.
+
+Prior: 2026-11-02 — #10661 (D1, D5–D8): `publish_draft` (`mcp-workspace`'s `content_publish.ts`) twins the publish route for an agent holding `content-publish`, whose blanket agent refusal narrows to agents without the grant — the signed-in workspace surface is thirty-nine tools — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts`, `packages-paid/api-content-write/src/routes/workspaces/content.ts` and `tests/parity/api-parity/kinds/site.ts`.
+
+Prior: 2026-10-31 — #10391 (D2–D6): `/mcp/workspace` gains the OAuth bearer branch beside the agent key — one `token-info` lookup per request, the `WWW-Authenticate` challenge and the RFC 9728 protected-resource document, on only with `BETTER_AUTH_URL` and `MCP_PUBLIC_HTTP_URL` — verified against `packages/mcp-server/src/{http-transport,oauth-bearer}.ts`.
 
 Prior: 2026-10-31 — #10345 (D9, D12): `read_knowledge` and `read_knowledge_doc` (`mcp-workspace`'s `knowledge_base.ts`) twin the per-user knowledge-base read — the signed-in workspace surface is thirty-seven tools — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts` and `tests/parity/api-parity/kinds/site.ts`.
 

package/templates/apps/web/.env.example

@@ -17,8 +17,10 @@ CONTENT_ADAPTER=mdx
 # Override the on-disk content root. Defaults to <repo-root>/content.
 # AILK_CONTENT_ROOT=
 
-# The shared secret /api/revalidate verifies apps/api's publish webhook
-# against — the SAME value as the API's CONTENT_REVALIDATE_SECRET (#5877).
+# The secret /api/revalidate verifies apps/api's publish webhook against
+# (#5877). On a site a hub serves (a spoke), the value `spokes revalidate-url`
+# printed for it — NEVER the hub's own secret (#10593). Otherwise, the SAME
+# value as the API's CONTENT_REVALIDATE_SECRET.
 # Needed when CONTENT_ADAPTER=database. Unset means the route returns 503 and
 # the site is not push-revalidated: a publish changes nothing user-visible
 # until a rebuild.

package/templates/apps/web/CLAUDE.md

@@ -43,7 +43,7 @@ Raw HTML is allowed only when no `@working-theory/ui` component fits. Flag it in
 - Animations: only `transform` and `opacity`. Never `transition-all`.
 - Every interactive element needs hover, focus-visible, and active states.
 
-The four widths above are the responsive contract. Brand reference files (logos, photos, colour and type notes) live in `brand_assets/` at the repo root; the site's own brand colours and fonts are set in `content/_site.mdx` under `brand.colors` and `brand.fonts`. The signed-out header button is set there too, as `header.cta` (`label`, `href`), with `header.signIn: link | hidden` choosing whether Sign in stays beside it as a text link — never by editing `app/[locale]/layout.tsx`. Each page's chrome is set there too (#10049, resolved by `lib/page-chrome.ts`): `header.style` (`full | bare | none`), `footer.style` (`columns | centered | closing | none`), `layout` (`deck | default`, the home's) and one `{ header, footer }` key per route family (`blog`, `docs`, `services`, …), with a page's own `header:` / `footer:` / `layout:` frontmatter winning over all of them.
+The four widths above are the responsive contract. Brand reference files (logos, photos, colour and type notes) live in `brand_assets/` at the repo root; the site's own brand colours and fonts are set in `content/_site.mdx` under `brand.colors` and `brand.fonts`. The signed-out header button is set there too, as `header.cta` (`label`, `href`), with `header.signIn: link | hidden` choosing whether Sign in stays beside it as a text link — never by editing `app/[locale]/layout.tsx`. Each page's chrome is set there too (#10049, resolved by `lib/page-chrome.ts`): `header.style` (`full | bare | none`), `footer.style` (`columns | centered | closing | none`), `layout` (`deck | default`, the home's) and one `{ header, footer }` key per route family (`blog`, `docs`, `services`, …), with a page's own `header:` / `footer:` / `layout:` frontmatter winning over all of them. The closing footer alone also reads three site-level keys (#10550): `footer.locality` (the line above the email, winning over the identity's address), `footer.actions` (one or two `{ label, href }` site paths — the primary, then the secondary — in place of the auth links) and `footer.legalBar` (off by default: `true` moves the legal line into a full-width bottom bar, on the deck's closing slide its bottom edge). The cookie notice's look is set there too (#10555, #10721): `consent.appearance` is `compact` (the floating card, bottom-left) or `hairline` (the full-width band on the page ground); absent, it follows the design's `chromeStyle` — the band under `minimal`, else the card. Only the band waits for the minimal deck home's first slide to leave view (#7782); the card shows on load on every page.
 
 ## Local dev
 
@@ -277,8 +277,8 @@ embedding for it is behind the hero CTA's lightbox gate
 
 The workspace's **Newsletter magnet** (#8847) — seeded live at slug
 `newsletter` in every workspace — is the only source of `/newsletter`,
-`/unsubscribe` and the footer signup; none of their copy is in page code,
-content or the message catalog. All three read it through
+`/unsubscribe`, the footer signup and a bound `newsletter` section; none of
+their copy is in page code, content or the message catalog. All four read it through
 `lib/in-page-magnet.ts`'s `readServedMagnet("newsletter")`, shared for 15
 seconds per instance like /contact's read.
 
@@ -306,6 +306,13 @@ seconds per instance like /contact's read.
 - **The footer** fills `Footer`'s `subscribe` slot with the compact form
   (stacked, `sr-only` label) only when the magnet is served and capture is
   on; the built-in config never fills it.
+- **A bound `newsletter` section** (#10629) — a content `newsletter` section
+  with `magnet: "newsletter"` in place of `action` renders, under its own
+  headline, the full-size signup the locale layout builds from the footer's
+  same read and hands every page through `NewsletterSignupProvider` — with
+  `consentGate: "on-submit"`, so Subscribe stays enabled and an unticked
+  submit shows the consent error beside the box. It renders nothing whenever
+  the footer would show nothing. A section with `action` posts as before.
 
 ## Careers
 
@@ -581,7 +588,7 @@ A visitor's browser never calls the hub. Lead capture, newsletter signup, callba
 - **No cross-site POST.** A `Sec-Fetch-Site` other than `same-origin`, or an `Origin` not on this site's own host, is refused 403 before the hub is called.
 - **Headers are an allow-list.** The visitor's `x-forwarded-for` (else `x-real-ip`) and `user-agent` pass through so per-visitor rate limits still count each visitor; no `authorization`, client-sent `x-ailk-*` or `host` is forwarded, and a `cookie` goes only on `POST /v1/commerce/invoices`, the one session route.
 - **The relay has its own per-visitor budget (#7707).** Each visitor gets 8 calls per 10 minutes across the five visitor routes, and the session route (`POST /v1/commerce/invoices`) gets its own, wider budget of 30 per 10 minutes; the call that exceeds either gets `429 rate_limited` before any hub call. The budget is held in this instance's own process (no shared store, no env variable) and holds only where the site's edge overwrites `x-forwarded-for` and `x-real-ip` — Vercel does; a bare self-hosted Next server does not.
-- **A bot check on the public writes (#9889, #9255).** On Vercel, `lib/bot-check.ts`'s `runBotCheck` asks Vercel BotID for a verdict before the hub is called — in the relay for `POST /v1/leads/{submit,subscribe,callback}` and `POST /v1/schedule/book` (`BOT_CHECKED_ROUTES`: `403 bot_detected`, or `503 bot_check_unavailable` when the check throws, answers no boolean or takes over 5 seconds), and in the contact, careers, newsletter, flow-step, flow-checkout, saved-recommendation and `/dev/purchase` Server Actions immediately before their hub call, which answer their own existing failure variant. The locale layout's `BotIdClient` protects every same-origin POST (`BOT_CLIENT_PROTECT`, `/*`), because a Server Action posts to the page it was submitted from; `next.config.mjs` wraps `withBotId` and `middleware.ts` keeps BotID's proxy prefix out of its matcher. It is on by default and inert off Vercel: `AILK_BOT_CHECK=off` turns every check off, `AILK_BOOKING_BOT_CHECK=off` the booking's alone, and MCP tools never pass through a site, so they are never challenged.
+- **A bot check on the public writes (#9889, #9255).** On Vercel, `lib/bot-check.ts`'s `runBotCheck` asks Vercel BotID for a verdict before the hub is called — in the relay for `POST /v1/leads/{submit,subscribe,callback}` and `POST /v1/schedule/book` (`BOT_CHECKED_ROUTES`: `403 bot_detected`, or `503 bot_check_unavailable` when the check throws, answers no boolean or takes over 5 seconds), and in the contact, careers, newsletter, flow-step, flow-checkout, saved-recommendation and `/dev/purchase` Server Actions immediately before their hub call, which answer their own existing failure variant. The locale layout's `BotIdClient` protects every same-origin POST (`BOT_CLIENT_PROTECT`, `/*`), because a Server Action posts to the page it was submitted from; `next.config.mjs` wraps `withBotId` and `middleware.ts` keeps BotID's proxy prefix out of its matcher. It is on by default and inert off Vercel: `AILK_BOT_CHECK=off` turns every check off, `AILK_BOOKING_BOT_CHECK=off` the booking's alone, and MCP tools never pass through a site, so they are never challenged. A refusal logs `[<source>] bot refused` with BotID's `classificationReason`, `bypassed` and `isVerifiedBot`, the request's `host` and `forwardedHost`, and `proxied` (a `cf-ray` header) — no other header value, no form field (#10715). `AILK_BOT_CHECK=observe` runs the check and logs the same facts plus `isBot` as `observed`, but passes every write — for diagnosis only. **A BotID-protected site must be reached directly — Cloudflare DNS-only, no reverse proxy in front of Vercel (#10715).** Behind a proxy the write reaches Vercel from the proxy's egress rather than the browser that solved the challenge, so BotID refuses every real visitor; the first proxied request per process logs `[<source>] reverse proxy detected` (outcome `proxied`) naming that fix.
 - `/v1` is exempt from next-intl's locale rewrite in `middleware.ts`, as `/api` is.
 
 ## Where the docs live (`docsPath`)
@@ -637,7 +644,11 @@ A list page whose frontmatter sets `navOnly: true` (valid on a registry list typ
 - Don't reach into `apps/api` or `apps/mcp` from `apps/web`. They're peer apps — talk via HTTP/MCP.
 - Don't commit images to `screenshots/` — only the `.gitkeep` is tracked.
 
-Last updated: 2026-11-01 — § The owner's discovery switch: the six discovery files read the workspace's `discoverable` setting per request through `siteDiscoverable()`, off answering robots.txt's disallow-all and 404 for the rest, never cached (#10510) — verified against `app/{robots.txt,sitemap.xml,llms.txt,openapi.json}/route.ts`, `app/.well-known/{mcp.json,ai-plugin.json}/route.ts`, `lib/slices/docs-blog/llms-route.ts` and `packages/api-client/src/discovery.ts`.
+Last updated: 2026-11-02 — § Theme & styling: `consent.appearance` named beside the other `_site.mdx` chrome keys, and the minimal deck home's hold-back is the band's alone, so a minimal site that picks the card sees it on load there too (#10721) — verified against `app/[locale]/layout.tsx`.
+
+Prior: 2026-11-02 — § The same-origin relay: a bot-check refusal names its cause (`classificationReason`, `bypassed`, `isVerifiedBot`, both hosts, `proxied`), `AILK_BOT_CHECK=observe` logs and never refuses, and a BotID-protected site must be reached directly, Cloudflare DNS-only (#10715) — verified against `lib/bot-check.ts`.
+
+Prior: 2026-11-01 — § The owner's discovery switch: the six discovery files read the workspace's `discoverable` setting per request through `siteDiscoverable()`, off answering robots.txt's disallow-all and 404 for the rest, never cached (#10510) — verified against `app/{robots.txt,sitemap.xml,llms.txt,openapi.json}/route.ts`, `app/.well-known/{mcp.json,ai-plugin.json}/route.ts`, `lib/slices/docs-blog/llms-route.ts` and `packages/api-client/src/discovery.ts`.
 
 Prior: 2026-10-30 — § The MCP authorization server: the site's OAuth 2.1 authorization server, its consent step, rotation and revocation (#10357) — verified against `auth.ts`, `lib/mcp-oauth.ts`, `app/[locale]/(auth)/consent/` and `app/.well-known/oauth-authorization-server/route.ts`.
 

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

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