@tokenoftrust/cli 1.0.0 → 1.1.0

package/bin/tot.mjs

@@ -5,14 +5,18 @@
  * 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 start --sample        FREE local preview — no login, no MCP       ← built (zero-login quickstart; MCP is the upsell)
  *   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 checkout [<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 dev --sample          run a FREE bundled sample store locally    ← built (zero-login, no MCP; compliance rendering still shows)
  *   tot submit                submit your store for preview             ← built (validate + push preview ref; MCP preview_status read-back)
  *   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 help                  this help
  *
  * Context-aware (see src/context.mjs): the same `tot` does the right thing from
@@ -23,34 +27,46 @@
  * bundles the moat-free storefront runner; `tot checkout/validate/submit` are
  * pure Node. Dependency-free by design so `npm i -g @tokenoftrust/cli` stays light.
  */
+import { readFileSync } from "node:fs";
 import { detectContext } from "../src/context.mjs";
 import { printError } from "../src/errors.mjs";
+import { recordActivity, redactArgs } from "../src/activity-log.mjs";
 
 const BUILD_ORDER = ["checkout", "validate", "dev", "submit"];
 
+// CLI version (stamped into the activity log). Read from our own package.json; best-effort.
+const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+})();
+
 function usage() {
   console.log(`
 tot — Token of Trust developer CLI
 
   tot start                 invite → running store in one command (start here)
+  tot start --sample        free local preview — no login, no account needed
   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 checkout [<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 dev --sample          run a free bundled sample store (no login, no MCP)
   tot submit                submit your store for preview
   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 help                  show this help
 
 Run \`tot <command> --help\` for command-specific options.
 `);
 }
 
-async function main() {
-  const [cmd, ...rest] = process.argv.slice(2);
-  const ctx = detectContext();
-
+async function dispatch(cmd, rest, ctx) {
   if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
     usage();
     return cmd ? 0 : 2;
@@ -66,6 +82,16 @@ async function main() {
     return run(rest, ctx);
   }
 
+  if (cmd === "logout") {
+    const { run } = await import("../src/commands/logout.mjs");
+    return run(rest, ctx);
+  }
+
+  if (cmd === "feedback") {
+    const { run } = await import("../src/commands/feedback.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "whoami") {
     const { run } = await import("../src/commands/whoami.mjs");
     return run(rest, ctx);
@@ -116,6 +142,33 @@ async function main() {
   return 2;
 }
 
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const ctx = detectContext();
+  const startedAt = Date.now();
+  let code = 0;
+  let errMsg = null;
+  try {
+    code = await dispatch(cmd, rest, ctx);
+    return code;
+  } catch (e) {
+    errMsg = e?.message || String(e);
+    throw e;
+  } finally {
+    // Best-effort activity breadcrumb (never throws, never blocks). `feedback`'s own
+    // free-text message is omitted — it's user-typed and belongs only in the report.
+    recordActivity({
+      ts: new Date().toISOString(),
+      v: VERSION,
+      cmd: cmd || "(none)",
+      args: cmd === "feedback" ? ["«omitted»"] : redactArgs(rest),
+      code: errMsg ? 1 : (code ?? 0),
+      ms: Date.now() - startedAt,
+      ...(errMsg ? { err: String(errMsg).slice(0, 200) } : {}),
+    });
+  }
+}
+
 main()
   .then((code) => process.exit(code ?? 0))
   .catch((e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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.",
   "license": "Apache-2.0",
   "author": "Token of Trust",
@@ -25,6 +25,7 @@
   "files": [
     "bin",
     "src",
+    "template",
     "README.md",
     "LICENSE"
   ],

package/src/activity-log.mjs

@@ -0,0 +1,112 @@
+/**
+ * Activity log for `tot` — a bounded, secret-safe breadcrumb trail of what the CLI
+ * did, so a developer who hits friction can attach it to a `tot feedback` report
+ * (sent through the Token of Trust MCP's `feedback_submit` tool).
+ *
+ * ONE file, `~/.tot/activity.log` (JSON-lines), beside the credential cache. Each
+ * line is one command invocation: { ts, v, cmd, args, code, ms, err? }. Bounded to
+ * the most recent MAX_ENTRIES so it never grows without limit.
+ *
+ * NEVER records secrets: the value after `--code` / `--token` (the single-use
+ * sign-in code) is redacted, and we only ever store argv — never env, never file
+ * contents, never the cached OAuth token. `tot feedback`'s own message is omitted
+ * by the dispatcher (it's free text the user typed).
+ *
+ * Best-effort by contract: recording NEVER throws and never blocks a command.
+ * `TOT_HOME` overrides the home dir (tests point it at a temp dir), like token-store.
+ */
+import {
+  readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+/** Keep at most this many recent invocations. */
+export const MAX_ENTRIES = 300;
+
+// Flags whose FOLLOWING token is a secret and must never be logged.
+const SECRET_VALUE_FLAGS = new Set(["--code", "--token"]);
+
+/** Absolute path to the activity log for this environment. */
+export function activityLogPath(env = process.env) {
+  const home = env.TOT_HOME || homedir();
+  return join(home, ".tot", "activity.log");
+}
+
+/**
+ * Redact secret values from an argv array (never mutates the input). Handles both
+ * the split form (`--code TOKEN`) and the `=` form (`--code=TOKEN`).
+ */
+export function redactArgs(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = String(args[i]);
+    const eq = a.match(/^(--code|--token)=/);
+    if (eq) {
+      out.push(`${eq[1]}=«redacted»`);
+      continue;
+    }
+    out.push(a);
+    if (SECRET_VALUE_FLAGS.has(a) && i + 1 < args.length) {
+      out.push("«redacted»");
+      i++; // skip the secret value we just masked
+    }
+  }
+  return out;
+}
+
+function readRawLines(filePath) {
+  try {
+    return readFileSync(filePath, "utf8").split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Append one activity entry, keeping only the most recent MAX_ENTRIES. Atomic
+ * (temp-file rename) + owner-only (0600 in a 0700 dir), like the credential cache.
+ * Never throws — activity logging must never break a command.
+ */
+export function recordActivity(entry, env = process.env) {
+  try {
+    const filePath = activityLogPath(env);
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    const lines = readRawLines(filePath);
+    lines.push(JSON.stringify(entry));
+    const kept = lines.slice(-MAX_ENTRIES);
+    const tmp = `${filePath}.tmp`;
+    writeFileSync(tmp, `${kept.join("\n")}\n`, { mode: 0o600 });
+    renameSync(tmp, filePath);
+    chmodSync(filePath, 0o600);
+  } catch {
+    /* best-effort: never throw */
+  }
+}
+
+/** Read recent activity entries (most recent last), parsed. Never throws. */
+export function readActivity(env = process.env, { limit = MAX_ENTRIES } = {}) {
+  const out = [];
+  for (const line of readRawLines(activityLogPath(env)).slice(-limit)) {
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      /* skip a malformed line */
+    }
+  }
+  return out;
+}
+
+/** A compact, human-readable rendering of recent activity, for a feedback attachment. */
+export function formatActivity(entries) {
+  return entries
+    .map((e) => {
+      const when = e.ts || "?";
+      const cmd = [e.cmd, ...(e.args || [])].join(" ").trim();
+      const status = e.code === 0 ? "ok" : `exit ${e.code}`;
+      const ms = typeof e.ms === "number" ? ` ${e.ms}ms` : "";
+      const err = e.err ? ` — ${e.err}` : "";
+      return `${when}  tot ${cmd}  [${status}${ms}]${err}`;
+    })
+    .join("\n");
+}

package/src/auth.mjs

@@ -91,7 +91,7 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
   if (!creds || !creds.accessToken) {
     throw new AuthUnavailableError(
       "you're not signed in to Token of Trust.",
-      { hint: "run `tot login` to sign in, then re-run." },
+      { hint: "run `tot login` to sign in (or `tot login --code <token>` to paste your invite token), then re-run." },
     );
   }
 

package/src/commands/dev.mjs

@@ -20,6 +20,12 @@
  *              (--docker, or automatically if the native artifact can't be
  *              fetched) — see runContainer below.
  *
+ *   --sample — the ZERO-LOGIN, NO-MCP free taste. Scaffolds a bundled sample store
+ *              onto disk and runs it natively WITHOUT any authenticated
+ *              dev_renderer_artifact call — the renderer is resolved offline via
+ *              resolveRendererSource() (env / cache / in-tree monorepo). Compliance
+ *              rendering (age-gate + nicotine warning) still shows. See sample.mjs.
+ *
  * IP note: the artifact is the pruned runner (control plane physically absent),
  * vended by a short-lived signed URL (`dev_renderer_artifact`) gated on the same
  * developer entitlement as the Docker pull token — no hand-provisioned AWS creds
@@ -29,6 +35,7 @@ import { spawn, spawnSync, execFileSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, createWriteStream } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { setTimeout as delay } from "node:timers/promises";
@@ -36,6 +43,10 @@ import { createMcpClient } from "../mcp.mjs";
 import { resolveSession } from "../auth.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { openBrowser, waitForServer } from "../open.mjs";
+import {
+  scaffoldSample, isSampleCheckout, sampleConfig,
+  resolveRendererSource as resolveLocalRendererSource, SAMPLE_DIR_NAME,
+} from "../sample.mjs";
 
 /** The published moat-free runner image (--docker fallback). Override with --image / TOT_DEV_IMAGE. */
 const DEFAULT_DEV_IMAGE =
@@ -43,11 +54,15 @@ const DEFAULT_DEV_IMAGE =
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 /** Where downloaded+installed renderer-artifact versions are cached, one dir per version. */
 const RENDERER_CACHE_ROOT = join(homedir(), ".tot", "cache", "renderer");
+/** The PUBLIC, un-entitled runner published to npm (sample / zero-login mode). */
+const PUBLIC_RUNNER_PACKAGE = "@tokenoftrust/storefront-runner";
+const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
 
 export function parseArgs(argv) {
   const a = {
     workspace: null, port: "4321", image: null, mcp: null,
-    noLogin: false, noOpen: false, docker: false, help: false,
+    noLogin: false, noOpen: false, docker: false, sample: false, help: false,
+    rendererVersion: null,
   };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
@@ -58,6 +73,8 @@ export function parseArgs(argv) {
     else if (t === "--no-login") a.noLogin = true;
     else if (t === "--no-open") a.noOpen = true;
     else if (t === "--docker") a.docker = true;
+    else if (t === "--sample") a.sample = true;
+    else if (t === "--renderer-version") a.rendererVersion = argv[++i];
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
@@ -67,6 +84,8 @@ const USAGE = `tot dev — run your store locally with save→reload
 
   tot dev <tenant>              (in the monorepo) run tenants/<tenant>/
   tot dev                       (in a checkout) run this store natively (no Docker)
+  tot dev --sample              scaffold + run a FREE local sample store — no login,
+                                no MCP, no account (the free first taste)
   tot dev --workspace <dir>     run a specific checkout directory
   tot dev --port <n>            host port (default 4321)
   tot dev --docker              use the Docker runner image instead of the native path
@@ -74,8 +93,8 @@ const USAGE = `tot dev — run your store locally with save→reload
   tot dev --no-open             don't auto-open the browser when the server is up
 
 Edit content/*.html or the theme + save → the browser reloads. Private local
-preview — nothing is published. Prerequisites: Node.js and an invite — no Docker,
-no hand-provisioned AWS creds.`;
+preview — nothing is published. Prerequisites: Node.js and an invite (or just
+--sample, which needs neither) — no Docker, no hand-provisioned AWS creds.`;
 
 /** @param {string[]} argv @param {any} ctx */
 export function run(argv, ctx) {
@@ -85,6 +104,12 @@ export function run(argv, ctx) {
     return 0;
   }
 
+  // Zero-login free taste: scaffold + run a bundled sample store, no MCP. Wins
+  // over every context (works in the monorepo, a checkout, or a loose dir).
+  if (args.sample) {
+    return runSample(args, ctx);
+  }
+
   // Monorepo: delegate to the in-tree runner (host astro dev + HMR).
   if (ctx.mode === "monorepo" && !args.workspace) {
     return runMonorepo(ctx, argv);
@@ -101,7 +126,7 @@ export 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), or pass --workspace <dir>",
+        "tot checkout <tenant> --clone <dir>   (then `cd` in and re-run), pass --workspace <dir>, or try `tot dev --sample`",
       ),
     );
     return 2;
@@ -171,12 +196,22 @@ async function runNative(workspace, args, ctx) {
     });
   }
   const port = String(args.port || "4321");
-  const { domain, url } = deriveUrl(cfg, port);
+  const { url } = deriveUrl(cfg, port);
 
   const runnerDir = await ensureRendererArtifact(args);
 
   printDevBanner({ tenant: cfg.tenant || null, url });
 
+  return bootNative(runnerDir, workspace, port, url, args);
+}
+
+/**
+ * Spawn the native runner against a workspace and (unless --no-open) auto-open
+ * the browser the moment the server answers. Returns the spawn handle's `done`
+ * promise. Shared by the authenticated native path (runNative) and the
+ * zero-login sample path (runSample) so both boot identically.
+ */
+function bootNative(runnerDir, workspace, port, url, args) {
   const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "inherit" });
 
   // Auto-open the browser the moment the server answers (D). Non-blocking so
@@ -196,6 +231,113 @@ async function runNative(workspace, args, ctx) {
   return handle.done;
 }
 
+/**
+ * `tot dev --sample` — the ZERO-LOGIN, NO-MCP free taste. Scaffolds a bundled
+ * sample store (unless we're already standing in one), resolves a renderer
+ * OFFLINE (no dev_renderer_artifact call), and boots it natively. Compliance
+ * rendering still shows because the sample borrows a registered regulated
+ * tenant's identity (see sample.mjs).
+ */
+async function runSample(args, ctx) {
+  let workspace;
+  try {
+    if (ctx.mode === "checkout" && isSampleCheckout(ctx.workspacePath)) {
+      workspace = ctx.workspacePath;
+      console.error(`~ reusing sample checkout: ${workspace}`);
+    } else {
+      const dest = args.workspace ? resolve(args.workspace) : resolve(process.cwd(), SAMPLE_DIR_NAME);
+      const r = scaffoldSample(dest, { log: (m) => console.error(m) });
+      workspace = r.dir;
+    }
+
+    const cfg = readWorkspaceConfig(workspace) || sampleConfig();
+    const port = String(args.port || "4321");
+    const { url } = deriveUrl(cfg, port);
+
+    const runnerDir = await ensureSampleRenderer(args, ctx);
+
+    printSampleBanner({ url });
+    return await bootNative(runnerDir, workspace, port, url, args);
+  } catch (e) {
+    console.error(formatError(e));
+    return e instanceof CliError ? (e.exitCode ?? 2) : 2;
+  }
+}
+
+/** The free-taste banner — honest about what this is, and what unlocks the real thing. */
+export function printSampleBanner({ url }) {
+  console.error(`\n  tot dev --sample — free local preview (sample vape store)`);
+  console.error(`  ➜  Local:    ${url}`);
+  console.error(`  ➜  Edit:     content/home.html or theme.json + save → the browser reloads`);
+  console.error(`  ➜  FREE local preview — no login, no ToT account, nothing published. Ctrl-C to stop.`);
+  console.error(`     Connect the ToT MCP for your REAL store, AI editing & compliance previews.\n`);
+}
+
+/**
+ * Resolve WHERE to get the moat-free runner tarball for this run — the seam that
+ * splits the entitled and the public (zero-login sample) delivery paths. Returns
+ * `{ kind, version, url, strip, cacheKey }`; callers download + extract + install +
+ * cache it uniformly (installRunnerTarball).
+ *
+ *   • SAMPLE mode (args.sample) → the PUBLIC npm package @tokenoftrust/storefront-runner.
+ *     NO dev_renderer_artifact MCP call, NO entitlement, NO session. The npm tarball
+ *     wraps the tree under `package/`, so `strip: 1` yields the same tree the entitled
+ *     artifact ships.
+ *   • ENTITLED mode (default) → the MCP's `dev_renderer_artifact` signed URL, gated on
+ *     the developer entitlement. `strip: 0` (the raw build-runner tarball).
+ *
+ * Exported so sample/tests can drive the selection directly.
+ * @param {ReturnType<typeof parseArgs>} args
+ * @param {{ client?: any }} [opts] an already-authenticated MCP client (entitled path)
+ * @returns {Promise<{kind:"public"|"entitled",version:string,url:string,strip:number,cacheKey:string}>}
+ */
+export async function resolveRendererSource(args, { client } = {}) {
+  if (args.sample) return resolvePublicRendererSource(args);
+  return resolveEntitledRendererSource(args, { client });
+}
+
+/**
+ * PUBLIC, un-entitled source for sample / zero-login mode: the moat-free runner
+ * straight from the public npm registry — NO MCP call, NO entitlement. Reads the
+ * package's registry metadata (unauthenticated JSON) for the tarball URL + version.
+ * Pin with `--renderer-version` / TOT_RUNNER_VERSION, else the `latest` dist-tag.
+ * Package/registry overridable via env for testing.
+ */
+export async function resolvePublicRendererSource(args, env = process.env) {
+  const pkg = env.TOT_RUNNER_PACKAGE || PUBLIC_RUNNER_PACKAGE;
+  const registry = (env.TOT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY).replace(/\/$/, "");
+  const pin = args.rendererVersion || env.TOT_RUNNER_VERSION || "latest";
+  const metaUrl = `${registry}/${pkg.replace("/", "%2f")}`;
+  const res = await fetch(metaUrl, { headers: { accept: "application/json" } });
+  if (!res.ok) {
+    throw new Error(`npm metadata for ${pkg} failed: HTTP ${res.status} ${res.statusText}`);
+  }
+  const meta = await res.json();
+  const version = meta?.["dist-tags"]?.[pin] || pin;
+  const tarball = meta?.versions?.[version]?.dist?.tarball;
+  if (!tarball) throw new Error(`no published ${pkg}@${version} on npm`);
+  return { kind: "public", version, url: tarball, strip: 1, cacheKey: `public-${version}` };
+}
+
+/**
+ * ENTITLED source: the MCP's `dev_renderer_artifact` signed URL, gated on the
+ * developer entitlement (same gate as the Docker pull token). Reuses an
+ * already-authenticated `client` when provided (C1/F3), else establishes its own.
+ */
+export async function resolveEntitledRendererSource(args, { client: providedClient } = {}) {
+  const baseUrl = args.mcp || process.env.MCP_BASE_URL || process.env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = providedClient || createMcpClient(baseUrl);
+  if (!providedClient) {
+    await client.initialize();
+    await resolveSession(client, { env: process.env });
+  }
+  const res = await client.callTool("dev_renderer_artifact", {});
+  if (!res?.url || !res?.version) {
+    throw new Error(res?.error || "no renderer-artifact URL returned");
+  }
+  return { kind: "entitled", version: res.version, url: res.url, strip: 0, cacheKey: res.version };
+}
+
 /**
  * Get the moat-free renderer artifact for this host — a signed URL from the MCP
  * (dev_renderer_artifact, same entitlement gate as the Docker pull token),
@@ -230,18 +372,111 @@ export async function ensureRendererArtifact(args, { client: providedClient } =
     throw new NativeArtifactUnavailableError(String(e?.message || e));
   }
 
-  const runnerDir = join(RENDERER_CACHE_ROOT, credential.version);
+  try {
+    return await installRunnerTarball(
+      { source: credential.url, version: credential.version, isUrl: true },
+      { log: (m) => console.error(m) },
+    );
+  } catch (e) {
+    throw new NativeArtifactUnavailableError(String(e?.message || e));
+  }
+}
+
+/**
+ * Resolve the renderer for the ZERO-LOGIN sample path WITHOUT any MCP call — the
+ * whole point of the free taste. Uses resolveRendererSource() (env override →
+ * cached runner from a prior `tot dev` → in-tree monorepo), and only when none of
+ * those exist does it fail with the exact seam WS3b fills (a public tarball URL).
+ * Unlike ensureRendererArtifact it does NOT fall back to Docker — the sample is
+ * deliberately Docker-free and login-free.
+ * @returns {Promise<string>} the runner tree's root directory (has scripts/tot-dev.mjs).
+ */
+export async function ensureSampleRenderer(args, ctx, { env = process.env } = {}) {
+  const src = resolveLocalRendererSource({
+    env,
+    mode: ctx?.mode,
+    repoRoot: ctx?.repoRoot,
+    cacheRoot: RENDERER_CACHE_ROOT,
+  });
+
+  if (src.kind === "dir") {
+    if (!existsSync(join(src.dir, "scripts", "tot-dev.mjs"))) {
+      throw new CliError(`the renderer at ${src.dir} has no scripts/tot-dev.mjs (source: ${src.why})`, {
+        next: "point TOT_RUNNER_DIR at a built runner tree, or unset it to fetch a tarball",
+        exitCode: 2,
+      });
+    }
+    console.error(`~ renderer: ${src.why} (${src.dir})`);
+    return src.dir;
+  }
+
+  if (src.kind === "tarball") {
+    console.error(`~ renderer: ${src.why}`);
+    return installRunnerTarball(
+      { source: src.source, version: sourceVersionKey(src.source), isUrl: src.isUrl },
+      { log: (m) => console.error(m) },
+    );
+  }
+
+  // kind === "none" — nothing local: fetch the PUBLIC runner from npm (the seam
+  // ws1b left for WS3b). No MCP, no entitlement, no login — the point of --sample.
+  let pub;
+  try {
+    pub = await resolvePublicRendererSource(args, env);
+  } catch (e) {
+    throw new CliError(
+      `can't run the sample — no local runner and the public runner is unavailable: ${e?.message || e}`,
+      {
+        next:
+          "check your network, set TOT_RUNNER_URL=<public renderer tarball>, or run `tot dev --sample` inside the storefront monorepo",
+        exitCode: 2,
+      },
+    );
+  }
+  console.error(`~ renderer: public npm ${pub.version} (${PUBLIC_RUNNER_PACKAGE})`);
+  return installRunnerTarball(
+    { source: pub.url, version: pub.cacheKey, isUrl: true, strip: pub.strip },
+    { log: (m) => console.error(m) },
+  );
+}
+
+/** A stable, filesystem-safe cache key for a renderer resolved from a tarball source. */
+function sourceVersionKey(source) {
+  const base =
+    String(source).split(/[?#]/)[0].split("/").pop()?.replace(/\.(tar\.gz|tgz)$/i, "") || "runner";
+  const h = createHash("sha1").update(String(source)).digest("hex").slice(0, 8);
+  return `sample-${base}-${h}`.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+/**
+ * Download (if a URL) or read (if a local path) a renderer tarball, extract it,
+ * `pnpm install` it, and cache the installed tree under
+ * ~/.tot/cache/renderer/<version>/ — atomically, so an interrupted run never
+ * leaves a half-built cache entry a later run treats as ready. Shared by the
+ * authenticated (ensureRendererArtifact) and zero-login (ensureSampleRenderer)
+ * paths so they cache identically.
+ *
+ * @param {{ source: string, version: string, isUrl?: boolean }} spec
+ * @param {{ log?: (m: string) => void }} [opts]
+ * @returns {Promise<string>} the cached, installed runner tree's root directory.
+ */
+export async function installRunnerTarball({ source, version, isUrl = true, strip = 0 }, { log = (m) => console.error(m) } = {}) {
+  const runnerDir = join(RENDERER_CACHE_ROOT, version);
   const marker = join(runnerDir, ".tot-cache-complete");
   if (existsSync(marker)) return runnerDir; // already downloaded + installed
 
-  console.error(`~ fetching the native renderer (version ${credential.version}, first run only)...`);
-  const archivePath = join(tmpdir(), `tot-renderer-${process.pid}-${Date.now()}.tar.gz`);
+  log(`~ preparing the native renderer (version ${version}, first run only)...`);
+  const localSource = isUrl ? null : resolveLocalTarball(source);
+  const archivePath = isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${Date.now()}.tar.gz`) : localSource;
   try {
-    await downloadFile(credential.url, archivePath);
+    if (isUrl) await downloadFile(source, archivePath);
+    if (!existsSync(archivePath)) {
+      throw new Error(`renderer tarball not found: ${archivePath}`);
+    }
     const stagingDir = `${runnerDir}.staging-${process.pid}`;
     rmSync(stagingDir, { recursive: true, force: true });
     mkdirSync(stagingDir, { recursive: true });
-    extractTarball(archivePath, stagingDir);
+    extractTarball(archivePath, stagingDir, { strip });
     ensureCorepackPnpm(stagingDir);
     runPnpmInstall(stagingDir);
     // Atomic-ish: only rename into the final, discoverable path once install
@@ -250,14 +485,23 @@ export async function ensureRendererArtifact(args, { client: providedClient } =
     rmSync(runnerDir, { recursive: true, force: true });
     renameSync(stagingDir, runnerDir);
     writeFileSync(marker, new Date().toISOString());
-  } catch (e) {
-    throw new NativeArtifactUnavailableError(String(e?.message || e));
   } finally {
-    rmSync(archivePath, { force: true });
+    if (isUrl) rmSync(archivePath, { force: true });
   }
   return runnerDir;
 }
 
+/** Strip an optional file:// prefix from a local tarball path and resolve it absolute. */
+function resolveLocalTarball(source) {
+  const s = String(source).startsWith("file://") ? fileURLToPathSafe(source) : source;
+  return resolve(s);
+}
+
+/** Minimal file:// → path (avoids importing node:url just for this one call). */
+function fileURLToPathSafe(u) {
+  return decodeURIComponent(String(u).replace(/^file:\/\//, "").replace(/^\/([A-Za-z]:)/, "$1"));
+}
+
 /** Stream `url` to `destPath`. Throws on a non-2xx response or a network failure. */
 async function downloadFile(url, destPath) {
   const res = await fetch(url);
@@ -267,9 +511,17 @@ async function downloadFile(url, destPath) {
   await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
 }
 
-/** Extract a .tar.gz into `destDir` using the system `tar` (present on macOS/Linux/WSL). */
-function extractTarball(archivePath, destDir) {
-  const r = spawnSync("tar", ["xzf", archivePath, "-C", destDir], { stdio: ["ignore", "ignore", "pipe"] });
+/**
+ * Extract a .tar.gz into `destDir` using the system `tar` (present on
+ * macOS/Linux/WSL). `strip` drops leading path components — the entitled artifact
+ * is a raw tree (strip 0), while an npm package tarball wraps everything under
+ * `package/` (strip 1), so both yield an identical tree root.
+ */
+function extractTarball(archivePath, destDir, { strip = 0 } = {}) {
+  const stripArgs = strip > 0 ? [`--strip-components=${strip}`] : [];
+  const r = spawnSync("tar", ["xzf", archivePath, "-C", destDir, ...stripArgs], {
+    stdio: ["ignore", "ignore", "pipe"],
+  });
   if (r.status !== 0) {
     throw new Error(`tar extraction failed: ${r.stderr?.toString().trim() || `exit ${r.status}`}`);
   }
@@ -315,10 +567,15 @@ function runPnpmInstall(runnerDir) {
  */
 export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit" } = {}) {
   const script = join(runnerDir, "scripts", "tot-dev.mjs");
+  // Translate the same "inherit"|"piped" contract spawnDevContainer honors:
+  // "piped" means stdin ignored + stdout/stderr captured so `tot start` can hold
+  // the prompt on stdin and stream the logs after the aha. child_process.spawn
+  // doesn't understand the bare string "piped", so map it to the array here.
+  const stdioArr = stdio === "piped" ? ["ignore", "pipe", "pipe"] : stdio;
   const child = spawn(
     process.execPath,
     [script, "--workspace", workspace, "--port", port],
-    { cwd: runnerDir, stdio },
+    { cwd: runnerDir, stdio: stdioArr },
   );
   const handle = { child, exited: false, done: null };
   handle.done = new Promise((resolvePromise) => {