quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/capabilities.js

@@ -0,0 +1,75 @@
+/**
+ * /capabilities and the K2 offer helper. Pure: everything comes from the server's
+ * GET /api/v1/capabilities answer (QUOXON E1), which derives each availability from
+ * real health, licence, install and provider signals. This module never decides a
+ * capability exists; when the server cannot answer it says so and claims nothing.
+ *
+ * `res` is { ok:true, capabilities } or { ok:false, status?, missing?, error? }.
+ */
+
+const norm = (s) => String(s || '').trim().toLowerCase();
+
+/** -> the capability matching an id, a provider short name, or a display name; else null. */
+export function findCapability(query, res) {
+  if (!res?.ok || !Array.isArray(res.capabilities)) return null;
+  const q = norm(query);
+  if (!q) return null;
+  return res.capabilities.find(c => norm(c.id) === q)
+    || res.capabilities.find(c => norm(c.id) === `provider.${q}`)
+    || res.capabilities.find(c => norm(c.name) === q || norm(c.name).split(/\s+\(/)[0] === q)
+    || null;
+}
+
+/**
+ * K2: the honest one-line offer for a gap, or null when there is no gap (or we cannot tell).
+ * Offers a place to set it up; never asks for a secret in the conversation.
+ */
+export function offerFor(capabilityId, res) {
+  const c = findCapability(capabilityId, res);
+  if (!c) return null;
+  const name = c.name || c.id;
+  switch (c.availability) {
+    case 'installed': return null;
+    case 'planned': return `Ⓠ ${name} is planned, not built yet.`;
+    case 'requires_setup': {
+      const why = c.reason ? ` (${c.reason})` : '';
+      if (!c.setup) return `Ⓠ ${name} isn't set up yet${why}.`;
+      if (c.permissions_ok === false) return `Ⓠ ${name} isn't set up yet${why}. An org admin can set it up: ${String(c.setup).replace(/ \(ask an org admin\)$/, '')}`;
+      return `Ⓠ ${name} isn't set up yet${why}. Set it up now? ${c.setup}`;
+    }
+    case 'unavailable':
+      return `Ⓠ ${name} isn't available on this Quox${c.reason ? `: ${c.reason}` : ''}.`;
+    default: return null;
+  }
+}
+
+/** -> [[text, tone?]] for /capabilities. */
+export function capabilityLines(res) {
+  if (!res?.ok || !Array.isArray(res.capabilities)) {
+    if (res?.missing) return [['This Quox does not report its capabilities yet (no /api/v1/capabilities route). Nothing is assumed.', 'warn']];
+    return [[`Could not read capabilities: ${res?.error || 'no answer'}. Nothing is assumed.`, 'warn']];
+  }
+  const caps = res.capabilities;
+  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']);
+  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']);
+  }
+  const off = of('unavailable');
+  if (off.length) {
+    out.push(['Not available here:']);
+    for (const c of off) out.push([`○ ${c.name}  ${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}`]);
+  }
+  out.push(['  /capabilities <name> for one, e.g. /capabilities workflows']);
+  return out;
+}

package/lib/quoxon/commands.js

@@ -0,0 +1,154 @@
+/**
+ * The single registry behind /help and slash-command dispatch. Anything shown
+ * as active here is wired in app.js; planned entries are listed dim under
+ * "Coming" and refuse to run. Add a command here first, or it does not exist.
+ */
+export const GROUPS = ['Talk', 'Approvals', 'Skills', 'Conversation', 'Connect', 'Verbose', 'Context', 'Awareness'];
+
+export const REGISTRY = [
+  // Talk (keys)
+  { id: 'type', kind: 'key', group: 'Talk', usage: 'just type', desc: 'ask Quox anything; CommanderQ routes it to the right agent', status: 'active' },
+  { id: 'enter', kind: 'key', group: 'Talk', usage: 'Enter', desc: 'send; while Quox works, steer the running turn if this server supports it, else queue it', status: 'active',
+    detail: 'Idle: sends. During a turn: steers when the server supports it (shown here once known), delivered at the next model boundary (never kills a running tool). If the server cannot steer, or the turn already finished, it is queued instead and you are told.' },
+  { id: 'tab', kind: 'key', group: 'Talk', usage: 'Tab', desc: 'queue your message to run after this turn', status: 'active',
+    detail: 'Queued messages show above the composer. Up (empty composer) pulls the last one back to edit. After an interrupt they wait; press Enter on an empty composer to send the next one.' },
+  { id: 'esc', kind: 'key', group: 'Talk', usage: 'Esc', desc: 'ask the server to stop the turn (idle: Esc Esc clears the draft to history)', status: 'active',
+    detail: 'Asks the server to stop before the next model call or tool; you see "stopping" until the server confirms. A tool already dispatched finishes and is reported, never hidden. Until the server route exists the stream is aborted locally and you are told work already sent may still finish.' },
+  { id: 'newline', kind: 'key', group: 'Talk', usage: 'Shift+Enter / Ctrl+J', desc: 'new line in the composer (a trailing \\ then Enter also works)', status: 'active' },
+  { id: 'editor', kind: 'key', group: 'Talk', usage: 'Ctrl+G', desc: 'edit the draft in $EDITOR', status: 'active' },
+  { id: 'stash', kind: 'key', group: 'Talk', usage: 'Ctrl+S', desc: 'stash the draft; on an empty composer, restore it', status: 'active' },
+  { id: 'undo', kind: 'key', group: 'Talk', usage: 'Ctrl+_', desc: 'undo in the composer', status: 'active' },
+  { id: 'paste', kind: 'key', group: 'Talk', usage: 'paste', desc: 'long pastes collapse to [Pasted text #N +L lines] and expand on send', status: 'active' },
+  { id: 'ctrlc', kind: 'key', group: 'Talk', usage: 'Ctrl+C', desc: 'clear the draft; during a turn interrupt; twice when idle quits', status: 'active' },
+  // Approvals
+  { id: 'approvals', kind: 'command', group: 'Approvals', usage: '/approvals', desc: 'list what is waiting for you', server: true, cap: 'approvals', status: 'active' },
+  { id: 'approve', kind: 'command', group: 'Approvals', usage: '/approve N', desc: 'approve item N from the list', server: true, cap: 'approvals', status: 'active',
+    detail: 'Run /approvals first. Mid-turn approval cards also take a (approve), d (deny), o (open); they arm after 300 ms and never default to approve.' },
+  { id: 'deny', kind: 'command', group: 'Approvals', usage: '/deny N', desc: 'deny item N from the list', server: true, cap: 'approvals', status: 'active' },
+  // Skills and rules
+  { id: 'skills', kind: 'command', group: 'Skills', usage: '/skills [name]', desc: 'list your org\'s governed skills, or show one as a card', needs: ['skills'], cap: 'skills', status: 'active',
+    detail: 'Lists your org skills (reusable procedures an agent follows; not Crystals, which are deterministic replays) with edition and one-line description. /skills <name> shows its card: purpose, version and review state, tests (results only when run-tests recorded them), the agents it is for, where it came from, recorded use, and how to run it.' },
+  { id: 'skill', kind: 'command', group: 'Skills', usage: '/skill <name> [args]', desc: 'ask Quox to run a skill (governed: approvals still apply)', server: true, cap: 'skills', status: 'active',
+    detail: 'Sends "Run the skill <name> with: <args>" as a normal turn, so CommanderQ runs it through the usual governed path. Nothing is executed from here, and approval cards work as always.' },
+  { id: 'rules', kind: 'command', group: 'Skills', usage: '/rules [files|off|on|N]', desc: 'which rules win: advisory QUOX.md, the dev pack, enforced server policy', status: 'active',
+    detail: '/rules shows the precedence: QUOX.md and the dev pack only guide; armed governance policies on the server are enforced and win. /rules files shows the QUOX.md text. QUOX.md in this directory and parents up to the git root, plus ~/.quox/QUOX.md, are sent with each turn as your rules. World-writable files and symlinks leaving your home or repo are ignored. /rules N shows page N.' },
+  // Conversation
+  { id: 'clear', kind: 'command', group: 'Conversation', usage: '/clear', desc: 'fresh conversation and a clear screen; rules and memory kept, /resume goes back', status: 'active', aliases: ['new', 'reset'],
+    detail: 'Clears the screen and starts a new conversation. Your QUOX.md rules, attached agent, model choice and Quox memory stay as they are. The previous conversation is kept on the server: /resume lists it.' },
+  { id: 'resume', kind: 'command', group: 'Conversation', usage: '/resume [id|name]', desc: 'pick a recent conversation and carry on where it left off', status: 'active', needs: ['conversations', 'conversationTurns'],
+    detail: 'Alone: a picker of your recent conversations (title, agent, age); Up/Down and Enter resume, Esc cancels. With an id (or the start of one) or a /rename name it resumes directly. The last turns are shown as history and your next message continues that conversation. Also at launch: quox --resume [id|name] or quox --conversation <id>.' },
+  { id: 'compact', kind: 'command', group: 'Conversation', usage: '/compact [show]', desc: 'summarise the conversation on the server, keeping decisions', status: 'active', needs: ['compactConversation'],
+    detail: 'The server summarises this conversation with your AI provider, keeping decisions, and the summary becomes the start of the conversation for later turns. Shows the token change and the first lines of the summary; /compact show prints all of it. Refused while a turn runs, and when the org has not given AI processing consent. Asking "compact this conversation" in words only suggests it.' },
+  { id: 'help', kind: 'command', group: 'Conversation', usage: '/help [command]', desc: 'this reference, or detail for one command or key', status: 'active' },
+  { id: 'note', kind: 'command', group: 'Conversation', usage: '/note <text>', desc: 'jot an observation for the dev observer (also: // text); not sent to Quox', status: 'active',
+    detail: 'Records your text in the dev transcript only: not sent to the model or the server, no turn, not in chat history. Needs dev transcripts on (touch ~/.config/quox/dev-transcripts). Up to 2000 characters.' },
+  { id: 'copy', kind: 'command', group: 'Conversation', usage: '/copy [N|code]', desc: 'copy the last answer (raw markdown) to the clipboard; N = Nth-last, code = last code block', status: 'active',
+    detail: 'Uses the OSC 52 terminal escape (works over SSH in most terminals; wrapped for tmux). Needs a terminal that allows OSC 52. Mouse selection is untouched: select and copy with your terminal as usual.' },
+  { id: 'eye', kind: 'command', group: 'Conversation', usage: '/eye', desc: 'the Q opens its eye and blinks (the Dragon\'s Eye)', status: 'active',
+    detail: 'A small Easter egg. Under reduced motion (QUOX_REDUCED_MOTION=1) it shows a still open eye instead.' },
+  { id: 'sound', kind: 'command', group: 'Conversation', usage: '/sound [profile|test]', desc: 'earcons for approvals, failures and long turns: Silent | Minimal | Operational | Full', status: 'active',
+    detail: 'Same setting as the dashboard (your account\'s soundProfile). Minimal (default) sounds for approvals, critical alerts and failures; Operational adds a short tick when a turn over 20 s finishes or the terminal is in the background. Over SSH only the terminal bell rings, for approvals and critical alerts. QUOX_SOUND=off mutes this terminal; --print never makes sound.' },
+  { id: 'about', kind: 'command', group: 'Conversation', usage: '/about', desc: 'who we are, terms, privacy, licence and docs links', status: 'active' },
+  { id: 'quit', kind: 'command', group: 'Conversation', usage: '/quit', desc: 'leave; finished work is kept and /resume picks the conversation up', status: 'active', aliases: ['exit'],
+    detail: 'Idle: leaves at once; the conversation stays on the server for /resume (or quox --resume). During a turn it asks first, because leaving disconnects the turn and the server stops it before its next step (a tool already running finishes and is recorded). /quit again within 5 s leaves anyway.' },
+  { id: 'restart', kind: 'command', group: 'Conversation', usage: '/restart', desc: 'restart into the latest installed quox and resume this conversation', status: 'active',
+    detail: 'Re-runs the quox on your PATH in this terminal with the same arguments and profile, plus --resume for this conversation. During a turn it asks first: restarting disconnects the turn and the server stops it before its next step (this server cannot reattach a running turn yet); /restart again within 5 s goes ahead. When a newer build is installed than the one running, a dim line says so (checked at most once a minute, no network).' },
+  { id: 'gripe', kind: 'command', group: 'Conversation', usage: '/gripe <text>', desc: 'file a GitHub issue through the GRIPE agent; shows it first, /gripe! files at once', needs: ['gripe'], status: 'active', aliases: ['gripe!'],
+    detail: 'The same governed path as `quox gripe`: the GRIPE agent files the issue through your org\'s GitHub connector (default repo quoxai/quox). /gripe <text> shows what would be filed and asks; /gripe! (alone, within 2 minutes) files it, or /gripe! <text> files straight away. The issue link is shown when one comes back; with no link it says so and treats it as not filed.' },
+  { id: 'sessions', kind: 'command', group: 'Conversation', usage: '/sessions [all]', desc: 'your recent conversations; /sessions all shows everything live in your org', needs: ['conversations'], status: 'active',
+    detail: '/sessions all is the same overview as `quox sessions`: every live tmux session, conversation, held slot and running objective, loop or workflow in your org, grouped by agent, with how to attach. Bare /sessions lists recent conversations from the server. Names set with /rename are kept on this machine (~/.config/quox/sessions.json) because the server has no rename route yet.' },
+  { id: 'rename', kind: 'command', group: 'Conversation', usage: '/rename [name]', desc: 'name this session (shown in the top rule); alone shows the current name', status: 'active',
+    detail: 'Also settable at launch with quox -n <name>. The name is kept on this machine, keyed by conversation, and shown in /sessions.' },
+  { id: 'slot', kind: 'command', group: 'Conversation', usage: '/slot <name>', desc: 'give this session a slot address (checks out the slot)', needs: ['checkoutSlot'], cap: 'slots', status: 'active',
+    detail: 'Checks out the slot, creating it if needed, as `quox slot checkout <name> --create --session <session>` does; typing it is your consent. Discord replies are not relayed into this window yet (no slot wait loop here).' },
+  { id: 'attach', kind: 'command', group: 'Conversation', usage: '/attach [agent]', desc: 'send your turns to a specific agent; alone shows the current one', needs: ['agents'], cap: 'agents', status: 'active',
+    detail: 'The agent name is checked against your org\'s agent list. Later turns go to that agent (the chat stream assistant field) until /detach.' },
+  { id: 'detach', kind: 'command', group: 'Conversation', usage: '/detach', desc: 'back to CommanderQ', status: 'active' },
+  { id: 'peek', kind: 'command', group: 'Conversation', usage: '/peek <id>', desc: 'look up an envelope, task or agent by id', status: 'planned' },
+  { id: 'aside', kind: 'command', group: 'Conversation', usage: '/aside', desc: 'a read-only side question', status: 'planned' },
+  // Connect
+  { id: 'connect', kind: 'command', group: 'Connect', usage: '/connect [provider]', desc: 'see what is connected; /connect openai adds a key safely', needs: ['connections'], cap: 'vault', status: 'active',
+    detail: 'Alone: AI providers (OpenAI, Claude API, Ollama) and the integrations in your org vault, with real status from the server; anything it cannot read shows ? unknown. /connect openai (or anthropic) opens a secure card: paste the key, Enter tests it with the provider and saves it to your org vault as the default; Esc cancels. Keys typed there never reach chat, history or transcripts. A key pasted into the composer is never sent.' },
+  { id: 'capabilities', kind: 'command', group: 'Connect', usage: '/capabilities [name]', desc: 'what this Quox can do here: ready, needs setup, not available, planned', status: 'active',
+    detail: 'Asks the server (GET /api/v1/capabilities), which checks real service health, your plan, plugin install state and connected providers. Each gap says why and how to set it up; /capabilities <name> gives the one-line offer for one. If the server cannot answer, nothing is assumed.' },
+  // Verbose
+  { id: 'verbose', kind: 'command', group: 'Verbose', usage: '/verbose off|on|full', desc: 'protocol lines: off = receipts only, on = compact, full = adds thinking', status: 'active',
+    detail: 'on (default) shows compact AEE / AOCL / WARD lines as they happen. off collapses to the receipt line. full adds the thinking stream.' },
+  { id: 'proof', kind: 'command', group: 'Verbose', usage: '/proof [envelope]', desc: 'the evidence chain for the last tool call: AEE, AOCL, tool, WARD', server: true, cap: 'receipts', status: 'active',
+    detail: 'Each link is read back from the server and drawn confirmed only when the read says so. WARD is the server-verified inclusion receipt; it can be slow on a large chain and is bounded, so a link may stay open.' },
+  { id: 'reconcile', kind: 'command', group: 'Verbose', usage: '/reconcile', desc: 'check tool calls that ended with effect unknown against the server\'s record', server: true, cap: 'receipts', status: 'active' },
+  // Awareness
+  { id: 'roster', kind: 'command', group: 'Awareness', usage: '/roster [all]', desc: 'show or hide the live roster under the status line; all includes background work', needs: ['roster'], status: 'active',
+    detail: 'The roster lists what needs you: pending approvals, then work you started (objectives, loops, manual workflows). Scheduled and event-driven workflows are hidden; background failures show once per workflow in the bar below. /roster all shows everything. Refreshed every 15 s from the server. Down on an empty composer focuses it; Enter peeks, s asks to stop (y confirms), Esc returns. A source the server cannot answer shows nothing and is named here.' },
+  { id: 'workflow', kind: 'command', group: 'Skills', usage: '/workflow <name|id|run>', desc: 'the step flow of a workflow\'s latest run (or one run): state, timings, human gates', server: true, cap: 'workflows', status: 'active',
+    detail: 'Steps come from the workflow definition and each state and duration from that run\'s recorded envelopes. A reached human gate shows amber. Enter on a workflow row in the roster shows the same flow.' },
+  { id: 'crystal', kind: 'command', group: 'Skills', usage: '/crystal <workflow>', desc: 'is this workflow eligible to become a Crystal? checked against the real gate', server: true, cap: 'crystals', status: 'active',
+    detail: 'Computed from the workflow\'s recorded runs with quoxflow\'s crystalliser rule: at least 3 runs, at least 80% successful, one action sequence. Says how many more successful runs are needed.' },
+  { id: 'agents', kind: 'command', group: 'Awareness', usage: '/agents <name>', desc: 'an agent\'s card: role, tools, slot, last action and its WARD witness', server: true, cap: 'agents', status: 'active' },
+  { id: 'memory', kind: 'command', group: 'Awareness', usage: '/memory <query>', desc: 'facts Quox remembers, each with where it came from, age, trust and conflicts', server: true, cap: 'memory', status: 'active' },
+  { id: 'observers', kind: 'command', group: 'Awareness', usage: '/observers', desc: 'LUCID situation, what changed since you last looked, what Quox records about its own learning', needs: ['observers'], cap: 'lucid', status: 'active',
+    detail: 'Facts only, read from persisted data: the LUCID situation (without moving your cursor), recent changes, lessons taught, and the reflect / learn / insight counters. Nothing is summarised by a model.' },
+  // Context
+  { id: 'statusline', kind: 'key', group: 'Context', usage: 'status line', desc: 'profile · org · agent · model · mode, under the composer', status: 'active' },
+  { id: 'status', kind: 'command', group: 'Context', usage: '/status', desc: 'profile, org, server and its health, model, agent, slot, session, version', status: 'active',
+    detail: 'The provider and model shown are what the server last reported running (turn.started), not what was asked for. Server health is checked live. Asking "what is my status" in words prints the same panel as a tip.' },
+  { id: 'cost', kind: 'command', group: 'Context', usage: '/cost', desc: 'tokens and cost per model for this session, from real usage', status: 'active', aliases: ['usage'],
+    detail: 'Counts only what the server reported on turn.finished (input, output and cache tokens, cost when the provider gives one). Cost stays blank when the server did not report it, and says so; nothing is estimated. Asking "what is this costing" prints the same panel.' },
+  { id: 'context', kind: 'command', group: 'Context', usage: '/context', desc: 'model, conversation tokens, rules, skills, memory and the attached agent', status: 'active',
+    detail: 'Conversation tokens are the sum the server reported for this conversation in this session. Skills and memory are real calls to your server; anything it cannot answer shows ? with the reason. Asking "how much context have we used" prints the same panel.' },
+  { id: 'doctor', kind: 'command', group: 'Context', usage: '/doctor', desc: 'the quox doctor checks plus chat checks, as rows', status: 'active', needs: ['doctorChecks'],
+    detail: 'Runs the same checks as `quox doctor` (services, auth token, CLI version) in this process, then chat checks: the chat routes answer, a provider is connected, the capability contract.' },
+  { id: 'config', kind: 'command', group: 'Context', usage: '/config', desc: 'settings: theme, motion, verbose, model; saved on this profile', status: 'active', aliases: ['settings'],
+    detail: 'An interactive card: Up/Down pick a setting, Left/Right or Space change it (saved at once to this CLI profile), Enter on Model opens /model, Esc closes. Theme replaces the env-only QUOX_THEME; if QUOX_THEME is set in your shell it still wins and the card says so.' },
+  { id: 'profile', kind: 'command', group: 'Context', usage: '/profile', desc: 'switch profile or org without leaving', status: 'planned' },
+  { id: 'model', kind: 'command', group: 'Context', usage: '/model [provider [model] [compact|full]|auto]', desc: 'see what is connected and choose the provider/model for your next turns', needs: ['connections'], status: 'active',
+    detail: 'Alone: auto, OpenAI, Claude API and Ollama with real status from your org vault (the same source as /connect). /model openai, /model openai gpt-5.4-mini, /model anthropic, /model auto (server policy). The choice is saved for this profile (no keys) and sent with each turn; the server decides, and the status line shows what it actually ran. A provider that is not connected is refused with a /connect offer; if the server runs something else, you are told once. quox --provider openai does the same for one run. A trailing compact or full picks the prompt profile: compact is a short system prompt for small or local models (the default on Ollama, LM Studio and vLLM), full is the default elsewhere; --prompt-profile does the same for one --print run.' },
+  { id: 'mentions', kind: 'key', group: 'Context', usage: '@mention', desc: 'complete agents, hosts, tasks and receipts', status: 'planned' }
+];
+
+const norm = (s) => String(s || '').trim().toLowerCase().replace(/^\//, '');
+
+export function findEntry(name) {
+  const n = norm(name);
+  if (!n) return null;
+  return REGISTRY.find(e => e.id === n || e.aliases?.includes(n) || norm(e.usage.split(/\s/)[0]) === n || e.usage.toLowerCase() === n) || null;
+}
+
+/** Slash commands only. */
+export const commandNames = () => REGISTRY.filter(e => e.kind === 'command' && e.status === 'active').flatMap(e => ['/' + e.id, ...(e.aliases || []).map(a => '/' + a)]);
+
+/** Pure help model: [{ kind: 'head'|'row'|'dim'|'gap'|'plain', key?, text? }]. */
+const capView = (e, caps = {}) => {
+  if (e.id === 'enter' && caps.steer === false) return { ...e, desc: 'send; while Quox works, queue it (this server cannot steer a running turn)', detail: 'This server has no steer route: Enter during a turn queues your message as the next turn.' };
+  if (e.id === 'esc' && caps.interrupt === false) return { ...e, desc: 'disconnect from the turn (this server cannot stop it; idle: Esc Esc clears the draft)', detail: 'This server has no interrupt route: Esc aborts only your stream. Work already sent may still finish and be charged.' };
+  return e;
+};
+
+export function helpModel(topic, caps = {}) {
+  if (topic) {
+    const e0 = findEntry(topic);
+    const e = e0 && capView(e0, caps);
+    if (!e) return [{ kind: 'plain', text: `No help for "${topic}". Try /help` }];
+    return [
+      { kind: 'head', text: e.usage },
+      { kind: 'plain', text: e.desc },
+      ...(e.detail ? [{ kind: 'plain', text: e.detail }] : []),
+      ...(e.status === 'planned' ? [{ kind: 'dim', text: 'Planned, not built yet.' }] : [])
+    ];
+  }
+  const out = [];
+  for (const g of GROUPS) {
+    const active = REGISTRY.filter(e => e.group === g && e.status === 'active').map(e => capView(e, caps));
+    if (!active.length) continue;
+    if (out.length) out.push({ kind: 'gap' });
+    out.push({ kind: 'head', text: g });
+    for (const e of active) out.push({ kind: 'row', key: e.usage, text: e.desc });
+  }
+  const planned = REGISTRY.filter(e => e.status === 'planned');
+  if (planned.length) {
+    out.push({ kind: 'gap' }, { kind: 'head', text: 'Coming', dim: true });
+    for (const e of planned) out.push({ kind: 'dim', key: e.usage, text: e.desc });
+  }
+  out.push({ kind: 'gap' }, { kind: 'dim', text: '/help <command> for detail, e.g. /help esc' });
+  return out;
+}