@tokenoftrust/cli 1.0.0 → 1.1.0

package/src/commands/feedback.mjs

@@ -0,0 +1,176 @@
+/**
+ * `tot feedback` — send a note to Token of Trust, with your recent CLI activity
+ * attached, straight through the ToT MCP's `feedback_submit` tool.
+ *
+ * Why it exists: when the `tot` dev loop surprises you, the fastest useful report is
+ * "here's what I was doing + what happened." The bounded, secret-redacted activity
+ * log (~/.tot/activity.log) is attached in the report's `sensitive` field — private
+ * to ToT admins, never clustered or shared — so triage sees the breadcrumbs without
+ * the developer copy-pasting anything.
+ *
+ * Auth: the MCP feedback tool is authenticated, so this reuses the signed-in session
+ * (`resolveSession` → operator creds if present, else the `tot login` developer
+ * token). Not signed in → a clear "run `tot login`" instead of a stack trace.
+ *
+ * Sending publishes to Token of Trust, so we PREVIEW the report and ask before
+ * sending (skippable with --yes; required in a non-interactive shell).
+ *
+ * Usage:
+ *   tot feedback "the sign-in code kept opening a browser"
+ *   tot feedback --bug --severity high "tot dev crashed on save"
+ *   tot feedback --no-activity "just a doc nit"
+ */
+import { createInterface } from "node:readline/promises";
+import { createMcpClient } from "../mcp.mjs";
+import { resolveSession, AuthUnavailableError } from "../auth.mjs";
+import { readActivity, formatActivity } from "../activity-log.mjs";
+import { fail } from "../errors.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+const TYPES = new Set(["bug", "feature", "improvement"]);
+const SEVERITIES = new Set(["critical", "high", "medium", "low"]);
+const CATEGORIES = new Set([
+  "doc-gap", "api-ambiguity", "setup-confusion", "platform-bug",
+  "ai-agent-confusion", "product-ux", "scenario-instruction-gap",
+]);
+
+const USAGE = `tot feedback — send a note to Token of Trust (with your recent CLI activity)
+
+  tot feedback "<what happened>"      report friction; attaches your recent
+                                      CLI activity (secret-redacted, admin-only)
+  tot feedback --bug "<what broke>"   file it as a bug (default: improvement)
+  tot feedback --feature "<idea>"     file it as a feature request
+
+  --severity <critical|high|medium|low>   default: medium
+  --category <doc-gap|api-ambiguity|setup-confusion|platform-bug|
+              ai-agent-confusion|product-ux|scenario-instruction-gap>  default: product-ux
+  --no-activity   don't attach the activity log
+  --yes, -y       send without the confirmation prompt (required non-interactively)
+  --mcp <url>     MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+Requires a signed-in session — run \`tot login\` first if needed.`;
+
+function parseArgs(argv) {
+  const a = {
+    mcp: null, type: "improvement", category: "product-ux", severity: "medium",
+    activity: true, yes: false, help: false,
+  };
+  const words = [];
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--type") a.type = argv[++i];
+    else if (t === "--bug") a.type = "bug";
+    else if (t === "--feature") a.type = "feature";
+    else if (t === "--category") a.category = argv[++i];
+    else if (t === "--severity") a.severity = argv[++i];
+    else if (t === "--no-activity") a.activity = false;
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+    else words.push(t);
+  }
+  a.message = words.join(" ").trim() || null;
+  return a;
+}
+
+/** @param {string[]} argv */
+export async function run(argv) {
+  const env = process.env;
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (!TYPES.has(args.type)) {
+    console.error(fail(`--type must be one of: ${[...TYPES].join(", ")}.`, "e.g. --bug"));
+    return 2;
+  }
+  if (!SEVERITIES.has(args.severity)) {
+    console.error(fail(`--severity must be one of: ${[...SEVERITIES].join(", ")}.`));
+    return 2;
+  }
+  if (!CATEGORIES.has(args.category)) {
+    console.error(fail(`--category must be one of: ${[...CATEGORIES].join(", ")}.`));
+    return 2;
+  }
+
+  const isTty = Boolean(process.stdin.isTTY);
+
+  // The message: prompt in a TTY, otherwise it must be an argument.
+  let message = args.message;
+  if (!message && isTty) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    message = (await rl.question("What happened? (a sentence or two)\n> ")).trim();
+    rl.close();
+  }
+  if (!message) {
+    console.error(fail(
+      "a feedback message is required.",
+      'e.g. tot feedback "the sign-in code opened a browser instead of redeeming"',
+    ));
+    return 2;
+  }
+
+  const entries = args.activity ? readActivity(env, { limit: 40 }) : [];
+  const activityText = entries.length ? formatActivity(entries) : null;
+  const title = message.length > 80 ? `${message.slice(0, 79)}…` : message;
+
+  // Preview — sending publishes to Token of Trust, so show exactly what goes out.
+  console.error("\nAbout to send to Token of Trust:");
+  console.error(`  ${args.type} · ${args.category} · ${args.severity}`);
+  console.error(`  "${title}"`);
+  console.error(
+    activityText
+      ? `  + your last ${entries.length} CLI command(s) — secret-redacted, ToT-admins-only`
+      : "  (no activity log attached)",
+  );
+
+  if (!args.yes) {
+    if (!isTty) {
+      console.error(fail(
+        "refusing to send without confirmation in a non-interactive shell.",
+        "re-run with --yes to send.",
+      ));
+      return 2;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const ans = (await rl.question("Send it? [y/N] ")).trim().toLowerCase();
+    rl.close();
+    if (ans !== "y" && ans !== "yes") {
+      console.error("- not sent.");
+      return 0;
+    }
+  }
+
+  const mcpUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(mcpUrl);
+  try {
+    await resolveSession(client);
+    await client.initialize({ name: "tot-cli", version: "feedback" });
+    const payload = {
+      type: args.type,
+      category: args.category,
+      severity: args.severity,
+      title,
+      description: message,
+      scenario: "tot-cli",
+      // Activity → `sensitive` (ToT-admins-only, never clustered/shared). It's already
+      // secret-redacted; `sensitive` is the belt-and-suspenders home for it.
+      ...(activityText ? { sensitive: `tot CLI activity (most recent last):\n${activityText}` } : {}),
+    };
+    const res = await client.callTool("feedback_submit", payload);
+    const id = res?.reportId || res?.id || null;
+    console.log(`\n+ sent — thank you.${id ? ` (report ${id})` : ""}`);
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail(`can't send feedback: ${e.message}`, e.hint || "run `tot login` first."));
+      return 1;
+    }
+    console.error(fail(
+      `couldn't send feedback: ${e?.message || e}`,
+      "your note was NOT sent — try again in a moment.",
+    ));
+    return 1;
+  }
+}

package/src/commands/login.mjs

@@ -19,7 +19,7 @@
  *
  * Dependency-free (node built-ins via oauth.mjs).
  */
-import { loginFlow, deviceLoginFlow, NoOpenerError } from "../oauth.mjs";
+import { loginFlow, deviceLoginFlow, redeemCodeFlow, NoOpenerError } from "../oauth.mjs";
 import { defaultCredentialsPath, readCredentials, writeCredentials } from "../token-store.mjs";
 import { openBrowser } from "../open.mjs";
 import { fail } from "../errors.mjs";
@@ -27,11 +27,12 @@ import { fail } from "../errors.mjs";
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 function parseArgs(argv) {
-  const a = { mcp: null, device: false, help: false };
+  const a = { mcp: null, device: false, code: null, help: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
     else if (t === "--device") a.device = true;
+    else if (t === "--code" || t === "--token") a.code = argv[++i];
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
@@ -40,6 +41,8 @@ function parseArgs(argv) {
 const USAGE = `tot login — sign in to Token of Trust
 
   tot login                 open the browser, sign in, cache your session
+  tot login --code <token>  paste the sign-in token from your invite — no browser,
+                            no email code (alias: --token)
   tot login --device        headless/SSH: print a code, poll until approved
                             elsewhere (also the automatic fallback when no
                             browser opener exists on this box)
@@ -77,6 +80,21 @@ export async function loginAndCache(mcpUrl, env = process.env, { log = () => {},
   return creds;
 }
 
+/**
+ * The core of `tot login --code`: run the browserless redemption (POST the invite
+ * token to the MCP, get a grant back) and cache it, reusing a previously-registered
+ * client for THIS MCP so we don't re-register on every login.
+ * @returns {Promise<object>} the credentials written to disk.
+ */
+export async function redeemAndCache(mcpUrl, code, env = process.env) {
+  const path = defaultCredentialsPath(env);
+  const prior = readCredentials(path);
+  const clientId = prior && prior.mcpUrl === mcpUrl ? prior.clientId : undefined;
+  const creds = await redeemCodeFlow({ mcpUrl, clientId, code });
+  writeCredentials(path, creds);
+  return creds;
+}
+
 /** @param {string[]} argv @param {any} _ctx */
 export async function run(argv, _ctx) {
   const env = process.env;
@@ -87,6 +105,25 @@ export async function run(argv, _ctx) {
   }
 
   const mcpUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+
+  if (args.code) {
+    console.error(`~ signing in to Token of Trust with your invite code (${mcpUrl})`);
+    try {
+      await redeemAndCache(mcpUrl, args.code, env);
+      console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
+      console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
+      return 0;
+    } catch (e) {
+      console.error(
+        fail(
+          `sign-in didn't complete: ${e?.message || e}`,
+          "double-check the sign-in token from your invite — it's single-use and expires, so ask for a fresh invite if needed.",
+        ),
+      );
+      return 1;
+    }
+  }
+
   console.error(`~ signing in to Token of Trust (${mcpUrl})`);
   try {
     await loginAndCache(mcpUrl, env, { log: (m) => console.error(m), device: args.device });

package/src/commands/logout.mjs

@@ -0,0 +1,39 @@
+/**
+ * `tot logout` — sign this machine out of Token of Trust.
+ *
+ * Deletes the cached session (`~/.tot/credentials.json`) so the next command starts
+ * clean — the counterpart to `tot login` / `tot login --code`. Idempotent: logging
+ * out when already signed out is success, not an error.
+ *
+ * LOCAL ONLY: this clears the credential cache on THIS machine. It does not revoke
+ * the grant server-side — revoke from your Token of Trust account if you need that.
+ *
+ * Dependency-free (node built-ins via token-store.mjs).
+ */
+import { defaultCredentialsPath, readCredentials, clearCredentials } from "../token-store.mjs";
+
+const USAGE = `tot logout — sign this machine out of Token of Trust
+
+  tot logout    delete the cached session (~/.tot/credentials.json)
+
+Idempotent — safe to run when already signed out. Clears only this machine's cache;
+it does not revoke server-side. Run \`tot whoami\` to confirm you're signed out.`;
+
+/** @param {string[]} argv */
+export async function run(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(USAGE);
+    return 0;
+  }
+  const path = defaultCredentialsPath(process.env);
+  // Report against the prior state so "signed out" vs "already clean" is honest.
+  const wasSignedIn = !!readCredentials(path);
+  const removed = clearCredentials(path);
+  if (wasSignedIn || removed) {
+    console.log(`+ signed out. Cleared ${path}.`);
+    console.log("  Run `tot login` (or `tot login --code <token>`) to sign in again.");
+  } else {
+    console.log("+ already signed out — no cached session to clear.");
+  }
+  return 0;
+}

package/src/commands/start.mjs

@@ -28,6 +28,13 @@
  *               yes, `claude mcp add` AND drop straight into that seeded
  *               prompt (G2) — the payoff, not a pointer to go write one.
  *
+ * ZERO-LOGIN FREE TASTE (--sample / no session): when the user passes --sample,
+ * or has no Token of Trust session (and doesn't decline), `tot start` SKIPS
+ * login + client_list + tenant_checkout entirely, scaffolds a bundled sample
+ * store locally, runs it natively (no Docker, no MCP), opens the browser, and
+ * ends on the SAME "connect the ToT MCP for the real power" opt-in. The MCP is
+ * repositioned as the upsell, not a gate. See runSampleStart + sample.mjs.
+ *
  * Value-first ordering (C): the running site + browser come BEFORE any mention of
  * connecting the MCP; Claude is the supercharge offered after the aha, not a gate.
  * ONE felt browser login (B2): `claude mcp add` only ever runs behind that final
@@ -43,7 +50,7 @@ import { createInterface } from "node:readline/promises";
 
 import { detectContext } from "../context.mjs";
 import { createMcpClient } from "../mcp.mjs";
-import { resolveSession } from "../auth.mjs";
+import { resolveSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError, exitCodeFor } from "../errors.mjs";
 import { openBrowser, waitForServer } from "../open.mjs";
 import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
@@ -52,8 +59,10 @@ import { normalizeStores, checkoutTenant } from "./checkout.mjs";
 import {
   buildContainerPlan, spawnDevContainer, dockerAvailable, tryStartDocker,
   resolveDevImage, isPrivateRegistryImage, ensureRegistryLogin,
-  ensureRendererArtifact, spawnNativeDev, deriveUrl, NativeArtifactUnavailableError,
+  ensureRendererArtifact, ensureSampleRenderer, spawnNativeDev, deriveUrl,
+  NativeArtifactUnavailableError,
 } from "./dev.mjs";
+import { scaffoldSample, isSampleCheckout, sampleConfig, SAMPLE_DIR_NAME } from "../sample.mjs";
 import { IDEAS } from "./ideas.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -62,7 +71,7 @@ const CLAUDE_MCP_ARGS = ["mcp", "add", "--transport", "http", "tot", `${DEFAULT_
 function parseArgs(argv) {
   const a = {
     mcp: null, identity: null, tenant: null, port: "4321",
-    noOpen: false, noConnect: false, yes: false, docker: false, help: false,
+    noOpen: false, noConnect: false, yes: false, docker: false, sample: false, help: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
@@ -74,6 +83,7 @@ function parseArgs(argv) {
     else if (t === "--no-connect") a.noConnect = true;
     else if (t === "--yes" || t === "-y") a.yes = true;
     else if (t === "--docker") a.docker = true;
+    else if (t === "--sample") a.sample = true;
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
@@ -83,9 +93,12 @@ const USAGE = `tot start — go from invite to a running store in one command
 
   tot start                 preflight → sign in → pick your store → check out →
                             run it → open your browser → connect Claude
+  tot start --sample        the FREE local preview — no login, no MCP, no account:
+                            scaffold + run a sample store, then offer the MCP upsell
 Options:
   --tenant <id>    use this store (skips auto-pick/prompt; remembered for next time)
   --port <n>       host port for the dev server (default 4321)
+  --sample         zero-login free taste (see above); also what a no-session run offers
   --docker         use the Docker runner instead of the native runtime (F3
                     default); also the automatic fallback if the native
                     artifact can't be fetched
@@ -131,6 +144,20 @@ export function pickTenant(stores, { explicit = null, lastTenant = null } = {})
   return pick;
 }
 
+/**
+ * Decide whether `tot start` runs the ZERO-LOGIN sample path or the authenticated
+ * path. Pure + exported so the branch is unit-tested without any I/O.
+ *   - `--sample` explicit → always sample (skip login entirely).
+ *   - otherwise: a usable session → authed; NO session → sample (the graceful
+ *     free-taste default instead of dead-ending at "ask for an invite").
+ * @param {{ sampleFlag: boolean, hasSession: boolean }} args
+ * @returns {"sample"|"authed"}
+ */
+export function decideStartMode({ sampleFlag, hasSession }) {
+  if (sampleFlag) return "sample";
+  return hasSession ? "authed" : "sample";
+}
+
 /** @param {string[]} argv @param {any} ctx */
 export async function run(argv, ctx) {
   const env = process.env;
@@ -141,16 +168,31 @@ export async function run(argv, ctx) {
   }
 
   const startedAt = Date.now();
+
+  // Explicit free taste: skip login/store/checkout entirely (A0 zero-login).
+  if (decideStartMode({ sampleFlag: args.sample, hasSession: true }) === "sample") {
+    return runSampleStart(args, ctx, env, startedAt);
+  }
+
   try {
-    // 1+2. preflight (F) and login (B) run CONCURRENTLY (A2) — the local machine
-    // checks (node/git/Docker) don't gate the network sign-in and vice versa, so
-    // gate on the slower of the two instead of paying their sum serially.
     const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
     const client = createMcpClient(baseUrl);
-    const [, session] = await Promise.all([
-      preflight(ctx, env),
-      loginStep(client, env, args),
-    ]);
+
+    // Resolve a session, tolerating a no-session / no-network condition so we can
+    // offer the free local preview instead of dead-ending (B/A0).
+    const session = await tryResolveSession(client, env, args);
+    if (decideStartMode({ sampleFlag: false, hasSession: !!session }) === "sample") {
+      if (!(await confirmSampleFallback(args))) {
+        throw new CliError("no Token of Trust session, and you declined the free local preview", {
+          next: "tot login   (then re-run `tot start`), or `tot start --sample` for the free local preview",
+        });
+      }
+      return await runSampleStart(args, ctx, env, startedAt);
+    }
+
+    // Authenticated path. Preflight (F) now that we know we're taking it — the
+    // local machine checks (node/git/Docker) that the authed loop needs.
+    await preflight(ctx, env);
     console.log(`  ✓ signed in as ${session.identity}${session.appDomain ? ` (${session.appDomain})` : ""}`);
 
     // 3. store — auto-pick, use --tenant, use the remembered one, or choose (A4).
@@ -223,8 +265,79 @@ export async function run(argv, ctx) {
 }
 
 /**
- * MCP init + session resolve — the "login" half of preflight (A2: runs
- * concurrently with the local machine checks in preflight(), below).
+ * The ZERO-LOGIN free taste: scaffold a bundled sample store, run it natively
+ * (no Docker, no MCP, no auth), open the browser, and end on the "connect the
+ * ToT MCP for the real power" upsell. Skips loginStep + client_list +
+ * tenant_checkout entirely. Reuses connectClaude() as the terminal opt-in.
+ */
+async function runSampleStart(args, ctx, env, startedAt) {
+  try {
+    // Minimal preflight — the free path needs ONLY Node (no git, no Docker, no auth).
+    const nodeMajor = Number(process.versions.node.split(".")[0]);
+    if (nodeMajor < 20) {
+      throw new CliError(`Node 20+ is required (have ${process.versions.node})`, {
+        next: "upgrade Node, then re-run",
+        exitCode: 2,
+      });
+    }
+
+    // Scaffold — or reuse a sample checkout we're already standing in.
+    let workspace;
+    if (ctx.mode === "checkout" && isSampleCheckout(ctx.workspacePath)) {
+      workspace = ctx.workspacePath;
+      console.log(`  ✓ reusing the sample checkout at ${workspace}`);
+    } else {
+      const dest = resolve(process.cwd(), SAMPLE_DIR_NAME);
+      const r = scaffoldSample(dest, { log: (m) => console.log(m) });
+      workspace = r.dir;
+    }
+
+    // Resolve a renderer OFFLINE (no dev_renderer_artifact MCP call) + boot it.
+    const devArgs = {
+      image: null, port: String(args.port || "4321"), mcp: args.mcp,
+      noLogin: true, noOpen: args.noOpen, docker: false, sample: true,
+    };
+    const runnerDir = await ensureSampleRenderer(devArgs, ctx, { env });
+
+    const ctxDev = detectContext(workspace);
+    const url = deriveUrl(ctxDev.config || sampleConfig(), devArgs.port).url;
+    console.log(`  → starting the free local preview … ${url}`);
+    const handle = spawnNativeDev(runnerDir, workspace, devArgs.port, { stdio: "piped" });
+
+    const up = await Promise.race([
+      waitForServer(url, { until: () => handle.exited }),
+      handle.done.then(() => "exited"),
+    ]);
+    if (up !== true) {
+      throw new CliError("the local preview server didn't come up", {
+        next: `cd ${SAMPLE_DIR_NAME} && tot dev --sample   (to watch the runner logs)`,
+      });
+    }
+    if (!args.noOpen) {
+      openBrowser(url);
+      console.log("  ✓ opened your browser");
+    }
+
+    // You're live — the FREE preview. End on the MCP upsell (the whole point).
+    printSampleLiveEnding(url, formatElapsed(Date.now() - startedAt));
+    if (!args.noConnect) {
+      const yes = args.yes || (await promptYesNo("  Connect the ToT MCP for your real store + AI editing?", true));
+      if (yes) connectClaude();
+    }
+
+    console.log("\n  Streaming preview logs — edit content/*.html + save to see reloads. Ctrl-C to stop.\n");
+    handle.child.stdout?.pipe(process.stdout);
+    handle.child.stderr?.pipe(process.stderr);
+    return handle.done;
+  } catch (e) {
+    console.error(formatError(e));
+    return exitCodeFor(e);
+  }
+}
+
+/**
+ * MCP init + session resolve — the "login" half of preflight. Throws
+ * AuthUnavailableError (no creds) or a CliError (can't reach the MCP).
  */
 async function loginStep(client, env, args) {
   try {
@@ -237,14 +350,41 @@ async function loginStep(client, env, args) {
   return resolveSession(client, { env, prefer: args.identity || undefined });
 }
 
+/**
+ * Resolve a session but return null (instead of throwing) for the two conditions
+ * the free-taste fallback should absorb: no usable session, or the MCP being
+ * unreachable. A blocking machine problem (or any other error) still throws.
+ */
+async function tryResolveSession(client, env, args) {
+  try {
+    return await loginStep(client, env, args);
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) return null;
+    if (e instanceof CliError && /can't reach the Token of Trust MCP/.test(e.message)) return null;
+    throw e;
+  }
+}
+
+/**
+ * Offer the free local preview when there's no session. Non-interactive (or
+ * --yes) defaults to YES — the graceful free path, never a hang. Returns whether
+ * to proceed into the sample run.
+ */
+async function confirmSampleFallback(args) {
+  console.log("");
+  console.log("  You're not signed in to Token of Trust — no problem. You can try the FREE");
+  console.log("  local preview right now (no account, no MCP), then connect for your real store.");
+  if (args.yes) return true;
+  if (!isInteractive()) return true;
+  return promptYesNo("  Run the free local sample store?", true);
+}
+
 /**
  * Self-healing preflight (F): run the readiness checks; a blocking failure
  * ends with the next command. Docker is informational-only here (F3: native
  * is the default runtime, so Docker not running doesn't block `tot start`
  * anymore) — its own readiness is handled lazily in prefetchDockerLogin(),
  * only when the run actually needs it (--docker or the native fallback).
- * Runs concurrently with loginStep (A2) via Promise.all in run(), so nothing
- * here may assume login has happened.
  */
 async function preflight(ctx, env) {
   const checks = collectChecks(ctx, env);
@@ -311,7 +451,7 @@ async function resolveTenant(stores, args, env, baseUrl) {
   let tenant;
   if (pick.kind === "none") {
     throw new CliError("no stores you can build on yet", {
-      next: "ask your Token of Trust contact for a store invite, then re-run",
+      next: "ask your Token of Trust contact for a store invite, then re-run — or `tot start --sample` for the free local preview",
     });
   } else if (pick.kind === "explicit") {
     tenant = pick.tenant;
@@ -385,6 +525,24 @@ function printLiveEnding(tenant, url, elapsed) {
   console.log("");
 }
 
+/**
+ * The crafted "you're live" ending for the FREE local preview — honest about
+ * what it is (a sample on your machine) and what unlocks the real thing (the
+ * MCP: your real store, AI editing, live compliance previews). The upsell IS the
+ * ending — connectClaude() runs right after this on opt-in.
+ */
+function printSampleLiveEnding(url, elapsed) {
+  console.log("");
+  console.log(`  ✨ You're live — the FREE local preview.${elapsed ? `  (${elapsed})` : ""}`);
+  console.log(`     ${url}`);
+  console.log("     Edit content/home.html + save → it reloads. The age-gate + nicotine warning");
+  console.log("     you see ARE Token of Trust compliance rendering — live, on your machine.");
+  console.log("");
+  console.log("  This is a sample store, running locally, for free. Connect the ToT MCP to use");
+  console.log("  your REAL store, AI editing, and live compliance previews:");
+  console.log("");
+}
+
 /**
  * Offer + wire Claude (G2): `claude mcp add`, then — the payoff, not just a
  * pointer — drop the user straight into an interactive Claude session already

package/src/oauth.mjs

@@ -285,6 +285,83 @@ export async function loginFlow({
   }
 }
 
+// ── WS2b: browserless invite-code redemption (`tot login --code <token>`) ─────
+//
+// The invited developer pastes the single-use sign-in token their invite minted;
+// we hand it to the MCP's redeem endpoint, which validates + BURNS it via ToT and
+// returns a normal MCP OAuth grant. No browser, no loopback, no OTP — the token IS
+// the operator's authorization. Same credentials shape as loginFlow/deviceLoginFlow,
+// and the grant is bound to our registered client_id so later silent refreshes go
+// through the standard token endpoint like any other session.
+//
+// Wire contract (CLI → MCP):
+//   POST {mcp-origin}/oauth/redeem-code   (application/json)
+//     { code: "<invite sign-in token>", client_id, scope? }
+//   → 200 { access_token, refresh_token, token_type, expires_in, scope }
+//   → 400 { error, error_description }   (invalid_grant | invalid_client)
+//
+// The token→CLI binding is inherent to the single request: the tokens are returned
+// only in the direct TLS response to the client that presented the code, and the
+// grant is pinned to our dynamically-registered client_id (only that client can
+// refresh it). A separate PKCE nonce would add nothing here — there is no second
+// exchange step at which a verifier could be presented.
+
+/** The MCP's redeem endpoint — the MCP origin (from the AS token endpoint) + a
+ * fixed path. Kept beside the flow so the path lives in exactly one place. */
+export function redeemCodeEndpoint(mcpUrl, meta) {
+  const origin = meta?.token_endpoint ? new URL(meta.token_endpoint) : new URL(mcpUrl);
+  return new URL("/oauth/redeem-code", origin).toString();
+}
+
+/** POST the invite token to the MCP redeem endpoint and return the raw token
+ * response (→ credentialsFromToken). Throws a clear, non-stack error on rejection. */
+export async function redeemInviteCode(redeemEndpoint, { code, clientId, scope = SCOPE }, fetchImpl = fetch) {
+  const res = await fetchImpl(redeemEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    body: JSON.stringify({ code, client_id: clientId, scope }),
+  });
+  const text = await res.text();
+  let body;
+  try { body = text ? JSON.parse(text) : {}; } catch { body = {}; }
+  if (!res.ok) {
+    const detail = [body.error, body.error_description].filter(Boolean).join(" — ");
+    throw new Error(`your sign-in code was not accepted (HTTP ${res.status}${detail ? `: ${detail}` : ""})`);
+  }
+  if (!body.access_token) throw new Error("the redeem endpoint returned no access_token");
+  return body;
+}
+
+/**
+ * Run the full browserless redemption and return a persistable credentials record
+ * — the invite-token sibling of loginFlow()/deviceLoginFlow(), same credentials
+ * shape, same dynamically-registered client_id (reused when the caller cached one
+ * for this MCP). Injectable (`fetchImpl`, `now`) so it's testable with no network.
+ * @returns {Promise<object>} credentials to hand to writeCredentials()
+ */
+export async function redeemCodeFlow({
+  mcpUrl,
+  clientId,
+  code,
+  fetchImpl = fetch,
+  now = () => Date.now(),
+}) {
+  const meta = await discoverMetadata(mcpUrl, fetchImpl);
+  const resolvedClientId = clientId || (await registerClient(meta.registration_endpoint, LOOPBACK_REDIRECT, fetchImpl));
+  const token = await redeemInviteCode(
+    redeemCodeEndpoint(mcpUrl, meta),
+    { code, clientId: resolvedClientId },
+    fetchImpl,
+  );
+  return credentialsFromToken({
+    mcpUrl,
+    clientId: resolvedClientId,
+    tokenEndpoint: meta.token_endpoint,
+    token,
+    now: now(),
+  });
+}
+
 // ── B3: device-code grant (RFC 8628) — headless/SSH/no-browser sign-in ────────
 
 /**