quoxcli 0.2.0 → 0.3.1

package/lib/quoxon/bang.js

@@ -0,0 +1,224 @@
+/**
+ * QUOXON-FW8: "!" commands. A line that starts with `!` runs on THIS machine, in the session cwd, and its output
+ * is shown inline. It never reaches the model (no turn, no server call) and needs no approval card: it is the
+ * user's own action on their own machine. Pure parsing plus one process runner; app.js owns the display.
+ *
+ *   !<shell command>        run via $SHELL -lc
+ *   !quox <args> / !q <args> run THIS quox binary (not whatever is on PATH) with the current profile injected
+ *   !!                       reserved (refused with a note)
+ *
+ * BANG-TTY (owner 2026-10-16): capture stays the default (so /share works), but a known interactive command
+ * (needsTerminal, e.g. quox lucid deck, vim, top) or a captured run that failed for want of a terminal (ttyFailure)
+ * is handed the terminal, the same way a slot run request is.
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+export const MAX_LINES = 2000;
+export const MAX_BYTES = 256 * 1024;
+export const SHARE_MAX_BYTES = 16 * 1024;
+export const DEFAULT_TIMEOUT_MS = 120000;
+export const KILL_GRACE_MS = 2000;
+export const QUOX_ENTRY = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'quox.js');
+
+/** -> null (not a bang line) | { kind: 'reserved' | 'empty' | 'shell' | 'quox', cmd?, args? } */
+export function parseBang(line) {
+  const t = String(line ?? '').replace(/^\s+/, '');
+  if (!t.startsWith('!')) return null;
+  if (t.startsWith('!!')) return { kind: 'reserved' };
+  const rest = t.slice(1).trim();
+  if (!rest) return { kind: 'empty' };
+  const m = /^(quox|q)(?:\s+([\s\S]*))?$/.exec(rest);
+  if (m) return { kind: 'quox', args: tokenize(m[2] || ''), cmd: rest };
+  return { kind: 'shell', cmd: rest };
+}
+
+/** Minimal shell-ish word split: whitespace, 'single' and "double" quotes, backslash escapes outside single quotes. */
+export function tokenize(s) {
+  const out = []; let cur = ''; let has = false; let q = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (q === "'") { if (ch === "'") q = null; else cur += ch; continue; }
+    if (q === '"') {
+      if (ch === '"') q = null;
+      else if (ch === '\\' && i + 1 < s.length && /["\\$`]/.test(s[i + 1])) cur += s[++i];
+      else cur += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') { q = ch; has = true; continue; }
+    if (ch === '\\' && i + 1 < s.length) { cur += s[++i]; has = true; continue; }
+    if (/\s/.test(ch)) { if (cur || has) out.push(cur); cur = ''; has = false; continue; }
+    cur += ch; has = true;
+  }
+  if (cur || has) out.push(cur);
+  return out;
+}
+
+const hasProfile = (args) => args.some(a => a === '-p' || a === '--profile' || a.startsWith('--profile=') || /^-p.+/.test(a));
+const INTERACTIVE = new Set(['tui', 'quoxon']);
+// quox leaves that draw a full-screen view (first two positional words); `--interactive` anywhere also counts
+const INTERACTIVE_QUOX = new Set(['lucid deck']);
+const INTERACTIVE_FLAG = (a) => a === '--interactive'; // not -i: some leaves use it for other things
+// shell programs that need a terminal whatever their arguments; ssh only when it has no remote command
+const INTERACTIVE_SHELL = new Set(['vim', 'vi', 'nvim', 'nano', 'emacs', 'less', 'more', 'most', 'man', 'top', 'htop', 'btop', 'atop', 'watch', 'tmux', 'screen', 'mc', 'ranger']);
+const SSH_VALUE_FLAGS = new Set(['-b', '-c', '-D', '-E', '-e', '-F', '-I', '-i', '-J', '-L', '-l', '-m', '-O', '-o', '-p', '-Q', '-R', '-S', '-W', '-w', '-B']);
+
+const quoxPositional = (args) => {
+  const pos = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '-p' || a === '--profile') { i++; continue; }
+    if (a.startsWith('-')) continue;
+    pos.push(a);
+  }
+  return pos;
+};
+
+/** -> a short reason when this ! command needs a real terminal (hand it over), else null. */
+export function needsTerminal(bang) {
+  if (!bang || (bang.kind !== 'shell' && bang.kind !== 'quox')) return null;
+  if (bang.kind === 'quox') {
+    const args = bang.args || [];
+    const pos = quoxPositional(args);
+    const info = args.some(a => a === '--help' || a === '-h' || a === '--version' || a === '-V');
+    if (!pos.length || info || INTERACTIVE.has(pos[0])) return null; // bare quox and tui stay refused (quoxArgv): this window IS that app
+    if (INTERACTIVE_QUOX.has(pos.slice(0, 2).join(' '))) return `quox ${pos.slice(0, 2).join(' ')} is interactive`;
+    if (args.some(INTERACTIVE_FLAG)) return 'it asked for --interactive';
+    return null;
+  }
+  const words = tokenize(bang.cmd);
+  let i = 0;
+  while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i])) i++; // FOO=1 less x
+  if (/[|;&<>]/.test(bang.cmd)) return null; // a pipeline or redirect is the user's own plumbing: leave it captured
+  const prog = (words[i] || '').split('/').pop();
+  if (INTERACTIVE_SHELL.has(prog)) return `${prog} is interactive`;
+  if (prog === 'ssh') {
+    const rest = words.slice(i + 1); let host = -1;
+    for (let k = 0; k < rest.length; k++) {
+      if (SSH_VALUE_FLAGS.has(rest[k])) { k++; continue; }
+      if (rest[k].startsWith('-')) continue;
+      host = k; break;
+    }
+    if (host >= 0 && host === rest.length - 1) return 'ssh with no command opens a shell';
+  }
+  return null;
+}
+
+const TTY_FAIL = /needs an interactive terminal|not a tty|inappropriate ioctl|must be run (from|in) a terminal|(input|stdin|stdout) is not a terminal|requires a tty|no tty present/i;
+/** -> true when a captured run failed because it had no terminal (re-run it handed over). */
+export function ttyFailure(r) {
+  if (!r || r.code === 0 || r.code == null || r.timedOut || r.killed) return false;
+  return TTY_FAIL.test(String(r.text || '').slice(-2000));
+}
+
+/** -> { refuse: 'one-line hint' } | { argv: [...] } for process.execPath. */
+export function quoxArgv(args, { profile, entry = QUOX_ENTRY } = {}) {
+  // positional words: skip flags and the value that follows -p/--profile
+  const pos = quoxPositional(args);
+  const info = args.some(a => a === '--help' || a === '-h' || a === '--version' || a === '-V');
+  const inject = profile && !hasProfile(args) ? ['-p', profile] : [];
+  const argv = [entry, ...inject, ...args];
+  // refuse = it cannot run captured inline; tty = the argv to hand the terminal to instead (BANG-TTY)
+  if (!pos.length && !info) return { refuse: 'bare quox opens the full-screen app, which needs the terminal. Give it a subcommand, e.g. !quox inbox list (or !quox --help).' };
+  if (INTERACTIVE.has(pos[0])) return { refuse: `quox ${pos[0]} is interactive and needs the terminal, so it cannot run inline. Open it in another terminal.` };
+  if (needsTerminal({ kind: 'quox', args })) return { refuse: `quox ${pos.slice(0, 2).join(' ')} is interactive and needs the terminal, so it cannot run inline.`, tty: { argv } };
+  return { argv };
+}
+
+const STDIN_HINT = /stdin|end of file|\bEOF\b|password|passphrase|\[y\/n\]|\(y\/n\)|continue\?|press (any )?key|enter .*:\s*$/i;
+
+/**
+ * Run one command. -> { kill(), done: Promise<result> }.
+ * result: { code, signal, ms, timedOut, killed, lines, truncated, text, stdinNote }
+ * onData(text) is called with accepted output only (capped at MAX_LINES / MAX_BYTES); `text` is the same capped capture.
+ */
+export function runBang(plan, { cwd = process.cwd(), env = process.env, timeoutMs, onData = () => {}, graceMs = KILL_GRACE_MS, now = Date.now, shell } = {}) {
+  const tmo = Number(timeoutMs ?? env.QUOX_BANG_TIMEOUT_MS ?? DEFAULT_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS;
+  const t0 = now();
+  let file, args;
+  if (plan.argv) { file = process.execPath; args = plan.argv; }
+  else { file = shell || env.SHELL || '/bin/sh'; args = ['-lc', plan.cmd]; }
+  const st = { timedOut: false, killed: false, lines: 0, acc: 0, bytes: 0, truncated: false, text: '', partial: false };
+  let child, timer, killTimer;
+  const done = new Promise((resolve) => {
+    const finish = (code, signal) => {
+      clearTimeout(timer); clearTimeout(killTimer);
+      const res = { code, signal, ms: now() - t0, timedOut: st.timedOut, killed: st.killed && !st.timedOut, lines: st.lines, truncated: st.truncated, text: st.text };
+      if (code !== 0 && !st.timedOut && !st.killed && (!st.text.trim() || STDIN_HINT.test(st.text.slice(-400)))) res.stdinNote = 'This command got end-of-file on stdin (input is not available here), so it may have been waiting for input.';
+      resolve(res);
+    };
+    try {
+      child = spawn(file, args, { cwd, env, detached: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (e) { st.text = String(e.message); return finish(127, null); }
+    child.on('error', (e) => { st.text += `${e.message}\n`; onData(`${e.message}\n`); finish(127, null); });
+    child.stdin.on('error', () => {});
+    child.stdin.end(); // EOF immediately: nothing here can answer a prompt
+    const take = (buf) => {
+      let s = buf.toString('utf8');
+      if (!s) return;
+      for (const ch of s) if (ch === '\n') st.lines++;
+      if (st.truncated) return;
+      if (st.acc >= MAX_LINES) { st.truncated = true; return; }
+      const room = MAX_BYTES - st.bytes;
+      if (Buffer.byteLength(s) > room) { s = Buffer.from(s).subarray(0, Math.max(0, room)).toString('utf8'); st.truncated = true; }
+      let nl = 0;
+      for (let i = 0; i < s.length; i++) {
+        if (s[i] === '\n' && st.acc + (++nl) >= MAX_LINES) { if (i + 1 < s.length) st.truncated = true; s = s.slice(0, i + 1); break; }
+      }
+      st.acc += (s.match(/\n/g) || []).length; st.bytes += Buffer.byteLength(s); st.text += s;
+      if (s) onData(s);
+    };
+    const onOut = (b) => take(b);
+    child.stdout.on('data', onOut); child.stderr.on('data', onOut);
+    child.on('close', (code, signal) => finish(code, signal));
+    timer = setTimeout(() => { st.timedOut = true; kill(); }, tmo);
+  });
+  function kill() {
+    if (!child || child.exitCode !== null || child.signalCode) return;
+    st.killed = true;
+    const sig = (s) => { try { process.kill(-child.pid, s); } catch { try { child.kill(s); } catch { /* gone */ } } };
+    sig('SIGTERM');
+    killTimer = setTimeout(() => sig('SIGKILL'), graceMs);
+  }
+  return { kill, done };
+}
+
+/** The "exit N · 1.2s" footer, plus the plain-words reasons. */
+export function footer(r, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const secs = `${(r.ms / 1000).toFixed(1)}s`;
+  if (r.timedOut) return `timed out after ${Math.round(timeoutMs / 1000)}s and was stopped · ${secs} (QUOX_BANG_TIMEOUT_MS changes the limit)`;
+  if (r.killed) return `stopped (Ctrl+C) · ${secs}`;
+  if (r.signal) return `killed by ${r.signal} · ${secs}`;
+  return `exit ${r.code} · ${secs}`;
+}
+
+export const truncNote = (r) => `(output truncated, ${r.lines} lines)`;
+
+/** Text to attach for /share: capped at SHARE_MAX_BYTES. -> { text, truncated } */
+export function shareText(text, max = SHARE_MAX_BYTES) {
+  const b = Buffer.from(String(text ?? ''), 'utf8');
+  if (b.length <= max) return { text: String(text ?? ''), truncated: false };
+  return { text: b.subarray(0, max).toString('utf8'), truncated: true };
+}
+
+/** The message sent to the model: the attached output, clearly framed, then the user's words. */
+export function withShared(message, shared) {
+  if (!shared?.length) return message;
+  const blocks = shared.map(s => `[output of \`${s.cmd}\`${s.truncated ? ' (truncated)' : ''}]\n${s.text}`).join('\n\n');
+  return `${message}\n\n${blocks}`;
+}
+
+/**
+ * Make command output safe for Ink: keep SGR colour codes, drop every other escape sequence (cursor moves, OSC titles,
+ * clears), resolve carriage-return rewrites (progress bars) to their last state, expand tabs, drop other control bytes.
+ */
+export function cleanOutput(s) {
+  let t = String(s ?? '');
+  t = t.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g, ''); // OSC
+  t = t.replace(/\x1b\[([0-9;:]*)([\x20-\x2f]*)([\x40-\x7e])/g, (m, p, i, f) => (f === 'm' ? m : '')); // CSI: keep only colour
+  t = t.replace(/\x1b[PX^_][^\x1b]*(?:\x1b\\)?/g, '').replace(/\x1b[@-Z\\-_]/g, '');
+  t = t.replace(/\r\n/g, '\n').split('\n').map(l => { const i = l.lastIndexOf('\r'); return i >= 0 && i < l.length - 1 ? l.slice(i + 1) : l.replace(/\r/g, ''); }).join('\n');
+  t = t.replace(/\t/g, '    ');
+  return t.replace(/[\x00-\x08\x0b-\x1a\x1c-\x1f\x7f]/g, '');
+}

package/lib/quoxon/bulkRisk.js

@@ -0,0 +1,17 @@
+// APPROVALS-AUDIT finding 1: a bulk yes (/yestoall, /approve all, /answer 1-3 y) never covers a risky ask.
+// A held decision is walked one card at a time, with its full text and its own explicit yes.
+// Mirror of services/auth/lib/bulkGuard.js (the server refuses the same set); a test pins the two together.
+const LOOSEN = /loosen|\.test\.[a-z]+|\.spec\.[a-z]+|\/tests?\/|__tests__|test[- ]guard|\bguard\b|skip(ping)? (a |the )?test|re-?baseline/i;
+const PRIV = /restart|daemon|privileged|elevated|sudo|\bgrant\b.*\btools?\b/i;
+
+export function heldReason(it) {
+  const p = it?.payload || {};
+  if (p.high_risk === true) return 'high risk';
+  if (p.privileged === true) return 'privileged';
+  if (p.category === 'loosening' || p.category === 'test_change') return p.category;
+  const text = [it?.title, p.why, p.category, ...(Array.isArray(p.paths) ? p.paths : []), p.approval_context?.reason].filter(Boolean).join(' ');
+  if (LOOSEN.test(text)) return 'changes a test or guard';
+  if (PRIV.test(String(it?.title || ''))) return 'privileged or restart';
+  return null;
+}
+export const isHeldFromBulk = (it) => heldReason(it) !== null;

package/lib/quoxon/capabilities.js

@@ -7,6 +7,8 @@
  * `res` is { ok:true, capabilities } or { ok:false, status?, missing?, error? }.
  */
 
+import { capabilityName, statusUnreadable } from './providers.js';
+
 const norm = (s) => String(s || '').trim().toLowerCase();
 
 /** -> the capability matching an id, a provider short name, or a display name; else null. */
@@ -27,7 +29,7 @@ export function findCapability(query, res) {
 export function offerFor(capabilityId, res) {
   const c = findCapability(capabilityId, res);
   if (!c) return null;
-  const name = c.name || c.id;
+  const name = capabilityName(c);
   switch (c.availability) {
     case 'installed': return null;
     case 'planned': return `Ⓠ ${name} is planned, not built yet.`;
@@ -53,22 +55,27 @@ export function capabilityLines(res) {
   const of = (a) => caps.filter(c => c.availability === a);
   const out = [['What this Quox can do here:']];
   const installed = of('installed');
-  for (const c of installed) out.push([`● ${c.name}  ${c.intent}`, 'ok']);
+  for (const c of installed) out.push([`● ${capabilityName(c)}  ${c.intent}`, 'ok']);
   if (!installed.length) out.push(['  nothing is ready yet']);
   const setup = of('requires_setup');
   if (setup.length) {
     out.push(['Needs setup:']);
-    for (const c of setup) out.push([`◐ ${c.name}  ${c.reason || 'needs setup'}${c.setup ? ` · ${c.setup}` : ''}`, 'warn']);
+    for (const c of setup) out.push([`◐ ${capabilityName(c)}  ${c.reason || 'needs setup'}${c.setup ? ` · ${c.setup}` : ''}`, 'warn']);
+  }
+  const unk = caps.filter(statusUnreadable);
+  if (unk.length) {
+    out.push(['Unknown (status could not be read):']);
+    for (const c of unk) out.push([`? ${capabilityName(c)}  ${c.reason}`, 'warn']);
   }
-  const off = of('unavailable');
+  const off = of('unavailable').filter(c => !statusUnreadable(c));
   if (off.length) {
     out.push(['Not available here:']);
-    for (const c of off) out.push([`○ ${c.name}  ${c.reason || 'unavailable'}${c.setup ? ` · ${c.setup}` : ''}`]);
+    for (const c of off) out.push([`○ ${capabilityName(c)}  ${c.reason || 'unavailable'}${c.setup ? ` · ${c.setup}` : ''}`]);
   }
   const planned = of('planned');
   if (planned.length) {
     out.push(['Planned (not built yet):']);
-    for (const c of planned) out.push([`· ${c.name}  ${c.intent}`]);
+    for (const c of planned) out.push([`· ${capabilityName(c)}  ${c.intent}`]);
   }
   out.push(['  /capabilities <name> for one, e.g. /capabilities workflows']);
   return out;

package/lib/quoxon/cells.js

@@ -0,0 +1,53 @@
+/**
+ * TUI-FOOTER: terminal cell widths for the bottom chrome (divider, custom rows, status rows).
+ *
+ * string-width counts East Asian Ambiguous characters as one cell. Several of ours are Ambiguous: the ' · '
+ * separator, ● Ⓠ │ ─ ▁ █ ▲ ▼ ▶. A terminal set to draw them wide (a CJK locale, or the "ambiguous characters
+ * are wide" option in iTerm2, VTE or Windows Terminal) gives each two cells, so a row measured to fit overflows
+ * and the terminal wraps it mid-label. Policy, in order: QUOX_AMBIGUOUS=wide|narrow; else a ja/zh/ko locale
+ * (LC_ALL, LC_CTYPE, LANG) means wide; else narrow (what nearly every Western terminal does).
+ * Pure apart from the env default; no extra dependency (the ranges below are Unicode EastAsianWidth=A, U+00A0..U+2FFF,
+ * combining marks excluded since they take no cell).
+ */
+import stringWidth from 'string-width';
+
+const RANGES = ('a1 a4 a7-a8 aa ad-ae b0-b4 b6-ba bc-bf c6 d0 d7-d8 de-e1 e6 e8-ea ec-ed f0 f2-f3 f7-fa fc fe 101 111 113 11b ' +
+  '126-127 12b 131-133 138 13f-142 144 148-14b 14d 152-153 166-167 16b 1ce 1d0 1d2 1d4 1d6 1d8 1da 1dc 251 261 2c4 2c7 2c9-2cb ' +
+  '2cd 2d0 2d8-2db 2dd 2df 391-3a1 3a3-3a9 3b1-3c1 3c3-3c9 401 410-44f 451 2010 2013-2016 2018-2019 201c-201d 2020-2022 ' +
+  '2024-2027 2030 2032-2033 2035 203b 203e 2074 207f 2081-2084 20ac 2103 2105 2109 2113 2116 2121-2122 2126 212b 2153-2154 ' +
+  '215b-215e 2160-216b 2170-2179 2189 2190-2199 21b8-21b9 21d2 21d4 21e7 2200 2202-2203 2207-2208 220b 220f 2211 2215 221a ' +
+  '221d-2220 2223 2225 2227-222c 222e 2234-2237 223c-223d 2248 224c 2252 2260-2261 2264-2267 226a-226b 226e-226f 2282-2283 ' +
+  '2286-2287 2295 2299 22a5 22bf 2312 2460-24e9 24eb-254b 2550-2573 2580-258f 2592-2595 25a0-25a1 25a3-25a9 25b2-25b3 ' +
+  '25b6-25b7 25bc-25bd 25c0-25c1 25c6-25c8 25cb 25ce-25d1 25e2-25e5 25ef 2605-2606 2609 260e-260f 261c 261e 2640 2642 ' +
+  '2660-2661 2663-2665 2667-266a 266c-266d 266f 269e-269f 26bf 26c6-26cd 26cf-26d3 26d5-26e1 26e3 26e8-26e9 26eb-26f1 26f4 ' +
+  '26f6-26f9 26fb-26fc 26fe-26ff 273d 2776-277f 2b56-2b59')
+  .split(' ').map((r) => { const [a, b = a] = r.split('-'); return [parseInt(a, 16), parseInt(b, 16)]; });
+
+/** Is this code point East Asian Ambiguous (drawn one or two cells depending on the terminal)? */
+export function isAmbiguous(cp) {
+  let lo = 0, hi = RANGES.length - 1;
+  while (lo <= hi) {
+    const m = (lo + hi) >> 1;
+    if (cp < RANGES[m][0]) hi = m - 1; else if (cp > RANGES[m][1]) lo = m + 1; else return true;
+  }
+  return false;
+}
+
+/** The ambiguous-width policy for this terminal: true when Ambiguous characters take two cells. */
+export function ambiguousWide(env = process.env) {
+  const o = String(env.QUOX_AMBIGUOUS || '').toLowerCase();
+  if (o === 'wide') return true;
+  if (o === 'narrow') return false;
+  return /^(ja|zh|ko)([_.@-]|$)/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || '');
+}
+
+const ANSI = /\x1b\[[0-9;]*m/g;
+/** Cells `text` takes in a terminal with the given ambiguous-width policy (escapes take none). */
+export function cellWidth(text, { wide = ambiguousWide() } = {}) {
+  const t = String(text ?? '');
+  let w = stringWidth(t);
+  if (!wide) return w;
+  for (const ch of t.replace(ANSI, '')) if (isAmbiguous(ch.codePointAt(0))) w += 1;
+  return w;
+}
+

package/lib/quoxon/commandShort.js

@@ -0,0 +1,112 @@
+/**
+ * The palette's one-line description of each slash command: plain words, the job not the mechanism, at most 54
+ * characters so a row never clips at 79 columns. The long wording stays in the registry for /help.
+ * Rule: lowercase first word unless it is an acronym or a command name. A command with no entry here uses its
+ * registry desc, which a test requires to be short already.
+ */
+export const SHORT_MAX = 54;
+export const SHORT = {
+  walkthrough: 'a guided pass: what it does, why, my advice',
+  approvals: 'the questions waiting for you, one at a time',
+  peek: 'look up an envelope, item, run or receipt by id',
+  aside: 'a read-only side question, kept out of the chat',
+  yestoall: 'approve everything waiting (same as /approve all)',
+  approve: 'approve item N, or everything one agent asked',
+  deny: 'deny item N (or all of one agent), with a reason',
+  answer: 'answer a question a session asked you',
+  authenticate: 'enter your PIN once, good for 10 minutes',
+  override: 'override one blocked action (PIN, witnessed)',
+  skills: 'list your org\'s governed skills, or show one',
+  skill: 'ask Quox to run a skill (approvals still apply)',
+  rules: 'which rules win: QUOX.md, dev pack, server policy',
+  clear: 'fresh conversation and a clear screen',
+  resume: 'pick a recent conversation and carry on',
+  compact: 'summarise the conversation, keeping decisions',
+  challenge: 'a second opinion on the last answer (one extra turn)',
+  spawn: 'ask HYPERION for a disposable VM (max 24h)',
+  consent: 'AI data sharing: see where you stand, or agree',
+  help: 'this reference, or detail for one command',
+  note: 'jot a note for the dev observer (also // text)',
+  share: 'attach your last ! command\'s output to your message',
+  copy: 'copy the last answer to the clipboard',
+  dragon: 'the Q comes alive; explain, ask, sleep',
+  'dragon-fly': 'the dragon flies across the screen',
+  sound: 'earcons: Silent, Minimal, Operational or Full',
+  mouse: 'click to reply and answer cards (off by default)',
+  tip: 'a "did you know" tip about something Quox can do',
+  tips: 'search the tips, or list the topics',
+  'tip-settings': 'tips: off, core (free features) or all',
+  whatsnew: 'new commands and release notes since you last looked',
+  welcome: 'show the welcome screen again',
+  about: 'who we are, terms, privacy, licence and docs',
+  quit: 'leave; finished work is kept, /resume picks it up',
+  restart: 'restart into the latest quox and resume',
+  update: 'update quox to the latest version, then restart',
+  demo: 'play the simulated demo; nothing real runs',
+  feedback: 'tell the Quox team something (you see it first)',
+  gripe: 'file a GitHub issue; /gripe! files at once',
+  sessions: 'everything live in your org, and where it runs',
+  active: 'who is doing what, one line per worker',
+  dashboard: 'open the web dashboard already signed in',
+  rename: 'name this session (alone shows the current name)',
+  slot: 'give this session a slot address',
+  say: 'message one or more slots directly',
+  join: 'join a slot as a group room',
+  leave: 'leave a slot room you joined',
+  rooms: 'rooms this window has joined, with unread counts',
+  broadcast: 'tell every held slot in this org at once',
+  page: 'urgent message to one slot, with acknowledgement',
+  ack: 'acknowledge a broadcast',
+  send: 'send a local text file into a slot (64 KB cap)',
+  attach: 'send your turns to a specific agent',
+  login: 'sign in again without leaving quox',
+  profile: 'switch this window to another signed-in profile',
+  connect: 'see what is connected; /connect openai adds a key',
+  hosts: 'add a host to your fleet; /hosts lists them',
+  capabilities: 'what this Quox can do here, and what needs setup',
+  verbose: 'protocol lines: off, on (compact) or full',
+  proof: 'the evidence chain for the last tool call',
+  prove: 'check the last turn\'s tool calls did what they said',
+  replay: 'rebuild an earlier run from the audit trail',
+  aocl: 'every AOCL layer of the last turn',
+  reconcile: 'check tool calls that ended with effect unknown',
+  roster: 'show or hide the live roster under the status line',
+  workflow: 'the step flow of a workflow\'s latest run',
+  crystal: 'could this workflow become a Crystal?',
+  undo: 'reverse the last thing Quox did, if it knows how',
+  wish: 'describe something Quox cannot do yet',
+  agents: 'pick an agent, or show one\'s card',
+  which: 'what this window is using: login, org, agent, model',
+  crystallize: 'turn what was just done into a reusable skill',
+  automate: 'turn this conversation or a task into a workflow',
+  watch: 'turn a site, repo, server or metric into an observer',
+  fleet: 'computers, agents, missions and SubFleets, with health',
+  memory: 'facts Quox remembers: source, age, trust, conflicts',
+  sitrep: 'the situation now: waiting, running, unseen',
+  away: 'what happened while you were away',
+  vm: 'VMs on Proxmox via HYPERION: list, start, stop',
+  hyperion: 'which VMs HYPERION has out, and who holds each',
+  observers: 'LUCID: the situation and what changed since',
+  mind: 'QuoxMind implants: status and last activity',
+  hat: 'list hats, switch hat, or make your own',
+  org: 'list your orgs, switch to one, or go back',
+  r: 'reply to whoever last messaged you (also /reply)',
+  poke: 'wake a session with an urgent page (also /wake)',
+  afk: 'tell sessions you are away; approvals still queue',
+  back: 'mark yourself present and show what you missed',
+  observe: 'post a note to the session watching your window',
+  huh: 'the dragon explains what just happened',
+  sleep: 'mark yourself sleeping; the dragon curls up',
+  mode: 'ask first (default) or plan only',
+  slots: 'held slots: who holds them and where',
+  mirror: 'what CommanderQ sees about this org right now',
+  health: 'dashboard summary: services, agents, approvals',
+  status: 'profile, org, server health, model, agent, slot',
+  cost: 'tokens and cost per model for this session',
+  context: 'model, tokens, rules, skills, memory, agent',
+  doctor: 'the quox doctor checks plus chat checks',
+  server: 'your self-hosted install: version, health, disk',
+  config: 'settings: theme, motion, verbose, model',
+  model: 'choose the provider and model for your next turns',
+  row: 'your own live lines above the status bar',
+};