@tokenoftrust/cli 1.4.0-rc.20 → 1.4.0-rc.22

package/src/commands/pr.mjs

@@ -7,7 +7,7 @@
  *   tot pr close <N|id>  close (reject) a candidate without merging
  *
  * A candidate PR is the reviewable unit `tot submit` creates. By default a
- * re-submit UPDATES your open candidate; `tot submit --new` forks another. This
+ * re-submit UPDATES your open candidate; `tot submit --fork-candidate` forks another. This
  * command fills the gap the raw submit loop left — a first-party way to list your
  * open candidates and to close one (candidate close was otherwise gated to
  * version-control apps only).
@@ -71,7 +71,7 @@ const USAGE = `tot pr — see and manage candidate PRs
 
   DEVELOPER (default) — run inside your OWN store checkout: lists/manages the
   candidates \`tot submit\` opens. A re-submit updates your open one by default;
-  \`tot submit --new\` forks another.
+  \`tot submit --fork-candidate\` forks another.
 
   OPERATOR — \`tot pr list --tenant <appDomain>\` lists ANY tenant's open candidate
   queue WITHOUT a checkout (the read-only companion to \`tot ship --pr <N> --tenant\`).
@@ -225,8 +225,9 @@ export async function runPrListOperator({ tenant, secret, storefrontUrl = null }
   if (!secret) {
     console.error(
       fail(
-        "listing a tenant's queue is an OPERATOR action — it needs an operator secret",
-        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+        "no operator secret — view this tenant's queue from the storefront admin instead.",
+        `open  https://${tenant}/admin  → Publish tab to see the candidate queue and act on it. ` +
+          "Operators/CI: set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret.",
       ),
     );
     return 2;
@@ -287,7 +288,7 @@ export async function run(argv, ctx) {
     console.log(USAGE);
     return 0;
   }
-  if (!SUBCOMMANDS.includes(args.sub)) {
+  if (!SUBCOMMANDS.includes(/** @type {any} */ (args.sub))) {
     console.error(fail(`unknown subcommand: \`tot pr ${args.sub}\``, "tot pr list | view <N> | close <N>"));
     return 2;
   }

package/src/commands/preview-doctor.mjs

@@ -0,0 +1,225 @@
+/**
+ * `tot preview doctor --tenant <t>` — the merge self-serve DIAGNOSIS in the terminal.
+ *
+ * Calls the hosted merge-doctor seam `GET /<tenant>/api/preview/merge-doctor` (unit
+ * A2) — which composes the SAME two server-side reads the admin Publish tab builds
+ * (`GET /api/changes` + `GET /api/changes/branches`) through the PURE `analyzeMerge`
+ * taxonomy — and prints its `{ scopeKnown, verdict, findings, counts }` as the compact,
+ * ordered (blocker → warn → info) report, each finding carrying who-owns-it and its
+ * remedy/action. It composes NO per-PR forge calls of its own: one GET, one answer.
+ *
+ * READ-ONLY — it mutates nothing, so there is NO plan/confirm gate (unlike `tot
+ * accept` / `tot preview build`). It just answers "what's blocking my merges, and
+ * what do I do about it?" in seconds.
+ *
+ * AUTH — the endpoint is session-gated exactly like `GET /api/changes`, so this
+ * reaches it by EITHER of the two transports `tot accept` already speaks:
+ *   - OPERATOR SECRET (operators / headless CI): Bearer + `X-Tot-Owner` on the
+ *     generic storefront origin (from PREVIEW_RECONCILE_SECRET / GRANTS_ADMIN_SECRET
+ *     / TOT_OPERATOR_SECRET, or `--secret`).
+ *   - VIEWER SESSION (an invited developer with no secret): mint a `tot_session`
+ *     from their own `tot login` on the tenant's own host (`resolveViewerTransport`).
+ * A caller who cannot see the accept queue cannot get a diagnosis of it — an auth
+ * refusal (401/403) is relayed as a clean house-style failure, not a wrapped verdict.
+ *
+ * EXIT CODE — mirrors the `scripts/tenant/gitea-merge-doctor.mjs` driver: a report
+ * with any blocker exits 1 (so a CI gate fails on a blocked merge), otherwise 0.
+ *
+ * The rendering helpers are the SHARED port in `../merge-doctor-report.mjs` (a
+ * faithful PORT of the analyzer's own `formatReport`/`attentionBanner`/
+ * `supportContext` — mergeDoctor.ts §render / the gitea-merge-doctor.mjs mirror);
+ * this package is the dependency-free published `@tokenoftrust/cli`, so it cannot
+ * import the app/scripts source, and the port is kept in sync with that taxonomy by
+ * hand. They live in their own module so `tot accept` / `tot ship` can reuse the same
+ * fetch + compact render (C5) without a cycle back through this command's transports.
+ *
+ * Dependency-free (global fetch + the shared viewer/operator transports).
+ */
+import { fail } from "../errors.mjs";
+import { resolveOperatorSecret } from "./ship.mjs";
+import { resolveViewerTransport } from "../viewer-session.mjs";
+import {
+  DOCTOR_PATH,
+  normalizeAnalysis,
+  attentionBanner,
+  supportContext,
+  formatReport,
+} from "../merge-doctor-report.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot preview doctor — diagnose what's blocking this tenant's merges
+
+  tot preview doctor                    diagnose the current checkout's tenant
+  tot preview doctor --tenant <t>       diagnose <t> (works without a checkout)
+  tot preview doctor --json             emit the raw { scopeKnown, verdict, findings, counts }
+
+  Calls the hosted merge-doctor (GET /api/preview/merge-doctor), which composes the
+  SAME reads the admin Publish tab builds and runs them through the shared analyzer,
+  and prints the ordered report: blockers first, then warnings, then info — each
+  finding names who resolves it (you / on-us / housekeeping) and the exact remedy.
+  Read-only: it mutates nothing and needs no confirmation.
+
+  Exit code: 1 if the report has any blocker (so it can gate CI), else 0.
+
+Options:
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --url <origin>         Storefront origin for the operator-secret path
+                         (default: env TOT_STOREFRONT_URL or ${DEFAULT_STOREFRONT_URL}).
+  --secret <s>           Operator secret (prefer the env vars below).
+  --json                 Print the raw analysis JSON instead of the report.
+  --help, -h             Show this help.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret). Without one, an
+  invited developer's own \`tot login\` session is used.`;
+
+/** Parse `tot preview doctor` argv. Pure — unit-testable. */
+export function parsePreviewDoctorArgs(argv) {
+  const a = { tenant: null, url: null, secret: null, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--json") a.json = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+// The render/normalize helpers (normalizeAnalysis / attentionBanner /
+// supportContext / formatReport) are the shared port in ../merge-doctor-report.mjs,
+// imported at the top of this file.
+
+// ── run ────────────────────────────────────────────────────────────────────────
+
+/**
+ * Fetch + render the merge-doctor report for one tenant. Resolves the SAME two
+ * transports `tot accept` uses (operator secret → generic origin + X-Tot-Owner;
+ * else viewer session → tenant host + cookie), GETs the hosted seam, and prints the
+ * ordered report (or raw JSON). `fetch`/`resolveViewerTransport` are injected so it
+ * is unit-tested with no network. Returns the process exit code (blocker → 1).
+ *
+ * @param {{ tenant:string, secret:string, storefrontUrl?:string|null,
+ *   json?:boolean, env?:NodeJS.ProcessEnv }} params
+ * @param {{ fetch?:typeof fetch, resolveViewerTransport?:typeof resolveViewerTransport }} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runDoctor(
+  { tenant, secret, storefrontUrl = null, json = false, env = process.env },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const resolveViewer = deps.resolveViewerTransport || resolveViewerTransport;
+
+  // Resolve the transport — operator secret preferred, else the developer's own
+  // viewer session on the tenant host.
+  let base;
+  let authHeaders;
+  if (secret) {
+    base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+    authHeaders = {
+      authorization: `Bearer ${secret}`,
+      "x-tot-owner": tenant,
+      "x-tot-capability": "ship-on-behalf",
+    };
+  } else {
+    const viewer = await resolveViewer({ tenant, env, fetchImpl });
+    if (!viewer.ok) {
+      console.error(fail(viewer.message, viewer.hint));
+      return 2;
+    }
+    base = viewer.base;
+    authHeaders = viewer.authHeaders;
+  }
+
+  let res;
+  try {
+    res = await fetchImpl(`${base}${DOCTOR_PATH}`, { method: "GET", headers: authHeaders });
+  } catch (e) {
+    console.error(
+      fail(
+        `couldn't reach the merge-doctor at ${base}: ${String(e?.message || e)}`,
+        "check --url / your network, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON / empty body */
+  }
+
+  // Session gating: the endpoint relays the queue read's auth refusal verbatim, so a
+  // caller who cannot see the accept queue cannot diagnose it.
+  if (res.status === 401 || res.status === 403) {
+    console.error(
+      fail(
+        `not authorized to diagnose ${tenant}'s merges: ${data?.error || `HTTP ${res.status}`}`,
+        "you need a live ship-on-behalf grant on this tenant (ask the store owner), or an operator secret authorised for it — then re-run",
+      ),
+    );
+    return 2;
+  }
+
+  if (!res.ok) {
+    console.error(
+      fail(
+        `the merge-doctor did not answer for ${tenant}: ${data?.error || `HTTP ${res.status}`}`,
+        "check --tenant / --url, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  const analysis = normalizeAnalysis(data);
+
+  if (json) {
+    console.log(JSON.stringify(analysis, null, 2));
+  } else {
+    console.log(formatReport(analysis));
+  }
+
+  // Mirror the scripts driver: any blocker fails the run so a CI gate catches it.
+  return analysis.counts.blocker > 0 ? 1 : 0;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx — detected CLI context (ctx.tenant when in a checkout)
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parsePreviewDoctorArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const tenant = (args.tenant || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "no target tenant.",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), or run inside a store checkout.",
+      ),
+    );
+    return 2;
+  }
+
+  const storefrontUrl =
+    args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+
+  return await runDoctor({
+    tenant,
+    secret: resolveOperatorSecret(args.secret, env),
+    storefrontUrl,
+    json: args.json,
+    env,
+  });
+}

package/src/commands/preview.mjs

@@ -45,7 +45,7 @@ export function postRunHint(code, alias) {
 /**
  * @param {string[]} argv
  * @param {any} ctx
- * @param {{ alias?: string|null }} [opts] — `alias` is the old verb the developer typed
+ * @param {{ alias?: string|null }} [opts] - `alias` is the old verb the developer typed
  *   (`"submit"` / `"deploy"`) when this flow is reached as a teaching alias; null/omitted
  *   for the first-class `tot preview`.
  */
@@ -59,6 +59,14 @@ export async function run(argv, ctx, { alias = null } = {}) {
     return runBuild(argv.slice(1), ctx);
   }
 
+  // `tot preview doctor …` is the read-only merge DIAGNOSIS subcommand (unit C1) —
+  // a distinct verb from the developer preview flow, dispatched before the submit-
+  // flow arg parse (like `build`). Only the first-class `tot preview` carries it.
+  if (!alias && argv[0] === "doctor") {
+    const { run: runDoctor } = await import("./preview-doctor.mjs");
+    return runDoctor(argv.slice(1), ctx);
+  }
+
   const verb = alias || "preview";
   const args = parseArgs(argv);
 

package/src/commands/rollback.mjs

@@ -63,7 +63,9 @@ const USAGE = `tot rollback [<versionId>] — instant re-point to a prior live v
 
 /** Parse `tot rollback` argv. Pure. Deliberately NO --yes/--force (see the header). */
 export function parseRollbackArgs(argv) {
+  /** @type {{ versionId: string|null, target: string|null, mcp: string|null, identity: string|null, help: boolean }} */
   const a = { versionId: null, target: null, mcp: null, identity: null, help: false };
+  /** @type {string[]} */
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
@@ -179,8 +181,8 @@ export function rollbackCandidates(history, currentVersionId) {
 /** Render the `tot rollback` (no args) history listing — the rollback-target
  *  picker (unit u2), each entry annotated with its immutable `/rev/<sha>` link
  *  (unit u5) when a storefront origin is available. Pure — unit-tested.
- * @param {{ tenant:string, target:string, current:Record<string,unknown>|null,
- *   candidates:Record<string,unknown>[], revisionBase?:string|null }} input
+ * @param {{ tenant:string, target:string, current:any,
+ *   candidates:any[], revisionBase?:string|null }} input
  * @returns {string[]}
  */
 export function renderHistory({ tenant, target, current, candidates, revisionBase }) {
@@ -209,7 +211,7 @@ export function renderHistory({ tenant, target, current, candidates, revisionBas
  */
 export function renderRollbackPreview({ tenant, target, toVersionId, preview }) {
   const lines = ["", `  This rollback will change the LIVE site for ${tenant}:`];
-  const current = preview.pointer?.current;
+  const current = /** @type {any} */ (preview.pointer?.current);
   if (current) lines.push(`    ${target}: ${current.versionId} → ${toVersionId}`);
   else lines.push(`    ${target}: → ${toVersionId}`);
   return lines;
@@ -258,7 +260,7 @@ export async function runRollback(client, { tenant, target, toVersionId, revisio
       );
       return 1;
     }
-    const candidates = rollbackCandidates(status.history, status.current?.versionId ?? null);
+    const candidates = rollbackCandidates(status.history, /** @type {any} */ (status).current?.versionId ?? null);
     for (const line of renderHistory({ tenant, target, current: status.current, candidates, revisionBase })) {
       console.log(line);
     }

package/src/commands/ship.mjs

@@ -48,6 +48,11 @@ import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
 import { openBrowser } from "../open.mjs";
 import { emitActivity } from "../activity.mjs";
+// C5 — the doctor PUSH: on a refused/failed ship (most tellingly "not green"),
+// auto-append the COMPACT summary over the SAME operator transport, so the operator
+// sees WHICH changes are keeping the aggregate from going green without a separate
+// `tot preview doctor` run.
+import { autoSurfaceDoctor } from "../merge-doctor-report.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 
@@ -327,6 +332,14 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
     "x-tot-capability": "ship-on-behalf",
   };
 
+  // C5 — auto-surface the merge-doctor on a refused/failed ship. Best-effort:
+  // fetches the hosted doctor over the SAME operator transport and prints the COMPACT
+  // summary; never throws and never touches the exit code. A clean/unreachable doctor
+  // prints nothing — so this only ever ADDS the "here's what's not green" context.
+  const surfaceDoctor = async () => {
+    for (const line of await autoSurfaceDoctor({ base, authHeaders, fetchImpl })) console.error(line);
+  };
+
   // 1. GET the read-only plan: the pinned sha + artifact digest + included PRs +
   //    rollback target + paywall verdict. Zero side effects.
   let planRes;
@@ -356,6 +369,9 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
   const plan = normalizeShipPlan(planData);
   if (!plan.ok) {
     console.error(fail(plan.message, refusalNextStep(plan.reason)));
+    // A not-green / no-passed-run refusal is exactly what the doctor diagnoses —
+    // name the changes keeping the aggregate red right here.
+    await surfaceDoctor();
     return 1;
   }
 
@@ -433,7 +449,9 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
     payload: { args: { command: "ship", subcommand: "ship.publish" } },
   });
 
-  return reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+  const code = reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+  if (code !== 0) await surfaceDoctor();
+  return code;
 }
 
 /**

package/src/commands/start.mjs

@@ -67,7 +67,7 @@ import {
   activityBridgeEnv, NativeArtifactUnavailableError,
 } from "./dev.mjs";
 import { scaffoldSample, isSampleCheckout, sampleConfig, SAMPLE_DIR_NAME } from "../sample.mjs";
-import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
+import { startHeartbeatFromEnv, resolveEditor } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
 import { milestoneBanner, cockpitUrlFrom, DEVELOPER_COCKPIT } from "../banner.mjs";
 import { IDEAS } from "./ideas.mjs";
@@ -262,11 +262,11 @@ export async function run(argv, ctx) {
     const dir = resolve(process.cwd(), tenant);
     // Resolve a free port so the URL we open/poll/print matches what the runner
     // binds (Vite strictPort is off → a busy port would drift). No-op if free.
-    const devArgs = {
+    const devArgs = /** @type {any} */ ({
       image: null, port: String(await firstFreePort(Number(args.port || 4321))), mcp: args.mcp,
       noLogin: false, noOpen: args.noOpen, docker: args.docker,
-    };
-    const runtime = { useDocker: args.docker, runnerDir: null };
+    });
+    const runtime = /** @type {{ useDocker: boolean, runnerDir: any }} */ ({ useDocker: args.docker, runnerDir: null });
     await Promise.all([
       ensureCheckout(client, tenant, dir, env),
       prefetchRuntime(client, devArgs, env, runtime, ctx),
@@ -318,7 +318,7 @@ export async function run(argv, ctx) {
     // (A3) so the "instant" claim is measured. The "Connect Claude" step is
     // intentionally removed for now — a blocking prompt here meant Ctrl-C'ing it
     // tore down the dev server; revisit AI-connect as a non-blocking step later.
-    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt), cockpitUrl);
+    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt), cockpitUrl, dir);
 
     // 7. hand the terminal to the running dev server until Ctrl-C.
     console.log("\n  Watching your store — edit content/home.html + save. Ctrl-C to stop.\n");
@@ -581,6 +581,10 @@ function noStoresError({ session, baseUrl, listErr, list = null }) {
  * the remembered last tenant (A4) — then remember whatever was decided so the
  * next bare `tot start` doesn't have to ask again.
  */
+/**
+ * @param {any} stores @param {any} args @param {any} env @param {string} baseUrl
+ * @param {{ session?: any, listErr?: string|null, list?: any }} [opts]
+ */
 async function resolveTenant(stores, args, env, baseUrl, { session = null, listErr = null, list = null } = {}) {
   const lastTenantPath = defaultLastTenantPath(env);
   const pick = pickTenant(stores, {
@@ -603,9 +607,10 @@ async function resolveTenant(stores, args, env, baseUrl, { session = null, listE
   } else {
     // Many stores, nothing remembered — choose. Non-interactive (no TTY /
     // --yes without a name) can't guess.
+    const many = /** @type {any} */ (pick);
     if (!isInteractive() || args.yes) {
       throw new CliError("you can build on several stores — pick one", {
-        next: `tot start --tenant <tenant>  (one of: ${pick.stores.map((s) => s.id).join(", ")})`,
+        next: `tot start --tenant <tenant>  (one of: ${many.stores.map((s) => s.id).join(", ")})`,
       });
     }
     // Loud + unmissable: a >1-store dev is often looking at their browser
@@ -614,11 +619,11 @@ async function resolveTenant(stores, args, env, baseUrl, { session = null, listE
     console.log("");
     console.log("  ⚑ ACTION NEEDED IN YOUR TERMINAL — you can build on several stores.");
     console.log("    Pick one here to light up your cockpit:\n");
-    pick.stores.forEach((s, i) => console.log(`    ${i + 1}. ${s.id}${s.name ? `  — ${s.name}` : ""}`));
+    many.stores.forEach((s, i) => console.log(`    ${i + 1}. ${s.id}${s.name ? `  — ${s.name}` : ""}`));
     console.log("");
-    const idx = await promptChoice(pick.stores.length);
+    const idx = await promptChoice(many.stores.length);
     console.log("");
-    tenant = pick.stores[idx].id;
+    tenant = many.stores[idx].id;
   }
 
   writeLastTenant(lastTenantPath, { mcpUrl: baseUrl, tenant });
@@ -685,6 +690,7 @@ export function formatElapsed(ms) {
  * Developer Cockpit URL, the one next step is framed as "edit a line → see it in
  * your cockpit"; otherwise it's the same edit-to-see-it-reload action.
  */
+/** @param {string} dir @param {string|null} [cockpitUrl] */
 function printCheckoutLanding(dir, cockpitUrl = null) {
   console.log("");
   console.log(`  📁 Your store code is at:  ${dir}`);
@@ -693,10 +699,38 @@ function printCheckoutLanding(dir, cockpitUrl = null) {
   console.log(`     content/home.html — you'll see it reflected in ${where}.`);
 }
 
+/**
+ * OS/editor-aware suggestions for opening the checkout, shown once at the
+ * "you're live" moment. $VISUAL/$EDITOR (same signal the cockpit's "open this
+ * file" hint uses — see dev-heartbeat.mjs#resolveEditor) wins when set;
+ * otherwise a short per-platform shortlist of common editor launch commands.
+ * Deliberately NOT probed against PATH — a spawnSync per candidate would add
+ * real latency to the crafted "aha" ending for the common case (nothing set),
+ * so this is a labeled suggestion list, not a detection result.
+ */
+function editorOpenLines(dir, { platform = process.platform, env = process.env } = {}) {
+  const configured = resolveEditor(env);
+  if (configured) return [`${configured} ${dir}`];
+  if (platform === "darwin") {
+    return [`code ${dir}      (VS Code, if installed)`, `cursor ${dir}    (Cursor, if installed)`, `open ${dir}      (Finder)`];
+  }
+  if (platform === "win32") {
+    return [`code ${dir}      (VS Code, if installed)`, `explorer ${dir}  (File Explorer)`];
+  }
+  return [`code ${dir}      (VS Code, if installed)`, `cursor ${dir}    (Cursor, if installed)`, `xdg-open ${dir}  (file manager)`];
+}
+
 /** The crafted "you're live" ending — a PROMINENT milestone banner (u2) that,
  * when we hold a Developer Cockpit URL, explicitly sends the developer BACK to
- * their cockpit as the next place to look. */
-function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
+ * their cockpit as the next place to look. Then: an OS-suited "open this in
+ * an editor" suggestion, and the four-pane layout tip (this terminal, cockpit,
+ * local preview, editor) so a build problem, a reload, and the code are never
+ * more than a glance apart. */
+/**
+ * @param {string} tenant @param {string} url @param {string|null} elapsed
+ * @param {string|null} [cockpitUrl] @param {string|null} [dir]
+ */
+function printLiveEnding(tenant, url, elapsed, cockpitUrl = null, dir = null) {
   const lines = [
     `✨  You're live.${elapsed ? `  (${elapsed})` : ""}`,
     `    ${url}`,
@@ -710,6 +744,20 @@ function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
   console.log(milestoneBanner(lines));
   console.log("  " + versionStamp("native"));
   console.log("");
+  if (dir) {
+    console.log("  Open your project in an editor (an AI coding agent like Claude works too —");
+    console.log("  same idea, different hands on the keyboard):");
+    for (const line of editorOpenLines(dir)) console.log(`     ${line}`);
+    console.log("");
+  }
+  console.log("  Keep THIS terminal open — it's your live build/status feed, the fastest way to");
+  console.log("  see a problem the moment it happens. Need the command line for something else?");
+  console.log("  Open a NEW terminal window rather than closing this one.");
+  console.log("");
+  console.log("  Best view: arrange this terminal, your Developer Cockpit, the local preview,");
+  console.log("  and your editor so you can see all four at once — site, cockpit, build status,");
+  console.log("  and code, together.");
+  console.log("");
 }
 
 /**