@tokenoftrust/cli 1.4.0-rc.6 → 1.4.0-rc.8

package/README.md

@@ -5,8 +5,8 @@ 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
@@ -22,7 +22,7 @@ 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 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 submit. |
 | `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). |
@@ -34,7 +34,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 +42,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 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 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

@@ -10,7 +10,7 @@
  *   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)
@@ -25,7 +25,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)
@@ -35,7 +35,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", "submit"];
 
 // CLI version (stamped into the activity log). Read from our own package.json; best-effort.
 const VERSION = (() => {
@@ -56,7 +56,7 @@ tot — Token of Trust developer CLI
   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
@@ -131,8 +131,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);
   }
 
@@ -156,10 +156,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.6",
-  "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.8",
+  "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/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 }>}
@@ -409,5 +427,5 @@ function printClientList(list) {
   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>`);
 }

package/src/commands/dev.mjs

@@ -138,7 +138,7 @@ export async function run(argv, ctx) {
     console.error(
       fail(
         "nothing to run — you're not inside a tenant checkout",
-        "tot checkout <tenant> --clone <dir>   (then `cd` in and re-run), pass --workspace <dir>, or try `tot dev --sample`",
+        "tot clone <tenant>   (then `cd` in and re-run), pass --workspace <dir>, or try `tot dev --sample`",
       ),
     );
     return 2;
@@ -194,7 +194,7 @@ async function runNativePublic(workspace, args, ctx) {
   const cfg = readWorkspaceConfig(workspace);
   if (!cfg) {
     throw new CliError(`${workspace} isn't a tenant checkout (no readable .tot/config.json)`, {
-      next: "tot checkout <tenant> --clone <dir>   (produces a runnable checkout)",
+      next: "tot clone <tenant>   (produces a runnable checkout)",
       exitCode: 2,
     });
   }
@@ -280,7 +280,7 @@ async function runNative(workspace, args, ctx) {
   const cfg = readWorkspaceConfig(workspace);
   if (!cfg) {
     throw new CliError(`${workspace} isn't a tenant checkout (no readable .tot/config.json)`, {
-      next: "tot checkout <tenant> --clone <dir>   (produces a runnable checkout)",
+      next: "tot clone <tenant>   (produces a runnable checkout)",
       exitCode: 2,
     });
   }
@@ -1240,7 +1240,7 @@ export function buildContainerPlan(workspace, args, _ctx) {
   const cfg = readWorkspaceConfig(workspace);
   if (!cfg) {
     throw new CliError(`${workspace} isn't a tenant checkout (no readable .tot/config.json)`, {
-      next: "tot checkout <tenant> --clone <dir>   (produces a runnable checkout)",
+      next: "tot clone <tenant>   (produces a runnable checkout)",
       exitCode: 2,
     });
   }

package/src/commands/doctor.mjs

@@ -1,7 +1,7 @@
 /**
  * `tot doctor` — is this machine ready to run the loop?
  *
- * Standalone (unlike the in-monorepo doctor): checks the things `tot checkout`
+ * Standalone (unlike the in-monorepo doctor): checks the things `tot clone`
  * and `tot dev`/`tot start` actually need — Node, git, an MCP URL, whether an
  * auth identity is available, and Docker — plus reports the detected context
  * so a developer knows which mode `tot` will use here.
@@ -187,7 +187,7 @@ export async function run(argv, ctx) {
   }
   console.log(
     failed === 0
-      ? "\n✔ Ready. Try: tot start   (checks out your store and runs it), or tot checkout\n"
+      ? "\n✔ Ready. Try: tot start   (checks out your store and runs it), or tot clone\n"
       : args.fix
         ? `\n✖ ${failed} check(s) still failing — see the exact next command(s) above, then re-run \`tot doctor\`.\n`
         : `\n✖ ${failed} check(s) failed — try \`tot doctor --fix\`, or fix the above, then re-run \`tot doctor\`.\n`,
@@ -199,5 +199,5 @@ function describeContext(ctx) {
   if (ctx.mode === "monorepo") return `storefront monorepo (${ctx.repoRoot})`;
   if (ctx.mode === "checkout")
     return `tenant checkout${ctx.tenant ? ` for "${ctx.tenant}"` : ""} (${ctx.workspacePath})`;
-  return "loose (not inside a checkout — `tot checkout <tenant> --clone <dir>` to get one)";
+  return "loose (not inside a checkout — `tot clone <tenant>` to get one)";
 }

package/src/commands/grants.mjs

@@ -26,7 +26,7 @@
 import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { storeListError, noStoresGuidance } from "./checkout.mjs";
+import { storeListError, noStoresGuidance } from "./clone.mjs";
 import { offerSignIn } from "./login.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
 

package/src/commands/link.mjs

@@ -4,7 +4,7 @@
  *
  * Some developers sign in fine (a valid ToT OAuth session) but their identity
  * isn't yet linked to the broker that maps a person → the tenants they can build
- * on — so `tot start` / `tot checkout` / `tot whoami` resolve ZERO stores. That's
+ * on — so `tot start` / `tot clone` / `tot whoami` resolve ZERO stores. That's
  * NOT a "you weren't invited" problem and NOT "the invite is still propagating";
  * it's a one-time link step. This command drives it end-to-end from the terminal:
  *
@@ -24,7 +24,7 @@ import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { offerSignIn } from "./login.mjs";
 import { openBrowser } from "../open.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
-import { normalizeStores } from "./checkout.mjs";
+import { normalizeStores } from "./clone.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
@@ -83,9 +83,17 @@ export function linkPollStatus(res) {
     (typeof c.status === "string" && c.status) || (typeof c.state === "string" && c.state) || "";
   const s = raw.toLowerCase();
   if (!s) return "pending";
-  if (/^(linked|complete|completed|done|ok|success|active)$/.test(s)) return "linked";
-  if (/^(pending|waiting|in_?progress|processing|started)$/.test(s)) return "pending";
-  return s; // an unknown/error status — surfaced to the caller
+  // The broker namespaces its poll status with a `link_` prefix (e.g. `link_pending`,
+  // `link_approved`, `link_denied`) — strip it before matching so a normal "still
+  // waiting" state isn't misread as an unknown/error status and doesn't abort the poll.
+  // (Regression: `link_pending` fell through to the error branch and killed `tot link`
+  // the instant the developer hadn't yet finished the browser step.)
+  const bare = s.replace(/^link[_-]/, "");
+  if (/^(linked|link|complete|completed|done|ok|success|succeeded|active|approved|granted)$/.test(bare))
+    return "linked";
+  if (/^(pending|waiting|in_?progress|processing|started|created|authorizing|polling)$/.test(bare))
+    return "pending";
+  return s; // a terminal error status (link_denied, link_expired, …) — surfaced to the caller
 }
 
 /** @param {string[]} argv @param {any} _ctx */
@@ -160,7 +168,7 @@ export async function run(argv, _ctx) {
       const stores = normalizeStores(list);
       if (stores.length) {
         console.log(`  stores you can build on: ${stores.map((s) => s.id).join(", ")}`);
-        console.log("  Next: `tot start` (or `tot checkout <tenant>`).");
+        console.log("  Next: `tot start` (or `tot clone <tenant>`).");
       } else {
         console.log("  Next: `tot start` — if it still shows no stores, ask your ToT contact for a store invite.");
       }

package/src/commands/login.mjs

@@ -4,7 +4,7 @@
  * Runs the MCP OAuth 2.1 PKCE loopback (the same ceremony `claude mcp add` runs):
  * opens the browser to the MCP's authorize page, the developer signs in with their
  * ToT identity + approves, and the loopback catches the code and exchanges it for a
- * token cached at ~/.tot/credentials.json. Every later command (`tot checkout`,
+ * token cached at ~/.tot/credentials.json. Every later command (`tot clone`,
  * `tot submit`, …) then runs as that developer with NO re-auth.
  *
  * The MCP defaults to the same target `tot submit` talks to (env MCP_BASE_URL /
@@ -109,7 +109,7 @@ const USAGE = `tot login — sign in to Token of Trust
   link a later \`tot feedback\` report to your invite + session) — not meant to be
   typed by hand.
 
-After signing in, run \`tot whoami\` to confirm, then \`tot checkout\` / \`tot submit\`.`;
+After signing in, run \`tot whoami\` to confirm, then \`tot clone\` / \`tot submit\`.`;
 
 /**
  * The core of `tot login`: run the OAuth ceremony (browser loopback, or the
@@ -270,7 +270,7 @@ export async function run(argv, _ctx) {
       cacheTraceId(env, args.traceId);
       cacheEmailHint(env, args.emailHint);
       console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
-      console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
+      console.log("  Next: `tot whoami` to confirm, or `tot clone` / `tot submit` to build.");
       return 0;
     } catch (e) {
       console.error(
@@ -288,7 +288,7 @@ export async function run(argv, _ctx) {
     await loginAndCache(mcpUrl, env, { log: (m) => console.error(m), device: args.device });
     cacheTraceId(env, args.traceId);
     console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
-    console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
+    console.log("  Next: `tot whoami` to confirm, or `tot clone` / `tot submit` to build.");
     return 0;
   } catch (e) {
     console.error(

package/src/commands/start.mjs

@@ -59,7 +59,7 @@ import { startProgress } from "../progress.mjs";
 import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
 import { readCredentials, defaultCredentialsPath } from "../token-store.mjs";
 import { collectChecks } from "./doctor.mjs";
-import { normalizeStores, storeListError, checkoutTenant, noStoresGuidance } from "./checkout.mjs";
+import { normalizeStores, storeListError, checkoutTenant, noStoresGuidance } from "./clone.mjs";
 import {
   buildContainerPlan, spawnDevContainer, dockerAvailable, tryStartDocker,
   resolveDevImage, isPrivateRegistryImage, ensureRegistryLogin,
@@ -633,7 +633,7 @@ async function ensureCheckout(client, tenant, dir, env) {
       console.log(`  ✓ reusing existing checkout ./${tenant}`);
       return;
     }
-    throw new CliError(`./${tenant} already exists and isn't a tot checkout`, {
+    throw new CliError(`./${tenant} already exists and isn't a store checkout`, {
       next: `remove it (or run \`tot start\` from an empty directory)`,
       exitCode: 2,
     });

package/src/commands/validate.mjs

@@ -68,11 +68,11 @@ export function run(argv, ctx) {
 
   const target = resolveTarget(args, ctx);
   if (target.error) {
-    console.error(fail(target.error, "tot checkout <tenant> --clone <dir>, or pass --workspace <dir>"));
+    console.error(fail(target.error, "tot clone <tenant>, or pass --workspace <dir>"));
     return 2;
   }
   if (!existsSync(target.dir)) {
-    console.error(fail(`no tenant directory at ${target.dir}`, "confirm the path, or `tot checkout <tenant> --clone <dir>`"));
+    console.error(fail(`no tenant directory at ${target.dir}`, "confirm the path, or `tot clone <tenant>`"));
     return 2;
   }
 

package/src/commands/whoami.mjs

@@ -11,7 +11,7 @@
 import { defaultCredentialsPath, readCredentials, isExpired, activeProfile } from "../token-store.mjs";
 import { establishSession } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { normalizeStores, storeListError, noStoresGuidance } from "./checkout.mjs";
+import { normalizeStores, storeListError, noStoresGuidance } from "./clone.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
 
 /**

package/src/context.mjs

@@ -6,13 +6,13 @@
  *
  *   monorepo   — inside a full storefront checkout (pnpm-workspace.yaml +
  *                apps/storefront + tenants/). This is us / a platform dev.
- *                `tot dev` here runs the in-tree astro dev; `tot checkout`
+ *                `tot dev` here runs the in-tree astro dev; `tot clone`
  *                can suggest cloning a sibling dir.
  *   checkout   — inside a STANDALONE tenant checkout: the flat, content-only
  *                shape `content/ public/ theme.json .tot/config.json` a
  *                developer clones. The tenant is read from .tot/config.json.
  *                `tot dev` here boots the bundled runner against this dir.
- *   loose      — anywhere else. `tot checkout <tenant>` still works (it's how
+ *   loose      — anywhere else. `tot clone <tenant>` still works (it's how
  *                you GET a checkout); commands that need a workspace say so.
  *
  * Detection walks UP from the cwd so `tot` works from any subdirectory of a

package/src/obstacle-beacon.cjs

@@ -1,6 +1,6 @@
 /**
  * The obstacle beacon — a fire-and-forget POST that tells the hosted cockpit a
- * `tot start` / `tot checkout` failed, so it can show the exact fix in the bridge
+ * `tot start` / `tot clone` failed, so it can show the exact fix in the bridge
  * strip (obstacle lane, server side already shipped). Best-effort telemetry that
  * rides ALONGSIDE the house-style `✗ … → next:` error; it must NEVER change,
  * delay past its timeout, or fail that error path.