@arbidocs/cli 0.3.62 → 0.3.64

package/dist/index.js

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
 'use strict';
 
+var prompts = require('@inquirer/prompts');
 var commander = require('commander');
 var fs5 = require('fs');
 var path5 = require('path');
-var os = require('os');
+var os2 = require('os');
 var chalk2 = require('chalk');
 var sdk = require('@arbidocs/sdk');
-var prompts = require('@inquirer/prompts');
 var child_process = require('child_process');
 var client = require('@arbidocs/client');
 var url = require('url');
+var crypto$1 = require('crypto');
 var module$1 = require('module');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -18,11 +19,73 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var fs5__default = /*#__PURE__*/_interopDefault(fs5);
 var path5__default = /*#__PURE__*/_interopDefault(path5);
-var os__default = /*#__PURE__*/_interopDefault(os);
+var os2__default = /*#__PURE__*/_interopDefault(os2);
 var chalk2__default = /*#__PURE__*/_interopDefault(chalk2);
 
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/prompts.ts
+var prompts_exports = {};
+__export(prompts_exports, {
+  checkbox: () => prompts.checkbox,
+  confirm: () => prompts.confirm,
+  input: () => prompts.input,
+  password: () => prompts.password,
+  promptCheckbox: () => promptCheckbox,
+  promptConfirm: () => promptConfirm,
+  promptInput: () => promptInput,
+  promptPassword: () => promptPassword,
+  promptSearch: () => promptSearch,
+  promptSelect: () => promptSelect,
+  search: () => prompts.search,
+  select: () => prompts.select
+});
+async function promptSelect(message, choices) {
+  return prompts.select({ message, choices });
+}
+async function promptCheckbox(message, choices) {
+  return prompts.checkbox({ message, choices });
+}
+async function promptSearch(message, choices) {
+  return prompts.search({
+    message,
+    source: async (term) => {
+      if (!term) return choices;
+      const lower = term.toLowerCase();
+      return choices.filter((c) => c.name.toLowerCase().includes(lower));
+    }
+  });
+}
+async function promptInput(message, required = true) {
+  return prompts.input({
+    message,
+    validate: required ? (v) => v.trim() ? true : "Required" : void 0
+  });
+}
+async function promptPassword(message) {
+  return prompts.password({
+    message,
+    mask: "*",
+    validate: (v) => v ? true : "Required"
+  });
+}
+async function promptConfirm(message, defaultValue = true) {
+  return prompts.confirm({ message, default: defaultValue });
+}
+var init_prompts = __esm({
+  "src/prompts.ts"() {
+  }
+});
 function getCacheFile() {
-  const configDir = process.env.ARBI_CONFIG_DIR ?? path5__default.default.join(os__default.default.homedir(), ".arbi");
+  const configDir = process.env.ARBI_CONFIG_DIR ?? path5__default.default.join(os2__default.default.homedir(), ".arbi");
   return path5__default.default.join(configDir, "completions.json");
 }
 function ensureDir(filePath) {
@@ -40,6 +103,16 @@ function getCachedWorkspaceIds() {
     return [];
   }
 }
+function getCachedWorkspaceName(id) {
+  try {
+    const content = fs5__default.default.readFileSync(getCacheFile(), "utf-8");
+    const cache = JSON.parse(content);
+    const hit = cache.workspaces.find((w) => w.id === id);
+    return hit?.name?.trim() ? hit.name : null;
+  } catch {
+    return null;
+  }
+}
 function updateCompletionCache(workspaces3) {
   const cache = {
     workspaces: workspaces3.filter((w) => w.external_id).map((w) => ({ id: w.external_id, name: w.name ?? "" })),
@@ -194,8 +267,8 @@ var ALIAS_LINE = 'alias A="arbi ask"';
 var ALIAS_MARKER = "# arbi-cli alias";
 function getShellRcPath() {
   const shell = process.env.SHELL || "";
-  if (shell.includes("zsh")) return path5.join(os.homedir(), ".zshrc");
-  return path5.join(os.homedir(), ".bashrc");
+  if (shell.includes("zsh")) return path5.join(os2.homedir(), ".zshrc");
+  return path5.join(os2.homedir(), ".bashrc");
 }
 function isAliasInstalled(rcPath) {
   if (!fs5.existsSync(rcPath)) return false;
@@ -203,7 +276,7 @@ function isAliasInstalled(rcPath) {
   return content.includes(ALIAS_LINE) || content.includes(ALIAS_MARKER);
 }
 function registerConfigCommand(program2) {
-  const config = program2.command("config").description("Manage CLI configuration");
+  const config = program2.command("config").description("CLI configuration: set-url, show, notifications, verbose, watch, alias");
   config.command("set-url <url>").description("Set the ARBI server URL").action((url) => {
     try {
       const parsed = new URL(url);
@@ -219,7 +292,17 @@ function registerConfigCommand(program2) {
   config.command("show").description("Show current configuration").option("--json", "Output as JSON").action((opts) => {
     const cfg = getConfig();
     if (opts.json) {
-      console.log(JSON.stringify(cfg ?? {}, null, 2));
+      const projection = cfg ? {
+        baseUrl: cfg.baseUrl ?? null,
+        deploymentDomain: cfg.deploymentDomain ?? null,
+        autoUpdate: cfg.autoUpdate ?? false,
+        verbose: cfg.verbose !== false,
+        watch: cfg.watch !== false,
+        notifications: cfg.notifications !== false,
+        orchestrator: cfg.orchestrator ?? null,
+        selectedWorkspaceId: cfg.selectedWorkspaceId ?? null
+      } : {};
+      console.log(JSON.stringify(projection, null, 2));
       return;
     }
     if (!cfg) {
@@ -232,6 +315,7 @@ function registerConfigCommand(program2) {
     label("Verbose:", cfg.verbose !== false ? "on" : "off");
     label("Watch:", cfg.watch !== false ? "on" : "off");
     label("Notifications:", cfg.notifications !== false ? "on" : "off");
+    if (cfg.orchestrator) label("Orchestrator:", cfg.orchestrator);
     if (cfg.selectedWorkspaceId) {
       label("Workspace:", cfg.selectedWorkspaceId);
     }
@@ -275,7 +359,7 @@ function registerConfigCommand(program2) {
     updateConfig({ watch: toggle === "on" });
     success(`Watch: ${toggle}`);
   });
-  config.command("alias").description('Set up shell alias A for "arbi ask"').action(() => {
+  config.command("alias").description('Append `alias A="arbi ask"` to your shell rc file (idempotent, reversible)').action(() => {
     const rcPath = getShellRcPath();
     if (isAliasInstalled(rcPath)) {
       success(`Alias already set up in ${rcPath}`);
@@ -3255,7 +3339,7 @@ var waitForOthersClosedDelete = (databases, name, openDatabases, cb) => {
 };
 var deleteDatabase = (databases, connectionQueues, name, request, cb) => {
   const deleteDBTask = () => {
-    return new Promise((resolve3) => {
+    return new Promise((resolve5) => {
       const db = databases.get(name);
       const oldVersion = db !== void 0 ? db.version : 0;
       const onComplete = (err) => {
@@ -3266,7 +3350,7 @@ var deleteDatabase = (databases, connectionQueues, name, request, cb) => {
             cb(null, oldVersion);
           }
         } finally {
-          resolve3();
+          resolve5();
         }
       };
       try {
@@ -3414,7 +3498,7 @@ var runVersionchangeTransaction = (connection, version, request, cb) => {
 };
 var openDatabase = (databases, connectionQueues, name, version, request, cb) => {
   const openDBTask = () => {
-    return new Promise((resolve3) => {
+    return new Promise((resolve5) => {
       const onComplete = (err) => {
         try {
           if (err) {
@@ -3423,7 +3507,7 @@ var openDatabase = (databases, connectionQueues, name, version, request, cb) =>
             cb(null, connection);
           }
         } finally {
-          resolve3();
+          resolve5();
         }
       };
       let db = databases.get(name);
@@ -3572,39 +3656,8 @@ Object.defineProperties(globalVar, {
   IDBTransaction: createPropertyDescriptor(FDBTransaction_default),
   IDBVersionChangeEvent: createPropertyDescriptor(FDBVersionChangeEvent_default)
 });
-async function promptSelect(message, choices) {
-  return prompts.select({ message, choices });
-}
-async function promptCheckbox(message, choices) {
-  return prompts.checkbox({ message, choices });
-}
-async function promptSearch(message, choices) {
-  return prompts.search({
-    message,
-    source: async (term) => {
-      if (!term) return choices;
-      const lower = term.toLowerCase();
-      return choices.filter((c) => c.name.toLowerCase().includes(lower));
-    }
-  });
-}
-async function promptInput(message, required = true) {
-  return prompts.input({
-    message,
-    validate: required ? (v) => v.trim() ? true : "Required" : void 0
-  });
-}
-async function promptPassword(message) {
-  return prompts.password({
-    message,
-    mask: "*",
-    validate: (v) => v ? true : "Required"
-  });
-}
-async function promptConfirm(message, defaultValue = true) {
-  return prompts.confirm({ message, default: defaultValue });
-}
-var CACHE_FILE = path5__default.default.join(os__default.default.homedir(), ".arbi", "version-cache.json");
+init_prompts();
+var CACHE_FILE = path5__default.default.join(os2__default.default.homedir(), ".arbi", "version-cache.json");
 var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 function readCache() {
   try {
@@ -3641,7 +3694,7 @@ function getLatestVersion(skipCache = false) {
   }
 }
 function getCurrentVersion() {
-  return "0.3.62";
+  return "0.3.64";
 }
 function readChangelog(fromVersion, toVersion) {
   try {
@@ -3694,38 +3747,61 @@ function showChangelog(fromVersion, toVersion) {
 async function checkForUpdates(autoUpdate) {
   try {
     const latest = getLatestVersion();
-    if (!latest || latest === "0.3.62") return;
+    if (!latest || latest === "0.3.64") return;
     if (autoUpdate) {
       warn(`
-Your arbi version is out of date (${"0.3.62"} \u2192 ${latest}). Updating...`);
+Your arbi version is out of date (${"0.3.64"} \u2192 ${latest}). Updating...`);
       child_process.execSync("npm install -g @arbidocs/cli@latest", { stdio: "inherit" });
-      showChangelog("0.3.62", latest);
+      showChangelog("0.3.64", latest);
       console.log(`Updated to ${latest}.`);
     } else {
       warn(
         `
-Your arbi version is out of date (${"0.3.62"} \u2192 ${latest}).
+Your arbi version is out of date (${"0.3.64"} \u2192 ${latest}).
 Run "arbi update" to upgrade, or "arbi update auto" to always stay up to date.`
       );
     }
   } catch {
   }
 }
+var NAG_FILE = path5__default.default.join(os2__default.default.homedir(), ".arbi", "last-update-hint.json");
+var NAG_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+function shouldShowNag(latest) {
+  if (process.env.ARBI_JSON === "1") return false;
+  if (process.argv.includes("--json")) return false;
+  try {
+    const data = JSON.parse(fs5__default.default.readFileSync(NAG_FILE, "utf8"));
+    if (data.latest === latest && typeof data.shownAt === "number" && Date.now() - data.shownAt < NAG_INTERVAL_MS) {
+      return false;
+    }
+  } catch {
+  }
+  return true;
+}
+function markNagShown(latest) {
+  try {
+    const dir = path5__default.default.dirname(NAG_FILE);
+    if (!fs5__default.default.existsSync(dir)) fs5__default.default.mkdirSync(dir, { recursive: true, mode: 448 });
+    fs5__default.default.writeFileSync(NAG_FILE, JSON.stringify({ latest, shownAt: Date.now() }) + "\n");
+  } catch {
+  }
+}
 function hintUpdateOnError() {
   try {
     const cached = readCache();
-    if (cached && cached.latest !== "0.3.62") {
-      warn(
-        `Your arbi version is out of date (${"0.3.62"} \u2192 ${cached.latest}). Run "arbi update".`
-      );
-    }
+    if (!cached || cached.latest === "0.3.64") return;
+    if (!shouldShowNag(cached.latest)) return;
+    warn(
+      `Your arbi version is out of date (${"0.3.64"} \u2192 ${cached.latest}). Run "arbi update".`
+    );
+    markNagShown(cached.latest);
   } catch {
   }
 }
 var MAX_TASKS = 50;
 var MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
 function getTasksFile() {
-  const configDir = process.env.ARBI_CONFIG_DIR ?? path5__default.default.join(os__default.default.homedir(), ".arbi");
+  const configDir = process.env.ARBI_CONFIG_DIR ?? path5__default.default.join(os2__default.default.homedir(), ".arbi");
   return path5__default.default.join(configDir, "tasks.json");
 }
 function ensureDir2(filePath) {
@@ -3858,14 +3934,46 @@ function formatCliError(err) {
   if (err instanceof sdk.ArbiApiError && err.apiError && typeof err.apiError === "object") {
     const base = err.message;
     const apiErr = err.apiError;
-    const detail = apiErr.detail ?? apiErr.message ?? apiErr.error;
-    if (typeof detail === "string" && detail && !base.includes(detail)) {
+    const detail = stringifyApiDetail(apiErr.detail ?? apiErr.message ?? apiErr.error ?? apiErr);
+    if (detail && !base.includes(detail)) {
       return `${base} \u2014 ${detail}`;
     }
     return base;
   }
   return sdk.getErrorMessage(err);
 }
+function stringifyApiDetail(value) {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    const parts = value.map((v) => {
+      if (typeof v === "string") return v;
+      if (v && typeof v === "object") {
+        const rec = v;
+        const loc = Array.isArray(rec.loc) ? rec.loc.join(".") : void 0;
+        const msg = typeof rec.msg === "string" ? rec.msg : void 0;
+        if (loc && msg) return `${loc}: ${msg}`;
+        return stringifyApiDetail(v);
+      }
+      return "";
+    }).filter(Boolean);
+    return parts.join("; ");
+  }
+  if (typeof value === "object") {
+    const rec = value;
+    if (typeof rec.detail === "string") return rec.detail;
+    if (Array.isArray(rec.detail)) return stringifyApiDetail(rec.detail);
+    if (typeof rec.message === "string") return rec.message;
+    if (typeof rec.error === "string") return rec.error;
+    try {
+      const s = JSON.stringify(value);
+      return s === "{}" ? "" : s;
+    } catch {
+      return "";
+    }
+  }
+  return String(value);
+}
 function runAction(fn) {
   return async () => {
     try {
@@ -3918,13 +4026,19 @@ async function resolveDmCrypto() {
   const crypto2 = sdk.dm.createDmCryptoContext(arbi, loginResult.signingPrivateKey, userExtId);
   return { ...authCtx, crypto: crypto2 };
 }
+function truncate(value, width) {
+  if (width <= 0) return "";
+  if (value.length <= width) return value;
+  if (width === 1) return "\u2026";
+  return value.slice(0, width - 1) + "\u2026";
+}
 function printTable(columns, rows) {
   console.log(chalk2__default.default.bold(columns.map((c) => c.header.padEnd(c.width)).join("")));
   for (const row of rows) {
     console.log(
       columns.map((c) => {
         const val = c.value(row) ?? "";
-        return val.slice(0, c.width - 2).padEnd(c.width);
+        return truncate(val, c.width - 1).padEnd(c.width);
       }).join("")
     );
   }
@@ -3937,6 +4051,91 @@ function parseJsonArg(input2, example) {
     process.exit(1);
   }
 }
+function isInteractive() {
+  return Boolean(process.stdin.isTTY);
+}
+function requireInteractive(hint) {
+  if (isInteractive()) return;
+  error(`Cannot prompt: not running in a terminal. ${hint}`);
+  process.exit(1);
+}
+function printJson(value) {
+  process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+function nearestMatch(input2, candidates) {
+  if (!input2 || candidates.length === 0) return null;
+  const lower = input2.toLowerCase();
+  const prefix = candidates.find((c) => c.startsWith(lower));
+  if (prefix) return prefix;
+  let best = null;
+  for (const c of candidates) {
+    let score = 0;
+    for (let i = 0; i < Math.min(c.length, lower.length); i++) {
+      if (c[i] === lower[i]) score++;
+      else break;
+    }
+    if (!best || score > best.score) best = { name: c, score };
+  }
+  return best && best.score >= 1 ? best.name : null;
+}
+function suggestSubcommandAndExit(parentName, attempted, candidates) {
+  const suggestion = nearestMatch(attempted, candidates);
+  const hint = suggestion ? ` (Did you mean ${suggestion}?)` : "";
+  error(
+    `unknown subcommand '${attempted}' for '${parentName}'${hint}
+Available: ${candidates.join(", ")}`
+  );
+  process.exit(1);
+}
+function emitListOrTable(data, opts, emptyMessage) {
+  if (opts.json) {
+    printJson(data);
+    return false;
+  }
+  if (data.length === 0) {
+    process.stderr.write(`${emptyMessage}
+`);
+    return false;
+  }
+  return true;
+}
+function resolveByIdOrName(list, selector) {
+  const byId = list.find((w) => w.external_id === selector);
+  if (byId) return { ok: true, item: byId, id: byId.external_id };
+  const lower = selector.toLowerCase();
+  const byName = list.filter((w) => (w.name ?? "").toLowerCase() === lower);
+  if (byName.length === 1) return { ok: true, item: byName[0], id: byName[0].external_id };
+  if (byName.length > 1) return { ok: false, reason: "ambiguous", matches: byName };
+  return { ok: false, reason: "not-found", matches: [] };
+}
+function failResolveAndExit(thing, selector, res) {
+  if (res.reason === "ambiguous") {
+    error(
+      `Ambiguous ${thing} "${selector}" \u2014 matches ${res.matches.map((m) => m.external_id).join(", ")}. Use the ID.`
+    );
+  } else {
+    error(`${thing} "${selector}" not found.`);
+  }
+  process.exit(3);
+}
+function dryRun(verb, targets) {
+  const list = Array.isArray(targets) ? targets : [targets];
+  process.stdout.write(`[dry-run] Would ${verb}:
+`);
+  for (const t of list) process.stdout.write(`  - ${t}
+`);
+  process.stdout.write("[dry-run] (no changes made; drop --dry-run to execute)\n");
+}
+async function pickFromList(items, toChoice, options) {
+  if (items.length === 0) {
+    process.stderr.write(`${options.emptyMessage}
+`);
+    process.exit(0);
+  }
+  requireInteractive(options.nonTtyHint);
+  const { promptSelect: promptSelect2 } = await Promise.resolve().then(() => (init_prompts(), prompts_exports));
+  return promptSelect2(options.message, items.map(toChoice));
+}
 var AGENT_BACKENDS = ["claude", "openclaw"];
 var AGENT_MIN_VERSIONS = {
   claude: {
@@ -3995,7 +4194,7 @@ function installSkill(backend) {
     return;
   }
   if (backend === "claude") {
-    const dir = path5.join(os.homedir(), ".claude", "commands", "arbi");
+    const dir = path5.join(os2.homedir(), ".claude", "commands", "arbi");
     const target = path5.join(dir, "SKILL.md");
     try {
       fs5.mkdirSync(dir, { recursive: true });
@@ -4006,7 +4205,7 @@ function installSkill(backend) {
     } catch {
     }
   } else if (backend === "openclaw") {
-    const workspace = path5.join(os.homedir(), ".arbi", "openclaw-workspace");
+    const workspace = path5.join(os2.homedir(), ".arbi", "openclaw-workspace");
     const bootstrap = path5.join(workspace, "BOOTSTRAP.md");
     try {
       fs5.mkdirSync(workspace, { recursive: true });
@@ -4091,7 +4290,9 @@ async function startListening(agentName, config) {
   });
 }
 function registerListenCommand(program2) {
-  program2.command("listen").description("Start DM listener (connect agent backend to ARBI messaging)").option("--agent <name>", `Agent backend: ${AGENT_BACKENDS.join(", ")}`).action(
+  program2.command("listen").description(
+    "Start DM listener (foreground; runs until Ctrl-C \u2014 use `& disown` or systemd for background)"
+  ).option("--agent <name>", `Agent backend: ${AGENT_BACKENDS.join(", ")}`).action(
     (opts) => (async () => {
       const config = resolveConfig();
       await setupAgent(opts.agent, config);
@@ -4118,7 +4319,8 @@ function registerLoginCommand(program2) {
       }
       const passwordFromFlagOrEnv = opts.password || process.env.ARBI_PASSWORD;
       if (!isTty && !passwordFromFlagOrEnv && !opts.signingKey) {
-        const msg = "Password is required when stdin is not a TTY. Use --password <password> or set ARBI_PASSWORD.";
+        const why = opts.sso ? "\nNote: --sso still requires --password \u2014 the master password is the E2E key seed,\nthe SSO token only proves identity. ARBI has no passwordless mode." : "";
+        const msg = "Password is required when stdin is not a TTY. Use --password <password> or set ARBI_PASSWORD." + why;
         if (opts.json) console.log(JSON.stringify({ ok: false, error: msg }));
         else error(msg);
         process.exit(1);
@@ -4221,6 +4423,7 @@ Open this URL in your browser:
     })()
   );
 }
+init_prompts();
 var CENTRAL_API_URL = "https://central.arbi.work";
 var RegisterHintError = class extends Error {
   constructor(message, kind) {
@@ -4360,6 +4563,17 @@ async function nonInteractiveRegister(config, opts) {
   const password2 = opts.password || process.env.ARBI_PASSWORD;
   const supportApiKey = process.env.SUPPORT_API_KEY;
   if (!email) {
+    if (opts.json) {
+      console.log(
+        JSON.stringify({
+          ok: false,
+          stage: "preflight",
+          error: "Email required",
+          hint: "Use --email <email> or set ARBI_EMAIL"
+        })
+      );
+      process.exit(1);
+    }
     error("Email required. Use --email <email> or set ARBI_EMAIL");
     process.exit(1);
   }
@@ -4368,6 +4582,17 @@ async function nonInteractiveRegister(config, opts) {
     if (!opts.json) console.log(`Using email: ${email}`);
   }
   if (!password2) {
+    if (opts.json) {
+      console.log(
+        JSON.stringify({
+          ok: false,
+          stage: "preflight",
+          error: "Password required",
+          hint: "Use --password <password> or set ARBI_PASSWORD"
+        })
+      );
+      process.exit(1);
+    }
     error("Password required. Use --password <password> or set ARBI_PASSWORD");
     process.exit(1);
   }
@@ -4388,6 +4613,17 @@ async function nonInteractiveRegister(config, opts) {
     verificationCode = opts.verificationCode;
   } else {
     if (!supportApiKey) {
+      if (opts.json) {
+        console.log(
+          JSON.stringify({
+            ok: false,
+            stage: "preflight",
+            error: "Verification code required",
+            hint: "Use --verification-code <code> or set SUPPORT_API_KEY for CI mode"
+          })
+        );
+        process.exit(1);
+      }
       error(
         "Verification code required. Use --verification-code <code> or set SUPPORT_API_KEY for CI mode"
       );
@@ -4532,6 +4768,8 @@ function registerStatusCommand(program2) {
   program2.command("status").description("Show current configuration and login status").option("--json", "Output as JSON for scripting").action((opts) => {
     const config = getConfig();
     const creds = getCredentials();
+    const wsId = config?.selectedWorkspaceId ?? null;
+    const wsName = wsId ? getCachedWorkspaceName(wsId) : null;
     if (opts.json) {
       console.log(
         JSON.stringify(
@@ -4540,7 +4778,8 @@ function registerStatusCommand(program2) {
             server: config?.baseUrl ?? null,
             logged_in: !!creds,
             user: creds?.email ?? null,
-            workspace: config?.selectedWorkspaceId ?? null
+            workspace: wsId,
+            workspace_name: wsName
           },
           null,
           2
@@ -4558,13 +4797,14 @@ function registerStatusCommand(program2) {
     } else {
       label("User:", "(not logged in)");
     }
-    if (config.selectedWorkspaceId) {
-      label("Workspace:", config.selectedWorkspaceId);
+    if (wsId) {
+      label("Workspace:", wsName ? `${wsName} (${wsId})` : wsId);
     } else {
       label("Workspace:", "(none selected)");
     }
   });
 }
+init_prompts();
 function resolveWorkspaceSelector(list, selector) {
   const byId = list.find((w) => w.external_id === selector);
   if (byId) return { ok: true, id: byId.external_id, ws: byId };
@@ -4587,35 +4827,55 @@ function printResolveError(list, selector, res) {
   for (const w of list) error(`  ${w.external_id}  ${w.name}`);
 }
 function registerWorkspacesCommand(program2) {
-  program2.command("workspaces").description("List workspaces").option("--json", "Output as JSON").option("--ids", "Output only workspace IDs (one per line)").action(
+  program2.command("workspaces").description("List workspaces").option("--json", "Output as JSON").option("--ids", "Output only workspace IDs (one per line)").option(
+    "--mine",
+    "Only workspaces where you have a membership role (hide deployment-wide common ones)"
+  ).action(
     (opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
-      const data = await sdk.workspaces.listWorkspaces(arbi);
-      updateCompletionCache(data);
+      const allWorkspaces = await sdk.workspaces.listWorkspaces(arbi);
+      updateCompletionCache(allWorkspaces);
+      const data = opts.mine ? allWorkspaces.filter((w) => w.users?.length > 0) : allWorkspaces;
       if (opts.ids) {
         for (const w of data) console.log(w.external_id);
         return;
       }
       if (opts.json) {
-        const selectedId = getConfig()?.selectedWorkspaceId ?? null;
-        const out = data.map((w) => ({
-          id: w.external_id,
-          name: w.name,
-          docs: w.shared_document_count + w.private_document_count,
-          role: w.users?.[0]?.role ?? null,
-          is_selected: w.external_id === selectedId
-        }));
+        const selectedId2 = getConfig()?.selectedWorkspaceId ?? null;
+        const out = data.map((w) => {
+          const role = w.users?.[0]?.role ?? null;
+          return {
+            id: w.external_id,
+            name: w.name,
+            docs: w.shared_document_count + w.private_document_count,
+            role,
+            is_common: role === null,
+            is_selected: w.external_id === selectedId2
+          };
+        });
         console.log(JSON.stringify(out, null, 2));
         return;
       }
       if (data.length === 0) {
-        console.log("No workspaces found.");
+        process.stderr.write(
+          opts.mine ? "No workspaces you are a member of. (Drop --mine to see deployment-wide ones.)\n" : "No workspaces found.\n"
+        );
         return;
       }
+      const selectedId = getConfig()?.selectedWorkspaceId ?? null;
       printTable(
         [
           { header: "ID", width: 24, value: (r) => r.external_id },
-          { header: "NAME", width: 30, value: (r) => r.name },
+          {
+            header: "NAME",
+            width: 30,
+            // Asterisk-mark the active workspace so a glance at the table
+            // tells you which one `arbi docs / ask / upload` will hit.
+            value: (r) => {
+              const name = r.name ?? "";
+              return r.external_id === selectedId ? `* ${name}` : `  ${name}`;
+            }
+          },
           {
             header: "DOCS",
             width: 6,
@@ -4623,8 +4883,11 @@ function registerWorkspacesCommand(program2) {
           },
           {
             header: "ROLE",
-            width: 10,
-            value: (r) => r.users?.[0]?.role ?? ""
+            width: 12,
+            // `common` (italics dimmed) for memberless rows the caller can
+            // see only because it's a deployment-wide workspace. The blank
+            // ROLE that used to render here read like missing data.
+            value: (r) => r.users?.[0]?.role ?? "common"
           }
         ],
         data
@@ -4699,7 +4962,7 @@ function registerWorkspacesCommand(program2) {
       success(`Selected: ${ws.name} (${ref(selectedId)})`);
     })()
   );
-  workspace.command("create <name>").description("Create a new workspace").option("-d, --description <text>", "Workspace description").option("--public", "Make workspace public", false).option("--select", "Set the new workspace as the active selection", false).option("--json", "Output the new workspace as JSON").action(
+  workspace.command("create <name>").description("Create a new workspace").option("-d, --description <text>", "Workspace description").option("--public", "Make workspace public", false).option("--select", "Set the new workspace as the active selection", false).action(
     (name, opts) => runAction(async () => {
       const { arbi, loginResult } = await resolveAuth();
       const userProjects = await sdk.projects.listProjects(arbi);
@@ -4718,25 +4981,11 @@ function registerWorkspacesCommand(program2) {
         updateConfig({ selectedWorkspaceId: data.external_id });
         clearChatSession();
       }
-      if (opts.json) {
-        console.log(
-          JSON.stringify(
-            {
-              id: data.external_id,
-              name: data.name,
-              selected: opts.select ?? false
-            },
-            null,
-            2
-          )
-        );
-        return;
-      }
       success(`Created: ${data.name} (${ref(data.external_id)})`);
       if (opts.select) success(`Selected: ${data.name} (${ref(data.external_id)})`);
     })()
   );
-  workspace.command("delete [id-or-name]").description("Delete a workspace (defaults to selected workspace)").option("-y, --yes", "Skip confirmation prompt (required in non-interactive shells)", false).option("--json", "Output the result as JSON").action(
+  workspace.command("delete [id-or-name]").description("Delete a workspace (defaults to selected workspace)").option("-y, --yes", "Skip confirmation prompt (required in non-interactive shells)", false).option("--dry-run", "Preview which workspace would be deleted (no SDK call)").action(
     (idOrName, opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const config = getConfig();
@@ -4758,9 +5007,14 @@ function registerWorkspacesCommand(program2) {
           process.exit(1);
         }
       }
-      const isInteractive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+      if (opts.dryRun) {
+        const label2 = targetName ? `${targetId} ("${targetName}")` : targetId;
+        dryRun("delete workspace (along with all its documents, conversations, and tags)", label2);
+        return;
+      }
+      const isInteractive2 = process.stdin.isTTY === true && process.stdout.isTTY === true;
       if (!opts.yes) {
-        if (!isInteractive) {
+        if (!isInteractive2) {
           error(
             `Refusing to delete ${targetId} without confirmation. Re-run with --yes (non-interactive shell).`
           );
@@ -4784,22 +5038,42 @@ function registerWorkspacesCommand(program2) {
       if (session.workspaceId === targetId) {
         clearChatSession();
       }
-      if (opts.json) {
-        console.log(JSON.stringify({ id: targetId, deleted: true }, null, 2));
-        return;
-      }
       success(`Deleted workspace ${targetId}`);
     })()
   );
-  workspace.command("update <json>").description("Update workspace properties (pass JSON)").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("--json", "Output the updated workspace as JSON").action(
+  workspace.command("rename <name>").description("Rename the active workspace").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(
+    (name, opts) => runAction(async () => {
+      const { arbi } = await resolveWorkspace(opts.workspace);
+      const data = await sdk.workspaces.updateWorkspace(arbi, { name });
+      success(`Renamed: ${data.name} (${ref(data.external_id)})`);
+    })()
+  );
+  workspace.command("describe <description>").description("Update the workspace's description").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(
+    (description, opts) => runAction(async () => {
+      const { arbi } = await resolveWorkspace(opts.workspace);
+      const data = await sdk.workspaces.updateWorkspace(arbi, {
+        description
+      });
+      success(`Updated description: ${data.name} (${ref(data.external_id)})`);
+    })()
+  );
+  workspace.command("public <on-or-off>").description("Toggle workspace visibility (on = public, off = private)").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(
+    (onOff, opts) => runAction(async () => {
+      const isPublic = onOff === "on" || onOff === "true" || onOff === "public";
+      const { arbi } = await resolveWorkspace(opts.workspace);
+      const data = await sdk.workspaces.updateWorkspace(arbi, {
+        is_public: isPublic
+      });
+      success(
+        `Visibility: ${isPublic ? "public" : "private"} \u2014 ${data.name} (${ref(data.external_id)})`
+      );
+    })()
+  );
+  workspace.command("update <json>").description("Update workspace properties (pass JSON; prefer `rename`/`describe`/`public`)").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(
     (json, opts) => runAction(async () => {
       const body = parseJsonArg(json, `arbi workspace update '{"name": "New Name"}'`);
       const { arbi } = await resolveWorkspace(opts.workspace);
       const data = await sdk.workspaces.updateWorkspace(arbi, body);
-      if (opts.json) {
-        console.log(JSON.stringify({ id: data.external_id, name: data.name }, null, 2));
-        return;
-      }
       success(`Updated: ${data.name} (${ref(data.external_id)})`);
     })()
   );
@@ -4862,13 +5136,72 @@ function registerWorkspacesCommand(program2) {
       for (const u of data) success(`Added: ${u.user.email} as ${u.role}`);
     })()
   );
-  workspace.command("remove-user <user-ids...>").description("Remove users from the active workspace").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(
-    (userIds, opts) => runAction(async () => {
+  workspace.command("remove-user <users...>").description("Remove users from the active workspace (accepts usr-ids or emails)").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("--dry-run", "Preview which users would be removed (no SDK call)").action(
+    (users, opts) => runAction(async () => {
       const { arbi } = await resolveWorkspace(opts.workspace);
+      const needsLookup = users.some((u) => u.includes("@"));
+      let userIds = users;
+      if (needsLookup) {
+        const members = await sdk.workspaces.listWorkspaceUsers(arbi);
+        userIds = users.map((u) => {
+          if (!u.includes("@")) return u;
+          const hit = members.find((m) => m.email === u);
+          if (!hit) {
+            error(`Workspace member ${u} not found. Try: arbi workspace users`);
+            process.exit(3);
+          }
+          return hit.external_id;
+        });
+      }
+      if (opts.dryRun) {
+        dryRun(`remove ${userIds.length} user(s) from this workspace`, userIds);
+        return;
+      }
       await sdk.workspaces.removeWorkspaceUsers(arbi, userIds);
       success(`Removed ${userIds.length} user(s).`);
     })()
   );
+  workspace.command("leave [id-or-name]").description("Leave a workspace (defaults to the active one)").option("-y, --yes", "Skip confirmation (required in non-TTY shells)").option("--dry-run", "Preview which workspace would be left (no SDK call)").action(
+    (selector, opts) => runAction(async () => {
+      const { arbi: userArbi } = await resolveAuth();
+      const wsList = await sdk.workspaces.listWorkspaces(userArbi);
+      const target = selector ? resolveWorkspaceSelector(wsList, selector) : (() => {
+        const activeId = getConfig()?.selectedWorkspaceId;
+        const hit = wsList.find((w) => w.external_id === activeId);
+        return hit ? { ok: true, id: hit.external_id, ws: hit } : { ok: false, reason: "not-found" };
+      })();
+      if (!target.ok) {
+        printResolveError(wsList, selector ?? "(active workspace)", target);
+        process.exit(3);
+      }
+      const selfExtId = userArbi.session.getState().userExtId;
+      if (!selfExtId) {
+        error("No user ID in session \u2014 cannot resolve self for leave.");
+        process.exit(1);
+      }
+      if (opts.dryRun) {
+        dryRun("leave workspace", `${target.id} ("${target.ws.name}")`);
+        return;
+      }
+      if (!opts?.yes) {
+        requireInteractive("Pass -y/--yes to confirm in non-TTY shells.");
+        const confirmed = await promptConfirm(
+          `Leave workspace "${target.ws.name}" (${target.id})?`,
+          false
+        );
+        if (!confirmed) {
+          console.log("Cancelled.");
+          return;
+        }
+      }
+      const { arbi } = await resolveWorkspace(target.id);
+      await sdk.workspaces.removeWorkspaceUsers(arbi, [selfExtId]);
+      if (getConfig()?.selectedWorkspaceId === target.id) {
+        updateConfig({ selectedWorkspaceId: "" });
+      }
+      success(`Left workspace "${target.ws.name}" (${target.id}).`);
+    })()
+  );
   workspace.command("set-role <role> <user-ids...>").description("Update user roles (owner, collaborator, guest)").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(
     (role, userIds, opts) => runAction(async () => {
       const { arbi } = await resolveWorkspace(opts.workspace);
@@ -4880,15 +5213,29 @@ function registerWorkspacesCommand(program2) {
       for (const u of data) success(`Updated: ${u.user.email} \u2192 ${u.role}`);
     })()
   );
-  workspace.command("copy <target-workspace-id> <doc-ids...>").description("Copy documents to another workspace").option("-w, --workspace <id>", "Source workspace ID (defaults to selected workspace)").action(
-    (targetId, docIds, opts) => runAction(async () => {
+  workspace.command("copy <target-workspace> <doc-ids...>").description("Copy documents to another workspace (target accepts ID or unique name)").option("-w, --workspace <id>", "Source workspace ID (defaults to selected workspace)").action(
+    (targetRef, docIds, opts) => runAction(async () => {
       const { arbi: userArbi } = await resolveAuth();
       const wsList = await sdk.workspaces.listWorkspaces(userArbi);
-      const targetWs = wsList.find((w) => w.external_id === targetId);
+      let targetWs = wsList.find((w) => w.external_id === targetRef);
+      if (!targetWs) {
+        const nameMatches = wsList.filter(
+          (w) => w.name?.toLowerCase() === targetRef.toLowerCase()
+        );
+        if (nameMatches.length === 1) {
+          targetWs = nameMatches[0];
+        } else if (nameMatches.length > 1) {
+          error(
+            `Ambiguous target workspace "${targetRef}" \u2014 matches ${nameMatches.map((w) => w.external_id).join(", ")}. Use the ID.`
+          );
+          process.exit(3);
+        }
+      }
       if (!targetWs || !targetWs.wrapped_key) {
-        error(`Target workspace ${targetId} not found or has no encryption key`);
-        process.exit(1);
+        error(`Target workspace ${targetRef} not found or has no encryption key`);
+        process.exit(3);
       }
+      const targetId = targetWs.external_id;
       const { arbi, loginResult } = await resolveWorkspace(opts.workspace);
       const signingPrivateKeyBase64 = arbi.crypto.bytesToBase64(loginResult.signingPrivateKey);
       const targetKey = await sdk.generateEncryptedWorkspaceKey(
@@ -4913,6 +5260,7 @@ function registerWorkspacesCommand(program2) {
     })()
   );
 }
+init_prompts();
 function statusSymbol(status2) {
   switch (status2) {
     case "completed":
@@ -5235,8 +5583,8 @@ function registerDocsCommand(program2) {
       }
     })()
   );
-  doc.command("delete [ids...]").description("Delete documents (interactive picker if no IDs given)").action(
-    (ids) => runAction(async () => {
+  doc.command("delete [ids...]").description("Delete documents (interactive picker if no IDs given)").option("--dry-run", "Preview which docs would be deleted (no SDK call)").action(
+    (ids, opts) => runAction(async () => {
       const { arbi } = await resolveWorkspace();
       let docIds = ids && ids.length > 0 ? ids : void 0;
       if (!docIds) {
@@ -5245,26 +5593,94 @@ function registerDocsCommand(program2) {
         if (selected.length === 0) return;
         docIds = selected;
       }
+      if (opts?.dryRun) {
+        dryRun(`delete ${docIds.length} document(s)`, docIds);
+        return;
+      }
       await sdk.documents.deleteDocuments(arbi, docIds);
       success(`Deleted ${docIds.length} document(s).`);
     })()
   );
-  doc.command("update [json]").description("Update documents (interactive form if no JSON given)").action(
-    (json) => runAction(async () => {
-      if (json) {
-        const parsed = parseJsonArg(json, `arbi doc update '[{"external_id": "doc-123", "shared": true}]'`);
-        const docs = Array.isArray(parsed) ? parsed : parsed.documents;
-        const { arbi } = await resolveWorkspace();
-        const data = await sdk.documents.updateDocuments(
-          arbi,
-          docs
-        );
-        success(`Updated ${data.length} document(s).`);
-      } else {
-        const { arbi } = await resolveWorkspace();
-        const choices = await fetchDocChoices(arbi);
-        const docId = await promptSearch("Select document to update", choices);
-        const field = await promptSelect("Field to update", [
+  doc.command("share <ids...>").description("Mark documents as shared (visible to all workspace members)").action(
+    (ids) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      await sdk.documents.updateDocuments(
+        arbi,
+        ids.map((external_id) => ({ external_id, shared: true }))
+      );
+      success(`Shared ${ids.length} document(s).`);
+    })()
+  );
+  doc.command("unshare <ids...>").description("Mark documents as private (owner-only)").action(
+    (ids) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      await sdk.documents.updateDocuments(
+        arbi,
+        ids.map((external_id) => ({ external_id, shared: false }))
+      );
+      success(`Unshared ${ids.length} document(s).`);
+    })()
+  );
+  doc.command("similar [doc-id]").description("Find near-duplicate documents (cached similarity pairs)").option(
+    "--threshold <n>",
+    "Minimum cosine similarity score, 0.0\u20131.0 (default 0.0 = all stored pairs)",
+    (v) => parseFloat(v),
+    0
+  ).option("--json", "Output as JSON").action(
+    (docId, opts) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      const res = await arbi.fetch.GET("/v1/document/similar", {
+        params: {
+          query: {
+            ...docId ? { doc_ext_id: docId } : {},
+            threshold: opts.threshold
+          }
+        }
+      });
+      if (res.error) throw new Error(`similar failed: ${JSON.stringify(res.error)}`);
+      const envelope = res.data;
+      const pairs = envelope.pairs ?? [];
+      if (opts.json) {
+        console.log(JSON.stringify(envelope, null, 2));
+        return;
+      }
+      if (pairs.length === 0) {
+        process.stderr.write(
+          docId ? `No similar documents found above threshold ${opts.threshold}.
+` : "No stored similarity pairs.\n"
+        );
+        return;
+      }
+      printTable(
+        [
+          { header: "DOC A", width: 18, value: (r) => r.doc_a_ext_id ?? "" },
+          { header: "DOC B", width: 18, value: (r) => r.doc_b_ext_id ?? "" },
+          {
+            header: "SCORE",
+            width: 8,
+            value: (r) => (r.score ?? 0).toFixed(3)
+          }
+        ],
+        pairs
+      );
+    })()
+  );
+  doc.command("update [json]").description("Update documents (interactive form if no JSON given)").action(
+    (json) => runAction(async () => {
+      if (json) {
+        const parsed = parseJsonArg(json, `arbi doc update '[{"external_id": "doc-123", "shared": true}]'`);
+        const docs = Array.isArray(parsed) ? parsed : parsed.documents;
+        const { arbi } = await resolveWorkspace();
+        const data = await sdk.documents.updateDocuments(
+          arbi,
+          docs
+        );
+        success(`Updated ${data.length} document(s).`);
+      } else {
+        const { arbi } = await resolveWorkspace();
+        const choices = await fetchDocChoices(arbi);
+        const docId = await promptSearch("Select document to update", choices);
+        const field = await promptSelect("Field to update", [
           { name: "Title", value: "title" },
           { name: "Shared", value: "shared" },
           { name: "Author", value: "author" },
@@ -5344,9 +5760,9 @@ function registerDocsCommand(program2) {
     "5"
   ).option("-v, --verbose", "Print a log line after each batch in addition to periodic stats.").option("-q, --quiet", "Suppress periodic progress lines \u2014 only print the final summary.").option("-W, --watch", "Watch document processing progress after submission").option("--no-watch", "Skip watching document processing").action(
     (ids, opts) => runAction(async () => {
-      const isInteractive = process.stdout.isTTY === true;
+      const isInteractive2 = process.stdout.isTTY === true;
       const watchPref = getConfig()?.watch !== false;
-      const willWatch = opts.watch === false ? false : opts.watch === true || watchPref && isInteractive;
+      const willWatch = opts.watch === false ? false : opts.watch === true || watchPref && isInteractive2;
       const { arbi, config, accessToken } = await resolveWorkspace(void 0, {
         skipNotifications: true
       });
@@ -5440,7 +5856,7 @@ function registerDocsCommand(program2) {
       if (!opts.quiet && statusIntervalMs > 0) {
         statusTimer = setInterval(() => printStatus("  "), statusIntervalMs);
       }
-      const sleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+      const sleep = (ms) => new Promise((resolve5) => setTimeout(resolve5, ms));
       const backoff = async (attempt) => {
         const delayMs = Math.min(1e3 * Math.pow(2, attempt), 3e4);
         await sleep(delayMs);
@@ -5718,9 +6134,9 @@ function classifyDirectInputs(inputPaths) {
   return out;
 }
 async function runDirectUploadMode(inputPaths, opts) {
-  const isInteractive = process.stdout.isTTY === true;
+  const isInteractive2 = process.stdout.isTTY === true;
   const watchPref = getConfig()?.watch !== false;
-  const willWatch = opts.watch === false ? false : opts.watch === true || watchPref && isInteractive;
+  const willWatch = opts.watch === false ? false : opts.watch === true || watchPref && isInteractive2;
   const inputs = classifyDirectInputs(inputPaths);
   if (inputs.length === 0) {
     warn("No supported files found to upload.");
@@ -5949,9 +6365,9 @@ function registerUploadCommand(program2) {
           process.exit(1);
         }
       }
-      const isInteractive = process.stdout.isTTY === true;
+      const isInteractive2 = process.stdout.isTTY === true;
       const watchPref = getConfig()?.watch !== false;
-      const willWatch = opts.watch === false ? false : opts.watch === true || watchPref && isInteractive;
+      const willWatch = opts.watch === false ? false : opts.watch === true || watchPref && isInteractive2;
       const { config, accessToken } = await resolveWorkspace(opts.workspace, {
         skipNotifications: willWatch
       });
@@ -6127,7 +6543,7 @@ Watching ${pending.size} document(s)...`);
                 pending.delete(msg.doc_ext_id);
               } else {
                 console.log(`  ${docName}: ${status(msg.status)} (${msg.progress}%)`);
-                if (msg.status === "completed") {
+                if (sdk.DOC_TERMINAL_STATUSES.has(msg.status)) {
                   pending.delete(msg.doc_ext_id);
                 }
               }
@@ -6415,7 +6831,7 @@ async function runManifestMode(inputPaths, opts) {
       pathsToUpload = pathsToUpload.slice(0, n);
     }
   }
-  const isInteractive = process.stdout.isTTY === true;
+  const isInteractive2 = process.stdout.isTTY === true;
   const humanOutput = !opts.json;
   if (humanOutput) {
     console.log(
@@ -6441,7 +6857,7 @@ async function runManifestMode(inputPaths, opts) {
     return;
   }
   const watchPref = getConfig()?.watch !== false;
-  const willWatch = opts.watch === false ? false : opts.watch === true || watchPref && isInteractive;
+  const willWatch = opts.watch === false ? false : opts.watch === true || watchPref && isInteractive2;
   const { config, accessToken, workspaceId } = await resolveWorkspace(opts.workspace, {
     skipNotifications: willWatch
   });
@@ -6489,13 +6905,13 @@ async function runManifestMode(inputPaths, opts) {
   let errorCount = 0;
   let skippedCount = 0;
   const renderProgress = () => {
-    if (!humanOutput || !isInteractive) return;
+    if (!humanOutput || !isInteractive2) return;
     const pct = total > 0 ? Math.floor(done / total * 100) : 100;
     const line = `  ${done}/${total} (${pct}%)  ok=${uploadedCount}` + (duplicateCount > 0 ? ` dup=${duplicateCount}` : "") + (rejectedCount > 0 ? ` rej=${rejectedCount}` : "") + (skippedCount > 0 ? ` skip=${skippedCount}` : "") + (errorCount > 0 ? ` err=${errorCount}` : "");
     process.stderr.write("\r" + line.padEnd(80, " "));
   };
   const clearProgress = () => {
-    if (humanOutput && isInteractive) process.stderr.write("\r" + " ".repeat(80) + "\r");
+    if (humanOutput && isInteractive2) process.stderr.write("\r" + " ".repeat(80) + "\r");
   };
   const printInlineOutcome = (o) => {
     if (!humanOutput) return;
@@ -6628,7 +7044,7 @@ Watching ${pending.size} document(s)...`);
             pending.delete(msg.doc_ext_id);
           } else {
             console.log(`  ${docName}: ${status(msg.status)} (${msg.progress}%)`);
-            if (msg.status === "completed") {
+            if (sdk.DOC_TERMINAL_STATUSES.has(msg.status)) {
               pending.delete(msg.doc_ext_id);
             }
           }
@@ -6658,6 +7074,7 @@ Connection closed. ${pending.size} document(s) still processing.`);
     await done2;
   }
 }
+init_prompts();
 function registerDownloadCommand(program2) {
   program2.command("download [doc-id]").description("Download a document (interactive picker if no ID given)").option(
     "-o, --output <path>",
@@ -6716,8 +7133,17 @@ function registerDownloadCommand(program2) {
   );
 }
 function registerAskCommand(program2) {
-  program2.command("ask <question...>").description("Ask the RAG assistant a question (no quotes needed)").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("-c, --continue <msg-id>", "Continue from a specific message ID").option("--config <id>", "Config ext_id to use (e.g. cfg-xxx)").option("-n, --new", "Start a new conversation (ignore previous context)").option("-b, --background", "Submit as background task (fire and forget)").option("-q, --quiet", "Suppress agent steps and tool calls").option("--json", "Output in JSON format (background mode only)").action(
+  program2.command("ask <question...>").description("Ask the RAG assistant a question (no quotes needed)").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("-c, --continue <msg-id>", "Continue from a specific message ID").option("--config <id>", "Config ext_id to use (e.g. cfg-xxx)").option("-n, --new", "Start a new conversation (ignore previous context)").option("-b, --background", "Submit as background task \u2014 fetch result with `arbi task result`").option("-q, --quiet", "Suppress agent steps and tool calls").option("--json", "Output in JSON format (background mode only)").option(
+    "--raw-citations",
+    "Keep raw `[text](#cite-N)` markdown links instead of the cleaner `text[N]` form"
+  ).action(
     (words, opts) => runAction(async () => {
+      if (opts.json && !opts.background) {
+        console.error(
+          "Error: --json only works with -b/--background. Streaming mode emits prose, not JSON.\nRun: arbi ask -b --json <question>  (then `arbi task result`)"
+        );
+        process.exit(1);
+      }
       const question = words.join(" ");
       const { arbi, accessToken, workspaceId, config } = await resolveWorkspace(opts.workspace);
       let previousResponseId = null;
@@ -6792,13 +7218,23 @@ function registerAskCommand(program2) {
       const verbose = opts.quiet === true ? false : getConfig()?.verbose !== false;
       let elapsedTime = null;
       let firstToken = true;
+      let buf = "";
+      const transform = opts.rawCitations ? (s) => s : sdk.stripCitationMarkdown;
+      const flush = (final) => {
+        const cut = final ? buf.length : Math.max(0, buf.length - 32);
+        if (cut === 0) return;
+        const out = transform(buf.slice(0, cut));
+        buf = buf.slice(cut);
+        if (out) process.stdout.write(out);
+      };
       const result = await sdk.streamSSE(res, {
         onToken: (content) => {
           if (firstToken) {
             process.stderr.write(chalk2__default.default.dim("[ARBI] "));
             firstToken = false;
           }
-          process.stdout.write(content);
+          buf += content;
+          flush(false);
         },
         onAgentStep: (data) => {
           if (verbose) {
@@ -6815,6 +7251,7 @@ function registerAskCommand(program2) {
         onError: (message) => console.error(chalk2__default.default.red(`
 Error: ${message}`))
       });
+      flush(true);
       process.stdout.write("\n");
       if (result.metadata) {
         saveLastMetadata(result.metadata);
@@ -6833,9 +7270,10 @@ Error: ${message}`))
           chalk2__default.default.dim(`[${refs} citation${refs === 1 ? "" : "s"} \u2014 arbi cite to browse]`)
         );
       }
-      if (result.assistantMessageExtId) {
+      const assistantId = result.assistantMessageExtId ?? result.metadata?.external_id;
+      if (assistantId) {
         const updates = {
-          lastMessageExtId: result.assistantMessageExtId,
+          lastMessageExtId: assistantId,
           workspaceId
         };
         const conversationExtId = result.userMessage?.conversation_ext_id ?? result.metadata?.conversation_ext_id;
@@ -6843,96 +7281,202 @@ Error: ${message}`))
           updates.conversationExtId = conversationExtId;
         }
         updateChatSession(updates);
+      } else if (opts.quiet !== true) {
+        console.error(
+          chalk2__default.default.yellow(
+            "[warn] No assistant message ID received \u2014 session not saved. The next `arbi ask` will start a new conversation."
+          )
+        );
       }
     })()
   );
 }
-var MAX_PASSAGE_LINES = 40;
+function hashUtf8(s) {
+  return crypto$1.createHash("sha256").update(s, "utf8").digest("hex");
+}
 function registerCiteCommand(program2) {
-  program2.command("cite [number]").description("Browse citations from the last response").option("-a, --all", "Show all citations with full passages").action(
-    (number, opts) => runAction(async () => {
-      const raw = loadLastMetadata();
-      if (!raw) {
-        console.error(chalk2__default.default.dim("No citation data available. Run `arbi ask` first."));
-        return;
-      }
-      const metadata = raw;
-      const count = sdk.countCitations(metadata);
-      if (count === 0) {
-        console.log(chalk2__default.default.dim("The last response contained no citations."));
-        return;
-      }
-      const resolved = sdk.resolveCitations(metadata);
-      if (opts.all) {
-        for (const r of resolved) {
-          printCitationDetail(r.citationNum, resolved);
-          console.log();
+  program2.command("cite [number]").description("Browse citations from the last `arbi ask` response in this shell").allowExcessArguments(true).option("-a, --all", "Show all citations as markdown blocks").option("--json", "Output citations as JSON (full structured payload)").action(
+    (numberOrVerb, opts) => runAction(async () => {
+      if (numberOrVerb === "verify") {
+        const argv = process.argv;
+        const i = argv.indexOf("verify");
+        const target = i !== -1 ? argv[i + 1] : void 0;
+        if (!target) {
+          console.error("Usage: arbi cite verify <number>");
+          process.exit(1);
         }
+        await verifyOne(target, opts);
         return;
       }
-      if (number) {
-        printCitationDetail(number, resolved);
-        return;
-      }
-      const summaries = sdk.summarizeCitations(resolved);
-      console.log(chalk2__default.default.bold(`Citations (${summaries.length}):
-`));
-      for (const s of summaries) {
-        const page = s.pageNumber != null ? `, p${s.pageNumber}` : "";
-        const chunks = s.chunkCount > 1 ? ` (${s.chunkCount} passages)` : "";
-        console.log(
-          `  ${chalk2__default.default.cyan(`[${s.citationNum}]`)} ${chalk2__default.default.bold(s.docTitle)}${page}${chunks}`
-        );
-        const truncated = s.statement.length > 120 ? s.statement.slice(0, 120).replace(/\n/g, " ").trim() + "..." : s.statement.replace(/\n/g, " ").trim();
-        console.log(`      ${chalk2__default.default.dim(truncated)}`);
-      }
-      console.log(chalk2__default.default.dim(`
-Use \`arbi cite <N>\` to view full passage.`));
+      await listOrShow(numberOrVerb, opts);
     })()
   );
 }
-function printCitationDetail(num, resolved) {
-  const citation = resolved.find((r) => r.citationNum === num);
-  if (!citation) {
-    console.error(chalk2__default.default.red(`Citation [${num}] not found.`));
-    return;
-  }
-  const firstChunk = citation.chunks[0];
+function renderCitation(r) {
+  const firstChunk = r.chunks[0];
   const docTitle = firstChunk?.metadata?.doc_title ?? "Unknown document";
   const page = firstChunk?.metadata?.page_number;
-  console.log(chalk2__default.default.bold.cyan(`[Citation ${citation.citationNum}]`) + " " + chalk2__default.default.bold(docTitle));
-  if (page != null) {
-    console.log(chalk2__default.default.dim(`Page ${page}`));
-  }
-  console.log();
-  console.log(chalk2__default.default.bold("Statement:"));
-  console.log(`  ${citation.citationData.statement}`);
-  console.log();
-  for (let i = 0; i < citation.chunks.length; i++) {
-    const chunk = citation.chunks[i];
-    if (citation.chunks.length > 1) {
-      console.log(chalk2__default.default.bold(`Passage ${i + 1}/${citation.chunks.length}:`));
-    } else {
-      console.log(chalk2__default.default.bold("Passage:"));
+  const docId = firstChunk?.metadata?.doc_ext_id ?? null;
+  const chunkId = firstChunk?.metadata?.chunk_ext_id ?? null;
+  const passage = r.chunks.map((c) => c.content).join("\n\n");
+  const sha = hashUtf8(passage);
+  const lines = [];
+  lines.push(chalk2__default.default.bold(`## Citation ${r.citationNum}`));
+  lines.push("");
+  lines.push(`${chalk2__default.default.bold("**Document:**")} ${docTitle}`);
+  if (page != null) lines.push(`${chalk2__default.default.bold("**Page:**")} ${page}`);
+  if (docId) lines.push(`${chalk2__default.default.bold("**Doc ID:**")} ${docId}`);
+  if (chunkId) lines.push(`${chalk2__default.default.bold("**Chunk ID:**")} ${chunkId}`);
+  lines.push(`${chalk2__default.default.bold("**SHA256:**")} ${sha}`);
+  lines.push("");
+  lines.push(chalk2__default.default.bold("### Claim"));
+  lines.push(r.citationData.statement ?? "");
+  lines.push("");
+  lines.push(chalk2__default.default.bold("### Passage"));
+  lines.push("```");
+  lines.push(passage);
+  lines.push("```");
+  return lines.join("\n");
+}
+async function listOrShow(number, opts) {
+  const raw = loadLastMetadata();
+  if (!raw) {
+    if (opts.json) {
+      printJson({ count: 0, citations: [] });
+      return;
     }
-    const lines = chunk.content.split("\n");
-    if (lines.length > MAX_PASSAGE_LINES) {
-      console.log(lines.slice(0, MAX_PASSAGE_LINES).join("\n"));
-      console.log(chalk2__default.default.dim(`  ... (${lines.length - MAX_PASSAGE_LINES} more lines)`));
-    } else {
-      console.log(chunk.content);
+    process.stderr.write("No citation data available. Run `arbi ask` first.\n");
+    return;
+  }
+  const metadata = raw;
+  if (sdk.countCitations(metadata) === 0) {
+    if (opts.json) {
+      printJson({ count: 0, citations: [] });
+      return;
+    }
+    process.stderr.write("The last response contained no citations.\n");
+    return;
+  }
+  const resolved = sdk.resolveCitations(metadata);
+  if (opts.json) {
+    const projection = resolved.map((r) => {
+      const passage = r.chunks.map((c) => c.content).join("\n\n");
+      return {
+        num: r.citationNum,
+        statement: r.citationData.statement ?? "",
+        doc_title: r.chunks[0]?.metadata?.doc_title ?? null,
+        page_number: r.chunks[0]?.metadata?.page_number ?? null,
+        chunk_ext_ids: r.chunks.map((c) => c.metadata?.chunk_ext_id ?? null),
+        doc_ext_ids: [...new Set(r.chunks.map((c) => c.metadata?.doc_ext_id).filter(Boolean))],
+        passages: r.chunks.map((c) => c.content),
+        passage_hashes: r.chunks.map((c) => hashUtf8(c.content)),
+        combined_passage_hash: hashUtf8(passage)
+      };
+    });
+    const filtered = number ? projection.filter((p) => p.num === number) : projection;
+    printJson({ count: filtered.length, citations: filtered });
+    return;
+  }
+  if (number) {
+    const hit = resolved.find((r) => r.citationNum === number);
+    if (!hit) {
+      console.error(chalk2__default.default.red(`Citation [${number}] not found.`));
+      process.exit(3);
+    }
+    console.log(renderCitation(hit));
+    return;
+  }
+  if (opts.all) {
+    for (let i = 0; i < resolved.length; i++) {
+      if (i > 0) console.log("\n---\n");
+      console.log(renderCitation(resolved[i]));
+    }
+    return;
+  }
+  console.log(chalk2__default.default.bold(`# Citations (${resolved.length})`));
+  console.log("");
+  for (const r of resolved) {
+    const docTitle = r.chunks[0]?.metadata?.doc_title ?? "Unknown document";
+    const page = r.chunks[0]?.metadata?.page_number;
+    const pageSuffix = page != null ? `, p${page}` : "";
+    const docId = r.chunks[0]?.metadata?.doc_ext_id;
+    const statement = (r.citationData.statement ?? "").replace(/\s+/g, " ").trim();
+    const trimmed = statement.length > 140 ? statement.slice(0, 140) + "\u2026" : statement;
+    console.log(
+      `- ${chalk2__default.default.bold(`[${r.citationNum}]`)} ${docTitle}${pageSuffix}${docId ? ` (${docId})` : ""}`
+    );
+    console.log(`  ${trimmed}`);
+  }
+  console.log("");
+  console.log(
+    chalk2__default.default.dim("`arbi cite <N>` for the full markdown block; `--json` for the structured payload.")
+  );
+}
+async function verifyOne(number, opts) {
+  const raw = loadLastMetadata();
+  if (!raw) {
+    if (opts.json) {
+      printJson({ verified: false, reason: "no-last-metadata" });
+      return;
+    }
+    process.stderr.write("No citation data available. Run `arbi ask` first.\n");
+    process.exit(1);
+  }
+  const metadata = raw;
+  const resolved = sdk.resolveCitations(metadata);
+  const citation = resolved.find((r) => r.citationNum === number);
+  if (!citation) {
+    if (opts.json) {
+      printJson({ verified: false, reason: "not-found", number });
+      return;
     }
-    if (i < citation.chunks.length - 1) console.log();
+    console.error(chalk2__default.default.red(`Citation [${number}] not found in last response.`));
+    process.exit(3);
+  }
+  const chunks = citation.chunks.map((c) => ({
+    chunk_ext_id: c.metadata?.chunk_ext_id ?? null,
+    doc_ext_id: c.metadata?.doc_ext_id ?? null,
+    doc_title: c.metadata?.doc_title ?? null,
+    page_number: c.metadata?.page_number ?? null,
+    passage_length: c.content.length,
+    passage_sha256: hashUtf8(c.content)
+  }));
+  if (opts.json) {
+    printJson({
+      verified: chunks.length > 0,
+      number,
+      statement: citation.citationData.statement ?? "",
+      chunks,
+      followup_hint: "For independent re-verification, run `arbi doc get <doc_ext_id> --json` and confirm the passage hash matches the doc content."
+    });
+    return;
   }
-  if (citation.chunks.length === 0) {
-    console.log(chalk2__default.default.dim("  (no passage data available)"));
+  console.log(chalk2__default.default.bold(`## Verification: Citation ${number}`));
+  console.log("");
+  console.log(`${chalk2__default.default.bold("**Status:**")} ${chunks.length > 0 ? "verified" : "no chunks"}`);
+  console.log(`${chalk2__default.default.bold("**Claim:**")} ${citation.citationData.statement ?? ""}`);
+  console.log("");
+  for (let i = 0; i < chunks.length; i++) {
+    const v = chunks[i];
+    console.log(chalk2__default.default.bold(`### Chunk ${i + 1}/${chunks.length}`));
+    console.log(`${chalk2__default.default.bold("**Doc:**")} ${v.doc_title ?? "Unknown"}`);
+    if (v.page_number != null) console.log(`${chalk2__default.default.bold("**Page:**")} ${v.page_number}`);
+    if (v.doc_ext_id) console.log(`${chalk2__default.default.bold("**Doc ID:**")} ${v.doc_ext_id}`);
+    if (v.chunk_ext_id) console.log(`${chalk2__default.default.bold("**Chunk ID:**")} ${v.chunk_ext_id}`);
+    console.log(`${chalk2__default.default.bold("**Length:**")} ${v.passage_length} chars`);
+    console.log(`${chalk2__default.default.bold("**SHA256:**")} ${v.passage_sha256}`);
+    if (i < chunks.length - 1) console.log("");
   }
+  console.log("");
+  console.log(
+    chalk2__default.default.dim("Re-verify: `arbi doc get <Doc ID> --json` and compare the passage SHA256.")
+  );
 }
 var MAX_INDIVIDUALLY_SELECTED_DOCS = 5e3;
 function chunkScore(chunk) {
   return chunk.metadata.rerank_score ?? chunk.metadata.score ?? 0;
 }
-function truncate(text, max) {
+function truncate2(text, max) {
   const oneLine = text.replace(/\n/g, " ").trim();
   return oneLine.length > max ? oneLine.slice(0, max - 1) + "\u2026" : oneLine;
 }
@@ -6987,11 +7531,22 @@ Narrow your selection, or omit -d to search the whole workspace.`
       const filtered = allChunks.filter((c) => chunkScore(c) >= minScore).sort((a, b) => chunkScore(b) - chunkScore(a)).slice(0, limit);
       const uniqueDocs = new Set(filtered.map((c) => c.metadata.doc_ext_id));
       if (opts.json) {
-        console.log(JSON.stringify(result, null, 2));
+        console.log(
+          JSON.stringify(
+            {
+              results: filtered,
+              count: filtered.length,
+              unique_documents: uniqueDocs.size,
+              raw: result
+            },
+            null,
+            2
+          )
+        );
         return;
       }
       if (filtered.length === 0) {
-        console.log("No results found.");
+        process.stderr.write("No results found.\n");
         return;
       }
       console.log(
@@ -7005,7 +7560,7 @@ Found ${chalk2__default.default.bold(String(filtered.length))} result${filtered.
           const score = fmtScore(chunkScore(chunk));
           const doc = chunk.metadata.doc_title ?? chunk.metadata.doc_ext_id ?? "";
           const page = chunk.metadata.page_number ? `p.${chunk.metadata.page_number}` : "";
-          const preview = truncate(chunk.content, 80);
+          const preview = truncate2(chunk.content, 80);
           console.log(
             `  ${chalk2__default.default.dim(String(i + 1).padStart(2, " "))}. ${chalk2__default.default.yellow(score)} ${chalk2__default.default.cyan(doc)} ${chalk2__default.default.dim(page)}`
           );
@@ -7030,7 +7585,7 @@ Found ${chalk2__default.default.bold(String(filtered.length))} result${filtered.
         for (const chunk of chunks) {
           const score = fmtScore(chunkScore(chunk));
           const page = chunk.metadata.page_number ? `p.${chunk.metadata.page_number}` : "";
-          const preview = truncate(chunk.content, 72);
+          const preview = truncate2(chunk.content, 72);
           console.log(
             `  ${chalk2__default.default.yellow(score)} ${chalk2__default.default.dim(page.padEnd(6))} ${chalk2__default.default.dim(preview)}`
           );
@@ -7046,8 +7601,19 @@ function colorize2(level, text) {
   if (level === "warning") return chalk2__default.default.yellow(text);
   return text;
 }
+var KNOWN_WATCH_TYPES = [
+  "task_update",
+  "batch_complete",
+  "presence_update",
+  "response_complete",
+  "notification",
+  "error"
+];
 function registerWatchCommand(program2) {
-  program2.command("watch").description("Watch workspace activity in real time").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("-t, --timeout <seconds>", "Auto-close after N seconds").option("-n, --count <n>", "Stop after N messages").option("--json", "Output NDJSON (one JSON object per line)").action(
+  program2.command("watch").description("Watch workspace activity in real time").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("-t, --timeout <seconds>", "Auto-close after N seconds").option("-n, --count <n>", "Stop after N messages").option(
+    "--type <comma-list>",
+    `Only emit events of these types (default: all). Known: ${KNOWN_WATCH_TYPES.join(",")}`
+  ).option("--json", "Output NDJSON (one JSON object per line)").action(
     (opts) => runAction(async () => {
       const { config, accessToken, workspaceId } = await resolveWorkspace(opts.workspace, {
         skipNotifications: true
@@ -7055,6 +7621,21 @@ function registerWatchCommand(program2) {
       const timeoutSec = opts.timeout ? parseInt(opts.timeout, 10) : void 0;
       const maxCount = opts.count ? parseInt(opts.count, 10) : void 0;
       const jsonMode = opts.json ?? false;
+      const typeFilter = opts.type ? new Set(
+        opts.type.split(",").map((t) => t.trim()).filter(Boolean)
+      ) : null;
+      if (typeFilter) {
+        const unknown = [...typeFilter].filter(
+          (t) => !KNOWN_WATCH_TYPES.includes(t)
+        );
+        if (unknown.length > 0) {
+          console.error(
+            `Error: unknown event type(s): ${unknown.join(", ")}
+Known: ${KNOWN_WATCH_TYPES.join(", ")}`
+          );
+          process.exit(1);
+        }
+      }
       if (!jsonMode) {
         const parts = [`Watching workspace ${workspaceId}...`];
         if (timeoutSec) parts.push(`(timeout: ${timeoutSec}s)`);
@@ -7063,6 +7644,7 @@ function registerWatchCommand(program2) {
         console.log(parts.join(" "));
       }
       let messageCount = 0;
+      let timedOut = false;
       let onDone;
       const done = new Promise((r) => {
         onDone = r;
@@ -7071,6 +7653,10 @@ function registerWatchCommand(program2) {
         baseUrl: config.baseUrl,
         accessToken,
         onMessage: (msg) => {
+          if (typeFilter) {
+            const type = msg.type;
+            if (!type || !typeFilter.has(type)) return;
+          }
           messageCount++;
           if (jsonMode) {
             console.log(JSON.stringify(msg));
@@ -7097,6 +7683,7 @@ Connection closed (code ${code}${reason ? ": " + reason : ""})`)
       let timer;
       if (timeoutSec) {
         timer = setTimeout(() => {
+          timedOut = true;
           if (!jsonMode) console.log(chalk2__default.default.dim(`
 Timeout (${timeoutSec}s), closing.`));
           conn.close();
@@ -7110,21 +7697,53 @@ Timeout (${timeoutSec}s), closing.`));
       await done;
       if (timer) clearTimeout(timer);
       process.removeListener("SIGINT", sigintHandler);
+      if (timedOut && maxCount && messageCount < maxCount) {
+        if (jsonMode) {
+          console.log(
+            JSON.stringify({
+              type: "timeout",
+              received: messageCount,
+              expected: maxCount,
+              timeout_seconds: timeoutSec
+            })
+          );
+        } else {
+          console.error(
+            chalk2__default.default.yellow(`Timed out before reaching ${maxCount} messages (got ${messageCount}).`)
+          );
+        }
+        process.exit(124);
+      }
     })()
   );
 }
+init_prompts();
+function redactPictures(rows) {
+  return rows.map((row) => {
+    const user = row.user;
+    if (!user || typeof user.picture !== "string" || user.picture.length === 0) return row;
+    return {
+      ...row,
+      user: {
+        ...user,
+        has_picture: true,
+        picture: null
+      }
+    };
+  });
+}
 function registerContactsCommand(program2) {
-  const contacts = program2.command("contacts").description("Manage contacts");
-  contacts.command("list").description("List all contacts").option("--json", "Output as JSON").action(
+  const contacts = program2.command("contacts").description("Contacts: list, add, remove");
+  contacts.command("list").description("List all contacts").option("--json", "Output as JSON").option("--include-pictures", "Keep base64 profile-picture bytes in --json output").action(
     (opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.contacts.listContacts(arbi);
       if (opts.json) {
-        console.log(JSON.stringify(data, null, 2));
+        printJson(opts.includePictures ? data : redactPictures(data));
         return;
       }
       if (data.length === 0) {
-        console.log("No contacts found.");
+        process.stderr.write("No contacts found.\n");
         return;
       }
       printTable(
@@ -7146,6 +7765,7 @@ function registerContactsCommand(program2) {
     (emails) => runAction(async () => {
       const { arbi } = await resolveAuth();
       if (!emails || emails.length === 0) {
+        requireInteractive("Pass email(s) as positional args: arbi contacts add foo@x.y bar@x.y");
         const input2 = await promptInput("Email address(es), comma-separated");
         emails = input2.split(",").map((e) => e.trim()).filter(Boolean);
         if (emails.length === 0) return;
@@ -7156,16 +7776,17 @@ function registerContactsCommand(program2) {
       }
     })()
   );
-  contacts.command("remove [ids...]").description("Remove contacts (interactive picker if no IDs given)").action(
-    (ids) => runAction(async () => {
+  contacts.command("remove [ids...]").description("Remove contacts (interactive picker if no IDs given)").option("--dry-run", "Preview which contacts would be removed (no SDK call)").action(
+    (ids, opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       let contactIds = ids && ids.length > 0 ? ids : void 0;
       if (!contactIds) {
         const data = await sdk.contacts.listContacts(arbi);
         if (data.length === 0) {
-          console.log("No contacts found.");
+          process.stderr.write("No contacts found.\n");
           return;
         }
+        requireInteractive("Pass contact IDs directly: arbi contacts remove cnt-\u2026");
         contactIds = await promptCheckbox(
           "Select contacts to remove",
           data.map((c) => {
@@ -7178,57 +7799,157 @@ function registerContactsCommand(program2) {
         );
         if (contactIds.length === 0) return;
       }
+      if (opts?.dryRun) {
+        dryRun(`remove ${contactIds.length} contact(s)`, contactIds);
+        return;
+      }
       await sdk.contacts.removeContacts(arbi, contactIds);
       success(`Removed ${contactIds.length} contact(s).`);
     })()
   );
-  contacts.option("--json", "Output as JSON").action(async (opts) => {
-    const args = [];
-    if (opts.json) args.push("--json");
-    await contacts.commands.find((c) => c.name() === "list").parseAsync(args, { from: "user" });
+  contacts.allowUnknownOption(true).allowExcessArguments(true).action(async () => {
+    const tail = contacts.args ?? [];
+    await contacts.commands.find((c) => c.name() === "list").parseAsync(tail, { from: "user" });
+  });
+}
+init_prompts();
+async function resolveRecipient(arbi, ref2) {
+  const isEmail = ref2.includes("@");
+  const matchKey = isEmail ? "email" : "external_id";
+  const contacts = await sdk.contacts.listContacts(arbi);
+  const contactMatch = contacts.find((c) => {
+    if (isEmail) return c.email === ref2;
+    const u = c.user;
+    return u?.external_id === ref2 || c.external_id === ref2;
   });
+  if (contactMatch) {
+    const u = contactMatch.user;
+    const extId = u?.external_id ?? contactMatch.external_id;
+    const pubKey = u?.encryption_public_key ?? "";
+    if (pubKey) return { extId, pubKey };
+  }
+  try {
+    const agents = await sdk.agents.listAgents(arbi);
+    const agentMatch = agents.find((a) => a[matchKey] === ref2);
+    if (agentMatch) {
+      return { extId: agentMatch.external_id, pubKey: agentMatch.encryption_public_key };
+    }
+  } catch {
+  }
+  try {
+    const wsUsers = await sdk.workspaces.listWorkspaceUsers(arbi);
+    const wsMatch = wsUsers.find((wu) => wu[matchKey] === ref2);
+    if (wsMatch) {
+      const u = wsMatch;
+      return {
+        extId: u.external_id,
+        pubKey: u.encryption_public_key
+      };
+    }
+  } catch {
+  }
+  return null;
+}
+function rowMatchesFilters(row, opts) {
+  if (opts.unread && row.read) return false;
+  const sender = row.sender;
+  const recipient = row.recipient;
+  if (opts.from) {
+    const needle = opts.from.toLowerCase();
+    const senderMatch = sender?.email?.toLowerCase() === needle || sender?.external_id === opts.from;
+    const recipientMatch = recipient?.email?.toLowerCase() === needle || recipient?.external_id === opts.from;
+    if (!senderMatch && !recipientMatch) return false;
+  }
+  if (opts.thread) {
+    const needle = opts.thread.toLowerCase();
+    const peer = sender?.external_id === opts.myExtId ? recipient : sender;
+    const peerMatch = peer?.email?.toLowerCase() === needle || peer?.external_id === opts.thread;
+    if (!peerMatch) return false;
+  }
+  if (opts.since) {
+    const cutoff = Date.parse(opts.since);
+    if (Number.isFinite(cutoff)) {
+      const createdAt = typeof row.created_at === "string" ? Date.parse(row.created_at) : NaN;
+      if (!Number.isFinite(createdAt) || createdAt < cutoff) return false;
+    }
+  }
+  return true;
 }
 function registerDmCommand(program2) {
   const dm = program2.command("dm").description("Direct messages (E2E encrypted)");
-  dm.command("list").description("List all DMs and notifications (decrypted)").action(
-    runAction(async () => {
+  dm.command("list").description("List direct messages (decrypted, newest first)").option("--unread", "Only show unread messages").option("--from <email-or-extid>", "Filter by sender OR recipient (email or usr- id)").option(
+    "--thread <email-or-extid>",
+    "Show the full conversation with one peer (both directions)"
+  ).option("--since <iso>", "Only messages newer than this ISO timestamp").option("-l, --limit <n>", "Cap to N most-recent messages", (v) => parseInt(v, 10)).option("--json", "Output as JSON (recommended for scripting / agents)").action(
+    (opts) => runAction(async () => {
       const { arbi, crypto: crypto2 } = await resolveDmCrypto();
-      const data = await sdk.dm.listDecryptedDMs(arbi, crypto2);
-      if (data.length === 0) {
-        console.log("No messages found.");
+      const all = await sdk.dm.listDecryptedDMs(arbi, crypto2);
+      const myExtId = arbi.session.getState().userExtId;
+      const dms = all.filter((r) => r.type === "user_message");
+      const filterOpts = {
+        unread: Boolean(opts.unread),
+        from: typeof opts.from === "string" ? opts.from : void 0,
+        thread: typeof opts.thread === "string" ? opts.thread : void 0,
+        since: typeof opts.since === "string" ? opts.since : void 0,
+        myExtId
+      };
+      const filtered = dms.filter((r) => rowMatchesFilters(r, filterOpts));
+      const limited = typeof opts.limit === "number" && opts.limit > 0 ? filtered.slice(0, opts.limit) : filtered;
+      if (opts.json) {
+        printJson(limited.map((r) => ({ ...r, encrypted_in_transit: true })));
+        return;
+      }
+      if (limited.length === 0) {
+        process.stderr.write("No messages found.\n");
         return;
       }
+      const peer = (r) => {
+        const s = r.sender;
+        const recip = r.recipient;
+        return s?.external_id === myExtId ? recip : s;
+      };
       printTable(
         [
           { header: "ID", width: 16, value: (r) => r.external_id },
-          { header: "TYPE", width: 18, value: (r) => r.type },
           {
-            header: "FROM",
-            width: 22,
+            header: "DIR",
+            width: 4,
+            value: (r) => r.sender?.external_id === myExtId ? "\u2192" : "\u2190"
+          },
+          {
+            header: "PEER",
+            width: 26,
             value: (r) => {
-              const s = r.sender;
-              return sdk.formatUserName(s) || s?.email || "";
+              const p = peer(r);
+              return sdk.formatUserName(p) || p?.email || "";
             }
           },
           { header: "READ", width: 6, value: (r) => r.read ? "yes" : "no" },
-          { header: "CONTENT", width: 40, value: (r) => r.content ?? "" }
+          {
+            header: "CONTENT",
+            width: 50,
+            value: (r) => truncate(r.content ?? "", 49)
+          }
         ],
-        data
+        limited
       );
-    })
+    })()
   );
   dm.command("send [recipient] [content...]").description("Send an E2E encrypted DM (interactive if no args)").action(
     (recipient, contentParts) => runAction(async () => {
       const { arbi, crypto: crypto2 } = await resolveDmCrypto();
       if (!recipient) {
-        const contacts2 = await sdk.contacts.listContacts(arbi);
-        if (contacts2.length === 0) {
+        requireInteractive(
+          'Pass recipient + message as arguments: arbi dm send <email-or-id> "<message>"'
+        );
+        const contacts = await sdk.contacts.listContacts(arbi);
+        if (contacts.length === 0) {
           error("No contacts found. Add contacts first: arbi contacts add <email>");
           process.exit(1);
         }
         recipient = await promptSelect(
           "Send to",
-          contacts2.map((c) => {
+          contacts.map((c) => {
             const u = c.user;
             const name = sdk.formatUserName(u);
             return {
@@ -7241,79 +7962,26 @@ function registerDmCommand(program2) {
       }
       let content = contentParts?.length ? contentParts.join(" ") : void 0;
       if (!content) {
+        requireInteractive(
+          'Pass the message as a positional argument: arbi dm send <email> "your message"'
+        );
         content = await promptInput("Message");
       }
-      const contacts = await sdk.contacts.listContacts(arbi);
-      let recipientExtId = recipient;
-      let recipientPubKey;
-      if (recipient.includes("@")) {
-        const match = contacts.find((c) => c.email === recipient);
-        if (match) {
-          const u = match.user;
-          recipientExtId = u?.external_id ?? match.external_id;
-          recipientPubKey = u?.encryption_public_key;
-        } else {
-          try {
-            const agentsList = await sdk.agents.listAgents(arbi);
-            const agentMatch = agentsList.find((a) => a.email === recipient);
-            if (agentMatch) {
-              recipientExtId = agentMatch.external_id;
-              recipientPubKey = agentMatch.encryption_public_key;
-            }
-          } catch {
-          }
-          if (!recipientPubKey) {
-            try {
-              const wsUsers = await sdk.workspaces.listWorkspaceUsers(arbi);
-              const wsMatch = wsUsers.find(
-                (wu) => wu.email === recipient
-              );
-              if (wsMatch) {
-                const u = wsMatch;
-                recipientExtId = u.external_id;
-                recipientPubKey = u.encryption_public_key;
-              }
-            } catch {
-            }
-          }
-          if (!recipientExtId || recipientExtId === recipient) {
-            error(`No contact, agent, or workspace member found with email: ${recipient}`);
-            process.exit(1);
-          }
-        }
-      } else {
-        const match = contacts.find((c) => {
-          const u = c.user;
-          return u?.external_id === recipient || c.external_id === recipient;
-        });
-        recipientPubKey = match?.user?.encryption_public_key;
-        if (!recipientPubKey) {
-          try {
-            const agentsList = await sdk.agents.listAgents(arbi);
-            const agentMatch = agentsList.find((a) => a.external_id === recipientExtId);
-            if (agentMatch) {
-              recipientPubKey = agentMatch.encryption_public_key;
-            }
-          } catch {
-          }
-        }
-        if (!recipientPubKey) {
-          try {
-            const wsUsers = await sdk.workspaces.listWorkspaceUsers(arbi);
-            const wsMatch = wsUsers.find(
-              (wu) => wu.external_id === recipientExtId
-            );
-            if (wsMatch) {
-              recipientPubKey = wsMatch.encryption_public_key;
-            }
-          } catch {
-          }
-        }
+      const resolved = await resolveRecipient(arbi, recipient);
+      if (!resolved) {
+        error(
+          `No contact, agent, or workspace member found for: ${recipient}
+Try: arbi contacts add ${recipient.includes("@") ? recipient : "<their-email>"}`
+        );
+        process.exit(3);
       }
+      const recipientExtId = resolved.extId;
+      const recipientPubKey = resolved.pubKey;
       if (!recipientPubKey) {
-        error("Cannot send encrypted DM \u2014 recipient public key not found.");
-        error("The recipient is not in your contacts or workspace.");
-        process.exit(1);
+        error(
+          "Cannot send encrypted DM \u2014 recipient public key not found.\nAdd them as a contact first: arbi contacts add <email>"
+        );
+        process.exit(3);
       }
       const data = await sdk.dm.sendEncryptedDM(
         arbi,
@@ -7327,21 +7995,26 @@ function registerDmCommand(program2) {
         crypto2
       );
       for (const n of data) {
-        success(`Sent: ${n.external_id} \u2192 ${n.recipient.email}`);
+        success(`Sent (encrypted): ${n.external_id} \u2192 ${n.recipient.email}`);
       }
     })()
   );
-  dm.command("read [ids...]").description("Mark messages as read (interactive picker if no IDs given)").action(
-    (ids) => runAction(async () => {
+  dm.command("read [ids...]").description("Mark messages as read (interactive picker if no IDs given)").option("--all", "Mark every unread message as read (no picker)").action(
+    (ids, opts) => runAction(async () => {
       const { arbi, crypto: crypto2 } = await resolveDmCrypto();
       let msgIds = ids && ids.length > 0 ? ids : void 0;
+      if (!msgIds && opts?.all) {
+        const data2 = await sdk.dm.listDecryptedDMs(arbi, crypto2);
+        msgIds = data2.filter((m) => !m.read).map((m) => m.external_id);
+      }
       if (!msgIds) {
         const data2 = await sdk.dm.listDecryptedDMs(arbi, crypto2);
         const unread = data2.filter((m) => !m.read);
         if (unread.length === 0) {
-          console.log("No unread messages.");
+          process.stderr.write("No unread messages.\n");
           return;
         }
+        requireInteractive("Pass IDs directly or use --all to mark every unread message read.");
         msgIds = await promptCheckbox(
           "Select messages to mark as read",
           unread.map((m) => {
@@ -7355,20 +8028,29 @@ function registerDmCommand(program2) {
         );
         if (msgIds.length === 0) return;
       }
+      if (msgIds.length === 0) {
+        process.stderr.write("No unread messages.\n");
+        return;
+      }
       const data = await sdk.dm.markRead(arbi, msgIds);
       success(`Marked ${data.length} message(s) as read.`);
     })()
   );
-  dm.command("delete [ids...]").description("Delete messages (interactive picker if no IDs given)").action(
-    (ids) => runAction(async () => {
+  dm.command("delete [ids...]").description("Delete messages (interactive picker if no IDs given)").option("--all", "Delete every message in your DM history (no picker, no prompt)").option("--dry-run", "Preview which messages would be deleted (no SDK call)").action(
+    (ids, opts) => runAction(async () => {
       const { arbi, crypto: crypto2 } = await resolveDmCrypto();
       let msgIds = ids && ids.length > 0 ? ids : void 0;
+      if (!msgIds && opts?.all) {
+        const data = await sdk.dm.listDecryptedDMs(arbi, crypto2);
+        msgIds = data.map((m) => m.external_id);
+      }
       if (!msgIds) {
         const data = await sdk.dm.listDecryptedDMs(arbi, crypto2);
         if (data.length === 0) {
-          console.log("No messages found.");
+          process.stderr.write("No messages found.\n");
           return;
         }
+        requireInteractive("Pass IDs directly or use --all to delete the whole inbox.");
         msgIds = await promptCheckbox(
           "Select messages to delete",
           data.map((m) => {
@@ -7382,18 +8064,34 @@ function registerDmCommand(program2) {
         );
         if (msgIds.length === 0) return;
       }
+      if (msgIds.length === 0) {
+        process.stderr.write("No messages to delete.\n");
+        return;
+      }
+      if (opts?.dryRun) {
+        dryRun(`delete ${msgIds.length} message(s)`, msgIds);
+        return;
+      }
       await sdk.dm.deleteDMs(arbi, msgIds);
       success(`Deleted ${msgIds.length} message(s).`);
     })()
   );
-  dm.action(async () => {
+  dm.arguments("[maybeSubcommand]").action(async (maybe) => {
+    if (maybe) {
+      suggestSubcommandAndExit(
+        "dm",
+        maybe,
+        dm.commands.map((c) => c.name())
+      );
+    }
     await dm.commands.find((c) => c.name() === "list").parseAsync([], { from: "user" });
   });
 }
+init_prompts();
 async function fetchTagChoices(arbi) {
   const data = await sdk.tags.listTags(arbi);
   if (data.length === 0) {
-    console.log("No tags found.");
+    process.stderr.write("No tags found.\n");
     process.exit(0);
   }
   return {
@@ -7406,17 +8104,17 @@ async function fetchTagChoices(arbi) {
   };
 }
 function registerTagsCommand(program2) {
-  const tags = program2.command("tags").description("Manage tags");
+  const tags = program2.command("tags").description("Tags: list, create, delete, update, share, unshare, rename");
   tags.command("list").description("List tags in the active workspace").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("--json", "Output as JSON").action(
     (opts) => runAction(async () => {
       const { arbi } = await resolveWorkspace(opts.workspace);
       const data = await sdk.tags.listTags(arbi);
       if (opts.json) {
-        console.log(JSON.stringify(data, null, 2));
+        printJson(data);
         return;
       }
       if (data.length === 0) {
-        console.log("No tags found.");
+        process.stderr.write("No tags found.\n");
         return;
       }
       printTable(
@@ -7470,17 +8168,42 @@ function registerTagsCommand(program2) {
       success(`Created: ${data.name} (${ref(data.external_id)})`);
     })()
   );
-  tags.command("delete [id]").description("Delete a tag (interactive picker if no ID given)").action(
-    (id) => runAction(async () => {
+  tags.command("delete [id]").description("Delete a tag (interactive picker if no ID given)").option("--dry-run", "Preview which tag would be deleted (no SDK call)").action(
+    (id, opts) => runAction(async () => {
       const { arbi } = await resolveWorkspace();
       if (!id) {
         const { choices } = await fetchTagChoices(arbi);
         id = await promptSelect("Select tag to delete", choices);
       }
+      if (opts?.dryRun) {
+        dryRun("delete tag", id);
+        return;
+      }
       const data = await sdk.tags.deleteTag(arbi, id);
       success(data?.detail ?? `Deleted tag ${id}`);
     })()
   );
+  tags.command("share <id>").description("Mark a tag as shared (visible to other workspace members)").action(
+    (id) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      const data = await sdk.tags.updateTag(arbi, id, { shared: true });
+      success(`Shared: ${data.name} (${ref(data.external_id)})`);
+    })()
+  );
+  tags.command("unshare <id>").description("Mark a tag as private (owner-only)").action(
+    (id) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      const data = await sdk.tags.updateTag(arbi, id, { shared: false });
+      success(`Unshared: ${data.name} (${ref(data.external_id)})`);
+    })()
+  );
+  tags.command("rename <id> <name>").description("Rename a tag").action(
+    (id, name) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      const data = await sdk.tags.updateTag(arbi, id, { name });
+      success(`Renamed: ${data.name} (${ref(data.external_id)})`);
+    })()
+  );
   tags.command("update [id] [json]").description("Update a tag (interactive picker + form if no args)").action(
     (id, json) => runAction(async () => {
       const { arbi } = await resolveWorkspace();
@@ -7507,34 +8230,43 @@ function registerTagsCommand(program2) {
       success(`Updated: ${data.name} (${ref(data.external_id)})`);
     })()
   );
-  tags.option("--json", "Output as JSON").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(async (opts, cmd) => {
-    const args = [];
-    if (opts.json) args.push("--json");
-    if (opts.workspace) args.push("-w", opts.workspace);
-    await cmd.commands.find((c) => c.name() === "list").parseAsync(args, { from: "user" });
+  tags.allowUnknownOption(true).allowExcessArguments(true).action(async () => {
+    const tail = tags.args ?? [];
+    await tags.commands.find((c) => c.name() === "list").parseAsync(tail, { from: "user" });
   });
 }
-async function pickTag(arbi, workspaceId, message = "Select tag") {
+init_prompts();
+async function resolveTagRef(arbi, ref2) {
+  if (ref2.startsWith("tag-")) return ref2;
   const data = await sdk.tags.listTags(arbi);
-  if (data.length === 0) {
-    console.log("No tags found.");
-    process.exit(0);
-  }
-  return promptSelect(
-    message,
-    data.map((t) => ({
-      name: `${t.name} (${t.tag_type?.type ?? ""})`,
-      value: t.external_id,
-      description: t.external_id
-    }))
+  const res = resolveByIdOrName(data, ref2);
+  if (!res.ok) failResolveAndExit("tag", ref2, res);
+  return res.id;
+}
+function pickTag(arbi, message = "Select tag") {
+  return sdk.tags.listTags(arbi).then(
+    (data) => pickFromList(
+      data,
+      (t) => ({
+        name: `${t.name} (${t.tag_type?.type ?? ""})`,
+        value: t.external_id,
+        description: t.external_id
+      }),
+      {
+        message,
+        emptyMessage: "No tags found.",
+        nonTtyHint: "Pass <tag-id> (or unique tag name) and <doc-ids...> directly."
+      }
+    )
   );
 }
-async function pickDocs(arbi, workspaceId, message = "Select documents") {
+async function pickDocs(arbi, message = "Select documents") {
   const data = await sdk.documents.listDocuments(arbi);
   if (data.length === 0) {
-    console.log("No documents found.");
+    process.stderr.write("No documents found.\n");
     process.exit(0);
   }
+  requireInteractive("Pass <doc-ids...> directly: arbi docs --ids to list them.");
   return promptCheckbox(
     message,
     data.map((d) => ({
@@ -7544,32 +8276,37 @@ async function pickDocs(arbi, workspaceId, message = "Select documents") {
   );
 }
 function registerDoctagsCommand(program2) {
-  const doctagsCmd = program2.command("doctags").description("Manage document tags (doctags)");
-  doctagsCmd.command("create [tag-id] [doc-ids...]").description("Assign a tag to documents (interactive pickers if no args)").option("-n, --note <text>", "Note for the doctag").action(
-    (tagId, docIds, opts) => runAction(async () => {
-      const { arbi, workspaceId } = await resolveWorkspace();
-      if (!tagId) tagId = await pickTag(arbi, workspaceId, "Select tag to assign");
-      if (!docIds || docIds.length === 0)
-        docIds = await pickDocs(arbi, workspaceId, "Select documents to tag");
+  const doctagsCmd = program2.command("doctags").description("Doctags (tag\u2194doc links): create, delete, generate");
+  doctagsCmd.command("create [tag] [doc-ids...]").description("Assign a tag to documents (tag accepts ID or unique name; pickers if no args)").option("-n, --note <text>", "Note for the doctag").action(
+    (tagRef, docIds, opts) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      let tagId = tagRef ? await resolveTagRef(arbi, tagRef) : void 0;
+      if (!tagId) tagId = await pickTag(arbi, "Select tag to assign");
+      if (!docIds || docIds.length === 0) docIds = await pickDocs(arbi, "Select documents to tag");
       if (docIds.length === 0) return;
       const data = await sdk.doctags.assignDocTags(arbi, tagId, docIds, opts?.note);
       success(`Created ${data.length} doctag(s) for tag ${tagId}.`);
     })()
   );
-  doctagsCmd.command("delete [tag-id] [doc-ids...]").description("Remove a tag from documents (interactive pickers if no args)").action(
-    (tagId, docIds) => runAction(async () => {
-      const { arbi, workspaceId } = await resolveWorkspace();
-      if (!tagId) tagId = await pickTag(arbi, workspaceId, "Select tag to remove");
+  doctagsCmd.command("delete [tag] [doc-ids...]").description("Remove a tag from documents (tag accepts ID or unique name; pickers if no args)").option("--dry-run", "Preview which doctag links would be removed (no SDK call)").action(
+    (tagRef, docIds, opts) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      let tagId = tagRef ? await resolveTagRef(arbi, tagRef) : void 0;
+      if (!tagId) tagId = await pickTag(arbi, "Select tag to remove");
       if (!docIds || docIds.length === 0)
-        docIds = await pickDocs(arbi, workspaceId, "Select documents to untag");
+        docIds = await pickDocs(arbi, "Select documents to untag");
       if (docIds.length === 0) return;
+      if (opts?.dryRun) {
+        dryRun(`remove tag ${tagId} from ${docIds.length} document(s)`, docIds);
+        return;
+      }
       await sdk.doctags.removeDocTags(arbi, tagId, docIds);
       success(`Removed tag ${tagId} from ${docIds.length} document(s).`);
     })()
   );
   doctagsCmd.command("generate").description("AI-generate doctags (interactive pickers if no flags)").option("--tags <ids>", "Comma-separated tag IDs").option("--docs <ids>", "Comma-separated document IDs").action(
     (opts) => runAction(async () => {
-      const { arbi, workspaceId } = await resolveWorkspace();
+      const { arbi } = await resolveWorkspace();
       let tagIds;
       if (opts.tags) {
         tagIds = opts.tags.split(",").map((s) => s.trim());
@@ -7592,7 +8329,7 @@ function registerDoctagsCommand(program2) {
       if (opts.docs) {
         docIds = opts.docs.split(",").map((s) => s.trim());
       } else {
-        docIds = await pickDocs(arbi, workspaceId, "Select documents for AI tagging");
+        docIds = await pickDocs(arbi, "Select documents for AI tagging");
         if (docIds.length === 0) return;
       }
       const data = await sdk.doctags.generateDocTags(arbi, tagIds, docIds);
@@ -7602,10 +8339,11 @@ function registerDoctagsCommand(program2) {
     })()
   );
 }
+init_prompts();
 async function pickConversation(arbi, workspaceId, message = "Select conversation") {
   const data = await sdk.conversations.listConversations(arbi);
   if (data.length === 0) {
-    console.log("No conversations found.");
+    process.stderr.write("No conversations found.\n");
     process.exit(0);
   }
   return promptSelect(
@@ -7618,17 +8356,17 @@ async function pickConversation(arbi, workspaceId, message = "Select conversatio
   );
 }
 function registerConversationsCommand(program2) {
-  const conv = program2.command("conversations").description("Manage conversations");
+  const conv = program2.command("convo").description("Conversations: list, switch, threads, delete, share, title, message, trace");
   conv.command("list").description("List conversations in the active workspace").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").option("--json", "Output as JSON").action(
     (opts) => runAction(async () => {
       const { arbi } = await resolveWorkspace(opts.workspace);
       const data = await sdk.conversations.listConversations(arbi);
       if (opts.json) {
-        console.log(JSON.stringify(data, null, 2));
+        printJson(data);
         return;
       }
       if (data.length === 0) {
-        console.log("No conversations found.");
+        process.stderr.write("No conversations found.\n");
         return;
       }
       printTable(
@@ -7650,8 +8388,39 @@ function registerConversationsCommand(program2) {
       console.log(JSON.stringify(data, null, 2));
     })()
   );
-  conv.command("delete [conversation-id]").description("Delete a conversation (interactive picker if no ID given)").action(
+  conv.command("switch <conversation-id>").description(
+    "Continue a previous conversation \u2014 next `arbi ask` resumes from its latest message"
+  ).action(
     (conversationId) => runAction(async () => {
+      const { arbi, workspaceId } = await resolveWorkspace();
+      const data = await sdk.conversations.getConversationThreads(arbi, conversationId);
+      const threads = data.threads ?? [];
+      if (threads.length === 0) {
+        process.stderr.write(`Conversation ${conversationId} has no threads.
+`);
+        process.exit(3);
+      }
+      const primary = threads[0];
+      const leafId = primary.leaf_message_ext_id;
+      const lastAssistant = [...primary.history ?? []].reverse().find((m) => m.role === "assistant");
+      const resumeId = leafId ?? lastAssistant?.external_id;
+      if (!resumeId) {
+        process.stderr.write(
+          `No resumable message in conversation ${conversationId}. (Empty thread or never reached an assistant turn.)
+`
+        );
+        process.exit(3);
+      }
+      updateChatSession({
+        conversationExtId: conversationId,
+        lastMessageExtId: resumeId,
+        workspaceId
+      });
+      success(`Switched to conversation ${conversationId} (resume from ${resumeId}).`);
+    })()
+  );
+  conv.command("delete [conversation-id]").description("Delete a conversation (interactive picker if no ID given)").option("--dry-run", "Preview which conversation would be deleted (no SDK call)").action(
+    (conversationId, opts) => runAction(async () => {
       const { arbi, workspaceId } = await resolveWorkspace();
       if (!conversationId)
         conversationId = await pickConversation(
@@ -7659,6 +8428,10 @@ function registerConversationsCommand(program2) {
           workspaceId,
           "Select conversation to delete"
         );
+      if (opts?.dryRun) {
+        dryRun("delete conversation", conversationId);
+        return;
+      }
       const data = await sdk.conversations.deleteConversation(arbi, conversationId);
       success(data?.detail ?? `Deleted conversation ${conversationId}`);
     })()
@@ -7681,11 +8454,18 @@ function registerConversationsCommand(program2) {
       success(data?.detail ?? `Updated title to: ${title}`);
     })()
   );
-  conv.command("message <message-id>").description("Get message details").action(
+  conv.command("message <message-id>").description("Get message details (full decrypted JSON, useful for debugging)").action(
     (messageId) => runAction(async () => {
       const { arbi } = await resolveWorkspace();
       const data = await sdk.conversations.getMessage(arbi, messageId);
-      console.log(JSON.stringify(data, null, 2));
+      printJson(data);
+    })()
+  );
+  conv.command("trace <message-id>").description("Decrypted execution trace for one agent response (alias for `message`)").action(
+    (messageId) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      const data = await sdk.conversations.getMessage(arbi, messageId);
+      printJson(data);
     })()
   );
   conv.command("delete-message <message-id>").description("Delete a message and its descendants").action(
@@ -7695,20 +8475,18 @@ function registerConversationsCommand(program2) {
       success(data?.detail ?? `Deleted message ${messageId}`);
     })()
   );
-  conv.option("--json", "Output as JSON").option("-w, --workspace <id>", "Workspace ID (defaults to selected workspace)").action(async (opts, cmd) => {
-    const args = [];
-    if (opts.json) args.push("--json");
-    if (opts.workspace) args.push("-w", opts.workspace);
-    await cmd.commands.find((c) => c.name() === "list").parseAsync(args, { from: "user" });
+  conv.allowUnknownOption(true).allowExcessArguments(true).action(async () => {
+    const tail = conv.args ?? [];
+    await conv.commands.find((c) => c.name() === "list").parseAsync(tail, { from: "user" });
   });
 }
 function registerSettingsCommand(program2) {
-  const settings = program2.command("settings").description("Manage user settings");
+  const settings = program2.command("settings").description("User settings: get, set");
   settings.command("get").description("Show current user settings (always JSON; --json accepted for consistency)").option("--json", "Output as JSON (default \u2014 always JSON)").action(
     () => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.settings.getSettings(arbi);
-      console.log(JSON.stringify(data, null, 2));
+      printJson(data);
     })()
   );
   settings.command("set <json>").description("Update user settings (pass JSON object)").action(
@@ -7723,6 +8501,7 @@ function registerSettingsCommand(program2) {
     await settings.commands.find((c) => c.name() === "get").parseAsync([], { from: "user" });
   });
 }
+init_prompts();
 var MODEL_SECTIONS = [
   "Agents",
   "QueryLLM",
@@ -7866,7 +8645,7 @@ async function buildConfigInteractively(arbi) {
   return body;
 }
 function registerAgentconfigCommand(program2) {
-  const ac = program2.command("agentconfig").description("Manage agent configurations");
+  const ac = program2.command("agentconfig").description("Agent configurations: list, get, save, delete, schema");
   ac.command("list").description("List saved configuration versions").action(
     runAction(async () => {
       const { arbi } = await resolveAuth();
@@ -8013,12 +8792,29 @@ function registerTuiCommand(program2) {
   });
 }
 function registerUpdateCommand(program2) {
-  const update = program2.command("update").description("Update ARBI CLI to the latest version").action(() => {
+  const update = program2.command("update").description("Update ARBI CLI to the latest version (use --check to only probe)").option("--check", "Only report whether an update is available \u2014 never install anything").option("--json", "Output {current, latest, update_available} as JSON (implies --check)").action((opts) => {
     const current = getCurrentVersion();
-    label("Current version:", current);
-    console.log("Checking for updates...\n");
+    const checkOnly = Boolean(opts.check || opts.json);
+    if (!checkOnly) {
+      label("Current version:", current);
+      console.log("Checking for updates...\n");
+    }
     try {
       const latest = getLatestVersion(true) || child_process.execSync("npm view @arbidocs/cli version", { encoding: "utf8" }).trim();
+      if (checkOnly) {
+        const updateAvailable = latest !== current;
+        if (opts.json) {
+          printJson({ current, latest, update_available: updateAvailable });
+        } else if (updateAvailable) {
+          label("Current version:", current);
+          label("Latest version:", latest);
+          console.log("Update available. Run `arbi update` to install.");
+        } else {
+          label("Current version:", current);
+          success("Already up to date.");
+        }
+        process.exit(updateAvailable ? 1 : 0);
+      }
       if (latest === current) {
         success("Already up to date.");
         return;
@@ -8031,6 +8827,10 @@ function registerUpdateCommand(program2) {
 Updated to ${latest}.`);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
+      if (opts.json) {
+        printJson({ current, latest: null, update_available: null, error: msg });
+        process.exit(1);
+      }
       error(`Update failed: ${msg}`);
       error("\nYou can update manually with:");
       dim("  npm install -g @arbidocs/cli@latest");
@@ -8042,6 +8842,7 @@ Updated to ${latest}.`);
     success("Auto-update enabled. ARBI CLI will update automatically on login.");
   });
 }
+init_prompts();
 function isExitPromptError(err) {
   return err instanceof Error && err.name === "ExitPromptError";
 }
@@ -8215,7 +9016,9 @@ async function getVerificationCode2(email, apiKey) {
   return Array.isArray(words) ? words.join(" ") : String(words);
 }
 function registerAgentCreateCommand(program2) {
-  program2.command("agent-create").description("Create a bot/test account (requires SUPPORT_API_KEY)").argument("[url]", "Server URL (auto-detected if omitted)").option("-p, --password <password>", "Account password", DEFAULT_PASSWORD).option("--workspace-name <name>", "Workspace name", "Agent Workspace").option("--email <email>", "Custom email (default: agent-{timestamp}@{domain})").action(
+  program2.command("agent-create").description(
+    "Create a standalone bot/test ACCOUNT via SUPPORT_API_KEY (different from `arbi agent create`, which makes a child agent under the current user)"
+  ).argument("[url]", "Server URL (auto-detected if omitted)").option("-p, --password <password>", "Account password", DEFAULT_PASSWORD).option("--workspace-name <name>", "Workspace name", "Agent Workspace").option("--email <email>", "Custom email (default: agent-{timestamp}@{domain})").action(
     async (url, opts) => {
       const { config, source } = store.resolveConfigWithFallbacks();
       if (url) {
@@ -8306,6 +9109,7 @@ function registerAgentCreateCommand(program2) {
     }
   );
 }
+init_prompts();
 function generatePassword() {
   const chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_";
   const bytes = new Uint8Array(20);
@@ -8313,8 +9117,12 @@ function generatePassword() {
   return Array.from(bytes, (b) => chars[b % chars.length]).join("");
 }
 function registerAgentCommand(program2) {
-  const agent = program2.command("agent").description("Manage persistent agents");
-  agent.command("create").description("Create a persistent agent with its own login credentials").option("--name <name>", "Agent name (letters, digits, hyphens, underscores)").option("-w, --workspace <ids...>", "Workspace IDs to share with the agent").option("--role <role>", "Workspace role: collaborator or guest", "collaborator").action(
+  const agent = program2.command("agent").description(
+    "Child agents under your user: list, create, delete (for SUPPORT_API_KEY bot accounts, use `arbi agent-create`)"
+  );
+  agent.command("create").description(
+    "Create a child persistent agent owned by the current user (different from `arbi agent-create`, which is a SUPPORT_API_KEY bot-account flow)"
+  ).option("--name <name>", "Agent name (letters, digits, hyphens, underscores)").option("-w, --workspace <ids...>", "Workspace IDs to share with the agent").option("--role <role>", "Workspace role: collaborator or guest", "collaborator").action(
     (opts) => runAction(async () => {
       const { arbi, loginResult } = await resolveAuth();
       const config = resolveConfig();
@@ -8390,12 +9198,16 @@ function registerAgentCommand(program2) {
       dim(`On the agent machine: arbi login --email ${agent2.email} --password <password>`);
     })()
   );
-  agent.command("list").description("List your persistent agents").action(
-    runAction(async () => {
+  agent.command("list").description("List your persistent agents").option("--json", "Output as JSON (recommended for scripting / agents)").action(
+    (opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.agents.listAgents(arbi);
+      if (opts?.json) {
+        printJson(data);
+        return;
+      }
       if (data.length === 0) {
-        console.log("No agents found.");
+        process.stderr.write("No agents found.\n");
         return;
       }
       printTable(
@@ -8410,17 +9222,18 @@ function registerAgentCommand(program2) {
         ],
         data
       );
-    })
+    })()
   );
-  agent.command("delete [agent-id]").description("Delete a persistent agent (picker if no ID)").action(
-    (agentId) => runAction(async () => {
+  agent.command("delete [agent-id]").description("Delete a persistent agent (picker if no ID)").option("-y, --yes", "Skip confirmation (required in non-TTY shells)").option("--dry-run", "Preview which agent would be deleted (no SDK call)").action(
+    (agentId, opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       if (!agentId) {
         const data = await sdk.agents.listAgents(arbi);
         if (data.length === 0) {
-          console.log("No agents to delete.");
+          process.stderr.write("No agents to delete.\n");
           return;
         }
+        requireInteractive("Pass <agent-id> directly: arbi agent delete <id>");
         agentId = await promptSelect(
           "Select agent to delete",
           data.map((a) => ({
@@ -8429,16 +9242,30 @@ function registerAgentCommand(program2) {
           }))
         );
       }
-      const confirmed = await promptConfirm(`Delete agent ${agentId}?`, false);
-      if (!confirmed) {
-        console.log("Cancelled.");
+      if (opts?.dryRun) {
+        dryRun("delete agent", agentId);
         return;
       }
+      if (!opts?.yes) {
+        requireInteractive("Pass -y/--yes to confirm in non-TTY shells.");
+        const confirmed = await promptConfirm(`Delete agent ${agentId}?`, false);
+        if (!confirmed) {
+          console.log("Cancelled.");
+          return;
+        }
+      }
       await sdk.agents.deleteAgents(arbi, [agentId]);
       success(`Agent ${agentId} deleted.`);
     })()
   );
-  agent.action(async () => {
+  agent.arguments("[maybeSubcommand]").action(async (maybe) => {
+    if (maybe) {
+      suggestSubcommandAndExit(
+        "agent",
+        maybe,
+        agent.commands.map((c) => c.name())
+      );
+    }
     await agent.commands.find((c) => c.name() === "list").parseAsync([], { from: "user" });
   });
 }
@@ -8465,15 +9292,33 @@ function statusColor2(s) {
   return s;
 }
 function registerTaskCommand(program2) {
-  const task = program2.command("task").description("Manage background tasks");
-  task.action(async (_opts, cmd) => {
-    await cmd.commands.find((c) => c.name() === "list").parseAsync([], { from: "user" });
+  const task = program2.command("task").description("Background tasks (from `arbi ask -b`): list, status, result");
+  task.arguments("[maybeSubcommand]").action(async (maybe) => {
+    if (maybe) {
+      suggestSubcommandAndExit(
+        "task",
+        maybe,
+        task.commands.map((c) => c.name())
+      );
+    }
+    await task.commands.find((c) => c.name() === "list").parseAsync([], { from: "user" });
   });
-  task.command("list").description("List background tasks").action(
-    () => runAction(async () => {
+  task.command("list").description("List background tasks").option("--json", "Output as JSON (recommended for scripting / agents)").action(
+    (opts) => runAction(async () => {
       const tasks = getTasks();
+      if (opts?.json) {
+        const out = tasks.map((t) => ({
+          id: t.id,
+          status: t.status,
+          question: t.question,
+          age_seconds: Math.round((Date.now() - new Date(t.submittedAt).getTime()) / 1e3),
+          submitted_at: t.submittedAt
+        }));
+        printJson(out);
+        return;
+      }
       if (tasks.length === 0) {
-        console.log('No tasks. Submit one with: arbi ask -b "your question"');
+        process.stderr.write('No tasks. Submit one with: arbi ask -b "your question"\n');
         return;
       }
       printTable(
@@ -8556,8 +9401,8 @@ compdef _arbi_completions arbi
 ${MARKER_END}`;
 function getShellRcPath2() {
   const shell = process.env.SHELL || "";
-  if (shell.includes("zsh")) return path5.join(os.homedir(), ".zshrc");
-  return path5.join(os.homedir(), ".bashrc");
+  if (shell.includes("zsh")) return path5.join(os2.homedir(), ".zshrc");
+  return path5.join(os2.homedir(), ".bashrc");
 }
 function isZsh() {
   return (process.env.SHELL || "").includes("zsh");
@@ -8576,7 +9421,7 @@ function removeCompletionBlock(content) {
   return before + after;
 }
 function registerCompletionCommand(program2) {
-  const completion = program2.command("completion").description("Manage shell tab completion");
+  const completion = program2.command("completion").description("Shell tab completion: install, uninstall, refresh");
   completion.command("install").description("Install shell tab completion (auto-detects bash or zsh \u2014 no shell arg needed)").action(() => {
     const rcPath = getShellRcPath2();
     if (isCompletionInstalled(rcPath)) {
@@ -8614,7 +9459,7 @@ function registerCompletionCommand(program2) {
 }
 function resolvePath(p) {
   const raw = p ?? ".";
-  const expanded = raw.startsWith("~") ? raw.replace("~", os.homedir()) : raw;
+  const expanded = raw.startsWith("~") ? raw.replace("~", os2.homedir()) : raw;
   return path5.resolve(expanded);
 }
 function formatSize2(bytes) {
@@ -8623,9 +9468,20 @@ function formatSize2(bytes) {
   if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
   return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}G`;
 }
+function entryToRow(dir, name) {
+  try {
+    const stat = fs5.statSync(path5.join(dir, name));
+    if (stat.isDirectory()) return { name, type: "dir", size: null };
+    if (stat.isSymbolicLink()) return { name, type: "symlink", size: stat.size };
+    if (stat.isFile()) return { name, type: "file", size: stat.size };
+    return { name, type: "other", size: stat.size };
+  } catch {
+    return { name, type: "other", size: null };
+  }
+}
 function registerLocalCommand(program2) {
   const local = program2.command("local").description("Local filesystem operations");
-  local.command("ls [path]").description("List files in a directory").option("-l, --long", "Show file sizes and types").action((path7, opts) => {
+  local.command("ls [path]").description("List files in a directory").option("-l, --long", "Show file sizes and types (ignored when --json is set)").option("-a, --all", "Include dotfiles").option("--json", "Output as JSON array of {name, type, size}").action((path7, opts) => {
     const dir = resolvePath(path7);
     let entries;
     try {
@@ -8634,33 +9490,46 @@ function registerLocalCommand(program2) {
       console.error(`Cannot read directory: ${dir}`);
       process.exit(1);
     }
-    for (const entry of entries.filter((e) => !e.startsWith(".")).sort()) {
+    const sorted = entries.filter((e) => opts?.all || !e.startsWith(".")).sort();
+    if (opts?.json) {
+      const rows = sorted.map((name) => entryToRow(dir, name));
+      printJson(rows);
+      return;
+    }
+    for (const entry of sorted) {
       if (opts?.long) {
-        try {
-          const stat = fs5.statSync(path5.join(dir, entry));
-          const type = stat.isDirectory() ? "dir" : "file";
-          const size = stat.isFile() ? formatSize2(stat.size) : "-";
-          console.log(`${type.padEnd(5)} ${size.padStart(10)}  ${entry}`);
-        } catch {
-          console.log(`?     ${"-".padStart(10)}  ${entry}`);
-        }
+        const row = entryToRow(dir, entry);
+        const size = row.size !== null && row.type === "file" ? formatSize2(row.size) : "-";
+        console.log(`${row.type.padEnd(5)} ${size.padStart(10)}  ${entry}`);
       } else {
         console.log(entry);
       }
     }
   });
-  local.command("find <pattern>").description('Find files matching a glob (e.g. "**/*.pdf")').option("-d, --dir <path>", "Directory to search in", ".").action((pattern, opts) => {
+  local.command("find <pattern>").description('Find files matching a glob (e.g. "**/*.pdf")').option("-d, --dir <path>", "Directory to search in", ".").option("--json", "Output as JSON array of matched paths").action((pattern, opts) => {
     const dir = resolvePath(opts.dir);
     const results = fs5.globSync(pattern, { cwd: dir });
+    if (opts.json) {
+      if (results.length === 0) {
+        process.stderr.write(`No files matching "${pattern}" in ${dir}
+`);
+      }
+      printJson(results);
+      return;
+    }
     if (results.length === 0) {
-      console.log(`No files matching "${pattern}" in ${dir}`);
+      process.stderr.write(`No files matching "${pattern}" in ${dir}
+`);
       return;
     }
     for (const file of results) {
       console.log(file);
     }
   });
-  local.command("cat <file>").description("Print file contents").option("--head <lines>", "Only show first N lines").action((file, opts) => {
+  local.command("cat <file>").description("Print file contents").option("--head <lines>", "Only show first N lines").option(
+    "--json",
+    "Output as {path, bytes, content} \u2014 useful when content has newlines an agent needs to handle"
+  ).action((file, opts) => {
     const filePath = resolvePath(file);
     let content;
     try {
@@ -8671,18 +9540,51 @@ function registerLocalCommand(program2) {
     }
     if (opts.head) {
       const n = parseInt(opts.head, 10);
-      console.log(content.split("\n").slice(0, n).join("\n"));
-    } else {
-      console.log(content);
+      content = content.split("\n").slice(0, n).join("\n");
     }
+    if (opts.json) {
+      printJson({ path: filePath, bytes: Buffer.byteLength(content, "utf-8"), content });
+      return;
+    }
+    console.log(content);
   });
-  local.command("tree [path]").description("Show directory tree").option("-d, --depth <n>", "Maximum depth", "3").action((path7, opts) => {
+  local.command("tree [path]").description("Show directory tree").option("-d, --depth <n>", "Maximum depth", "3").option("--json", "Output as nested {name, type, children} tree").action((path7, opts) => {
     const dir = resolvePath(path7);
     const maxDepth = parseInt(opts?.depth ?? "3", 10);
+    if (opts?.json) {
+      printJson(buildTree(dir, maxDepth, 0));
+      return;
+    }
     console.log(path5.basename(dir) + "/");
     printTree(dir, "", maxDepth, 0);
   });
 }
+function buildTree(dir, maxDepth, depth) {
+  const node = { name: path5.basename(dir), type: "dir", children: [] };
+  if (depth >= maxDepth) return node;
+  let entries;
+  try {
+    entries = fs5.readdirSync(dir).filter((e) => !e.startsWith(".")).sort();
+  } catch {
+    return node;
+  }
+  for (const entry of entries) {
+    const full = path5.join(dir, entry);
+    let isDir = false;
+    try {
+      isDir = fs5.statSync(full).isDirectory();
+    } catch {
+      node.children.push({ name: entry, type: "other" });
+      continue;
+    }
+    if (isDir) {
+      node.children.push(buildTree(full, maxDepth, depth + 1));
+    } else {
+      node.children.push({ name: entry, type: "file" });
+    }
+  }
+  return node;
+}
 function printTree(dir, prefix, maxDepth, depth) {
   if (depth >= maxDepth) return;
   let entries;
@@ -8709,14 +9611,25 @@ function printTree(dir, prefix, maxDepth, depth) {
     }
   }
 }
+function humanizeTtl(seconds) {
+  if (!Number.isFinite(seconds) || seconds < 0) return "";
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
+  if (seconds < 86400) return `${Math.round(seconds / 3600)}h`;
+  return `${Math.round(seconds / 86400)}d`;
+}
 function registerSessionCommand(program2) {
   const session = program2.command("session").description("List and manage sessions");
-  session.command("list").description("List active sessions").action(
-    runAction(async () => {
+  session.command("list").description("List active sessions").option("--json", "Output as JSON (recommended for scripting / agents)").action(
+    (opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.sessions.listSessions(arbi);
+      if (opts?.json) {
+        printJson(data);
+        return;
+      }
       if (data.length === 0) {
-        console.log("No active sessions.");
+        process.stderr.write("No active sessions.\n");
         return;
       }
       printTable(
@@ -8728,7 +9641,13 @@ function registerSessionCommand(program2) {
           },
           { header: "NAME", width: 20, value: (r) => r.name || "" },
           { header: "STATUS", width: 12, value: (r) => r.status },
-          { header: "TTL", width: 10, value: (r) => `${r.ttl}s` },
+          {
+            header: "TTL",
+            width: 10,
+            // Raw `<n>s` was unreadable past a few hours; humanize once the
+            // window grows beyond a minute.
+            value: (r) => humanizeTtl(r.ttl)
+          },
           {
             header: "WORKSPACES",
             width: 12,
@@ -8737,12 +9656,423 @@ function registerSessionCommand(program2) {
         ],
         data
       );
-    })
+    })()
   );
-  session.action(async () => {
+  session.arguments("[maybeSubcommand]").action(async (maybe) => {
+    if (maybe) {
+      suggestSubcommandAndExit(
+        "session",
+        maybe,
+        session.commands.map((c) => c.name())
+      );
+    }
     await session.commands.find((c) => c.name() === "list").parseAsync([], { from: "user" });
   });
 }
+function registerNotificationsCommand(program2) {
+  const notif = program2.command("notifications").enablePositionalOptions().description("Non-DM notifications");
+  notif.command("list").description("List non-DM notifications (workspace invites, contact accepts, \u2026)").option("--unread", "Only show unread notifications").option("--type <comma-list>", "Filter to specific type(s), e.g. workspaceuser_invited").option("-l, --limit <n>", "Cap to N most-recent", (v) => parseInt(v, 10)).option("--json", "Output as JSON (recommended for scripting / agents)").action(
+    (opts) => runAction(async () => {
+      const { arbi, crypto: crypto2 } = await resolveDmCrypto();
+      const all = await sdk.dm.listDecryptedDMs(arbi, crypto2);
+      const nonDm = all.filter((r) => r.type !== "user_message");
+      const typeFilter = opts.type ? new Set(
+        opts.type.split(",").map((t) => t.trim()).filter(Boolean)
+      ) : null;
+      const filtered = nonDm.filter((r) => {
+        if (opts.unread && r.read) return false;
+        if (typeFilter && !typeFilter.has(r.type ?? "")) return false;
+        return true;
+      });
+      const limited = opts.limit && opts.limit > 0 ? filtered.slice(0, opts.limit) : filtered;
+      if (opts.json) {
+        printJson(limited);
+        return;
+      }
+      if (limited.length === 0) {
+        process.stderr.write("No notifications.\n");
+        return;
+      }
+      printTable(
+        [
+          { header: "ID", width: 16, value: (r) => r.external_id },
+          { header: "TYPE", width: 24, value: (r) => r.type ?? "" },
+          { header: "READ", width: 6, value: (r) => r.read ? "yes" : "no" },
+          {
+            header: "CONTENT",
+            width: 50,
+            // Non-DM rows usually carry a JSON-encoded payload in
+            // `content`. Show the first slice and let the JSON path
+            // expose the full thing for agents that want to introspect.
+            value: (r) => truncate(r.content ?? "", 49)
+          }
+        ],
+        limited
+      );
+    })()
+  );
+  notif.command("mark-read [ids...]").description("Mark notifications as read (use --all to drain the unread queue)").option("--all", "Mark every unread non-DM notification as read").action(
+    (ids, opts) => runAction(async () => {
+      const { arbi, crypto: crypto2 } = await resolveDmCrypto();
+      let toMark = ids && ids.length > 0 ? ids : void 0;
+      if (!toMark && opts.all) {
+        const all = await sdk.dm.listDecryptedDMs(arbi, crypto2);
+        toMark = all.filter((r) => r.type !== "user_message" && !r.read).map((r) => r.external_id);
+      }
+      if (!toMark || toMark.length === 0) {
+        process.stderr.write("Nothing to mark read. (Pass IDs or --all.)\n");
+        return;
+      }
+      const data = await sdk.dm.markRead(arbi, toMark);
+      process.stdout.write(`Marked ${data.length} notification(s) as read.
+`);
+    })()
+  );
+  notif.command("delete [ids...]").description("Delete notifications by ID (or use --all to clear non-DM noise)").option("--all", "Delete every non-DM notification (workspace invites, contact accepts, ...)").option("--dry-run", "Preview which notifications would be deleted (no SDK call)").action(
+    (ids, opts) => runAction(async () => {
+      const { arbi, crypto: crypto2 } = await resolveDmCrypto();
+      let toDelete = ids && ids.length > 0 ? ids : void 0;
+      if (!toDelete && opts.all) {
+        const all = await sdk.dm.listDecryptedDMs(arbi, crypto2);
+        toDelete = all.filter((r) => r.type !== "user_message").map((r) => r.external_id);
+      }
+      if (!toDelete || toDelete.length === 0) {
+        process.stderr.write("Nothing to delete. (Pass IDs or --all.)\n");
+        return;
+      }
+      if (opts?.dryRun) {
+        dryRun(`delete ${toDelete.length} notification(s)`, toDelete);
+        return;
+      }
+      await sdk.dm.deleteDMs(arbi, toDelete);
+      process.stdout.write(`Deleted ${toDelete.length} notification(s).
+`);
+    })()
+  );
+  notif.allowUnknownOption(true).allowExcessArguments(true).action(async () => {
+    const tail = notif.args ?? [];
+    const subcommands = notif.commands.map((c) => c.name());
+    const firstNonFlag = tail.find((a) => !a.startsWith("-"));
+    if (firstNonFlag && !subcommands.includes(firstNonFlag)) {
+      suggestSubcommandAndExit("notifications", firstNonFlag, subcommands);
+    }
+    await notif.commands.find((c) => c.name() === "list").parseAsync(tail, { from: "user" });
+  });
+}
+function registerProjectCommand(program2) {
+  const project = program2.command("project").description("Project tenancy: list, create, refresh");
+  project.command("list").description("List your projects").option("--json", "Output as JSON").action(
+    (opts) => runAction(async () => {
+      const { arbi } = await resolveAuth();
+      const data = await sdk.projects.listProjects(arbi);
+      if (!emitListOrTable(data, opts, "No projects found.")) return;
+      printTable(
+        [
+          { header: "ID", width: 18, value: (r) => r.external_id },
+          { header: "NAME", width: 30, value: (r) => r.name ?? "" },
+          { header: "PLAN", width: 14, value: (r) => r.plan ?? "" },
+          { header: "ROLE", width: 14, value: (r) => r.role ?? "" }
+        ],
+        data
+      );
+    })()
+  );
+  project.command("create <name>").description("Create a new project").action(
+    (name) => runAction(async () => {
+      const { arbi } = await resolveAuth();
+      const data = await sdk.projects.createProject(arbi, name);
+      success(`Created project: ${data.name} (${ref(data.external_id)})`);
+    })()
+  );
+  project.command("refresh <id>").description("Refresh a project (force plan/usage sync from billing)").action(
+    (id) => runAction(async () => {
+      const { arbi } = await resolveAuth();
+      await sdk.projects.refreshProject(arbi, id);
+      success(`Refreshed project: ${ref(id)}`);
+    })()
+  );
+  project.allowUnknownOption(true).allowExcessArguments(true).action(async () => {
+    const tail = project.args ?? [];
+    const subcommands = project.commands.map((c) => c.name());
+    const firstNonFlag = tail.find((a) => !a.startsWith("-"));
+    if (firstNonFlag && !subcommands.includes(firstNonFlag)) {
+      suggestSubcommandAndExit("project", firstNonFlag, subcommands);
+    }
+    await project.commands.find((c) => c.name() === "list").parseAsync(tail, { from: "user" });
+  });
+}
+function formatBytes(n) {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}K`;
+  if (n < 1024 * 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)}M`;
+  return `${(n / (1024 * 1024 * 1024)).toFixed(1)}G`;
+}
+function registerFilesCommand(program2) {
+  const files = program2.command("files").description("Ephemeral files: list, upload, get, delete, fetch content");
+  files.command("list").description("List ephemeral files attached to your account").option("--purpose <name>", "Filter by purpose (default: assistants)").option("-l, --limit <n>", "Cap to N entries", (v) => parseInt(v, 10)).option("--json", "Output as JSON").action(
+    (opts) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      const data = await sdk.files.listFiles(arbi, {
+        purpose: opts.purpose ?? null,
+        limit: opts.limit
+      });
+      const items = data.data ?? [];
+      if (opts.json) {
+        printJson(data);
+        return;
+      }
+      if (!emitListOrTable(items, opts, "No files found.")) return;
+      printTable(
+        [
+          { header: "ID", width: 30, value: (r) => r.id },
+          {
+            header: "NAME",
+            width: 30,
+            value: (r) => truncate(r.filename ?? "", 29)
+          },
+          { header: "BYTES", width: 10, value: (r) => formatBytes(r.bytes ?? 0) },
+          { header: "PURPOSE", width: 14, value: (r) => r.purpose ?? "" }
+        ],
+        items
+      );
+    })()
+  );
+  files.command("upload <path>").description("Upload a file (file ID is returned for use with arbi ask -b --attach)").option("--purpose <name>", "OpenAI purpose tag (default: assistants)", "assistants").action(
+    (path7, opts) => runAction(async () => {
+      const { arbi, loginResult } = await resolveWorkspace();
+      const filePath = path5.resolve(path7);
+      let bytes;
+      try {
+        bytes = fs5.readFileSync(filePath);
+      } catch {
+        error(`Cannot read file: ${filePath}`);
+        process.exit(3);
+      }
+      const blob = new Blob([new Uint8Array(bytes)]);
+      const data = await sdk.files.uploadFile(
+        {
+          baseUrl: arbi.fetch.baseUrl,
+          accessToken: loginResult.accessToken
+        },
+        blob,
+        path5.basename(filePath),
+        opts.purpose ?? "assistants"
+      );
+      success(`Uploaded: ${ref(data.id)} (${formatBytes(data.bytes ?? 0)})`);
+    })()
+  );
+  files.command("get <id>").description("Show a file's metadata (always JSON \u2014 the metadata IS the data)").action(
+    (id) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      const data = await sdk.files.getFile(arbi, id);
+      printJson(data);
+    })()
+  );
+  files.command("delete <id>").description("Delete an ephemeral file").option("--dry-run", "Preview which file would be deleted (no SDK call)").action(
+    (id, opts) => runAction(async () => {
+      if (opts?.dryRun) {
+        dryRun("delete file", id);
+        return;
+      }
+      const { arbi } = await resolveWorkspace();
+      await sdk.files.deleteFile(arbi, id);
+      success(`Deleted: ${ref(id)}`);
+    })()
+  );
+  files.command("content <id>").description("Fetch a file's raw bytes (writes to disk or stdout)").option("-o, --output <path>", 'Output file path (use "-" for stdout)').action(
+    (id, opts) => runAction(async () => {
+      const { arbi, loginResult } = await resolveWorkspace();
+      const res = await sdk.files.getFileContent(
+        {
+          baseUrl: arbi.fetch.baseUrl,
+          accessToken: loginResult.accessToken
+        },
+        id
+      );
+      const buf = Buffer.from(await res.arrayBuffer());
+      if (!opts.output || opts.output === "-") {
+        process.stdout.write(buf);
+        return;
+      }
+      fs5.writeFileSync(path5.resolve(opts.output), buf);
+      success(`Wrote ${formatBytes(buf.length)} \u2192 ${opts.output}`);
+    })()
+  );
+  files.allowUnknownOption(true).allowExcessArguments(true).action(async () => {
+    const tail = files.args ?? [];
+    const subcommands = files.commands.map((c) => c.name());
+    const firstNonFlag = tail.find((a) => !a.startsWith("-"));
+    if (firstNonFlag && !subcommands.includes(firstNonFlag)) {
+      suggestSubcommandAndExit("files", firstNonFlag, subcommands);
+    }
+    await files.commands.find((c) => c.name() === "list").parseAsync(tail, { from: "user" });
+  });
+}
+
+// src/commands/usage.ts
+function registerUsageCommand(program2) {
+  const usage = program2.command("usage").description("Show today's usage against the daily cap");
+  usage.command("today").description("Today's tokens used / remaining (for the current user)").option("--json", "Output as JSON").action(
+    (opts) => runAction(async () => {
+      const { arbi } = await resolveAuth();
+      const res = await arbi.fetch.GET("/v1/user/me/usage/today");
+      if (res.error) {
+        throw new Error(`Failed to fetch usage: ${JSON.stringify(res.error)}`);
+      }
+      const data = res.data;
+      if (opts.json) {
+        printJson(data);
+        return;
+      }
+      for (const [k, v] of Object.entries(data)) {
+        label(`${k}:`, typeof v === "object" ? JSON.stringify(v) : String(v));
+      }
+      dim("\nPass --json for machine-readable output.");
+    })()
+  );
+  usage.allowUnknownOption(true).allowExcessArguments(true).action(async () => {
+    const tail = usage.args ?? [];
+    const subcommands = usage.commands.map((c) => c.name());
+    const firstNonFlag = tail.find((a) => !a.startsWith("-"));
+    if (firstNonFlag && !subcommands.includes(firstNonFlag)) {
+      suggestSubcommandAndExit("usage", firstNonFlag, subcommands);
+    }
+    await usage.commands.find((c) => c.name() === "today").parseAsync(tail, { from: "user" });
+  });
+}
+init_prompts();
+function registerAuthCommand(program2) {
+  const auth = program2.command("auth").description("Self-service account ops: profile, change-email, delete-account, sso-config");
+  auth.command("profile").description("Show or update your display profile (given/family name, picture)").option("--name <given>", "New given name").option("--family <family>", "New family name (empty string clears it)").option(
+    "--picture <path-or-url>",
+    "Profile picture (local path \u2192 base64 inline; URL \u2192 stored verbatim)"
+  ).action(
+    (opts) => runAction(async () => {
+      const { arbi } = await resolveAuth();
+      const noUpdates = !opts.name && opts.family === void 0 && !opts.picture;
+      if (noUpdates) {
+        const myExtId = arbi.session.getState().userExtId;
+        const res2 = await arbi.fetch.GET("/v1/workspace/users");
+        if (res2.error || !res2.data) {
+          error(
+            "No profile-read endpoint exists. To inspect: arbi status --json or arbi contacts --json"
+          );
+          process.exit(1);
+        }
+        const me = res2.data.find(
+          (u) => u.external_id === myExtId
+        );
+        const profile = me ?? { external_id: myExtId };
+        for (const [k, v] of Object.entries(profile)) {
+          label(`${k}:`, typeof v === "object" ? JSON.stringify(v) : String(v));
+        }
+        dim("\nPass --name/--family/--picture to update.");
+        return;
+      }
+      let picture = opts.picture;
+      if (picture && !/^https?:|^data:/.test(picture)) {
+        try {
+          const bytes = fs5.readFileSync(path5.resolve(picture));
+          const ext = picture.toLowerCase().split(".").pop();
+          const mime = ext === "png" ? "image/png" : ext === "gif" ? "image/gif" : "image/jpeg";
+          picture = `data:${mime};base64,${bytes.toString("base64")}`;
+        } catch {
+          error(`Cannot read picture file: ${picture}`);
+          process.exit(3);
+        }
+      }
+      const body = {};
+      if (opts.name !== void 0) body.given_name = opts.name;
+      if (opts.family !== void 0) body.family_name = opts.family;
+      if (picture !== void 0) body.picture = picture;
+      const res = await arbi.fetch.PATCH("/v1/user/profile", { body });
+      if (res.error) throw new Error(`Profile update failed: ${JSON.stringify(res.error)}`);
+      success("Profile updated.");
+    })()
+  );
+  auth.command("change-email <new-email>").description("Request a verification code for an email change (SSO users update at IdP)").action(
+    (newEmail) => runAction(async () => {
+      const { arbi } = await resolveAuth();
+      const res = await arbi.fetch.POST("/v1/user/request-email-change", {
+        body: { new_email: newEmail }
+      });
+      if (res.error) throw new Error(`request-email-change failed: ${JSON.stringify(res.error)}`);
+      success(`Verification code sent to ${newEmail}.`);
+      dim(`Confirm with: arbi auth confirm-email <code>`);
+    })()
+  );
+  auth.command("confirm-email <code>").description("Confirm an email change with the code from change-email").option("--new-email <email>", "The new email being confirmed (required)").action(
+    (code, opts) => runAction(async () => {
+      if (!opts.newEmail) {
+        error("Missing --new-email. The new address is required to complete the change.");
+        process.exit(1);
+      }
+      const { arbi } = await resolveAuth();
+      const res = await arbi.fetch.POST("/v1/user/confirm-email-change", {
+        body: { new_email: opts.newEmail, verification_code: code }
+      });
+      if (res.error) throw new Error(`confirm-email-change failed: ${JSON.stringify(res.error)}`);
+      success(`Email changed to ${opts.newEmail}.`);
+    })()
+  );
+  auth.command("delete-account").description("Request account deletion (30-day grace window \u2014 use cancel-deletion to undo)").option("-y, --yes", "Skip confirmation (required in non-TTY shells)").option("--dry-run", "Preview the deletion request (no SDK call)").action(
+    (opts) => runAction(async () => {
+      const { arbi } = await resolveAuth();
+      if (opts.dryRun) {
+        const email = arbi.session.getState().userExtId ?? "(unknown)";
+        dryRun("request account deletion (30-day grace)", email);
+        return;
+      }
+      if (!opts.yes) {
+        requireInteractive("Pass -y/--yes to confirm in non-TTY shells.");
+        const confirmed = await promptConfirm(
+          "Request deletion of this account (30-day grace)?",
+          false
+        );
+        if (!confirmed) {
+          console.log("Cancelled.");
+          return;
+        }
+      }
+      const res = await arbi.fetch.POST("/v1/user/request-deletion", { body: {} });
+      if (res.error) throw new Error(`request-deletion failed: ${JSON.stringify(res.error)}`);
+      success("Deletion requested. You have 30 days to cancel with: arbi auth cancel-deletion");
+    })()
+  );
+  auth.command("cancel-deletion").description("Cancel an in-flight account deletion request").action(
+    () => runAction(async () => {
+      const { arbi } = await resolveAuth();
+      const res = await arbi.fetch.POST("/v1/user/cancel-deletion", { body: {} });
+      if (res.error) throw new Error(`cancel-deletion failed: ${JSON.stringify(res.error)}`);
+      success("Deletion cancelled. Account is active.");
+    })()
+  );
+  auth.command("sso-config").description("Show SSO config for this deployment (sso_enabled, Auth0 domain, audience)").option("--json", "Output as JSON").action(
+    (opts) => runAction(async () => {
+      const { arbi } = await resolveAuth();
+      const res = await arbi.fetch.GET("/v1/user/sso-config");
+      if (res.error) throw new Error(`sso-config failed: ${JSON.stringify(res.error)}`);
+      if (opts.json) {
+        printJson(res.data);
+        return;
+      }
+      for (const [k, v] of Object.entries(res.data)) {
+        label(`${k}:`, typeof v === "object" ? JSON.stringify(v) : String(v));
+      }
+      dim("\nTo log in: arbi login --sso -e <email> -p <master-password>");
+      dim("(--sso still needs --password \u2014 the master password is the E2E key seed.)");
+    })()
+  );
+  auth.allowUnknownOption(true).allowExcessArguments(true).action(async () => {
+    const tail = auth.args ?? [];
+    const subcommands = auth.commands.map((c) => c.name());
+    const firstNonFlag = tail.find((a) => !a.startsWith("-"));
+    if (firstNonFlag && !subcommands.includes(firstNonFlag)) {
+      suggestSubcommandAndExit("auth", firstNonFlag, subcommands);
+    }
+    await auth.commands.find((c) => c.name() === "profile").parseAsync(tail, { from: "user" });
+  });
+}
 
 // src/index.ts
 console.debug = () => {
@@ -8753,7 +10083,7 @@ console.info = (...args) => {
   _origInfo(...args);
 };
 var program = new commander.Command();
-program.name("arbi").description("ARBI CLI \u2014 interact with ARBI from the terminal").version("0.3.62");
+program.name("arbi").description("ARBI CLI \u2014 interact with ARBI from the terminal").version("0.3.64").showHelpAfterError(true).showSuggestionAfterError(true);
 registerConfigCommand(program);
 registerLoginCommand(program);
 registerRegisterCommand(program);
@@ -8785,6 +10115,41 @@ registerCompletionCommand(program);
 registerListenCommand(program);
 registerSessionCommand(program);
 registerLocalCommand(program);
+registerNotificationsCommand(program);
+registerProjectCommand(program);
+registerFilesCommand(program);
+registerUsageCommand(program);
+registerAuthCommand(program);
+applyHelpGroups(program, {
+  "Getting started:": [
+    "quickstart",
+    "login",
+    "register",
+    "logout",
+    "status",
+    "config",
+    "completion"
+  ],
+  "Workspaces:": ["workspaces", "workspace", "project"],
+  "Documents:": ["docs", "doc", "add", "upload", "download"],
+  "Search & ask:": ["ask", "find", "cite", "watch"],
+  "Tagging:": ["tags", "doctags"],
+  "Conversations & messaging:": ["convo", "dm", "listen", "notifications", "contacts"],
+  "Agents & tasks:": ["agent", "agent-create", "task", "agentconfig", "session"],
+  "Account:": ["auth", "usage", "files"],
+  "System:": ["health", "models", "settings", "tui", "local", "update"]
+});
+function applyHelpGroups(prog, groups) {
+  for (const [groupLabel, names] of Object.entries(groups)) {
+    for (const name of names) {
+      const cmd = prog.commands.find((c) => c.name() === name);
+      const hg = cmd?.helpGroup;
+      if (cmd && typeof hg === "function") {
+        hg.call(cmd, groupLabel);
+      }
+    }
+  }
+}
 var completionIdx = process.argv.indexOf("--get-completions");
 if (completionIdx !== -1) {
   const line = process.argv[completionIdx + 1] ?? "";