quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/objects/skill.js

@@ -0,0 +1,105 @@
+/**
+ * E1 skill card from a real QSKL skill record (GET /quoxflow/skills/:id) plus, when reachable, its
+ * quoxflow scoreboard row (GET /api/quox-skills/scoreboards). Tests: the record carries test
+ * DEFINITIONS in `tests`; results exist only once run-tests has written `evals.tests`
+ * ({ total, passed, failed, last_run_at, results }). Never shows a pass that was not recorded.
+ */
+import { seg, fit, ago, day, plural, short, boxWidth } from './model.js';
+
+const EDITION_ROLE = { stable: 'ok', experimental: 'warn', archived: 'muted' };
+
+/** -> { word, role } for the review state the record actually states. */
+export function reviewState(s) {
+  if (s?.reviewNeeded) return { word: 'review needed', role: 'warn' };
+  const e = String(s?.edition || s?.status || '').toLowerCase();
+  return e ? { word: e, role: EDITION_ROLE[e] || 'muted' } : { word: 'state unknown', role: 'muted' };
+}
+
+/** -> { dots:[{ch,role}], text, role } or null when the skill has no tests at all. */
+export function testsSummary(s, now) {
+  const run = s?.evals?.tests;
+  if (run && Number.isFinite(Number(run.total))) {
+    const total = Number(run.total), passed = Number(run.passed) || 0, failed = Number(run.failed) || 0;
+    const res = Array.isArray(run.results) ? run.results : null;
+    const dots = res && res.length === total
+      ? res.map(r => ({ ch: '●', role: r.passed === true || r.status === 'passed' || r.ok === true ? 'ok' : 'error' }))
+      : [...Array(passed).fill({ ch: '●', role: 'ok' }), ...Array(Math.max(0, total - passed)).fill({ ch: '●', role: 'error' })];
+    const when = run.last_run_at ? ` · ${ago(run.last_run_at, now)} ago` : '';
+    if (passed === total && total > 0) return { dots, text: `${passed}/${total} pass${when}`, role: 'ok' };
+    return { dots, text: `${passed}/${total} pass · ${failed || total - passed} failing${when}`, role: 'error' };
+  }
+  const defined = s?.tests && typeof s.tests === 'object' ? Object.keys(s.tests).length : 0;
+  if (!defined) return null;
+  return { dots: Array(defined).fill({ ch: '○', role: 'muted' }), text: `${defined} defined · never run`, role: 'muted' };
+}
+
+const sourceOf = (s) => {
+  const parts = [];
+  if (s.category) parts.push(s.category);
+  if (s.createdAt) parts.push(`created ${day(s.createdAt)}`);
+  const tag = (s.tags || []).find(t => /^source:/.test(t));
+  if (tag) parts.push(`from ${tag.split(':')[1] === 'notesq' ? 'NotesQ' : tag.split(':')[1]}`);
+  if (s.authoringEnvelopeId) parts.push(`authored in ${short(s.authoringEnvelopeId, 12)}`);
+  if (s.lastPatchedBy) parts.push('patched since');
+  return parts.join(' · ');
+};
+
+/**
+ * d: { skill, scoreboard: { ok, row } | null, agentName?: (id) => string, now }
+ * -> view { box, rows }
+ */
+export function skillCard(d, cols) {
+  const s = d.skill || {};
+  const now = d.now ?? Date.now();
+  const w = boxWidth(cols, 72), inner = w - 4, nw = w < 50;
+  const rv = reviewState(s);
+  const name = s.name || s.id;
+  const right = s.version ? (nw ? `v${s.version}` : `v${s.version} · ${rv.word}`) : rv.word;
+  const rows = [];
+  if (s.description) rows.push([seg(fit(s.description, inner))]);
+  if (nw) rows.push([seg(rv.word, rv.role)]);
+
+  const agentName = d.agentName || ((id) => id);
+  const agents = (s.bestForAgents || []).map(id => String(agentName(id) || id));
+  const t = testsSummary(s, now);
+  const testRow = [];
+  if (t) {
+    testRow.push(seg('tests ', 'muted'));
+    for (const dt of t.dots.slice(0, 8)) testRow.push(seg(dt.ch, dt.role));
+    testRow.push(seg(` ${t.text}`, t.role));
+  } else testRow.push(seg('tests ', 'muted'), seg('none defined', 'muted'));
+  if (!nw && agents.length) {
+    testRow.push(seg('   agents ', 'muted'));
+    agents.slice(0, 3).forEach((a, i) => { if (i) testRow.push(seg(' ')); testRow.push(seg(a.toUpperCase(), `agent:${a}`)); });
+    if (agents.length > 3) testRow.push(seg(` +${agents.length - 3}`, 'muted'));
+  }
+  rows.push(testRow);
+  if (nw && agents.length) rows.push([seg('agents ', 'muted'), seg(agents.slice(0, 3).map(a => a.toUpperCase()).join(', '), `agent:${agents[0]}`)]);
+
+  const src = sourceOf(s);
+  if (src) rows.push([seg(fit(src, inner), 'muted')]);
+
+  const use = [];
+  const sb = d.scoreboard;
+  if (sb?.ok) {
+    const r = sb.row;
+    const n30 = Number(r?.total_invocations_30d) || 0;
+    if (!r || !n30) use.push(r?.last_used_at ? `no runs in 30d · last ${ago(r.last_used_at, now)} ago` : 'no recorded runs');
+    else {
+      use.push(`used ${plural(n30, 'time')} in 30d`);
+      if (r.last_used_at) use.push(`last ${ago(r.last_used_at, now)} ago`);
+      if (r.success_rate_30d != null) use.push(`${Math.round(Number(r.success_rate_30d) * 100)}% ok`);
+    }
+  }
+  const judge = s.evals?.judge;
+  if (judge && judge.avg_score != null) use.push(`judge ${judge.avg_score}/5${judge.scored_at ? ` (${day(judge.scored_at)})` : ''}`);
+  if (use.length) rows.push([seg(fit(use.join(' · '), inner), 'muted')]);
+
+  if (!nw && Array.isArray(s.policySatisfies) && s.policySatisfies.length) rows.push([seg(fit(`satisfies ${s.policySatisfies.join(', ')}`, inner), 'muted')]);
+
+  // Next possibility: only a capability that exists today. /skill runs a skill through a governed turn.
+  if (String(s.edition).toLowerCase() !== 'archived') rows.push([seg('next ', 'muted'), seg(`/skill ${name}`, 'key'), seg(nw ? ' runs it' : ' [args] runs it (governed turn)', 'muted')]);
+  else rows.push([seg('archived: kept for the record, not offered to agents', 'muted')]);
+
+  return { box: { width: w, title: `Skill · ${name}`, right, rightRole: rv.role, border: 'sky' }, rows };
+}

package/lib/quoxon/objects/view.js

@@ -0,0 +1,76 @@
+/**
+ * <ObjectView/>: the one Ink component for the inline object views. It maps a pure view (rows of
+ * { text, role } segments, optional box) to <Text> runs. `t` is seconds since arrival for the lab's
+ * decode-in (rows start 0.1 s apart); the default Infinity is the settled card, which is what history
+ * shows while there is no shared motion clock on main. Quiet (NO_COLOR or reduced motion) is always
+ * settled; NO_COLOR also drops every colour (c() returns undefined).
+ */
+import React from 'react';
+import { Box, Text } from 'ink';
+import { c, agentColor, mono } from '../theme.js';
+import { reducedMotion } from '../motion/clock.js';
+import { buildObject } from './index.js';
+import { decodeRow, padRow, fit, len } from './model.js';
+
+const h = React.createElement;
+
+/** Role -> Ink colour. agent:<name> uses the stable agent shade. */
+export function roleColor(role) {
+  if (mono()) return undefined;
+  if (typeof role === 'string' && role.startsWith('agent:')) return agentColor(role.slice(6));
+  return c(role || 'value');
+}
+
+function runsOf(cells, key) {
+  const out = [];
+  let run = '', role, bold = false, glyph = false, k = 0;
+  const flush = () => { if (run) out.push(h(Text, { key: `${key}-${k++}`, color: glyph ? roleColor('faint') : roleColor(role), bold }, run)); run = ''; };
+  for (const cl of cells) {
+    if (cl.role !== role || cl.bold !== bold || cl.glyph !== glyph) { flush(); role = cl.role; bold = cl.bold; glyph = cl.glyph; }
+    run += cl.ch;
+  }
+  flush();
+  return out;
+}
+
+/** Rows start this far apart (at most 0.1 s, the lab) so the last one lands inside the 0.65 s reveal window. */
+export const STAGGER_SPAN = 0.3;
+export const rowStart = (i, n) => i * Math.min(0.1, STAGGER_SPAN / Math.max(1, n - 1));
+const rowNode = (row, i, n, t, key) => h(Text, { key, wrap: 'truncate' }, ...runsOf(decodeRow(row, t, rowStart(i, n), 0.25, 70 + i), key));
+
+export function ObjectView({ item, cols, fx = null, t = fx && fx.e != null ? fx.e : Infinity, now }) {
+  const view = buildObject(item.obj || item, cols, now);
+  const tt = reducedMotion() ? Infinity : t;
+  const rows = view.rows || [];
+  if (!view.box) {
+    return h(Box, { flexDirection: 'column', marginTop: 1, paddingLeft: 2 }, ...rows.map((r, i) => rowNode(r, i, rows.length, tt, `r${i}`)));
+  }
+  const b = view.box, w = b.width, inner = w - 4;
+  const bc = roleColor(b.border || 'muted');
+  const right = b.right ? ` ${b.right} ` : '';
+  const title = b.title ? ` ${fit(b.title, Math.max(4, w - 6 - (right ? len(right) + 1 : 0)))} ` : '';
+  const fill = Math.max(0, w - 3 - len(title) - len(right) - 1);
+  const top = h(Text, { key: 'top', wrap: 'truncate' },
+    h(Text, { color: bc }, '╭─'),
+    h(Text, { color: roleColor(b.titleRole || 'value'), bold: true }, title),
+    h(Text, { color: bc }, '─'.repeat(fill)),
+    h(Text, { color: roleColor(b.rightRole || 'muted') }, right),
+    h(Text, { color: bc }, '─╮'));
+  const body = rows.map((r, i) => h(Text, { key: `b${i}`, wrap: 'truncate' },
+    h(Text, { color: bc }, '│ '), ...runsOf(decodeRow(padRow(r, inner), tt, rowStart(i, rows.length), 0.25, 70 + i), `b${i}`), h(Text, { color: bc }, ' │')));
+  const bottom = h(Text, { key: 'bot', color: bc }, '╰' + '─'.repeat(w - 2) + '╯');
+  return h(Box, { flexDirection: 'column', marginTop: 1, paddingLeft: 1 }, top, ...body, bottom);
+}
+
+/** Plain text of a view at a width (tests, transcripts, --print): the box drawn with the same geometry. */
+export function objectText(item, cols, now) {
+  const view = buildObject(item.obj || item, cols, now);
+  const rt = (r) => r.map(s => s.text).join('');
+  if (!view.box) return view.rows.map(r => '  ' + rt(fitRowText(r, cols - 2))).join('\n');
+  const b = view.box, w = b.width, inner = w - 4;
+  const right = b.right ? ` ${b.right} ` : '';
+  const title = b.title ? ` ${fit(b.title, Math.max(4, w - 6 - (right ? len(right) + 1 : 0)))} ` : '';
+  const fill = Math.max(0, w - 3 - len(title) - len(right) - 1);
+  return [` ╭─${title}${'─'.repeat(fill)}${right}─╮`, ...view.rows.map(r => ` │ ${rt(padRow(r, inner))} │`), ` ╰${'─'.repeat(w - 2)}╯`].join('\n');
+}
+const fitRowText = (r, n) => padRow(r, n).filter((s, i, a) => !(i === a.length - 1 && /^ +$/.test(s.text)));

package/lib/quoxon/objects/workflow.js

@@ -0,0 +1,119 @@
+/**
+ * E2 workflow step flow from ONE real execution: the step list comes from the workflow definition
+ * (GET /api/workflows/:id on quoxflow) in edge order, and each step's state and timing from that
+ * execution's AEE envelopes (GET /api/executions/:id/envelopes: quox.flow.node.started | completed |
+ * failed | skipped, keyed by payload.nodeId). Only the running step moves; a human gate
+ * (approval:gate, human:task) that is reached shows amber. A step with no envelope is shown as
+ * not reached, and when no envelopes could be read every state is '?', never guessed.
+ */
+import { seg, fit, dur, hhmm, short, parseTs } from './model.js';
+
+export const isGateType = (type) => /^(approval|human|hitl)[:_-]|(^|:)(approval|hitl|human)(gate|task)?$/i.test(String(type || ''));
+
+/** Definition nodes in execution order (Kahn over edges; definition order breaks ties). */
+export function orderNodes(def) {
+  const nodes = Array.isArray(def?.nodes) ? def.nodes : [];
+  const edges = Array.isArray(def?.edges) ? def.edges : [];
+  const ids = nodes.map(n => n.id);
+  const indeg = new Map(ids.map(id => [id, 0]));
+  for (const e of edges) if (indeg.has(e.target) && indeg.has(e.source)) indeg.set(e.target, indeg.get(e.target) + 1);
+  const out = [], seen = new Set();
+  const queue = ids.filter(id => indeg.get(id) === 0);
+  while (queue.length) {
+    const id = queue.shift();
+    if (seen.has(id)) continue;
+    seen.add(id); out.push(id);
+    for (const e of edges) if (e.source === id && indeg.has(e.target)) { indeg.set(e.target, indeg.get(e.target) - 1); if (indeg.get(e.target) === 0) queue.push(e.target); }
+  }
+  for (const id of ids) if (!seen.has(id)) out.push(id); // a cycle or dangling edge: keep definition order
+  const byId = new Map(nodes.map(n => [n.id, n]));
+  return out.map(id => byId.get(id));
+}
+
+/** nodeId -> { started, completed, failed, skipped, payload, nodeName, nodeType } from envelopes. */
+export function nodeStates(envelopes) {
+  const st = new Map();
+  for (const e of envelopes || []) {
+    const p = e?.payload || {};
+    const id = p.nodeId;
+    if (!id || !/^quox\.flow\.node\./.test(String(e.intent || ''))) continue;
+    const s = st.get(id) || { id };
+    const ts = parseTs(e.ts);
+    const kind = String(e.intent).slice('quox.flow.node.'.length);
+    if (kind === 'started') { if (s.started == null || ts < s.started) s.started = ts; s.nodeName ??= p.nodeName; s.nodeType ??= p.nodeType; }
+    else if (kind === 'completed') { s.completed = ts; s.result = p; }
+    else if (kind === 'failed') { s.failed = ts; s.error = p.error || p.message || null; }
+    else if (kind === 'skipped') s.skipped = ts;
+    st.set(id, s);
+  }
+  return st;
+}
+
+const triggerDetail = (n) => {
+  const c = n?.config || {};
+  return c.label || c.expression || c.event || c.path || '';
+};
+
+/**
+ * d: { execution, envelopes: [] | null, def: { nodes, edges } | null, now }
+ * -> view { rows } (no box: the lab draws this as an indented flow)
+ */
+export function stepFlow(d, cols) {
+  const ex = d.execution || {};
+  const now = d.now ?? Date.now();
+  const nw = cols < 60;
+  const rows = [];
+  const status = String(ex.status || 'unknown');
+  const head = [seg(ex.workflowName || ex.workflowId || 'workflow', 'value', true), seg('  ')];
+  const meta = [`run ${short(ex.id, 10)}`, status];
+  if (!nw && ex.startedAt) meta.push(`started ${hhmm(ex.startedAt)}`);
+  head.push(seg(meta.join(' · '), status === 'failed' ? 'error' : 'muted'));
+  rows.push(head);
+
+  const states = d.envelopes ? nodeStates(d.envelopes) : null;
+  let nodes = d.def ? orderNodes(d.def) : [];
+  if (!nodes.length && states) nodes = [...states.values()].filter(s => !/_replay_\d+$/.test(s.id)).map(s => ({ id: s.id, name: s.nodeName, type: s.nodeType }));
+  if (!nodes.length) {
+    rows.push([seg(d.envelopes ? 'No step records for this run.' : 'Steps could not be read for this run (no definition or envelopes).', 'muted')]);
+    return { rows };
+  }
+  const running = status === 'running' || status === 'paused';
+  const nameW = Math.min(Math.max(12, Math.floor((cols - 8) * 0.45)), Math.max(8, ...nodes.map(n => [...String(n.name || n.id)].length)));
+  for (const n of nodes) {
+    const s = states?.get(n.id);
+    const type = n.type || s?.nodeType || '';
+    const gate = isGateType(type);
+    let mark = '?', mrole = 'muted', nrole = 'value', det = '', drole = 'muted', bold = false;
+    if (!states) { det = 'state not readable'; }
+    else if (/^trigger/.test(type)) { mark = '●'; mrole = 'sky'; det = triggerDetail(n); }
+    else if (s?.failed != null) { mark = '✖'; mrole = 'error'; det = fit(s.error ? `failed: ${s.error}` : 'failed', 60); drole = 'error'; }
+    else if (s?.completed != null) {
+      mark = '✓'; mrole = 'ok';
+      const r = s.result || {};
+      const bits = [];
+      if (r.actions_taken != null) bits.push(`${r.actions_taken} action${r.actions_taken === 1 ? '' : 's'}`);
+      if (s.started != null) bits.push(dur(s.completed - s.started));
+      det = bits.join(' · ');
+    } else if (s?.skipped != null) { mark = '○'; mrole = 'faint'; nrole = 'muted'; det = 'skipped'; }
+    else if (s?.started != null && running) {
+      if (gate) { mark = '◐'; mrole = 'warn'; det = 'waiting for approval'; drole = 'warn'; }
+      else { mark = '◐'; mrole = 'sky'; bold = true; det = `running · ${dur(now - s.started)}`; }
+    } else if (s?.started != null) { mark = '?'; det = `started, no end recorded (run ${status})`; drole = 'warn'; }
+    else { mark = '○'; mrole = 'faint'; nrole = 'muted'; if (gate && running) { det = 'human gate'; drole = 'warn'; } }
+    rows.push([seg(' │', 'faint')]);
+    const nm = fit(n.name || n.id, nameW);
+    const row = [seg(' '), seg(mark, mrole, bold), seg(' '), seg(nm, nrole, bold)];
+    if (det) {
+      const pad = nw ? '  ' : ' '.repeat(Math.max(2, nameW + 2 - [...nm].length));
+      row.push(seg(pad), seg(fit(det, Math.max(6, cols - 6 - (nw ? [...nm].length + 2 : nameW + 2))), drole));
+    }
+    rows.push(row);
+  }
+  if (!running && (ex.duration != null || ex.completedAt)) {
+    const total = ex.duration != null ? dur(ex.duration) : dur(parseTs(ex.completedAt) - parseTs(ex.startedAt));
+    rows.push([seg(' ')]);
+    if (status === 'failed') rows.push([seg('✖ ', 'error'), seg(fit(`failed${total ? ` after ${total}` : ''}${ex.error ? `: ${typeof ex.error === 'string' ? ex.error : ex.error.message || ''}` : ''}`, cols - 6), 'error')]);
+    else rows.push([seg(status === 'completed' ? '✔ ' : '· ', status === 'completed' ? 'ok' : 'muted'), seg(`${status}${total ? ` in ${total}` : ''}${ex.envelopeCount != null ? ` · ${ex.envelopeCount} envelopes` : ''}`, 'muted')]);
+  }
+  return { rows };
+}

package/lib/quoxon/observers.js

@@ -0,0 +1,42 @@
+/**
+ * /observers: facts from persisted data only (LUCID situation, LUCID changes, lessons taught,
+ * reflect / learn / insight counters). No model-generated text: every line is a stored field
+ * or a count of them. Pure: takes api.observers() output, returns [[text, tone]].
+ */
+import { clip } from './theme.js';
+
+const why = (p) => (p.unavailable ? 'no endpoint on this server' : `unreadable (${p.error})`);
+
+export function observerLines(o, cols = 80) {
+  const out = [];
+  const add = (t, tone) => out.push([clip(t, cols - 4), tone]);
+  const sit = o.situation;
+  if (!sit?.ok) add(`◉ LUCID situation: ${why(sit || { error: 'no answer' })}`, 'warn');
+  else {
+    const s = sit.v?.situation || {};
+    add(`◉ LUCID: ${s.L0 || 'no summary recorded'}`);
+    const needs = s.needs_you || [];
+    needs.slice(0, 3).forEach(n => add(`  needs you: ${n.L0 || n.ref}`, 'warn'));
+    if (needs.length > 3) add(`  +${needs.length - 3} more needing you (quox lucid)`);
+    const cs = s.cannot_see || {};
+    const blind = [...(cs.unwired || []).map(x => `${x} not wired`), ...(cs.silent || []).map(x => `${x.feed} silent`), ...(cs.failing || []).map(x => `${x.feed || x} failing`)];
+    if (cs.coverage) add(`  sees ${cs.coverage.live} of ${cs.coverage.expected} sources${blind.length ? `; ${blind.join(', ')}` : ''}`);
+    const total = s.changed_total ?? (s.changed || []).length;
+    const range = s.cursor ? ` (journal ${s.cursor.from} to ${s.cursor.to})` : '';
+    add(`◉ Changed since you last looked: ${total}${range}`);
+    (s.changed || []).slice(0, 5).forEach(c => add(`  ${c.L0 || c.ref}${c.from && c.to ? ` (${c.from} to ${c.to})` : ''}`));
+    if (total > 5) add(`  +${total - 5} more (quox lucid since-last)`);
+  }
+  out.push(['', undefined]);
+  add('Self-learning records');
+  const les = o.lessons;
+  add(les?.ok ? `  LUCID lessons taught: ${(les.v?.lessons || []).length}` : `  LUCID lessons: ${why(les || { error: 'no answer' })}`);
+  for (const p of o.learning || []) {
+    if (!p.ok) { add(`  ${p.label || 'stat'}: ${why(p)}`); continue; }
+    const f = p.v.fields || {};
+    const last = f.lastOutcomeAt || f.lastObservationAt || f.lastSignalAt || f.lastClusterAt;
+    add(`  ${p.v.label}: ${p.v.text || 'no data'}${last ? ` · last ${last}` : ''}`);
+  }
+  add('  Memory consolidation: no read API found, not shown.');
+  return out;
+}

package/lib/quoxon/onboarding/copy.js

@@ -0,0 +1,235 @@
+/**
+ * Getting started: EVERY line the setup guide shows lives in this file, so the owner can review the whole
+ * first impression in one place (FIRST_RUN_JOURNEY.md, "Copy review"). House voice: no em dashes, no
+ * double hyphens in prose, `Quox` mixed case, nothing claimed that the code does not do.
+ *
+ * Functions take the facts they print (a URL, a size, a provider name); nothing here computes anything.
+ */
+
+export const LABEL = 'Getting started';
+export const LABEL_SUB = 'setup guide · no AI yet, every line here is scripted';
+
+// The Q says HELLO itself, decoded in beside the mark right after the intro (qmotion.js HelloIntro); the
+// guide then carries on with GREETING_REST. GREETING is the whole sentence, for anywhere that shows it at once.
+export const HELLO = "Hi, I'm Quox.";
+export const GREETING_REST = 'I run AI agents for you on your own machine, and I keep proof of everything they do.';
+export const GREETING = `${HELLO} ${GREETING_REST}`;
+export const QUESTION = 'What would you like help with?';
+export const EXAMPLES = ['watch my servers', 'automate something', 'code with agents', 'sort my email', 'just look around'];
+export const INPUT_PLACEHOLDER = 'Type anything, or a number from the list';
+
+/** One tailored line per intent: what Quox will do for that. */
+export const INTENT_LINES = {
+  servers: 'Quox can keep an eye on your servers, tell you what changed, and ask you before it touches anything.',
+  automate: 'Quox can run that as a workflow on a schedule, with an approval step wherever you want one.',
+  code: 'Quox can run coding agents on your repos, and every change they make leaves a receipt you can check.',
+  email: 'Quox can sort your inbox and draft replies. Nothing is sent without your say so.',
+  explore: 'Good plan. Once your Quox is running I will show you around, with real agents and real receipts.'
+};
+
+/** Off-script: an honest deferral, shown instantly (no model is running yet). */
+export const DEFERRAL = 'I can answer that properly once your Quox is running.';
+
+// The install time is NOT promised as a number until it has been measured on a clean machine (C2 exit).
+export const OFFER = "To do that I need a QuoxCORE, the engine your agents run in. It runs here in Docker, it's free for your own use, and the first install builds from source, so it takes a while.";
+export const OFFER_ASK = 'Set it up now? (Y/n)';
+export const ALREADY = 'Already have one? /connect server <url>';
+export const DECLINED = 'No problem. Run quox any time and we will pick up here.';
+export const DECLINED_HINT = 'Type yes to set up now, /connect server <url> to use one you have, or /exit.';
+
+export const RESUME = 'Picking up where we left off.';
+export const resumeRequest = (text) => `You asked: "${text}"`;
+
+// ---- /connect server ---------------------------------------------------------------------------
+export const CONNECT_USAGE = 'Usage: /connect server <url>   for example /connect server https://quox.example.com';
+export const connectBadUrl = (u) => `That does not look like a server address: ${u}. Use the full URL, starting with https://`;
+export const connectHandoff = (url) => `Connecting to ${url}. Sign in with your QuoxCORE email and password.`;
+export const CONNECT_DONE = 'Signed in. Starting Quox.';
+export const connectFailed = (url) => `Sign-in to ${url} did not complete. Check the address, then try /connect server again.`;
+export const CONNECT_INTENT_LINE = 'Great. Point me at it with /connect server <url> and sign in, and we go straight to your agents.';
+
+// ---- preflight ---------------------------------------------------------------------------------
+export const PREFLIGHT_TITLE = 'Checking this machine';
+export const PREFLIGHT_RETRY = 'r to check again · q to stop';
+export const PREFLIGHT_RETRY_DRY = 'r to check again · c to continue anyway (dry run) · q to stop';
+export const PREFLIGHT_CONTINUED = 'Continuing anyway: dry run, so nothing will be installed on this machine.';
+export const PREFLIGHT_OK = 'This machine is ready.';
+export const PREFLIGHT_FAIL = 'Fix the items above, then press r to check again.';
+export const SETUP_DOCS = 'https://quox.ai/docs/setup';
+
+export const CHECK = {
+  docker: {
+    name: 'DOCKER',
+    ok: (v) => `Docker ${v}, daemon reachable`,
+    missing: 'Docker is not installed',
+    missingFix: 'Install Docker, then press r.',
+    missingLink: 'https://docs.docker.com/get-docker/',
+    perm: 'Docker is installed, but this user cannot reach the daemon',
+    permFix: 'Run: sudo usermod -aG docker $USER && newgrp docker   then press r.',
+    down: 'Docker is installed, but the daemon is not running',
+    downFix: 'Start Docker (Docker Desktop, or: sudo systemctl start docker), then press r.',
+    link: 'https://docs.docker.com/engine/install/'
+  },
+  compose: {
+    name: 'COMPOSE',
+    ok: (v) => `Compose v${String(v).replace(/^v/, '')}`,
+    missing: 'Docker Compose v2 was not found',
+    missingFix: 'Install the Compose plugin (it ships with Docker Desktop), then press r.',
+    old: (v) => `Compose ${v} is too old, v2 is needed`,
+    link: 'https://docs.docker.com/compose/install/'
+  },
+  tools: {
+    name: 'TOOLS',
+    ok: 'git and openssl found',
+    missing: (list) => `Not found: ${list.join(', ')}`,
+    fix: (list) => `Install ${list.join(' and ')} with your package manager, then press r.`,
+    link: 'https://quox.ai/docs/setup'
+  },
+  disk: {
+    name: 'DISK',
+    ok: (gb) => `${gb} GB free`,
+    low: (gb, rec) => `${gb} GB free, ${rec} GB recommended (it may run out while building)`,
+    fail: (gb, min) => `${gb} GB free, at least ${min} GB needed`,
+    fix: (min) => `Free up space until at least ${min} GB is available, then press r.`,
+    link: 'https://quox.ai/docs/setup'
+  },
+  ram: {
+    name: 'MEMORY',
+    ok: (gb) => `${gb} GB of RAM`,
+    low: (gb, rec) => `${gb} GB of RAM, ${rec} GB recommended (it will run, slowly)`,
+    fail: (gb, min) => `${gb} GB of RAM, at least ${min} GB needed`,
+    fix: (min) => `Quox needs a machine with at least ${min} GB of RAM.`,
+    link: 'https://quox.ai/docs/setup'
+  },
+  ports: {
+    name: 'PORTS',
+    ok: (n) => `${n} ports free`,
+    busy: (list) => `In use: ${list.length > 5 ? `${list.slice(0, 4).join(', ')} and ${list.length - 4} more` : list.join(', ')}`,
+    ownInstall: 'In use by the Quox being installed here',
+    quoxFix: 'Quox looks like it is already running here. Use it with /connect server https://localhost:3000, or stop it first.',
+    fix: (p) => `Stop whatever is using port ${p} (see: ss -ltnp 'sport = :${p}'), then press r.`,
+    link: 'https://quox.ai/docs/setup'
+  },
+  running: 'checking'
+};
+
+// ---- credential --------------------------------------------------------------------------------
+export const CRED_TITLE = 'Which AI should your agents use?';
+export const CRED_HINT = '↑↓ to choose · Enter to pick';
+export const CRED_OPTIONS = {
+  chatgpt: { label: 'Sign in with ChatGPT', note: 'coming soon' },
+  openai: { label: 'OpenAI API key', note: '' },
+  anthropic: { label: 'Claude API key', note: '' },
+  ollama: { label: 'Ollama on this machine', note: 'found at localhost:11434' },
+  // B3: offered even when nothing answers locally; the user enters the LAN URL of the machine running it.
+  ollamaLan: { label: 'Ollama on another machine', note: 'enter its URL' },
+  skip: { label: 'Skip for now', note: 'agents will be limited' }
+};
+export const credPrompt = (label) => `Paste your ${label}. It stays in memory only: never written to disk, history or the transcript.`;
+export const CRED_INPUT_HINT = 'Enter to use it · Esc to go back';
+export const credHeld = (label, fp) => `${label} held in memory (fingerprint ${fp}). It is stored in your Quox vault after install, never on disk here.`;
+export const CRED_EMPTY = 'Nothing was pasted. Paste the key, or Esc to choose again.';
+export const CRED_OLLAMA = 'Ollama it is. The Quox server runs in Docker and cannot reach "localhost", so after install connect it by this machine\'s LAN address: start Ollama with OLLAMA_HOST=0.0.0.0, then /connect ollama http://<lan-ip>:11434';
+export const OLLAMA_URL_PROMPT = 'The Ollama URL on your network, for example http://<lan-ip>:11434. Not a secret. On that machine, start Ollama with OLLAMA_HOST=0.0.0.0 and allow port 11434.';
+export const OLLAMA_URL_HINT = 'Enter to use it · Esc to go back';
+export const OLLAMA_URL_BAD = 'That does not look like an Ollama URL. Use http://<host>:11434, or Esc to choose again.';
+export const ollamaChosen = (url) => `Ollama it is, at ${url}. After install, run /connect ollama ${url} so the server checks it and lists its models.`;
+export const CRED_SKIPPED = 'Skipped. Until you add an AI your agents are limited: they cannot think or answer for themselves. Add one later with /connect.';
+export const CRED_CHATGPT_SOON = 'Sign in with ChatGPT is coming soon. Pick another option for now.';
+
+// ---- install -----------------------------------------------------------------------------------
+export const INSTALL_TITLE = 'Installing Quox';
+export const INSTALL_DRY = 'dry run: nothing is downloaded, built or started';
+export const INSTALL_HINT = 'v to show the log · Ctrl+C to stop (you can pick it up again)';
+export const STAGES = {
+  fetch: 'Fetch the source',
+  configure: 'Configure secrets and certificates',
+  build: 'Build the images',
+  start: 'Start the services',
+  health: 'Wait until healthy'
+};
+export const INSTALL_FAILED = (stage) => `The install stopped at: ${stage}. Press v for the log, r to try again.`;
+export const INSTALL_NOT_YET = 'Installing from here arrives in the next release. For now, run this in another terminal:';
+export const INSTALL_COMMAND = 'curl -fsSL https://get.quox.ai | sh';
+export const INSTALL_NOT_YET_AFTER = 'Then run quox again and type /connect server https://localhost:3000';
+export const INSTALL_KEY_GONE = 'Your key was not kept: it only ever lived in memory. You will add it again after install.';
+export const installWhere = (dir) => `Installing into ${dir}`;
+export const installScriptLead = (url, bytes) => `Installer ${url} (${Math.max(1, Math.round(bytes / 1024))} KB), SHA256`;
+export const installScript = (url, sha, bytes) => `${installScriptLead(url, bytes)} ${sha}`;
+export const INSTALL_STOP_ASK = 'Stop the install? You can pick it up next time. (y/N)';
+export const INSTALL_STOP_KEEP = 'Carrying on.';
+export const INSTALL_STOPPED = 'Install stopped. Run quox to pick up where you left off.';
+export const INSTALL_EARLIER = 'done earlier';
+export const INSTALL_HEALTH_ONLY = 'Your Quox was already started last time, so this only checks that it is healthy.';
+export const INSTALL_DEGRADED = 'Some services are still starting. Press r to check again in a minute, or v for the log.';
+export const INSTALL_FAIL_HINT = 'v log · r try again · Ctrl+C stop';
+
+// ---- owner account (C2c) -----------------------------------------------------------------------
+export const OWNER_TITLE = 'Your owner account';
+export const OWNER_WHY = 'This account owns your Quox. You sign in to the dashboard with it.';
+export const OWNER_EMAIL_PLACEHOLDER = 'your email address';
+export const OWNER_EMAIL_BAD = 'That does not look like an email address.';
+export const OWNER_PW_PROMPT = 'Choose a password: 12 or more characters with upper and lower case, a number and a symbol. Or press Enter on an empty line and I will make a strong one.';
+export const OWNER_PW_HINT = 'Enter to use it · Enter on empty to generate one · Esc to change the email';
+export const ownerPwShownOnce = (pw) => `Your password, shown once: ${pw}`;
+export const OWNER_PW_SAVE = 'Save it in your password manager now. Quox keeps only a sign-in token on this machine, never the password.';
+export const OWNER_EXISTS = 'This Quox already has an owner. Enter that account\'s email and password to sign in.';
+
+// ---- finishing ---------------------------------------------------------------------------------
+export const FINISH_TITLE = 'Finishing';
+export const FIN = {
+  account: { name: 'ACCOUNT', running: 'creating your owner account', ok: (e) => `owner ${e}`, existing: (e) => `existing owner ${e}` },
+  signin: { name: 'SIGN-IN', running: 'signing you in', ok: (org) => `signed in${org ? ` to ${org}` : ''}, token saved` },
+  vault: {
+    name: 'AI KEY', running: (label) => `testing your ${label}, then storing it in your vault`,
+    skipped: 'no key to store', ollama: 'Ollama: add it to your vault with quox vault create --type ollama'
+  },
+  link: { name: 'DASHBOARD', running: 'making your one-time sign-in link', ok: 'one-time link ready (10 minutes, single use)', fail: (e) => `no link (${e}), sign in with your owner account instead` }
+};
+export const KEY_GONE_AFTER = 'The key is gone from this terminal\'s memory now.';
+export const keyNotStored = (provider) => `Add it again any time with /connect ${provider}.`;
+
+// ---- finale ------------------------------------------------------------------------------------
+export const FINALE_DRY_BANNER = 'Dry run: this is the planned finish. Nothing was installed.';
+export const FINALE_RUNNING = 'Your Quox is running.';
+export const REPLAY_TOUR = 'Give me a short tour of what you can do here.';
+export const finaleReplay = (text) => text ? `Your first real turn sends what you asked: "${text}"` : 'Your first real turn: a short tour of what your agents can do.';
+export const FINALE_REPLAY_DRY = '(the reply and its receipt appear here once the install is real)';
+export const finaleDashboard = (url) => `Your dashboard is ready: ${url} (one-time sign-in link)`;
+export const finaleDashboardPlain = (url) => `Your dashboard is ready: ${url} (sign in with your owner account)`;
+// When the line does not fit the terminal, the URL goes on its own unwrapped line so it stays clickable.
+export const FINALE_DASHBOARD_LEAD = 'Your dashboard is ready (one-time sign-in link, 10 minutes):';
+export const FINALE_DASHBOARD_LEAD_PLAIN = 'Your dashboard is ready (sign in with your owner account):';
+export const FINALE_CERT = 'Your browser will warn about the certificate the first time: it is the self-signed one this install made for you.';
+export const FINALE_PROOF = 'Everything you just did is there, with the proof.';
+export const FINALE_TIPS_TITLE = 'Three things to try:';
+export const TIPS = {
+  servers: ['/observers shows what Quox can see right now, and what it cannot', '/connect shows what is connected and adds AI keys safely', 'Just run quox any time; your conversations are kept on your server'],
+  automate: ['/skills lists what your agents already know how to do', '/approvals shows anything waiting for your yes', 'Just run quox any time; your conversations are kept on your server'],
+  code: ['/attach <agent> sends your turns to one agent, /detach comes back', '/connect shows what is connected and adds AI keys safely', 'Just run quox any time; your conversations are kept on your server'],
+  email: ['/approvals shows anything waiting for your yes; nothing is sent without it', '/connect shows what is connected and adds AI keys safely', 'Just run quox any time; your conversations are kept on your server'],
+  explore: ['/help lists every command', '/attach <agent> sends your turns to one agent, /detach comes back', 'Just run quox any time; your conversations are kept on your server']
+};
+TIPS.offscript = TIPS.explore;
+export const FINALE_TIPS = TIPS.explore; // the dry run and any intent without its own set
+// K2: one gentle, honest next connection that fits what they said they wanted.
+export const K2 = {
+  servers: 'You said you want to watch your servers. None are connected yet, and adding one from the terminal is not built yet: add your first host on the dashboard Fleet page.',
+  automate: 'You said you want to automate something. Already use n8n? Bring a workflow across with: quox workflow import-n8n --file <path>',
+  code: 'You said you want to code with agents. Connect GitHub so they can see your repos: quox vault create --type github',
+  email: 'You said you want help with email. Connect your mailbox: quox mail connect --provider gmail (or outlook, icloud)',
+  explore: 'Want your agents to do more? /connect shows what is connected and what you can add.'
+};
+K2.offscript = K2.explore;
+export const k2NoAi = (provider) => `Your agents have no AI yet, so they cannot answer for themselves. Connect one now? /connect ${provider}`;
+export const FINALE_EXIT = 'Enter to start talking to your Quox';
+export const FINALE_EXIT_DRY = 'Enter to finish';
+
+// ---- help, misc --------------------------------------------------------------------------------
+export const HELP = [
+  ['/connect server <url>', 'use a QuoxCORE you already have'],
+  ['/exit', 'leave; next time we pick up here']
+];
+export const SLASH_UNKNOWN = 'Only /connect server, /help and /exit work until your Quox is running.';
+export const BYE = 'See you soon. Run quox to pick up where you left off.';
+export const NO_SERVER_PRINT = 'Run quox (without --print) to get started.';