@arbidocs/cli 0.4.75 → 0.4.77

package/dist/index.js

@@ -12,6 +12,7 @@ var child_process = require('child_process');
 var client = require('@arbidocs/client');
 var url = require('url');
 var crypto = require('crypto');
+var yaml = require('yaml');
 var module$1 = require('module');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -3694,7 +3695,7 @@ function getLatestVersion(skipCache = false) {
   }
 }
 function getCurrentVersion() {
-  return "0.4.75";
+  return "0.4.77";
 }
 function readChangelog(fromVersion, toVersion) {
   try {
@@ -3747,17 +3748,17 @@ function showChangelog(fromVersion, toVersion) {
 async function checkForUpdates(autoUpdate) {
   try {
     const latest = getLatestVersion();
-    if (!latest || latest === "0.4.75") return;
+    if (!latest || latest === "0.4.77") return;
     if (autoUpdate) {
       warn(`
-Your arbi version is out of date (${"0.4.75"} \u2192 ${latest}). Updating...`);
+Your arbi version is out of date (${"0.4.77"} \u2192 ${latest}). Updating...`);
       child_process.execSync("npm install -g @arbidocs/cli@latest", { stdio: "inherit" });
-      showChangelog("0.4.75", latest);
+      showChangelog("0.4.77", latest);
       console.log(`Updated to ${latest}.`);
     } else {
       warn(
         `
-Your arbi version is out of date (${"0.4.75"} \u2192 ${latest}).
+Your arbi version is out of date (${"0.4.77"} \u2192 ${latest}).
 Run "arbi update" to upgrade, or "arbi update auto" to always stay up to date.`
       );
     }
@@ -3789,10 +3790,10 @@ function markNagShown(latest) {
 function hintUpdateOnError() {
   try {
     const cached = readCache();
-    if (!cached || cached.latest === "0.4.75") return;
+    if (!cached || cached.latest === "0.4.77") return;
     if (!shouldShowNag(cached.latest)) return;
     warn(
-      `Your arbi version is out of date (${"0.4.75"} \u2192 ${cached.latest}). Run "arbi update".`
+      `Your arbi version is out of date (${"0.4.77"} \u2192 ${cached.latest}). Run "arbi update".`
     );
     markNagShown(cached.latest);
   } catch {
@@ -3963,6 +3964,10 @@ function stringifyApiDetail(value) {
     const rec = value;
     if (typeof rec.detail === "string") return rec.detail;
     if (Array.isArray(rec.detail)) return stringifyApiDetail(rec.detail);
+    if (rec.fields && typeof rec.fields === "object" && !Array.isArray(rec.fields)) {
+      const fields = Object.entries(rec.fields).map(([name, problem]) => `${name}: ${String(problem)}`).join("; ");
+      return typeof rec.message === "string" ? `${rec.message} (${fields})` : fields;
+    }
     if (typeof rec.message === "string") return rec.message;
     if (typeof rec.error === "string") return rec.error;
     try {
@@ -6322,10 +6327,10 @@ function registerDocsCommand(program2) {
       if (!opts.quiet && statusIntervalMs > 0) {
         statusTimer = setInterval(() => printStatus("  "), statusIntervalMs);
       }
-      const sleep = (ms) => new Promise((resolve6) => setTimeout(resolve6, ms));
+      const sleep2 = (ms) => new Promise((resolve6) => setTimeout(resolve6, ms));
       const backoff = async (attempt) => {
         const delayMs = Math.min(1e3 * Math.pow(2, attempt), 3e4);
-        await sleep(delayMs);
+        await sleep2(delayMs);
       };
       const submitBatch = async (batchIds) => {
         const updates = batchIds.map((id) => ({
@@ -6437,12 +6442,12 @@ function registerDocsCommand(program2) {
               }
               submitted += 1;
               if (intervalMs > 0 && j < batch.length - 1) {
-                await sleep(intervalMs);
+                await sleep2(intervalMs);
               }
             }
           }
           if (intervalMs > 0 && i + batchSize < docIds.length) {
-            await sleep(intervalMs);
+            await sleep2(intervalMs);
           }
         }
       } finally {
@@ -6520,19 +6525,19 @@ Processing complete: completed=${procCompleted} failed=0  elapsed=${totalElapsed
 }
 
 // src/commands/upload-shared.ts
-function printSummary(summary) {
+function printSummary(summary2) {
   console.log("");
   console.log("Upload summary:");
-  console.log(`  Files found:  ${summary.totalFiles}`);
-  success(`  Uploaded:     ${summary.uploaded}`);
-  if (summary.skipped > 0) {
-    warn(`  Skipped:      ${summary.skipped}`);
+  console.log(`  Files found:  ${summary2.totalFiles}`);
+  success(`  Uploaded:     ${summary2.uploaded}`);
+  if (summary2.skipped > 0) {
+    warn(`  Skipped:      ${summary2.skipped}`);
   }
-  console.log(`  Folders:      ${summary.folders}`);
-  if (summary.skippedDetails.length > 0) {
+  console.log(`  Folders:      ${summary2.folders}`);
+  if (summary2.skippedDetails.length > 0) {
     console.log("");
     warn("Skipped files:");
-    for (const s of summary.skippedDetails) {
+    for (const s of summary2.skippedDetails) {
       warn(`  ${s.file_name}: ${s.reason}`);
     }
   }
@@ -6550,10 +6555,10 @@ function countSupportedFiles(dirPath) {
   }
   return count;
 }
-function mergeBatchResult(summary, uploadedDocs, result, sourceLabel, opts) {
+function mergeBatchResult(summary2, uploadedDocs, result, sourceLabel, opts) {
   for (const [folder, info] of result.folders) {
-    summary.folders += 1;
-    summary.totalFiles += info.fileCount;
+    summary2.folders += 1;
+    summary2.totalFiles += info.fileCount;
     if (!opts.json) {
       success(
         `  ${folder || "<root>"}: ${info.fileCount} file(s) \u2192 ${info.doc_ext_ids.length} uploaded`
@@ -6564,10 +6569,10 @@ function mergeBatchResult(summary, uploadedDocs, result, sourceLabel, opts) {
     }
     for (const docId of info.doc_ext_ids) uploadedDocs.set(docId, sourceLabel);
   }
-  summary.uploaded += result.doc_ext_ids.length;
-  summary.skipped += result.skipped.length;
-  summary.docIds.push(...result.doc_ext_ids);
-  summary.skippedDetails.push(...result.skipped);
+  summary2.uploaded += result.doc_ext_ids.length;
+  summary2.skipped += result.skipped.length;
+  summary2.docIds.push(...result.doc_ext_ids);
+  summary2.skippedDetails.push(...result.skipped);
 }
 function classifyDirectInputs(inputPaths) {
   const out = [];
@@ -6632,7 +6637,7 @@ async function runDirectUploadMode(inputPaths, opts) {
   });
   const creds = store.requireCredentials();
   const workspaceKey = await sdk.getRawWorkspaceKey(arbi, workspaceId, creds.signingPrivateKeyBase64);
-  const summary = {
+  const summary2 = {
     totalFiles: 0,
     uploaded: 0,
     skipped: 0,
@@ -6669,7 +6674,7 @@ async function runDirectUploadMode(inputPaths, opts) {
         warn(`No supported files found in directory: ${inp.originalPath}`);
         continue;
       }
-      mergeBatchResult(summary, uploadedDocs, result2, inp.originalPath, opts);
+      mergeBatchResult(summary2, uploadedDocs, result2, inp.originalPath, opts);
       if (!opts.json) {
         success(
           `Uploaded directory: ${inp.originalPath} (${result2.doc_ext_ids.length} document(s) total)`
@@ -6688,7 +6693,7 @@ async function runDirectUploadMode(inputPaths, opts) {
         warn(`No supported files found in zip: ${inp.originalPath}`);
         continue;
       }
-      mergeBatchResult(summary, uploadedDocs, result2, inp.originalPath, opts);
+      mergeBatchResult(summary2, uploadedDocs, result2, inp.originalPath, opts);
       if (!opts.json) {
         success(
           `Uploaded zip: ${inp.originalPath} (${result2.doc_ext_ids.length} document(s) total)`
@@ -6706,7 +6711,7 @@ async function runDirectUploadMode(inputPaths, opts) {
       warn(`No supported files found in archive: ${inp.originalPath}`);
       continue;
     }
-    mergeBatchResult(summary, uploadedDocs, result, inp.originalPath, opts);
+    mergeBatchResult(summary2, uploadedDocs, result, inp.originalPath, opts);
     if (!opts.json) {
       success(
         `Uploaded archive: ${inp.originalPath} (${result.doc_ext_ids.length} document(s) total)`
@@ -6723,11 +6728,11 @@ async function runDirectUploadMode(inputPaths, opts) {
       folder: opts.folder,
       configExtId: opts.config
     });
-    summary.totalFiles += plainFiles.length;
-    summary.uploaded += result.doc_ext_ids.length;
-    summary.skipped += result.skipped.length;
-    summary.docIds.push(...result.doc_ext_ids);
-    summary.skippedDetails.push(...result.skipped);
+    summary2.totalFiles += plainFiles.length;
+    summary2.uploaded += result.doc_ext_ids.length;
+    summary2.skipped += result.skipped.length;
+    summary2.docIds.push(...result.doc_ext_ids);
+    summary2.skippedDetails.push(...result.skipped);
     for (let i = 0; i < result.doc_ext_ids.length && i < plainFiles.length; i++) {
       uploadedDocs.set(result.doc_ext_ids[i], path6__default.default.basename(plainFiles[i]));
     }
@@ -6738,9 +6743,9 @@ async function runDirectUploadMode(inputPaths, opts) {
     }
   }
   if (opts.json) {
-    console.log(JSON.stringify(summary));
+    console.log(JSON.stringify(summary2));
   } else {
-    printSummary(summary);
+    printSummary(summary2);
   }
   if (willWatch && uploadedDocs.size > 0) {
     const pending = new Set(uploadedDocs.keys());
@@ -6849,7 +6854,7 @@ function registerUploadCommand(program2) {
       });
       const uploadedDocs = /* @__PURE__ */ new Map();
       const auth = { baseUrl: config.baseUrl, accessToken };
-      const summary = {
+      const summary2 = {
         totalFiles: 0,
         uploaded: 0,
         skipped: 0,
@@ -6883,7 +6888,7 @@ function registerUploadCommand(program2) {
           if (opts.dryRun) {
             const count = countSupportedFiles2(filePath);
             console.log(`${filePath}: ${count} supported file(s) would be uploaded`);
-            summary.totalFiles += count;
+            summary2.totalFiles += count;
             continue;
           }
           const result = await sdk.documentsNode.uploadDirectory(auth, filePath, progressCallbacks);
@@ -6906,7 +6911,7 @@ function registerUploadCommand(program2) {
               `Uploaded directory: ${filePath} (${result.doc_ext_ids.length} document(s) total)`
             );
           }
-          updateSummary(summary, result);
+          updateSummary(summary2, result);
           for (const id of result.doc_ext_ids) uploadedDocs.set(id, filePath);
         } else if (filePath.toLowerCase().endsWith(".zip")) {
           if (opts.dryRun) {
@@ -6931,7 +6936,7 @@ function registerUploadCommand(program2) {
             }
             success(`Uploaded zip: ${filePath} (${result.doc_ext_ids.length} document(s) total)`);
           }
-          updateSummary(summary, result);
+          updateSummary(summary2, result);
           for (const id of result.doc_ext_ids) uploadedDocs.set(id, filePath);
         } else if (sdk.documentsNode.ARCHIVE_EXTENSIONS.has(
           filePath.slice(filePath.lastIndexOf(".")).toLowerCase()
@@ -6960,12 +6965,12 @@ function registerUploadCommand(program2) {
               `Uploaded archive: ${filePath} (${result.doc_ext_ids.length} document(s) total)`
             );
           }
-          updateSummary(summary, result);
+          updateSummary(summary2, result);
           for (const id of result.doc_ext_ids) uploadedDocs.set(id, filePath);
         } else {
           if (opts.dryRun) {
             console.log(`${filePath}: single file would be uploaded`);
-            summary.totalFiles += 1;
+            summary2.totalFiles += 1;
             continue;
           }
           const result = await sdk.documentsNode.uploadLocalFile(auth, filePath, {
@@ -6981,12 +6986,12 @@ function registerUploadCommand(program2) {
               );
             }
           }
-          summary.totalFiles += 1;
-          summary.uploaded += result.doc_ext_ids?.length ?? 0;
-          summary.docIds.push(...result.doc_ext_ids ?? []);
+          summary2.totalFiles += 1;
+          summary2.uploaded += result.doc_ext_ids?.length ?? 0;
+          summary2.docIds.push(...result.doc_ext_ids ?? []);
           if (result.skipped) {
-            summary.skipped += result.skipped.length;
-            summary.skippedDetails.push(...result.skipped);
+            summary2.skipped += result.skipped.length;
+            summary2.skippedDetails.push(...result.skipped);
           }
           for (const id of result.doc_ext_ids ?? []) uploadedDocs.set(id, result.fileName);
         }
@@ -6995,9 +7000,9 @@ function registerUploadCommand(program2) {
         return;
       }
       if (opts.json) {
-        console.log(JSON.stringify(summary));
+        console.log(JSON.stringify(summary2));
       } else {
-        printSummary(summary);
+        printSummary(summary2);
       }
       if (willWatch && uploadedDocs.size > 0) {
         const pending = new Set(uploadedDocs.keys());
@@ -7059,17 +7064,17 @@ Connection closed. ${pending.size} document(s) still processing.`);
     })()
   );
 }
-function updateSummary(summary, result) {
+function updateSummary(summary2, result) {
   let totalFiles = 0;
   for (const [, info] of result.folders) {
     totalFiles += info.fileCount;
-    summary.folders += 1;
+    summary2.folders += 1;
   }
-  summary.totalFiles += totalFiles;
-  summary.uploaded += result.doc_ext_ids.length;
-  summary.skipped += result.skipped.length;
-  summary.docIds.push(...result.doc_ext_ids);
-  summary.skippedDetails.push(...result.skipped);
+  summary2.totalFiles += totalFiles;
+  summary2.uploaded += result.doc_ext_ids.length;
+  summary2.skipped += result.skipped.length;
+  summary2.docIds.push(...result.doc_ext_ids);
+  summary2.skippedDetails.push(...result.skipped);
 }
 function countSupportedFiles2(dirPath) {
   let count = 0;
@@ -7752,10 +7757,10 @@ Error: ${message}`))
         saveLastMetadata(result.metadata);
       }
       const refs = sdk.countCitations(result.metadata);
-      const summary = opts.quiet !== true ? sdk.formatStreamSummary(result, elapsedTime) : "";
-      if (summary) {
+      const summary2 = opts.quiet !== true ? sdk.formatStreamSummary(result, elapsedTime) : "";
+      if (summary2) {
         const refSuffix = refs > 0 ? ` \xB7 ${refs} ref${refs === 1 ? "" : "s"}` : "";
-        const text = `[${summary}${refSuffix}]`;
+        const text = `[${summary2}${refSuffix}]`;
         const cols = process.stderr.columns || 80;
         const pad = Math.max(0, cols - text.length);
         console.error(chalk2__default.default.dim(" ".repeat(pad) + text));
@@ -8472,6 +8477,174 @@ function registerTimelineCommand(program2) {
   );
 }
 init_prompts();
+function readStructured(path8) {
+  let text;
+  try {
+    text = fs7.readFileSync(path8, "utf8");
+  } catch (err) {
+    throw new Error(`Cannot read ${path8}: ${err.message}`);
+  }
+  const ext = path6.extname(path8).toLowerCase();
+  try {
+    return ext === ".json" ? JSON.parse(text) : yaml.parse(text);
+  } catch (err) {
+    throw new Error(
+      `${path8} is not valid ${ext === ".json" ? "JSON" : "YAML"}: ${err.message}`
+    );
+  }
+}
+function readStepsFile(path8) {
+  try {
+    return sdk.workflowSteps.parsePlanSteps(readStructured(path8));
+  } catch (err) {
+    if (err instanceof sdk.PlanStepsError) throw new Error(`${path8}: ${err.message}`);
+    throw err;
+  }
+}
+function readInputsFile(path8) {
+  const value = readStructured(path8);
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new Error(`${path8}: expected an object of input values, e.g. {"client": "Acme"}`);
+  return value;
+}
+function collect(value, previous = []) {
+  return [...previous, value];
+}
+var GAP = "\u2014";
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function parseFieldDefinitions(arg) {
+  let value;
+  const trimmed = arg.trim();
+  if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+    try {
+      value = JSON.parse(trimmed);
+    } catch (err) {
+      throw new Error(`--define is not valid JSON: ${err.message}`);
+    }
+  } else if (fs7.existsSync(arg)) value = readStructured(arg);
+  else
+    throw new Error(
+      `--define takes JSON (e.g. '[{"name":"budget","type":"number"}]') or a .json/.yaml file; no file "${arg}"`
+    );
+  const list = isRecord(value) ? value.fields : value;
+  if (!Array.isArray(list))
+    throw new Error('--define: expected a list of fields, or an object with a "fields" list');
+  const problems = [];
+  const names = /* @__PURE__ */ new Set();
+  const out = list.map((raw, i) => {
+    const at = `fields[${i}]`;
+    if (!isRecord(raw)) {
+      problems.push(`${at}: must be an object with a name and a type`);
+      return { name: "", type: "text" };
+    }
+    for (const key of Object.keys(raw))
+      if (!["id", "name", "type", "options"].includes(key))
+        problems.push(`${at}.${key}: unknown field (allowed: name, type, options, id)`);
+    const name = typeof raw.name === "string" ? raw.name.trim() : "";
+    if (!name || name.length > 200)
+      problems.push(`${at}.name: required text (up to 200 characters)`);
+    else if (names.has(name.toLowerCase())) problems.push(`${at}.name: "${name}" is used twice`);
+    names.add(name.toLowerCase());
+    const type = raw.type ?? "text";
+    if (!sdk.tags.TAG_FIELD_TYPES.includes(type))
+      problems.push(
+        `${at}.type: must be one of ${sdk.tags.TAG_FIELD_TYPES.join(", ")} (got ${JSON.stringify(type)})`
+      );
+    const options = raw.options;
+    if (options !== void 0 && options !== null) {
+      if (!Array.isArray(options) || options.some((o) => typeof o !== "string"))
+        problems.push(`${at}.options: a list of text, e.g. ["low", "high"]`);
+      else if (type !== "select") problems.push(`${at}.options: only a select field has options`);
+    } else if (type === "select") problems.push(`${at}.options: a select field needs its options`);
+    if (raw.id !== void 0 && (typeof raw.id !== "string" || !/^fld-[a-f0-9]{6}$/.test(raw.id)))
+      problems.push(`${at}.id: an existing field id (fld-\u2026), or leave it out`);
+    return {
+      ...typeof raw.id === "string" ? { id: raw.id } : {},
+      name,
+      type,
+      ...Array.isArray(options) ? { options } : {}
+    };
+  });
+  if (problems.length)
+    throw new Error(`Invalid field definitions:
+${problems.map((p) => `  - ${p}`).join("\n")}`);
+  return out;
+}
+function parseFieldValues(pairs, fields) {
+  const out = {};
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) throw new Error(`Invalid --set "${pair}": use name=value (name= clears it)`);
+    const name = pair.slice(0, eq).trim();
+    const value = pair.slice(eq + 1);
+    const field = fields.find((f) => f.name.toLowerCase() === name.toLowerCase() || f.id === name);
+    if (!field)
+      throw new Error(
+        `No field "${name}" on this tag. Its fields: ${fields.map((f) => f.name).join(", ") || "(none: add some with --define)"}`
+      );
+    if (value.trim() === "") out[field.name] = null;
+    else if (field.type === "select" && field.options?.length) {
+      const option = field.options.find((o) => o.toLowerCase() === value.trim().toLowerCase());
+      if (!option)
+        throw new Error(`"${field.name}" is one of ${field.options.join(", ")}; got "${value}"`);
+      out[field.name] = option;
+    } else out[field.name] = value;
+  }
+  return out;
+}
+function formatFieldValue(value) {
+  if (value === void 0 || value === null || value === "") return GAP;
+  if (typeof value === "boolean") return value ? "yes" : "no";
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
+function fieldRows(tag) {
+  return (tag.fields ?? []).map((f) => ({
+    id: f.id,
+    name: f.name,
+    type: f.type === "select" && f.options?.length ? `select: ${f.options.join("|")}` : f.type,
+    value: formatFieldValue(tag.field_values?.[f.id]),
+    from: f.tag_ext_id === tag.external_id ? "own" : `inherited (${f.tag_ext_id})`
+  }));
+}
+function matrixTable(matrix) {
+  const columns = sdk.tags.tagMatrixColumns(matrix);
+  const headers = ["TAG", ...columns.map((c) => c.name.toUpperCase()), "DOCS", "FACTS"];
+  const rows = [];
+  const gaps = [];
+  for (const row of matrix.rows ?? []) {
+    const has = new Set((row.tag.fields ?? []).map((f) => f.id));
+    const cells = columns.map(
+      (c) => has.has(c.id) ? formatFieldValue(row.tag.field_values?.[c.id]) : "n/a"
+    );
+    rows.push([
+      row.tag.name,
+      ...cells,
+      row.doc_count ? String(row.doc_count) : GAP,
+      row.fact_count ? String(row.fact_count) : GAP
+    ]);
+    const missing = columns.filter((c, i) => has.has(c.id) && cells[i] === GAP).map((c) => c.name);
+    if (!row.doc_count) missing.push("documents");
+    if (!row.fact_count) missing.push("facts");
+    if (missing.length) gaps.push(`${row.tag.name}: no ${missing.join(", no ")}`);
+  }
+  return { headers, rows, gaps };
+}
+function renderTable(headers, rows, max = 28) {
+  const clip = (s) => s.length > max ? `${s.slice(0, max - 1)}\u2026` : s;
+  const widths = headers.map(
+    (h, i) => Math.min(max, Math.max(h.length, ...rows.map((r) => clip(r[i] ?? "").length)))
+  );
+  const line = (cells) => cells.map((c, i) => clip(c ?? "").padEnd(widths[i])).join("  ").trimEnd();
+  return [line(headers), ...rows.map(line)];
+}
+
+// src/commands/tags.ts
+async function resolveTag(arbi, selector) {
+  const res = resolveByIdOrName(await sdk.tags.listTags(arbi), selector);
+  if (!res.ok) failResolveAndExit("Tag", selector, res);
+  return res.item;
+}
 async function fetchTagChoices(arbi) {
   const data = await sdk.tags.listTags(arbi);
   if (data.length === 0) {
@@ -8488,7 +8661,7 @@ async function fetchTagChoices(arbi) {
   };
 }
 function registerTagsCommand(program2) {
-  const tags = program2.command("tags").description("Tags: list, create, delete, update, share, unshare, rename");
+  const tags = program2.command("tags").description("Tags: list, create, delete, update, share, unshare, rename, fields, matrix");
   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);
@@ -8511,7 +8684,8 @@ function registerTagsCommand(program2) {
             value: (r) => r.tag_type?.type ?? ""
           },
           { header: "DOCS", width: 6, value: (r) => String(r.doctag_count) },
-          { header: "SHARED", width: 8, value: (r) => r.shared ? "yes" : "no" }
+          { header: "SHARED", width: 8, value: (r) => r.shared ? "yes" : "no" },
+          { header: "PARENT", width: 24, value: (r) => r.parent_ext_id ?? "" }
         ],
         data
       );
@@ -8521,9 +8695,10 @@ function registerTagsCommand(program2) {
     "-t, --type <type>",
     "Tag type (checkbox, text, number, select, folder, search, date, assistant)",
     "checkbox"
-  ).option("-i, --instruction <text>", "Tag instruction").option("--shared", "Make tag shared", false).action(
+  ).option("-i, --instruction <text>", "Tag instruction").option("--shared", "Make tag shared", false).option("--parent <tag>", "Make it a child of this tag (id or name): it inherits its fields").option("--json", "Output as JSON").action(
     (name, opts) => runAction(async () => {
       const { arbi } = await resolveWorkspace(opts.workspace);
+      const parent = opts.parent ? await resolveTag(arbi, opts.parent) : void 0;
       const interactive = !name;
       if (!name) {
         name = await promptInput("Tag name");
@@ -8547,9 +8722,16 @@ function registerTagsCommand(program2) {
           options: []
         },
         instruction,
-        shared
+        shared,
+        parentId: parent?.external_id ?? null
       });
-      success(`Created: ${data.name} (${ref(data.external_id)})`);
+      if (opts.json) {
+        printJson(data);
+        return;
+      }
+      success(
+        `Created: ${data.name} (${ref(data.external_id)})${parent ? ` under ${parent.name}` : ""}`
+      );
     })()
   );
   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(
@@ -8614,6 +8796,95 @@ function registerTagsCommand(program2) {
       success(`Updated: ${data.name} (${ref(data.external_id)})`);
     })()
   );
+  tags.command("fields <tag>").description(
+    "Show a tag's fields and values; --define its own fields (a child inherits its parent's), --set values"
+  ).option(
+    "--define <json|file>",
+    `Its own field definitions: JSON or a .json/.yaml file, e.g. '[{"name":"budget","type":"number"},{"name":"risk","type":"select","options":["low","high"]}]'. A field defined again by name keeps its values; ones left out are dropped unless --keep-others`
+  ).option("--keep-others", "With --define: keep its other own fields").option("--set <name=value>", "Set a field value (repeatable; name= clears it)", collect, []).option("--json", "Output as JSON").action(
+    (selector, opts) => runAction(async () => {
+      const defs = opts.define ? parseFieldDefinitions(opts.define) : void 0;
+      const { arbi } = await resolveWorkspace();
+      let tag = await resolveTag(arbi, selector);
+      if (defs || opts.set.length) {
+        const fields = defs ? sdk.tags.mergeTagFieldDefinitions(tag, defs, { keepOthers: !!opts.keepOthers }) : void 0;
+        const known = fields ? [
+          ...(tag.fields ?? []).filter((f) => f.tag_ext_id !== tag.external_id),
+          ...fields.map((f) => ({
+            id: f.id ?? "",
+            name: f.name,
+            type: f.type,
+            options: f.options ?? null,
+            tag_ext_id: tag.external_id
+          }))
+        ] : tag.fields ?? [];
+        const values = opts.set.length ? parseFieldValues(opts.set, known) : void 0;
+        tag = await sdk.tags.updateTagFields(arbi, tag.external_id, { fields, values });
+      }
+      if (opts.json) {
+        printJson(tag);
+        return;
+      }
+      if (defs || opts.set.length)
+        success(`Updated the fields of ${tag.name} (${ref(tag.external_id)})`);
+      else bold(`${tag.name} (${tag.external_id})`);
+      const rows = fieldRows(tag);
+      if (!rows.length) {
+        dim(
+          `No fields. Define some: arbi tags fields ${tag.external_id} --define '[{"name":"budget","type":"number"}]'`
+        );
+        return;
+      }
+      printTable(
+        [
+          { header: "FIELD", width: 22, value: (r) => r.name },
+          { header: "TYPE", width: 24, value: (r) => r.type },
+          { header: "VALUE", width: 28, value: (r) => r.value },
+          { header: "DEFINED", width: 30, value: (r) => r.from }
+        ],
+        rows
+      );
+    })()
+  );
+  tags.command("matrix").description(
+    "Tags as a table: rows are a parent's children (--parent) or the given tags (--tag), columns their fields, then document and fact counts; gaps marked \u2014"
+  ).option("--parent <tag>", "Rows are this tag\u2019s children (id or name)").option("--tag <tag>", "A row (id or name; repeatable, in this order)", collect, []).option("--links <n>", "Most documents and facts listed per row (JSON)").option("--json", "Output as JSON").action(
+    (opts) => runAction(async () => {
+      if (!opts.parent === !opts.tag.length)
+        throw new Error("Pass --parent <tag>, or one or more --tag <tag>");
+      const links = opts.links === void 0 ? void 0 : Number(opts.links);
+      if (links !== void 0 && (!Number.isInteger(links) || links < 0))
+        throw new Error("--links must be a whole number");
+      const { arbi } = await resolveWorkspace();
+      const all = await sdk.tags.listTags(arbi);
+      const pick = (selector) => {
+        const res = resolveByIdOrName(all, selector);
+        if (!res.ok) failResolveAndExit("Tag", selector, res);
+        return res.item;
+      };
+      const selection = opts.parent ? { parentId: pick(opts.parent).external_id } : { tagIds: opts.tag.map((t) => pick(t).external_id) };
+      const matrix = await sdk.tags.getTagMatrix(arbi, selection, links);
+      if (opts.json) {
+        printJson(matrix);
+        return;
+      }
+      const table = matrixTable(matrix);
+      if (matrix.parent) bold(`${matrix.parent.name} (${matrix.parent.external_id})`);
+      if (!table.rows.length) {
+        process.stderr.write(
+          opts.parent ? `No child tags. Add one: arbi tags create <name> --parent ${opts.parent}
+` : "No tags.\n"
+        );
+        return;
+      }
+      for (const line of renderTable(table.headers, table.rows)) console.log(line);
+      if (table.gaps.length) {
+        console.log("");
+        dim("Gaps:");
+        for (const g of table.gaps) dim(`  ${g}`);
+      }
+    })()
+  );
   tags.allowUnknownOption(true).allowExcessArguments(true).action(async () => {
     const tail = tags.args ?? [];
     await tags.commands.find((c) => c.name() === "list").parseAsync(tail, { from: "user" });
@@ -9427,6 +9698,9 @@ async function runQuickstart(url) {
     console.log(`  Workspace: ${workspaceName} (${ref(workspaceId)})`);
     console.log("");
     dim('Try: arbi ask "hello"');
+    dim(
+      "Workflows with steps: arbi workflow create --name <n> --steps steps.yaml (see arbi run --help)"
+    );
   } catch (err) {
     if (isExitPromptError(err)) throw err;
     error(`Login failed: ${sdk.getErrorMessage(err)}`);
@@ -9793,14 +10067,59 @@ function registerTaskCommand(program2) {
     })()
   );
 }
+function signalTrigger(name, eventKind, eventFilter) {
+  if (name === void 0) return void 0;
+  if (!sdk.workflowSteps.SIGNAL_NAME_PATTERN.test(name))
+    throw new Error(
+      `Invalid --on-signal "${name}": lowercase letters, digits, ".", "_" or "-", starting with a letter or digit (e.g. risk-high)`
+    );
+  if (eventKind && eventKind !== "workflow_signal")
+    throw new Error(`--on-signal is an event trigger: use it instead of --event-kind ${eventKind}`);
+  let filter = {};
+  if (eventFilter) {
+    try {
+      filter = JSON.parse(eventFilter);
+    } catch {
+      throw new Error("--event-filter must be a JSON object");
+    }
+  }
+  return { event_kind: "workflow_signal", event_filter: { ...filter, signal: name } };
+}
+function triggerText(w) {
+  const signal = w.event_filter?.signal;
+  if (w.event_kind === "workflow_signal" && typeof signal === "string") return `signal ${signal}`;
+  if (w.event_kind) return `event ${w.event_kind}`;
+  if (w.rrule) return w.rrule;
+  if (w.run_at) return `once ${w.run_at}`;
+  if (w.after_conversation_ext_id) return `after ${w.after_conversation_ext_id}`;
+  return "by hand";
+}
 function registerWorkflowCommand(program2) {
-  const workflow = program2.command("workflow").alias("automation").description("Workflows (/v1/workflow): create, list, resume, pause, run, delete");
-  workflow.command("create").description("Create a workflow with exactly one trigger").requiredOption("--name <name>", "Workflow name (required)").option("--rrule <RRULE>", "Trigger: RFC-5545 recurrence rule").option("--run-at <ISO>", "Trigger: run once at this time (ISO-8601)").option("--event-kind <kind>", "Trigger: a notification type to react to").option("--after <con-id>", "Trigger: when this task (conversation) is done").option("--timezone <tz>", "IANA timezone for --rrule", "UTC").option("--action <type>", "Action: annotate_documents or email_documents").option("--documents <ids>", "Comma-separated document IDs").option("--labels <ids>", "Select documents matching these label IDs at execution time").option("--latest", "Select documents uploaded since the previous successful run").option("--tags <ids>", "Annotation field IDs for AI review").option("--overwrite", "Regenerate existing annotation answers").option(
+  const workflow = program2.command("workflow").alias("automation").description(
+    "Workflows (/v1/workflow): create (optionally with steps), list, update, resume, pause, run, delete"
+  );
+  workflow.command("create").description(
+    "Create a workflow: at most one trigger (none = started by hand) and what it runs: --steps, --prompt, --skill or --action"
+  ).requiredOption("--name <name>", "Workflow name (required)").option(
+    "--steps <file>",
+    "Named steps (form/upload/agent/review) as a TaskPlanStep list in .json, .yaml or .yml"
+  ).option("--rrule <RRULE>", "Trigger: RFC-5545 recurrence rule").option("--run-at <ISO>", "Trigger: run once at this time (ISO-8601)").option("--event-kind <kind>", "Trigger: a notification type to react to").option(
+    "--on-signal <name>",
+    "Trigger: when a step of another run raises this signal (event_kind=workflow_signal, filter {signal})"
+  ).option("--after <con-id>", "Trigger: when this task (conversation) is done").option("--timezone <tz>", "IANA timezone for --rrule", "UTC").option("--action <type>", "Action: annotate_documents or email_documents").option("--documents <ids>", "Comma-separated document IDs").option("--labels <ids>", "Select documents matching these label IDs at execution time").option("--latest", "Select documents uploaded since the previous successful run").option("--tags <ids>", "Annotation field IDs for AI review").option("--overwrite", "Regenerate existing annotation answers").option(
     "--auth-mode <mode>",
     "scheduled_require_auth or scheduled_permanent",
     "scheduled_require_auth"
   ).option("--event-filter <json>", "Notification attribute filters as a JSON object").option("--prompt <text>", "Instruction the agent runs").option("--skill <ref>", "Skill reference to run").option("--agent <agt-id>", "Agent to run it as (external id)").option("--workspace <wrk-id>", "Workspace to scope the workflow to (default: the current one)").option("--shared", "Share it with the workspace").option("--json", "Output as JSON").action(
     (opts) => runAction(async () => {
+      if (opts.steps && (opts.prompt || opts.skill || opts.action))
+        throw new Error("Use --steps, or --prompt / --skill / --action, not both");
+      const signal = signalTrigger(opts.onSignal, opts.eventKind, opts.eventFilter);
+      if (signal) {
+        opts.eventKind = signal.event_kind;
+        opts.eventFilter = JSON.stringify(signal.event_filter);
+      }
+      const steps = opts.steps ? readStepsFile(opts.steps) : void 0;
       const { arbi, workspaceId } = await resolveWorkspace();
       const body = {
         name: opts.name,
@@ -9842,12 +10161,27 @@ function registerWorkflowCommand(program2) {
       if (opts.after) body.after_conversation_ext_id = opts.after;
       if (opts.skill) body.skill_ref = opts.skill;
       if (opts.agent) body.agent_ext_id = opts.agent;
+      if (steps) body.plan = sdk.workflowSteps.stepsPlan(steps);
       const data = await sdk.workflows.createWorkflow(arbi, body);
       if (opts.json) {
         printJson(data);
         return;
       }
-      success(`Created workflow: ${data.name} (${ref(data.external_id)})`);
+      success(
+        `Created workflow: ${data.name} (${ref(data.external_id)})${steps ? ` with ${steps.length} steps` : ""}`
+      );
+      if (opts.onSignal)
+        dim(
+          `It starts when a step of a run raises "${opts.onSignal}" (a step's signals: [{name: ${opts.onSignal}, when: \u2026}]).`
+        );
+      const raised = [
+        ...new Set((steps ?? []).flatMap((s) => (s.signals ?? []).map((x) => x.name)))
+      ];
+      if (raised.length)
+        dim(
+          `Its steps raise ${raised.map((n) => `"${n}"`).join(", ")}: a workflow made with --on-signal <name> starts on each.`
+        );
+      if (steps) dim(`Run it: arbi workflow run ${data.external_id}`);
     })()
   );
   workflow.command("list").description("List your workflows").option("--json", "Output as JSON").action(
@@ -9861,6 +10195,11 @@ function registerWorkflowCommand(program2) {
           { header: "NAME", width: 28, value: (r) => r.name ?? "" },
           { header: "ACTIVE", width: 7, value: (r) => r.active ? "yes" : "no" },
           { header: "SHARED", width: 8, value: (r) => r.shared ? "yes" : "no" },
+          {
+            header: "TRIGGER",
+            width: 26,
+            value: (r) => triggerText(r)
+          },
           { header: "NEXT RUN", width: 26, value: (r) => r.next_fire_at ?? "" },
           { header: "LAST RUN", width: 26, value: (r) => r.last_fired_at ?? "" }
         ],
@@ -9880,7 +10219,9 @@ function registerWorkflowCommand(program2) {
       })()
     );
   }
-  workflow.command("run <id>").description("Start the saved action now (document actions do not create a thread)").option("--json", "Output as JSON").action(
+  workflow.command("run <id>").description(
+    "Run a workflow now: a thread (a stepped one waits for its steps), or a document action without one"
+  ).option("--json", "Output as JSON").action(
     (id, opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.workflows.runWorkflow(arbi, id);
@@ -9890,11 +10231,17 @@ function registerWorkflowCommand(program2) {
       }
       if (data.error) throw new Error(data.error);
       success(
-        `${data.started ? "Started" : "Submitted"} automation ${ref(id)}${data.execution_id ? ` \u2014 execution ${data.execution_id}` : ""}${data.conversation_ext_id ? ` \u2014 thread ${ref(data.conversation_ext_id)}` : ""}`
+        `${data.started ? "Started" : "Submitted"} workflow ${ref(id)}${data.execution_id ? ` \u2014 execution ${data.execution_id}` : ""}${data.conversation_ext_id ? ` \u2014 thread ${ref(data.conversation_ext_id)}` : ""}`
       );
+      if (!data.conversation_ext_id) return;
+      const saved = await sdk.workflows.getWorkflow(arbi, id);
+      if (saved.plan?.steps?.length) {
+        dim(`Its steps: arbi run steps ${data.conversation_ext_id}`);
+        dim(`Follow it: arbi run steps ${data.conversation_ext_id} --watch --answers`);
+      }
     })()
   );
-  workflow.command("get <id>").description("Read the complete saved automation configuration").action(
+  workflow.command("get <id>").description("Read the complete saved workflow configuration").action(
     (id) => runAction(async () => {
       const { arbi } = await resolveAuth();
       printJson(await sdk.workflows.getWorkflow(arbi, id));
@@ -9904,7 +10251,7 @@ function registerWorkflowCommand(program2) {
     (id, opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.workflows.listWorkflowRuns(arbi, id);
-      if (!emitListOrTable(data, opts, "This automation has not run yet.")) return;
+      if (!emitListOrTable(data, opts, "This workflow has not run yet.")) return;
       printTable(
         [
           { header: "RUN", width: 10, value: (r) => String(r.id) },
@@ -9922,13 +10269,25 @@ function registerWorkflowCommand(program2) {
       );
     })()
   );
-  workflow.command("update <id>").description("Update any saved automation settings from a JSON file").requiredOption("--file <path>", "JSON UpdateWorkflowRequest file").option("--json", "Output as JSON").action(
+  workflow.command("update <id>").description("Update a saved workflow: its steps (--steps), and any setting from a JSON file").option("--steps <file>", "Replace its steps (TaskPlanStep list in .json, .yaml or .yml)").option("--file <path>", "JSON UpdateWorkflowRequest file").option("--on-signal <name>", "Start it when a run raises this signal (replaces its trigger)").option("--json", "Output as JSON").action(
     (id, opts) => runAction(async () => {
+      if (!opts.file && !opts.steps && !opts.onSignal)
+        throw new Error("Pass --steps <file>, --on-signal <name> and/or --file <path>");
+      const steps = opts.steps ? readStepsFile(opts.steps) : void 0;
+      const body = opts.file ? JSON.parse(fs7.readFileSync(opts.file, "utf8")) : {};
+      const signal = signalTrigger(opts.onSignal, void 0, void 0);
+      if (signal) Object.assign(body, signal, { on_demand: false });
+      if (steps)
+        Object.assign(body, {
+          plan: sdk.workflowSteps.stepsPlan(steps),
+          prompt: "",
+          skill_ref: null,
+          skill_inputs: null
+        });
       const { arbi } = await resolveAuth();
-      const body = JSON.parse(fs7.readFileSync(opts.file, "utf8"));
       const data = await sdk.workflows.updateWorkflow(arbi, id, body);
       if (opts.json) printJson(data);
-      else success(`Updated automation ${ref(id)}`);
+      else success(`Updated workflow ${ref(id)}${steps ? ` \u2014 ${steps.length} steps` : ""}`);
     })()
   );
   workflow.command("delete <id>").description("Delete a workflow (tasks it already created stay)").action(
@@ -9939,6 +10298,367 @@ function registerWorkflowCommand(program2) {
     })()
   );
 }
+function runJson(progress, answers = {}) {
+  const c = progress.conversation;
+  return {
+    conversation_ext_id: c.external_id,
+    title: c.title,
+    workflow_ext_id: c.workflow_ext_id ?? null,
+    parent_conversation_ext_id: c.parent_conversation_ext_id ?? null,
+    waiting_on: progress.waitingOn,
+    in_progress: c.in_progress,
+    pending_auth_request_id: c.pending_auth_request_id ?? null,
+    last_error: c.last_error ?? null,
+    steps: progress.steps.map((s) => ({
+      id: s.id,
+      title: s.title,
+      kind: s.kind,
+      state: s.phase,
+      after: s.after,
+      answer_id: s.responseId,
+      error: s.error,
+      assignee: s.assignee,
+      announced_to: s.announcedTo,
+      sent_back: s.sentBack,
+      sent_back_note: s.hasNote,
+      times_sent_back: s.timesSentBack,
+      signals: s.signals,
+      linked_runs: s.linkedRuns.map(linkedJson),
+      ...s.responseId && answers[s.responseId] !== void 0 ? { answer: answers[s.responseId] } : {}
+    })),
+    signals: (progress.signals ?? []).map((x) => ({ step: x.step, signal: x.signal, at: x.at })),
+    linked_runs: (progress.linkedRuns ?? []).map(linkedJson),
+    send_backs: (progress.sendBacks ?? []).map((b) => ({
+      step: b.step,
+      to: b.to,
+      reopened: b.reopened,
+      note: b.hasNote,
+      by: b.by,
+      at: b.at
+    }))
+  };
+}
+var linkedJson = (l) => ({
+  step: l.step,
+  signal: l.signal,
+  conversation_ext_id: l.conversationId,
+  workflow_ext_id: l.workflowId,
+  at: l.at
+});
+function stepNotes(s) {
+  const notes = [];
+  if (s.sentBack) notes.push(`sent back${s.hasNote ? " (note)" : ""}`);
+  else if (s.timesSentBack) notes.push(`sent back \xD7${s.timesSentBack}`);
+  if (s.signals.length) notes.push(`\u2691 ${s.signals.join(", ")}`);
+  if (s.linkedRuns.length)
+    notes.push(
+      s.linkedRuns.length === 1 ? `\u2192 ${s.linkedRuns[0].conversationId}` : `\u2192 ${s.linkedRuns.length} linked runs`
+    );
+  return notes.join("; ");
+}
+function runEventLines(progress) {
+  const lines = [
+    ...(progress.signals ?? []).map((x) => ({
+      at: x.at ?? "",
+      line: `\u2691 ${x.step} raised "${x.signal}"`
+    })),
+    ...(progress.linkedRuns ?? []).map((l) => ({
+      at: l.at ?? "",
+      line: `\u2192 "${l.signal ?? "?"}" started ${l.conversationId}${l.workflowId ? ` (workflow ${l.workflowId})` : ""}: arbi run steps ${l.conversationId}`
+    })),
+    ...(progress.sendBacks ?? []).map((b) => ({
+      at: b.at ?? "",
+      line: `\u21A9 ${b.step} sent the work back to ${b.to}${b.hasNote ? " with a note" : ""}${b.by ? ` (${b.by})` : ""}; reopened ${b.reopened.join(", ")}`
+    }))
+  ];
+  return lines.sort((a, b) => a.at && b.at ? a.at.localeCompare(b.at) : 0).map((l) => l.line);
+}
+function nextHint(progress, planSteps = []) {
+  const id = progress.conversation.external_id;
+  if (progress.conversation.pending_auth_request_id)
+    return "The run is waiting for access to the workspace: approve the request in ARBI.";
+  switch (progress.waitingOn) {
+    case "finished":
+      return "Every step is done or skipped.";
+    case "agent": {
+      const next = progress.steps.find((s) => s.phase === "running") ?? progress.steps.find((s) => s.kind === "agent" && s.phase === "ready");
+      return `Step ${next ? `"${next.id}" ` : ""}is on its way: arbi run steps ${id} --watch`;
+    }
+    case "person": {
+      const step = progress.steps.find((s) => s.kind !== "agent" && s.phase === "ready");
+      const planned = planSteps.find((p) => p.id === step.id);
+      const have = progress.conversation.skill_inputs ?? {};
+      const fields = (planned ? sdk.workflowSteps.stepFields(planned) : []).filter(
+        (f) => have[f.name] === void 0 || have[f.name] === null || have[f.name] === ""
+      );
+      const inputs = fields.map((f) => ` --input ${f.name}=\u2026`).join("");
+      const forWhom = step.assignee ? ` (for ${sdk.workflowSteps.describeAssignee(step.assignee)})` : "";
+      const hint = `Waiting on ${step.kind} step "${step.id}"${forWhom}: arbi run step ${id} ${step.id} complete${inputs}`;
+      const back = step.kind === "review" && step.after.length > 0;
+      return back ? `${hint}  (or: arbi run step ${id} ${step.id} send-back${step.after.length > 1 ? " --to <step>" : ""} --note "\u2026")` : hint;
+    }
+    default: {
+      const failed = progress.steps.find((s) => s.phase === "failed");
+      return failed ? `Step "${failed.id}" failed${failed.error ? ` (${failed.error})` : ""}: arbi run step ${id} ${failed.id} skip` : "Nothing can move: a step it waits for has not finished.";
+    }
+  }
+}
+function printRun(progress, answers) {
+  const c = progress.conversation;
+  bold(`Run ${c.external_id}${c.title ? ` \u2014 ${c.title}` : ""}`);
+  if (c.parent_conversation_ext_id)
+    dim(
+      `Started from ${c.parent_conversation_ext_id}${c.workflow_ext_id ? ` by workflow ${c.workflow_ext_id}` : ""}: arbi run steps ${c.parent_conversation_ext_id}`
+    );
+  printTable(
+    [
+      { header: "STEP", width: 16, value: (r) => r.id },
+      { header: "KIND", width: 8, value: (r) => r.kind },
+      { header: "STATE", width: 9, value: (r) => r.phase },
+      {
+        header: "FOR",
+        width: 15,
+        value: (r) => sdk.workflowSteps.describeAssignee(r.assignee)
+      },
+      { header: "ANSWER", width: 16, value: (r) => r.responseId ?? "" },
+      { header: "NOTES", width: 40, value: (r) => stepNotes(r) },
+      { header: "TITLE", width: 32, value: (r) => r.title }
+    ],
+    progress.steps
+  );
+  for (const line of runEventLines(progress)) dim(line);
+  for (const s of progress.steps) {
+    if (s.phase === "failed" && s.error) warn(`${s.id}: ${s.error}`);
+    if (!s.responseId || answers[s.responseId] === void 0) continue;
+    console.log("");
+    bold(`\u2500\u2500 ${s.id}: ${s.title} (${s.responseId})`);
+    console.log(answers[s.responseId]);
+  }
+  console.log("");
+  dim(nextHint(progress, c.plan?.steps ?? []));
+}
+async function answersFor(arbi, progress) {
+  const ids = progress.steps.filter((s) => s.kind === "agent" && s.phase === "done" && s.responseId).map((s) => s.responseId);
+  return sdk.work.getStepAnswers(arbi, progress.conversation.external_id, ids);
+}
+var sleep = (ms) => new Promise((resolve6) => setTimeout(resolve6, ms));
+var summary = (p) => p.steps.map((s) => `${s.id}:${s.phase}`).join(" ");
+async function watchRun(arbi, conversationId, { intervalMs, timeoutMs, quiet }) {
+  const deadline = Date.now() + timeoutMs;
+  let progress = await sdk.work.getRunProgress(arbi, conversationId);
+  let last = "";
+  const report = () => {
+    const now = summary(progress);
+    if (!quiet && now !== last) process.stderr.write(`${(/* @__PURE__ */ new Date()).toISOString()}  ${now}
+`);
+    last = now;
+  };
+  report();
+  while (progress.waitingOn === "agent" && !progress.conversation.pending_auth_request_id) {
+    if (Date.now() >= deadline) return { progress, timedOut: true };
+    await sleep(intervalMs);
+    progress = await sdk.work.getRunProgress(arbi, conversationId);
+    report();
+  }
+  return { progress, timedOut: false };
+}
+function seconds(value, flag) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) throw new Error(`${flag} must be a positive number of seconds`);
+  return n * 1e3;
+}
+var STEP_ACTIONS = {
+  complete: "complete",
+  skip: "skip",
+  "send-back": "send_back",
+  send_back: "send_back"
+};
+function fieldsHint(fields) {
+  const one = (f) => {
+    const options = f.options?.length ? `: ${f.options.map((o) => o.value).join("|")}` : "";
+    const range = f.min !== null && f.min !== void 0 && f.max !== null && f.max !== void 0 ? ` ${f.min}\u2013${f.max}` : "";
+    return `${f.name} (${f.type ?? "text"}${options}${range}${f.required ? ", required" : ""})`;
+  };
+  return `Its fields: ${fields.map(one).join(", ")}`;
+}
+function upstreamOf(plan, id) {
+  const found = /* @__PURE__ */ new Set();
+  const stack = sdk.workflowSteps.stepDependencies(plan, id);
+  while (stack.length) {
+    const d = stack.pop();
+    if (found.has(d)) continue;
+    found.add(d);
+    stack.push(...sdk.workflowSteps.stepDependencies(plan, d));
+  }
+  return found;
+}
+function checkSendBack(plan, stepId, to) {
+  const upstream = upstreamOf(plan, stepId);
+  if (to === void 0) {
+    const direct = sdk.workflowSteps.stepDependencies(plan, stepId);
+    if (direct.length !== 1)
+      throw new Error(
+        `"${stepId}" waits for ${direct.length ? direct.join(", ") : "no step"}: say which to send it back to with --to <step>`
+      );
+    return;
+  }
+  if (!plan.some((s) => s.id === to))
+    throw new Error(`No step "${to}". Its steps: ${plan.map((s) => s.id).join(", ")}`);
+  if (!upstream.has(to))
+    throw new Error(
+      `"${to}" is not a step "${stepId}" waits for: send it back to one of ${[...upstream].join(", ") || "(none)"}`
+    );
+}
+function gatherInputs(pairs, file, fields) {
+  return {
+    ...file ? readInputsFile(file) : {},
+    ...sdk.workflowSteps.parseInputPairs(pairs, fields)
+  };
+}
+function registerRunCommand(program2) {
+  const run = program2.command("run").description(
+    "Stepped workflow runs: start one from a steps file, see its steps, complete or skip a step"
+  );
+  run.command("start").description("Start a one-off stepped run as a work thread, without saving a workflow").requiredOption("--steps <file>", "Plan steps (TaskPlanStep list) as .json, .yaml or .yml").requiredOption("--title <title>", "The run thread's title").option("--input <name=value>", "A run input, e.g. a form field (repeatable)", collect, []).option("--inputs-file <file>", "Run inputs as a JSON or YAML object").option("--agent <agt-id>", "Agent to run the agent steps as (external id)").option("--shared", "Share the thread with the workspace").option("--json", "Output as JSON").action(
+    (opts) => runAction(async () => {
+      const steps = readStepsFile(opts.steps);
+      const inputs = gatherInputs(
+        opts.input,
+        opts.inputsFile,
+        steps.flatMap((s) => sdk.workflowSteps.stepFields(s))
+      );
+      const { arbi } = await resolveWorkspace();
+      const created = await sdk.work.createWork(arbi, {
+        title: opts.title,
+        plan: sdk.workflowSteps.stepsPlan(steps),
+        skill_inputs: Object.keys(inputs).length ? inputs : null,
+        agent_ext_id: opts.agent ?? null,
+        shared: opts.shared ?? null,
+        auth_mode: "run_now_temp"
+      });
+      const progress = await sdk.work.getRunProgress(arbi, created.external_id);
+      if (opts.json) {
+        printJson(runJson(progress));
+        return;
+      }
+      success(`Started run ${ref(created.external_id)} \u2014 ${opts.title}`);
+      dim(`Follow it: arbi run steps ${created.external_id} --watch`);
+      dim(nextHint(progress, steps));
+    })()
+  );
+  run.command("steps <con-id>").description(
+    "A run's steps and their state (pending, ready, running, done, skipped, failed), with each done agent step's answer id"
+  ).option("--answers", "Print the done agent steps' answers from the thread").option("--watch", "Poll until the run stops waiting on an agent step").option("--interval <seconds>", "Poll interval for --watch", "3").option("--timeout <seconds>", "Stop watching after this long", "600").option("--json", "Output as JSON").action(
+    (conversationId, opts) => runAction(async () => {
+      const intervalMs = seconds(opts.interval, "--interval");
+      const timeoutMs = seconds(opts.timeout, "--timeout");
+      const { arbi } = await resolveWorkspace();
+      let progress;
+      let timedOut = false;
+      if (opts.watch) {
+        ;
+        ({ progress, timedOut } = await watchRun(arbi, conversationId, {
+          intervalMs,
+          timeoutMs,
+          quiet: !!opts.json
+        }));
+      } else progress = await sdk.work.getRunProgress(arbi, conversationId);
+      const answers = opts.answers ? await answersFor(arbi, progress) : {};
+      if (opts.json) printJson({ ...runJson(progress, answers), timed_out: timedOut });
+      else {
+        printRun(progress, answers);
+        if (timedOut) warn(`Stopped watching after ${opts.timeout}s; the run is still going.`);
+      }
+    })()
+  );
+  run.command("step <con-id> <step-id> <action>").description(
+    "Act on a step: complete a person step (a form, or a step with fields, takes --input), skip any step, or send-back the work to an earlier step (--to, --note)"
+  ).option(
+    "--input <name=value>",
+    "An input: a form field or a step field (repeatable)",
+    collect,
+    []
+  ).option("--inputs-file <file>", "Inputs as a JSON or YAML object").option(
+    "--to <step-id>",
+    "send-back: the step to reopen (default: the one this step waits for)"
+  ).option("--note <text>", "send-back: what to change (an agent step runs again with it)").option("--json", "Output as JSON").action(
+    (conversationId, stepId, rawAction, opts) => runAction(async () => {
+      const action = STEP_ACTIONS[rawAction];
+      if (!action)
+        throw new Error(`Unknown action "${rawAction}": use complete, skip or send-back`);
+      if (action !== "send_back" && (opts.to !== void 0 || opts.note !== void 0))
+        throw new Error("--to and --note go with send-back only");
+      const { arbi } = await resolveWorkspace();
+      const before = await sdk.work.getRunProgress(arbi, conversationId);
+      const plan = before.conversation.plan?.steps ?? [];
+      const step = plan.find((s) => s.id === stepId);
+      if (!step)
+        throw new Error(
+          `No step "${stepId}" in ${conversationId}. Its steps: ${plan.map((s) => s.id).join(", ")}`
+        );
+      const fields = sdk.workflowSteps.stepFields(step);
+      const hasInputs = opts.input.length > 0 || !!opts.inputsFile;
+      if (hasInputs && (action !== "complete" || fields.length === 0))
+        throw new Error(
+          "Only completing a form step, or a step with fields, takes --input / --inputs-file"
+        );
+      const here = before.steps.find((s) => s.id === stepId);
+      if (action !== "skip") {
+        if (step.kind === "agent")
+          throw new Error(
+            action === "complete" ? `"${stepId}" is an agent step: it runs itself. Skip it with: arbi run step ${conversationId} ${stepId} skip` : `"${stepId}" is an agent step: send the work back to it from a person step after it (--to ${stepId})`
+          );
+        if (here.phase === "pending")
+          throw new Error(`"${stepId}" waits for ${here.after.join(", ")} to finish first`);
+        if (here.phase === "done" || here.phase === "skipped")
+          throw new Error(`"${stepId}" is already ${here.phase}`);
+      }
+      let inputs;
+      if (action === "complete" && fields.length) {
+        inputs = gatherInputs(opts.input, opts.inputsFile, fields);
+        if (Array.isArray(step.fields)) {
+          const problems = sdk.workflowSteps.checkStepInputs(step, inputs);
+          if (Object.keys(problems).length)
+            throw new Error(
+              `Cannot complete "${stepId}": ${sdk.workflowSteps.describeInputProblems(step, problems)}. ${fieldsHint(fields)}`
+            );
+        } else {
+          const missing = sdk.workflowSteps.missingRequiredFields(step, {
+            ...before.conversation.skill_inputs ?? {},
+            ...inputs
+          });
+          if (missing.length)
+            throw new Error(
+              `Missing required input${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}. Pass ${missing.map((m) => `--input ${m}=\u2026`).join(" ")}`
+            );
+        }
+      }
+      if (action === "send_back") checkSendBack(plan, stepId, opts.to);
+      await sdk.work.actOnStep(arbi, conversationId, {
+        step: stepId,
+        action,
+        ...inputs && Object.keys(inputs).length ? { inputs } : {},
+        ...action === "send_back" && opts.to ? { to: opts.to } : {},
+        ...action === "send_back" && opts.note?.trim() ? { note: opts.note.trim() } : {}
+      });
+      const progress = await sdk.work.getRunProgress(arbi, conversationId);
+      if (opts.json) {
+        printJson(runJson(progress));
+        return;
+      }
+      if (action === "send_back") {
+        const back = progress.sendBacks.at(-1);
+        success(
+          `Sent "${stepId}" of ${ref(conversationId)} back to "${back?.to ?? opts.to ?? "?"}"${opts.note?.trim() ? " with a note" : ""}; reopened ${back?.reopened.join(", ") ?? ""}`
+        );
+      } else
+        success(
+          `${action === "complete" ? "Completed" : "Skipped"} step "${stepId}" of ${ref(conversationId)}`
+        );
+      dim(nextHint(progress, plan));
+    })()
+  );
+}
 var MARKER_START = "# arbi-cli completion start";
 var MARKER_END = "# arbi-cli completion end";
 var BASH_COMPLETION = `
@@ -10172,12 +10892,12 @@ 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 humanizeTtl(seconds2) {
+  if (!Number.isFinite(seconds2) || seconds2 < 0) return "";
+  if (seconds2 < 60) return `${seconds2}s`;
+  if (seconds2 < 3600) return `${Math.round(seconds2 / 60)}m`;
+  if (seconds2 < 86400) return `${Math.round(seconds2 / 3600)}h`;
+  return `${Math.round(seconds2 / 86400)}d`;
 }
 function registerSessionCommand(program2) {
   const session = program2.command("session").description("List and manage sessions");
@@ -10239,7 +10959,7 @@ function parseAddress(value) {
   const name = match?.[1].replace(/^"|"$/g, "");
   return name ? { email, name } : { email };
 }
-function collect(value, previous = []) {
+function collect2(value, previous = []) {
   return [...previous, ...value.split(",").filter((v) => v.trim())];
 }
 var readTextFile = (path8) => fs7__default.default.readFileSync(path8 === "-" ? 0 : path8, "utf8");
@@ -10265,7 +10985,7 @@ function buildCompose(options) {
   };
 }
 function addComposeOptions(command) {
-  return command.option("--to <addresses>", "Recipient(s), comma-separated or repeated", collect).option("--cc <addresses>", "Cc recipient(s)", collect).option("--bcc <addresses>", "Bcc recipient(s)", collect).option("-s, --subject <subject>", "Subject").option("--text <text>", "Plain-text body").option("--text-file <path>", "Read the plain-text body from a file (- for stdin)").option("--html <html>", "HTML body (the plain text stays as the fallback)").option("--html-file <path>", "Read the HTML body from a file (- for stdin)").option("-a, --attach <path>", "Attach a file (repeatable)", (v, prev = []) => [
+  return command.option("--to <addresses>", "Recipient(s), comma-separated or repeated", collect2).option("--cc <addresses>", "Cc recipient(s)", collect2).option("--bcc <addresses>", "Bcc recipient(s)", collect2).option("-s, --subject <subject>", "Subject").option("--text <text>", "Plain-text body").option("--text-file <path>", "Read the plain-text body from a file (- for stdin)").option("--html <html>", "HTML body (the plain text stays as the fallback)").option("--html-file <path>", "Read the HTML body from a file (- for stdin)").option("-a, --attach <path>", "Attach a file (repeatable)", (v, prev = []) => [
     ...prev,
     v
   ]).option("--json", "Output as JSON (recommended for scripting / agents)");
@@ -10532,19 +11252,95 @@ async function resolveProjectId(arbi, explicit) {
   }
   return first;
 }
+var orNull = (value) => value.trim().toLowerCase() === "none" ? null : value;
+function projectPatch(opts) {
+  const body = {};
+  if (opts.budget !== void 0)
+    body.budget = orNull(opts.budget) === null ? null : sdk.projects.parseBudget(opts.budget);
+  if (opts.client !== void 0) body.client = orNull(opts.client);
+  if (opts.clientRef !== void 0) body.client_ref = orNull(opts.clientRef);
+  if (opts.stage !== void 0) body.stage = orNull(opts.stage);
+  if (opts.field?.length) {
+    const fields = {};
+    for (const pair of opts.field) {
+      const eq = pair.indexOf("=");
+      const key = eq > 0 ? pair.slice(0, eq).trim() : "";
+      if (!/^[a-z][a-z0-9_]{0,63}$/.test(key))
+        throw new Error(
+          `Invalid --field "${pair}": use key=value with a key like "matter_type" (lowercase, digits, "_")`
+        );
+      const value = pair.slice(eq + 1);
+      fields[key] = value.trim() === "" ? null : value;
+    }
+    body.fields = fields;
+  }
+  return body;
+}
+async function resolveProject(arbi, selector) {
+  const res = resolveByIdOrName(await sdk.projects.listProjects(arbi), selector);
+  if (!res.ok) failResolveAndExit("Project", selector, res);
+  return res.item;
+}
+var PERSON_ID = /^(?:usr|agt)-[a-zA-Z0-9]{8}$/;
+async function resolveLead(value) {
+  if (orNull(value) === null) return null;
+  if (PERSON_ID.test(value)) return value;
+  if (!value.includes("@"))
+    throw new Error(`--lead takes a person id (usr-\u2026), an email, or none; got "${value}"`);
+  const { arbi } = await resolveWorkspace();
+  const users = await sdk.workspaces.listWorkspaceUsers(arbi);
+  const found = users.find((u) => u.user.email.toLowerCase() === value.toLowerCase());
+  if (!found) {
+    error(
+      `No one with the email ${value} in the open workspace. Pass their id (usr-\u2026), or open a workspace they are in.`
+    );
+    process.exit(3);
+  }
+  return found.user.external_id;
+}
+function eventValue(event, side) {
+  const detail = event.detail ?? {};
+  const value = detail[side === "old" ? "from" : "to"];
+  if (value === null || value === void 0) return "\u2014";
+  if (typeof value === "object")
+    return sdk.projects.formatBudget(value) || JSON.stringify(value);
+  return String(value);
+}
+function printProjectDetails(p) {
+  label("Budget:", sdk.projects.formatBudget(p.budget) || "\u2014");
+  label("Client:", p.client ?? "\u2014");
+  label("Client ref:", p.client_ref ?? "\u2014");
+  label("Stage:", `${p.stage ?? "\u2014"}${p.stage_changed_at ? ` (since ${p.stage_changed_at})` : ""}`);
+  label("Lead:", p.lead_user ?? "\u2014");
+  const fields = Object.entries(p.fields ?? {});
+  label("Fields:", fields.length ? fields.map(([k, v]) => `${k}=${String(v)}`).join(", ") : "\u2014");
+}
 function registerProjectCommand(program2) {
-  const project = program2.command("project").description("Project tenancy: list, create, rename, update, delete, refresh");
-  project.command("list").description("List your projects").option("--json", "Output as JSON").action(
+  const project = program2.command("project").description(
+    "Project tenancy: list, create, rename, update, set (budget, client, stage, lead, fields), show, events, delete, refresh"
+  );
+  project.command("list").description("List your projects (--stage, --lead to filter)").option("--stage <label>", "Only projects at this stage").option("--lead <usr-id|email>", "Only projects led by this person").option("--json", "Output as JSON").action(
     (opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
-      const data = await sdk.projects.listProjects(arbi);
+      const leadUser = opts.lead ? await resolveLead(opts.lead) ?? void 0 : void 0;
+      const data = await sdk.projects.listProjects(arbi, { stage: opts.stage, leadUser });
       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 ?? "" }
+          { header: "NAME", width: 26, value: (r) => r.name ?? "" },
+          {
+            header: "PLAN",
+            width: 10,
+            value: (r) => r.plan ?? r.subscription ?? ""
+          },
+          { header: "STAGE", width: 16, value: (r) => r.stage ?? "" },
+          {
+            header: "BUDGET",
+            width: 16,
+            value: (r) => sdk.projects.formatBudget(r.budget)
+          },
+          { header: "LEAD", width: 14, value: (r) => r.lead_user ?? "" }
         ],
         data
       );
@@ -10587,6 +11383,69 @@ function registerProjectCommand(program2) {
       success(`Updated project ${ref(id)} (${data.name})`);
     })()
   );
+  project.command("set <project>").description(
+    "Set a project's details: budget, client, client ref, stage, lead and fields (owner only; stage and budget changes become project events)"
+  ).option("--budget <amount+currency>", "Budget, e.g. 6000GBP (none to clear)").option("--client <name>", "Client name (none to clear)").option("--client-ref <id>", "Client record id, e.g. a CRM id (none to clear)").option("--stage <label>", "Stage, e.g. Discovery (none to clear)").option(
+    "--lead <usr-id|email>",
+    "Lead: a member of one of its workspaces, by id or email (none to clear)"
+  ).option("--field <key=value>", "A field (repeatable; key= removes it)", collect, []).option("--json", "Output as JSON").action(
+    (selector, opts) => runAction(async () => {
+      const body = projectPatch(opts);
+      if (Object.keys(body).length === 0 && !opts.lead)
+        throw new Error(
+          "Nothing to set. Pass --budget, --client, --client-ref, --stage, --lead and/or --field"
+        );
+      const { arbi } = await resolveAuth();
+      const target = await resolveProject(arbi, selector);
+      if (opts.lead !== void 0) body.lead_user = await resolveLead(opts.lead);
+      const data = await sdk.projects.updateProject(arbi, target.external_id, body);
+      if (opts.json) {
+        printJson(data);
+        return;
+      }
+      success(`Updated project ${data.name} (${ref(data.external_id)})`);
+      printProjectDetails(data);
+    })()
+  );
+  project.command("show <project>").description("A project's details: budget, client, stage, lead and fields").option("--json", "Output as JSON").action(
+    (selector, opts) => runAction(async () => {
+      const { arbi } = await resolveAuth();
+      const data = await resolveProject(arbi, selector);
+      if (opts.json) {
+        printJson(data);
+        return;
+      }
+      bold(`${data.name} (${data.external_id})`);
+      printProjectDetails(data);
+    })()
+  );
+  project.command("events <project>").description("A project's stage and budget changes, newest first").option("--kind <kind>", "Only stage_changed or budget_changed").option("--limit <n>", "At most this many (default 100)").option("--json", "Output as JSON").action(
+    (selector, opts) => runAction(async () => {
+      if (opts.kind && !["stage_changed", "budget_changed"].includes(opts.kind))
+        throw new Error("--kind must be stage_changed or budget_changed");
+      const limit = opts.limit === void 0 ? void 0 : Number(opts.limit);
+      if (limit !== void 0 && (!Number.isInteger(limit) || limit < 1 || limit > 1e3))
+        throw new Error("--limit must be a whole number from 1 to 1000");
+      const { arbi } = await resolveAuth();
+      const target = await resolveProject(arbi, selector);
+      const events = await sdk.projects.listProjectEvents(arbi, target.external_id, {
+        kind: opts.kind,
+        limit
+      });
+      if (!emitListOrTable(events, opts, `No stage or budget changes on ${target.name} yet.`))
+        return;
+      printTable(
+        [
+          { header: "WHEN", width: 26, value: (r) => r.created_at },
+          { header: "CHANGE", width: 16, value: (r) => r.kind },
+          { header: "FROM", width: 22, value: (r) => eventValue(r, "old") },
+          { header: "TO", width: 22, value: (r) => eventValue(r, "new") },
+          { header: "BY", width: 14, value: (r) => r.actor ?? "" }
+        ],
+        events
+      );
+    })()
+  );
   project.command("delete <id>").description("Delete a project (irreversible; requires an explicit id)").action(
     (id) => runAction(async () => {
       const { arbi } = await resolveAuth();
@@ -10718,10 +11577,104 @@ function registerFilesCommand(program2) {
     await files.commands.find((c) => c.name() === "list").parseAsync(tail, { from: "user" });
   });
 }
-
-// src/commands/usage.ts
+var credits = (n) => `${n.toLocaleString("en", { maximumFractionDigits: 2 })} credits`;
+function breakdownRows(breakdown, name = (k) => k) {
+  return Object.entries(breakdown).sort(([, a], [, b]) => b.spend - a.spend).map(([key, b]) => [
+    name(key),
+    credits(b.spend),
+    b.total_tokens.toLocaleString("en"),
+    String(b.requests)
+  ]);
+}
+function printBreakdown(title, breakdown, name) {
+  console.log("");
+  bold(title);
+  const rows = breakdownRows(breakdown, name);
+  if (!rows.length) {
+    dim("  (nothing recorded)");
+    return;
+  }
+  for (const line of renderTable(["", "SPEND", "TOKENS", "REQUESTS"], rows, 40))
+    console.log(`  ${line}`);
+}
 function registerUsageCommand(program2) {
-  const usage = program2.command("usage").description("Show today's usage against the daily cap");
+  const usage = program2.command("usage").description(
+    "Usage and spend: today's against the daily cap, a conversation's by step, model and agent, a project's by conversation"
+  );
+  usage.command("conversation <con-id>").description(
+    "What a conversation's AI work cost this billing period: by step, model and agent (also by run and feature in --json)"
+  ).option("--json", "Output as JSON").action(
+    (conversationId, opts) => runAction(async () => {
+      const { arbi } = await resolveWorkspace();
+      const data = await sdk.work.getConversationUsage(arbi, conversationId);
+      if (opts.json) {
+        printJson(data);
+        return;
+      }
+      bold(`Conversation ${data.conversation_ext_id} (project ${data.project_ext_id})`);
+      label("Period:", `${data.period_start} \u2192 ${data.period_end}`);
+      label("Spend:", credits(data.total_spend));
+      label("Tokens:", data.total_tokens.toLocaleString("en"));
+      label("Requests:", String(data.total_requests));
+      printBreakdown("By step", data.by_step);
+      printBreakdown(
+        "By run (each run of the thread: a send-back runs a step again)",
+        data.by_run
+      );
+      printBreakdown("By model", data.by_model);
+      printBreakdown("By agent", data.by_agent);
+    })()
+  );
+  usage.command("project <project>").description(
+    "A project's spend this billing period (--by-conversation: per conversation, plus what none accounts for)"
+  ).option("--by-conversation", "Break the spend down by conversation").option("--months-back <n>", "0 = this billing period (default), 1 = the one before, \u2026").option("--json", "Output as JSON").action(
+    (selector, opts) => runAction(async () => {
+      const monthsBack = opts.monthsBack === void 0 ? void 0 : Number(opts.monthsBack);
+      if (monthsBack !== void 0 && (!Number.isInteger(monthsBack) || monthsBack < 0))
+        throw new Error("--months-back must be a whole number, 0 or more");
+      const { arbi } = await resolveAuth();
+      const res = resolveByIdOrName(await sdk.projects.listProjects(arbi), selector);
+      if (!res.ok) failResolveAndExit("Project", selector, res);
+      const projectId = res.item.external_id;
+      if (!opts.byConversation) {
+        const data2 = await sdk.projects.getProjectUsage(arbi, projectId, monthsBack);
+        if (opts.json) {
+          printJson(data2);
+          return;
+        }
+        bold(`Project ${res.item.name} (${projectId})`);
+        label("Period:", `${data2.period_start} \u2192 ${data2.period_end}`);
+        label("Spend:", credits(data2.total_spend));
+        label("Tokens:", data2.total_tokens.toLocaleString("en"));
+        dim(`By conversation: arbi usage project ${projectId} --by-conversation`);
+        return;
+      }
+      const data = await sdk.projects.getProjectConversationUsage(arbi, projectId, monthsBack);
+      if (opts.json) {
+        printJson(data);
+        return;
+      }
+      const titles = /* @__PURE__ */ new Map();
+      if (getConfig()?.selectedWorkspaceId)
+        try {
+          const { arbi: ws } = await resolveWorkspace();
+          for (const c of await sdk.conversations.listConversations(ws))
+            if (c.title) titles.set(c.external_id, c.title);
+        } catch {
+        }
+      bold(`Project ${res.item.name} (${projectId})`);
+      label("Period:", `${data.period_start} \u2192 ${data.period_end}`);
+      label("Spend:", credits(data.total_spend));
+      printBreakdown(
+        "By conversation",
+        data.by_conversation,
+        (id) => titles.has(id) ? `${id}  ${titles.get(id)}` : id
+      );
+      const u = data.unattributed;
+      if (u.spend || u.requests)
+        dim(`Not in any conversation: ${credits(u.spend)}, ${u.requests} requests`);
+    })()
+  );
   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();
@@ -10997,7 +11950,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.4.75").showHelpAfterError(true).showSuggestionAfterError(true);
+program.name("arbi").description("ARBI CLI \u2014 interact with ARBI from the terminal").version("0.4.77").showHelpAfterError(true).showSuggestionAfterError(true);
 registerConfigCommand(program);
 registerLoginCommand(program);
 registerRegisterCommand(program);
@@ -11027,6 +11980,7 @@ registerAgentCreateCommand(program);
 registerAgentCommand(program);
 registerTaskCommand(program);
 registerWorkflowCommand(program);
+registerRunCommand(program);
 registerCompletionCommand(program);
 registerListenCommand(program);
 registerSessionCommand(program);
@@ -11053,7 +12007,7 @@ applyHelpGroups(program, {
   "Search & ask:": ["ask", "find", "cite", "watch"],
   "Tagging:": ["tags", "doctags"],
   "Conversations & messaging:": ["convo", "dm", "listen", "notifications", "contacts"],
-  "Agents & tasks:": ["agent", "agent-create", "task", "workflow", "agentconfig", "session"],
+  "Agents & tasks:": ["agent", "agent-create", "task", "workflow", "run", "agentconfig", "session"],
   "Account:": ["auth", "usage", "files"],
   "System:": ["health", "models", "settings", "tui", "local", "update"]
 });