quoxcli 0.4.0 → 0.6.0

package/lib/commands/loop.js

@@ -29,6 +29,32 @@ function toMs(ts) {
   return Number.isNaN(n) ? null : n;
 }
 
+const LIVE_STATES = new Set(['pending', 'starting', 'decomposing', 'running', 'waiting']);
+
+/**
+ * One row, one vocabulary. The list route counts turn events, which loops driven by the runner never write, so a
+ * finished loop could read 0 there. The server now sends a real 0 (started, ran nothing) and null (no record at
+ * all); a number from the server is kept, null stays unknown unless the loop is live. objective_status is the objective row's word ('cancelled' for a
+ * human halt); `state` is the loop's, so the row says one thing and the raw word is kept as objective_row_status.
+ */
+export function normLoop(l) {
+  const n = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Number(v) : 0);
+  const count = n(l.turn) || n(l.iteration_count);
+  // the server's turn is authoritative: a real 0 (started, ran nothing) stays 0; only null/absent means unknown
+  const turn = count || (l.turn === 0 || LIVE_STATES.has(l.state) ? 0 : null);
+  const out = { ...l, turn };
+  if (l.objective_status !== undefined && l.state && l.objective_status !== l.state) {
+    out.objective_row_status = l.objective_status;
+    out.objective_status = l.state;
+  }
+  return out;
+}
+
+function turnLabel(l) {
+  if (l.turn === null) return '-';
+  return l.max_turns ? `${l.turn}/${l.max_turns}` : String(l.turn);
+}
+
 const SETTLE_MAX_MS = 90000;
 const SETTLE_POLL_MS = 4000;
 
@@ -149,7 +175,7 @@ function oneLineErr(err) {
 
 export function statusLines(s, { diagnostics = false } = {}) {
   const lines = [];
-  const turns = `turn ${s.turn}${s.max_turns ? `/${s.max_turns}` : ''}`;
+  const turns = `turn ${s.turn === null || s.turn === undefined ? '-' : s.turn}${s.max_turns ? `/${s.max_turns}` : ''}`;
   lines.push(loopLine(s.title || s.objective_id, `${s.state}, ${turns}`, s.state === 'running' ? 'busy' : (s.state === 'completed' ? 'ok' : (s.state === 'completed_with_errors' || s.state === 'halted' || s.state === 'interrupted' ? 'warn' : (s.finished ? 'fail' : 'busy')))));
   lines.push(`  id        ${s.objective_id}`);
   lines.push(`  host      ${s.host || '-'}   backend ${s.backend || '-'}   scope ${(s.scope || []).join(',') || '-'}`);
@@ -240,11 +266,12 @@ export function registerLoopCommands(program, ctx) {
       auth.requireAuth();
       const ep = resolveEndpoint('loops.list');
       const data = await client.get(ep.path, { service: ep.service, query: { limit: options.limit } });
+      const loops = (data.loops || []).map(normLoop);
       formatOutput({
         columns: ['objective_id', 'title', 'state', 'turn', 'backend', 'created_at'],
         headers: ['ID', 'Title', 'State', 'Turn', 'Backend', 'Created'],
-        rows: (data.loops || []).map((l) => ({ ...l, turn: l.max_turns ? `${l.turn}/${l.max_turns}` : String(l.turn) })),
-      }, { format: program.opts().output, emptyMessage: 'No loops in this org yet.' });
+        rows: loops.map((l) => ({ ...l, turn: turnLabel(l) })),
+      }, { format: program.opts().output, raw: loops, emptyMessage: 'No loops in this org yet.' });
     });
 
   // SECURITY containment (2026-10-26): which orgs may run loops in-server (core-local) while a security review is open.

package/lib/commands/lucid.js

@@ -9,12 +9,14 @@
  *   quox lucid teach <target> <field>=<value> | lessons | forget <id>
  *   quox lucid herald [set key=value... | test]   when LUCID speaks first, and what it has said
  *   quox lucid blind          sources live/silent/failing/never heard, and what doesn't add up
+ *   quox lucid goals ...      your goals and decisions, so LUCID ranks against them (see lucidGoals.js)
  */
 import { formatOutput, printSuccess } from '../core/output.js';
 import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { confirmDestructive } from '../core/confirm.js';
 import { resolveOrgId } from './helpers.js';
+import { registerLucidGoalsCommands, registerLucidInsightsCommands, registerLucidBriefCommand } from './lucidGoals.js';
 
 const SURFACE = 'cli';
 
@@ -105,6 +107,7 @@ export function registerLucidCommands(program, ctx) {
     if (o.markdown) { const { renderSitrepMarkdown } = await import('../lucid/markdown.js'); console.log(renderSitrepMarkdown(data)); return; }
     const { renderSitrep } = await import('../lucid/sitrep.js');
     const tty = Boolean(process.stdout.isTTY);
+    if (tty) process.stderr.write('Tip: for a shorter form use --spoken (sentences), --agent (compact) or --markdown (one chat message).\n');
     process.stdout.write(renderSitrep(data, {
       width: process.stdout.columns || 100,
       color: tty && !process.env.NO_COLOR && process.env.QUOX_COLOR !== '0',
@@ -504,6 +507,10 @@ export function registerLucidCommands(program, ctx) {
       if (st.length) console.log(`Stats: ${st.map(([k, v]) => `${k}=${Array.isArray(v) ? v.join(',') : v}`).join(' · ')}`);
     });
 
+  registerLucidGoalsCommands(lu, program, ctx);
+  registerLucidInsightsCommands(lu, program, ctx);
+  registerLucidBriefCommand(lu, program, ctx);
+
   // ---- herald: when LUCID reaches out on its own ----
   const LEVELS = { l1_inbox: 'filed in your Approvals inbox', l2_slot: 'nudged you in your slot', l3_call: 'called you', resolved: 'resolved' };
   const levelWords = (l) => LEVELS[l] || l || 'not yet reached out';

package/lib/commands/lucidGoals.js

@@ -0,0 +1,389 @@
+/**
+ * `quox lucid goals`: LUCID's World Model (LUCID-INTELLIGENCE LI-1). What you are trying to do,
+ * in your words, so LUCID can rank what matters against it instead of narrating telemetry.
+ *
+ *   quox lucid goals                       your active goals (and anything an agent proposed)
+ *   quox lucid goals add "<outcome>"       a goal; --priority, --by <date>, --success "<criteria>", --watch <refs>, --shared
+ *   quox lucid goals add --as decision "<question>"   also: initiative "<title>", actor "<name>"
+ *   quox lucid goals link <from> <to>      --relation blocks|requires|related
+ *   quox lucid goals show|history <id>
+ *   quox lucid goals change <id> key=value...   your correction (it wins, and stays confirmed)
+ *   quox lucid goals confirm <id>          accept something an agent proposed
+ *   quox lucid goals archive|restore <id>
+ *   quox lucid goals export [--out <file>]
+ *   quox lucid goals erase                 delete your personal World Model (asks first)
+ *
+ * What you add is CONFIRMED. What an agent adds is only PROPOSED until you confirm it.
+ */
+import fs from 'fs';
+import { formatOutput, printSuccess } from '../core/output.js';
+import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { confirmDestructive } from '../core/confirm.js';
+import { resolveOrgId } from './helpers.js';
+
+const KINDS = ['goal', 'initiative', 'decision', 'dependency', 'actor'];
+// Which field the free text fills for each kind.
+const TEXT_FIELD = { goal: 'outcome', initiative: 'title', decision: 'question', actor: 'name' };
+
+function coerce(v) {
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (v === 'null') return null;
+  return /^-?\d+(\.\d+)?$/.test(v) ? Number(v) : v;
+}
+
+/** The one-line, human description of an entity. */
+export function describeEntity(e) {
+  const text = e.outcome || e.title || e.question || e.name
+    || (e.kind === 'dependency' ? `${e.from} ${e.relation || 'related'} ${e.to}` : '') || e.id;
+  return String(text);
+}
+
+export function standingOf(e) {
+  const s = e.provenance && e.provenance.inference_status;
+  return s === 'confirmed' ? 'yours' : s === 'proposed' ? 'proposed, needs you' : s || '';
+}
+
+export function parsePairs(pairs) {
+  const patch = {};
+  for (const p of pairs) {
+    const eq = p.indexOf('=');
+    if (eq < 1) throw new Error(`expected key=value, got "${p}"`);
+    patch[p.slice(0, eq)] = coerce(p.slice(eq + 1));
+  }
+  return patch;
+}
+
+export function registerLucidGoalsCommands(lu, program, ctx) {
+  const { client, auth } = ctx;
+  const wantJson = (cmd) => {
+    const o = cmd.optsWithGlobals ? cmd.optsWithGlobals() : cmd.opts();
+    return Boolean(o.json) || program.opts().output === 'json';
+  };
+  const announce = (verb, result) => printEvent(glyphLine('lucid', verb, { result }).replace('Ⓠ', '◉'));
+
+  // An error body is not data: report the status and the server's reason, and stop.
+  async function call(key, { params, query, body } = {}) {
+    const ep = resolveEndpoint(key, params);
+    const q = { org_id: resolveOrgId(auth, program), ...query };
+    const method = { GET: 'get', POST: 'post', PATCH: 'patch', DELETE: 'delete' }[ep.method] || 'get';
+    try {
+      return await client[method](ep.path, { service: ep.service, query: q, ...(body !== undefined ? { body } : {}) });
+    } catch (err) {
+      const status = err && (err.status || err.statusCode);
+      if (status) {
+        const why = (err.body && (err.body.message || err.body.error)) || err.message || '';
+        console.error(`LUCID goals request failed: HTTP ${status}${why ? ` ${why}` : ''}`);
+        process.exitCode = 1;
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  function table(entities) {
+    formatOutput(entities.map((e) => ({
+      ID: e.id,
+      KIND: e.kind,
+      WHAT: describeEntity(e),
+      PRIORITY: e.priority || '',
+      STANDING: standingOf(e),
+      SHARED: e.scope && e.scope.type === 'org' ? 'org' : '',
+    })), {
+      format: program.opts().output,
+      columns: ['ID', 'KIND', 'WHAT', 'PRIORITY', 'STANDING', 'SHARED'],
+      emptyMessage: 'Nothing yet. Tell LUCID what you are working towards: quox lucid goals add "<what you want to be true>"',
+      raw: entities,
+    });
+  }
+
+  const goals = lu
+    .command('goals')
+    .alias('world')
+    .description("LUCID's World Model: your goals, initiatives and decisions, so it ranks what matters against them")
+    .option('--kind <kind>', `only one kind (${KINDS.join('|')})`)
+    .option('--archived', 'show archived instead of active')
+    .option('--all', 'active and archived')
+    .option('--proposed', 'only what an agent proposed and you have not confirmed')
+    .option('--json', 'print the full JSON response')
+    .action(async (options, cmd) => {
+      auth.requireAuth();
+      const data = await call('lucid.world.list', { query: {
+        kind: options.kind,
+        lifecycle: options.all ? 'all' : options.archived ? 'archived' : 'active',
+        status: options.proposed ? 'proposed' : undefined,
+      } });
+      if (data === null) return;
+      if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+      const es = data.entities || [];
+      const proposed = es.filter((e) => standingOf(e) === 'proposed, needs you').length;
+      announce('goals', `${es.length} held${proposed ? ` · ${proposed} proposed` : ''}`);
+      table(es);
+    });
+
+  goals
+    .command('add <text...>')
+    .description('Add a goal (or, with --as, an initiative, decision or actor). Yours, so it is confirmed')
+    .option('--as <kind>', 'goal (default), initiative, decision, actor', 'goal')
+    .option('--priority <band>', 'critical|high|normal|low')
+    .option('--by <date>', 'deadline, e.g. 2026-11-30')
+    .option('--success <criteria>', 'how you will know it is done')
+    .option('--shared', 'share with the whole org (org admins only)')
+    .option('--watch <refs>', 'what it depends on, so LUCID can tie problems to it, e.g. site:shop,unit:billing.service or site:*')
+    .option('--json', 'print the full JSON response')
+    .action(async (words, options, cmd) => {
+      auth.requireAuth();
+      const kind = String(options.as || 'goal');
+      if (!TEXT_FIELD[kind]) {
+        console.error(`--as must be one of ${Object.keys(TEXT_FIELD).join('|')} (use "goals link" for a dependency)`);
+        process.exitCode = 1;
+        return;
+      }
+      const body = { kind, [TEXT_FIELD[kind]]: words.join(' '), scope: options.shared ? 'org' : 'user', source_ref: 'cli:quox lucid goals add' };
+      if (options.priority) body.priority = options.priority;
+      if (options.by) body.deadline = options.by;
+      if (options.success) body.success_criteria = options.success;
+      if (options.watch) body.watches = String(options.watch).split(',').map((x) => x.trim()).filter(Boolean);
+      if (kind === 'decision') body.status = 'open';
+      const data = await call('lucid.world.create', { body });
+      if (data === null) return;
+      if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+      const e = data.entity;
+      announce('goals add', `${e.kind} ${e.id} · ${standingOf(e)}`);
+      printSuccess(`${describeEntity(e)} (${e.id})`);
+    });
+
+  goals
+    .command('link <from> <to>')
+    .description('Record that one thing depends on another')
+    .option('--relation <relation>', 'blocks|requires|related', 'blocks')
+    .option('--json', 'print the full JSON response')
+    .action(async (from, to, options, cmd) => {
+      auth.requireAuth();
+      const data = await call('lucid.world.create', { body: { kind: 'dependency', from, to, relation: options.relation, source_ref: 'cli:quox lucid goals link' } });
+      if (data === null) return;
+      if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+      printSuccess(`Linked: ${describeEntity(data.entity)} (${data.entity.id})`);
+    });
+
+  goals
+    .command('show <id>')
+    .description('One entity, with who said it and when')
+    .option('--json', 'print the full JSON response')
+    .action(async (id, _o, cmd) => {
+      auth.requireAuth();
+      const data = await call('lucid.world.get', { params: { id } });
+      if (data === null) return;
+      if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+      const e = data.entity;
+      const p = e.provenance || {};
+      console.log(`${describeEntity(e)}`);
+      console.log(`  ${e.kind}, ${standingOf(e)}${e.priority ? `, priority ${e.priority}` : ''}${e.deadline ? `, by ${e.deadline}` : ''}`);
+      if (e.success_criteria) console.log(`  Done when: ${e.success_criteria}`);
+      console.log(`  From: ${p.source_type || '?'} (${p.source_ref || '?'}) at ${p.observed_at || '?'}`);
+      console.log(`  ${e.lifecycle}, version ${e.version}, ${e.scope && e.scope.type === 'org' ? 'shared with the org' : 'private to you'}`);
+    });
+
+  goals
+    .command('history <id>')
+    .description('Every version of an entity: who changed it and how')
+    .option('--json', 'print the full JSON response')
+    .action(async (id, _o, cmd) => {
+      auth.requireAuth();
+      const data = await call('lucid.world.history', { params: { id } });
+      if (data === null) return;
+      if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+      formatOutput((data.history || []).map((h) => ({ V: h.version, WHAT: h.op, BY: `${h.actor_kind}${h.actor_id ? ` ${h.actor_id}` : ''}`, AT: h.at, TEXT: describeEntity(h.entity) })), {
+        format: program.opts().output, columns: ['V', 'WHAT', 'BY', 'AT', 'TEXT'], emptyMessage: 'No history.', raw: data.history,
+      });
+    });
+
+  goals
+    .command('change <id> <pairs...>')
+    .description('Correct an entity, e.g. quox lucid goals change wm_x outcome="Orders by the 20th" priority=high')
+    .option('--json', 'print the full JSON response')
+    .action(async (id, pairs, _o, cmd) => {
+      auth.requireAuth();
+      let patch;
+      try { patch = parsePairs(pairs); } catch (e) { console.error(e.message); process.exitCode = 1; return; }
+      const data = await call('lucid.world.amend', { params: { id }, body: { patch } });
+      if (data === null) return;
+      if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+      printSuccess(`Changed (version ${data.entity.version}): ${describeEntity(data.entity)}`);
+    });
+
+  for (const [verb, key, done] of [['confirm', 'lucid.world.confirm', 'Confirmed'], ['archive', 'lucid.world.archive', 'Archived'], ['restore', 'lucid.world.restore', 'Restored']]) {
+    goals
+      .command(`${verb} <id>`)
+      .description({ confirm: 'Accept something an agent proposed, so LUCID treats it as yours', archive: 'Set aside (kept, with history)', restore: 'Bring back an archived entity' }[verb])
+      .option('--json', 'print the full JSON response')
+      .action(async (id, _o, cmd) => {
+        auth.requireAuth();
+        const data = await call(key, { params: { id }, body: {} });
+        if (data === null) return;
+        if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+        printSuccess(`${done}: ${describeEntity(data.entity)}`);
+      });
+  }
+
+  goals
+    .command('export')
+    .description('Everything LUCID holds for you, with full history, as JSON')
+    .option('--out <file>', 'write to a file instead of stdout')
+    .action(async (options) => {
+      auth.requireAuth();
+      const data = await call('lucid.world.export');
+      if (data === null) return;
+      const text = JSON.stringify(data, null, 2);
+      if (options.out) { fs.writeFileSync(options.out, `${text}\n`, { mode: 0o600 }); printSuccess(`Exported ${(data.entities || []).length} entities to ${options.out}`); return; }
+      console.log(text);
+    });
+
+  goals
+    .command('erase')
+    .description('Delete your personal World Model and its history (shared org entities stay)')
+    .option('--yes', 'skip the confirmation prompt')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ok = await confirmDestructive(program, { force: options.yes === true }, 'Erase every personal goal, initiative and decision LUCID holds for you, with their history?');
+      if (!ok) return;
+      const data = await call('lucid.world.erase', { body: { confirm: 'erase' } });
+      if (data === null) return;
+      printSuccess(`Erased ${data.erased} personal ${data.erased === 1 ? 'entity' : 'entities'}.`);
+    });
+}
+
+/** Plain standing for an insight. */
+export function insightStanding(i) {
+  if (i.status === 'retracted') return 'resolved';
+  if (i.status === 'supported') return 'you linked it';
+  return 'a guess, not linked';
+}
+
+/**
+ * `quox lucid insights` (LUCID-INTELLIGENCE LI-2, SHADOW): what LUCID would tie to your goals.
+ * Nothing here reaches you on its own yet; this is how to look at it and compare it with
+ * today's brief before LI-3 lets it shape what LUCID says.
+ */
+export function registerLucidInsightsCommands(lu, program, ctx) {
+  const { client, auth } = ctx;
+  const wantJson = (cmd) => {
+    const o = cmd.optsWithGlobals ? cmd.optsWithGlobals() : cmd.opts();
+    return Boolean(o.json) || program.opts().output === 'json';
+  };
+  async function get(key, { params, query } = {}) {
+    const ep = resolveEndpoint(key, params);
+    try {
+      return await client.get(ep.path, { service: ep.service, query: { org_id: resolveOrgId(auth, program), ...query } });
+    } catch (err) {
+      const status = err && (err.status || err.statusCode);
+      if (status) {
+        console.error(`LUCID insights request failed: HTTP ${status}${err.message ? ` ${err.message}` : ''}`);
+        process.exitCode = 1;
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  const ins = lu
+    .command('insights')
+    .description('SHADOW: what LUCID would tie to your goals, compared with what it tells you today')
+    .option('--retracted', 'include resolved ones')
+    .option('--json', 'print the full JSON response')
+    .action(async (options, cmd) => {
+      auth.requireAuth();
+      const data = await get('lucid.insights.list', { query: { retracted: options.retracted ? '1' : undefined } });
+      if (data === null) return;
+      if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+      const list = data.insights || [];
+      // The shadow comparison: today's brief beside the goal-linked view.
+      const sit = await get('lucid.situation', { query: { since: 'last', surface: 'cli' } });
+      const needs = sit && sit.situation ? (sit.situation.needs_you || []).length : null;
+      const tied = new Set(list.filter((i) => i.status !== 'retracted').map((i) => i.subject));
+      printEvent(glyphLine('lucid', 'insights', { result: `${list.length} shadow · ${needs === null ? '?' : needs} in today's brief` }).replace('Ⓠ', '◉'));
+      if (needs !== null) console.log(`Today LUCID says ${needs} ${needs === 1 ? 'thing needs' : 'things need'} you. ${tied.size} of what it sees ${tied.size === 1 ? 'touches' : 'touch'} a goal you set. (Shadow: this does not change what LUCID says yet.)\n`);
+      formatOutput(list.map((i) => ({
+        ID: i.id,
+        WHAT: i.headline,
+        WHY: (i.observations && i.observations[0] && i.observations[0].text) || '',
+        PRIORITY: (i.priority && i.priority.band) || '',
+        LINK: insightStanding(i),
+      })), {
+        format: program.opts().output,
+        columns: ['ID', 'WHAT', 'WHY', 'PRIORITY', 'LINK'],
+        emptyMessage: 'Nothing ties to your goals right now. (No goals yet? quox lucid goals add "<what you want to be true>". Link one to what it depends on: quox lucid goals change <id> watches=site:<name>)',
+        raw: list,
+      });
+    });
+
+  ins
+    .command('show <id>')
+    .description('One insight: what was seen, what LUCID makes of it, how sure, and the evidence')
+    .option('--json', 'print the full JSON response')
+    .action(async (id, _o, cmd) => {
+      auth.requireAuth();
+      const data = await get('lucid.insights.get', { params: { id } });
+      if (data === null) return;
+      if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+      const i = data.insight;
+      console.log(i.headline);
+      for (const o of i.observations || []) console.log(`  Seen: ${o.text} (evidence ${o.source_ref}, ${o.observed_at})`);
+      if (i.interpretation) console.log(`  Reading: ${i.interpretation.text} (${i.interpretation.classification}, ${i.interpretation.confidence} confidence)`);
+      for (const l of (i.interpretation && i.interpretation.limitations) || []) console.log(`  Limit: ${l}`);
+      if (i.priority) console.log(`  Why it ranks ${i.priority.band}: ${i.priority.why}`);
+      console.log(`  ${insightStanding(i)}${i.retracted_at ? `, resolved ${i.retracted_at}` : ''}`);
+    });
+
+  ins
+    .command('status')
+    .description("The shadow worker's health for your org: runs, skips, failures, last error")
+    .option('--json', 'print the full JSON response')
+    .action(async (_o, cmd) => {
+      auth.requireAuth();
+      const data = await get('lucid.insights.status');
+      if (data === null) return;
+      if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+      const w = data.worker || {};
+      console.log(`Runs ${w.runs}, skipped (nothing new) ${w.skipped}, failures ${w.failures}${w.consecutive_failures ? ` (${w.consecutive_failures} in a row)` : ''}.`);
+      console.log(`Last run ${w.last_run_at || 'never'}: found ${w.last_found}, rejected for bad evidence ${w.last_rejected}.`);
+      if (w.last_error) console.log(`Last error: ${w.last_error}${w.next_run_at ? ` (next try ${w.next_run_at})` : ''}`);
+    });
+}
+
+/**
+ * `quox lucid brief` (LUCID-INTELLIGENCE LI-3): the short answer to "what's going on". Your goals
+ * first, then what waits on you, then what went wrong today, then what LUCID cannot see. Never
+ * moves a cursor. --spoken gives exactly what the phone says.
+ */
+export function registerLucidBriefCommand(lu, program, ctx) {
+  const { client, auth } = ctx;
+  lu
+    .command('brief')
+    .description("The short brief: what matters now, in plain words (your goals first; never moves a cursor)")
+    .option('--spoken', 'exactly what the phone would say')
+    .option('--detail <n>', '1 headline only, 2 normal, 3 adds reasons and drill-down refs', '2')
+    .option('--json', 'print the full JSON response')
+    .action(async (options, cmd) => {
+      auth.requireAuth();
+      // `lucid --spoken` also exists on the parent, so read the merged options (commander hands it to the parent).
+      const all = cmd.optsWithGlobals ? cmd.optsWithGlobals() : options;
+      const spoken = Boolean(options.spoken || all.spoken);
+      const ep = resolveEndpoint('lucid.brief');
+      let data;
+      try {
+        data = await client.get(ep.path, { service: ep.service, query: { org_id: resolveOrgId(auth, program), surface: spoken ? 'voice' : 'cli', detail: options.detail } });
+      } catch (err) {
+        const status = err && (err.status || err.statusCode);
+        if (status) { console.error(`LUCID brief request failed: HTTP ${status}${err.message ? ` ${err.message}` : ''}`); process.exitCode = 1; return; }
+        throw err;
+      }
+      const o = cmd.optsWithGlobals ? cmd.optsWithGlobals() : cmd.opts();
+      if (o.json || program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      const b = (data && data.brief) || {};
+      printEvent(glyphLine('lucid', 'brief', { result: `${(b.items || []).length} item${(b.items || []).length === 1 ? '' : 's'}${b.more_available ? ` · ${b.more_available} more` : ''}` }).replace('Ⓠ', '◉'));
+      console.log(b.text || '');
+      if (b.degraded && b.degraded.length) console.error(`(${b.degraded.join(', ')}: this brief is from the situation alone)`);
+    });
+}