create-ailk 0.30.0 → 0.31.0

package/dist/migrate-content.js

@@ -3,15 +3,16 @@
  * [--workspace <id>]` — import an existing site's MDX pages into its
  * workspace (#10207).
  *
- * The same import as `seed-workspace` — `importMdx` over `<dir>/content` with
+ * The same import as `seed-workspace` — `importMdx` over `<dir>/content`, and
+ * the docs-blog tree `<dir>/apps/web/content` when it exists (#10701), with
  * the site's own installed adapter — for the site `seed-workspace` refuses: one
  * with no `.ailk-site-manifest.json`, or a spoke, whose workspace lives on its
  * hub (D1). No manifest and no topology is read; the operator names the API
  * origin and the workspace, which is all the topology would decide.
  *
  * A dry run is the default (D3): the importer runs over `readOnlyFetch`, which
- * passes each `GET` through and answers a `POST` or `PATCH` locally without
- * sending it, so the plan — create · update · unchanged · skipped · failed — is
+ * passes each `GET` through and answers a `POST`, `PATCH` or `PUT` locally
+ * without sending it, so the plan — create · update · unchanged · skipped · failed — is
  * decided by the importer itself against the live workspace, and no write can
  * leave the process. `--apply` writes; a second `--apply` reports every page
  * `unchanged`.
@@ -27,7 +28,8 @@
  */
 import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { formatImportMdxReport, importMdx, loadSiteMdxAdapter, } from "./lib/import-mdx.js";
+import { languageLines, languageOffLine, withLanguage, } from "./language-import.js";
+import { formatImportMdxReport, importMdx, isDirectory, loadSiteMdxAdapter, outcomePath, } from "./lib/import-mdx.js";
 import { ParseError } from "./parse-args.js";
 import { AGENT_KEY_ENV_VAR, WORKSPACE_ID_ENV_VAR } from "./seed-workspace.js";
 import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, } from "./topology.js";
@@ -53,17 +55,20 @@ function given(value) {
 /**
  * A fetch that sends `GET`s through `inner` and never sends a write: a `POST`
  * is answered `201` and a `PATCH` `200` locally, with the one member of a
- * write's answer `importMdx` reads (`data.locale`). Any other method throws.
+ * write's answer `importMdx` reads (`data.locale`), and the structure write's
+ * `PUT` (#10534) `200` as a layout unchanged (`data.written: false`). Any
+ * other method throws.
  */
 export function readOnlyFetch(inner, locale) {
     return (async (input, init) => {
         const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
         if (method === "GET")
             return inner(input, init);
-        if (method !== "POST" && method !== "PATCH") {
+        if (method !== "POST" && method !== "PATCH" && method !== "PUT") {
             throw new Error(`a dry run sends no ${method} request`);
         }
-        return new Response(JSON.stringify({ ok: true, data: { locale } }), {
+        const data = method === "PUT" ? { locale, written: false } : { locale };
+        return new Response(JSON.stringify({ ok: true, data }), {
             status: method === "POST" ? 201 : 200,
             headers: { "content-type": "application/json" },
         });
@@ -81,8 +86,8 @@ const PLAN_VERB = {
 function planLine(outcome) {
     const verb = PLAN_VERB[outcome.result];
     return "reason" in outcome
-        ? `${outcome.path}: ${verb} — ${outcome.reason}`
-        : `${outcome.path}: ${verb}`;
+        ? `${outcomePath(outcome)}: ${verb} — ${outcome.reason}`
+        : `${outcomePath(outcome)}: ${verb}`;
 }
 // ── The command (D1–D4) ─────────────────────────────────────────────────────
 export async function migrateContent(opts) {
@@ -119,14 +124,29 @@ export async function migrateContent(opts) {
         : `Planning ${opts.targetDir} against ${at} Nothing is written without --apply.`);
     const adapters = opts.adapters ?? (await loadSiteMdxAdapter(targetDir));
     const fetch = opts.fetch ?? globalThis.fetch;
+    const transport = apply ? fetch : readOnlyFetch(fetch, LOCALE);
+    // #10735 D1 — the Language pass wraps the importer's read.
+    const pass = withLanguage(adapters, {
+        apiOrigin: origin,
+        workspaceId,
+        apiKey,
+        locale: LOCALE,
+        fetch: transport,
+        apply,
+        ...(opts.sleep !== undefined && { sleep: opts.sleep }),
+        onLine,
+    });
+    // #10701 D7 — the docs-blog tree, when the site has one.
+    const editorialRoot = join(targetDir, "apps", "web", "content");
     const result = await importMdx({
         contentRoot: join(targetDir, "content"),
-        adapters,
+        ...(isDirectory(editorialRoot) && { editorialRoot }),
+        adapters: pass.adapters,
         apiOrigin: origin,
         workspaceId,
         apiKey,
         defaultLocale: LOCALE,
-        fetch: apply ? fetch : readOnlyFetch(fetch, LOCALE),
+        fetch: transport,
         ...(opts.sleep !== undefined && { sleep: opts.sleep }),
         // A dry run's importer lines say `created`/`updated`, which nothing was.
         ...(apply && { onLine }),
@@ -148,7 +168,17 @@ export async function migrateContent(opts) {
             onLine(`${failed} page(s) would fail. Fix them before --apply.`);
         }
     }
-    return { result, exitCode: failed > 0 ? 1 : 0 };
+    // #10735 D7 — the Language lines come last.
+    const { result: language, off } = pass.report();
+    if (off !== undefined)
+        onLine(languageOffLine(off));
+    if (language !== undefined)
+        languageLines(language, apply).forEach(onLine);
+    return {
+        result,
+        exitCode: failed > 0 ? 1 : 0,
+        ...(language !== undefined && { language }),
+    };
 }
 export const MIGRATE_CONTENT_HELP = `create-ailk migrate-content — import an existing site's pages into its workspace.
 
@@ -174,11 +204,27 @@ content/<Type>/<slug>.mdx) is written to the workspace as a draft through
 the API's content routes, with the agent key, which is read from
 AILK_AGENT_KEY only and needs the content-edit grant. Nothing is published,
 so the live site does not change. The site needs no .ailk-site-manifest.json
-and may be a spoke; its dependencies must be installed.
+and may be a spoke; its dependencies must be installed. A page whose
+frontmatter carries sections is converted: its words are written to the
+page's Markdown and its sections to its layout.
+
+Each FAQ item and glossary-index term becomes one Language item of its kind,
+set Live when the run creates it, and its section pins the items in the
+order the file lists them. A question on several pages is one item, with
+the FAQ page's words (the glossary page's, for a term). Lines prefixed
+language: report each item, and each page the database read will not show
+as its file does. An API with no Language collection leaves them inline.
+
+When the site has apps/web/content, each blog post and docs page in it is
+written too: apps/web/content/en/blog/<slug>.mdx (or <slug>/index.mdx) as a
+BlogPosting, the same under docs as a DocsDetail, and each directory's own
+index.mdx as its BlogList or DocsList index. Their lines are prefixed
+editorial: — each outcome's root is content or editorial.
 
 A dry run prints create, update, unchanged, skipped or failed per page. It
 cannot see a write the API would refuse at --apply (a conflict or a server
-error), and a page whose content fails its page type is planned and saved
+error), nor a layout change on a page whose words did not change, and a
+page whose content fails its page type is planned and saved
 with errors the editor shows, not failed. --apply prints created, updated,
 unchanged, skipped or failed per page, so a re-run is safe. Exit 0 when no
 page failed, 1 when any did, 2 on a refusal (nothing is sent).

package/dist/seed-workspace.d.ts

@@ -4,6 +4,8 @@ import { type Topology } from "./topology.js";
 export declare const AGENT_KEY_ENV_VAR = "AILK_AGENT_KEY";
 /** The environment variable the workspace id is read from when no flag names one. */
 export declare const WORKSPACE_ID_ENV_VAR = "AILK_WORKSPACE_ID";
+/** The environment variable each app chooses its content source by (#10659). */
+export declare const CONTENT_ADAPTER_ENV_VAR = "CONTENT_ADAPTER";
 /** A refusal the CLI exits 2 on, thrown before any request is sent. */
 export declare class SeedWorkspaceRefusedError extends Error {
     readonly exitCode = 2;
@@ -67,5 +69,5 @@ export interface SeedWorkspaceArgs {
     workspaceId: string | undefined;
     help: boolean;
 }
-export declare const SEED_WORKSPACE_HELP = "create-ailk seed-workspace \u2014 import a starter's pages into its workspace.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk seed-workspace [<dir>] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                    The site. Defaults to the current dir.\n\nOptions:\n  --api-url <origin>       The site's API origin. Else AILK_API_URL. https:\n                           only (http: on localhost or 127.0.0.1).\n  --workspace <wksp_id>    The workspace the pages are written to. Else\n                           AILK_WORKSPACE_ID.\n  -h, --help               Show this help.\n\nEach content/en/<Type>/<slug>.mdx page is written to the workspace as a\ndraft through the API's content routes, with the agent key, which is read\nfrom AILK_AGENT_KEY only and needs the content-edit grant. Each page prints\ncreated, updated, unchanged, skipped or failed, so a re-run is safe. The\nsite's dependencies must be installed. Exit 0 when every page was seeded, 1\nwhen any failed, 2 on a refusal (nothing is sent).\n";
+export declare const SEED_WORKSPACE_HELP = "create-ailk seed-workspace \u2014 import a starter's pages into its workspace.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk seed-workspace [<dir>] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                    The site. Defaults to the current dir.\n\nOptions:\n  --api-url <origin>       The site's API origin. Else AILK_API_URL. https:\n                           only (http: on localhost or 127.0.0.1).\n  --workspace <wksp_id>    The workspace the pages are written to. Else\n                           AILK_WORKSPACE_ID.\n  -h, --help               Show this help.\n\nEach content/en/<Type>/<slug>.mdx page is written to the workspace, and set\nLive when it has no Live version, through the API's content routes, with the\nagent key, which is read from AILK_AGENT_KEY only and needs the content-edit\nand content-publish grants. Each page prints created, updated, unchanged,\nskipped or failed, so a re-run is safe. When every page is Live, the site\nswitches apps/web and apps/api to CONTENT_ADAPTER=database, keeping a value\neither already sets. The site's dependencies must be installed. Exit 0 when\nevery page was seeded, 1 when any failed, 2 on a refusal (nothing is sent).\n";
 export declare function parseSeedWorkspaceArgs(argv: string[]): SeedWorkspaceArgs;

package/dist/seed-workspace.js

@@ -6,7 +6,10 @@
  * A fresh scaffold's `content/` tree is exactly its roster (spec §1), so the
  * seed is `importMdx` over `<dir>/content` with the site's own installed
  * adapter (D1): one `text/page` Artifact per page, and a re-run writes
- * nothing and reports every page `unchanged`.
+ * nothing and reports every page `unchanged`. Each page with no Live version
+ * is set Live, and when every page is Live both apps that choose a content
+ * source are switched to `CONTENT_ADAPTER=database`, each keeping a value it
+ * already sets (#10659 D3); anything less leaves the site on `content/`.
  *
  * The API origin comes from `--api-url`, else `AILK_API_URL`; the workspace
  * id from `--workspace`, else `AILK_WORKSPACE_ID`; the agent key from
@@ -18,12 +21,14 @@
  *
  * The scaffold-time step (D3, D6) runs only on a hub with an Admin
  * (`workspace` or `multi-tenant`), after `--install`, with all three
- * variables set; otherwise it prints why and the command that seeds later,
- * or nothing on a site with no Admin. It never fails the scaffold.
+ * variables set; otherwise it prints why and the command that seeds and
+ * switches later, or nothing on a site with no Admin. It never fails the
+ * scaffold.
  *
  * Pure module: no `import.meta.url`, so jest can import it directly. `fetch`,
  * `sleep`, `env` and the adapter are injectable. Spec:
- * docs/specs/10204-seed-the-starter-s-roster-spec.md.
+ * docs/specs/10204-seed-the-starter-s-roster-spec.md; the publish and the
+ * switch docs/specs/10659-a-licensed-hub-scaffold-starts-spec.md.
  */
 import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
@@ -31,11 +36,13 @@ import { AddModuleRefusedError } from "./add-module-core.js";
 import { ImportMdxRefusedError, formatImportMdxReport, importMdx, loadSiteMdxAdapter, } from "./lib/import-mdx.js";
 import { ParseError } from "./parse-args.js";
 import { readSiteRoster } from "./site-roster.js";
-import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, readSiteTopology, } from "./topology.js";
+import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, readSiteTopology, writeApiEnv, writeWebEnv, } from "./topology.js";
 /** The environment variable the agent key is read from — and nowhere else. */
 export const AGENT_KEY_ENV_VAR = "AILK_AGENT_KEY";
 /** The environment variable the workspace id is read from when no flag names one. */
 export const WORKSPACE_ID_ENV_VAR = "AILK_WORKSPACE_ID";
+/** The environment variable each app chooses its content source by (#10659). */
+export const CONTENT_ADAPTER_ENV_VAR = "CONTENT_ADAPTER";
 /** A refusal the CLI exits 2 on, thrown before any request is sent. */
 export class SeedWorkspaceRefusedError extends Error {
     exitCode = 2;
@@ -83,7 +90,7 @@ export async function seedWorkspace(opts) {
     }
     const apiKey = given(env[AGENT_KEY_ENV_VAR]);
     if (apiKey === undefined) {
-        refuse(`set ${AGENT_KEY_ENV_VAR} to an agent key with the content-edit grant. It is read from the environment only — never a flag or a file.`);
+        refuse(`set ${AGENT_KEY_ENV_VAR} to an agent key with the content-edit and content-publish grants. It is read from the environment only — never a flag or a file.`);
     }
     const workspaceId = given(opts.workspaceId) ?? given(env[WORKSPACE_ID_ENV_VAR]);
     if (workspaceId === undefined) {
@@ -115,12 +122,30 @@ export async function seedWorkspace(opts) {
         ...(opts.fetch !== undefined && { fetch: opts.fetch }),
         ...(opts.sleep !== undefined && { sleep: opts.sleep }),
         onLine,
+        publish: true,
     });
     // The report's count line alone: no page rows.
     onLine(formatImportMdxReport({ pages: [], counts: result.counts }).trimEnd());
-    const { failed } = result.counts;
-    if (failed > 0) {
-        onLine(`${failed} page(s) were not seeded. Fix them and re-run: create-ailk seed-workspace ${opts.targetDir}`);
+    const { created, updated, unchanged, failed } = result.counts;
+    const live = result.live ?? 0;
+    onLine(`Live: ${live} page(s), ${result.published ?? 0} published now.`);
+    // #10659 D3 — both apps switch only when every page is in and Live.
+    if (failed === 0 && live >= 1 && live === created + updated + unchanged) {
+        for (const [app, file, write] of [
+            ["apps/web", "apps/web/.env.local", writeWebEnv],
+            ["apps/api", "apps/api/.env", writeApiEnv],
+        ]) {
+            onLine(write(targetDir, CONTENT_ADAPTER_ENV_VAR, () => "database")
+                ? `Content source: the database for ${app} (${CONTENT_ADAPTER_ENV_VAR}=database in ${file}).`
+                : `Content source: ${app} already sets ${CONTENT_ADAPTER_ENV_VAR}, which was kept.`);
+        }
+        onLine("  The API serves these pages from the database it was seeded through (DATABASE_URL), for the workspace its site resolves.");
+    }
+    else {
+        if (failed > 0) {
+            onLine(`${failed} page(s) were not seeded. Fix them and re-run: create-ailk seed-workspace ${opts.targetDir}`);
+        }
+        onLine("Content source: content/ (unchanged) until every page is seeded and Live.");
     }
     return { result, exitCode: failed > 0 ? 1 : 0 };
 }
@@ -166,9 +191,10 @@ export async function runScaffoldSeed(opts) {
     const plan = scaffoldSeedPlan(opts);
     if (plan.kind === "not-applicable")
         return;
+    const later = `  To seed it and switch to the database later: ${AGENT_KEY_ENV_VAR}=<key> create-ailk seed-workspace ${opts.targetDir} --api-url <origin> --workspace <wksp_id>`;
     if (plan.kind === "skip") {
         opts.onLine(plan.reason);
-        opts.onLine(`  To seed it later: ${AGENT_KEY_ENV_VAR}=<key> create-ailk seed-workspace ${opts.targetDir} --api-url <origin> --workspace <wksp_id>`);
+        opts.onLine(later);
         return;
     }
     opts.onLine("Seeding the workspace:");
@@ -188,6 +214,7 @@ export async function runScaffoldSeed(opts) {
             throw err;
         }
         opts.onLine(err.message);
+        opts.onLine(later);
     }
 }
 export const SEED_WORKSPACE_HELP = `create-ailk seed-workspace — import a starter's pages into its workspace.
@@ -205,12 +232,14 @@ Options:
                            AILK_WORKSPACE_ID.
   -h, --help               Show this help.
 
-Each content/en/<Type>/<slug>.mdx page is written to the workspace as a
-draft through the API's content routes, with the agent key, which is read
-from AILK_AGENT_KEY only and needs the content-edit grant. Each page prints
-created, updated, unchanged, skipped or failed, so a re-run is safe. The
-site's dependencies must be installed. Exit 0 when every page was seeded, 1
-when any failed, 2 on a refusal (nothing is sent).
+Each content/en/<Type>/<slug>.mdx page is written to the workspace, and set
+Live when it has no Live version, through the API's content routes, with the
+agent key, which is read from AILK_AGENT_KEY only and needs the content-edit
+and content-publish grants. Each page prints created, updated, unchanged,
+skipped or failed, so a re-run is safe. When every page is Live, the site
+switches apps/web and apps/api to CONTENT_ADAPTER=database, keeping a value
+either already sets. The site's dependencies must be installed. Exit 0 when
+every page was seeded, 1 when any failed, 2 on a refusal (nothing is sent).
 `;
 export function parseSeedWorkspaceArgs(argv) {
     let parsed;

package/dist/topology.d.ts

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

package/dist/topology.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.30.0",
+  "version": "0.31.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.54.0",
+    "@working-theory/templates": "0.54.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,8 @@ 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
 
       - 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/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.