quoxcli 0.0.0-stage → 0.3.1

package/lib/lucid/LucidIntro.jsx

@@ -0,0 +1,92 @@
+/**
+ * LucidIntro: the ~1.6s startup for `quox lucid deck`.
+ *
+ * Frames (50ms): the Quoxon particle collapse (particles swarm in and lock into the horned Q, tail last),
+ * the ◉ LUCID mark fades in under it, then "tuning in…" resolves into
+ * "◉ LUCID │ N sources live · M need you" once the first fetch has landed.
+ * The fetch is owned by the deck and runs in parallel, never gated on this.
+ * onDone fires once: at the natural end, on a hard 2.5s cap, or on a key
+ * (the deck calls skip via the `skipSignal` prop).
+ */
+import React, { useState, useEffect, useRef } from 'react';
+import { Box, Text } from 'ink';
+import { c, gradient, mono } from '../quoxon/theme.js';
+import { QGlyph } from '../quoxon/qmotion.js';
+import { Clock } from '../quoxon/motion/clock.js';
+import { particleCellsAt, qCells, cellsToAnsi, labSize } from '../quoxon/qart.js';
+
+export const FRAME_MS = 50;
+const PARTICLE_MS = 1100; // the collapse; the Q is fully settled ~470ms later
+const MIN_FRAMES = 32;    // 1.6s: the Q settles, then the live line shows
+const MAX_FRAMES = 50;    // 2.5s cap if the fetch never lands
+
+/** Rows of the particle Q at frame `frame` (motion off: the settled Q). Under 12 rows the compact Q. */
+export function introQ(cols, rows, frame, motion = true) {
+  const size = labSize(cols, Math.max(0, rows - 8));
+  const color = !mono();
+  const t = frame * FRAME_MS;
+  return cellsToAnsi(motion ? particleCellsAt(size, t, { dur: PARTICLE_MS, color }) : qCells(size, { color }));
+}
+
+export function LucidIntro({ data, err, onDone, rows = 24, cols = 100, motion = true }) {
+  const [frame, setFrame] = useState(0);
+  const doneRef = useRef(false);
+  const readyAt = useRef(null);
+  const sit = data && data.situation;
+
+  if (sit && readyAt.current == null) readyAt.current = frame;
+
+  // The deck's shared clock drives the intro too: one timer, armed only while the intro still has frames to play.
+  const clockRef = useRef(null);
+  if (!clockRef.current) clockRef.current = new Clock(() => setFrame((f) => f + 1));
+  useEffect(() => { if (!doneRef.current) clockRef.current.schedule([{ every: FRAME_MS }]); });
+  useEffect(() => () => clockRef.current.stop(), []);
+
+  const finishAt = readyAt.current != null
+    ? Math.max(MIN_FRAMES, readyAt.current + 6)
+    : (err ? Math.max(MIN_FRAMES, 16) : MAX_FRAMES);
+
+  useEffect(() => {
+    if (frame >= finishAt && !doneRef.current) { doneRef.current = true; onDone(); }
+  }, [frame, finishAt, onDone]);
+
+  const qRows = introQ(cols, rows, frame, motion);
+  const markOn = frame >= 14;
+  const resolved = sit && frame >= 22 && frame >= (readyAt.current ?? 0) + 2;
+  const cov = (sit && sit.cannot_see && sit.cannot_see.coverage) || { live: 0, expected: 0 };
+  const dots = '.'.repeat((frame % 3) + 1).padEnd(3, ' ');
+
+  const mark = (
+    <Text>
+      <QGlyph state="working" ms={Date.now()} quiet={!motion} />
+      <Text> </Text>
+      {gradient('LUCID').map((g, i) => <Text key={i} bold color={g.color}>{g.ch}</Text>)}
+    </Text>
+  );
+
+  return (
+    <Box flexDirection="column" alignItems="center" justifyContent="center" flexGrow={1} paddingY={1}>
+      <Box flexDirection="column" alignItems="center">
+        {qRows.map((l, r) => <Text key={r} wrap="truncate">{l}</Text>)}
+      </Box>
+      <Box marginTop={1}>{markOn ? mark : <Text> </Text>}</Box>
+      <Box marginTop={1}>
+        {frame < 16 ? <Text> </Text> : resolved ? (
+          <Text>
+            <QGlyph state={(sit.needs_you || []).length ? 'waiting' : 'resting'} ms={Date.now()} quiet />
+            <Text bold color={c('sky')}> LUCID</Text>
+            <Text color={c('muted')}> │ </Text>
+            <Text color={c('ok')}>{cov.live} sources live</Text>
+            <Text color={c('muted')}> · </Text>
+            <Text bold color={(sit.needs_you || []).length ? c('warn') : c('ok')}>{(sit.needs_you || []).length} need you</Text>
+          </Text>
+        ) : err && !sit ? (
+          <Text color={c('error')}>LUCID unreachable, still trying</Text>
+        ) : (
+          <Text color={c('muted')}>tuning in{dots}</Text>
+        )}
+      </Box>
+      <Box marginTop={1}><Text color={c('muted')}>any key to skip</Text></Box>
+    </Box>
+  );
+}

package/lib/lucid/blind.js

@@ -0,0 +1,71 @@
+/**
+ * `quox lucid blind`: what LUCID can and cannot hear, and what does not add up.
+ * Pure: renderBlind({ situation, feeds, expected }, { now }) -> string (plain text, no colour,
+ * so it pastes anywhere and reads the same in a pipe).
+ *
+ * A source is live, silent (expected but quiet), failing (speaking, but its own read is
+ * failing) or never heard. Contradictions list both sides of each mismatch.
+ */
+
+function ago(ms, now) {
+  if (ms == null) return '';
+  const s = Math.max(0, Math.floor((now - ms) / 1000));
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  return `${Math.floor(h / 24)}d ago`;
+}
+
+const nameOf = (x) => (typeof x === 'string' ? x : (x && (x.feed || x.name)) || '');
+
+/** Rows: { source, state, last, note } sorted worst first. */
+export function blindRows({ situation, feeds = [], expected = [] } = {}, now = Date.now()) {
+  const cs = (situation && situation.cannot_see) || {};
+  const byFeed = new Map(feeds.map((f) => [f.feed, f]));
+  const failing = new Map((cs.failing || []).map((x) => [nameOf(x), x]));
+  const silent = new Set((cs.silent || []).map(nameOf));
+  const unwired = new Set((cs.unwired || []).map(nameOf));
+  const names = new Set([...byFeed.keys(), ...expected, ...failing.keys(), ...silent, ...unwired]);
+  const rows = [];
+  for (const source of names) {
+    if (!source) continue;
+    const f = byFeed.get(source);
+    const last = f && f.last_heard != null ? ago(f.last_heard, now) : '';
+    if (failing.has(source)) rows.push({ rank: 0, source, state: 'failing', last, note: (failing.get(source) || {}).error || (f && f.last_error) || '' });
+    else if (silent.has(source)) rows.push({ rank: 1, source, state: 'silent', last, note: 'expected, but gone quiet' });
+    else if (unwired.has(source) || !f) rows.push({ rank: 2, source, state: 'never heard', last: '', note: 'expected, has never reported' });
+    else rows.push({ rank: 3, source, state: 'live', last, note: '' });
+  }
+  return rows.sort((a, b) => a.rank - b.rank || a.source.localeCompare(b.source));
+}
+
+export function renderBlind(data = {}, { now = Date.now() } = {}) {
+  const sit = data.situation || {};
+  const cov = (sit.cannot_see && sit.cannot_see.coverage) || null;
+  const rows = blindRows(data, now);
+  const out = [];
+  out.push(`SOURCES${cov ? ` (${cov.live} of ${cov.expected} speaking)` : ''}`);
+  if (!rows.length) out.push('  I have not heard from any source yet. That is not "all quiet".');
+  else {
+    const w = Math.max(6, ...rows.map((r) => r.source.length));
+    out.push(`  ${'SOURCE'.padEnd(w)}  ${'STATE'.padEnd(11)}  ${'LAST HEARD'.padEnd(10)}  NOTE`);
+    for (const r of rows) out.push(`  ${r.source.padEnd(w)}  ${r.state.padEnd(11)}  ${r.last.padEnd(10)}  ${r.note}`.trimEnd());
+  }
+  const stale = (sit.cannot_see && sit.cannot_see.stale) || [];
+  if (stale.length) out.push('', `Stale claims (source quiet, so these may be out of date): ${stale.map((s) => nameOf({ name: s.subject })).join(', ')}`);
+
+  const da = sit.doesnt_add_up || [];
+  out.push('', `DOESN'T ADD UP${da.length ? ` (${da.length})` : ''}`);
+  if (!da.length) out.push('  Nothing I can see contradicts anything else. I can only compare what the sources tell me.');
+  da.forEach((x, i) => {
+    out.push(`  ${i + 1}. ${x.L0}${x.urgent ? '  [TODAY]' : ''}`);
+    out.push(`     Claimed   ${x.claimed}`);
+    out.push(`     Observed  ${x.observed}`);
+    if (x.sources && x.sources.length) out.push(`     Sources   ${x.sources.join(', ')}`);
+    if (x.why) out.push(`     Why       ${x.why}`);
+    if (x.how) out.push(`     Settle    ${x.how}`);
+  });
+  return `${out.join('\n')}\n`;
+}

package/lib/lucid/cards.js

@@ -0,0 +1,86 @@
+/**
+ * LUCID object cards: pure views for the deck, in the Quoxon object-card shape ({ box, rows } of
+ * { text, role } segments, see quoxon/objects/model.js). An area is a tile card; a Needs-you item is a card
+ * that opens in place into who / what / why / when and the actions. Nothing here reads a clock or does I/O.
+ *
+ * Roles are theme roles; the renderer (LucidCard.jsx) also understands 'sel' (the selected action bar).
+ * Text is WRAPPED to the card, never clipped, except for a single action line and the command line.
+ */
+import { seg, fit, padRow } from '../quoxon/objects/model.js';
+import { wrap, whenText, ageOf, GLYPH, clip } from './fmt.js';
+
+export const URGENCY_ROLE = { now: 'error', today: 'warn', 'this week': 'sky', whenever: 'muted', fyi: 'muted' };
+export const URGENCY_LABEL = { now: 'NOW', today: 'TODAY', 'this week': 'THIS WEEK', whenever: 'WHENEVER', fyi: 'FYI' };
+export const STATE_ROLE = { ok: 'ok', attention: 'warn', unknown: 'muted', blind: 'error' };
+export const STATE_WORD = { ok: 'ok', attention: 'attention', unknown: 'no signal', blind: 'blind' };
+
+const nm = (x) => (typeof x === 'string' ? x : (x && (x.label || x.name || x.L0 || x.id)) || '');
+const LW = 8; // label column of the open card
+
+/**
+ * An area tile. d: { area, label, state, L0, last, n (needs), active (filter on), selected, focused,
+ * expanded, now }. A tile is one status row; the selected tile in a focused pane opens to its sentence.
+ */
+export function lucidArea(d, cols) {
+  const w = Math.max(18, cols), inner = w - 4;
+  const all = d.area == null;
+  const glyph = all ? '◉' : (GLYPH[d.state] || '?');
+  const role = all ? 'sky' : (STATE_ROLE[d.state] || 'muted');
+  const right = `${d.active ? '● ' : ''}${d.n ? d.n : '·'}`;
+  const rows = [];
+  const word = all ? 'everything' : (STATE_WORD[d.state] || 'unknown');
+  const age = d.last && d.last.ts != null && d.now != null ? `last ${ageOf(d.last.ts, d.now)}` : '';
+  const line = age && [...`${word} · ${age}`].length <= inner ? `${word} · ${age}` : word;
+  rows.push([seg(line, d.selected ? 'value' : role === 'ok' ? 'muted' : role)]);
+  if (d.expanded && d.L0) for (const ln of wrap(d.L0, inner)) rows.push([seg(ln, 'value')]);
+  const mark = d.selected ? '▶ ' : '';
+  return {
+    box: {
+      width: w, title: `${mark}${glyph} ${fit(d.label || d.area || 'All areas', Math.max(4, inner - 8))}`, titleRole: role,
+      right, rightRole: d.n ? 'warn' : 'muted', border: d.selected ? 'sky' : 'faint', sel: d.selected ? (d.focused ? 'focus' : 'dim') : null,
+    },
+    rows,
+  };
+}
+
+/**
+ * A Needs-you card. d: { item, areaLabel, isNew, selected, focused, open, mSel, now }.
+ * Collapsed: the wrapped sentence. Open: the sentence, who/what/why/when, affects, then the actions with
+ * the highlighted one as a bar and its exact command beneath.
+ */
+export function lucidNeed(d, cols) {
+  const it = d.item, w = Math.max(24, cols), inner = w - 4;
+  const urg = it.urgency || 'whenever';
+  const a = it.L1 || {};
+  const ms = (it.L2 && it.L2.measures) || [];
+  const mark = d.selected ? '▶ ' : '';
+  const rows = [];
+  const text = (d.isNew ? '● ' : '') + (it.L0 || '');
+  wrap(text, inner).forEach((ln, i) => rows.push([seg(ln, d.isNew ? 'ok' : d.selected ? 'value' : 'text', d.selected)]));
+  if (d.open) {
+    const detail = (lbl, v) => wrap(v, inner - LW).forEach((ln, i) => rows.push([seg(i ? ' '.repeat(LW) : lbl.padEnd(LW), i ? 'muted' : 'label'), seg(ln, 'text')]));
+    for (const [lbl, v] of [['Who', a.who], ['What', a.what], ['Why', a.why], ['When', whenText(a.when, d.now)]]) if (v) detail(lbl, v);
+    if ((a.affected || []).length) rows.push([seg('Affects'.padEnd(LW), 'label'), seg(clip(a.affected.map(nm).filter(Boolean).join(', '), inner - LW), 'muted')]);
+    rows.push(ms.length ? [seg('What you can do', 'key', true)] : [seg('No actions to offer here. Esc closes.', 'muted')]);
+    ms.forEach((m, mi) => {
+      const on = mi === d.mSel;
+      const risk = ` ${m.risk}`;
+      const label = fit(m.say || m.label, Math.max(8, inner - 2 - risk.length));
+      if (on) rows.push([seg(`❯ ${label}${risk}`.padEnd(inner, ' '), 'sel', true)]);
+      else rows.push([seg('  ', 'muted'), seg(label, 'text'), seg(risk, m.risk === 'dangerous' ? 'error' : m.risk === 'gated' ? 'warn' : 'muted')]);
+    });
+    const cmd = ms[d.mSel] && ms[d.mSel].command;
+    if (cmd) rows.push([seg('  $ ', 'muted'), seg(clip(cmd, inner - 4), 'code')]);
+    else if (ms.some((m) => m.command)) rows.push([seg(' ', 'muted')]);
+  }
+  return {
+    box: {
+      width: w, title: `${mark}${URGENCY_LABEL[urg] || String(urg).toUpperCase()} · ${it.kind || 'item'}`, titleRole: URGENCY_ROLE[urg] || 'muted',
+      right: d.areaLabel || '', rightRole: 'muted', border: d.selected ? 'sky' : (urg === 'now' ? 'error' : 'faint'), sel: d.selected ? (d.focused ? 'focus' : 'dim') : null,
+    },
+    rows,
+  };
+}
+
+export const cardHeight = (view) => view.rows.length + 2;
+export { padRow };

package/lib/lucid/deck.js

@@ -0,0 +1,32 @@
+/**
+ * Launcher for the LUCID deck TUI. Alt screen via fullscreen-ink when the
+ * terminal supports raw mode; restores the terminal on every exit path.
+ */
+export async function launchDeck(api, { intervalMs = 10000, noIntro = false } = {}) {
+  if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== 'function' || !process.stdout.isTTY) {
+    console.error('quox lucid deck needs an interactive terminal. Use `quox lucid --sitrep` for a one-shot snapshot.');
+    process.exitCode = 1;
+    return;
+  }
+  const { shouldIntro } = await import('./fmt.js');
+  const intro = shouldIntro({ noIntro: noIntro || process.argv.includes('--no-intro'), isTTY: true });
+  // A long-running TUI must use React's production build: the development build keeps debug
+  // records per render and grew the heap steadily (measured flat at 14MB in production).
+  if (!process.env.NODE_ENV) process.env.NODE_ENV = 'production';
+  await import('../tui/index.js'); // registers the .jsx loader hook
+  const React = (await import('react')).default;
+  const { LucidDeck } = await import('../tui/views/LucidDeck.jsx');
+  const { withFullScreen } = await import('fullscreen-ink');
+  const app = withFullScreen(React.createElement(LucidDeck, { api, intervalMs, intro }), { exitOnCtrlC: true });
+  const restore = () => { try { process.stdout.write('\x1b[?1049l\x1b[?25h'); } catch { /* best effort */ } };
+  process.once('SIGTERM', () => { restore(); process.exit(143); });
+  process.once('SIGHUP', () => { restore(); process.exit(129); });
+  process.once('exit', restore);
+  process.once('uncaughtException', (e) => { restore(); console.error(e); process.exit(1); });
+  try {
+    await app.start();
+    await app.waitUntilExit();
+  } finally {
+    restore();
+  }
+}

package/lib/lucid/fmt.js

@@ -0,0 +1,139 @@
+/**
+ * LUCID presentation helpers shared by `quox lucid --sitrep` and the deck TUI.
+ * Pure functions, no I/O. Colour is a parameter, never read from globals, so
+ * renderers are deterministic under test.
+ */
+
+export const GLYPH = { ok: '✔', attention: '⚠', unknown: '?', blind: '✖' };
+export const STATE_HEX = { ok: '#22C55E', attention: '#FBBF24', unknown: '#A1A1AA', blind: '#EF4444' };
+export const URGENCY = {
+  now: { label: 'NOW', hex: '#EF4444' },
+  today: { label: 'TODAY', hex: '#FBBF24' },
+  'this week': { label: 'THIS WEEK', hex: '#38BDF8' },
+  whenever: { label: 'WHENEVER', hex: '#71717A' },
+  fyi: { label: 'FYI', hex: '#71717A' },
+};
+export const PALETTE = {
+  brand: '#38BDF8', accent: '#C084FC', text: '#E4E4E7', muted: '#A1A1AA', dim: '#71717A', code: '#7DD3FC',
+};
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+export const stripAnsi = (s) => String(s).replace(ANSI_RE, '');
+export const vlen = (s) => [...stripAnsi(s)].length;
+
+/** Truncate a plain string to max visible chars with an ellipsis. */
+export function clip(s, max) {
+  const a = [...String(s ?? '')];
+  if (a.length <= max) return a.join('');
+  return max <= 1 ? a.slice(0, max).join('') : a.slice(0, max - 1).join('') + '…';
+}
+
+/** Word-wrap plain text to width; hard-breaks over-long words. Returns lines. */
+export function wrap(text, width) {
+  width = Math.max(4, width);
+  const out = [];
+  for (const para of String(text ?? '').split('\n')) {
+    let cur = '';
+    for (let w of para.split(/\s+/).filter(Boolean)) {
+      while ([...w].length > width) {
+        if (cur) { out.push(cur); cur = ''; }
+        out.push([...w].slice(0, width).join(''));
+        w = [...w].slice(width).join('');
+      }
+      if (!cur) cur = w;
+      else if ([...cur].length + 1 + [...w].length <= width) cur += ' ' + w;
+      else { out.push(cur); cur = w; }
+    }
+    out.push(cur);
+  }
+  return out.length ? out : [''];
+}
+
+export function padEnd(s, width) {
+  const n = width - vlen(s);
+  return n > 0 ? s + ' '.repeat(n) : s;
+}
+
+/** "3m", "2h", "4d" from a ms timestamp (relative to now). */
+export function ageOf(ms, now = Date.now()) {
+  if (ms == null) return '';
+  const s = Math.max(0, Math.floor((now - ms) / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+/** ▰▰▰▰▱ meter, `cells` wide, filled proportionally (never rounds a gap to full). */
+export function meter(live, expected, cells = 5) {
+  if (!expected) return '▱'.repeat(cells);
+  let f = Math.round((live / expected) * cells);
+  if (live < expected && f >= cells) f = cells - 1;
+  if (live > 0 && f === 0) f = 1;
+  return '▰'.repeat(f) + '▱'.repeat(cells - f);
+}
+
+export function clockLondon(ms = Date.now()) {
+  try {
+    return new Intl.DateTimeFormat('en-GB', {
+      timeZone: 'Europe/London', hour: '2-digit', minute: '2-digit', hour12: false,
+    }).format(new Date(ms));
+  } catch { return new Date(ms).toISOString().slice(11, 16); }
+}
+
+/** Plain-words account of a measure for the "do" line. */
+export function firstMeasure(item) {
+  const ms = (item && item.L2 && item.L2.measures) || [];
+  return ms[0] || null;
+}
+
+export function whenText(w, now = Date.now()) {
+  if (!w) return '';
+  const parts = [];
+  if (w.clock) parts.push(w.clock);
+  else if (w.since) parts.push(`${ageOf(w.since, now)} ago`);
+  if (w.waited_ms != null && !w.clock) parts.push(`waiting ${ageOf(now - w.waited_ms, now)}`);
+  return parts.join(' · ');
+}
+
+/** Label for a changed[] entry in plain words. */
+export function changedWords(c) {
+  const o = c.outcome ? `${c.outcome}` : (c.to ? `${c.from ? c.from + ' → ' : ''}${c.to}` : '');
+  return o;
+}
+
+/** Blind spot sentence list from cannot_see, names not counts where we have names. */
+export function blindSpots(cs) {
+  cs = cs || {};
+  const nm = (x) => (typeof x === 'string' ? x : x && (x.feed || x.name || x.id || x.label)) || '';
+  const parts = [];
+  const silent = (cs.silent || []).map(nm).filter(Boolean);
+  const failing = (cs.failing || []).map(nm).filter(Boolean);
+  const stale = (cs.stale || []).map(nm).filter(Boolean);
+  const unwired = (cs.unwired || []).map(nm).filter(Boolean);
+  if (failing.length) parts.push({ k: 'failing', text: `failing: ${failing.join(', ')}` });
+  if (silent.length) parts.push({ k: 'silent', text: `silent: ${silent.join(', ')}` });
+  if (stale.length) parts.push({ k: 'stale', text: `stale: ${stale.join(', ')}` });
+  if (unwired.length) parts.push({ k: 'unwired', text: `not wired up: ${unwired.join(', ')}` });
+  return parts;
+}
+
+/** HH:MM:SS London clock for the living deck header. */
+export function clockLondonSec(ms = Date.now()) {
+  try {
+    return new Intl.DateTimeFormat('en-GB', {
+      timeZone: 'Europe/London', hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false,
+    }).format(new Date(ms));
+  } catch { return new Date(ms).toISOString().slice(11, 19); }
+}
+
+export const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+/** Whether the startup intro should play. Pure so it is testable. */
+export function shouldIntro({ noIntro = false, env = process.env, isTTY = true } = {}) {
+  if (noIntro || !isTTY) return false;
+  if (env.NO_COLOR || env.QUOX_TUI_LITE) return false;
+  return true;
+}

package/lib/lucid/markdown.js

@@ -0,0 +1,81 @@
+/**
+ * The sitrep as chat Markdown (Discord, Matrix, slots): short, scannable, under one Discord message.
+ * Owner 2026-10-17: "Format your sitrep" after the spoken paragraph was posted to Discord as a wall of text.
+ * Pure: data in, string out. No colour codes, no box drawing (chat clients mangle both).
+ */
+
+const URGENCY = { now: '🔴', today: '🟠', this_week: '🟡', week: '🟡', whenever: '⚪', fyi: '⚪' };
+const STATE = { attention: '⚠️', ok: '✅', partial: '🟡', unknown: '❔', blind: '⛔' };
+export const MAX_CHARS = 1900; // Discord's limit is 2000 per message
+
+const clip = (s, n) => {
+  const t = String(s || '').replace(/\s+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+};
+
+function age(ms) {
+  if (!(ms > 0)) return '';
+  const m = Math.floor(ms / 60000);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 48) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+function clockLondon(now) {
+  try {
+    return new Intl.DateTimeFormat('en-GB', { timeZone: 'Europe/London', hour: '2-digit', minute: '2-digit', timeZoneName: 'short' }).format(new Date(now));
+  } catch { return new Date(now).toISOString().slice(11, 16) + ' UTC'; }
+}
+
+/** opts: { now, maxNeeds (default 6), maxChars (default MAX_CHARS) } */
+export function renderSitrepMarkdown(data, opts = {}) {
+  const sit = (data && data.situation) || data || {};
+  const now = opts.now ?? Date.now();
+  const maxNeeds = opts.maxNeeds ?? 6;
+  const maxChars = opts.maxChars ?? MAX_CHARS;
+  const cov = sit.coverage || (sit.cannot_see && sit.cannot_see.coverage) || { live: 0, expected: 0 };
+  const missing = sit.coverage && Array.isArray(sit.coverage.missing) ? sit.coverage.missing : [];
+  const needs = Array.isArray(sit.needs_you) ? sit.needs_you : [];
+  const low = needs.filter((n) => n.urgency === 'whenever' || n.urgency === 'fyi').length;
+
+  const out = [];
+  out.push(`**◉ LUCID sitrep** · ${clockLondon(now)} · ${cov.live}/${cov.expected} sources`);
+  out.push('');
+  if (!needs.length) {
+    out.push('**Needs you:** nothing right now.');
+  } else {
+    out.push(`**Needs you (${needs.length}${low ? `, ${low} low priority` : ''})**`);
+    needs.slice(0, maxNeeds).forEach((n, i) => {
+      const w = n.L1 && n.L1.when && n.L1.when.waited_ms;
+      const tail = [n.area, age(w)].filter(Boolean).join(', ');
+      out.push(`${i + 1}. ${URGENCY[n.urgency] || '•'} ${clip(n.L0, 90)}${tail ? ` _(${tail})_` : ''}`);
+    });
+    if (needs.length > maxNeeds) out.push(`…and ${needs.length - maxNeeds} more: \`quox sitrep\``);
+  }
+
+  const areas = Array.isArray(sit.areas) ? sit.areas : [];
+  if (areas.length) {
+    out.push('');
+    out.push('**At a glance**');
+    for (const a of areas) out.push(`${STATE[a.state] || '•'} **${a.label || a.area}**: ${clip(a.L0, 80)}`);
+  }
+
+  const dau = Array.isArray(sit.doesnt_add_up) ? sit.doesnt_add_up : [];
+  if (dau.length) {
+    out.push('');
+    out.push(`**Doesn't add up (${dau.length}):** ${clip(dau[0].L0, 90)}${dau.length > 1 ? ' …' : ''}`);
+  }
+  out.push('');
+  out.push(missing.length ? `**Can't see:** ${missing.join(', ')}` : `**Can't see:** nothing, every source is reporting.`);
+
+  // Stay inside one chat message: drop "at a glance" rows from the bottom, then needs, never the header.
+  let text = out.join('\n');
+  while (text.length > maxChars && out.length > 3) {
+    const i = out.findLastIndex((l) => /^(✅|⚠️|🟡|❔|⛔|•) \*\*/.test(l));
+    if (i < 0) break;
+    out.splice(i, 1);
+    text = out.join('\n');
+  }
+  return text.length > maxChars ? `${text.slice(0, maxChars - 1)}…` : text;
+}

package/lib/lucid/motion.js

@@ -0,0 +1,56 @@
+/**
+ * LUCID deck motion: pure helpers for the deck's ONE clock (quoxon/motion/clock.js).
+ *
+ * Idle is still. The deck declares a demand each render; the clock keeps one timer for the soonest demand and
+ * none at all when nothing asks. Frames (~12 fps) are demanded ONLY while something is visibly moving: a fetch
+ * in flight (the Q works), the Q settling after a state change (a short window, then still colour), or a
+ * card dropping in. Everything else is a one-shot wake (toast expiry, ghost expiry, the minute tick).
+ *
+ * LUCID state -> Q state (qglyph.js): needs you = waiting, fetching = working, unreachable = failing,
+ * quiet = resting. Failing wins over working so an outage never reads as busy.
+ */
+import { FRAME_MS } from '../quoxon/motion/clock.js';
+
+export { FRAME_MS };
+/** After a state change the Q animates this long, then holds a still colour (no timer, no writes). */
+export const SETTLE_MS = 2400;
+/** A card dropping in is revealing for this long from its start (rows decode, then a short afterglow). */
+export const REVEAL_MS = 1500;
+/** Cards of one load start this far apart so the board fills top to bottom. */
+export const STAGGER_MS = 70;
+
+export function glyphStateOf({ err = null, fetching = false, needs = 0 } = {}) {
+  if (err) return 'failing';
+  if (fetching) return 'working';
+  return needs > 0 ? 'waiting' : 'resting';
+}
+
+/** Is the Q moving at `now`? Working moves while it lasts; every other state settles after SETTLE_MS. */
+export function glyphAnimating({ state, since, now, motion }) {
+  if (!motion) return false;
+  if (state === 'working') return true;
+  return since != null && now - since < SETTLE_MS;
+}
+
+/** Seconds into a card's reveal, or Infinity when settled (or motion is off). A future start is negative. */
+export function revealT(startAt, now, motion) {
+  if (!motion || startAt == null) return Infinity;
+  const ms = now - startAt;
+  return ms >= REVEAL_MS ? Infinity : ms / 1000;
+}
+
+/**
+ * The demands for this render. frames: something is moving right now. at: epoch ms of one-shot wakes
+ * (past or null entries are ignored). Without motion there are no frame demands at all.
+ */
+export function deckDemands({ motion = false, frames = false, at = [], now = Date.now() } = {}) {
+  const d = [];
+  if (motion && frames) d.push({ every: FRAME_MS });
+  let soonest = null;
+  for (const a of at) if (Number.isFinite(a) && a > now && (soonest == null || a < soonest)) soonest = a;
+  if (soonest != null) d.push({ at: soonest });
+  return d;
+}
+
+/** Next wall-clock minute boundary for a displayed time (the injected clock, so tests stay deterministic). */
+export const nextMinuteAt = (wall, shown) => wall + (60000 - (shown % 60000));