@tokenoftrust/cli 1.4.1 → 1.5.0

package/README.md

@@ -19,6 +19,11 @@ install, no hand-provisioned AWS credentials. (Docker remains available as a
 fallback — `tot dev --docker` — or automatically if the native artifact can't
 be fetched.)
 
+For Storefront Private App contracts, examples, and LLM-ready developer material, start at
+[Storefront Devkit — Apps / Private](https://github.com/tokenoftrust/storefront-devkit/tree/main/apps/private).
+The `tot app` commands use the CLI's self-contained helper; they do not require a separately
+published npm SDK.
+
 ## Commands
 
 | Command | Status | What it does |

package/bin/tot.mjs

@@ -2,30 +2,9 @@
 /**
  * `tot` — the Token of Trust developer CLI.
  *
- * One command a developer learns to go from an invite to a running store:
- *
- *   tot start                 invite → running store in one command      ← built (orchestrates the below, value-first)
- *   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 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 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                  publish the current green aggregate live  ← built (GET/POST /api/changes/ship → b09 orchestrator; exact plan + y/N confirm; waits for VERIFIED live truth)
- *   tot accept / tot merge    queue a PR into the preview aggregate      ← built (b08: plan + y/N confirm → POST /api/changes/integrate = b07 queue enqueue; NO merge-to-main, NO go-live; refuses non-TTY without --yes)
- *   tot sync                  fetch `preview` + merge it into your branch ← built (b16: the common accept-conflict recovery path; local-only, stops safely on conflict)
- *   tot rollback [<version>]  instant re-point to a prior live version  ← built (u3 promotion_status/promotion_rollback seam; diff + y/N confirm; refuses non-TTY / ineligible)
- *   tot pr                    list / view / close your candidate PRs    ← built (candidate_status/candidate_close; gh-pr-shaped)
- *   tot branches              full branch-cleanup report (every branch, not just open PRs)  ← built (b14: candidate_list)
- *   tot cleanup               owner-confirmed branch GC (deletes terminal branches only)     ← built (b14: candidate_list + candidate_delete; --dry-run classifies only)
- *   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)
- *   tot app scaffold/dev      build + locally exercise a Private App        ← built (offline; see src/commands/app/)
- *   tot help                  this help
+ * One command a developer learns to go from an invite to a running store. The
+ * user-facing command list is the single source of truth in `COMMANDS` below;
+ * `usage()` renders it, so add new commands there — never in a second list.
  *
  * Context-aware (see src/context.mjs): the same `tot` does the right thing from
  * inside the storefront monorepo, from inside a standalone tenant checkout, or
@@ -54,38 +33,47 @@ const VERSION = (() => {
   }
 })();
 
+// Single source of truth for the user-facing command list. `usage()` renders
+// it and the file header points here; keep new commands in this one array so the
+// help output can't drift from a second hand-maintained copy. `invocation` is the
+// text after `tot ` (including any argument hint); `blurb` is the one-line help.
+const COMMANDS = [
+  { invocation: "start", blurb: "invite → running store in one command (start here)" },
+  { invocation: "login", blurb: "sign in to Token of Trust" },
+  { invocation: "logout", blurb: "sign out (clear the cached session)" },
+  { invocation: "whoami", blurb: "show who you're signed in as" },
+  { invocation: "link", blurb: "link your identity so your stores resolve" },
+  { invocation: "grants", blurb: "capability/tier/expiry per store you can act on" },
+  { invocation: "clone [<tenant>]", blurb: "clone a store you can build on" },
+  { invocation: "validate", blurb: "lint your store before you submit" },
+  { invocation: "dev", blurb: "run your store locally with save→reload" },
+  { invocation: "preview", blurb: "push your store to a reviewable preview" },
+  { invocation: "ship", blurb: "publish the tenant's current green aggregate live (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)" },
+  { invocation: "revert --preview <PR|sha>", blurb: "remove already-integrated content from the preview aggregate via a new revert commit — no force-reset (plan → confirm → revert)" },
+  { invocation: "hotfix --pr <N>", blurb: "OWNER-ONLY exception: release an urgent fix from main to live, bypassing unshipped preview work (plan → confirm → release → auto forward-integrate)", },
+  { invocation: "go-live", blurb: "cut the apex domain over to the storefront (readiness → confirm → cutover)" },
+  { invocation: "pr", blurb: "list / view / close your candidate PRs" },
+  { invocation: "branches", blurb: "full branch-cleanup report — every branch, any PR state, cleanup eligibility" },
+  { invocation: "cleanup", blurb: "owner-confirmed branch GC (--dry-run to classify only; deletes terminal branches only)" },
+  { invocation: "doctor", blurb: "check this machine is ready" },
+  { invocation: "ideas", blurb: "copy-paste AI prompts that reliably wow" },
+  { invocation: 'feedback "<msg>"', blurb: "send feedback to Token of Trust (attaches recent activity)" },
+  { invocation: "app scaffold <name>", blurb: "scaffold a Storefront Private App" },
+  { invocation: "app dev ...", blurb: "local, offline Private App webhook/manifest/JWT harness" },
+  { invocation: "help", blurb: "show this help" },
+  { invocation: "--version", blurb: "print the CLI version" },
+];
+
 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");
   console.log(`
 tot — Token of Trust developer CLI
 
-  tot start                 invite → running store in one command (start here)
-  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 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 preview               push your store to a reviewable preview
-  tot ship                  publish the tenant's current green aggregate live (plan → confirm → ship)
-  tot accept / tot merge    queue a PR into the preview aggregate — operator verb, no go-live (plan → confirm → integrate)
-  tot sync                  fetch \`preview\` and merge it into your local branch (accept-conflict recovery)
-  tot rollback [<version>]  instant re-point to a prior live version (list → confirm → rollback)
-  tot revert --preview <PR|sha>  remove already-integrated content from the preview aggregate via a new revert commit — no force-reset (plan → confirm → revert)
-  tot hotfix --pr <N>       OWNER-ONLY exception: release an urgent fix from main to live, bypassing unshipped preview work (plan → confirm → release → auto forward-integrate)
-  tot retire                evict a candidate PR's preview to reclaim space — operator verb, rebuildable (plan → confirm → evict)
-  tot go-live               cut the apex domain over to the storefront (readiness → confirm → cutover)
-  tot pr                    list / view / close your candidate PRs
-  tot branches              full branch-cleanup report — every branch, any PR state, cleanup eligibility
-  tot cleanup               owner-confirmed branch GC (--dry-run to classify only; deletes terminal branches only)
-  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)
-  tot app scaffold <name>   scaffold a Storefront Private App
-  tot app dev ...           local, offline Private App webhook/manifest/JWT harness
-  tot help                  show this help
-  tot --version             print the CLI version
+${lines}
 
 Run \`tot <command> --help\` for command-specific options.
 `);
@@ -117,12 +105,12 @@ async function dispatch(cmd, rest, ctx) {
 
   if (cmd === "logout") {
     const { run } = await import("../src/commands/logout.mjs");
-    return run(rest, ctx);
+    return /** @type {any} */ (run)(rest, ctx);
   }
 
   if (cmd === "feedback") {
     const { run } = await import("../src/commands/feedback.mjs");
-    return run(rest, ctx);
+    return /** @type {any} */ (run)(rest, ctx);
   }
 
   if (cmd === "whoami") {
@@ -158,7 +146,7 @@ async function dispatch(cmd, rest, ctx) {
   // Plumbing, not a developer-facing verb (like git's own credential helpers,
   // never listed in `git help`) — `tot clone` configures it as this checkout's
   // `credential.helper`, and git alone invokes it (get/store/erase) on every
-  // fetch/push. See src/commands/git-credential.mjs's header (unit u10).
+  // fetch/push. See src/commands/git-credential.mjs's header.
   if (cmd === "git-credential") {
     const { run } = await import("../src/commands/git-credential.mjs");
     return run(rest, ctx);
@@ -192,17 +180,17 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
-  // `accept` queue-integrates a PR into the protected `preview` aggregate (b08) —
+  // `accept` queue-integrates a PR into the protected `preview` aggregate —
   // NO merge-to-main, NO go-live; going live is `tot ship`, which publishes the
-  // whole current GREEN AGGREGATE (b10). Backed by POST /api/changes/integrate
-  // (b07's TenantIntegrationQueue.enqueue); see accept.mjs's header. `merge` is a
+  // whole current GREEN AGGREGATE. Backed by POST /api/changes/integrate
+  // (TenantIntegrationQueue.enqueue); see accept.mjs's header. `merge` is a
   // first-class alias, not a teaching nudge: both dispatch straight to the same command.
   if (cmd === "accept" || cmd === "merge") {
     const { run } = await import("../src/commands/accept.mjs");
     return run(rest, ctx);
   }
 
-  // `sync` is the common accept-conflict recovery path (P1 item 12): fetches the
+  // `sync` is the common accept-conflict recovery path: fetches the
   // protected `preview` branch and merges it into the developer's local branch so
   // they can resolve locally, then re-`tot preview`. Purely local — no push, no
   // MCP call, never touches the shared `preview`/`main` refs themselves. See
@@ -218,34 +206,26 @@ async function dispatch(cmd, rest, ctx) {
   }
 
   // `revert --preview <PR|integration-sha>` removes already-integrated content from
-  // the protected `preview` aggregate via a NEW auditable revert commit (b21) — NO
-  // force-reset, NO touch to main/live. Backed by POST /api/changes/revert (b07's
-  // TenantIntegrationQueue.enqueueRevert). To undo something already LIVE, that's
+  // the protected `preview` aggregate via a NEW auditable revert commit — NO
+  // force-reset, NO touch to main/live. Backed by POST /api/changes/revert
+  // (TenantIntegrationQueue.enqueueRevert). To undo something already LIVE, that's
   // `tot rollback`, not this. See revert.mjs's header.
   if (cmd === "revert") {
     const { run } = await import("../src/commands/revert.mjs");
     return run(rest, ctx);
   }
 
-  // `hotfix --pr <N>` is the OWNER-ONLY EXCEPTION lane (b22): release an urgent fix
+  // `hotfix --pr <N>` is the OWNER-ONLY EXCEPTION lane: release an urgent fix
   // from `main` to live while `preview` still holds other unshipped work, EXCLUDING
   // that unshipped preview head, then automatically forward-integrate main → preview
   // and re-validate. It is DELIBERATELY a distinct verb — never a `--base main` flag
   // on `tot ship` (which publishes the whole green preview aggregate). Backed by
-  // GET/POST /api/changes/hotfix → b22's HotfixOrchestrator. See hotfix.mjs's header.
+  // GET/POST /api/changes/hotfix → HotfixOrchestrator. See hotfix.mjs's header.
   if (cmd === "hotfix") {
     const { run } = await import("../src/commands/hotfix.mjs");
     return run(rest, ctx);
   }
 
-  // `retire` evicts a candidate PR's hosted preview to reclaim space (unit U7) —
-  // a DISTINCT operator verb from `accept`/reject: retire touches no change
-  // lifecycle and is reversible-by-rebuild (`tot preview build`). See retire.mjs.
-  if (cmd === "retire") {
-    const { run } = await import("../src/commands/retire.mjs");
-    return run(rest, ctx);
-  }
-
   if (cmd === "go-live") {
     const { run } = await import("../src/commands/go-live.mjs");
     return run(rest, ctx);
@@ -257,16 +237,15 @@ async function dispatch(cmd, rest, ctx) {
   }
 
   // `branches` is the FULL branch-cleanup report (every branch, any PR state) —
-  // distinct from `tot pr list`, which only shows OPEN PRs (P1 item 9). Read-only;
+  // distinct from `tot pr list`, which only shows OPEN PRs. Read-only;
   // always safe to run, and the report `tot cleanup` reuses before deleting anything.
   if (cmd === "branches") {
     const { run } = await import("../src/commands/branches.mjs");
     return run(rest, ctx);
   }
 
-  // `cleanup` is owner-confirmed BRANCH GC (P1 items 9/10) — an irreversible git-ref
-  // delete, distinct from `tot retire`'s hosted-preview eviction (rebuildable, no
-  // branch touched). `--dry-run` classifies and prints; it never deletes. Age alone
+  // `cleanup` is owner-confirmed BRANCH GC — an irreversible git-ref
+  // delete for terminal candidates. `--dry-run` classifies and prints; it never deletes. Age alone
   // never makes a branch eligible; main/preview are always kept; orphans are
   // quarantined, never auto-deleted. See cleanup.mjs's header.
   if (cmd === "cleanup") {
@@ -329,7 +308,7 @@ async function main() {
   let code = 0;
   let errMsg = null;
 
-  // D3: emit `cli.command.invoked` on start — best-effort, a SILENT no-op without a
+  // Emit `cli.command.invoked` on start — best-effort, a SILENT no-op without a
   // hosted-bridge credential (never a network call / never blocks). Fired without
   // await so it adds no latency to the command; settled alongside the result below.
   const invokedEmit = emitActivity({
@@ -358,9 +337,9 @@ async function main() {
       ms: durationMs,
       ...(errMsg ? { err: String(errMsg).slice(0, 200) } : {}),
     });
-    // D3: emit `cli.command.result` (exit code + duration + a bounded/redacted
+    // Emit `cli.command.result` (exit code + duration + a bounded/redacted
     // rendered field). The house-style error text is capped + run through the JS
-    // redaction mirror; per the D0 catalog the `cli.*` rendered lane is empty-
+    // redaction mirror; per the activity catalog the `cli.*` rendered lane is empty-
     // allowlisted, so it's DROPPED by design (the safe default for a high-volume
     // action) — the emit path still exercises the mirror. Bounded-await here (with
     // the invoked emit) so a live bridge flushes before the process exits; a no-op

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "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",
@@ -36,7 +36,12 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "typescript": "^5.6.3"
+  },
   "scripts": {
+    "typecheck": "tsc --noEmit",
     "test": "node --test",
     "prepublishOnly": "node ../../scripts/build/check-cli-clean.mjs ."
   }

package/src/activity.mjs

@@ -1,11 +1,11 @@
 /**
- * emitActivity — the CLI's operational-activity emitter (card D3).
+ * emitActivity — the CLI's operational-activity emitter.
  *
- * This is a hand-maintained JS MIRROR of the D0 actor×action contract that lives,
+ * This is a hand-maintained JS MIRROR of the actor×action contract that lives,
  * in TypeScript, in `packages/public-runtime/src/activity/` (event.ts / catalog.ts
  * / redaction.ts). The CLI is published to npm STANDALONE and is deliberately pure
  * JS with NO dependency on `@tot/public-runtime` (a TS package) — see that module's
- * README ("Consuming this from the downstream cards → D3"). So instead of importing
+ * README ("Consuming this from the downstream cards"). So instead of importing
  * the contract, we mirror the slice of it the CLI needs, and a keep-in-step test
  * (activity-mirror.test.mjs) fails LOUDLY the moment this mirror drifts from the TS
  * source of truth (the same discipline as no-gitea-links.test.mjs).
@@ -191,6 +191,7 @@ export function redactPayload(action, raw) {
  * and runs the raw payload through redactPayload() so the returned event's payload
  * is already default-denied + canary-scanned. Throws only on an out-of-catalog
  * (non-`cli.*`) action — a programming error.
+ * @param {{ action: any, actor?: any, source?: string, outcome?: any, scope?: any, payload?: any, at?: any, id?: any }} input
  */
 export function createActivityEvent({ action, actor, source = "cli", outcome, scope, payload, at, id }) {
   if (!isCliActionKey(action)) throw new Error(`activity: unknown CLI action "${action}" (not in the CLI mirror catalog)`);
@@ -217,7 +218,7 @@ export function createActivityEvent({ action, actor, source = "cli", outcome, sc
 const EMIT_TIMEOUT_MS = 1500;
 
 /**
- * The ONE activity-telemetry kill switch (card D8) — the SAME flag name the server
+ * The ONE activity-telemetry kill switch — the SAME flag name the server
  * honours (`apps/storefront/src/lib/activity/killSwitch.ts`). Set
  * `ACTIVITY_TELEMETRY_DISABLED=1` (or true/yes/on) and every CLI emit becomes a silent
  * no-op — no build, no redaction, no network — while the command itself runs unchanged
@@ -253,9 +254,9 @@ export function resolveActivityBridge(env = process.env) {
 
 /**
  * The event's actor — kind `dev` (or `agent` when the caller signals an automated
- * run) with an OPAQUE, non-reversible id, per the D0 contract (actor.id in the core
+ * run) with an OPAQUE, non-reversible id, per the contract (actor.id in the core
  * zone is NEVER raw PII). Until the canonical pseudonymization salt lands (an open
- * question owned by D1/D4 — see redaction.ts header), we derive the id from an
+ * question — see redaction.ts header), we derive the id from an
  * already-opaque handle: the masked emailHint if present, else a one-way hash of the
  * bridge token, else "anonymous". Never reversible, never raw PII.
  */
@@ -279,7 +280,7 @@ export function resolveActor(env = process.env) {
  * event it triggers share one trace (matching the existing feedback/heartbeat use).
  */
 function resolveScope(env = process.env, extra = {}) {
-  const scope = { ...extra };
+  const scope = /** @type {any} */ ({ ...extra });
   try {
     const creds = readCredentials(defaultCredentialsPath(env));
     if (creds?.traceId && !scope.traceId) scope.traceId = creds.traceId;
@@ -298,10 +299,10 @@ function resolveScope(env = process.env, extra = {}) {
  * Returns `{ sent, event?, report? }` so callers/tests can assert what would be
  * emitted without any network. `fetchImpl` and `bridge` are injectable for tests.
  *
- * @param {{ action: string, outcome: object, actor?: object, scope?: object,
+ * @param {{ action?: string, outcome?: object, actor?: object, scope?: object,
  *   payload?: object, source?: string, env?: NodeJS.ProcessEnv,
- *   fetchImpl?: typeof fetch, bridge?: {url:string,token:string}|null }} input
- * @returns {Promise<{sent:boolean, event?:object, report?:object}>}
+ *   fetchImpl?: typeof fetch, bridge?: {url:string,token:string}|null }} [input]
+ * @returns {Promise<{sent:boolean, event?:object, report?:object, disabled?:boolean}>}
  */
 export async function emitActivity({
   action,
@@ -315,7 +316,7 @@ export async function emitActivity({
   bridge,
 } = {}) {
   try {
-    // Kill switch (D8): telemetry off ⇒ true no-op (no build/redaction/network),
+    // Kill switch: telemetry off ⇒ true no-op (no build/redaction/network),
     // fail-open — the command is unaffected.
     if (isActivityDisabled(env)) return { sent: false, disabled: true };
     const resolvedBridge = bridge !== undefined ? bridge : resolveActivityBridge(env);
@@ -344,8 +345,8 @@ export async function emitActivity({
           "content-type": "application/json",
           authorization: `Bearer ${resolvedBridge.token}`,
         },
-        // `event: "activity"` tags the stream for the bridge/D4 ingest to route,
-        // alongside the D0 envelope. Best-effort — an older bridge that doesn't
+        // `event: "activity"` tags the stream for the bridge ingest to route,
+        // alongside the standard envelope. Best-effort — an older bridge that doesn't
         // recognize it simply ignores the post.
         body: JSON.stringify({ event: "activity", ...event }),
         signal: controller.signal,
@@ -366,7 +367,7 @@ export async function emitActivity({
  * Cap + surface a bit of rendered output for a command-result event. The full raw
  * stdout is NEVER stored — this caps to MAX_VALUE_LEN and hands the string to the
  * redaction mirror via payload.rendered. NB the `cli.command.*` actions carry an
- * EMPTY renderedAllow in the D0 catalog, so this string is DROPPED at redaction by
+ * EMPTY renderedAllow in the action catalog, so this string is DROPPED at redaction by
  * design (the safe default for a high-volume action) — running it through the
  * mirror is the belt-and-suspenders the contract prescribes, and keeps the emit
  * path honest if the allowlist ever opens. Pure.

package/src/app-scaffold.mjs

@@ -1,6 +1,6 @@
 /**
- * Private App scaffolding — `tot app scaffold <name>` (PrivateApps epic D6
- * Chunk C). Mirrors `sample.mjs`'s `scaffoldSample`: materialize a bundled
+ * Private App scaffolding — `tot app scaffold <name>` (PrivateApps epic).
+ * Mirrors `sample.mjs`'s `scaffoldSample`: materialize a bundled
  * template onto disk, idempotently, fully offline. No login, no MCP, no
  * network — a developer building a Storefront Private App gets a runnable
  * skeleton before they've registered anything with Token of Trust.
@@ -63,14 +63,14 @@ export function scaffoldApp(destDir, { force = false, log = () => {} } = {}) {
     const err = new Error(
       `${dir} isn't empty and isn't an app scaffold — scaffold into an empty directory (or pass a new name)`,
     );
-    err.code = "ENOTEMPTY_APP";
+    /** @type {any} */ (err).code ="ENOTEMPTY_APP";
     throw err;
   }
 
   const template = appTemplateDir();
   if (!existsSync(template)) {
     const err = new Error("the private-app template isn't available in this release yet — it's coming soon.");
-    err.code = "TEMPLATE_UNAVAILABLE";
+    /** @type {any} */ (err).code ="TEMPLATE_UNAVAILABLE";
     throw err;
   }
 

package/src/auth.mjs

@@ -26,8 +26,13 @@ import { refreshAccessToken, credentialsFromToken } from "./oauth.mjs";
 
 /** Thrown when no provider can authenticate — carries actionable guidance. */
 export class AuthUnavailableError extends Error {
-  constructor(message, { hint, reason } = {}) {
+  /**
+   * @param {string} message
+   * @param {{ hint?: string|null, reason?: string|null }} [opts]
+   */
+  constructor(message, opts = {}) {
     super(message);
+    const { hint, reason } = opts;
     this.name = "AuthUnavailableError";
     this.hint = hint || null;
     this.reason = reason || null;
@@ -72,7 +77,10 @@ export function credentialEmailHint(creds) {
   );
 }
 
-/** Hosted cockpit URL for regenerating local CLI credentials, when we cached one. */
+/**
+ * Hosted cockpit URL for regenerating local CLI credentials, when we cached one.
+ * @param {any} activityUrl @param {string|null} [emailHint]
+ */
 export function cockpitRecoveryUrl(activityUrl, emailHint = null) {
   if (!activityUrl) return null;
   try {
@@ -125,10 +133,10 @@ export function warnLegacyOperatorEnv(env = process.env, warn = (m) => console.e
  * every tool call carries the developer identity. Fails with a clear next step
  * (never a stack trace) when there's no usable session.
  *
- * @param {import("./mcp.mjs").createMcpClient extends (...a:any)=>infer R ? R : any} client
+ * @param {(import("./mcp.mjs").createMcpClient extends (...a:any)=>infer R ? R : any)|null} client
  * @param {NodeJS.ProcessEnv} env
  * @param {{ fetchImpl?: typeof fetch, now?: number }} [deps] injectable for tests
- * @returns {Promise<{ identity: "developer", appDomain: null, token: string }>}
+ * @returns {Promise<{ identity: "developer", appDomain: null, token: string, email?: string|null }>}
  */
 export async function resolveDeveloperSession(client, env, deps = {}) {
   const { fetchImpl = fetch, now = Date.now() } = deps;
@@ -219,7 +227,7 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
  * are never read for auth.
  *
  * @param {ReturnType<import("./mcp.mjs").createMcpClient>} client
- * @param {{ env?: NodeJS.ProcessEnv, initialize?: () => Promise<any> }} [opts]
+ * @param {{ env?: NodeJS.ProcessEnv, initialize?: () => Promise<any>, prefer?: string }} [opts]
  * @returns {Promise<{ identity: "developer", appDomain: null, token: string, email?: string|null }>}
  */
 export async function establishSession(client, opts = {}) {

package/src/candidate-state.mjs

@@ -7,14 +7,14 @@
  * 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
+ *   - `tot submit --fork-candidate` 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
+ * DEFAULT branch and `<mcpUrl>::<repo>::<branch>` on any other (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
@@ -123,7 +123,7 @@ export function clearActiveChangeId(filePath, { mcpUrl, repo, branch }) {
 /**
  * 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
+ * 6 random hex chars (so two `--fork-candidate` runs never collide); tests inject a fixed
  * suffix. Pure given `suffix`.
  */
 export function mintFreshChangeId(baseId, suffix = randomBytes(3).toString("hex")) {