quoxcli 0.5.0 → 0.6.0

package/lib/commands/plan.js

@@ -28,6 +28,10 @@ import { printSuccess } from '../core/output.js';
 import { events, printEvent, celebrate, line as glyphLine } from '../core/quoxglyph.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { QuoxApiError } from '../core/errors.js';
+import {
+  statusGlyph, STATUS_LEGEND, pad, truncate, idWidth, relativeAge, humanDate, termWidth,
+  renderBrief, renderFocusCapped, diffBriefs, renderTicker, capNotes, capPlan, capNoteBody,
+} from '../render/planBrief.js';
 
 const VALID_LENSES = ['focus', 'tier', 'all'];
 const VALID_STATUSES = ['NOT_STARTED', 'IN_PROGRESS', 'COMPLETE', 'BLOCKED', 'DECISION_NEEDED'];
@@ -38,17 +42,8 @@ const WEEK_WIDTH = 4; // characters of bar per week, timeline view
 
 // ── glyphs ───────────────────────────────────────────────────────────────
 
-const STATUS_GLYPH = {
-  NOT_STARTED: { glyph: '◇', color: chalk.dim },
-  IN_PROGRESS: { glyph: '⬗', color: chalk.yellow },
-  BLOCKED: { glyph: '◆', color: chalk.red },
-  DECISION_NEEDED: { glyph: '◈', color: chalk.magenta },
-  COMPLETE: { glyph: '◆', color: chalk.dim },
-};
-
-function statusGlyph(status) {
-  return STATUS_GLYPH[status] || { glyph: '◇', color: chalk.dim };
-}
+// STATUS_GLYPH / statusGlyph live in ../render/planBrief.js (shared with the
+// brief, focus and watch renderers). COMPLETE is ✔ there, distinct from BLOCKED ◆.
 
 const PHASE_GLYPH = {
   TODO: { glyph: '□', color: chalk.dim },
@@ -66,16 +61,7 @@ function phaseGlyph(status) {
 // string with padEnd/padStart would count the escape bytes as visible width
 // and break column alignment.
 
-function pad(value, n) {
-  const s = String(value ?? '');
-  return s.length >= n ? s : s + ' '.repeat(n - s.length);
-}
-
-function truncate(value, n) {
-  const s = String(value ?? '');
-  if (s.length <= n) return s;
-  return s.slice(0, Math.max(0, n - 1)) + '…';
-}
+// pad() and truncate() are imported from ../render/planBrief.js.
 
 function wrapText(text, width) {
   const words = String(text || '').split(/\s+/);
@@ -125,7 +111,7 @@ function renderRoadmapsList(roadmaps) {
   const lines = [];
   for (const r of roadmaps) {
     lines.push('');
-    lines.push(chalk.cyan.bold(`  ${r.id}`) + '  ' + r.name);
+    lines.push(chalk.cyan.bold(`  ${r.id}`) + '  ' + r.name + (r.archived_at ? '  ' + chalk.yellow('archived') : ''));
     if (r.description) lines.push(chalk.dim(`    ${r.description}`));
     const counts = r.status_counts || {};
     const parts = Object.entries(counts).map(([status, n]) => {
@@ -141,12 +127,13 @@ function renderSearchResults(data) {
   const results = data.results || [];
   if (results.length === 0) return [chalk.dim(`  No streams match "${data.q}".`)];
   const lines = [''];
+  const idW = idWidth(results);
   for (const r of results) {
     const g = statusGlyph(r.status);
     const where = [...new Set((r.matches || []).map((m) => m.where))].join(', ');
     const first = (r.matches || []).find((m) => m.snippet) || {};
     lines.push(
-      `  ${g.color(g.glyph)} ${pad(truncate(r.id, ID_WIDTH), ID_WIDTH)} ${pad(truncate(r.name, NAME_WIDTH), NAME_WIDTH)} `
+      `  ${g.color(g.glyph)} ${chalk.cyan(pad(truncate(r.id, idW), idW))} ${pad(truncate(r.name, NAME_WIDTH), NAME_WIDTH)} `
       + `${pad(r.status, 15)} ${pad(where, 18)} ${chalk.dim(truncate(first.snippet || '', 60))}`
     );
   }
@@ -154,10 +141,12 @@ function renderSearchResults(data) {
   return lines;
 }
 
-function streamLine(s, { indent = 0, showReasons = false } = {}) {
+function streamLine(s, { indent = 0, showReasons = false, idW = ID_WIDTH } = {}) {
   const prefix = indent > 0 ? '  '.repeat(indent) + '└ ' : '  ';
   const g = statusGlyph(s.status);
-  const idPlain = pad(s.id, ID_WIDTH);
+  // Substream rows are shifted right by their prefix, so shrink their id pad
+  // by the same amount to keep the name column aligned with top-level rows.
+  const idPlain = pad(s.id, Math.max(0, idW - (prefix.length - 2)));
   const idStr = indent > 0 ? chalk.dim(idPlain) : chalk.cyan(idPlain);
   const nameStr = pad(truncate(s.name, NAME_WIDTH - 1), NAME_WIDTH);
   const tierStr = chalk.dim(`T${s.tier}`);
@@ -176,10 +165,21 @@ function streamAndSubstreams(s, opts) {
   return lines;
 }
 
+/** Id column width for a stream list: widest id plus its substream indent, never below the old 18. */
+function listIdWidth(tops) {
+  let w = ID_WIDTH;
+  for (const s of tops) {
+    w = Math.max(w, String(s.id).length);
+    for (const sub of s.substreams || []) w = Math.max(w, String(sub.id).length + 2);
+  }
+  return w;
+}
+
 /** lens: 'tier' | 'focus' | 'all' — matches the API's `streams` payload shape for that lens. */
 function renderStreamList(payload, { lens = 'tier' } = {}) {
   const lines = [];
   const streams = (payload && payload.streams) || [];
+  const idW = listIdWidth(lens === 'tier' ? streams.flatMap((g) => g.streams || []) : streams);
 
   if (lens === 'tier') {
     if (streams.length === 0) {
@@ -190,7 +190,7 @@ function renderStreamList(payload, { lens = 'tier' } = {}) {
       lines.push('');
       lines.push(chalk.cyan.bold(`  TIER ${group.tier}`));
       for (const s of group.streams) {
-        lines.push(...streamAndSubstreams(s, { indent: 0 }));
+        lines.push(...streamAndSubstreams(s, { indent: 0, idW }));
       }
     }
     return lines;
@@ -202,7 +202,7 @@ function renderStreamList(payload, { lens = 'tier' } = {}) {
     return lines;
   }
   for (const s of streams) {
-    lines.push(...streamAndSubstreams(s, { indent: 0, showReasons: lens === 'focus' }));
+    lines.push(...streamAndSubstreams(s, { indent: 0, showReasons: lens === 'focus', idW }));
   }
   return lines;
 }
@@ -219,13 +219,13 @@ function renderListFooter(payload, lens) {
   return [
     '',
     chalk.dim(`  ${count}`),
-    chalk.dim('  ◇ not started  ⬗ in progress  ◈ decision needed  ◆ blocked (red) or complete (dim)  └ substream'),
+    chalk.dim(`  ${STATUS_LEGEND}  └ substream`),
   ];
 }
 
 // ── render: stream detail ───────────────────────────────────────────────
 
-function renderStreamDetail(detail) {
+function renderStreamDetail(detail, { full = false, now = Date.now() } = {}) {
   const { stream, phases = [], plan, notes = [], depends_on: dependsOn = [], dependents = [] } = detail;
   const lines = [];
   const g = statusGlyph(stream.status);
@@ -274,18 +274,23 @@ function renderStreamDetail(detail) {
   }
 
   if (plan && plan.body) {
+    const { body, hidden } = capPlan(plan.body, { full });
     lines.push('');
     lines.push(chalk.cyan.bold(`  Plan (v${plan.version})`));
     lines.push('');
-    lines.push(renderMarkdownLite(plan.body));
+    lines.push(renderMarkdownLite(body));
+    if (hidden) lines.push(chalk.dim(`  +${hidden} more lines, --full to print the whole plan`));
   }
 
   if (notes.length) {
+    const { notes: shown, hidden } = capNotes(notes, { full });
     lines.push('');
-    lines.push(chalk.cyan.bold('  Notes'));
-    for (const n of notes) {
-      lines.push(`    ${chalk.dim(n.created_at)} ${n.author ? chalk.dim(`(${n.author}) `) : ''}${n.body}`);
+    lines.push(chalk.cyan.bold('  Notes') + chalk.dim(full ? `  ${notes.length}, newest first` : `  newest ${shown.length} of ${notes.length}`));
+    for (const n of shown) {
+      const stamp = `${String(n.created_at || '').slice(0, 10)} ${relativeAge(n.created_at, now).padStart(3)}`;
+      lines.push(`    ${chalk.dim(stamp)}  ${n.author ? chalk.dim(`(${n.author}) `) : ''}${capNoteBody(n.body, { full })}`);
     }
+    if (hidden) lines.push(chalk.dim(`    +${hidden} older notes, --full to print every note`));
   }
 
   lines.push('');
@@ -383,6 +388,60 @@ function renderTimeline(timeline, opts = {}) {
   return lines;
 }
 
+// ── render: follow-ups (server: action items) ───────────────────────────
+// Named "follow-ups" in the CLI (owner 2026-11-08) so they do not collide with
+// the Action Tracker's `quox actions`; the server routes stay /action-items.
+// The legacy hidden `plan actions` / `plan action ...` aliases keep the old
+// "action item" wording. Rows from quoxplan/server/src/api/actionItems.js (rowToActionItem, plus
+// stream_name/stream_status on the roadmap-wide list). kind 'manual' was
+// added by a person; 'blocked'/'decision' were raised automatically when the
+// stream entered BLOCKED / DECISION_NEEDED, and close when it leaves.
+
+const VALID_ACTION_STATUSES = ['OPEN', 'DONE', 'CANCELLED'];
+
+const ACTION_STATUS_COLOR = {
+  OPEN: chalk.yellow,
+  DONE: chalk.green,
+  CANCELLED: chalk.dim,
+};
+
+function actionKindLabel(kind) {
+  return kind === 'manual' || !kind ? 'manual' : `auto ${kind}`;
+}
+
+// Wording for the two verb families: `followups` (current) and the hidden
+// legacy `actions` alias. Only labels differ; routes and payloads are shared.
+const FOLLOWUP_NOUN = { one: 'follow-up', many: 'follow-ups', a: 'a follow-up' };
+const LEGACY_ACTION_NOUN = { one: 'action item', many: 'action items', a: 'an action item', idLabel: 'action', glyph: 'action' };
+
+function renderActionItems(items, { now = Date.now(), status = null, noun = LEGACY_ACTION_NOUN } = {}) {
+  const list = items || [];
+  if (list.length === 0) {
+    return [chalk.dim(`  No ${status ? `${status} ` : ''}${noun.many}.`)];
+  }
+  const idW = idWidth(list.map((a) => `#${a.id}`), { min: 3 });
+  const streamW = idWidth(list.map((a) => a.stream_id), { min: 8 });
+  const kindW = Math.max(...list.map((a) => actionKindLabel(a.kind).length));
+  const lines = [''];
+  for (const a of list) {
+    const color = ACTION_STATUS_COLOR[a.status] || chalk.white;
+    const kind = actionKindLabel(a.kind);
+    const kindStr = a.kind === 'manual' ? chalk.dim(pad(kind, kindW)) : chalk.magenta(pad(kind, kindW));
+    const age = relativeAge(a.created_at, now).padStart(3);
+    const due = a.due_at ? '  ' + chalk.yellow(`due ${String(a.due_at).slice(0, 10)}`) : '';
+    lines.push(
+      `  ${chalk.cyan(pad(`#${a.id}`, idW))} ${color(pad(a.status, 9))} ${kindStr} `
+      + `${chalk.cyan(pad(truncate(a.stream_id, streamW), streamW))} ${chalk.dim(age)}  ${truncate(a.title, 60)}${due}`
+    );
+  }
+  const counts = VALID_ACTION_STATUSES
+    .map((s) => [s, list.filter((a) => a.status === s).length])
+    .filter(([, n]) => n > 0)
+    .map(([s, n]) => `${n} ${s}`);
+  lines.push('', chalk.dim(`  ${list.length} ${list.length === 1 ? noun.one : noun.many}  (${counts.join(', ')})`));
+  return lines;
+}
+
 // ── render: stats / completed ────────────────────────────────────────────
 // Fed by GET /roadmaps/:id/export (the same STRATEGIC_ROADMAP.json-shaped
 // doc the retired roadmap-cli used to read from disk). Adapted from the
@@ -413,7 +472,7 @@ function renderStats(doc) {
 
   const lines = [];
   lines.push('');
-  lines.push(chalk.cyan.bold('  ROADMAP STATISTICS') + '  ' + chalk.dim(doc.updated || ''));
+  lines.push(chalk.cyan.bold('  ROADMAP STATISTICS') + (doc.updated ? '  ' + chalk.dim(`updated ${humanDate(doc.updated)}`) : ''));
   lines.push('  ' + '-'.repeat(50));
   lines.push(`  ${chalk.green('✓ Completed')}        ${completed.length} streams`);
   lines.push(`  ${chalk.yellow('● In progress')}      ${inProgress} streams`);
@@ -421,9 +480,21 @@ function renderStats(doc) {
   if (blocked) lines.push(`  ${chalk.red('✗ Blocked')}          ${blocked} streams`);
   if (decisions) lines.push(`  ${chalk.magenta('? Needs decision')}   ${decisions} streams`);
   lines.push('');
+  // Label the scope: the export's `streams` are OPEN streams only (completed
+  // ones are in `completed`), so this differs from the brief's all-streams
+  // phase line. Unlabelled, the two read as a contradiction.
   lines.push(
-    `  Phase progress   ${progressBar(donePhases, totalPhases || 1)} ${chalk.dim(`(${donePhases}/${totalPhases})`)}`
+    `  Phase progress (open streams)  ${progressBar(donePhases, totalPhases || 1)} ${chalk.dim(`(${donePhases}/${totalPhases})`)}`
   );
+  // An all-streams line only when the completed rows carry phase counts;
+  // otherwise it would silently equal the open-streams number.
+  if (completed.length && completed.every((s) => Number.isFinite(s.phases_total))) {
+    const allTotal = totalPhases + completed.reduce((a, s) => a + (s.phases_total || 0), 0);
+    const allDone = donePhases + completed.reduce((a, s) => a + (s.phases_done || 0), 0);
+    lines.push(
+      `  Phase progress (all streams)   ${progressBar(allDone, allTotal || 1)} ${chalk.dim(`(${allDone}/${allTotal})`)}`
+    );
+  }
   lines.push(`  Tests shipped    ${totalTests} ${chalk.dim('(completed streams)')}`);
   lines.push('');
   return lines;
@@ -485,6 +556,91 @@ async function resolveRoadmapId(client, explicit, orgLabel) {
   return roadmaps[0].id;
 }
 
+const BRIEF_TOP = { def: 7, min: 1, max: 25 };
+const BRIEF_DAYS = { def: 7, min: 1, max: 60 };
+const WATCH_INTERVAL = { def: 30, min: 5 };
+
+function intInRange(raw, { def, min, max }, flag) {
+  if (raw === undefined || raw === null) return def;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < min || (max !== undefined && n > max)) {
+    throw new Error(`invalid ${flag} "${raw}" (expected a whole number ${max !== undefined ? `from ${min} to ${max}` : `of at least ${min}`})`);
+  }
+  return n;
+}
+
+/**
+ * GET the roadmap brief. A 404 means either the roadmap is missing (server
+ * says "roadmap not found") or the QuoxPlan server predates the brief
+ * endpoint (generic "not found"); both get a plain sentence, not a stack.
+ */
+async function fetchBrief(client, roadmapId, { top, days }, orgLabel) {
+  const ep = resolveEndpoint('quoxplan.roadmap.brief.get', { roadmapId });
+  try {
+    return await client.get(ep.path, { service: ep.service, query: { top, days } });
+  } catch (err) {
+    if (err instanceof QuoxApiError && err.status === 404) {
+      const said = String(err.body?.error || err.code || err.message || '');
+      if (/roadmap not found/i.test(said)) {
+        throw new QuoxApiError(404, err.code, `Roadmap ${roadmapId} not found in org ${orgLabel}. It may exist in another org you belong to; switch with \`quox org switch <org>\`.`, err.detail, err.body);
+      }
+      throw new QuoxApiError(404, 'brief_unavailable', 'this QuoxPlan server does not have the brief endpoint yet, update QuoxPlan. Meanwhile `quox plan focus` and `quox plan stats` still work.', err.detail, err.body);
+    }
+    throw err;
+  }
+}
+
+/**
+ * --scope / --dev-server filters, sent only when given so an unfiltered call
+ * is byte-identical to before. scope = a division/department name (matched
+ * against a stream's assignee_scope); dev_server = a governed dev-server host
+ * id (streams tagged for that host, parents kept when a substream matches).
+ */
+function filterQuery(options, { devServer = true } = {}) {
+  const q = {};
+  if (options.scope) q.scope = options.scope;
+  if (devServer && options.devServer) q.dev_server = options.devServer;
+  return q;
+}
+
+function filterLabel(options) {
+  const parts = [];
+  if (options.scope) parts.push(`scope: ${options.scope}`);
+  if (options.devServer) parts.push(`dev server: ${options.devServer}`);
+  return parts.length ? `, ${parts.join(', ')}` : '';
+}
+
+const SCOPE_HELP = 'only streams in this division or department scope (the name, as in the dashboard scope filter)';
+const DEV_SERVER_HELP = 'only streams tagged for this governed dev server (host id)';
+
+function parseActionId(raw, noun = LEGACY_ACTION_NOUN) {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) throw new Error(`${noun.idLabel || noun.one} id must be a positive whole number, got "${raw}"`);
+  return n;
+}
+
+function parseActionStatus(raw, flag) {
+  const status = String(raw || '').toUpperCase();
+  if (!VALID_ACTION_STATUSES.includes(status)) {
+    throw new Error(`invalid ${flag ? `${flag} ` : 'status '}"${raw}" (expected ${VALID_ACTION_STATUSES.join(', ')})`);
+  }
+  return status;
+}
+
+/**
+ * PATCH one follow-up's (server: action item's) status. Module-level (not a
+ * closure in the registrar) so cli/scripts/export-leaf-methods.mjs sees the
+ * PATCH and the chat policy classes `followup done` / `followup status` (and
+ * the hidden legacy `action done` / `action status`) as writes.
+ */
+async function setActionStatus(client, program, actionIdArg, status, noun = LEGACY_ACTION_NOUN) {
+  const actionId = parseActionId(actionIdArg, noun);
+  const ep = resolveEndpoint('quoxplan.actionItem.update', { actionId });
+  const data = await client.patch(ep.path, { service: ep.service, body: { status, actor: 'quox-cli' } });
+  if (isJsonOutput(program)) return printJson(data);
+  printEvent(glyphLine('quoxplan', `${noun.glyph || noun.one} status`, { result: `#${data.id} ${data.stream_id} -> ${data.status}`, status: 'ok' }));
+}
+
 function printJson(data) {
   console.log(JSON.stringify(data, null, 2));
 }
@@ -524,11 +680,14 @@ export function registerPlanCommands(program, ctx) {
 
   plan
     .command('roadmaps')
-    .description('List roadmaps with status counts')
-    .action(async () => {
+    .description('List roadmaps with status counts (archived roadmaps hidden unless --archived)')
+    .option('--archived', 'include archived roadmaps (marked "archived")')
+    .action(async (options = {}) => {
       auth.requireAuth();
       const ep = resolveEndpoint('quoxplan.roadmaps.list');
-      const data = await client.get(ep.path, { service: ep.service });
+      const data = options.archived
+        ? await client.get(ep.path, { service: ep.service, query: { include_archived: '1' } })
+        : await client.get(ep.path, { service: ep.service });
       if (isJsonOutput(program)) return printJson(data);
       console.log(renderRoadmapsList(data.roadmaps || []).join('\n'));
     });
@@ -540,7 +699,7 @@ export function registerPlanCommands(program, ctx) {
   // standalone verb in its own right so nothing has to shell out to onboard.
   const roadmap = plan
     .command('roadmap')
-    .description('Roadmap-level operations (create a roadmap)');
+    .description('Roadmap-level operations (create, archive, unarchive a roadmap)');
 
   roadmap
     .command('create')
@@ -579,6 +738,25 @@ export function registerPlanCommands(program, ctx) {
       printSuccess(`Created roadmap ${created.id || options.id} for org ${orgId}`);
     });
 
+  // QUOXPLAN-TERMINAL (gripe quoxai/quox#1586): archive hides a finished
+  // roadmap from `plan roadmaps` and `plan search` and freezes its streams
+  // (writes answer 409); its history stays readable by id. Not delete.
+  for (const [verb, endpointKey, done, help] of [
+    ['archive', 'quoxplan.roadmap.archive', 'Archived', 'Archive a roadmap: hide it from lists and search, refuse writes to its streams (history stays readable by id)'],
+    ['unarchive', 'quoxplan.roadmap.unarchive', 'Unarchived', 'Unarchive a roadmap: back in lists and search, writes allowed again'],
+  ]) {
+    roadmap
+      .command(`${verb} <roadmapId>`)
+      .description(help)
+      .action(async (roadmapId) => {
+        auth.requireAuth();
+        const ep = resolveEndpoint(endpointKey, { roadmapId });
+        const data = await client.post(ep.path, { service: ep.service, body: { actor: 'quox-cli' } });
+        if (isJsonOutput(program)) return printJson(data);
+        printSuccess(`${done} roadmap ${data.id || roadmapId}`);
+      });
+  }
+
   // ── search ───────────────────────────────────────────────────────────
 
   plan
@@ -606,6 +784,8 @@ export function registerPlanCommands(program, ctx) {
     .command('list [roadmap]')
     .description('Tier-grouped stream list (default roadmap: first by name)')
     .option('--lens <lens>', 'focus | tier | all', 'tier')
+    .option('--scope <scope>', SCOPE_HELP)
+    .option('--dev-server <hostId>', DEV_SERVER_HELP)
     .action(async (roadmapArg, options) => {
       auth.requireAuth();
       if (!VALID_LENSES.includes(options.lens)) {
@@ -613,9 +793,9 @@ export function registerPlanCommands(program, ctx) {
       }
       const roadmapId = await resolveRoadmapId(client, roadmapArg, describeActiveOrg(auth, program));
       const ep = resolveEndpoint('quoxplan.roadmap.streams.list', { roadmapId });
-      const data = await client.get(ep.path, { service: ep.service, query: { lens: options.lens } });
+      const data = await client.get(ep.path, { service: ep.service, query: { lens: options.lens, ...filterQuery(options) } });
       if (isJsonOutput(program)) return printJson(data);
-      console.log(`\n  ${roadmapId}  (lens: ${options.lens})`);
+      console.log(`\n  ${roadmapId}  (lens: ${options.lens}${filterLabel(options)})`);
       console.log(renderStreamList(data, { lens: options.lens }).join('\n'));
       console.log(renderListFooter(data, options.lens).join('\n'));
     });
@@ -624,23 +804,140 @@ export function registerPlanCommands(program, ctx) {
 
   plan
     .command('focus [roadmap]')
-    .description('The focus lens: what matters now (P0, blocked, decision needed, in-flight, stale)')
-    .action(async (roadmapArg) => {
+    .description('What matters now: everything blocked or waiting on a decision, the top 12 in flight, and a stale count (--all for the full focus list)')
+    .option('--all', 'print the full focus list (every P0, blocked, decision, in-flight and stale stream)')
+    .option('--scope <scope>', SCOPE_HELP)
+    .option('--dev-server <hostId>', DEV_SERVER_HELP)
+    .action(async (roadmapArg, options) => {
       auth.requireAuth();
       const roadmapId = await resolveRoadmapId(client, roadmapArg, describeActiveOrg(auth, program));
       const ep = resolveEndpoint('quoxplan.roadmap.streams.list', { roadmapId });
-      const data = await client.get(ep.path, { service: ep.service, query: { lens: 'focus' } });
+      const data = await client.get(ep.path, { service: ep.service, query: { lens: 'focus', ...filterQuery(options) } });
       if (isJsonOutput(program)) return printJson(data);
-      console.log(`\n  ${roadmapId}  (focus)`);
-      console.log(renderStreamList(data, { lens: 'focus' }).join('\n'));
+      if (options.all) {
+        console.log(`\n  ${roadmapId}  (focus, all${filterLabel(options)})`);
+        console.log(renderStreamList(data, { lens: 'focus' }).join('\n'));
+        console.log(renderListFooter(data, 'focus').join('\n'));
+        return;
+      }
+      console.log('');
+      if (filterLabel(options)) console.log(chalk.dim(`  filtered by ${filterLabel(options).slice(2)}`));
+      console.log(renderFocusCapped(data, { roadmapId, width: termWidth() }).join('\n'));
+    });
+
+  // ── brief ────────────────────────────────────────────────────────────
+  // One screen: what to work on, what needs you, what moved, what is stale.
+  // Fed by the server's brief computation so CLI and chat give one answer.
+
+  const runBrief = async (roadmapArg, options = {}) => {
+    auth.requireAuth();
+    const top = intInRange(options.top, BRIEF_TOP, '--top');
+    const days = intInRange(options.days, BRIEF_DAYS, '--days');
+    const orgLabel = describeActiveOrg(auth, program);
+    const roadmapId = await resolveRoadmapId(client, roadmapArg, orgLabel);
+    const data = await fetchBrief(client, roadmapId, { top, days }, orgLabel);
+    if (isJsonOutput(program)) return printJson(data);
+    console.log('');
+    console.log(renderBrief(data, { width: termWidth(), top, days }).join('\n'));
+  };
+
+  plan
+    .command('brief [roadmap]')
+    .description('One-screen roadmap brief: top priorities, what needs you, what to unblock, what moved, what is stale')
+    .option('--top <n>', `how many top priorities to show (${BRIEF_TOP.min} to ${BRIEF_TOP.max}, default ${BRIEF_TOP.def})`)
+    .option('--days <d>', `window for "moved" in days (${BRIEF_DAYS.min} to ${BRIEF_DAYS.max}, default ${BRIEF_DAYS.def})`)
+    .action(runBrief);
+
+  // Bare `quox plan` prints the brief for the default roadmap.
+  plan
+    .allowExcessArguments(true)
+    .action(async (_opts, cmd) => {
+      const extra = (cmd && cmd.args) || [];
+      if (extra.length) {
+        throw new Error(`unknown command 'plan ${extra[0]}'. See \`quox plan --help\`.`);
+      }
+      await runBrief(undefined, {});
+    });
+
+  // ── watch ────────────────────────────────────────────────────────────
+
+  plan
+    .command('watch [roadmap]')
+    .description('Live board: redraws the brief every interval and ticks off changes since you started watching (Ctrl-C exits)')
+    .option('--interval <sec>', `seconds between refreshes (at least ${WATCH_INTERVAL.min}, default ${WATCH_INTERVAL.def})`)
+    .option('--top <n>', `how many top priorities to show (default ${BRIEF_TOP.def})`)
+    .option('--days <d>', `window for "moved" in days (default ${BRIEF_DAYS.def})`)
+    .action(async (roadmapArg, options) => {
+      auth.requireAuth();
+      const interval = intInRange(options.interval, WATCH_INTERVAL, '--interval');
+      const top = intInRange(options.top, BRIEF_TOP, '--top');
+      const days = intInRange(options.days, BRIEF_DAYS, '--days');
+      const orgLabel = describeActiveOrg(auth, program);
+      const roadmapId = await resolveRoadmapId(client, roadmapArg, orgLabel);
+      const first = await fetchBrief(client, roadmapId, { top, days }, orgLabel);
+
+      if (isJsonOutput(program) || !process.stdout.isTTY) {
+        if (isJsonOutput(program)) printJson(first);
+        else {
+          console.log('');
+          console.log(renderBrief(first, { width: termWidth(), top, days }).join('\n'));
+          console.log(chalk.dim('\n  stdout is not a terminal, so this printed one brief instead of a live board.'));
+        }
+        return;
+      }
+
+      const since = new Date().toISOString();
+      const seen = [];
+      let prev = first;
+      let lastError = null;
+      let stopped = false;
+      let wake = null;
+      const draw = () => {
+        const width = termWidth();
+        const out = [
+          ...renderBrief(prev, { width, top, days }),
+          ...renderTicker(seen, { since, width }),
+        ];
+        if (lastError) out.push(chalk.yellow(`  last refresh failed: ${lastError}. Retrying every ${interval}s.`));
+        process.stdout.write('\x1b[2J\x1b[H' + out.join('\n') + '\n');
+      };
+      const stop = () => {
+        stopped = true;
+        if (wake) wake();
+      };
+      process.once('SIGINT', stop);
+      try {
+        draw();
+        while (!stopped) {
+          await new Promise((resolve) => {
+            const t = setTimeout(resolve, interval * 1000);
+            wake = () => { clearTimeout(t); resolve(); };
+          });
+          if (stopped) break;
+          try {
+            const next = await fetchBrief(client, roadmapId, { top, days }, orgLabel);
+            const at = new Date().toISOString();
+            for (const change of diffBriefs(prev, next)) seen.push({ change, at });
+            prev = next;
+            lastError = null;
+          } catch (err) {
+            lastError = err.message;
+          }
+          draw();
+        }
+      } finally {
+        process.removeListener('SIGINT', stop);
+      }
+      console.log(chalk.dim(`\n  stopped watching ${roadmapId}. ${seen.length} change${seen.length === 1 ? '' : 's'} seen.`));
     });
 
   // ── show ─────────────────────────────────────────────────────────────
 
   plan
     .command('show <streamId>')
-    .description('Full stream detail: header, phases checklist, plan, notes timeline, deps')
-    .action(async (streamId) => {
+    .description('Stream detail: header, phases checklist, deps, plan (first 40 lines) and the newest 5 notes (--full for everything)')
+    .option('--full', 'print the whole plan and every note')
+    .action(async (streamId, options) => {
       auth.requireAuth();
       const ep = resolveEndpoint('quoxplan.stream.get', { id: streamId });
       let detail;
@@ -653,7 +950,7 @@ export function registerPlanCommands(program, ctx) {
         throw err;
       }
       if (isJsonOutput(program)) return printJson(detail);
-      console.log(renderStreamDetail(detail).join('\n'));
+      console.log(renderStreamDetail(detail, { full: !!options.full }).join('\n'));
     });
 
   // ── timeline ─────────────────────────────────────────────────────────
@@ -662,15 +959,128 @@ export function registerPlanCommands(program, ctx) {
     .command('timeline [roadmap]')
     .description('ASCII Gantt: dependency-sequenced schedule, critical path bold, blocked edges marked')
     .option('--weeks <n>', 'force the number of week columns shown', (v) => parseInt(v, 10))
+    // No --dev-server here: the timeline route reads only ?scope (roadmaps.js).
+    .option('--scope <scope>', SCOPE_HELP)
     .action(async (roadmapArg, options) => {
       auth.requireAuth();
       const roadmapId = await resolveRoadmapId(client, roadmapArg, describeActiveOrg(auth, program));
       const ep = resolveEndpoint('quoxplan.roadmap.timeline.get', { roadmapId });
-      const data = await client.get(ep.path, { service: ep.service });
+      const query = filterQuery(options, { devServer: false });
+      const data = await client.get(ep.path, Object.keys(query).length ? { service: ep.service, query } : { service: ep.service });
       if (isJsonOutput(program)) return printJson(data);
-      console.log(renderTimeline(data.timeline, { weeks: options.weeks, title: roadmapId }).join('\n'));
+      const title = options.scope ? `${roadmapId}  (scope: ${options.scope})` : roadmapId;
+      console.log(renderTimeline(data.timeline, { weeks: options.weeks, title }).join('\n'));
     });
 
+  // ── followups / followup (legacy hidden: actions / action) ──────────
+  // The dashboard's follow-ups panel, from the terminal. `followups` lists
+  // (roadmap-wide, or one stream with --stream); `followup add|done|status`
+  // writes. `followup` is a pure group with no action of its own, so every
+  // leaf classes cleanly as read or write in the chat CLI policy.
+  // Owner 2026-11-08: renamed from `actions` / `action` because those
+  // collided with the Action Tracker's `quox actions`. The old names stay
+  // registered as hidden aliases (same handlers, old wording) so existing
+  // scripts keep working; `quox plan --help` lists only the follow-up verbs.
+
+  const followupFamilies = [
+    { list: 'followups', group: 'followup', idArg: 'followupId', noun: FOLLOWUP_NOUN, hidden: false },
+    { list: 'actions', group: 'action', idArg: 'actionId', noun: LEGACY_ACTION_NOUN, hidden: true },
+  ];
+
+  for (const fam of followupFamilies) {
+    const { noun } = fam;
+    // Hidden on the legacy group AND its subcommands, so the leaf tree flags every legacy leaf hidden.
+    const cmdOpts = fam.hidden ? { hidden: true } : {};
+
+    plan
+      .command(`${fam.list} [roadmap]`, cmdOpts)
+      .description(`List ${noun.many}: roadmap-wide (default roadmap: first by name), or one stream with --stream`)
+      .option('--stream <streamId>', `list one stream's ${noun.many} instead of the whole roadmap`)
+      .option('--status <status>', `only items in this status (${VALID_ACTION_STATUSES.join(', ')})`)
+      .action(async (roadmapArg, options) => {
+        auth.requireAuth();
+        const status = options.status ? parseActionStatus(options.status, '--status') : null;
+        if (roadmapArg && options.stream) {
+          throw new Error('give either a roadmap or --stream <streamId>, not both');
+        }
+        const orgLabel = describeActiveOrg(auth, program);
+        let data;
+        let items;
+        if (options.stream) {
+          const ep = resolveEndpoint('quoxplan.stream.actionItems.list', { id: options.stream });
+          try {
+            data = await client.get(ep.path, { service: ep.service });
+          } catch (err) {
+            if (err instanceof QuoxApiError && err.status === 404) {
+              throw new QuoxApiError(404, err.code, `Stream ${options.stream} not found in org ${orgLabel}. It may exist in another org you belong to; switch with \`quox org switch <org>\`.`, err.detail, err.body);
+            }
+            throw err;
+          }
+          // The per-stream route has no status filter, so filter here.
+          items = (data.action_items || []).filter((a) => !status || a.status === status);
+          if (status) data = { ...data, status, action_items: items };
+        } else {
+          const roadmapId = await resolveRoadmapId(client, roadmapArg, orgLabel);
+          const ep = resolveEndpoint('quoxplan.roadmap.actionItems.list', { roadmapId });
+          try {
+            data = await client.get(ep.path, status ? { service: ep.service, query: { status } } : { service: ep.service });
+          } catch (err) {
+            if (err instanceof QuoxApiError && err.status === 404) {
+              throw new QuoxApiError(404, err.code, `Roadmap ${roadmapId} not found in org ${orgLabel}, or this QuoxPlan server has no ${noun.many} yet. Switch org with \`quox org switch <org>\`.`, err.detail, err.body);
+            }
+            throw err;
+          }
+          items = data.action_items || [];
+        }
+        if (isJsonOutput(program)) return printJson(data);
+        const where = options.stream || data.roadmap_id || roadmapArg;
+        console.log(`\n  ${where}  (${noun.many}${status ? `, ${status}` : ''})`);
+        console.log(renderActionItems(items, { status, noun }).join('\n'));
+      });
+
+    const group = plan
+      .command(fam.group, cmdOpts)
+      .description(`${noun.one[0].toUpperCase()}${noun.one.slice(1)} writes: add a manual item, mark one done, or set its status`);
+
+    group
+      .command('add <streamId> <title...>', cmdOpts)
+      .description(`Add a manual ${noun.one} to a stream`)
+      .option('--due <date>', 'due date (ISO 8601, e.g. 2026-12-15)')
+      .action(async (streamId, titleParts, options) => {
+        auth.requireAuth();
+        const title = titleParts.join(' ').trim();
+        if (!title) throw new Error(`${noun.one} title is required`);
+        const body = { title, actor: 'quox-cli' };
+        if (options.due !== undefined) {
+          if (!/^\d{4}-\d{2}-\d{2}/.test(options.due) || !Number.isFinite(Date.parse(options.due))) {
+            throw new Error(`invalid --due "${options.due}" (expected an ISO 8601 date, e.g. 2026-12-15)`);
+          }
+          body.due_at = options.due;
+        }
+        const ep = resolveEndpoint('quoxplan.stream.actionItems.create', { id: streamId });
+        const data = await client.post(ep.path, { service: ep.service, body });
+        if (isJsonOutput(program)) return printJson(data);
+        printEvent(glyphLine('quoxplan', `${noun.glyph || noun.one} added`, { result: `${streamId} #${data.id} ${title}`, status: 'ok' }));
+      });
+
+    group
+      .command(`done <${fam.idArg}>`, cmdOpts)
+      .description(`Mark ${noun.a} DONE`)
+      .action(async (actionIdArg) => {
+        auth.requireAuth();
+        await setActionStatus(client, program, actionIdArg, 'DONE', noun);
+      });
+
+    group
+      .command(`status <${fam.idArg}> <status>`, cmdOpts)
+      .description(`Set ${noun.a}'s status (${VALID_ACTION_STATUSES.join(', ')})`)
+      .action(async (actionIdArg, statusArg) => {
+        auth.requireAuth();
+        const status = parseActionStatus(statusArg);
+        await setActionStatus(client, program, actionIdArg, status, noun);
+      });
+  }
+
   // ── status ───────────────────────────────────────────────────────────
 
   plan
@@ -870,7 +1280,7 @@ export function registerPlanCommands(program, ctx) {
   plan
     .command('add <json>')
     .description('Create a new stream from a JSON object (id, name required)')
-    .option('--roadmap <roadmap>', 'roadmap id (default: first roadmap)')
+    .option('--roadmap <roadmap>', 'roadmap id (default: roadmap_id in the JSON, else the first roadmap)')
     .action(async (json, options) => {
       auth.requireAuth();
       let body;
@@ -880,7 +1290,15 @@ export function registerPlanCommands(program, ctx) {
         throw new Error(`invalid JSON: ${err.message}`);
       }
       body.actor = body.actor || 'quox-cli';
-      const roadmapId = await resolveRoadmapId(client, options.roadmap, describeActiveOrg(auth, program));
+      // The roadmap comes from the URL, never the body. A roadmap_id in the JSON used to be silently ignored and the
+      // stream landed in the FIRST roadmap (2026-11-09: a fixture seed filled the wrong roadmap). Honour it, and refuse
+      // a disagreement with --roadmap rather than guess.
+      const jsonRoadmap = typeof body.roadmap_id === 'string' && body.roadmap_id ? body.roadmap_id : null;
+      delete body.roadmap_id;
+      if (jsonRoadmap && options.roadmap && jsonRoadmap !== options.roadmap) {
+        throw new Error(`the JSON says roadmap_id "${jsonRoadmap}" but --roadmap "${options.roadmap}": pass one, or make them agree`);
+      }
+      const roadmapId = await resolveRoadmapId(client, options.roadmap || jsonRoadmap, describeActiveOrg(auth, program));
       const ep = resolveEndpoint('quoxplan.roadmap.streams.create', { roadmapId });
       const data = await client.post(ep.path, { service: ep.service, body });
       if (isJsonOutput(program)) return printJson(data);