@revturbine/cli 0.3.0 → 0.4.0

package/README.md

@@ -1,12 +1,12 @@
 # revturbine-cli (`revturbine`)
 
-Verify [RevTurbine](https://revturbine.com) **ExportedConfig** files and ship
-them to a RevTurbine instance through the playbook-version lifecycle — from the
-terminal, the same operations the in-app Pre-Sales Agent performs.
+Validate [RevTurbine](https://revturbine.com) **Config Files** and ship them to
+a RevTurbine instance through the playbook-version lifecycle (draft → Release) —
+from the terminal, the same operations the in-app studios perform.
 
 `revturbine` is the command-line counterpart to the RevTurbine control plane. It
 schema-validates a config offline, authenticates to an instance via the browser
-(RFC 8628 device flow), and stages / deploys configs as playbook versions so
+(RFC 8628 device flow), and stages / launches configs as playbook versions so
 every change is reviewable and rollback-able.
 
 ## Install
@@ -25,38 +25,70 @@ Requires Node ≥ 20.
 ## Quick start
 
 ```bash
-revturbine signup                           # create an account (email + password + emailed code)
-revturbine verify ./export-config.json      # schema-validate locally (no network)
-revturbine login                            # authorize this machine (device flow)
-revturbine diff ./export-config.json        # dry-run: live config vs local, no writes
-revturbine upload ./export-config.json      # stage as a draft playbook version
-revturbine deploy <playbook-version-id>     # submit → approve → deploy (go live)
+revturbine signup                             # create an account (email + password + emailed code)
+revturbine login                              # authorize this machine (device flow)
+revturbine download --live --save ./config.json
+# …edit ./config.json…
+revturbine validate ./config.json             # schema-validate locally (no network)
+revturbine diff ./config.json --live          # what would change (no writes)
+revturbine launch ./config.json               # upload, gate, and go live
 ```
 
 `revturbine <command> --help` documents every flag.
 
+## Version selectors
+
+Commands that read a config name the version explicitly — there is no default:
+
+| Selector | Meaning |
+|---|---|
+| `<file>` / `--file <path>` | a local Config File |
+| `--draft` | the tenant's single open draft (resolved automatically) |
+| `--live` | the current live Release |
+| `--release <id>` | a specific playbook version / Release |
+
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `signup` | Create an account headlessly: email + password, then an emailed one-time code to verify, then a token is stored. A business-email domain already claimed by a workspace exits with "an admin must invite you" (no token). |
+| `signup` | Create an account headlessly: email + password, then an emailed one-time code to verify, then a token is stored. |
 | `login` / `logout` | Device-flow auth; tokens stored at `~/.revturbine/credentials.json` (mode 0600). |
-| `verify` | Schema-validate a config offline against the bundled schema. |
-| `diff` | Non-destructive: download the live config, diff against local, dry-run the import. |
-| `upload` | Stage a config as a draft playbook version (`--deploy` to also activate). |
-| `deploy` | Activate a staged draft: submit → approve → deploy. |
-| `validate` | Run config-validation against a staged draft. |
-| `export` | Download the live config (stdout, or `--save`). |
-| `status` | Show the active draft and recent releases. |
-| `discard` / `rollback` | Archive an open draft / revert a deployed playbook version. |
+| `whoami` | The resolved instance, tenant, credentials source, and whether the stored token works. |
+| `schema` | Emit the bundled `RevTurbineConfig` JSON schema (for agents to author against). |
+| `docs` | Print the canonical documentation URL. |
+| `download` | Fetch a config version (`--live` / `--draft` / `--release <id>`); `--save`, `--format flatbuffer`. |
+| `validate` | Offline schema validation of a `<file>`, or the full server catalog against the open draft (`--draft`). |
+| `diff` | Compare any two versions, first → second (dry-run, no writes). |
+| `show <kind>` | Summary tables: `plans` · `entitlements` · `segments` · `placements` · `trials` for any version. |
+| `upload` | Stage a Config File as the open draft. |
+| `launch` | Take a config live: validate (launch gate) → submit → approve → deploy. `launch <file>` or `launch --draft`. |
+| `discard` | Archive the open draft (`--yes`). |
+| `rollback` | Revert a deployed playbook version (creates a reverting draft; becomes `restore` once server-side entry copying lands). |
+| `status` | The live Release and the open draft, side by side. |
+| `history` | The Release Version Log, newest first. |
+| `preview` | The open draft's staged changes. |
 | `evaluate` | Run the live config's placement/entitlement decisions for a user context. |
-| `preview` | Runtime-impact preview of a draft playbook version. |
-| `promote` | Promote a compiled config from one environment to another. |
+
+`--json` on read commands emits machine-readable output. Results go to stdout,
+diagnostics to stderr.
+
+## Exit-code classes
+
+```
+0  success
+1  unexpected error (catch-all)
+2  bad usage — unknown command, flag, argument, or missing version selector
+3  authentication or permission denied
+4  validation blocked (schema failure, blocking findings, unknown id)
+5  conflict or stale state (e.g. a draft is already open)
+6  network or transient failure
+7  server error
+```
 
 ## Schema validation
 
 Validation is **mandatory** and runs fully offline against a vendored,
-version-stamped snapshot of RevTurbine's `ExportedConfigSchema`
+version-stamped snapshot of RevTurbine's `RevTurbineConfigSchema`
 (`src/schema/`, regenerated from the canonical schema via
 `npm run generate:schema`). The CLI never uploads a config it could not
 validate. `revturbine --version` reports both the CLI version and the schema

package/dist/cli.js

@@ -5,7 +5,9 @@ import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as rea
 import path2 from "path";
 import { createRequire } from "module";
 import { createInterface } from "readline/promises";
-import { Command, Option } from "commander";
+import { spawn as spawn2 } from "child_process";
+import { Command, CommanderError, Option } from "commander";
+import { z as z27 } from "zod";
 
 // src/schema/exported-config.snapshot.mjs
 import { z as z2 } from "zod";
@@ -5222,7 +5224,7 @@ var AuthSsoProviderSchema = IdField.extend({
 }).meta({ id: "AuthSsoProvider", "x-revturbine-schema-persistence": Persisted23, "x-revturbine-schema-exposure": Internal19 });
 
 // src/schema/version.ts
-var SCHEMA_VERSION = "0.1.106";
+var SCHEMA_VERSION = "0.1.107";
 
 // src/lib/credentials.ts
 import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
@@ -5553,7 +5555,7 @@ function formatDiff(diff) {
 }
 
 // src/lib/config-validate.ts
-var BLOCKING_SEVERITIES = /* @__PURE__ */ new Set(["error_draft", "error_publish"]);
+var BLOCKING_SEVERITIES = /* @__PURE__ */ new Set(["error_draft", "error_launch"]);
 function isBlockingFinding(finding) {
   return BLOCKING_SEVERITIES.has(finding.severity);
 }
@@ -5579,33 +5581,134 @@ async function fetchValidation(baseUrl, playbookVersionId, headers, fetchImpl =
   };
 }
 
-// src/cli.ts
+// src/lib/drafts.ts
+async function resolveActiveDraft(baseUrl, headers, fetchImpl = fetch) {
+  const res = await fetchImpl(`${baseUrl}/api/optimization/drafts`, { headers });
+  const json = await res.json().catch(() => ({}));
+  return { ok: res.ok, status: res.status, draft: res.ok ? json.active ?? null : null };
+}
+
+// src/lib/output.ts
+var EXIT = {
+  OK: 0,
+  /** Unexpected error (catch-all). */
+  UNEXPECTED: 1,
+  /** Bad usage — unknown command, flag, argument, or missing version selector. */
+  USAGE: 2,
+  /** Authentication or permission denied. */
+  AUTH: 3,
+  /** Validation blocked (schema failure, blocking findings, rejected config, unknown id). */
+  VALIDATION: 4,
+  /** Conflict or stale state (open draft exists, base moved). */
+  CONFLICT: 5,
+  /** Network or transient failure. */
+  NETWORK: 6,
+  /** Server error. */
+  SERVER: 7
+};
+function classFromStatus(status) {
+  if (status === 401 || status === 403) return EXIT.AUTH;
+  if (status === 409) return EXIT.CONFLICT;
+  if (status === 400 || status === 404 || status === 422) return EXIT.VALIDATION;
+  if (status >= 500) return EXIT.SERVER;
+  return EXIT.UNEXPECTED;
+}
+function isNetworkError(err) {
+  return err instanceof TypeError || err instanceof Error && /fetch failed|ECONN|ENOTFOUND|ETIMEDOUT|EAI_AGAIN/i.test(err.message);
+}
 var LOG = "[revturbine]";
+function diag(message) {
+  console.error(`${LOG} ${message}`);
+}
+function diagRaw(message) {
+  console.error(message);
+}
+function emit(data, json, humanText) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+  } else {
+    process.stdout.write(`${humanText ?? JSON.stringify(data, null, 2)}
+`);
+  }
+}
+function fail(cls, message) {
+  console.error(`${LOG} \u2717 ${message}`);
+  process.exit(cls);
+}
+
+// src/lib/selectors.ts
+var SelectorError = class extends Error {
+  code = "STATE_REQUIRED";
+  constructor(message) {
+    super(message);
+  }
+};
+function collectSelectors(opts, positionalFiles = []) {
+  const found = positionalFiles.map((path3) => ({ kind: "file", path: path3 }));
+  if (opts.file) found.push({ kind: "file", path: opts.file });
+  if (opts.draft) found.push({ kind: "draft" });
+  if (opts.live) found.push({ kind: "live" });
+  if (opts.release) found.push({ kind: "release", id: opts.release });
+  return found;
+}
+function describeSelector(sel) {
+  switch (sel.kind) {
+    case "file":
+      return sel.path;
+    case "draft":
+      return "--draft";
+    case "live":
+      return "--live";
+    case "release":
+      return `--release ${sel.id}`;
+  }
+}
+function requireSelectors(opts, positionalFiles, {
+  count,
+  allowed,
+  command
+}) {
+  const found = collectSelectors(opts, positionalFiles);
+  const choices = allowed.map((k) => k === "file" ? "<file>" : k === "release" ? "--release <id>" : `--${k}`).join(" / ");
+  const disallowed = found.find((s) => !allowed.includes(s.kind));
+  if (disallowed) {
+    throw new SelectorError(`${command} does not accept ${describeSelector(disallowed)} \u2014 use ${choices}.`);
+  }
+  if (found.length === 0) {
+    throw new SelectorError(
+      `STATE_REQUIRED \u2014 ${command} needs ${count === 1 ? "a version" : `${count} versions`}: ${choices}. There is no default.`
+    );
+  }
+  if (found.length !== count) {
+    throw new SelectorError(`${command} takes exactly ${count} version${count === 1 ? "" : "s"} (${choices}); got ${found.length}.`);
+  }
+  return found;
+}
+
+// src/cli.ts
+var DOCS_URL = "https://github.com/revt-eng/revturbine-cli#readme";
 var DEFAULT_URL = "https://revturbine.com/app";
 var schema = RevTurbineConfigSchema;
 function loadConfig(file) {
   const resolved = path2.resolve(file);
-  if (!existsSync2(resolved)) {
-    console.error(`${LOG} Config not found: ${resolved}`);
-    process.exit(1);
-  }
+  if (!existsSync2(resolved)) fail(EXIT.USAGE, `Config not found: ${resolved}`);
   try {
     return JSON.parse(readFileSync2(resolved, "utf8"));
   } catch (err) {
-    console.error(`${LOG} invalid JSON in ${resolved}: ${err.message}`);
-    process.exit(1);
+    fail(EXIT.VALIDATION, `invalid JSON in ${resolved}: ${err.message}`);
   }
 }
 function verifyConfig(file) {
   const parsed = loadConfig(file);
   const result = schema.safeParse(parsed);
   if (result.success) {
-    console.log(`${LOG} \u2713 ${file}: schema validation passed`);
+    diag(`\u2713 ${file}: schema validation passed`);
     return result.data;
   }
-  console.error(`${LOG} \u2717 ${file}: schema validation FAILED:`);
+  diag(`\u2717 ${file}: schema validation FAILED:`);
   for (const issue of result.error.issues) {
-    console.error(`  ${issue.path.join(".") || "<root>"}: ${issue.message}`);
+    diagRaw(`  ${issue.path.join(".") || "<root>"}: ${issue.message}`);
   }
   return null;
 }
@@ -5615,15 +5718,19 @@ function connect(rawUrl, explicitTenantId) {
   const cred = getCredential(url);
   const tenantId = explicitTenantId ?? cred?.tenant_id ?? "dev-tenant-001";
   const tenantSource = explicitTenantId ? "--tenant-id" : cred?.tenant_id ? "stored token" : "default";
-  console.log(`${LOG} Tenant ${tenantId} (${tenantSource}); credentials: ${dir} [${source}].`);
+  diag(`Tenant ${tenantId} (${tenantSource}); credentials: ${dir} [${source}].`);
   if (source === "global") {
-    console.warn(
-      `${LOG} WARNING: using the global ${dir} - NOT worktree-scoped. If this session is for a specific customer, run from that customer's worktree (with its own .revturbine/) so a stale login can't target the wrong tenant.`
+    diag(
+      `WARNING: using the global ${dir} - NOT worktree-scoped. If this session is for a specific customer, run from that customer's worktree (with its own .revturbine/) so a stale login can't target the wrong tenant.`
     );
   }
   return {
     url,
     tenantId,
+    tenantSource,
+    credentialsDir: dir,
+    credentialsSource: source,
+    hasToken: Boolean(cred),
     headers: {
       "Content-Type": "application/json",
       "x-tenant-id": tenantId,
@@ -5633,129 +5740,216 @@ function connect(rawUrl, explicitTenantId) {
 }
 function authHint(url, status) {
   if (status === 401 || status === 403) {
-    console.error(
-      `
-${LOG} Authentication required for ${url}. Log in with:
-  revturbine login ${url}`
-    );
+    diag(`Authentication required for ${url}. Log in with:
+  revturbine login ${url}`);
+  }
+}
+function httpFail(conn, what, status, detail) {
+  authHint(conn.url, status);
+  fail(classFromStatus(status), `${what} failed (${status})${detail ? `: ${JSON.stringify(detail)}` : ""}`);
+}
+async function request(conn, pathname, init) {
+  try {
+    return await fetch(`${conn.url}${pathname}`, { headers: conn.headers, ...init });
+  } catch (err) {
+    if (isNetworkError(err)) fail(EXIT.NETWORK, `network failure reaching ${conn.url}: ${err.message}`);
+    throw err;
   }
 }
 async function postJson(conn, pathname, body) {
-  const res = await fetch(`${conn.url}${pathname}`, {
-    method: "POST",
-    headers: conn.headers,
-    body: JSON.stringify(body)
-  });
+  const res = await request(conn, pathname, { method: "POST", body: JSON.stringify(body) });
+  const json = await res.json().catch(() => ({}));
+  return { res, json };
+}
+async function getJson(conn, pathname) {
+  const res = await request(conn, pathname);
   const json = await res.json().catch(() => ({}));
   return { res, json };
 }
-async function activatePlaybookVersion(conn, playbookVersionId) {
-  console.log(`
-${LOG} Activating playbook version ${playbookVersionId} (submit \u2192 approve \u2192 deploy) \u2026`);
+async function downloadConfig(conn, playbookVersionId) {
+  const qs = playbookVersionId ? `?playbookVersionId=${encodeURIComponent(playbookVersionId)}` : "";
+  const res = await request(conn, `/api/config/export${qs}`);
+  if (!res.ok) httpFail(conn, "download", res.status);
+  return res.json().catch(() => ({}));
+}
+async function requireOpenDraft(conn) {
+  const { ok, status, draft } = await resolveActiveDraft(conn.url, conn.headers);
+  if (!ok) httpFail(conn, "draft lookup", status);
+  if (!draft) fail(EXIT.VALIDATION, "No open draft for this tenant \u2014 stage one with `revturbine upload <file>`.");
+  return draft.id;
+}
+async function loadVersion(conn, sel) {
+  switch (sel.kind) {
+    case "file":
+      return loadConfig(sel.path);
+    case "live":
+      return downloadConfig(conn);
+    case "release":
+      return downloadConfig(conn, sel.id);
+    case "draft":
+      return downloadConfig(conn, await requireOpenDraft(conn));
+  }
+}
+async function launchDraft(conn, playbookVersionId) {
+  diag(`Launch gate: validating draft ${playbookVersionId} \u2026`);
+  const validation = await fetchValidation(conn.url, playbookVersionId, conn.headers);
+  if (!validation.ok) httpFail(conn, "validate", validation.status, validation.error);
+  if (validation.findings.length > 0) diagRaw(formatFindings(validation.findings));
+  if (hasBlockingFindings(validation.findings)) {
+    fail(EXIT.VALIDATION, "blocking findings \u2014 this draft cannot launch.");
+  }
+  diag(`Launching playbook version ${playbookVersionId} (submit \u2192 approve \u2192 deploy) \u2026`);
   for (const step of ["submit", "approve", "deploy"]) {
     const { res, json } = await postJson(conn, `/api/playbook-versions/${playbookVersionId}/${step}`, {});
     if (!res.ok) {
-      console.error(`${LOG} \u2717 ${step} failed (${res.status}). The draft is staged but NOT live.`);
-      console.error(`  ${JSON.stringify(json)}`);
-      console.error(`  Finish it from the UI (Drafts & Releases): playbook version ${playbookVersionId}`);
+      diag(`\u2717 ${step} failed (${res.status}). The draft is staged but NOT live.`);
+      diagRaw(`  ${JSON.stringify(json)}`);
+      diag(`Finish it from the UI (Drafts & Releases): playbook version ${playbookVersionId}`);
       authHint(conn.url, res.status);
-      process.exit(1);
+      process.exit(classFromStatus(res.status));
     }
-    console.log(`  \u2713 ${step}`);
+    diag(`  \u2713 ${step}`);
   }
-  console.log(`${LOG} \u2713 Deployed \u2014 the playbook version is now the live configuration.`);
-}
-async function getJson(conn, pathname) {
-  const res = await fetch(`${conn.url}${pathname}`, { headers: conn.headers });
-  const json = await res.json().catch(() => ({}));
-  return { res, json };
-}
-async function downloadLiveConfig(conn, playbookVersionId) {
-  const qs = playbookVersionId ? `?playbookVersionId=${encodeURIComponent(playbookVersionId)}` : "";
-  const res = await fetch(`${conn.url}/api/config/export${qs}`, { headers: conn.headers });
-  const config = res.ok ? await res.json().catch(() => ({})) : {};
-  return { res, config };
+  diag("\u2713 Launched \u2014 the playbook version is now the live configuration.");
 }
 async function confirmOrExit(promptText, yes) {
   if (yes) return;
   if (!process.stdin.isTTY) {
-    console.error(`${LOG} Refusing a destructive action without confirmation (no TTY). Pass --yes.`);
-    process.exit(1);
+    fail(EXIT.USAGE, "Refusing a destructive action without confirmation (no TTY). Pass --yes.");
   }
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
   const answer = (await rl.question(`${promptText} [y/N] `)).trim().toLowerCase();
   rl.close();
   if (answer !== "y" && answer !== "yes") {
-    console.log(`${LOG} Aborted.`);
+    diag("Aborted.");
     process.exit(0);
   }
 }
+function table(rows) {
+  if (rows.length === 0) return "  (none)";
+  const widths = rows[0].map((_, col) => Math.max(...rows.map((r) => (r[col] ?? "").length)));
+  return rows.map((r) => "  " + r.map((cell, i) => (cell ?? "").padEnd(widths[i])).join("  ")).join("\n");
+}
+var SHOW_KINDS = ["plans", "entitlements", "segments", "placements", "trials"];
+function renderShow(kind, config) {
+  const arr = (key) => Array.isArray(config[key]) ? config[key] : [];
+  const handleOf = (item) => item.handle ?? item.unique_handle ?? item.id ?? "";
+  switch (kind) {
+    case "plans": {
+      const plans = arr("plans");
+      const addons = arr("addons");
+      const ents = arr("entitlements");
+      const data = { plans, addons, entitlements: ents };
+      const text = [
+        `plans (${plans.length}):`,
+        table(plans.map((p) => [handleOf(p), p.name ?? "", `tier ${p.tier_position ?? "-"}`])),
+        `addons (${addons.length}):`,
+        table(addons.map((a) => [handleOf(a), a.name ?? ""])),
+        `entitlements (${ents.length}):`,
+        table(ents.map((e) => [handleOf(e), e.name ?? "", e.type ?? ""]))
+      ].join("\n");
+      return { data, text };
+    }
+    case "entitlements": {
+      const ents = arr("entitlements");
+      return { data: ents, text: table(ents.map((e) => [handleOf(e), e.name ?? "", e.type ?? ""])) };
+    }
+    case "segments": {
+      const segs = arr("segments");
+      return {
+        data: segs,
+        text: table(segs.map((s) => [handleOf(s), s.name ?? "", `${(s.predicates ?? []).length} predicate(s)`]))
+      };
+    }
+    case "placements": {
+      const pls = arr("placements");
+      return {
+        data: pls,
+        text: table(
+          pls.map((p) => [p.name ?? handleOf(p), p.category ?? "", p.trigger?.type ?? "", `${(p.payloads ?? []).length} payload(s)`])
+        )
+      };
+    }
+    case "trials": {
+      const free = arr("free_trial_rules");
+      const reverse = arr("reverse_trial_rules");
+      const data = { free_trial_rules: free, reverse_trial_rules: reverse };
+      const text = [
+        `free_trial_rules (${free.length}):`,
+        table(free.map((r) => [handleOf(r), r.name ?? ""])),
+        `reverse_trial_rules (${reverse.length}):`,
+        table(reverse.map((r) => [handleOf(r), r.name ?? ""]))
+      ].join("\n");
+      return { data, text };
+    }
+  }
+}
 var pkgVersion = createRequire(import.meta.url)("../package.json").version ?? "0.0.0";
 var HELP_AFTER = `
 Command groups:
-  Auth          login, logout
-  Validate      verify, diff
-  Stage/deploy  upload, deploy
-  Inspect       status, preview, export
-  Lifecycle     submit, approve, reject, discard, rollback
-  Runtime/ops   evaluate, promote
+  Auth & meta   login, logout, signup, whoami, schema, docs
+  Download      download
+  Check         validate, diff, show
+  Stage/launch  upload, launch, discard, rollback
+  Inspect       status, history, preview, evaluate
+
+Version selectors (no defaults \u2014 a command that reads a config requires one):
+  <file>            a local Config File (positional, or --file <path>)
+  --draft           the tenant's single open draft (resolved automatically)
+  --live            the current live Release
+  --release <id>    a specific playbook version / Release
 
 Common workflows:
   # Author, validate, and ship against the default instance (revturbine.com/app)
   revturbine login
-  revturbine verify ./export-config.json
-  revturbine diff ./export-config.json
-  revturbine upload ./export-config.json --deploy
+  revturbine download --live --save ./config.json
+  revturbine validate ./config.json
+  revturbine diff ./config.json --live
+  revturbine launch ./config.json
 
-  # Target a different instance \u2014 pass its URL (include the /app path)
-  revturbine login https://app.example.com/app
-  revturbine upload ./export-config.json --url https://app.example.com/app --deploy
-
-  # Manual review flow (stage \u2192 inspect \u2192 submit \u2192 approve \u2192 deploy)
-  revturbine upload ./export-config.json         # stage a draft playbook version
-  revturbine preview <playbook-version-id>       # inspect runtime impact
-  revturbine submit  <playbook-version-id>
-  revturbine approve <playbook-version-id>
-  revturbine deploy  <playbook-version-id>
+  # Manual review flow (stage \u2192 inspect \u2192 launch)
+  revturbine upload ./config.json          # stage as the open draft
+  revturbine preview                       # inspect the open draft
+  revturbine validate --draft              # full server catalog
+  revturbine launch --draft
 
   # Inspect and roll back
   revturbine status
+  revturbine history
   revturbine rollback <playbook-version-id>
 
-Default instance:
-  --url and the \`login\` argument default to https://revturbine.com/app \u2014
-  the /app subfolder is required for API routing. Pass an explicit URL (with its
-  /app path) to target another instance.
+Exit-code classes: 0 ok \xB7 1 unexpected \xB7 2 usage \xB7 3 auth \xB7 4 validation
+blocked \xB7 5 conflict/stale \xB7 6 network \xB7 7 server error.
 
 Auth:
   Most commands need a token \u2014 run \`login\` first. Credentials live at
   ~/.revturbine/credentials.json (0600); the token's tenant is used by default,
-  override with -t/--tenant-id. Mutating commands (discard, rollback, promote)
-  prompt for confirmation unless --yes.
+  override with -t/--tenant-id. Mutating commands (discard, rollback) prompt
+  for confirmation unless --yes.
 
-Full reference: https://github.com/revt-eng/revturbine-cli#commands
+Full reference: ${DOCS_URL}
 `;
 var program = new Command();
 program.hook("postAction", async (_thisCommand, actionCommand) => {
   const opts = actionCommand.opts();
+  if (actionCommand.name() === "validate" && !opts.draft) return;
   if (!shouldTrackCommandExecution(actionCommand.name(), Boolean(opts.url))) return;
   await trackEvent(opts.url, opts.tenantId, "cli_command_executed", {
     command: actionCommand.name()
   });
 });
-program.name("revturbine").description("Verify ExportedConfig files and load them into a RevTurbine instance via playbook versions.").version(`${pkgVersion} (schema ${SCHEMA_VERSION})`, "-V, --version", "Print the revturbine and bundled schema versions").showHelpAfterError().addHelpText("after", HELP_AFTER);
+program.name("revturbine").description("Validate RevTurbine Config Files and ship them through the playbook-version lifecycle (draft \u2192 Release).").version(`${pkgVersion} (schema ${SCHEMA_VERSION})`, "-V, --version", "Print the revturbine and bundled schema versions").showHelpAfterError().addHelpText("after", HELP_AFTER);
 program.command("login").description("Authorize this machine via the browser (device flow) and store a token for the instance (default: the production instance).").argument("[url]", `RevTurbine instance URL (default: ${DEFAULT_URL})`).action(async (url) => {
   try {
     const base = normalizeBaseUrl(url ?? DEFAULT_URL);
     await deviceLogin(base);
     await trackEvent(base, void 0, "cli_signed_in");
   } catch (err) {
-    console.error(`${LOG} \u2717 Login failed: ${err.message}`);
-    process.exit(1);
+    fail(EXIT.AUTH, `Login failed: ${err.message}`);
   }
 });
 async function promptLine(question) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
   try {
     return (await rl.question(question)).trim();
   } finally {
@@ -5763,10 +5957,10 @@ async function promptLine(question) {
   }
 }
 function promptHidden(question) {
-  const { stdin, stdout } = process;
+  const { stdin, stderr } = process;
   if (!stdin.isTTY) return promptLine(question);
   return new Promise((resolve) => {
-    stdout.write(question);
+    stderr.write(question);
     const wasRaw = stdin.isRaw;
     stdin.setRawMode(true);
     stdin.resume();
@@ -5782,24 +5976,24 @@ function promptHidden(question) {
         const code = ch.charCodeAt(0);
         if (code === 13 || code === 10 || code === 4) {
           cleanup();
-          stdout.write("\n");
+          stderr.write("\n");
           resolve(input.trim());
           return;
         }
         if (code === 3) {
           cleanup();
-          stdout.write("\n");
+          stderr.write("\n");
           process.exit(130);
         }
         if (code === 127 || code === 8) {
           if (input.length > 0) {
             input = input.slice(0, -1);
-            stdout.write("\b \b");
+            stderr.write("\b \b");
           }
           continue;
         }
         input += ch;
-        stdout.write("*");
+        stderr.write("*");
       }
     };
     stdin.on("data", onData);
@@ -5812,8 +6006,7 @@ program.command("signup").description("Create a RevTurbine account and log in (e
     const email = opts.email ?? await promptLine("Email: ");
     const password = opts.password ?? await promptHidden("Password: ");
     if (!name || !email || password.length < 8) {
-      console.error(`${LOG} \u2717 Name, email, and a password of at least 8 characters are required.`);
-      process.exit(1);
+      fail(EXIT.USAGE, "Name, email, and a password of at least 8 characters are required.");
     }
     const result = await signup({
       baseUrl,
@@ -5825,290 +6018,314 @@ program.command("signup").description("Create a RevTurbine account and log in (e
     if (result.status === "awaiting_invitation") process.exit(0);
     await trackEvent(baseUrl, void 0, "cli_signed_up");
   } catch (err) {
-    console.error(`${LOG} \u2717 Signup failed: ${err.message}`);
-    process.exit(1);
+    fail(EXIT.AUTH, `Signup failed: ${err.message}`);
   }
 });
 program.command("logout").description("Remove the stored token for <url>.").argument("[url]", `RevTurbine instance URL (default: ${DEFAULT_URL})`).action((url) => {
   const normalized = normalizeBaseUrl(url ?? DEFAULT_URL);
   const removed = removeCredential(normalized);
-  console.log(removed ? `${LOG} Logged out of ${normalized}.` : `${LOG} No stored credential for ${normalized}.`);
-});
-program.command("verify").description("Schema-validate one or more ExportedConfig files (offline).").argument("<config...>", "Path(s) to an export-config.json file").action((configs) => {
-  const failures = configs.filter((file) => verifyConfig(file) === null).length;
-  if (configs.length > 1) console.log(`
-${LOG} ${configs.length - failures}/${configs.length} passed.`);
-  process.exit(failures > 0 ? 1 : 0);
+  diag(removed ? `Logged out of ${normalized}.` : `No stored credential for ${normalized}.`);
 });
-program.command("diff").description("Non-destructive: download the tenant's live config, diff against the local config, and dry-run the import.").argument("<config>", "Path to an export-config.json file").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (configFile2, opts) => {
-  const config = verifyConfig(configFile2);
-  if (config === null) process.exit(1);
+program.command("whoami").description("Show the resolved instance, tenant, credentials source, and whether the stored token works.").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--json", "Machine-readable output").action(async (opts) => {
   const conn = connect(opts.url, opts.tenantId);
-  console.log(`
-${LOG} Comparing ${configFile2} against ${conn.url} (tenant ${conn.tenantId})\u2026`);
-  const { res: exportRes, config: current } = await downloadLiveConfig(conn);
-  if (!exportRes.ok && (exportRes.status === 401 || exportRes.status === 403)) {
-    console.error(`${LOG} \u2717 Could not download current config (${exportRes.status}).`);
-    authHint(conn.url, exportRes.status);
-    process.exit(1);
-  } else if (!exportRes.ok) {
-    console.log(`${LOG} (no current config \u2014 HTTP ${exportRes.status}; treating tenant as empty)`);
-  }
-  console.log(`
-${LOG} Diff (local vs tenant):`);
-  console.log(formatDiff(diffExportedConfig(current, config)));
-  const { res: dryRes, json: dry } = await postJson(conn, "/api/config/import?dryRun=true", config);
-  console.log(`
-${LOG} Dry-run checks:`, JSON.stringify(dry.checks ?? dry, null, 2));
-  const conflicts = Array.isArray(dry.conflicts) ? dry.conflicts : [];
-  if (conflicts.length) {
-    console.error(`
-${LOG} \u2717 ${conflicts.length} uniqueness conflict(s):`);
-    for (const c of conflicts) {
-      const why = c.scope === "existing" ? `handle already used by ${c.existing_id}` : `duplicated within the config (${c.config_id})`;
-      console.error(`  - ${c.collection}.${c.handle}: ${why}`);
-    }
-  }
-  if (!dryRes.ok || dry.ok === false) {
-    authHint(conn.url, dryRes.status);
-    console.error(`
-${LOG} Dry-run found problems. Fix them before uploading.`);
-    process.exit(1);
-  }
-  console.log(
-    `
-${LOG} \u2713 No conflicts. Stage it with:
-  revturbine upload ${configFile2} --url ${conn.url} --deploy`
+  let tokenValid = null;
+  if (conn.hasToken) {
+    const probe = await resolveActiveDraft(conn.url, conn.headers).catch(() => ({ ok: false, status: 0, draft: null }));
+    tokenValid = probe.ok || probe.status !== 401 && probe.status !== 403 && probe.status !== 0;
+  }
+  const data = {
+    instance: conn.url,
+    tenant: conn.tenantId,
+    tenant_source: conn.tenantSource,
+    credentials_dir: conn.credentialsDir,
+    credentials_source: conn.credentialsSource,
+    token_present: conn.hasToken,
+    token_valid: tokenValid
+  };
+  emit(
+    data,
+    Boolean(opts.json),
+    [
+      `instance:    ${data.instance}`,
+      `tenant:      ${data.tenant} (${data.tenant_source})`,
+      `credentials: ${data.credentials_dir} [${data.credentials_source}]`,
+      `token:       ${data.token_present ? tokenValid ? "present, valid" : "present, NOT accepted" : "absent \u2014 run `revturbine login`"}`
+    ].join("\n")
   );
 });
-program.command("upload").description("Stage an ExportedConfig file as a draft playbook version (POST /api/config/import). Use --deploy to also activate it.").argument("<config>", "Path to an export-config.json file").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").addOption(new Option("--deploy", "After staging, activate the draft (submit \u2192 approve \u2192 deploy)")).action(async (configFile2, opts) => {
-  const config = verifyConfig(configFile2);
-  if (config === null) {
-    console.error(`
-${LOG} Fix the issues above in ${configFile2}, then re-run.`);
-    process.exit(1);
+program.command("schema").description("Emit the bundled RevTurbineConfig JSON schema for an agent to author against.").option("--json", "Accepted for symmetry; output is always JSON").action(() => {
+  try {
+    const jsonSchema = z27.toJSONSchema(RevTurbineConfigSchema, { unrepresentable: "any" });
+    emit({ schema_version: SCHEMA_VERSION, schema: jsonSchema }, true);
+  } catch (err) {
+    fail(EXIT.UNEXPECTED, `could not render the bundled schema (${SCHEMA_VERSION}): ${err.message}`);
   }
-  const conn = connect(opts.url, opts.tenantId);
-  console.log(`
-${LOG} Staging ${configFile2} into a draft playbook version (${conn.url}/api/config/import) \u2026`);
-  const { res, json } = await postJson(conn, "/api/config/import", config);
-  if (!res.ok) {
-    console.error(`${LOG} \u2717 Upload failed (${res.status})`);
-    if (json && typeof json === "object" && json.stage) {
-      console.error(`  stage:  ${json.stage}`);
-      console.error(`  detail: ${JSON.stringify(json.detail)}`);
+});
+program.command("docs").description("Print the canonical documentation URL (and open it in a browser when interactive).").action(() => {
+  process.stdout.write(`${DOCS_URL}
+`);
+  if (process.stdout.isTTY) {
+    const [cmd, args] = process.platform === "win32" ? ["cmd", ["/c", "start", "", DOCS_URL]] : process.platform === "darwin" ? ["open", [DOCS_URL]] : ["xdg-open", [DOCS_URL]];
+    try {
+      spawn2(cmd, args, { stdio: "ignore", detached: true }).unref();
+    } catch {
+    }
+  }
+});
+program.command("download").description("Fetch a config version from the server. Requires --live, --draft, or --release <id>.").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--draft", "The tenant's open draft (rendered on demand)").option("--live", "The current live Release").option("--release <id>", "A specific playbook version / Release").addOption(new Option("-f, --format <format>", "Representation").choices(["json", "flatbuffer"]).default("json")).option("--save <file>", "Write to <file> instead of stdout").action(
+  async (opts) => {
+    const [sel] = requireSelectors(opts, [], { count: 1, allowed: ["draft", "live", "release"], command: "download" });
+    const conn = connect(opts.url, opts.tenantId);
+    const playbookVersionId = sel.kind === "release" ? sel.id : sel.kind === "draft" ? await requireOpenDraft(conn) : void 0;
+    if (opts.format === "flatbuffer") {
+      const qs = playbookVersionId ? `?playbookVersionId=${encodeURIComponent(playbookVersionId)}` : "";
+      const res = await request(conn, `/api/config/bundle${qs}`);
+      if (!res.ok) httpFail(conn, "bundle download", res.status);
+      const bytes = Buffer.from(await res.arrayBuffer());
+      if (opts.save) {
+        const out2 = path2.resolve(opts.save);
+        mkdirSync2(path2.dirname(out2), { recursive: true });
+        writeFileSync2(out2, bytes);
+        diag(`\u2713 Wrote ${bytes.length} bytes \u2192 ${out2}`);
+      } else {
+        process.stdout.write(`${bytes.toString("base64")}
+`);
+      }
+      return;
+    }
+    const config = await downloadConfig(conn, playbookVersionId);
+    const out = `${JSON.stringify(config, null, 2)}
+`;
+    if (opts.save) {
+      const file = path2.resolve(opts.save);
+      mkdirSync2(path2.dirname(file), { recursive: true });
+      writeFileSync2(file, out);
+      diag(`\u2713 Wrote ${file}`);
     } else {
-      console.error(`  ${JSON.stringify(json)}`);
+      process.stdout.write(out);
     }
-    authHint(conn.url, res.status);
-    process.exit(1);
   }
-  const playbookVersionId = json?.playbook_version_id;
-  console.log(`${LOG} \u2713 Staged ${configFile2} as a draft playbook version (${res.status})`);
-  console.log(`  imported: ${JSON.stringify(json.imported ?? {})}`);
-  if (playbookVersionId) console.log(`  playbook_version_id: ${playbookVersionId}`);
-  if (!opts.deploy) {
-    console.log(
-      `
-${LOG} Staged as a draft. Activate it with:
-` + (playbookVersionId ? `  revturbine deploy ${playbookVersionId} --url ${conn.url}
-` : "") + "  \u2026or from the RevTurbine UI (Drafts & Releases)."
-    );
-    return;
+);
+program.command("validate").description("Validate a Config File offline (schema), or the open draft against the full server catalog (--draft).").argument("[file...]", "Path(s) to a Config File (offline mode)").option("--draft", "Validate the open draft server-side (full catalog)").option("-u, --url <url>", "RevTurbine instance URL (used with --draft)", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (files, opts) => {
+  if (opts.draft && files.length > 0) fail(EXIT.USAGE, "validate takes either <file> or --draft, not both.");
+  if (!opts.draft && files.length === 0) {
+    throw new SelectorError("STATE_REQUIRED \u2014 validate needs a version: <file> (offline) or --draft (server catalog).");
   }
-  if (!playbookVersionId) {
-    console.warn(
-      `${LOG} No playbook_version_id returned \u2014 the server predates the playbook-version wire; nothing to deploy.`
-    );
-    return;
+  if (!opts.draft) {
+    const failures = files.filter((file) => verifyConfig(file) === null).length;
+    if (files.length > 1) diag(`${files.length - failures}/${files.length} passed.`);
+    process.exit(failures > 0 ? EXIT.VALIDATION : 0);
   }
-  await activatePlaybookVersion(conn, playbookVersionId);
-});
-program.command("deploy").description("Activate a staged draft playbook version: submit \u2192 approve \u2192 deploy.").argument("<playbook-version-id>", "The playbook_version_id returned by `upload`").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--yes", "Accepted for parity with discard/rollback; deploy has no confirmation prompt").action(async (playbookVersionId, opts) => {
-  const conn = connect(opts.url, opts.tenantId);
-  await activatePlaybookVersion(conn, playbookVersionId);
-});
-program.command("validate").description("Run config-validation against a staged draft. Prints findings; exits non-zero if any block.").argument("<playbook-version-id>", "The playbook_version_id to validate").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (playbookVersionId, opts) => {
   const conn = connect(opts.url, opts.tenantId);
+  const playbookVersionId = await requireOpenDraft(conn);
   const result = await fetchValidation(conn.url, playbookVersionId, conn.headers);
-  if (!result.ok) {
-    console.error(`${LOG} \u2717 validate failed (${result.status})${result.error ? `: ${result.error}` : ""}`);
-    authHint(conn.url, result.status);
-    process.exit(1);
-  }
-  console.log(`
-${LOG} Validation for playbook version ${playbookVersionId}:`);
-  console.log(formatFindings(result.findings));
+  if (!result.ok) httpFail(conn, "validate", result.status, result.error);
+  diag(`Validation for the open draft (${playbookVersionId}):`);
+  process.stdout.write(`${formatFindings(result.findings)}
+`);
   if (hasBlockingFindings(result.findings)) {
-    const blocking = result.findings.filter((f) => f.severity === "error_draft" || f.severity === "error_publish");
-    console.error(`${LOG} \u2717 ${blocking.length} blocking finding(s) \u2014 this draft cannot be deployed.`);
-    process.exit(1);
+    const blocking = result.findings.filter((f) => f.severity === "error_draft" || f.severity === "error_launch");
+    fail(EXIT.VALIDATION, `${blocking.length} blocking finding(s) \u2014 this draft cannot launch.`);
   }
-  console.log(`${LOG} \u2713 No blocking findings.`);
+  diag("\u2713 No blocking findings.");
 });
-program.command("export").description("Download the tenant's live config. JSON to stdout by default; --save <file> writes it to disk.").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").addOption(new Option("-f, --format <format>", "Representation").choices(["json", "flatbuffer"]).default("json")).option("--save <file>", "Write the downloaded config (json) or bundle (flatbuffer) to <file> instead of stdout").option("--playbook-version <id>", "Export a specific playbook version (default: the live configuration)").action(async (opts) => {
-  const conn = connect(opts.url, opts.tenantId);
-  const qs = opts.playbookVersion ? `?playbookVersionId=${encodeURIComponent(opts.playbookVersion)}` : "";
-  if (opts.format === "flatbuffer") {
-    const res2 = await fetch(`${conn.url}/api/config/bundle${qs}`, { headers: conn.headers });
-    if (!res2.ok) {
-      console.error(`${LOG} \u2717 bundle download failed (${res2.status})`);
-      authHint(conn.url, res2.status);
-      process.exit(1);
-    }
-    const bytes = Buffer.from(await res2.arrayBuffer());
-    if (opts.save) {
-      const out2 = path2.resolve(opts.save);
-      mkdirSync2(path2.dirname(out2), { recursive: true });
-      writeFileSync2(out2, bytes);
-      console.log(`${LOG} \u2713 Wrote ${bytes.length} bytes \u2192 ${out2}`);
-    } else {
-      process.stdout.write(`${bytes.toString("base64")}
+program.command("diff").description("Compare two config versions (first \u2192 second). Dry-run, no writes.").argument("[file...]", "Local Config File path(s)").option("--draft", "The tenant's open draft").option("--live", "The current live Release").option("--release <id>", "A specific playbook version / Release").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (files, opts) => {
+  const sels = requireSelectors(opts, files, { count: 2, allowed: ["file", "draft", "live", "release"], command: "diff" });
+  const needsServer = sels.some((s) => s.kind !== "file");
+  const conn = needsServer ? connect(opts.url, opts.tenantId) : null;
+  const [a, b] = await Promise.all(sels.map((s) => loadVersion(conn, s)));
+  diag(`Diff (${sels.map((s) => s.kind === "file" ? s.path : s.kind === "release" ? `--release ${s.id}` : `--${s.kind}`).join(" \u2192 ")}):`);
+  process.stdout.write(`${formatDiff(diffExportedConfig(a, b))}
 `);
+});
+program.command("show").description(`Render a summary view of a config version. <kind> \u2208 ${SHOW_KINDS.join(" | ")}.`).argument("<kind>", `One of: ${SHOW_KINDS.join(", ")}`).option("--file <path>", "A local Config File").option("--draft", "The tenant's open draft").option("--live", "The current live Release").option("--release <id>", "A specific playbook version / Release").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--json", "Machine-readable output").action(
+  async (kind, opts) => {
+    if (!SHOW_KINDS.includes(kind)) {
+      fail(EXIT.USAGE, `unknown kind '${kind}' \u2014 use one of: ${SHOW_KINDS.join(", ")}.`);
     }
-    return;
+    const [sel] = requireSelectors(opts, [], { count: 1, allowed: ["file", "draft", "live", "release"], command: "show" });
+    const needsServer = sel.kind !== "file";
+    const conn = needsServer ? connect(opts.url, opts.tenantId) : null;
+    const config = await loadVersion(conn, sel);
+    const { data, text } = renderShow(kind, config);
+    emit(data, Boolean(opts.json), text);
   }
-  const { res, config } = await downloadLiveConfig(conn, opts.playbookVersion);
+);
+program.command("upload").description("Stage a Config File as the open draft (POST /api/config/import).").argument("<config>", "Path to a Config File").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (configFile2, opts) => {
+  const config = verifyConfig(configFile2);
+  if (config === null) fail(EXIT.VALIDATION, `Fix the issues above in ${configFile2}, then re-run.`);
+  const conn = connect(opts.url, opts.tenantId);
+  diag(`Staging ${configFile2} as the open draft (${conn.url}/api/config/import) \u2026`);
+  const { res, json } = await postJson(conn, "/api/config/import", config);
   if (!res.ok) {
-    console.error(`${LOG} \u2717 export failed (${res.status})`);
-    authHint(conn.url, res.status);
-    process.exit(1);
-  }
-  const out = `${JSON.stringify(config, null, 2)}
-`;
-  if (opts.save) {
-    const file = path2.resolve(opts.save);
-    mkdirSync2(path2.dirname(file), { recursive: true });
-    writeFileSync2(file, out);
-    console.log(`${LOG} \u2713 Wrote ${file}`);
-  } else {
-    process.stdout.write(out);
+    if (json && typeof json === "object" && json.stage) {
+      diagRaw(`  stage:  ${json.stage}`);
+      diagRaw(`  detail: ${JSON.stringify(json.detail)}`);
+    } else {
+      diagRaw(`  ${JSON.stringify(json)}`);
+    }
+    httpFail(conn, "upload", res.status);
   }
+  const playbookVersionId = json?.playbook_version_id;
+  diag(`\u2713 Staged ${configFile2} as the open draft (${res.status})`);
+  diagRaw(`  imported: ${JSON.stringify(json.imported ?? {})}`);
+  if (playbookVersionId) diagRaw(`  playbook_version_id: ${playbookVersionId}`);
+  diag("Launch it with `revturbine launch --draft`, or from the UI (Drafts & Releases).");
 });
-program.command("status").description("Show the tenant's active draft playbook version and recent releases.").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (opts) => {
+program.command("launch").description("Take a config live as a new Release: validate (launch gate), then submit \u2192 approve \u2192 deploy. Synchronous.").argument("[file]", "Config File to upload and launch directly").option("--draft", "Launch the already-open draft").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--yes", "Accepted for parity with discard/rollback; launch has no confirmation prompt").action(async (file, opts) => {
+  const [sel] = requireSelectors(opts, file ? [file] : [], { count: 1, allowed: ["file", "draft"], command: "launch" });
   const conn = connect(opts.url, opts.tenantId);
-  const drafts = await getJson(conn, "/api/optimization/drafts");
-  if (!drafts.res.ok) {
-    console.error(`${LOG} \u2717 Could not read drafts (${drafts.res.status})`);
-    authHint(conn.url, drafts.res.status);
-    process.exit(1);
-  }
-  console.log(`
-${LOG} Drafts:`);
-  console.log(JSON.stringify(drafts.json, null, 2));
-  const rel = await getJson(conn, "/api/optimization/releases");
-  console.log(`
-${LOG} Recent releases:`);
-  console.log(JSON.stringify(rel.res.ok ? rel.json : { error: rel.res.status }, null, 2));
+  let playbookVersionId;
+  if (sel.kind === "file") {
+    const config = verifyConfig(sel.path);
+    if (config === null) fail(EXIT.VALIDATION, `Fix the issues above in ${sel.path}, then re-run.`);
+    diag(`Staging ${sel.path} as the open draft \u2026`);
+    const { res, json } = await postJson(conn, "/api/config/import", config);
+    if (!res.ok) {
+      diagRaw(`  ${JSON.stringify(json)}`);
+      httpFail(conn, "upload", res.status);
+    }
+    playbookVersionId = json?.playbook_version_id;
+    if (!playbookVersionId) fail(EXIT.SERVER, "No playbook_version_id returned by the import \u2014 cannot launch.");
+    diag(`\u2713 Staged (${playbookVersionId})`);
+  } else {
+    playbookVersionId = await requireOpenDraft(conn);
+  }
+  await launchDraft(conn, playbookVersionId);
 });
-program.command("discard").description("Discard (archive) an open draft playbook version so a new upload can proceed.").argument("<playbook-version-id>", "The draft playbook_version_id").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--yes", "Skip the confirmation prompt").action(async (playbookVersionId, opts) => {
+program.command("discard").description("Discard (archive) the open draft so a fresh one can start.").argument("[playbook-version-id]", "A specific draft id (default: the open draft)").option("--draft", "The open draft (explicit form of the default)").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--yes", "Skip the confirmation prompt").action(async (id, opts) => {
   const conn = connect(opts.url, opts.tenantId);
-  await confirmOrExit(`Discard draft playbook version ${playbookVersionId} on ${conn.url}?`, !!opts.yes);
+  const playbookVersionId = id ?? await requireOpenDraft(conn);
+  await confirmOrExit(`Discard draft ${playbookVersionId} on ${conn.url}?`, !!opts.yes);
   const { res, json } = await postJson(conn, `/api/playbook-versions/${playbookVersionId}/archive`, {});
-  if (!res.ok) {
-    console.error(`${LOG} \u2717 discard failed (${res.status}): ${JSON.stringify(json)}`);
-    authHint(conn.url, res.status);
-    process.exit(1);
-  }
-  console.log(`${LOG} \u2713 Discarded playbook version ${playbookVersionId}.`);
+  if (!res.ok) httpFail(conn, "discard", res.status, json);
+  diag(`\u2713 Discarded draft ${playbookVersionId}.`);
 });
-program.command("rollback").description("Roll back a deployed playbook version to the prior configuration (creates a reverting playbook version).").argument("<playbook-version-id>", "The deployed playbook_version_id to revert").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--yes", "Skip the confirmation prompt").action(async (playbookVersionId, opts) => {
+program.command("rollback").description("Roll back a deployed playbook version (creates a reverting draft). Becomes `restore <release>` once server-side entry copying lands (plan 131 TASK-6).").argument("<playbook-version-id>", "The deployed playbook_version_id to revert").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--yes", "Skip the confirmation prompt").action(async (playbookVersionId, opts) => {
   const conn = connect(opts.url, opts.tenantId);
   await confirmOrExit(
     `Roll back playbook version ${playbookVersionId} on ${conn.url}? This changes the LIVE configuration.`,
     !!opts.yes
   );
   const { res, json } = await postJson(conn, `/api/playbook-versions/${playbookVersionId}/rollback`, {});
-  if (!res.ok) {
-    console.error(`${LOG} \u2717 rollback failed (${res.status}): ${JSON.stringify(json)}`);
-    authHint(conn.url, res.status);
-    process.exit(1);
-  }
-  console.log(`${LOG} \u2713 Rollback requested for playbook version ${playbookVersionId}.`);
-  if (json?.playbook_version_id) console.log(`  reverting playbook_version_id: ${json.playbook_version_id}`);
+  if (!res.ok) httpFail(conn, "rollback", res.status, json);
+  diag(`\u2713 Rollback requested for playbook version ${playbookVersionId}.`);
+  const reverting = json?.item?.id ?? json?.playbook_version_id;
+  if (reverting) diagRaw(`  reverting draft: ${reverting}`);
 });
-program.command("evaluate").description("Run the live config's placement/entitlement decisions for a user context (from a JSON file).").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).requiredOption("--user <file>", "JSON file: { user_id, customer_id?, plan_handle?, placement_ids?, entitlement_handles?, traits?, now_iso? }").option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (opts) => {
+program.command("status").description("The current live Release and the open draft, side by side.").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--json", "Machine-readable output").action(async (opts) => {
   const conn = connect(opts.url, opts.tenantId);
-  if (!existsSync2(opts.user)) {
-    console.error(`${LOG} user file not found: ${opts.user}`);
-    process.exit(1);
-  }
-  let body;
-  try {
-    body = JSON.parse(readFileSync2(opts.user, "utf8"));
-  } catch (err) {
-    console.error(`${LOG} invalid JSON in ${opts.user}: ${err.message}`);
-    process.exit(1);
-  }
-  const { res, json } = await postJson(conn, "/api/sdk/evaluate", body);
-  if (!res.ok) {
-    console.error(`${LOG} \u2717 evaluate failed (${res.status}): ${JSON.stringify(json)}`);
-    authHint(conn.url, res.status);
-    process.exit(1);
-  }
-  console.log(JSON.stringify(json, null, 2));
+  const drafts = await getJson(conn, "/api/optimization/drafts");
+  if (!drafts.res.ok) httpFail(conn, "draft lookup", drafts.res.status);
+  const releases = await getJson(conn, "/api/optimization/releases");
+  const items = releases.res.ok && Array.isArray(releases.json?.items) ? releases.json.items : [];
+  const live = items.find((r) => r.status === "live") ?? items[0] ?? null;
+  const draft = drafts.json?.active ?? null;
+  const parked = Array.isArray(drafts.json?.parked) ? drafts.json.parked : [];
+  const data = { live, draft, parked };
+  const liveLine = live ? `v${live.version ?? "?"} "${live.playbook_version_name ?? live.name ?? ""}" (${live.playbook_version_id ?? live.id}) released ${live.released_at ?? "?"}` : "(none)";
+  const draftLine = draft ? `"${draft.name ?? ""}" (${draft.id}) status ${draft.status ?? "draft"}` : "(none)";
+  emit(
+    data,
+    Boolean(opts.json),
+    [
+      `Live release: ${liveLine}`,
+      `Open draft:   ${draftLine}`,
+      `Parked:       ${parked.length === 0 ? "(none)" : `${parked.length} draft(s)`}`
+    ].join("\n")
+  );
 });
-program.command("preview").description("Show the runtime-impact preview of a draft playbook version.").argument("<playbook-version-id>", "The draft playbook_version_id").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (playbookVersionId, opts) => {
+program.command("history").description("The Release Version Log: recent Releases, newest first.").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--json", "Machine-readable output").action(async (opts) => {
   const conn = connect(opts.url, opts.tenantId);
+  const { res, json } = await getJson(conn, "/api/optimization/releases");
+  if (!res.ok) httpFail(conn, "history", res.status);
+  const items = Array.isArray(json?.items) ? json.items : [];
+  emit(
+    items,
+    Boolean(opts.json),
+    table(
+      items.map((r) => [
+        `v${r.version ?? "?"}`,
+        r.status ?? "",
+        (r.released_at ?? "").slice(0, 19),
+        r.playbook_version_name ?? r.name ?? "",
+        r.playbook_version_id ?? r.id ?? ""
+      ])
+    )
+  );
+});
+program.command("preview").description("The open draft's staged changes (runtime-impact summary once plan 78 lands).").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--json", "Machine-readable output (default shape is already JSON)").action(async (opts) => {
+  const conn = connect(opts.url, opts.tenantId);
+  const playbookVersionId = await requireOpenDraft(conn);
   const { res, json } = await getJson(conn, `/api/playbook-versions/${playbookVersionId}/preview`);
-  if (!res.ok) {
-    console.error(`${LOG} \u2717 preview failed (${res.status}): ${JSON.stringify(json)}`);
-    authHint(conn.url, res.status);
-    process.exit(1);
-  }
-  console.log(JSON.stringify(json, null, 2));
+  if (!res.ok) httpFail(conn, "preview", res.status, json);
+  emit(json, true);
 });
-for (const step of ["submit", "approve", "reject"]) {
-  program.command(step).description(`Transition a playbook version: ${step}.`).argument("<playbook-version-id>", "The playbook_version_id").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (playbookVersionId, opts) => {
-    const conn = connect(opts.url, opts.tenantId);
-    const { res, json } = await postJson(conn, `/api/playbook-versions/${playbookVersionId}/${step}`, {});
-    if (!res.ok) {
-      console.error(`${LOG} \u2717 ${step} failed (${res.status}): ${JSON.stringify(json)}`);
-      authHint(conn.url, res.status);
-      process.exit(1);
-    }
-    console.log(`${LOG} \u2713 ${step} \u2192 playbook version ${playbookVersionId}`);
-  });
-}
-program.command("promote").description("Promote a compiled config from one environment to another.").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).requiredOption("--from <env>", "Source environment id").requiredOption("--to <env>", "Target environment id").option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").option("--yes", "Skip the confirmation prompt").action(async (opts) => {
+program.command("evaluate").description("Run the live config's placement/entitlement decisions for a user context (from a JSON file). Draft/Release-targeted evaluation lands with plan 131 TASK-7.").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).requiredOption("--user <file>", "JSON file: { user_id, customer_id?, plan_handle?, placement_ids?, entitlement_handles?, traits?, now_iso? }").option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(async (opts) => {
   const conn = connect(opts.url, opts.tenantId);
-  await confirmOrExit(`Promote config ${opts.from} \u2192 ${opts.to} on ${conn.url}?`, !!opts.yes);
-  const { res, json } = await postJson(conn, "/api/environments/promote", {
-    source_environment_id: opts.from,
-    target_environment_id: opts.to
-  });
-  if (!res.ok) {
-    console.error(`${LOG} \u2717 promote failed (${res.status}): ${JSON.stringify(json)}`);
-    authHint(conn.url, res.status);
-    process.exit(1);
+  if (!existsSync2(opts.user)) fail(EXIT.USAGE, `user file not found: ${opts.user}`);
+  let body;
+  try {
+    body = JSON.parse(readFileSync2(opts.user, "utf8"));
+  } catch (err) {
+    fail(EXIT.VALIDATION, `invalid JSON in ${opts.user}: ${err.message}`);
   }
-  console.log(`${LOG} \u2713 Promotion ${opts.from} \u2192 ${opts.to} requested.`);
+  const { res, json } = await postJson(conn, "/api/sdk/evaluate", body);
+  if (!res.ok) httpFail(conn, "evaluate", res.status, json);
+  emit(json, true);
 });
 var COMMAND_EXAMPLES = {
-  upload: [
+  download: [
+    "",
+    "Examples:",
+    "  revturbine download --live --save ./config.json     The live config \u2192 file",
+    "  revturbine download --draft                         The open draft (rendered on demand) \u2192 stdout",
+    "  revturbine download --release cs_1a2b3c --format flatbuffer --save ./bundle.fb"
+  ].join("\n"),
+  validate: [
+    "",
+    "Examples:",
+    "  revturbine validate ./config.json      Offline schema validation (no network)",
+    "  revturbine validate --draft            Full server catalog against the open draft"
+  ].join("\n"),
+  diff: [
     "",
     "Examples:",
-    "  revturbine upload ./export-config.json --url <url>             Stage as a draft playbook version",
-    "  revturbine upload ./export-config.json --url <url> --deploy    Stage, then submit \u2192 approve \u2192 deploy"
+    "  revturbine diff ./config.json --live   Local edits vs the live config",
+    "  revturbine diff --live --draft         What the open draft would change"
   ].join("\n"),
-  deploy: ["", "Example:", "  revturbine deploy cs_1a2b3c --url <url>        Activate a staged draft"].join("\n"),
-  export: [
+  show: ["", "Examples:", "  revturbine show plans --live", "  revturbine show segments --file ./config.json"].join("\n"),
+  upload: ["", "Example:", "  revturbine upload ./config.json        Stage as the open draft"].join("\n"),
+  launch: [
     "",
     "Examples:",
-    "  revturbine export --url <url>                                 Active playbook version \u2192 stdout (JSON)",
-    "  revturbine export --url <url> --save ./export-config.json     Write the live config to a file",
-    "  revturbine export --url <url> --format flatbuffer --save ./bundle.fb  Compiled bundle \u2192 file",
-    "  revturbine export --url <url> --playbook-version cs_1a2b3c    A specific playbook version\u2019s frozen snapshot"
+    "  revturbine launch ./config.json        Upload, gate, and go live",
+    "  revturbine launch --draft              Launch the already-open draft"
   ].join("\n"),
   evaluate: [
     "",
     "Example:",
     "  revturbine evaluate --url <url> --user ./ctx.json",
     '    ctx.json: { "user_id": "u1", "plan_handle": "pro", "entitlement_handles": ["seats"] }'
-  ].join("\n"),
-  promote: ["", "Example:", "  revturbine promote --url <url> --from production --to staging"].join("\n")
+  ].join("\n")
 };
 for (const [name, text] of Object.entries(COMMAND_EXAMPLES)) {
   program.commands.find((c) => c.name() === name)?.addHelpText("after", text);
 }
-await program.parseAsync(process.argv);
+program.exitOverride();
+try {
+  await program.parseAsync(process.argv);
+} catch (err) {
+  if (err instanceof CommanderError) {
+    if (err.code === "commander.helpDisplayed" || err.code === "commander.version" || err.code === "commander.help") {
+      process.exit(0);
+    }
+    process.exit(EXIT.USAGE);
+  }
+  if (err instanceof SelectorError) {
+    console.error(`[revturbine] \u2717 ${err.message}`);
+    process.exit(EXIT.USAGE);
+  }
+  console.error(`[revturbine] \u2717 ${err.message}`);
+  process.exit(EXIT.UNEXPECTED);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revturbine/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "revturbine — verify RevTurbine ExportedConfig files and ship them to a RevTurbine instance through the Change Set lifecycle.",
   "license": "MIT",
   "repository": {