@voltade/volty 0.1.9

package/README.md

@@ -0,0 +1,57 @@
+# @voltade/volty
+
+The Volty command-line tool for [Claude Code](https://claude.com/claude-code). You set it up once; after that, you don't use it directly — **Claude does**. It lets Claude test the Volty agent for real (safely, in a sandbox — nothing ever reaches a real contact) and look inside what the agent saw and decided.
+
+## One-time setup
+
+Open a terminal and run these four steps.
+
+**1. Install Bun** (skip if you already have it):
+
+```sh
+curl -fsSL https://bun.sh/install | bash
+```
+
+Then close and reopen your terminal.
+
+**2. Install the Volty tool:**
+
+```sh
+bun add -g @voltade/volty
+```
+
+**3. Teach Claude Code how to use it:**
+
+```sh
+volty skill install
+```
+
+**4. Log in** — this opens your browser; approve it with your normal Volty account:
+
+```sh
+volty auth login --env prod
+```
+
+To check it worked: `volty auth whoami --env prod` should print your email, org, and role.
+
+That's it. You never need to memorize any other commands.
+
+## Using it — just ask Claude
+
+Open Claude Code anywhere and ask in plain language. The skill you installed in step 3 kicks in automatically. For example:
+
+- *"Test the Volty agent — ask it whether we're GST registered."*
+- *"Send the agent a follow-up in that same test conversation."*
+- *"What did the agent actually reply with, and why? Show me what the LLM decided."*
+- *"Why didn't the agent learn anything from that conversation?"*
+- *"Clean up the test conversations on prod."*
+
+Claude knows the safety rules: tests run against a sandboxed draft version of the agent with a synthetic contact, so nothing can ever be sent to a real contact, and Claude cleans up after itself when it's done.
+
+## Upgrading
+
+When a newer version exists, the tool prints a notice — Claude will see it and upgrade for you. To do it yourself:
+
+```sh
+bun add -g @voltade/volty@latest && volty skill install
+```

package/dist/volty.js

@@ -0,0 +1,868 @@
+#!/usr/bin/env node
+
+// bin/volty.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join4 } from "node:path";
+
+// ../shared/ops/retired-prefix.ts
+function retiredPrefix(retired, argv) {
+  for (let n = Math.min(argv.length, 4);n >= 1; n--) {
+    const name = argv.slice(0, n).join(" ");
+    const replacement = retired[name];
+    if (replacement !== undefined)
+      return { name, replacement };
+  }
+  return null;
+}
+
+// src/api.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+var CATALOG_TTL_MS = 5 * 60 * 1000;
+var targetOrg;
+function setOrgOverride(org) {
+  targetOrg = org;
+}
+function authHeaders(ctx) {
+  const headers = {};
+  if (ctx.apiKey)
+    headers.authorization = `Bearer ${ctx.apiKey}`;
+  if (targetOrg)
+    headers["x-volty-org"] = targetOrg;
+  return headers;
+}
+async function apiFetch(ctx, path, init) {
+  if (!ctx.baseUrl)
+    throw new Error("no baseUrl for this context — run `volty env use <env> --base-url <url>`");
+  const res = await fetch(`${ctx.baseUrl}${path}`, {
+    method: init?.method ?? "GET",
+    headers: {
+      "content-type": "application/json",
+      ...authHeaders(ctx),
+      ...init?.headers
+    },
+    body: init?.body !== undefined ? JSON.stringify(init.body) : undefined
+  });
+  const text = await res.text();
+  let body = text;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {}
+  return { ok: res.ok, status: res.status, body };
+}
+var cachePath = (env) => join(tmpdir(), `volty-catalog-${env}-${targetOrg ?? "default"}.json`);
+async function fetchCatalog(ctx, env, useCache = true) {
+  const path = cachePath(env);
+  if (useCache && existsSync(path)) {
+    try {
+      const cached = JSON.parse(readFileSync(path, "utf8"));
+      if (Date.now() - cached.at < CATALOG_TTL_MS && cached.retired)
+        return { ops: cached.ops, retired: cached.retired };
+    } catch {}
+  }
+  const res = await apiFetch(ctx, "/api/v/_catalog");
+  if (!res.ok || !res.body.catalog) {
+    throw new Error(`could not fetch the operation catalog (HTTP ${res.status})${res.status === 401 ? " — run `volty auth login`" : ""}`);
+  }
+  const ops = res.body.catalog;
+  const retired = res.body.retired ?? {};
+  try {
+    mkdirSync(tmpdir(), { recursive: true });
+    writeFileSync(path, JSON.stringify({ at: Date.now(), ops, retired }));
+  } catch {}
+  return { ops, retired };
+}
+async function fetchOrgs(ctx, env, useCache = true) {
+  const path = join(tmpdir(), `volty-orgs-${env}.json`);
+  if (useCache && existsSync(path)) {
+    try {
+      const cached = JSON.parse(readFileSync(path, "utf8"));
+      if (Date.now() - cached.at < CATALOG_TTL_MS)
+        return cached.orgs;
+    } catch {}
+  }
+  const res = await apiFetch(ctx, "/api/cli/orgs");
+  if (!res.ok || !res.body.orgs) {
+    throw new Error(`could not fetch your org memberships (HTTP ${res.status})${res.status === 401 ? " - run `volty auth login`" : ""}`);
+  }
+  const orgs = res.body.orgs;
+  try {
+    writeFileSync(path, JSON.stringify({ at: Date.now(), orgs }));
+  } catch {}
+  return orgs;
+}
+function pathForOp(name) {
+  return `/api/v/${name.trim().split(/\s+/).join("/")}`;
+}
+
+// src/auth.ts
+import { spawn } from "node:child_process";
+
+// src/config.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join as join2 } from "node:path";
+var DEFAULT_BASE_URLS = {
+  dev: "http://localhost:3000",
+  prod: "https://volty.voltade.com"
+};
+var globalConfigPath = () => join2(homedir(), ".config", "volty", "config.json");
+function localConfigPath() {
+  let dir = process.cwd();
+  const home = homedir();
+  for (;; ) {
+    const candidate = join2(dir, ".volty", "config.json");
+    if (existsSync2(candidate))
+      return candidate;
+    if (existsSync2(join2(dir, ".git")) || dir === home)
+      return null;
+    const parent = dirname(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync2(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function emptyConfig() {
+  return { contexts: {} };
+}
+function loadConfig() {
+  const global = readJson(globalConfigPath()) ?? emptyConfig();
+  const localPath = localConfigPath();
+  const local = localPath ? readJson(localPath) : null;
+  if (!local)
+    return global;
+  const merged = {
+    current: local.current ?? global.current,
+    contexts: { ...global.contexts }
+  };
+  for (const [name, ctx] of Object.entries(local.contexts)) {
+    merged.contexts[name] = { ...merged.contexts[name], ...ctx };
+  }
+  return merged;
+}
+function saveConfig(config) {
+  const path = globalConfigPath();
+  mkdirSync2(dirname(path), { recursive: true });
+  writeFileSync2(path, `${JSON.stringify(config, null, 2)}
+`, { mode: 384 });
+}
+function activeEnv(config, envFlag) {
+  if (envFlag)
+    return envFlag;
+  if (config.current)
+    return config.current;
+  const names = Object.keys(config.contexts);
+  return names.length === 1 ? names[0] : "dev";
+}
+function ensureContext(config, env) {
+  const existing = config.contexts[env];
+  if (existing)
+    return existing;
+  const ctx = { baseUrl: DEFAULT_BASE_URLS[env] ?? "" };
+  config.contexts[env] = ctx;
+  return ctx;
+}
+
+// src/auth.ts
+async function whoami(ctx) {
+  if (!ctx.apiKey)
+    return null;
+  const res = await apiFetch(ctx, "/api/cli/whoami");
+  if (!res.ok || !res.body.organizationId)
+    return null;
+  ctx.organizationId = res.body.organizationId;
+  ctx.principal = res.body.email ?? res.body.name ?? res.body.userId;
+  return res.body;
+}
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd", "/c", "start", url] : ["xdg-open", url];
+  try {
+    const child = spawn(cmd[0], cmd.slice(1), { detached: true, stdio: "ignore" });
+    child.on("error", () => {});
+    child.unref();
+  } catch {}
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function deviceGrant(ctx) {
+  const start = await apiFetch(ctx, "/api/cli/grant", { method: "POST", body: {} });
+  if (!start.ok || !start.body.code || !start.body.verifyUrl) {
+    throw new Error(`could not start the device grant (HTTP ${start.status})`);
+  }
+  const { code, verifyUrl } = start.body;
+  process.stdout.write(`
+Authorize this CLI in your browser:
+  ${verifyUrl}
+
+Waiting for approval…
+`);
+  openBrowser(verifyUrl);
+  const deadline = Date.now() + 5 * 60 * 1000;
+  while (Date.now() < deadline) {
+    await sleep(2000);
+    const poll = await apiFetch(ctx, `/api/cli/grant/poll?code=${encodeURIComponent(code)}`);
+    if (poll.status === 404)
+      throw new Error("the authorization request expired — run `volty auth login` again");
+    if (poll.body.status === "approved" && poll.body.apiKey) {
+      if (poll.body.organizationId)
+        ctx.organizationId = poll.body.organizationId;
+      return poll.body.apiKey;
+    }
+  }
+  throw new Error("timed out waiting for browser approval");
+}
+async function devGrant(ctx, persona, org) {
+  const res = await apiFetch(ctx, "/api/cli/dev-grant", {
+    method: "POST",
+    body: { persona, ...org ? { org } : {} }
+  });
+  if (res.status === 404)
+    return null;
+  if (!res.ok || !res.body.apiKey) {
+    throw new Error(res.body?.error?.message ?? `the dev grant failed (HTTP ${res.status})`);
+  }
+  if (res.body.organizationId)
+    ctx.organizationId = res.body.organizationId;
+  return res.body.apiKey;
+}
+async function login(config, env, opts) {
+  const ctx = ensureContext(config, env);
+  if (opts.baseUrl)
+    ctx.baseUrl = opts.baseUrl;
+  if (!ctx.baseUrl)
+    throw new Error(`no base URL for '${env}' — pass --base-url <url>`);
+  if (!opts.rotate && await whoami(ctx)) {
+    return `Already authenticated to '${env}' as ${ctx.principal ?? "(unknown)"} — reusing the stored key.`;
+  }
+  if (opts.token) {
+    ctx.apiKey = opts.token;
+    const who = await whoami(ctx);
+    if (!who)
+      throw new Error("the provided --token did not validate");
+    return `Authenticated to '${env}' as ${ctx.principal ?? "(unknown)"} (org ${ctx.organizationId}).`;
+  }
+  if (opts.devPersona) {
+    const key = await devGrant(ctx, opts.devPersona, opts.org);
+    if (key) {
+      ctx.apiKey = key;
+      const who = await whoami(ctx);
+      return `Authenticated to '${env}' as ${who?.email ?? ctx.organizationId ?? "(unknown)"} (dev persona ${opts.devPersona}).`;
+    }
+    process.stdout.write(`The '${env}' server is not in development mode, so --as has no dev grant to use. Falling back to the browser grant.
+`);
+  }
+  ctx.apiKey = await deviceGrant(ctx);
+  const who = await whoami(ctx);
+  return `Authenticated to '${env}' as ${who?.email ?? ctx.organizationId ?? "(unknown)"}.`;
+}
+async function logout(config, env) {
+  const ctx = config.contexts[env];
+  if (!ctx?.apiKey)
+    return `No stored key for '${env}'.`;
+  await apiFetch(ctx, "/api/cli/logout", { method: "POST", body: {} });
+  ctx.apiKey = undefined;
+  ctx.principal = undefined;
+  return `Logged out of '${env}' (key revoked).`;
+}
+
+// ../shared/ops/flag-parse.ts
+function acceptsNull(prop) {
+  if (prop.type === "null")
+    return true;
+  return Array.isArray(prop.anyOf) && prop.anyOf.some((branch) => branch?.type === "null");
+}
+function valueBranch(prop) {
+  if (!Array.isArray(prop.anyOf) || !acceptsNull(prop))
+    return prop;
+  return prop.anyOf.find((branch) => branch?.type !== "null") ?? prop;
+}
+function coerce(flag, raw, prop0, UsageError) {
+  if (acceptsNull(prop0) && raw === "null")
+    return null;
+  const prop = valueBranch(prop0);
+  if (prop.type === "boolean") {
+    if (raw === undefined || raw === "true")
+      return true;
+    if (raw === "false")
+      return false;
+    throw new UsageError(`--${flag} expects true|false`);
+  }
+  if (raw === undefined)
+    throw new UsageError(`--${flag} requires a value`);
+  if (prop.type === "number" || prop.type === "integer") {
+    const n = Number(raw);
+    if (Number.isNaN(n))
+      throw new UsageError(`--${flag} expects a number`);
+    return n;
+  }
+  if (prop.type === "object") {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      throw new UsageError(`--${flag} expects JSON`);
+    }
+  }
+  return raw;
+}
+function jsonArrayValue(raw) {
+  if (raw === undefined || !raw.trimStart().startsWith("["))
+    return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function canonicalFlag(props, flag) {
+  if (props[flag])
+    return flag;
+  const camel = flag.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+  return props[camel] ? camel : undefined;
+}
+function parseFlagTokens(props, rest, UsageError) {
+  const input = {};
+  let json = false;
+  for (let i = 0;i < rest.length; i++) {
+    const token = rest[i];
+    if (token === "--json") {
+      json = true;
+      continue;
+    }
+    const match = /^--([^=\s]+)(?:=([\s\S]*))?$/.exec(token);
+    if (!match)
+      throw new UsageError(`unexpected argument '${token}' (flags only, see --help)`);
+    const raw0 = match[1];
+    const flag = canonicalFlag(props, raw0);
+    const prop = flag ? props[flag] : undefined;
+    if (!flag || !prop)
+      throw new UsageError(`unknown flag --${raw0}`);
+    let raw = match[2];
+    const next = rest[i + 1];
+    if (raw === undefined && valueBranch(prop).type !== "boolean" && next !== undefined && !next.startsWith("--")) {
+      raw = rest[++i];
+    }
+    if (prop.type === "array") {
+      const list = input[flag] ?? [];
+      const spread = jsonArrayValue(raw);
+      if (spread)
+        list.push(...spread);
+      else
+        list.push(coerce(flag, raw, prop.items ?? {}, UsageError));
+      input[flag] = list;
+    } else {
+      input[flag] = coerce(flag, raw, prop, UsageError);
+    }
+  }
+  return { input, json };
+}
+
+// src/dispatch.ts
+class CliUsageError extends Error {
+}
+function resolveOp(catalog, argv) {
+  const byName = new Map(catalog.map((c) => [c.name, c]));
+  for (let n = Math.min(argv.length, 4);n >= 1; n--) {
+    const op = byName.get(argv.slice(0, n).join(" "));
+    if (op)
+      return { op, rest: argv.slice(n) };
+  }
+  return null;
+}
+function parseFlags(op, rest) {
+  return parseFlagTokens(op.input.properties ?? {}, rest, CliUsageError);
+}
+async function runOp(ctx, op, input) {
+  const res = await apiFetch(ctx, pathForOp(op.name), { method: "POST", body: input });
+  return { status: res.status, ok: res.ok, body: res.body };
+}
+
+// src/format.ts
+function flagType(prop) {
+  if (Array.isArray(prop.enum))
+    return prop.enum.join("|");
+  if (prop.type === "number" || prop.type === "integer")
+    return "n";
+  if (prop.type === "boolean")
+    return "true|false";
+  if (prop.type === "array")
+    return "value, repeatable, or a JSON array";
+  if (prop.type === "object")
+    return "json";
+  return "text";
+}
+function kebab(name) {
+  return name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+function flagsOf(op) {
+  const props = op.input.properties ?? {};
+  const required = new Set(op.input.required ?? []);
+  return Object.entries(props).map(([name, prop]) => ({
+    name: kebab(name),
+    required: required.has(name),
+    type: flagType(prop),
+    description: prop.description
+  }));
+}
+function opUsage(op) {
+  const parts = [`volty ${op.name}`];
+  for (const f of flagsOf(op)) {
+    const token = `--${f.name}=<${f.type}>`;
+    parts.push(f.required ? token : `[${token}]`);
+  }
+  return parts.join(" ");
+}
+function renderCatalog(catalog) {
+  const lines = catalog.toSorted((a, b) => a.name.localeCompare(b.name)).map((op) => `  ${op.name}  —  ${op.description}`);
+  return [
+    "Run a Volty platform operation:  volty <operation> [--flags] [--json]",
+    "",
+    ...lines,
+    "",
+    "`volty <operation> --help` shows usage; `--json` returns the machine-readable result."
+  ].join(`
+`);
+}
+function renderOpHelp(op) {
+  const lines = [opUsage(op), "", op.description];
+  const flags = flagsOf(op);
+  if (flags.length > 0) {
+    lines.push("", "Flags:");
+    for (const f of flags) {
+      const optional = f.required ? "" : " (optional)";
+      lines.push(`  --${f.name}=<${f.type}>${optional}${f.description ? ` — ${f.description}` : ""}`);
+    }
+  }
+  if (op.prompt)
+    lines.push("", op.prompt);
+  lines.push("", "Add --json for the full machine-readable result.");
+  return lines.join(`
+`);
+}
+function renderError(body, status) {
+  const error = { code: body.error?.code ?? "http_error", message: body.error?.message ?? `HTTP ${status}`, status };
+  return JSON.stringify({ error }, null, 2);
+}
+function renderResult(body, json) {
+  if (json)
+    return JSON.stringify({ content: body.content, structuredContent: body.structuredContent }, null, 2);
+  const text = (body.content ?? []).map((b) => b.type === "text" ? b.text ?? "" : `[${b.type}]`).join(`
+`);
+  return text || "(no output)";
+}
+
+// src/org-guard.ts
+var ORG_NATIVE = new Set(["use", "current", "list"]);
+function isOrgFreeCommand(command) {
+  const [cmd, sub] = command;
+  if (!cmd || cmd === "help" || cmd === "--help")
+    return true;
+  if (command.includes("--help"))
+    return true;
+  if (cmd === "auth" || cmd === "env" || cmd === "docs" || cmd === "skill")
+    return true;
+  return cmd === "org" && ORG_NATIVE.has(sub ?? "");
+}
+function isProdShaped(env, baseUrl) {
+  if (env === "prod")
+    return true;
+  if (!baseUrl)
+    return false;
+  let host;
+  try {
+    host = new URL(baseUrl).hostname;
+  } catch {
+    return false;
+  }
+  return host !== "localhost" && host !== "127.0.0.1" && host !== "::1" && host !== "[::1]";
+}
+var PROD_ORG_REFUSAL = "prod needs an explicit org: pass --org <id> or VOLTY_ORG=<id>; run 'volty org list --env prod' to see your orgs";
+var STICKY_ORG_REFUSAL = "prod does not honour a sticky org: pass --org <id> or VOLTY_ORG=<id> on each command instead; run 'volty org list --env prod' to see your orgs";
+function resolveTargetOrg({ env, baseUrl, override, sticky, command }) {
+  if (!isProdShaped(env, baseUrl))
+    return { org: override ?? sticky };
+  if (override)
+    return { org: override };
+  if (isOrgFreeCommand(command))
+    return { org: undefined };
+  return { refusal: PROD_ORG_REFUSAL };
+}
+function describeOrgTarget(orgs, org, env) {
+  const match = orgs.find((o) => o.organizationId === org);
+  if (!match)
+    return { refusal: `org ${org} is not one of your memberships on ${env}` };
+  return { line: `→ ${env} · ${match.name} (${match.organizationId}) · ${match.role}` };
+}
+
+// src/proposals.ts
+function decideProposal(ctx, proposalId, decision, reason) {
+  return apiFetch(ctx, `/api/changes/proposals/${encodeURIComponent(proposalId)}/decide`, {
+    method: "POST",
+    body: { decision, ...reason ? { reason } : {} }
+  });
+}
+
+// src/update.ts
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname2, join as join3 } from "node:path";
+var CACHE_PATH = join3(homedir2(), ".config", "volty", "update-check.json");
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+var REGISTRY_LATEST = "https://registry.npmjs.org/@voltade/volty/latest";
+function currentVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync3(join3(import.meta.dirname, "..", "package.json"), "utf8"));
+    return pkg.version ?? null;
+  } catch {
+    return null;
+  }
+}
+function cmpVersion(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0;i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0)
+      return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+function readCache() {
+  try {
+    return JSON.parse(readFileSync3(CACHE_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeCache(cache) {
+  try {
+    mkdirSync3(dirname2(CACHE_PATH), { recursive: true });
+    writeFileSync3(CACHE_PATH, `${JSON.stringify(cache)}
+`);
+  } catch {}
+}
+async function maybePrintUpdateHint() {
+  if (process.env.VOLTY_NO_UPDATE_CHECK)
+    return;
+  if (import.meta.url.endsWith(".ts"))
+    return;
+  const current = currentVersion();
+  if (!current)
+    return;
+  let cache = readCache();
+  if (!cache || Date.now() - cache.checkedAt > CHECK_INTERVAL_MS) {
+    cache = { checkedAt: Date.now(), latest: cache?.latest };
+    try {
+      const res = await fetch(REGISTRY_LATEST, { signal: AbortSignal.timeout(1500) });
+      if (res.ok) {
+        const body = await res.json();
+        if (body.version)
+          cache.latest = body.version;
+      }
+    } catch {}
+    writeCache(cache);
+  }
+  if (cache.latest && cmpVersion(current, cache.latest) < 0) {
+    process.stderr.write(`volty ${current} → ${cache.latest} available — run \`bun add -g @voltade/volty@latest\`, ` + `then \`volty skill install\` to refresh the skill.
+`);
+  }
+}
+
+// bin/volty.ts
+function fail(message) {
+  process.stderr.write(`volty: ${message}
+`);
+  process.exit(1);
+}
+function failResult(label, body, status, json) {
+  if (json) {
+    process.stdout.write(`${renderError(body, status)}
+`);
+    process.exit(1);
+  }
+  fail(`${label}: ${body.error?.message ?? `HTTP ${status}`}`);
+}
+function takeValue(argv, name) {
+  const rest = [];
+  let value;
+  for (let i = 0;i < argv.length; i++) {
+    const t = argv[i];
+    if (t === name) {
+      value = argv[++i];
+    } else if (t.startsWith(`${name}=`)) {
+      value = t.slice(name.length + 1);
+    } else {
+      rest.push(t);
+    }
+  }
+  return { value, rest };
+}
+function takeBool(argv, name) {
+  const rest = argv.filter((t) => t !== name);
+  return { present: rest.length !== argv.length, rest };
+}
+async function handleAuth(rest, config, env, orgOverride) {
+  const sub = rest[0];
+  if (sub === "login") {
+    const token = takeValue(rest.slice(1), "--token");
+    const baseUrl = takeValue(token.rest, "--base-url");
+    const rotate = takeBool(baseUrl.rest, "--rotate");
+    const persona = takeValue(rotate.rest, "--as");
+    const msg = await login(config, env, {
+      token: token.value,
+      baseUrl: baseUrl.value,
+      rotate: rotate.present,
+      devPersona: persona.value ?? (process.env.VOLTY_DEV_PERSONA || undefined),
+      org: orgOverride
+    });
+    saveConfig(config);
+    process.stdout.write(`${msg}
+`);
+    return;
+  }
+  if (sub === "whoami") {
+    const ctx = config.contexts[env];
+    if (!ctx?.apiKey)
+      fail(`not logged in to '${env}' — run \`volty auth login --env ${env}\``);
+    const who = await whoami(ctx);
+    if (!who)
+      fail("the stored key did not validate — run `volty auth login --rotate`");
+    saveConfig(config);
+    process.stdout.write(`${who.email ?? who.userId} · org ${who.organizationId} · role ${who.role}
+`);
+    return;
+  }
+  if (sub === "logout") {
+    process.stdout.write(`${await logout(config, env)}
+`);
+    saveConfig(config);
+    return;
+  }
+  fail("usage: volty auth <login|whoami|logout> [--env <e>] [--as <persona>] [--org <slug-or-id>] (--as and --org are dev servers only)");
+}
+function handleEnv(rest, config, env) {
+  const sub = rest[0];
+  if (sub === "use") {
+    const name = rest[1];
+    if (!name)
+      fail("usage: volty env use <name> [--base-url <url>]");
+    const baseUrl = takeValue(rest.slice(2), "--base-url");
+    config.current = name;
+    const ctx = ensureContext(config, name);
+    if (baseUrl.value)
+      ctx.baseUrl = baseUrl.value;
+    saveConfig(config);
+    process.stdout.write(`Active env: ${name}${ctx.baseUrl ? ` (${ctx.baseUrl})` : ""}
+`);
+    return;
+  }
+  if (sub === "list") {
+    const names = Object.keys(config.contexts);
+    if (names.length === 0)
+      process.stdout.write("(no contexts — run `volty auth login --env dev`)\n");
+    for (const name of names) {
+      const ctx = config.contexts[name];
+      const marker = name === config.current ? "*" : " ";
+      process.stdout.write(`${marker} ${name}	${ctx?.baseUrl ?? ""}	${ctx?.principal ?? ""}
+`);
+    }
+    return;
+  }
+  if (sub === "current") {
+    const ctx = config.contexts[env];
+    process.stdout.write(`${env}	${ctx?.baseUrl ?? "(no base URL)"}	${ctx?.principal ?? "(not logged in)"}
+`);
+    return;
+  }
+  fail("usage: volty env <use|list|current>");
+}
+async function handleOrg(rest, config, env, target) {
+  const sub = rest[0];
+  const ctx = ensureContext(config, env);
+  if (sub === "use") {
+    const id = rest[1];
+    if (!id)
+      fail("usage: volty org use <organization-id> | volty org use --clear");
+    if (id === "--clear" || id === "default") {
+      ctx.activeOrg = undefined;
+      saveConfig(config);
+      process.stdout.write(`Org override cleared for '${env}' — using the key's default org.
+`);
+      return;
+    }
+    if (target.prod)
+      fail(STICKY_ORG_REFUSAL);
+    ctx.activeOrg = id;
+    saveConfig(config);
+    process.stdout.write(`Active org for '${env}': ${id}
+`);
+    return;
+  }
+  if (sub === "current") {
+    if (target.prod) {
+      process.stdout.write(`${target.org ?? "(none: prod needs --org <id> or VOLTY_ORG=<id>)"}
+`);
+      return;
+    }
+    process.stdout.write(`${ctx.activeOrg ?? "(key default)"}
+`);
+    return;
+  }
+  if (sub === "list") {
+    const json = takeBool(rest.slice(1), "--json");
+    if (!ctx.apiKey)
+      fail(`not logged in to '${env}' — run \`volty auth login --env ${env}\``);
+    const res = await apiFetch(ctx, "/api/cli/orgs");
+    if (!res.ok || !res.body.orgs)
+      failResult("org list", res.body, res.status, json.present);
+    if (json.present) {
+      process.stdout.write(`${JSON.stringify(res.body, null, 2)}
+`);
+      return;
+    }
+    const active = target.org ?? res.body.current;
+    if (res.body.orgs.length === 0)
+      process.stdout.write(`(no org memberships)
+`);
+    for (const o of res.body.orgs) {
+      const marker = o.organizationId === active ? "*" : " ";
+      process.stdout.write(`${marker} ${o.organizationId}	${o.role}	${o.name}
+`);
+    }
+    return;
+  }
+  fail("usage: volty org <use|current|list>");
+}
+async function handleChanges(rest, ctx) {
+  if (rest[0] !== "decide")
+    fail("usage: volty changes decide --proposal-id <id> --decision approve|reject [--reason <text>]");
+  const pid = takeValue(rest.slice(1), "--proposal-id");
+  const dec = takeValue(pid.rest, "--decision");
+  const reason = takeValue(dec.rest, "--reason");
+  const json = takeBool(reason.rest, "--json");
+  if (!pid.value)
+    fail("--proposal-id <id> is required");
+  if (dec.value !== "approve" && dec.value !== "reject")
+    fail("--decision must be approve or reject");
+  const res = await decideProposal(ctx, pid.value, dec.value, reason.value);
+  if (!res.ok)
+    failResult("changes decide", res.body, res.status, json.present);
+  if (json.present) {
+    process.stdout.write(`${JSON.stringify(res.body, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`${dec.value === "approve" ? "Approved" : "Rejected"} proposal ${res.body.proposal?.id ?? pid.value} → ${res.body.proposal?.status ?? "decided"}
+`);
+}
+async function handleDocs(config, env) {
+  const ctx = ensureContext(config, env);
+  if (!ctx.baseUrl)
+    fail(`no base URL for '${env}' — run \`volty env use ${env} --base-url <url>\``);
+  const res = await fetch(new URL("/llms.txt", ctx.baseUrl));
+  if (!res.ok)
+    fail(`GET ${ctx.baseUrl}/llms.txt → HTTP ${res.status}`);
+  process.stdout.write(await res.text());
+}
+function handleSkill(rest) {
+  if (rest[0] !== "install")
+    fail("usage: volty skill install");
+  const candidates = [
+    join4(import.meta.dirname, "..", "skill", "volty-cli-ops", "SKILL.md"),
+    join4(import.meta.dirname, "..", "..", ".claude", "skills", "volty-cli-ops", "SKILL.md")
+  ];
+  const source = candidates.find((p) => existsSync3(p));
+  if (!source)
+    fail("bundled SKILL.md not found — reinstall the @voltade/volty package");
+  const destDir = join4(homedir3(), ".claude", "skills", "volty-cli-ops");
+  mkdirSync4(destDir, { recursive: true });
+  writeFileSync4(join4(destDir, "SKILL.md"), readFileSync4(source, "utf8"));
+  process.stdout.write(`Installed the volty-cli-ops skill → ${join4(destDir, "SKILL.md")}
+`);
+}
+async function main() {
+  await maybePrintUpdateHint();
+  const envExtract = takeValue(process.argv.slice(2), "--env");
+  let argv = envExtract.rest;
+  const orgExtract = takeValue(argv, "--org");
+  argv = orgExtract.rest;
+  const cacheFlag = takeBool(argv, "--no-cache");
+  argv = cacheFlag.rest;
+  const config = loadConfig();
+  const env = activeEnv(config, envExtract.value ?? (process.env.VOLTY_ENV || undefined));
+  const peek = config.contexts[env];
+  const prod = isProdShaped(env, peek?.baseUrl);
+  const target = resolveTargetOrg({
+    env,
+    baseUrl: peek?.baseUrl,
+    override: orgExtract.value ?? (process.env.VOLTY_ORG || undefined),
+    sticky: peek?.activeOrg,
+    command: argv
+  });
+  if ("refusal" in target)
+    fail(target.refusal);
+  setOrgOverride(target.org);
+  const [cmd, ...rest] = argv;
+  if (cmd === "auth")
+    return handleAuth(rest, config, env, orgExtract.value ?? (process.env.VOLTY_ORG || undefined));
+  if (cmd === "env")
+    return handleEnv(rest, config, env);
+  if (cmd === "org" && ORG_NATIVE.has(rest[0] ?? ""))
+    return handleOrg(rest, config, env, { ...target, prod });
+  if (cmd === "docs")
+    return handleDocs(config, env);
+  if (cmd === "skill")
+    return handleSkill(rest);
+  const ctx = config.contexts[env];
+  if (!ctx?.apiKey)
+    fail(`not logged in to '${env}' — run \`volty auth login --env ${env}\``);
+  if (prod && !isOrgFreeCommand(argv) && target.org) {
+    const described = describeOrgTarget(await fetchOrgs(ctx, env, !cacheFlag.present), target.org, env);
+    if ("refusal" in described)
+      fail(described.refusal);
+    process.stderr.write(`${described.line}
+`);
+  }
+  if (cmd === "changes" && rest[0] === "decide")
+    return handleChanges(rest, ctx);
+  const catalog = await fetchCatalog(ctx, env, !cacheFlag.present);
+  if (!cmd || cmd === "help" || cmd === "--help") {
+    process.stdout.write(`${renderCatalog(catalog.ops)}
+`);
+    return;
+  }
+  const resolved = resolveOp(catalog.ops, argv);
+  if (!resolved) {
+    const retired = retiredPrefix(catalog.retired, argv);
+    if (retired)
+      fail(`\`${retired.name}\` is retired: ${retired.replacement}`);
+    fail(`unknown operation '${argv.join(" ")}' — run \`volty help\``);
+  }
+  if (resolved.rest.includes("--help")) {
+    process.stdout.write(`${renderOpHelp(resolved.op)}
+`);
+    return;
+  }
+  let parsed;
+  try {
+    parsed = parseFlags(resolved.op, resolved.rest);
+  } catch (err) {
+    if (err instanceof CliUsageError)
+      fail(err.message);
+    throw err;
+  }
+  const result = await runOp(ctx, resolved.op, parsed.input);
+  if (!result.ok)
+    failResult(resolved.op.name, result.body, result.status, parsed.json);
+  process.stdout.write(`${renderResult(result.body, parsed.json)}
+`);
+}
+main().catch((err) => fail(err instanceof Error ? err.message : String(err)));

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@voltade/volty",
+  "version": "0.1.9",
+  "description": "Remote CLI for the Volty platform — run operations, trigger real agent wakes, and inspect LLM I/O over an API key.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "volty": "dist/volty.js"
+  },
+  "files": [
+    "dist",
+    "skill"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build bin/volty.ts --target=node --banner='#!/usr/bin/env node' --outfile dist/volty.js",
+    "prepublishOnly": "bun run build && rm -rf skill && bun scripts/public-skill.ts"
+  }
+}

package/skill/volty-cli-ops/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: volty-cli-ops
+description: "Drive Volty's agent with the `volty` CLI: run a real agent turn in one command on either lane (a contact message or a staff session) and read what the model saw and did. Use whenever you need to exercise the live agent end to end: does an inbound trigger the right reply, learning or proposal, can Volty read or operate a connected system (CRM, MCP server, drive, channel), why did a tool call come back wrong. Reproducing a reported behaviour costs one command, so reach for it before theorising. Triggers: 'test the agent', 'trigger a wake', 'wake-sync', 'session-sync', 'ask Volty on prod', 'what did the agent do with X', 'run a real LLM turn', 'reproduce this inbound', 'can Volty see X?'."
+---
+
+# volty CLI
+
+The `volty` command runs Volty operations over an API key. Its main use is running a real agent turn (real model, real prompt, real operations) and then reading exactly what the model saw and did.
+
+This skill says which lane to use and what to keep to on prod. The commands and flags come from the server, so they always match it: `volty docs` prints the live guide (the same page as `/llms.txt`), `volty help` lists every op your key can run, and `volty <op> --help` shows one op's flags. Read `volty docs` once per session before the first prod command.
+
+## Install
+
+`bun add -g @voltade/volty`, then `volty skill install` to install or refresh this skill, then `volty auth login --env prod`. When the CLI prints an upgrade line, run `bun add -g @voltade/volty@latest` and `volty skill install` before continuing, because an old CLI or skill can describe commands the server has since changed.
+
+## Pick the lane
+
+- `debug wake-sync` sends a synthetic contact message into the org's sandbox: the contact lane.
+- `debug session-sync` runs a turn on the internal Volty chat as you: the staff lane.
+
+Use the lane the behaviour was reported on. On the contact lane Volty declines to list internal records to a contact, as it should, so "can Volty read our CRM or MCP server" belongs on the staff lane; asked on the contact lane, that refusal looks like a broken feature.
+
+## On prod
+
+- Name the org on every command (`--env prod --org <id>`, or `VOLTY_ENV` and `VOLTY_ORG` in the process), and read the stderr line the CLI prints before each command to check it names the org you meant. Act only in the org the user named.
+- Test through the sandbox, where every reply stays a draft. A real conversation is never a test target.
+- Run `volty debug sandbox-cleanup --all --env prod --org <id>` when you finish.
+- A `{pending:true}` result means the turn outran the wait, not that it failed: poll for it (`volty docs` names the command) instead of sending the message again.