@tokenoftrust/cli 1.4.0-rc.1 → 1.4.0-rc.11

package/README.md

@@ -5,11 +5,12 @@ One command to go from a Token of Trust invite to a running store.
 ```sh
 npm i -g @tokenoftrust/cli
 
-tot checkout                 # list the stores you can build on
-tot checkout <tenant> --clone ./my-store
+tot clone                    # list the stores you can build on
+tot clone <tenant> my-store  # mirrors `git clone`; dir defaults to <tenant>
 cd my-store
 tot dev                      # run it locally with save→reload — no Docker needed
-tot submit                   # (coming) submit it for preview
+tot preview                  # bundle your edits into a compliance-reviewed preview
+tot ship                     # promote a reconciled preview live (diff + one confirm)
 ```
 
 **Prerequisites: Node.js and an invite. Nothing else.** `tot dev` downloads the
@@ -22,10 +23,12 @@ be fetched.)
 
 | Command | Status | What it does |
 | --- | --- | --- |
-| `tot checkout [<tenant>]` | **built** | Clone a store you're entitled to build on, with an authenticated remote configured. No arg → list your stores. |
-| `tot validate` | next | Lint your store before you submit. |
+| `tot clone [<tenant>] [<dir>]` | **built** | Clone a store you're entitled to build on (mirrors `git clone`), with an authenticated remote configured. Dir defaults to `<tenant>`. No arg → list your stores. |
+| `tot validate` | next | Lint your store before you preview. |
 | `tot dev` | **built** | Run your store locally with save→reload — NATIVELY (no Docker; falls back to it with `--docker` or automatically if the native artifact isn't available). |
-| `tot submit` | next | Submit your store for preview (pushes the preview ref, reports the reconcile/compliance verdict + preview URL). |
+| `tot preview` | **built** | Bundle your edits into a compliance-reviewed preview (validates, auto-commits the known content trees, pushes the preview ref, opens/updates a candidate PR, reports the reconcile/compliance verdict + preview URL). `tot submit` / `tot deploy` still work as teaching aliases for this same flow. |
+| `tot ship` | **built** | Promote a reconciled preview live: always shows a diff-vs-live and asks for one `[y/N]` confirm (no `--yes`, refuses outside a terminal); records an approval request if you're not authorised to ship yourself. |
+| `tot pr [list\|view\|close]` | **built** | See and manage the candidate PRs `tot preview` opens (`gh pr`-shaped). |
 | `tot doctor` | built | Check this machine is ready and show which context `tot` detected. |
 
 ## Context-aware
@@ -34,7 +37,7 @@ The same `tot` does the right thing wherever you run it (walks up like `git`):
 
 - **storefront monorepo** — a full platform checkout;
 - **tenant checkout** — a standalone `content/ public/ theme.json .tot/config.json` clone (tenant read from `.tot/config.json`);
-- **loose** — anywhere else; `tot checkout <tenant> --clone <dir>` gets you a checkout.
+- **loose** — anywhere else; `tot clone <tenant>` gets you a checkout.
 
 `tot doctor` prints the detected context.
 
@@ -42,8 +45,8 @@ The same `tot` does the right thing wherever you run it (walks up like `git`):
 
 `tot` talks to the Token of Trust MCP (default `https://mcp.tokenoftrust.com`, override with `--mcp` or `MCP_BASE_URL`). It is **single-plane**: the only identity is **you**, signed in against the MCP over OAuth.
 
-- Run `tot login` once — it opens your browser (or falls back to a device code on a headless box), you sign in as yourself, and the session is cached at `~/.tot/credentials.json` and refreshed silently. Every later command (`tot checkout`, `tot start`, `tot submit`, …) runs as you, with no re-auth. Entitlement is derived server-side from your ToT memberships.
-- Not signed in? On a terminal, `tot start` / `tot checkout` **offer to sign you in right there** and continue in-flow — no "run `tot login`, then re-run".
+- Run `tot login` once — it opens your browser (or falls back to a device code on a headless box), you sign in as yourself, and the session is cached at `~/.tot/credentials.json` and refreshed silently. Every later command (`tot clone`, `tot start`, `tot preview`, `tot ship`, …) runs as you, with no re-auth. Entitlement is derived server-side from your ToT memberships.
+- Not signed in? On a terminal, `tot start` / `tot clone` **offer to sign you in right there** and continue in-flow — no "run `tot login`, then re-run".
 - The old operator env-triple (`TOT_API_KEY` / `TOT_SECRET_KEY` / `TOT_APP_DOMAIN`) **no longer signs the CLI in** — tot-mcp went OAuth-first on 2026-07-23. If those vars are set, `tot` prints a one-line advisory and uses your `tot login` session anyway; it never reads them for auth.
 
 ### Optional: multiple identities at once (`TOT_PROFILE`)

package/bin/tot.mjs

@@ -8,11 +8,14 @@
  *   tot login                 sign in to Token of Trust (OAuth)          ← built (MCP OAuth PKCE loopback; caches ~/.tot/credentials.json)
  *   tot logout                sign out (clear the cached session)        ← built (deletes ~/.tot/credentials.json; local-only, no server revoke)
  *   tot whoami                who you're signed in as                    ← built
+ *   tot link                  link your identity to the ToT broker (resolve store scope)  ← built
  *   tot grants                capability/tier/expiry per store you can act on  ← built (introspection diagnostics)
- *   tot checkout [<tenant>]   clone a store you can build on            ← built
+ *   tot clone [<tenant>]      clone a store you can build on            ← built
  *   tot validate              lint your store before you submit         ← built
  *   tot dev                   run your store locally with save→reload   ← built (monorepo: host astro; standalone: runs the published runner image)
- *   tot submit                submit your store for preview             ← built (validate + push preview ref; MCP preview_status read-back)
+ *   tot preview               push your store to a reviewable preview   ← built (validate + push preview ref; MCP preview_status read-back). `submit`/`deploy` are teaching aliases.
+ *   tot ship                  promote a reconciled preview live         ← built (diff-vs-live + y/N confirm → change_accept; refuses non-TTY / unreconciled)
+ *   tot pr                    list / view / close your candidate PRs    ← built (candidate_status/candidate_close; gh-pr-shaped)
  *   tot doctor                check this machine is ready
  *   tot ideas                 copy-paste AI prompts that reliably wow
  *   tot feedback              send a note to ToT + your recent CLI activity  ← built (activity-log.mjs → feedback_submit MCP tool)
@@ -24,7 +27,7 @@
  * from anywhere else. Every command receives the detected context.
  *
  * This package is `@tokenoftrust/cli` (bin `tot`). Its heaviest command, `tot dev`,
- * fetches the published storefront runner; `tot checkout/validate/submit` are
+ * fetches the published storefront runner; `tot clone/validate/submit` are
  * pure Node. Dependency-free by design so `npm i -g @tokenoftrust/cli` stays light.
  */
 import "../src/ensure-node.mjs"; // hard Node-version gate — must stay first (see the module doc)
@@ -34,7 +37,7 @@ import { printError } from "../src/errors.mjs";
 import { recordActivity, redactArgs } from "../src/activity-log.mjs";
 import { maybeNotifyUpdate } from "../src/update-check.mjs";
 
-const BUILD_ORDER = ["checkout", "validate", "dev", "submit"];
+const BUILD_ORDER = ["clone", "validate", "dev", "preview"];
 
 // CLI version (stamped into the activity log). Read from our own package.json; best-effort.
 const VERSION = (() => {
@@ -53,11 +56,14 @@ tot — Token of Trust developer CLI
   tot login                 sign in to Token of Trust
   tot logout                sign out (clear the cached session)
   tot whoami                show who you're signed in as
+  tot link                  link your identity so your stores resolve
   tot grants                capability/tier/expiry per store you can act on
-  tot checkout [<tenant>]   clone a store you can build on
+  tot clone [<tenant>]      clone a store you can build on
   tot validate              lint your store before you submit
   tot dev                   run your store locally with save→reload
-  tot submit                submit your store for preview
+  tot preview               push your store to a reviewable preview
+  tot ship                  promote a reconciled preview live (diff → confirm → ship)
+  tot pr                    list / view / close your candidate PRs
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow
   tot feedback "<msg>"      send feedback to Token of Trust (attaches recent activity)
@@ -109,6 +115,11 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "link") {
+    const { run } = await import("../src/commands/link.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "doctor") {
     const { run } = await import("../src/commands/doctor.mjs");
     return run(rest, ctx);
@@ -124,8 +135,8 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
-  if (cmd === "checkout") {
-    const { run } = await import("../src/commands/checkout.mjs");
+  if (cmd === "clone") {
+    const { run } = await import("../src/commands/clone.mjs");
     return run(rest, ctx);
   }
 
@@ -139,8 +150,26 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
-  if (cmd === "submit") {
-    const { run } = await import("../src/commands/submit.mjs");
+  // dev → preview → ship. `preview` is the first-class verb; `submit`/`deploy`
+  // reach the SAME preview flow as teaching aliases (preview.mjs prints a one-line
+  // hint nudging the developer onto `tot preview` / `tot ship`).
+  if (cmd === "preview") {
+    const { run } = await import("../src/commands/preview.mjs");
+    return run(rest, ctx);
+  }
+
+  if (cmd === "submit" || cmd === "deploy") {
+    const { run } = await import("../src/commands/preview.mjs");
+    return run(rest, ctx, { alias: cmd });
+  }
+
+  if (cmd === "ship") {
+    const { run } = await import("../src/commands/ship.mjs");
+    return run(rest, ctx);
+  }
+
+  if (cmd === "pr") {
+    const { run } = await import("../src/commands/pr.mjs");
     return run(rest, ctx);
   }
 
@@ -149,10 +178,21 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  // `checkout` was deliberately freed up: it's no longer a tot verb precisely so it
+  // can mean what it means in git. Point both ways rather than a bare "unknown".
+  if (cmd === "checkout") {
+    console.error(
+      "`tot checkout` isn't a tot command — `checkout` now means what it does in git.\n\n" +
+        "  • switch branches / restore files in your store:  git checkout <ref>\n" +
+        "  • clone a store you can build on:                 tot clone <tenant>\n",
+    );
+    return 2;
+  }
+
   if (BUILD_ORDER.includes(cmd)) {
     console.error(
       `\`tot ${cmd}\` isn't built yet.\n\n` +
-        `Build order: ${BUILD_ORDER.map((c) => (c === "checkout" ? `${c}✓` : c)).join(" → ")}.\n` +
+        `Build order: ${BUILD_ORDER.map((c) => (c === "clone" ? `${c}✓` : c)).join(" → ")}.\n` +
         `Inside a storefront checkout you can use the in-repo scripts today ` +
         `(e.g. \`pnpm tot ${cmd}\`).`,
     );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.1",
-  "description": "Token of Trust developer CLI — check out a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
+  "version": "1.4.0-rc.11",
+  "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",
   "homepage": "https://www.tokenoftrust.com",

package/src/candidate-state.mjs

@@ -0,0 +1,137 @@
+/**
+ * The "active candidate" pointer — which open candidate PR a plain `tot submit`
+ * updates, per forge repo.
+ *
+ * `tot submit` is idempotent on a STABLE changeId (`deriveChangeId`) so a re-submit
+ * updates the same PR by default — the common case needs NO state and writes
+ * nothing here (backward-compatible with the stateless original). This file only
+ * records a DIVERGENCE from that stable default:
+ *
+ *   - `tot submit --new` forks a fresh candidate and remembers it here, so the
+ *     NEXT plain `tot submit` keeps updating the NEW PR (like pushing more commits
+ *     to a `gh pr` branch), not the old one; and
+ *   - a terminal-roll (the active candidate was merged/closed) records the fresh
+ *     candidate it rolled to, so you're never wedged submitting to a dead PR.
+ *
+ * ONE file, `~/.tot/candidates.json`, a map keyed by `<mcpUrl>::<repo>` on the
+ * DEFAULT branch and `<mcpUrl>::<repo>::<branch>` on any other (u4 — branch-bound
+ * candidates): a different MCP, repo, OR non-default git branch is a different
+ * candidate namespace, so a feature branch gets its OWN candidate PR instead of
+ * fighting main's over the same handle. The default branch deliberately keeps the
+ * OLD branch-less key so existing devs' state is byte-identical (zero migration),
+ * and a branch-scoped read that misses FALLS BACK to that old key so state written
+ * before the rekey (or by the default branch) is never orphaned. Same atomic-write
+ * discipline as last-tenant.mjs (0600 in a 0700 dir, write-tmp-then-rename).
+ * Dependency-free (node:fs/os/path). `TOT_HOME` overrides home (tests).
+ */
+import {
+  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
+/** Absolute path to the active-candidate map for this machine. */
+export function defaultCandidateStatePath(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "candidates.json");
+}
+
+/**
+ * Branch names that are treated as the repo's DEFAULT — their candidates keep the
+ * OLD branch-less key (zero migration). A null/empty/detached ("HEAD") branch is
+ * treated as default too, so an environment where the branch can't be resolved
+ * degrades to exactly today's behavior rather than minting a spurious namespace.
+ */
+export const DEFAULT_BRANCHES = new Set(["main", "master"]);
+
+/** Whether `branch` should use the OLD branch-less candidate key. Pure. */
+export function isDefaultBranch(branch) {
+  return !branch || branch === "HEAD" || DEFAULT_BRANCHES.has(branch);
+}
+
+/** The legacy (branch-less) namespace key — today's exact `<mcpUrl>::<repo>`. */
+function legacyStateKey(mcpUrl, repo) {
+  return `${mcpUrl}::${repo}`;
+}
+
+/**
+ * Namespace key for one (MCP, repo, branch) candidate pointer. The DEFAULT branch
+ * keeps the legacy `<mcpUrl>::<repo>` key byte-for-byte (zero migration); any other
+ * branch gets its own `<mcpUrl>::<repo>::<branch>` namespace. Pure.
+ */
+function stateKey(mcpUrl, repo, branch) {
+  return isDefaultBranch(branch) ? legacyStateKey(mcpUrl, repo) : `${mcpUrl}::${repo}::${branch}`;
+}
+
+/** Extract a usable changeId from a stored record, or null. Pure. */
+function recordChangeId(rec) {
+  return rec && typeof rec.changeId === "string" && rec.changeId ? rec.changeId : null;
+}
+
+function readMap(filePath) {
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeMap(filePath, map) {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmp = `${filePath}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(map, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, filePath);
+  chmodSync(filePath, 0o600);
+}
+
+/**
+ * The remembered active changeId for `(mcpUrl, repo, branch)`, or null when there
+ * isn't one (absent/unreadable/malformed) — a miss means "use the stable default".
+ * On a non-default branch whose branch-scoped key misses, FALLS BACK to the legacy
+ * branch-less key so state written before the rekey (or by the default branch)
+ * isn't orphaned. Never throws.
+ */
+export function readActiveChangeId(filePath, { mcpUrl, repo, branch }) {
+  const map = readMap(filePath);
+  const primary = recordChangeId(map[stateKey(mcpUrl, repo, branch)]);
+  if (primary) return primary;
+  // Legacy fallback: a branch-scoped miss reads the old branch-less key (a no-op
+  // when we're already on the default branch, which IS the legacy key).
+  if (!isDefaultBranch(branch)) return recordChangeId(map[legacyStateKey(mcpUrl, repo)]);
+  return null;
+}
+
+/** Remember `changeId` as the active candidate for `(mcpUrl, repo, branch)`, atomically. */
+export function writeActiveChangeId(filePath, { mcpUrl, repo, branch, changeId }) {
+  const map = readMap(filePath);
+  map[stateKey(mcpUrl, repo, branch)] = { changeId, updatedAt: Date.now() };
+  writeMap(filePath, map);
+}
+
+/** Forget the active candidate for `(mcpUrl, repo, branch)` (e.g. after closing it). */
+export function clearActiveChangeId(filePath, { mcpUrl, repo, branch }) {
+  const map = readMap(filePath);
+  const key = stateKey(mcpUrl, repo, branch);
+  if (key in map) {
+    delete map[key];
+    writeMap(filePath, map);
+  }
+}
+
+/**
+ * A fresh candidate handle forked from a stable base — `<baseId>-<suffix>`, still
+ * matching candidate_open's `[a-z0-9._-]` handle grammar. The suffix defaults to
+ * 6 random hex chars (so two `--new` runs never collide); tests inject a fixed
+ * suffix. Pure given `suffix`.
+ */
+export function mintFreshChangeId(baseId, suffix = randomBytes(3).toString("hex")) {
+  const safe = String(suffix).toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 12) || "new";
+  return `${baseId}-${safe}`;
+}
+
+/** Whether a forge candidate state means "no open PR to update" (rolled past). */
+export function isTerminalCandidateState(state) {
+  return state === "merged" || state === "closed";
+}

package/src/commands/{checkout.mjs → clone.mjs}

@@ -1,16 +1,23 @@
 /**
- * `tot checkout` — clone the tenant store you're entitled to build on, with an
- * authenticated remote already configured, ready for the local loop.
+ * `tot clone` — clone the tenant store you're entitled to build on, with an
+ * authenticated remote already configured, ready for the local loop. Mirrors
+ * `git clone <repo> [dir]`: the tenant is the repo, the dir defaults to the
+ * tenant name. (Named `clone`, not `checkout`, so it means what `git clone`
+ * means — materialize a local working copy — and never collides with the
+ * unrelated `git checkout` = switch-refs verb.)
  *
- *   tot checkout                      list the stores you can build on
- *   tot checkout <tenant>             show the checkout for <tenant>
- *   tot checkout <tenant> --clone DIR clone it to DIR with an authed remote
+ *   tot clone                    list the stores you can build on
+ *   tot clone <tenant>           clone into ./<tenant> (authenticated remote configured)
+ *   tot clone <tenant> <dir>     clone into <dir>
+ *   tot clone <tenant> --remote-only   just mint + print the remote, don't materialize
  *
  * This is the SAME MCP code path a developer gets when they switch to a tenant:
  * sign-in → client_switch(tenant) → tenant_checkout, where the MCP derives your
  * per-tenant Git user and mints a FRESH, single-active, repo-scoped push
- * credential (a later checkout for the same tenant rotates it). `tot` performs NO
- * privileged forge work itself — the MCP owns that.
+ * credential (a later clone for the same tenant rotates it). `tot` performs NO
+ * privileged forge work itself — the MCP owns that. ("checkout" survives only as
+ * the domain/lease term: the `tenant_checkout` MCP tool + the on-disk noun for a
+ * materialized store dir — never as a developer-facing verb.)
  *
  * Auth is the developer's own ToT identity (the cached `tot login` session,
  * resolved via src/auth.mjs). When there's no session yet and we're on a TTY, we
@@ -34,8 +41,9 @@ const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 function parseArgs(argv) {
   const a = {
     tenant: null,
+    dir: null,
     tag: "main",
-    clone: null,
+    remoteOnly: false,
     mcp: null,
     printRemote: false,
     help: false,
@@ -43,27 +51,32 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--tag") a.tag = argv[++i];
-    else if (t === "--clone") a.clone = argv[++i];
+    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 === "--help" || t === "-h") a.help = true;
-    else if (!t.startsWith("--") && !a.tenant) a.tenant = t;
+    // Positional, git-clone style: `tot clone <tenant> [<dir>]`.
+    else if (!t.startsWith("--")) {
+      if (!a.tenant) a.tenant = t;
+      else if (!a.dir) a.dir = t;
+    }
   }
   return a;
 }
 
-const USAGE = `tot checkout — clone a tenant store you can build on
+const USAGE = `tot clone — clone a tenant store you can build on (mirrors \`git clone\`)
 
-  tot checkout                        list the stores you can build on
-  tot checkout <tenant>               show the checkout for <tenant>
-  tot checkout <tenant> --clone <dir> clone it locally (authenticated remote configured)
+  tot clone                    list the stores you can build on
+  tot clone <tenant>           clone into ./<tenant> (authenticated remote configured)
+  tot clone <tenant> <dir>     clone into <dir>
 
 Options:
   --tag <tag>       which repo (repo = "<tenant>-<tag>"). Default: main.
-  --clone <dir>     git clone the authenticated remote into <dir>.
+  --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}.
-  --print-remote    also print the authenticated remote (contains a live token!).`;
+  --print-remote    with --remote-only, also print the authenticated remote
+                    (contains a live token!).`;
 
 /** Redact known secrets from any string before it hits the terminal. */
 function makeRedactor(env) {
@@ -92,6 +105,11 @@ export async function run(argv, ctx) {
     args.tenant = ctx.tenant;
   }
 
+  // git-clone semantics: unless you explicitly asked for --remote-only, cloning
+  // is the default, and the target dir defaults to the tenant name (like
+  // `git clone <url>` deriving the dir from the repo basename).
+  const cloneDir = args.remoteOnly ? null : args.dir || args.tenant;
+
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const redact = makeRedactor(env);
   const client = createMcpClient(baseUrl);
@@ -128,21 +146,21 @@ export async function run(argv, ctx) {
     const res = await checkoutTenant(client, {
       tenant: args.tenant,
       tag: args.tag,
-      cloneDir: args.clone || null,
+      cloneDir,
       redact,
     });
-    console.log(`\n+ checkout ready. repo: ${res.cloneUrl || res.publicUrl}`);
+    console.log(`\n+ ready. repo: ${res.cloneUrl || res.publicUrl}`);
 
     if (res.cloned) {
       console.log(`+ cloned. HEAD: ${res.head}`);
       console.log(`\nYour local working clone is at ${res.dir} with an authenticated remote.`);
       console.log(`  cd ${res.dir} && tot dev            # run it locally with save→reload`);
-      console.log(`  (the minted token lives in .git/config; a later checkout rotates it)`);
+      console.log(`  (the minted token lives in .git/config; a later clone rotates it)`);
       return 0;
     }
 
     console.log(`\nPublic clone URL (no credential): ${res.publicUrl}`);
-    console.log(`Re-run with --clone <dir> to clone with the authenticated remote configured.`);
+    console.log(`Drop --remote-only to clone with the authenticated remote configured.`);
     if (args.printRemote) {
       console.log(
         `\nAUTHENTICATED remote (contains a live token — handle carefully):\n${res.gitRemote}`,
@@ -164,7 +182,7 @@ export async function run(argv, ctx) {
 }
 
 /**
- * The privileged checkout core, composable in-process (used by `tot checkout`
+ * The privileged checkout core, composable in-process (used by `tot clone`
  * and by `tot start`): client_switch → tenant_checkout → optionally clone. The
  * MCP mints a fresh, repo-scoped push credential each time. Assumes `client` is
  * already initialized + has a validated session.
@@ -211,7 +229,7 @@ async function cloneRepo(gitRemote, dir, redact) {
     await git(["clone", gitRemote, dir]);
   } catch (e) {
     // Beacon the cockpit before we surface the error — covers this path for both
-    // `tot checkout` and `tot start` (which clones through here). Awaited so the
+    // `tot clone` and `tot start` (which clones through here). Awaited so the
     // packet lands before the process prints + exits; swallowed either way.
     await emitObstacle("clone-failed");
     throw new CliError(`clone failed: ${redact(String(e.stderr || e.message || e))}`, {
@@ -255,13 +273,13 @@ export function checkoutError(checkout) {
   }
   return {
     message: msg || "the store checkout couldn't be completed",
-    next: "confirm you're entitled to this store — `tot checkout` (lists your stores)",
+    next: "confirm you're entitled to this store — `tot clone` (lists your stores)",
   };
 }
 
 /**
  * Normalize the (shape-varying) `client_list` response into a plain, sorted
- * list of the stores this identity can build on. Shared by `tot checkout`'s
+ * list of the stores this identity can build on. Shared by `tot clone`'s
  * listing and `tot start`'s auto-pick so both read the same fields.
  * @param {unknown} list
  * @returns {Array<{ id: string, name: string, raw: any }>}
@@ -308,6 +326,86 @@ export function storeListError(list) {
   return null;
 }
 
+/**
+ * Extract card c1's broker-identity remediation signal from a `client_list`
+ * result. When the identity resolved ZERO stores, the server MAY carry:
+ *   - `brokerStatus`: 'unlinked' | 'unconfigured' | 'broker_error' — present only
+ *      when the empty scope is a BROKER-IDENTITY problem (not an entitlement one);
+ *      ABSENT for the genuine linked-but-zero-grants case.
+ *   - `nextAction`: a status-specific human remediation string the server owns
+ *      (single source of truth; e.g. an unlinked identity is told to finish
+ *      linking, an operator sees a diagnostic, zero-grants sees NO_TENANTS_MESSAGE).
+ * Returns { brokerStatus, nextAction } with nulls when absent. Pure + exported so
+ * it's unit-tested without any I/O.
+ * @param {unknown} list
+ * @returns {{ brokerStatus: string|null, nextAction: string|null }}
+ */
+export function brokerRemediation(list) {
+  const c = list && typeof list === "object" && !Array.isArray(list) ? list : null;
+  const brokerStatus = c && typeof c.brokerStatus === "string" ? c.brokerStatus : null;
+  const nextAction =
+    c && typeof c.nextAction === "string" && c.nextAction.trim() ? c.nextAction.trim() : null;
+  return { brokerStatus, nextAction };
+}
+
+/**
+ * Status-aware human guidance for an authenticated identity that resolved ZERO
+ * stores (card c2 — the fix for the misleading "may still be propagating / ask for
+ * a store invite" copy that dead-ended an UNLINKED identity). Driven by card c1's
+ * `brokerStatus`/`nextAction`:
+ *   - `unlinked` → the identity isn't linked to the ToT broker yet, so no scope can
+ *      resolve. This is NOT an entitlement problem — point at `tot link` (the
+ *      terminal action), NOT "ask for a store invite".
+ *   - `unconfigured` | `broker_error` → an operator/diagnostic condition; surface
+ *      the server's own `nextAction`, never "ask for an invite".
+ *   - no brokerStatus → the genuine linked-but-zero-grants case; keep the existing
+ *      "invite may still be propagating / ask for one" wording (NO_TENANTS_MESSAGE),
+ *      preferring the server's `nextAction` when present.
+ *
+ * Prefers the server's `nextAction` as the concrete `next` step (single source of
+ * truth) and falls back to sensible local copy when it's absent (older server).
+ * `linkHint` names the terminal action an unlinked identity is pointed at — the
+ * built-in `tot link`; a caller that didn't build `tot link` passes an MCP-client
+ * phrasing instead. Pure + exported so it's unit-tested without any I/O.
+ * @param {unknown} list
+ * @param {{ linkHint?: string }} [opts]
+ * @returns {{ brokerStatus: string|null, headline: string, next: string }}
+ */
+export function noStoresGuidance(list, { linkHint = "tot link" } = {}) {
+  const { brokerStatus, nextAction } = brokerRemediation(list);
+
+  if (brokerStatus === "unlinked") {
+    // The actionable terminal step beats the server's identity_link_begin/poll
+    // MCP-tool wording for a CLI user, so lead with `tot link` (c2 optional-arm
+    // directive). Fall back to the server string only if there's no link action.
+    return {
+      brokerStatus,
+      headline: "your Token of Trust identity isn't linked yet, so no stores could be resolved",
+      next: linkHint
+        ? `run \`${linkHint}\` to finish linking your identity, then re-run`
+        : nextAction || "finish linking your identity (identity_link_begin), then re-run",
+    };
+  }
+  if (brokerStatus === "unconfigured" || brokerStatus === "broker_error") {
+    // Operator/diagnostic conditions — surface the server's own words; do NOT tell
+    // the developer to "ask for an invite" (it isn't an entitlement problem).
+    return {
+      brokerStatus,
+      headline: "no stores could be resolved — the Token of Trust identity broker had a problem",
+      next: nextAction || "run `tot whoami` for details, or contact your Token of Trust operator",
+    };
+  }
+  // No brokerStatus → the genuine linked-but-zero-grants case.
+  return {
+    brokerStatus: null,
+    headline: "you have no stores to build on yet",
+    next:
+      nextAction ||
+      "if you were just invited, it may still be propagating — try again in a minute; " +
+        "otherwise ask your Token of Trust contact for a store invite (see `tot whoami`)",
+  };
+}
+
 function printClientList(list) {
   const err = storeListError(list);
   const stores = normalizeStores(list);
@@ -317,14 +415,17 @@ function printClientList(list) {
     return;
   }
   if (stores.length === 0) {
-    console.log("\nNo stores available to build on for this identity yet.");
-    console.log("If you were just invited, it may still be propagating — try again in a minute.");
-    if (list && !Array.isArray(list)) console.log(JSON.stringify(list, null, 2));
+    // Status-aware, human-readable guidance — NEVER a raw JSON dump (the old
+    // behaviour, James's 2026-07-19 failure mode).
+    const g = noStoresGuidance(list);
+    const line = g.headline.charAt(0).toUpperCase() + g.headline.slice(1);
+    console.log(`\n${line}.`);
+    console.log(`Next: ${g.next}`);
     return;
   }
   console.log("\nStores you can build on:\n");
   for (const s of stores) {
     console.log(`  ${s.id}${s.name ? `  — ${s.name}` : ""}`);
   }
-  console.log(`\nNext:  tot checkout <tenant> --clone <dir>`);
+  console.log(`\nNext:  tot clone <tenant>`);
 }