@tokenoftrust/cli 2.4.3 → 2.4.5

package/bin/tot.mjs

@@ -62,7 +62,7 @@ const COMMANDS = [
   { invocation: "dev", blurb: "run your store locally with save→reload" },
   { invocation: "preview", blurb: "push your store to a reviewable preview" },
   { invocation: "status", blurb: "the pipeline verdict for your active tenant — progressing / stuck / idle, and why" },
-  { invocation: "ship", blurb: "publish the tenant's current green aggregate live (plan → confirm → ship)" },
+  { invocation: "ship", blurb: "publish the store live — its green aggregate and approved mounted spaces as one release (plan → confirm → ship)" },
   { invocation: "accept / tot merge", blurb: "queue a PR into the preview aggregate — operator verb, no go-live (plan → confirm → integrate)" },
   { invocation: "sync", blurb: "fetch `preview` and merge it into your local branch (accept-conflict recovery)" },
   { invocation: "rollback [<version>]", blurb: "instant re-point to a prior live version (list → confirm → rollback)" },
@@ -81,6 +81,16 @@ const COMMANDS = [
   { invocation: "--version", blurb: "print the CLI version" },
 ];
 
+/** Store-root verbs that never run inside a mounted publication space's checkout. */
+const SPACE_REFUSED_COMMANDS = new Set(["preview", "submit", "deploy", "sync", "accept", "merge", "hotfix", "revert"]);
+
+/** @param {string} cmd @param {string} spaceId */
+function spaceCheckoutRefusal(cmd, spaceId) {
+  return `✗ this is the "${spaceId}" publication space's own repository — \`tot ${cmd}\` acts on the store's root repository.\n` +
+    "  → commit and `git push` here (tot mints this space's credential on push); once its version is built and\n" +
+    "    approved on the store's admin Publish tab, `tot ship` takes it live with the rest of the store.\n";
+}
+
 function usage() {
   const col = Math.max(...COMMANDS.map((c) => `tot ${c.invocation}`.length)) + 2;
   const lines = COMMANDS.map((c) => `  ${`tot ${c.invocation}`.padEnd(col)}${c.blurb}`).join("\n");
@@ -115,6 +125,18 @@ async function dispatch(cmd, rest, ctx) {
     return 2;
   }
 
+  // A mounted publication space's checkout (spaces/<id>/, recorded by `tot clone`) is its own
+  // repository: the store-root verbs below would push it with the ROOT's credential or merge the
+  // root's preview branch into it. Refuse them there, naming the space's own path.
+  if (SPACE_REFUSED_COMMANDS.has(cmd)) {
+    const { recordedCheckout } = await import("../src/commands/git-credential.mjs");
+    const space = recordedCheckout(ctx.cwd);
+    if (space?.kind === "publication-space") {
+      process.stderr.write(spaceCheckoutRefusal(cmd, space.spaceId));
+      return 2;
+    }
+  }
+
   if (cmd === "start") {
     const { run } = await import("../src/commands/start.mjs");
     return run(rest, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.4.3",
+  "version": "2.4.5",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/commands/clone.mjs

@@ -11,6 +11,18 @@
  *   tot clone <tenant> <dir>     clone into <dir>
  *   tot clone <tenant> --remote-only   just mint + print the remote, don't materialize
  *   tot clone agency-kit [dir]   READ-ONLY clone of the Agency Kit (ADR 0037)
+ *   tot clone --spaces           (inside a checkout) record the store's publication spaces and
+ *                                clone any mounted space not yet under spaces/
+ *
+ * MOUNTED PUBLICATION SPACES. A store whose site is split across repositories (a root plus
+ * mounted spaces such as `/blog`) is cloned whole: after the root, `tot clone` reads the
+ * platform's declared split (`GET /api/publication-spaces`, over the developer's own viewer
+ * session), records it in `.tot/publication-spaces.json`, and clones each mounted space it can
+ * get a credential for into `spaces/<spaceId>/`. Space credentials come only from the MCP
+ * `publication_checkout` tool; like the root's, the token rides a one-shot header, is never
+ * written to `.git/config`, and is never printed. Each space checkout records its kind so
+ * `tot git-credential` re-mints its credential through `publication_checkout` on every fetch and
+ * push, never as the root store's.
  *
  * AGENCY KIT. `agency-kit` is an alias, not a tenant: it mints through
  * `repo_read_credential` (see READ_ONLY_ALIASES / kitReadCredentialInput) and skips
@@ -53,6 +65,8 @@
  * Dependency-free (global fetch + `git` via child_process).
  */
 import { execFile, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { promisify } from "node:util";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
@@ -63,7 +77,12 @@ import { writeNvmrc } from "../sample.mjs";
 import { emitObstacle } from "../obstacle.mjs";
 import {
   splitAuthedRemote, basicAuthExtraHeader, installForgeCredentialHelper, recordReadOnlyKitCheckout,
+  recordPublicationSpaceCheckout,
 } from "../git-credential.mjs";
+import { resolveViewerTransport } from "../viewer-session.mjs";
+import {
+  mountedSpaces, spaceDir, topologyFromDeclaredSpaces, writeWorkspaceTopology, TOPOLOGY_FILE,
+} from "../publication-spaces.mjs";
 import { recordDiagnostic } from "../diagnostics.mjs";
 
 const execFileP = promisify(execFile);
@@ -71,7 +90,7 @@ const execFileP = promisify(execFile);
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 function parseArgs(argv) {
-  /** @type {{ tenant: string|null, dir: string|null, tag: string, pr: string|null, remoteOnly: boolean, mcp: string|null, printRemote: boolean, help: boolean }} */
+  /** @type {{ tenant: string|null, dir: string|null, tag: string, pr: string|null, remoteOnly: boolean, mcp: string|null, url: string|null, printRemote: boolean, spaces: boolean, help: boolean }} */
   const a = {
     tenant: null,
     dir: null,
@@ -79,7 +98,9 @@ function parseArgs(argv) {
     pr: null,
     remoteOnly: false,
     mcp: null,
+    url: null,
     printRemote: false,
+    spaces: false,
     help: false,
   };
   for (let i = 0; i < argv.length; i++) {
@@ -89,6 +110,8 @@ function parseArgs(argv) {
     else if (t === "--remote-only") a.remoteOnly = true;
     else if (t === "--mcp") a.mcp = argv[++i];
     else if (t === "--print-remote") a.printRemote = true;
+    else if (t === "--spaces") a.spaces = true;
+    else if (t === "--url") a.url = argv[++i];
     else if (t === "--help" || t === "-h") a.help = true;
     // Positional, git-clone style: `tot clone <tenant> [<dir>]`.
     else if (!t.startsWith("--")) {
@@ -126,6 +149,13 @@ const USAGE = `tot clone — clone a tenant store you can build on (mirrors \`gi
                                 <tenant>-pr<N>)
   tot clone agency-kit [dir]   clone the Agency Kit, READ-ONLY, into ./agency-kit
                                 (needs agency access — ask Token of Trust)
+  tot clone --spaces           (inside a checkout) record the store's publication
+                                spaces and clone any mounted space not yet under
+                                spaces/<id>/
+
+A store split across repositories (a root plus mounted spaces like /blog) clones
+whole: the root, then each mounted space you can edit into spaces/<id>/.
+\`tot validate --owner <path>\` names the repository that owns a URL.
 
 Options:
   --tag <tag>       deprecated compatibility input; tenant repos use the bare domain.
@@ -134,6 +164,8 @@ Options:
   --remote-only     don't clone; just mint + print the clone URL for <tenant>.
   --mcp <url>       MCP base URL. Default: env MCP_BASE_URL / TOT_MCP_URL, else
                     ${DEFAULT_MCP_URL}.
+  --url <origin>    storefront origin the publication spaces are read from.
+                    Default: env TOT_STOREFRONT_URL, else the shared storefront.
   --print-remote    with --remote-only, also print the authenticated remote
                     (contains a live token!).`;
 
@@ -154,7 +186,7 @@ function makeRedactor(env) {
 export async function run(argv, ctx, deps = {}) {
   const {
     env = process.env, createClient = createMcpClient, establish = establishSession,
-    signIn = offerSignIn, cloneDeps = {},
+    signIn = offerSignIn, cloneDeps = {}, readTopology = fetchDeclaredTopology,
   } = deps;
   const args = parseArgs(argv);
   if (args.help) {
@@ -172,6 +204,24 @@ export async function run(argv, ctx, deps = {}) {
     args.tenant = ctx.tenant;
   }
 
+  if (args.spaces) {
+    if (ctx.mode !== "checkout" || !ctx.workspacePath || !args.tenant) {
+      console.error(fail("`tot clone --spaces` runs inside a store checkout", "tot clone <tenant>   (clones the root and its spaces)"));
+      return 2;
+    }
+    const redact = makeRedactor(env);
+    const client = createClient(args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL);
+    try {
+      await signInOrOffer(client, { env, establish, signIn });
+      await clonePublicationSpacesInto(client, {
+        tenant: args.tenant, dir: ctx.workspacePath, env, storefrontUrl: args.url, redact, readTopology, cloneDeps,
+      });
+      return 0;
+    } catch (e) {
+      return reportFailure(e, redact);
+    }
+  }
+
   let pr;
   try {
     pr = parsePrNumber(args.pr);
@@ -246,11 +296,14 @@ export async function run(argv, ctx, deps = {}) {
       tag: args.tag,
       cloneDir,
       redact,
-    });
+    }, cloneDeps);
     console.log(`\n+ ready. repo: ${res.cloneUrl || res.publicUrl}`);
 
     if (res.cloned) {
       console.log(`+ cloned. HEAD: ${res.head}`);
+      await clonePublicationSpacesInto(client, {
+        tenant: args.tenant, dir: /** @type {string} */ (res.dir), env, storefrontUrl: args.url, redact, readTopology, cloneDeps,
+      });
       console.log(`\nYour local working clone is at ${res.dir}.`);
       console.log(`  cd ${res.dir} && tot dev            # run it locally with save→reload`);
       console.log(`  (origin has no token — \`tot\` mints one fresh at fetch/push time)`);
@@ -374,7 +427,7 @@ export function checkoutPointsAtEntitlement(checkout) {
  * @returns {Promise<{ gitRemote: string, cloneUrl: string|null, publicUrl: string,
  *   cloned: boolean, dir: string|null, head: string|null }>}
  */
-export async function checkoutTenant(client, { tenant, tag = "main", cloneDir = null, redact = (s) => s }) {
+export async function checkoutTenant(client, { tenant, tag = "main", cloneDir = null, redact = (s) => s }, cloneDeps = {}) {
   // tenant_checkout is the SOLE AUTHORITATIVE checkout decision, and it names the tenant
   // (scopeToTenant injects it), so the server checks out that held tenant directly — or
   // answers for a staff-preview authorization, or refuses naming the tenants the session
@@ -419,7 +472,7 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
   if (!cloneDir) {
     return { gitRemote, cloneUrl, publicUrl, cloned: false, dir: null, head: null };
   }
-  const { dir, head } = await cloneRepo(gitRemote, cloneDir, redact);
+  const { dir, head } = await cloneRepo(gitRemote, cloneDir, redact, cloneDeps);
   return { gitRemote, cloneUrl, publicUrl, cloned: true, dir, head };
 }
 
@@ -515,6 +568,137 @@ async function cloneRepo(gitRemote, dir, redact, {
   return { dir, head };
 }
 
+// ─── mounted publication spaces ────────────────────────────────────────────────
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+/**
+ * Read a store's declared publication topology from the platform: `GET /api/publication-spaces`
+ * over the developer's own viewer session, which returns only the spaces the platform lets this
+ * developer see. Never throws.
+ * @param {{ tenant: string, env?: NodeJS.ProcessEnv, storefrontUrl?: string|null,
+ *   fetchImpl?: typeof fetch, resolveTransport?: typeof resolveViewerTransport }} input
+ * @returns {Promise<{ ok: true, topology: import("../publication-spaces.mjs").Topology } | { ok: false, reason: string }>}
+ */
+export async function fetchDeclaredTopology({
+  tenant, env = process.env, storefrontUrl = null, fetchImpl = fetch, resolveTransport = resolveViewerTransport,
+}) {
+  const origin = storefrontUrl || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+  const transport = await resolveTransport({ tenant, env, fetchImpl, storefrontUrl: origin });
+  if (!transport.ok) return { ok: false, reason: transport.message };
+  let res;
+  try {
+    res = await fetchImpl(`${transport.base}/api/publication-spaces`, { headers: transport.authHeaders });
+  } catch (e) {
+    return { ok: false, reason: `couldn't reach ${transport.base}: ${/** @type {any} */ (e)?.message || e}` };
+  }
+  /** @type {any} */
+  let body = null;
+  try { body = await res.json(); } catch { /* not JSON */ }
+  if (!res.ok || !body?.ok) return { ok: false, reason: body?.error || `HTTP ${res.status}` };
+  try {
+    return { ok: true, topology: topologyFromDeclaredSpaces(tenant, body.spaces) };
+  } catch (e) {
+    return { ok: false, reason: String(/** @type {any} */ (e)?.message || e) };
+  }
+}
+
+/**
+ * Mint a write credential for one mounted space through `publication_checkout`, refusing a
+ * result for any other space or repository. The credential is returned, never printed.
+ * @param {{ callTool: (name: string, args?: Record<string, unknown>) => Promise<any> }} scoped
+ * @param {import("../publication-spaces.mjs").TopologySpace} space
+ * @param {(s: string) => string} redact
+ * @returns {Promise<{ gitRemote: string }>}
+ */
+export async function mintPublicationSpace(scoped, space, redact = (s) => s) {
+  const next = `ask the store owner for edit access to the "${space.id}" space, then run \`tot clone --spaces\` in your checkout`;
+  /** @type {any} */
+  let res;
+  try {
+    res = await scoped.callTool("publication_checkout", {});
+  } catch (e) {
+    const reason = serverReason(e);
+    throw new CliError(`no write credential for the "${space.id}" space${reason ? `: ${redact(reason)}` : ""}`, { next, cause: e });
+  }
+  if (!res || res.status !== "checked-out" || typeof res.gitRemote !== "string" || !res.gitRemote) {
+    const reason = serverReason(res);
+    throw new CliError(`no write credential for the "${space.id}" space${reason ? `: ${redact(reason)}` : ""}`, { next });
+  }
+  if (res.binding?.spaceId !== space.id || res.repo !== space.source.repo || res.binding?.source?.repo !== space.source.repo) {
+    throw new CliError(`Token of Trust has no write credential for the "${space.id}" space (it offered "${res.binding?.spaceId ?? "another space"}")`, { next });
+  }
+  return { gitRemote: res.gitRemote };
+}
+
+/**
+ * Clone each mounted space of `topology` that is not yet under `<dir>/spaces/` — a space this
+ * developer has no credential for is reported and skipped, never fatal to the root clone.
+ * @param {ReturnType<import("../mcp.mjs").createMcpClient>} client
+ * @param {{ tenant: string, dir: string, topology: import("../publication-spaces.mjs").Topology,
+ *   redact?: (s: string) => string }} input
+ * @param {Parameters<typeof cloneRepo>[3]} [deps]
+ * @returns {Promise<Array<{ spaceId: string, mount: string, dir: string, status: "cloned"|"present"|"skipped",
+ *   head?: string, reason?: string, next?: string }>>}
+ */
+export async function clonePublicationSpaces(client, { tenant, dir, topology, redact = (s) => s }, deps = {}) {
+  const spaces = mountedSpaces(topology);
+  if (!spaces.length) return [];
+  const scoped = await scopeToTenant(client, tenant, { redact });
+  const results = [];
+  for (const space of spaces) {
+    const rel = spaceDir(space);
+    const target = join(dir, rel);
+    if (existsSync(target)) {
+      results.push({ spaceId: space.id, mount: space.mount, dir: rel, status: /** @type {const} */ ("present") });
+      continue;
+    }
+    console.error(`~ publication_checkout (tenant=${tenant}, space=${space.id}) — MCP mints a fresh space credential`);
+    try {
+      const { gitRemote } = await mintPublicationSpace(scoped, space, redact);
+      const cred = splitAuthedRemote(gitRemote);
+      const scrub = (/** @type {string} */ s) => (cred ? redact(s).split(cred.token).join("***") : redact(s));
+      const { head } = await cloneRepo(gitRemote, target, scrub, {
+        ...deps,
+        store: false,
+        record: (gitSync) => recordPublicationSpaceCheckout(gitSync, { tenant, spaceId: space.id, repo: space.source.repo }),
+      });
+      results.push({ spaceId: space.id, mount: space.mount, dir: rel, status: /** @type {const} */ ("cloned"), head });
+    } catch (e) {
+      const err = /** @type {any} */ (e);
+      results.push({
+        spaceId: space.id, mount: space.mount, dir: rel, status: /** @type {const} */ ("skipped"),
+        reason: err instanceof CliError ? err.message : redact(String(err?.message || err)),
+        ...(err?.next ? { next: err.next } : {}),
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * After a root clone (or `tot clone --spaces` in a checkout): record the declared topology and
+ * clone the mounted spaces, reporting each in one line. A topology the platform will not give is
+ * reported and the root stays usable on its own.
+ */
+async function clonePublicationSpacesInto(client, { tenant, dir, env, storefrontUrl, redact, readTopology, cloneDeps }) {
+  const read = await readTopology({ tenant, env, storefrontUrl });
+  if (!read.ok) {
+    console.log(`~ publication spaces: couldn't read this store's split (${redact(read.reason)}) — the root is cloned on its own.`);
+    console.log(`  Run \`tot clone --spaces\` in ${dir} to retry.`);
+    return;
+  }
+  writeWorkspaceTopology(dir, read.topology);
+  const mounted = mountedSpaces(read.topology);
+  if (!mounted.length) return;
+  console.log(`+ publication spaces recorded in ${TOPOLOGY_FILE}: ${mounted.map((s) => `${s.mount} (${s.id})`).join(", ")}`);
+  for (const result of await clonePublicationSpaces(client, { tenant, dir, topology: read.topology, redact }, cloneDeps)) {
+    if (result.status === "cloned") console.log(`+ space ${result.spaceId} (${result.mount}) cloned into ${result.dir}/. HEAD: ${result.head}`);
+    else if (result.status === "present") console.log(`  space ${result.spaceId} (${result.mount}) already at ${result.dir}/`);
+    else console.log(`~ space ${result.spaceId} (${result.mount}) not cloned: ${result.reason}${result.next ? `\n  next: ${result.next}` : ""}`);
+  }
+}
+
 // ─── read-only aliases: `tot clone agency-kit` ─────────────────────────────────
 
 /**

package/src/commands/git-credential.mjs

@@ -17,10 +17,12 @@
  * sends when the forge rejected the credential, drops that cache so the next
  * `get` re-mints; `store` is a no-op.
  *
- * Two checkout kinds: a tenant store (its `.tot/config.json`) mints a push
+ * Three checkout kinds: a tenant store (its `.tot/config.json`) mints a push
  * credential through `tenant_checkout`; a read-only kit clone (recorded in local
  * git config by `tot clone agency-kit`) mints through `repo_read_credential`,
- * cached under a key a store's can never take.
+ * cached under a key a store's can never take; a mounted publication space (recorded
+ * by `tot clone` under `spaces/<id>/`) mints through `publication_checkout`, never
+ * cached, because each mint rotates the editor's older tokens.
  *
  * FAILS SILENT ON STDOUT, NEVER LOUD THERE: `get` prints NOTHING on stdout and
  * exits non-zero on any problem (not signed in, MCP unreachable, cwd isn't a
@@ -49,14 +51,15 @@ import { readFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession } from "../auth.mjs";
-import { checkoutTenant, mintReadOnlyAlias, resolveReadOnlyAlias } from "./clone.mjs";
+import { checkoutTenant, mintPublicationSpace, mintReadOnlyAlias, resolveReadOnlyAlias } from "./clone.mjs";
+import { scopeToTenant } from "../tenant-scope.mjs";
 import { detectContext } from "../context.mjs";
 import { repoNameFromRemote, tagFromRepoName } from "./submit.mjs";
 import { CliError, formatError } from "../errors.mjs";
 import {
   parseCredentialInput, formatCredentialOutput, splitAuthedRemote,
   readCachedCredential, writeCachedCredential,
-  kitCredentialCachePath, dropCachedCredential, readCheckoutKind, READ_ONLY_KIT_KIND,
+  kitCredentialCachePath, dropCachedCredential, readCheckoutKind, READ_ONLY_KIT_KIND, PUBLICATION_SPACE_KIND,
 } from "../git-credential.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -115,14 +118,39 @@ export function readStdin() {
  *   establish?: typeof establishSession,
  *   checkout?: typeof checkoutTenant,
  *   mintReadOnly?: typeof mintReadOnlyAlias,
+ *   mintSpace?: typeof mintPublicationSpace,
  * }} [opts]
  * @returns {Promise<{username:string,password:string}|null>}
  */
 export async function mintOrCacheCredential({
   env = process.env, cwd = process.cwd(), expectedHost = null,
   createClient = createMcpClient, establish = establishSession, checkout = checkoutTenant,
-  mintReadOnly = mintReadOnlyAlias,
+  mintReadOnly = mintReadOnlyAlias, mintSpace = mintPublicationSpace,
 } = {}) {
+  const recorded = recordedCheckout(cwd);
+  if (recorded?.kind === "invalid") return null; // a half-recorded space mints nothing, never the store's
+  if (recorded?.kind === PUBLICATION_SPACE_KIND) {
+    if (expectedHost && !hostMatches(recorded.originUrl, expectedHost)) return null;
+    const baseUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+    const client = createClient(baseUrl);
+    try {
+      await establish(client, { env });
+    } catch {
+      return null;
+    }
+    try {
+      const scoped = await scopeToTenant(client, recorded.tenant);
+      const res = await mintSpace(scoped, {
+        id: recorded.spaceId, mount: "", visibility: "public",
+        source: { forge: "", repo: recorded.repo, defaultBranch: "" },
+      });
+      const cred = splitAuthedRemote(res.gitRemote || "");
+      return cred ? { username: cred.username, password: cred.token } : null;
+    } catch (e) {
+      if (e instanceof CliError) console.error(formatError(e));
+      return null;
+    }
+  }
   const kit = kitCheckout(cwd);
   if (kit) {
     if (expectedHost && !hostMatches(kit.originUrl, expectedHost)) return null;
@@ -219,6 +247,25 @@ export async function mintOrCacheCredential({
   }
 }
 
+/**
+ * The publication-space checkout `cwd` is in (or a half-recorded one: `{ kind: "invalid" }`),
+ * from the kind `tot clone` recorded; null for anything else. Never throws.
+ * @param {string} cwd
+ * @returns {{ kind: "publication-space", tenant: string, spaceId: string, repo: string, originUrl: string|null }
+ *   | { kind: "invalid" } | null}
+ */
+export function recordedCheckout(cwd) {
+  const git = (cargs) =>
+    execFileSync("git", ["-C", cwd, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  let kind;
+  try { kind = readCheckoutKind(git); } catch { return null; }
+  if (kind.kind === "invalid") return { kind: "invalid" };
+  if (kind.kind !== PUBLICATION_SPACE_KIND) return null;
+  let originUrl = null;
+  try { originUrl = git(["remote", "get-url", "origin"]).trim(); } catch { /* host check fails closed */ }
+  return { ...kind, originUrl };
+}
+
 /**
  * The read-only kit checkout `cwd` is in, from the kind `tot clone` recorded, or null when
  * it is not one (a store, a loose dir, not a repo). Never throws.

package/src/commands/pr.mjs

@@ -17,6 +17,12 @@
  * `candidate_status` / `candidate_close` tools. Dependency-free (global fetch +
  * `git`).
  *
+ * A STORE SPLIT ACROSS REPOSITORIES. In a checkout that records mounted publication spaces
+ * (`tot clone`), `tot pr list` also routes every changed file — the root's and each
+ * `spaces/<id>/` checkout's — to the repository that ships it, lists each space repository's
+ * open candidates, and names any root change whose URL a mounted space serves (it would never
+ * reach a visitor).
+ *
  * OPERATOR MODE. `tot pr list --tenant <t>` lists a tenant's OPEN
  * candidate queue WITHOUT a checkout — the read-only companion to `tot ship --pr <N>
  * --tenant <t>`. It reuses that command's exact transport: the SAME `GET /api/changes`
@@ -24,6 +30,9 @@
  * `normalizeChangesQueue` from ship.mjs). `view`/`close` stay developer-only.
  */
 import { execFileSync } from "node:child_process";
+import {
+  readWorkspaceTopology, routeWorkspaceChanges, spaceDir, workspaceChangedFiles,
+} from "../publication-spaces.mjs";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { fail } from "../errors.mjs";
@@ -294,6 +303,56 @@ export async function runPrListOperator({ tenant, secret, storefrontUrl = null }
   return 0;
 }
 
+/**
+ * The per-repository view of a split store: each repository's changed files (not yet submitted)
+ * and, for a mounted space, its open candidates. Silent for a checkout that records no spaces.
+ * @param {string} workspace
+ * @param {{ scoped: { callTool: (name: string, args?: any) => Promise<any> }, storefrontUrl: string,
+ *   tenant: string, git?: (dir: string, args: string[]) => string }} deps
+ */
+export async function printChangesByRepository(workspace, {
+  scoped, storefrontUrl, tenant,
+  git = (dir, cargs) => {
+    try {
+      return execFileSync("git", ["-C", dir, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+    } catch {
+      return "";
+    }
+  },
+}) {
+  let topology;
+  try {
+    topology = readWorkspaceTopology(workspace);
+  } catch (e) {
+    console.log(`\n  ⚠ ${String(/** @type {any} */ (e)?.message || e)} — re-run \`tot clone --spaces\` to record it again.`);
+    return;
+  }
+  if (!topology || topology.spaces.length < 2) return;
+  const routed = routeWorkspaceChanges(topology, workspaceChangedFiles(workspace, topology, git));
+  console.log("\nChanges by owning repository:");
+  for (const { space, files } of routed.groups) {
+    const where = space.mount === "/" ? "this checkout" : `${spaceDir(space)}/, mount ${space.mount}`;
+    console.log(`  ${space.id} — ${space.source.forge}:${space.source.repo} (${where}): ` +
+      `${files.length ? `${files.length} changed file(s) not yet submitted` : "no local changes"}`);
+    for (const file of files) console.log(`      ${file}`);
+    if (space.mount === "/") continue;
+    try {
+      const open = extractCandidates(await scoped.callTool("candidate_status", { repo: space.source.repo }));
+      for (const c of open) {
+        console.log(`  ${formatCandidateLine({ ...c, previewUrl: c.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, c.prNumber) })}`);
+      }
+    } catch (e) {
+      console.log(`      (couldn't read this repository's candidates: ${String(/** @type {any} */ (e)?.message || e)})`);
+    }
+  }
+  for (const { file, owner } of routed.misrouted) {
+    console.log(`  ⚠ ${file}: its URL is served by the "${owner.id}" space (mount ${owner.mount}), so this root change never reaches a visitor — move it to ${spaceDir(owner)}/`);
+  }
+  for (const file of routed.unowned) {
+    console.log(`  ⚠ ${file}: no declared space owns this folder — it ships nowhere`);
+  }
+}
+
 /** @param {string[]} argv @param {any} ctx */
 export async function run(argv, ctx) {
   const env = process.env;
@@ -376,14 +435,15 @@ export async function run(argv, ctx) {
     if (args.sub === "list") {
       if (!candidates.length) {
         console.log(`No open candidate PRs for ${repo}. Run \`tot submit\` to open one.`);
-        return 0;
-      }
-      const active = readActiveChangeId(statePath, scope);
-      console.log(`Open candidate PRs for ${repo}:`);
-      for (const c of candidates) {
-        const previewUrl = c.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, c.prNumber);
-        console.log(formatCandidateLine({ ...c, previewUrl }, { active: !!active && c.changeId === active }));
+      } else {
+        const active = readActiveChangeId(statePath, scope);
+        console.log(`Open candidate PRs for ${repo}:`);
+        for (const c of candidates) {
+          const previewUrl = c.previewUrl ?? buildPreviewUrl(storefrontUrl, tenant, c.prNumber);
+          console.log(formatCandidateLine({ ...c, previewUrl }, { active: !!active && c.changeId === active }));
+        }
       }
+      await printChangesByRepository(workspace, { scoped, storefrontUrl, tenant });
       return 0;
     }
 

package/src/commands/ship.mjs

@@ -36,10 +36,20 @@
  *      `promote_failed` / `record_failed` (a partial failure, recoverable by
  *      re-running `tot ship`, never a false live claim).
  *
+ * A STORE SPLIT ACROSS REPOSITORIES ships as ONE release. Each mounted publication space (a
+ * `/blog` or `/docs` served from its own repository) publishes through its own reviewed path, so
+ * the plan also reads the tenant's declared spaces (`GET /api/publication-spaces`) and lists, per
+ * repository, what this release takes live: every space whose candidate is APPROVED and is not
+ * what live already serves is activated (`POST /api/publication-spaces/<id>/activate`, the same
+ * reviewed transition the admin Publish tab performs) under the same single confirm; a candidate
+ * still awaiting review is named as not in this release. The space list comes from the platform,
+ * never from the checkout.
+ *
  * TRANSPORT: operators/CI may use a Bearer operator secret. A signed-in owner or
  * developer instead mints a storefront viewer session from their OWN `tot login`
  * identity; the server still enforces the live owner / `ship-on-behalf` grant.
  */
+import { createHash } from "node:crypto";
 import { fail } from "../errors.mjs";
 import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
@@ -81,6 +91,10 @@ const USAGE = `tot ship — publish the tenant's CURRENT GREEN AGGREGATE to live
   VERIFIED live truth — never a false "shipped" — surfacing a refusal or a
   recoverable partial failure honestly if it isn't.
 
+  A store split across repositories (a root plus mounted spaces such as /blog)
+  ships as ONE release: the plan lists each repository, and every space whose
+  candidate is approved is taken live under the same confirm.
+
   The candidate-level merge is the separate \`tot accept\` / \`tot merge\` verb —
   \`tot ship\` never merges.`;
 
@@ -294,6 +308,102 @@ export function refusalNextStep(reason) {
   }
 }
 
+// ─── Mounted publication spaces in the release ──────────────────────────────────
+
+/**
+ * Split the tenant's declared spaces (`GET /api/publication-spaces` rows) into what this release
+ * takes live and what it leaves out. A space is READY when its candidate is approved and live
+ * does not already serve it; a candidate awaiting review (or with changes requested) is WAITING.
+ * A space with no candidate, or whose candidate is already live, has nothing to release. Pure.
+ * @param {any} rows
+ * @returns {{ ready: Array<{ spaceId: string, mount: string, versionId: string, sourceSha: string,
+ *   liveVersionId: string|null, activate: { targetVersionId: string, expectedSourceSha: string,
+ *   expectedArtifactDigest: string, expectedRevision: number } }>,
+ *   waiting: Array<{ spaceId: string, mount: string, versionId: string, why: string }> }}
+ */
+export function spaceReleasePlan(rows) {
+  const ready = [];
+  const waiting = [];
+  for (const row of Array.isArray(rows) ? rows : []) {
+    const candidate = row?.candidate;
+    if (!candidate || typeof row.id !== "string") continue;
+    const mount = row.routes?.canonicalMount ?? row.canonicalMount ?? "?";
+    if (candidate.live?.state === "current") continue;
+    const decision = candidate.review?.decision;
+    const activate = candidate.actions?.activate;
+    if (decision === "approved" && activate && typeof activate.targetVersionId === "string") {
+      ready.push({
+        spaceId: row.id, mount, versionId: candidate.versionId, sourceSha: String(candidate.sourceSha ?? ""),
+        liveVersionId: candidate.live?.versionId ?? null, activate,
+      });
+    } else {
+      waiting.push({
+        spaceId: row.id, mount, versionId: candidate.versionId,
+        why: decision === "changes-requested" ? "changes requested in review" : "awaiting review",
+      });
+    }
+  }
+  return { ready, waiting };
+}
+
+/** The plan lines naming each repository's part of the release. Pure. */
+export function spaceReleaseLines(release) {
+  const lines = [];
+  if (release.ready.length) {
+    lines.push("  publication spaces going live in this release:");
+    for (const space of release.ready) {
+      lines.push(`    ${space.mount} (${space.spaceId}): ${space.versionId} @ ${space.sourceSha.slice(0, 8)}` +
+        `${space.liveVersionId ? ` — replaces live ${space.liveVersionId}` : " — first live version"}`);
+    }
+  }
+  if (release.waiting.length) {
+    lines.push("  not in this release:");
+    for (const space of release.waiting) {
+      lines.push(`    ${space.mount} (${space.spaceId}): ${space.versionId} — ${space.why} (review it on the store's admin Publish tab)`);
+    }
+  }
+  return lines;
+}
+
+/** A deterministic transition id, so a retried ship of the same release is idempotent. Pure. */
+export function spaceTransitionId(space) {
+  const digest = createHash("sha256")
+    .update(`${space.spaceId}\0${space.activate.targetVersionId}\0${space.activate.expectedRevision}`)
+    .digest("hex").slice(0, 24);
+  return `cli-ship.${digest}`;
+}
+
+/** Read the tenant's declared spaces for the release; null when the store reports none. Never throws. */
+async function readSpaceRelease({ base, authHeaders, fetchImpl }) {
+  try {
+    const res = await fetchImpl(`${base}/api/publication-spaces`, { method: "GET", headers: authHeaders });
+    const body = await readJsonSafe(res);
+    if (!res.ok || body?.ok !== true) return null;
+    return spaceReleasePlan(body.spaces);
+  } catch {
+    return null;
+  }
+}
+
+/** Activate one approved space candidate; returns a one-line honest outcome. Never throws. */
+async function activateSpace({ base, authHeaders, fetchImpl, space }) {
+  try {
+    const res = await fetchImpl(`${base}/api/publication-spaces/${encodeURIComponent(space.spaceId)}/activate`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...authHeaders },
+      body: JSON.stringify({ transitionId: spaceTransitionId(space), ...space.activate }),
+    });
+    const body = await readJsonSafe(res);
+    if (res.ok && body?.ok === true) return { ok: true, line: `  ✓ ${space.mount} (${space.spaceId}) is live: ${space.versionId}` };
+    if (body?.committed === true) {
+      return { ok: false, line: `  ⏳ ${space.mount} (${space.spaceId}): selected ${space.versionId}; delivery is still confirming — re-run \`tot ship\` to confirm` };
+    }
+    return { ok: false, line: `  ✗ ${space.mount} (${space.spaceId}) did not go live: ${body?.error || `HTTP ${res.status}`}` };
+  } catch (e) {
+    return { ok: false, line: `  ✗ ${space.mount} (${space.spaceId}) did not go live: ${String(/** @type {any} */ (e)?.message || e)}` };
+  }
+}
+
 /** Read a fetch Response body as JSON, tolerating a non-JSON/empty body. */
 async function readJsonSafe(res) {
   try {
@@ -386,7 +496,9 @@ export async function runShip(
     return 1;
   }
   const plan = normalizeShipPlan(planData);
-  if (!plan.ok) {
+  // The tenant's mounted publication spaces ride the same release (see the file header).
+  const spaces = (await readSpaceRelease({ base, authHeaders, fetchImpl })) ?? { ready: [], waiting: [] };
+  if (!plan.ok && !spaces.ready.length) {
     console.error(fail(plan.message, refusalNextStep(plan.reason)));
     // A not-green / no-passed-run refusal is exactly what the doctor diagnoses —
     // name the changes keeping the aggregate red right here.
@@ -397,23 +509,28 @@ export async function runShip(
   // 2. Print the EXACT plan via the shared affordance, then require ONE
   //    explicit confirm (`--yes` non-interactive; a non-TTY without it refuses).
   const liveUrl = liveUrlFor(tenant);
-  const planLines = planForAction({
-    action: "ship",
-    tenant,
-    pinnedSha: plan.pinnedSha,
-    artifactDigest: plan.artifactDigest,
-    includedPrs: plan.includedPrs,
-    rollbackTarget: plan.rollbackTarget,
-    paywall: plan.paywall,
-    targets: { live: liveUrl },
-  });
+  const planLines = plan.ok
+    ? planForAction({
+      action: "ship",
+      tenant,
+      pinnedSha: plan.pinnedSha,
+      artifactDigest: plan.artifactDigest,
+      includedPrs: plan.includedPrs,
+      rollbackTarget: plan.rollbackTarget,
+      paywall: plan.paywall,
+      targets: { live: liveUrl },
+    })
+    : [`  whole-site aggregate: not in this release — ${plan.message}`];
+  planLines.push(...spaceReleaseLines(spaces));
   if (acceptQualityReason) {
     planLines.push("  quality findings: accept this exact revision and continue");
     planLines.push(`  acceptance reason: ${acceptQualityReason.trim() || "(missing)"}`);
   }
   const { confirmed, reason } = await confirmPlan(planLines, {
     yes,
-    question: `Ship ${tenant}'s current green aggregate live?`,
+    question: spaces.ready.length
+      ? `Ship this release of ${tenant} live (${[...(plan.ok ? ["the green aggregate"] : []), ...spaces.ready.map((s) => s.mount)].join(", ")})?`
+      : `Ship ${tenant}'s current green aggregate live?`,
   });
   if (!confirmed) {
     if (reason === "non-tty") {
@@ -459,6 +576,21 @@ export async function runShip(
     console.log("  ✓ quality findings accepted for this revision; continuing the publish.");
   }
 
+  // Each approved space goes live through its own reviewed transition, under the confirm above.
+  const releaseSpaces = async () => {
+    let allLive = true;
+    for (const space of spaces.ready) {
+      const outcome = await activateSpace({ base, authHeaders, fetchImpl, space });
+      if (!outcome.ok) allLive = false;
+      (outcome.ok ? console.log : console.error)(outcome.line);
+    }
+    return allLive;
+  };
+  if (!plan.ok) {
+    console.log(`\n  Shipping ${tenant}'s publication spaces (the whole-site aggregate is not in this release):`);
+    return (await releaseSpaces()) ? 0 : 1;
+  }
+
   // 3. SHIP — the human go-live gate (confirmGoLive) plus the reviewed pin, so a
   //    STALE plan (the aggregate moved / the artifact changed since GET) is
   //    refused rather than shipping something nobody reviewed.
@@ -504,7 +636,8 @@ export async function runShip(
 
   const code = reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
   if (code !== 0) await surfaceDoctor();
-  return code;
+  const spacesLive = spaces.ready.length ? await releaseSpaces() : true;
+  return code !== 0 ? code : spacesLive ? 0 : 1;
 }
 
 /**

package/src/commands/validate.mjs

@@ -10,26 +10,34 @@
  *   tot validate <tenant>        (inside the monorepo) lint tenants/<tenant>/
  *   tot validate --workspace DIR lint a specific checkout directory
  *   tot validate --json          machine-readable findings
+ *   tot validate --owner <path>  name the repository that owns a URL path
+ *
+ * A checkout whose tenant has mounted publication spaces (its `.tot/publication-spaces.json`, which
+ * `tot clone` records) also reports root files whose URL a mounted space owns.
  *
  * Exit 0 = no errors (warnings allowed); 1 = one or more errors; 2 = usage / no target.
  */
-import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
 import { validateTenant, ERROR, WARN, printLoudAdvisories } from "../validate.mjs";
 import { validateVisualParityClosure } from "../visual-parity.mjs";
 import { fail } from "../errors.mjs";
 import { tenantDirSegments } from "../tenant-dirs.mjs";
+import {
+  describeOwner, readWorkspaceTopology, rootFilesOwnedByMounts, TOPOLOGY_FILE,
+} from "../publication-spaces.mjs";
 
 const mergeFindings = (...groups) => [...new Map(groups.flat().map((item) => [JSON.stringify(item), item])).values()]
   .sort((a, b) => `${a.file}\0${a.rule}\0${a.message}`.localeCompare(`${b.file}\0${b.rule}\0${b.message}`));
 
 function parseArgs(argv) {
-  const a = { tenant: null, workspace: null, json: false, help: false, profile: null, profileSpecified: false };
+  const a = { tenant: null, workspace: null, json: false, help: false, profile: null, profileSpecified: false, owner: null };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--workspace") a.workspace = argv[++i];
     else if (t === "--profile") { a.profileSpecified = true; a.profile = argv[++i] ?? null; }
     else if (t === "--json") a.json = true;
+    else if (t === "--owner") a.owner = argv[++i] ?? "";
     else if (t === "--help" || t === "-h") a.help = true;
     else if (!t.startsWith("--") && !a.tenant) a.tenant = t;
   }
@@ -42,7 +50,70 @@ const USAGE = `tot validate — lint your store before you submit
   tot validate <tenant>         (inside the monorepo) lint tenants/<tenant>/
   tot validate --workspace <dir>  lint a specific checkout directory
   tot validate --profile visual-parity  close portable page/asset/link migration scope
-  tot validate --json           machine-readable findings`;
+  tot validate --json           machine-readable findings
+  tot validate --owner <path>   which repository owns a URL path (the root, or a mounted space)`;
+
+/** Every file under `<dir>/content/`, relative to `dir`. */
+function contentFiles(dir) {
+  const out = [];
+  const walk = (abs) => {
+    let entries;
+    try { entries = readdirSync(abs, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const full = join(abs, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) out.push(relative(dir, full).split(sep).join("/"));
+    }
+  };
+  walk(join(dir, "content"));
+  return out.sort();
+}
+
+/**
+ * The workspace's recorded topology, or an error string when it is unreadable.
+ * @returns {{ topology: import("../publication-spaces.mjs").Topology | null } | { error: string }}
+ */
+function topologyFor(dir) {
+  try {
+    return { topology: readWorkspaceTopology(dir) };
+  } catch (e) {
+    return { error: String(/** @type {any} */ (e)?.message || e) };
+  }
+}
+
+/** `tot validate --owner <path>`: name the repository that owns a URL path. */
+function runOwner(args, dir) {
+  const read = topologyFor(dir);
+  if ("error" in read) {
+    console.error(fail(read.error, "re-run `tot clone <tenant>` to record the topology again"));
+    return 2;
+  }
+  if (!read.topology) {
+    console.error(fail(
+      `this checkout records no publication topology (${TOPOLOGY_FILE})`,
+      "`tot clone <tenant>` records it — until then every path is the root repository's",
+    ));
+    return 2;
+  }
+  const owner = describeOwner(read.topology, /** @type {string} */ (args.owner));
+  if (!owner) {
+    console.error(fail(`"${args.owner}" is not a URL path`, "tot validate --owner /blog/my-post"));
+    return 2;
+  }
+  if (args.json) {
+    console.log(JSON.stringify(owner, null, 2));
+    return 0;
+  }
+  if (!owner.spaceId) {
+    console.log(`${owner.path} is a platform path — no repository serves it.`);
+    return 0;
+  }
+  const kind = owner.mount === "/" ? "the root space" : `the mounted space "${owner.spaceId}" (mount ${owner.mount}${owner.via === "alias" ? ", via an alias" : ""})`;
+  console.log(`${owner.path} is owned by ${kind}`);
+  console.log(`  repository: ${owner.repo}`);
+  console.log(`  edit it in: ${owner.dir === "." ? "this checkout" : `${owner.dir}/`}`);
+  return 0;
+}
 
 /**
  * Resolve the tenant directory + id + scope to validate, from args + context.
@@ -84,6 +155,8 @@ export function run(argv, ctx) {
     return 2;
   }
 
+  if (args.owner !== null) return runOwner(args, dir);
+
   if (args.profileSpecified && args.profile !== "visual-parity") {
     console.error(fail(`unknown validation profile: ${args.profile}`, "use --profile visual-parity"));
     return 2;
@@ -96,13 +169,21 @@ export function run(argv, ctx) {
     // arbitrary --workspace <dir> stays conservative (unless its config resolves the host).
     mode: args.workspace ? "workspace" : "monorepo",
   });
+  const topology = topologyFor(dir);
+  const spaceFindings = "error" in topology
+    ? [{ level: ERROR, rule: "publication-topology", file: TOPOLOGY_FILE, message: topology.error,
+      fix: "re-run `tot clone <tenant>` to record the topology again" }]
+    : topology.topology ? rootFilesOwnedByMounts(topology.topology, contentFiles(dir)) : [];
+  const withSpaces = spaceFindings.length
+    ? { ok: baseline.ok && !spaceFindings.some((item) => item.level === ERROR), findings: mergeFindings(baseline.findings, spaceFindings) }
+    : baseline;
   const result = args.profile === "visual-parity"
     ? (() => {
       const parity = validateVisualParityClosure(dir, { tenantId: target.tenantId ?? undefined });
-      const findings = mergeFindings(baseline.findings, parity.findings);
+      const findings = mergeFindings(withSpaces.findings, parity.findings);
       return { ok: !findings.some((item) => item.level === ERROR), findings };
     })()
-    : baseline;
+    : withSpaces;
   const { ok, findings } = result;
 
   if (args.json) {

package/src/git-credential.mjs

@@ -151,11 +151,17 @@ export function dropCachedCredential(filePath) {
 }
 
 /** The checkout kinds `tot` records in a checkout's local git config. A tenant store
- *  carries none (it is recognized by its `.tot/config.json`); a read-only kit clone is
- *  recorded explicitly, because nothing else in it says what to mint. */
+ *  carries none (it is recognized by its `.tot/config.json`); a read-only kit clone and a
+ *  mounted publication space are recorded explicitly, because nothing else in them says what
+ *  to mint — a space repository carries a `.tot/config.json` naming its tenant, which would
+ *  otherwise mint the ROOT repository's credential for it. */
 export const CHECKOUT_KIND_KEY = "tot.checkoutKind";
 export const READ_TARGET_KEY = "tot.readTarget";
 export const READ_ONLY_KIT_KIND = "read-only-kit";
+export const PUBLICATION_SPACE_KIND = "publication-space";
+export const SPACE_TENANT_KEY = "tot.spaceTenant";
+export const SPACE_ID_KEY = "tot.spaceId";
+export const SPACE_REPO_KEY = "tot.spaceRepo";
 
 /**
  * Record in a freshly cloned checkout that it is a read-only kit clone of `target`, so
@@ -169,18 +175,43 @@ export function recordReadOnlyKitCheckout(git, target) {
   git(["config", "--local", READ_TARGET_KEY, target]);
 }
 
+/**
+ * Record in a freshly cloned checkout that it is the mounted publication space `spaceId` of
+ * `tenant`, whose repository is `repo`, so `tot git-credential` mints its credential through
+ * `publication_checkout` and never as the tenant's root store. Throws on a git failure.
+ * @param {(cargs: string[]) => unknown} git  a `git -C <checkout>` runner
+ * @param {{ tenant: string, spaceId: string, repo: string }} space
+ */
+export function recordPublicationSpaceCheckout(git, { tenant, spaceId, repo }) {
+  git(["config", "--local", CHECKOUT_KIND_KEY, PUBLICATION_SPACE_KIND]);
+  git(["config", "--local", SPACE_TENANT_KEY, tenant]);
+  git(["config", "--local", SPACE_ID_KEY, spaceId]);
+  git(["config", "--local", SPACE_REPO_KEY, repo]);
+}
+
 /**
  * Read which kind of checkout `git` runs in: `{ kind: "read-only-kit", target }` for a
- * recorded kit clone, else `{ kind: "store" }` (the default; the store path then applies
- * its own checks). An unrecorded or unreadable config is a store, never a kit.
+ * recorded kit clone, `{ kind: "publication-space", tenant, spaceId, repo }` for a recorded
+ * space, else `{ kind: "store" }` (the default; the store path then applies its own checks).
+ * An unrecorded config is a store. A space record missing a field is `{ kind: "invalid" }`:
+ * it must mint nothing, never fall back to the store's credential.
  * @param {(cargs: string[]) => string} git
- * @returns {{ kind: "read-only-kit", target: string } | { kind: "store" }}
+ * @returns {{ kind: "read-only-kit", target: string } |
+ *   { kind: "publication-space", tenant: string, spaceId: string, repo: string } |
+ *   { kind: "invalid" } | { kind: "store" }}
  */
 export function readCheckoutKind(git) {
   const get = (key) => {
     try { return String(git(["config", "--local", "--get", key])).trim(); } catch { return ""; }
   };
-  if (get(CHECKOUT_KIND_KEY) !== READ_ONLY_KIT_KIND) return { kind: "store" };
+  const kind = get(CHECKOUT_KIND_KEY);
+  if (kind === PUBLICATION_SPACE_KIND) {
+    const tenant = get(SPACE_TENANT_KEY);
+    const spaceId = get(SPACE_ID_KEY);
+    const repo = get(SPACE_REPO_KEY);
+    return tenant && spaceId && repo ? { kind: PUBLICATION_SPACE_KIND, tenant, spaceId, repo } : { kind: "invalid" };
+  }
+  if (kind !== READ_ONLY_KIT_KIND) return { kind: "store" };
   const target = get(READ_TARGET_KEY);
   return target ? { kind: READ_ONLY_KIT_KIND, target } : { kind: "store" };
 }

package/src/publication-spaces.mjs

@@ -24,6 +24,18 @@ export const SPACES_DIR = "spaces";
 export const TOPOLOGY_FILE = ".tot/publication-spaces.json";
 export const TOPOLOGY_VERSION = 1;
 
+/**
+ * Platform-owned paths no space serves (packages/public-runtime PUBLICATION_SPACE_RESERVED_MOUNTS;
+ * the ownership parity test holds the two equal).
+ */
+export const PLATFORM_PATHS = Object.freeze([
+  "/.well-known", "/__evidence", "/__preview", "/_a", "/_astro", "/_style-guide", "/admin", "/api",
+  "/apps", "/assets", "/auth", "/brand", "/capabilities", "/cockpit", "/dashboard", "/dev",
+  "/favicon.svg", "/health", "/js", "/feed.json", "/llms.txt", "/publication-discovery",
+  "/search-index.json", "/sitemap.xml", "/platform", "/preview", "/products", "/collections",
+  "/search", "/saved", "/robots.txt", "/shared", "/style-guide", "/tenants",
+]);
+
 const SPACE_ID = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/;
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 
@@ -145,15 +157,17 @@ export function mountedSpaces(topology) {
 }
 
 /**
- * Which space owns a URL path: the longest canonical mount (or alias) that owns it, else the root.
- * Returns null for a path that cannot be read as a URL path.
+ * Which space owns a URL path: none for a platform path (`/api`, `/admin`, ...), else the longest
+ * canonical mount (or alias) that owns it, else the root. Null for a path that cannot be read as one.
  * @param {Topology} topology
  * @param {string} urlPath
- * @returns {{ space: TopologySpace, via: "mount"|"alias"|"root" } | null}
+ * @returns {{ space: TopologySpace, via: "mount"|"alias"|"root" } | { space: null, via: "platform" } | null}
  */
 export function owningSpace(topology, urlPath) {
   const path = normalizeRequestPath(urlPath);
   if (path === null) return null;
+  const folded = path.toLowerCase();
+  if (PLATFORM_PATHS.some((reserved) => mountMatchesPath(reserved, folded))) return { space: null, via: "platform" };
   /** @type {{ space: TopologySpace, via: "mount"|"alias", mount: string } | null} */
   let best = null;
   for (const space of topology.spaces) {
@@ -221,3 +235,145 @@ export function excludeFromRootRepo(workspace, patterns) {
   if (!missing.length) return;
   appendFileSync(file, `${current && !current.endsWith("\n") ? "\n" : ""}${missing.join("\n")}\n`);
 }
+
+/** The post collections a space can carry; each is served under its base path (default: its name). */
+export const COLLECTIONS = ["blog", "the-build"];
+
+/**
+ * The URL path a ROOT checkout file renders at, for the files whose URL the layout fixes:
+ * `content/pages-html/<slug>.html` and `content/pages/<slug>.json` at `/<slug>`, a collection's
+ * files under its base path. Null for files with no URL of their own (theme, chrome, assets).
+ * @param {TopologySpace} root
+ * @param {string} relPath  path relative to the root checkout
+ */
+export function rootFileUrlPath(root, relPath) {
+  const rel = String(relPath).replace(/\\/g, "/");
+  let m = /^content\/pages-html\/(.+)\.html$/.exec(rel) ?? /^content\/pages\/(.+)\.json$/.exec(rel);
+  if (m) return `/${m[1]}`;
+  m = /^content\/([^/]+)\//.exec(rel);
+  if (m && COLLECTIONS.includes(m[1])) {
+    const base = root.collections?.[m[1]] ?? m[1];
+    return base ? `/${base.replace(/^\/+|\/+$/g, "")}` : null;
+  }
+  return null;
+}
+
+/**
+ * Root files whose URL a mounted space owns. Visitors get the space's page at that URL, never the
+ * root's, so the file is dead weight in the root and a change to it ships nowhere.
+ * @param {Topology} topology
+ * @param {string[]} rootFiles  paths relative to the root checkout
+ * @returns {Array<{ level: "warn", rule: string, file: string, message: string, fix: string }>}
+ */
+export function rootFilesOwnedByMounts(topology, rootFiles) {
+  const root = rootSpace(topology);
+  const findings = [];
+  for (const file of rootFiles) {
+    const urlPath = rootFileUrlPath(root, file);
+    if (!urlPath) continue;
+    const owner = owningSpace(topology, urlPath);
+    if (!owner || !owner.space || owner.space.mount === "/") continue;
+    findings.push({
+      level: /** @type {"warn"} */ ("warn"),
+      rule: "publication-space-owns-url",
+      file,
+      message: `${urlPath} is served by the mounted space "${owner.space.id}" (${owner.space.source.forge}:${owner.space.source.repo}, mount ${owner.space.mount}), so this root file never reaches a visitor.`,
+      fix: `move it into ${spaceDir(owner.space)}/ (the "${owner.space.id}" repository), or delete it from the root`,
+    });
+  }
+  return findings;
+}
+
+/**
+ * Who owns a URL path. `spaceId` is null for a platform path, which no repository serves.
+ * @param {Topology} topology @param {string} urlPath
+ * @returns {{ path: string, spaceId: string|null, mount: string|null, via: string, repo: string|null, dir: string|null } | null}
+ */
+export function describeOwner(topology, urlPath) {
+  const owner = owningSpace(topology, urlPath);
+  if (!owner) return null;
+  const { space, via } = owner;
+  if (!space) {
+    return { path: /** @type {string} */ (normalizeRequestPath(urlPath)), spaceId: null, mount: null, via, repo: null, dir: null };
+  }
+  return {
+    path: /** @type {string} */ (normalizeRequestPath(urlPath)),
+    spaceId: space.id,
+    mount: space.mount,
+    via,
+    repo: `${space.source.forge}:${space.source.repo}`,
+    dir: spaceDir(space) || ".",
+  };
+}
+
+/**
+ * Route changed workspace files to the repository that ships them. Paths are relative to the
+ * root checkout (a space's files as `spaces/<id>/...`). Each file lands in its owning space's
+ * group; a root file whose URL a mounted space owns is ALSO named as misrouted (it ships with the
+ * root and still never reaches a visitor); a file under `spaces/` naming no declared space is
+ * unowned. Pure.
+ * @param {Topology} topology
+ * @param {string[]} files
+ * @returns {{ groups: Array<{ space: TopologySpace, files: string[] }>,
+ *   misrouted: Array<{ file: string, owner: TopologySpace }>, unowned: string[] }}
+ */
+export function routeWorkspaceChanges(topology, files) {
+  const root = rootSpace(topology);
+  /** @type {Map<string, string[]>} */
+  const byId = new Map(topology.spaces.map((space) => [space.id, []]));
+  const misrouted = [];
+  const unowned = [];
+  for (const file of files) {
+    const owner = spaceForWorkspaceFile(topology, file);
+    if (!owner) { unowned.push(file); continue; }
+    /** @type {string[]} */ (byId.get(owner.space.id)).push(file);
+    if (owner.space.mount === "/") {
+      const urlPath = rootFileUrlPath(root, file);
+      const served = urlPath ? owningSpace(topology, urlPath) : null;
+      if (served?.space && served.space.mount !== "/") misrouted.push({ file, owner: served.space });
+    }
+  }
+  return {
+    groups: topology.spaces.map((space) => ({ space, files: /** @type {string[]} */ (byId.get(space.id)) })),
+    misrouted,
+    unowned,
+  };
+}
+
+/**
+ * Parse `git status --porcelain=v1 -z` into changed paths (a rename yields its new path). Pure.
+ * @param {string} out
+ * @returns {string[]}
+ */
+export function parsePorcelainZ(out) {
+  const parts = String(out).split("\0");
+  const paths = [];
+  for (let i = 0; i < parts.length; i++) {
+    const entry = parts[i];
+    if (!entry || entry.length < 4) continue;
+    const status = entry.slice(0, 2);
+    paths.push(entry.slice(3));
+    if (status[0] === "R" || status[0] === "C") i++; // the next field is the rename's source
+  }
+  return paths;
+}
+
+/**
+ * Every changed file in a workspace, relative to the root checkout: the root repository's own
+ * changes plus each cloned space's (`spaces/<id>/...`). `git(dir, args)` runs git in `dir`.
+ * @param {string} workspace
+ * @param {Topology} topology
+ * @param {(dir: string, args: string[]) => string} git
+ * @returns {string[]}
+ */
+export function workspaceChangedFiles(workspace, topology, git) {
+  const files = parsePorcelainZ(git(workspace, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]));
+  for (const space of mountedSpaces(topology)) {
+    const dir = join(workspace, spaceDir(space));
+    if (!existsSync(join(dir, ".git"))) continue;
+    for (const file of parsePorcelainZ(git(dir, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]))) {
+      files.push(`${spaceDir(space)}/${file}`);
+    }
+  }
+  return files;
+}

package/src/tenant-scope.mjs

@@ -26,7 +26,8 @@ import { CliError } from "./errors.mjs";
  * Tools whose `tenant` argument is the tenant the call acts on. Action-harness tools get the
  * argument from `registerActionTool` (tot-mcp `src/modules/mcp/tools/action-tool.ts`), which
  * resolves it through `resolveCallTenant` and echoes the tenant it acted on in every success
- * result; `tenant_checkout` declares the same argument itself and echoes it too.
+ * result; `tenant_checkout` and `publication_checkout` declare the same argument themselves and
+ * echo the tenant too.
  */
 export const TENANT_SCOPED_TOOLS = Object.freeze(new Set([
   "candidate_open",
@@ -35,6 +36,7 @@ export const TENANT_SCOPED_TOOLS = Object.freeze(new Set([
   "preview_status",
   "promotion_rollback",
   "promotion_status",
+  "publication_checkout",
   "tenant_checkout",
 ]));