@voltade/volty 0.1.20 → 0.1.22

package/dist/volty.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // bin/volty.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync6 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 
 // src/api.ts
 import { createHash } from "node:crypto";
@@ -646,16 +646,422 @@ function decideProposal(ctx, proposalId, decision, reason) {
   });
 }
 
+// src/pull.ts
+import { createHash as createHash2 } from "node:crypto";
+import { chmodSync, existsSync as existsSync4, mkdirSync as mkdirSync3, readdirSync, readFileSync as readFileSync4, unlinkSync, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname2, join as join3 } from "node:path";
+async function call(ctx, name, input = {}) {
+  const res = await runOp(ctx, { name }, input);
+  if (!res.ok)
+    throw new Error(`${name}: ${res.body?.error?.message ?? `HTTP ${res.status}`}`);
+  const structured = res.body.structuredContent;
+  if (structured?.refused)
+    return { refused: res.body.content?.[0]?.text ?? `${name} refused` };
+  return { value: structured };
+}
+async function read(ctx, name, input = {}) {
+  const out = await call(ctx, name, input);
+  if ("refused" in out)
+    throw new Error(`${name}: ${out.refused}`);
+  return out.value;
+}
+function slugBase(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/^-+|-+$/g, "");
+  return slug || "source";
+}
+function tsLiteral(value, indent = "") {
+  if (value === null || typeof value !== "object")
+    return JSON.stringify(value) ?? "undefined";
+  const next = `${indent}  `;
+  if (Array.isArray(value)) {
+    if (value.length === 0)
+      return "[]";
+    return `[
+${value.map((v) => `${next}${tsLiteral(v, next)}`).join(`,
+`)},
+${indent}]`;
+  }
+  const entries = Object.entries(value).filter(([, v]) => v !== undefined);
+  if (entries.length === 0)
+    return "{}";
+  const key = (k) => /^[A-Za-z_$][\w$]*$/.test(k) ? k : JSON.stringify(k);
+  return `{
+${entries.map(([k, v]) => `${next}${key(k)}: ${tsLiteral(v, next)}`).join(`,
+`)},
+${indent}}`;
+}
+function tsFile(header, value) {
+  return `// ${header[0]}
+// ${header[1]}
+export default ${tsLiteral(value)}
+`;
+}
+var sha256 = (text) => createHash2("sha256").update(text).digest("hex");
+
+class Observed {
+  sections = new Map;
+  add(heading, line) {
+    let lines = this.sections.get(heading);
+    if (!lines) {
+      lines = [];
+      this.sections.set(heading, lines);
+    }
+    lines.push(line);
+  }
+  render() {
+    const blocks = [...this.sections].map(([heading, lines]) => `${heading}
+${lines.map((l) => `- ${l}`).join(`
+`)}`);
+    return `${[OBSERVED_HEAD, ...blocks].join(`
+
+`)}
+`;
+  }
+}
+var OBSERVED_HEAD = "Read-only. What this workspace holds outside the project as of the last volty pull: data Volty and staff write in the app, and what has no project file yet. Editing this file changes nothing, and volty pull rewrites it.";
+var WAITING_HEADING = "Versions waiting for approval (the files hold the running version)";
+var DRIVE_HEADING = "Drive files (the workspace Drive, which the project does not hold)";
+var part = () => ({ files: new Map, observed: new Observed });
+async function pooled(items, fn, size = 6) {
+  const out = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const i = next++;
+      out[i] = await fn(items[i]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(size, items.length) }, worker));
+  return out;
+}
+function ruleOut(rule) {
+  const { teamId, userId, userIds, ...action } = rule.action;
+  return {
+    enabled: rule.enabled,
+    condition: rule.condition,
+    action: {
+      ...action,
+      ...teamId ? { team: rule.teamSlug } : {},
+      ...userId ? { member: rule.memberEmails[0] ?? null } : {},
+      ...userIds ? { members: rule.memberEmails } : {}
+    }
+  };
+}
+async function pullInboxes(ctx) {
+  const out = { ...part(), slugById: new Map };
+  const { inboxes } = await read(ctx, "inboxes list");
+  const rows = inboxes.filter((i) => i.type === "shared").sort((a, b) => a.id.localeCompare(b.id));
+  const got = await pooled(rows, async (row) => {
+    if (row.role === null)
+      return null;
+    const inbox = await read(ctx, "inboxes get", { inboxId: row.id });
+    const flow = inbox.webChat ? await read(ctx, "chat-flow get", { inboxId: row.id, part: "source" }) : null;
+    return { inbox, flow };
+  });
+  rows.forEach((row, i) => {
+    const one = got[i];
+    if (!one) {
+      out.observed.add("Inboxes not pulled", `${row.name}: you are not on this inbox, so its settings are not readable`);
+      return;
+    }
+    const { inbox, flow } = one;
+    out.slugById.set(row.id, inbox.slug);
+    const dir = `inboxes/${inbox.slug}`;
+    if (flow?.published)
+      out.files.set(`${dir}/quick-paths.ts`, flow.published.source);
+    if (flow && flow.revision > 0 && flow.source !== flow.published?.source) {
+      out.observed.add("Quick paths with unpublished changes (the file holds the published version)", `${dir}/quick-paths.ts: the draft at revision ${flow.revision} is not published`);
+    }
+    const { volty, webChat, routing } = inbox;
+    const { agentId: _agentId, agentName, ...seat } = volty ?? { agentId: "", agentName: "" };
+    const { handoffWhatsappInstanceId: _wa, handoffEmailInstanceId: _email, ...chat } = webChat?.settings ?? {};
+    out.files.set(`${dir}/inbox.ts`, tsFile([
+      `The ${inbox.name} inbox: hours, reply targets, hand-off, priority guide, routing, Volty's reply mode and its web chat.`,
+      "Written by volty pull from the live inbox. Who works the inbox, team members and channels stay in the app."
+    ], {
+      name: inbox.name,
+      icon: inbox.icon,
+      autoEnrollOrgMembers: inbox.autoEnrollOrgMembers,
+      businessHours: inbox.businessHours,
+      idleClose: inbox.idleClose,
+      firstResponseMinutes: inbox.firstResponseMinutes,
+      handoff: inbox.handoff,
+      priority: inbox.priority,
+      routing: { ...routing, rules: routing.rules.map(ruleOut) },
+      volty: volty ? { agent: agentName, ...seat } : null,
+      webChat: webChat ? {
+        ...chat,
+        handoffWhatsappNumber: webChat.handoffAddresses.whatsapp,
+        handoffEmailAddress: webChat.handoffAddresses.email
+      } : null,
+      quickPaths: flow ? { enabled: flow.enabled } : undefined
+    }));
+  });
+  return out;
+}
+async function pullInstructions(ctx, inboxes) {
+  const out = part();
+  const [got, { slugById }] = await Promise.all([read(ctx, "instructions get"), inboxes]);
+  if (got.org.text)
+    out.files.set("instructions/org.md", got.org.text);
+  if (got.team.text)
+    out.files.set("instructions/team.md", got.team.text);
+  for (const row of got.inboxes) {
+    const slug = slugById.get(row.inboxId);
+    if (slug && row.text)
+      out.files.set(`inboxes/${slug}/instructions.md`, row.text);
+  }
+  return out;
+}
+async function pullSources(ctx) {
+  const { sources } = await read(ctx, "sources list");
+  const out = { ...part(), sources };
+  const rows = [...sources].sort((a, b) => a.id.localeCompare(b.id));
+  const got = await pooled(rows, (row) => call(ctx, "sources get", { source: row.id, export: true }));
+  const taken = new Set;
+  rows.forEach((row, i) => {
+    const one = got[i];
+    if (!one || "refused" in one) {
+      out.observed.add("Sources with no file yet (website, API and sync sources)", `${row.name} (${row.kind})`);
+      return;
+    }
+    const base = slugBase(row.name);
+    let slug = base;
+    for (let n = 2;taken.has(slug); n++)
+      slug = `${base}-${n}`;
+    taken.add(slug);
+    const { id: _id, scope, automation, ...rest } = one.value.file;
+    out.files.set(`sources/${slug}.ts`, tsFile([
+      `The ${row.name} source: its settings, the names of its secrets (never a value), lanes, scope and tool modes.`,
+      "Written by volty pull. Secret values, sign-ins and which tools an admin approved stay in the app."
+    ], {
+      ...rest,
+      scope: { mode: scope.mode, inboxes: scope.inboxes.map((i) => i.slug), privateInboxes: scope.privateInboxes },
+      automation: automation?.slug ?? null
+    }));
+  });
+  return out;
+}
+var notDeployed = (row) => `${row.slug}: ${row.pendingApproval ? "its first version waits for approval" : "no version is running"}`;
+async function pullAutomations(ctx) {
+  const out = part();
+  const { automations } = await read(ctx, "automations list");
+  const got = await pooled(automations, async (row) => {
+    if (!row.deployed)
+      return null;
+    const first = await read(ctx, "automations get", { id: row.id });
+    if (first.sourceLabel !== "pending" || !first.active?.version)
+      return { got: first, waiting: false };
+    return {
+      got: await read(ctx, "automations get", { id: row.id, version: first.active.version }),
+      waiting: true
+    };
+  });
+  automations.forEach((row, i) => {
+    const one = got[i];
+    if (!one) {
+      out.observed.add("Automations not deployed", notDeployed(row));
+      return;
+    }
+    if (one.waiting)
+      out.observed.add(WAITING_HEADING, `automations/${row.slug}.ts`);
+    if (one.got.source !== null)
+      out.files.set(`automations/${row.slug}.ts`, one.got.source);
+  });
+  return out;
+}
+async function pullPages(ctx) {
+  const out = part();
+  const { miniApps } = await read(ctx, "mini-apps list");
+  const got = await pooled(miniApps, async (row) => {
+    if (!row.deployed)
+      return null;
+    const first = await read(ctx, "mini-apps get", { id: row.id });
+    if (!first.pending)
+      return { got: first, waiting: false };
+    const active = first.deploys.find((d) => d.status === "active");
+    return {
+      got: active?.version ? await read(ctx, "mini-apps get", { id: row.id, version: active.version }) : first,
+      waiting: true
+    };
+  });
+  miniApps.forEach((row, i) => {
+    const one = got[i];
+    if (!one) {
+      out.observed.add("Pages not deployed", notDeployed(row));
+      return;
+    }
+    if (one.waiting)
+      out.observed.add(WAITING_HEADING, `pages/${row.slug}/`);
+    if (one.got.entrySource !== null)
+      out.files.set(`pages/${row.slug}/entry.tsx`, one.got.entrySource);
+    if (one.got.bffSource !== null)
+      out.files.set(`pages/${row.slug}/bff.ts`, one.got.bffSource);
+  });
+  return out;
+}
+var DRIVE_FOLDER_CAP = 100;
+async function walkDrive(ctx) {
+  const files = [];
+  let queue = ["/"];
+  let walked = 0;
+  while (queue.length > 0 && walked < DRIVE_FOLDER_CAP) {
+    const level = queue.slice(0, DRIVE_FOLDER_CAP - walked);
+    walked += level.length;
+    const listed = await pooled(level, (path) => read(ctx, "drive list-folder", { scope: "organization", path }));
+    const children = [];
+    for (const { entries } of listed) {
+      for (const entry of entries) {
+        if (entry.kind === "folder")
+          children.push(entry.path);
+        else
+          files.push(entry.path);
+      }
+    }
+    queue = [...queue.slice(level.length), ...children];
+  }
+  return { files, unread: queue.length };
+}
+async function observeData(ctx) {
+  const out = part();
+  const [learned, drive, { tables }] = await Promise.all([
+    read(ctx, "learned list"),
+    walkDrive(ctx),
+    read(ctx, "tables list")
+  ]);
+  for (const rule of learned.rules)
+    out.observed.add("Learned rules (Volty writes them; a push never touches them)", rule.text);
+  for (const path of drive.files)
+    out.observed.add(DRIVE_HEADING, path);
+  if (drive.unread > 0)
+    out.observed.add(DRIVE_HEADING, `${drive.unread} more folders not listed`);
+  for (const table of tables)
+    out.observed.add("Tables (their rows stay in the workspace)", table.name);
+  return out;
+}
+function agentsMd(workspaceId, sources) {
+  const systems = [...sources].sort((a, b) => a.name.localeCompare(b.name)).map((s) => `- ${s.name} (${s.kind})`);
+  return `# Volty project
+
+This folder is one Volty workspace's setup as files, written by \`volty pull\` from the live workspace \`${workspaceId}\`.
+
+- \`instructions/org.md\`: the instructions Volty reads everywhere. \`instructions/team.md\`: how Volty works with staff, read only when it talks to staff.
+- \`inboxes/<slug>/inbox.ts\`: one inbox's settings. Beside it, \`instructions.md\` is that inbox's own instructions and \`quick-paths.ts\` its web chat's quick paths.
+- \`sources/<slug>.ts\`: a connected source's settings, the names of its secrets (never a value), lanes and tool modes.
+- \`automations/<slug>.ts\`: an automation's running source.
+- \`pages/<slug>/\`: a page's \`entry.tsx\` and \`bff.ts\`.
+- \`volty.config.ts\`: the workspace this project deploys to.
+- \`.volty/targets\`: the version this folder was pulled from. \`.volty/observed\`: what the workspace holds outside the project (Learned rules, Drive files, tables, sources with no file yet), read-only.
+
+Systems connected to this workspace:
+${systems.length > 0 ? systems.join(`
+`) : "- none"}
+
+Pushing the folder back is not built yet. Run \`volty pull\` again to bring the folder up to date, and \`volty docs\` for every operation.
+`;
+}
+function configFile(target, workspaceId) {
+  return tsFile([
+    "Where this project deploys: each target names one workspace by id.",
+    "Written by volty pull; the version each target was pulled from is in .volty/targets."
+  ], { targets: { [target]: { workspace: workspaceId } } });
+}
+function readTargets(dir) {
+  const path = join3(dir, ".volty", "targets");
+  if (!existsSync4(path))
+    return null;
+  return JSON.parse(readFileSync4(path, "utf8"));
+}
+async function pull(ctx, opts) {
+  const { dir, workspaceId, target } = opts;
+  const targets = readTargets(dir);
+  if (targets) {
+    const other = Object.entries(targets).find(([, t]) => t.workspace !== workspaceId);
+    if (other) {
+      throw new Error(`${dir} holds the project of workspace ${other[1].workspace}: pull ${workspaceId} into its own folder.`);
+    }
+  } else if (existsSync4(dir) && readdirSync(dir).some((name) => !name.startsWith("."))) {
+    throw new Error(`${dir} is not empty and no volty pull wrote it: pull into an empty folder.`);
+  }
+  const inboxes = pullInboxes(ctx);
+  const parts = await Promise.all([
+    inboxes,
+    pullInstructions(ctx, inboxes),
+    pullSources(ctx),
+    pullAutomations(ctx),
+    pullPages(ctx),
+    observeData(ctx)
+  ]);
+  const files = new Map;
+  const observed = new Observed;
+  for (const one of parts) {
+    for (const [rel, text] of one.files)
+      files.set(rel, text);
+    for (const [heading, lines] of one.observed.sections)
+      for (const line of lines)
+        observed.add(heading, line);
+  }
+  files.set("AGENTS.md", agentsMd(workspaceId, parts[2].sources));
+  files.set("volty.config.ts", configFile(target, workspaceId));
+  const base = targets?.[target]?.version;
+  const { baseFiles, ...recorded } = await read(ctx, "project record-pull", {
+    workspace: workspaceId,
+    files: Object.fromEntries(files),
+    ...base ? { base } : {}
+  });
+  const written = [];
+  const deleted = [];
+  const kept = [];
+  const edited = (rel, local) => base !== undefined && sha256(local) !== baseFiles[rel];
+  for (const [rel, text] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+    const path = join3(dir, rel);
+    const local = existsSync4(path) ? readFileSync4(path, "utf8") : null;
+    if (local === text)
+      continue;
+    if (local !== null && edited(rel, local)) {
+      kept.push({ path: rel, workspace: sha256(text) === baseFiles[rel] ? "unchanged" : "changed" });
+      continue;
+    }
+    mkdirSync3(dirname2(path), { recursive: true });
+    writeFileSync4(path, text);
+    written.push(rel);
+  }
+  for (const rel of Object.keys(baseFiles).sort()) {
+    const path = join3(dir, rel);
+    if (files.has(rel) || !existsSync4(path))
+      continue;
+    if (edited(rel, readFileSync4(path, "utf8"))) {
+      kept.push({ path: rel, workspace: "removed" });
+    } else {
+      unlinkSync(path);
+      deleted.push(rel);
+    }
+  }
+  mkdirSync3(join3(dir, ".volty"), { recursive: true });
+  const nextTargets = {
+    ...targets,
+    [target]: { workspace: recorded.workspaceId, version: recorded.versionId }
+  };
+  writeFileSync4(join3(dir, ".volty", "targets"), `${JSON.stringify(nextTargets, null, 2)}
+`);
+  const observedPath = join3(dir, ".volty", "observed");
+  if (existsSync4(observedPath))
+    chmodSync(observedPath, 420);
+  writeFileSync4(observedPath, observed.render());
+  chmodSync(observedPath, 292);
+  return { ...recorded, written, deleted, kept };
+}
+
 // src/update.ts
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } 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");
+import { dirname as dirname3, join as join4 } from "node:path";
+var CACHE_PATH = join4(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(readFileSync4(join3(import.meta.dirname, "..", "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync5(join4(import.meta.dirname, "..", "package.json"), "utf8"));
     return pkg.version ?? null;
   } catch {
     return null;
@@ -673,15 +1079,15 @@ function cmpVersion(a, b) {
 }
 function readCache() {
   try {
-    return JSON.parse(readFileSync4(CACHE_PATH, "utf8"));
+    return JSON.parse(readFileSync5(CACHE_PATH, "utf8"));
   } catch {
     return null;
   }
 }
 function writeCache(cache) {
   try {
-    mkdirSync3(dirname2(CACHE_PATH), { recursive: true });
-    writeFileSync4(CACHE_PATH, `${JSON.stringify(cache)}
+    mkdirSync4(dirname3(CACHE_PATH), { recursive: true });
+    writeFileSync5(CACHE_PATH, `${JSON.stringify(cache)}
 `);
   } catch {}
 }
@@ -903,6 +1309,41 @@ async function handleChanges(rest, ctx) {
   process.stdout.write(`${dec.value === "approve" ? "Approved" : "Rejected"} proposal ${res.body.proposal?.id ?? pid.value} → ${res.body.proposal?.status ?? "decided"}
 `);
 }
+var KEPT_NOTE = {
+  unchanged: "",
+  changed: ", and the workspace changed it too: delete it and pull again for the workspace copy",
+  removed: ", and the workspace no longer has it"
+};
+async function handlePull(rest, ctx, env) {
+  const [dir = ".", ...extra] = rest;
+  if (extra.length > 0 || dir.startsWith("--"))
+    fail("usage: volty pull [dir] [--workspace <id>]");
+  let workspaceId = ctx.organizationId;
+  if (!workspaceId) {
+    const res = await whoami(ctx);
+    if ("error" in res)
+      fail(res.error);
+    workspaceId = res.who.organizationId;
+  }
+  if (!workspaceId)
+    fail("this key names no workspace: run `volty auth login`");
+  const out = await pull(ctx, { dir, workspaceId, target: env });
+  if (out.unchanged && out.written.length + out.deleted.length + out.kept.length === 0) {
+    process.stdout.write(`${dir} is up to date with version ${out.versionId} of workspace ${out.workspaceId}.
+`);
+    return;
+  }
+  const lines = [
+    `Pulled workspace ${out.workspaceId} into ${dir}: version ${out.versionId}${out.unchanged ? " (unchanged)" : ""}.`,
+    ...out.written.map((f) => `  wrote ${f}`),
+    ...out.deleted.map((f) => `  deleted ${f}, which the workspace no longer has`),
+    ...out.kept.map((f) => `  kept ${f.path}: edited here${KEPT_NOTE[f.workspace]}`),
+    "What the project does not hold is listed in .volty/observed."
+  ];
+  process.stdout.write(`${lines.join(`
+`)}
+`);
+}
 async function handleDocs(config, env) {
   const ctx = ensureContext(config, env);
   if (!ctx.baseUrl)
@@ -916,16 +1357,16 @@ 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")
+    join5(import.meta.dirname, "..", "skill", "volty-cli-ops", "SKILL.md"),
+    join5(import.meta.dirname, "..", "..", ".claude", "skills", "volty-cli-ops", "SKILL.md")
   ];
-  const source = candidates.find((p) => existsSync4(p));
+  const source = candidates.find((p) => existsSync5(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 });
-  writeFileSync5(join4(destDir, "SKILL.md"), readFileSync5(source, "utf8"));
-  process.stdout.write(`Installed the volty-cli-ops skill → ${join4(destDir, "SKILL.md")}
+  const destDir = join5(homedir3(), ".claude", "skills", "volty-cli-ops");
+  mkdirSync5(destDir, { recursive: true });
+  writeFileSync6(join5(destDir, "SKILL.md"), readFileSync6(source, "utf8"));
+  process.stdout.write(`Installed the volty-cli-ops skill → ${join5(destDir, "SKILL.md")}
 `);
 }
 async function main() {
@@ -936,6 +1377,8 @@ async function main() {
   argv = orgExtract.rest;
   const cacheFlag = takeBool(argv, "--no-cache");
   argv = cacheFlag.rest;
+  const workspaceExtract = argv[0] === "pull" ? takeValue(argv, "--workspace") : { value: undefined, rest: argv };
+  argv = workspaceExtract.rest;
   const config = loadConfig();
   const env = activeEnv(config, envExtract.value ?? (process.env.VOLTY_ENV || undefined));
   const peek = config.contexts[env];
@@ -943,7 +1386,7 @@ async function main() {
   const target = resolveTargetOrg({
     env,
     baseUrl: peek?.baseUrl,
-    override: orgExtract.value ?? (process.env.VOLTY_ORG || undefined),
+    override: workspaceExtract.value ?? orgExtract.value ?? (process.env.VOLTY_ORG || undefined),
     sticky: peek?.activeOrg,
     command: argv
   });
@@ -984,10 +1427,14 @@ async function main() {
     process.stderr.write(`→ ${env} · ${res.who.organizationName} (${res.who.organizationId}) · ${res.who.role}
 `);
   }
+  if (cmd === "pull")
+    return handlePull(rest, ctx, env);
   if (cmd === "changes" && rest[0] === "decide")
     return handleChanges(rest, ctx);
   if (cmd === "keys")
     argv = keysArgv(argv);
+  if (cmd === "changes" && (rest[0] === undefined || rest[0].startsWith("--")))
+    argv = ["changes", "list-mine", ...rest];
   const catalog = await fetchCatalog(ctx, env, !cacheFlag.present);
   if (!cmd || cmd === "help" || cmd === "--help") {
     process.stdout.write(`${renderCatalog(catalog.ops, rest.length ? rest.join(" ") : undefined)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltade/volty",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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",