@arbidocs/cli 0.4.76 → 0.4.78

package/dist/index.js

@@ -12,8 +12,8 @@ var child_process = require('child_process');
 var client = require('@arbidocs/client');
 var url = require('url');
 var crypto = require('crypto');
-var module$1 = require('module');
 var yaml = require('yaml');
+var module$1 = require('module');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -3695,7 +3695,7 @@ function getLatestVersion(skipCache = false) {
   }
 }
 function getCurrentVersion() {
-  return "0.4.76";
+  return "0.4.78";
 }
 function readChangelog(fromVersion, toVersion) {
   try {
@@ -3748,17 +3748,17 @@ function showChangelog(fromVersion, toVersion) {
 async function checkForUpdates(autoUpdate) {
   try {
     const latest = getLatestVersion();
-    if (!latest || latest === "0.4.76") return;
+    if (!latest || latest === "0.4.78") return;
     if (autoUpdate) {
       warn(`
-Your arbi version is out of date (${"0.4.76"} \u2192 ${latest}). Updating...`);
+Your arbi version is out of date (${"0.4.78"} \u2192 ${latest}). Updating...`);
       child_process.execSync("npm install -g @arbidocs/cli@latest", { stdio: "inherit" });
-      showChangelog("0.4.76", latest);
+      showChangelog("0.4.78", latest);
       console.log(`Updated to ${latest}.`);
     } else {
       warn(
         `
-Your arbi version is out of date (${"0.4.76"} \u2192 ${latest}).
+Your arbi version is out of date (${"0.4.78"} \u2192 ${latest}).
 Run "arbi update" to upgrade, or "arbi update auto" to always stay up to date.`
       );
     }
@@ -3790,10 +3790,10 @@ function markNagShown(latest) {
 function hintUpdateOnError() {
   try {
     const cached = readCache();
-    if (!cached || cached.latest === "0.4.76") return;
+    if (!cached || cached.latest === "0.4.78") return;
     if (!shouldShowNag(cached.latest)) return;
     warn(
-      `Your arbi version is out of date (${"0.4.76"} \u2192 ${cached.latest}). Run "arbi update".`
+      `Your arbi version is out of date (${"0.4.78"} \u2192 ${cached.latest}). Run "arbi update".`
     );
     markNagShown(cached.latest);
   } catch {
@@ -3964,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 {
@@ -8473,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) {
@@ -8489,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);
@@ -8512,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
       );
@@ -8522,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");
@@ -8548,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(
@@ -8615,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" });
@@ -9797,41 +10067,33 @@ function registerTaskCommand(program2) {
     })()
   );
 }
-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) {
+function signalTrigger(name, eventKind, eventFilter) {
+  if (name === void 0) return void 0;
+  if (!sdk.workflowSteps.SIGNAL_NAME_PATTERN.test(name))
     throw new Error(
-      `${path8} is not valid ${ext === ".json" ? "JSON" : "YAML"}: ${err.message}`
+      `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 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];
+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";
 }
-
-// src/commands/workflow.ts
 function registerWorkflowCommand(program2) {
   const workflow = program2.command("workflow").alias("automation").description(
     "Workflows (/v1/workflow): create (optionally with steps), list, update, resume, pause, run, delete"
@@ -9841,7 +10103,10 @@ function registerWorkflowCommand(program2) {
   ).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("--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(
+  ).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"
@@ -9849,6 +10114,11 @@ function registerWorkflowCommand(program2) {
     (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 = {
@@ -9900,6 +10170,17 @@ function registerWorkflowCommand(program2) {
       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}`);
     })()
   );
@@ -9914,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 ?? "" }
         ],
@@ -9983,11 +10269,14 @@ function registerWorkflowCommand(program2) {
       );
     })()
   );
-  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("--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) throw new Error("Pass --steps <file> and/or --file <path>");
+      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),
@@ -10014,6 +10303,8 @@ function runJson(progress, answers = {}) {
   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,
@@ -10026,10 +10317,62 @@ function runJson(progress, answers = {}) {
       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)
@@ -10049,7 +10392,10 @@ function nextHint(progress, planSteps = []) {
         (f) => have[f.name] === void 0 || have[f.name] === null || have[f.name] === ""
       );
       const inputs = fields.map((f) => ` --input ${f.name}=\u2026`).join("");
-      return `Waiting on ${step.kind} step "${step.id}": arbi run step ${id} ${step.id} complete${inputs}`;
+      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");
@@ -10060,16 +10406,27 @@ function nextHint(progress, planSteps = []) {
 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: "TITLE", width: 40, value: (r) => r.title }
+      { 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;
@@ -10110,6 +10467,48 @@ function seconds(value, flag) {
   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) : {},
@@ -10173,11 +10572,22 @@ function registerRunCommand(program2) {
     })()
   );
   run.command("step <con-id> <step-id> <action>").description(
-    "Act on a step: complete a form, upload or review step (a form takes its inputs), or skip any step"
-  ).option("--input <name=value>", "A form input (repeatable)", collect, []).option("--inputs-file <file>", "Form inputs as a JSON or YAML object").option("--json", "Output as JSON").action(
-    (conversationId, stepId, action, opts) => runAction(async () => {
-      if (action !== "complete" && action !== "skip")
-        throw new Error(`Unknown action "${action}": use complete or skip`);
+    "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 ?? [];
@@ -10186,22 +10596,33 @@ function registerRunCommand(program2) {
         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 === "skip" || step.kind !== "form"))
-        throw new Error("Only completing a form step takes --input / --inputs-file");
-      let inputs;
-      if (action === "complete") {
+      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(
-            `"${stepId}" is an agent step: it runs itself. Skip it with: arbi run step ${conversationId} ${stepId} skip`
+            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})`
           );
-        const phase = before.steps.find((s) => s.id === stepId)?.phase;
-        if (phase === "pending") {
-          const waits = before.steps.find((s) => s.id === stepId)?.after ?? [];
-          throw new Error(`"${stepId}" waits for ${waits.join(", ")} to finish first`);
-        }
-        if (step.kind === "form") {
-          inputs = gatherInputs(opts.input, opts.inputsFile, sdk.workflowSteps.stepFields(step));
+        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
@@ -10212,19 +10633,28 @@ function registerRunCommand(program2) {
             );
         }
       }
+      if (action === "send_back") checkSendBack(plan, stepId, opts.to);
       await sdk.work.actOnStep(arbi, conversationId, {
         step: stepId,
         action,
-        ...inputs && Object.keys(inputs).length ? { inputs } : {}
+        ...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;
       }
-      success(
-        `${action === "complete" ? "Completed" : "Skipped"} step "${stepId}" of ${ref(conversationId)}`
-      );
+      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));
     })()
   );
@@ -10822,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
       );
@@ -10877,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();
@@ -11008,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();
@@ -11287,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.76").showHelpAfterError(true).showSuggestionAfterError(true);
+program.name("arbi").description("ARBI CLI \u2014 interact with ARBI from the terminal").version("0.4.78").showHelpAfterError(true).showSuggestionAfterError(true);
 registerConfigCommand(program);
 registerLoginCommand(program);
 registerRegisterCommand(program);