quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/onboarding/copy.js

@@ -0,0 +1,263 @@
+/**
+ * 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.
+ */
+import { askText } from '../ask.js';
+
+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 receipts you can check for what 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 = askText('Set it up now?', { keys: '(Y/n)', who: 'Quox', action: 'connect an AI and install the Quox server, step by step' });
+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 connectChecking = (url) => `Checking ${url} is a QuoxCORE server...`;
+export const CONNECT_CANCELLED = 'Cancelled. Nothing was saved: the previous server address is back.';
+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 ---------------------------------------------------------------------------------
+// FIRSTRUN: the guide offers to fix Docker itself (dockerOffer.js), so nobody has to leave it to do so.
+export const DOCKER_OFFER_QUESTION = {
+  install: 'Install Docker for you now?',
+  group: 'Add you to the docker group now?',
+  relaunch: 'Carry on now with the docker group, without logging out?'
+};
+export const DOCKER_OFFER_HINT = 'y yes · r check again · q stop';
+export const DOCKER_OFFER_RUNNING = 'Running (sudo may ask for your password):';
+export const DOCKER_OFFER_FAILED = 'That did not finish. Fix what it said, then run quox to pick up where you left off.';
+export const DOCKER_OFFER_RELAUNCH = 'Starting quox again with the docker group.';
+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.',
+    permStale: 'Docker is installed, and you are in the docker group, but this terminal started before that',
+    permStaleFix: 'Pressing r cannot fix this: a running terminal never gains a new group. Run: newgrp docker   (or open a new terminal), then run: quox',
+    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 credConsent = (label) => `${label} is a cloud AI: your messages and tool results are sent to it, so Quox needs your OK once. Say no and nothing goes to it until you give it later with /consent grant openai (or Settings > Privacy in the dashboard). A local model (Ollama) needs no consent.`;
+// QUOXON-Z2H lane R: the one consent question at the credential step. Default No: cloud processing stays opt-in.
+export const credConsentAsk = (who) => askText(`Allow Quox to send your conversations to ${who}?`, { keys: 'y/N', who: 'Quox', action: `send your messages and any tool results to ${who}, a third party, when it answers` });
+export const CRED_CONSENT_HINT = 'y yes · n or Enter no';
+export const credConsentYes = (who) => `Yes. Your OK for ${who} is recorded as soon as your owner account exists. Withdraw it any time in Settings > Privacy.`;
+export const credConsentNo = (who, provider) => `No. ${who} receives nothing until you give your OK: /consent grant ${provider}, or Settings > Privacy in the dashboard.`;
+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'
+};
+/** Z2H-IMAGES: the build stage relabels itself once setup.sh says whether it is downloading or building. */
+export const BUILD_LABELS = { download: 'Download the images', build: 'Build the images' };
+export const INSTALL_RERUN_HINT = 'It is safe to run the installer again: finished steps are kept and the build is cached.';
+export const INSTALL_LOG_PATH = (p) => `Full install log: ${p}`;
+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 = askText('Stop the install?', { reason: 'You can pick it up next time.', keys: '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'
+  },
+  consent: { name: 'CONSENT', running: (who) => `recording your OK for ${who}`, ok: (who) => `OK recorded for ${who}`, fail: (e, provider) => `not recorded (${e}), later: /consent grant ${provider}` },
+  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. Add your first with /hosts add (it needs no AI), or 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 K2_SERVERS_NO_INSTALLER = 'You said you want to watch your servers. None are connected yet, and this install cannot enrol hosts yet because its host installer is not available.';
+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.';
+export const FINALE_HOSTS_NO_AI = 'No AI needed to add a host: /hosts add shows the one command to run on that machine.';

package/lib/quoxon/onboarding/credential.js

@@ -0,0 +1,108 @@
+/**
+ * The credential step: which AI the agents use, and the key, held in memory only.
+ *
+ * `requestCredential(provider)` is THE hook for the K1 secure key card (/connect, branch session/quox-connect).
+ * Until that merges, the broker below backs it with this view's own masked input. Same rules either way: the
+ * secret never enters a transcript, history item, journey file, config file or event stream, and the only
+ * thing ever shown or persisted about it is its fingerprint.
+ */
+import { createHash } from 'node:crypto';
+import { CRED_OPTIONS } from './copy.js';
+
+export const PROVIDERS = ['chatgpt', 'openai', 'anthropic', 'ollama', 'skip'];
+export const KEY_PROVIDERS = new Set(['openai', 'anthropic']);
+// Sign in with ChatGPT stays visible but unselectable until OpenAI approves the integration.
+export const CHATGPT_ENABLED = false;
+
+/**
+ * Options in display order. #1288: the choices that work come first. Sign in with ChatGPT is not built
+ * yet (waiting on OpenAI), so while it is off it is listed LAST as "coming soon", never first; once it
+ * is on it leads (OpenAI-first). Ollama is always offered (B3): "on this machine" first when
+ * localhost:11434 answered, else "on another machine" (asks for its LAN URL) before Skip.
+ */
+export function credentialOptions({ ollama = false, chatgpt = CHATGPT_ENABLED } = {}) {
+  const working = ollama ? ['ollama', 'openai', 'anthropic', 'skip'] : ['openai', 'anthropic', 'ollama', 'skip'];
+  const order = chatgpt ? ['chatgpt', ...working] : [...working, 'chatgpt'];
+  return order.map(id => {
+    if (id === 'ollama') return { id, ...(ollama ? CRED_OPTIONS.ollama : CRED_OPTIONS.ollamaLan), detected: Boolean(ollama), disabled: false };
+    return { id, ...CRED_OPTIONS[id], disabled: id === 'chatgpt' && !chatgpt };
+  });
+}
+
+/** The next selectable row from `sel` in direction dir (1 down, -1 up), wrapping; disabled rows are skipped. */
+export function nextSelectable(options, sel, dir) {
+  const n = options.length;
+  if (!n) return 0;
+  for (let k = 1; k <= n; k++) {
+    const i = (((sel + dir * k) % n) + n) % n;
+    if (!options[i].disabled) return i;
+  }
+  return sel;
+}
+
+/** A typed Ollama URL -> normalised http(s) URL (bare host gets http:// and :11434) | null. */
+export function normaliseOllamaUrl(text) {
+  let v = String(text || '').trim();
+  if (!v || /\s/.test(v)) return null;
+  const bare = !/^[a-z][a-z0-9+.-]*:\/\//i.test(v);
+  if (bare) v = `http://${v}`;
+  let u;
+  try { u = new URL(v); } catch { return null; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
+  if (u.username || u.password || !u.hostname) return null;
+  if (bare && !u.port) u.port = '11434';
+  return u.toString().replace(/\/$/, '');
+}
+
+export const fingerprint = (secret) => 'sha256:' + createHash('sha256').update(String(secret)).digest('hex').slice(0, 8);
+
+/** A secret that refuses to serialise: JSON, String() and util.inspect all show a redaction. */
+export function holdSecret(provider, value) {
+  let v = String(value);
+  const fp = fingerprint(v);
+  const redacted = `[${provider} key ${fp}]`;
+  return Object.freeze({
+    provider,
+    fingerprint: fp,
+    reveal: () => v, // the ONE accessor: C2c hands it to the new instance's vault API, then drops it
+    drop: () => { v = ''; },
+    toJSON: () => redacted,
+    toString: () => redacted,
+    [Symbol.for('nodejs.util.inspect.custom')]: () => redacted
+  });
+}
+
+/**
+ * Broker behind requestCredential(): a single pending request the view renders as a masked card.
+ * K1 swap: replace createCredentialBroker().request with the secure card call; the view keeps working.
+ */
+export function createCredentialBroker() {
+  let pending = null;
+  const listeners = new Set();
+  const emit = () => { for (const fn of listeners) fn(pending); };
+  return {
+    /** requestCredential(provider) -> Promise<held secret | null (cancelled)> */
+    request(provider) {
+      if (pending) pending.resolve(null);
+      return new Promise((resolve) => {
+        pending = { provider, resolve: (val) => { pending = null; emit(); resolve(val); } };
+        emit();
+      });
+    },
+    submit(value) { if (pending && String(value).length) pending.resolve(holdSecret(pending.provider, value)); },
+    cancel() { pending?.resolve(null); },
+    get pending() { return pending ? { provider: pending.provider } : null; },
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); }
+  };
+}
+
+/**
+ * THE hook the view calls: requestCredential(provider) -> Promise<held secret | null>.
+ * K1 merge (session/quox-connect): return the secure key card's result here instead of broker.request(provider).
+ * Whatever backs it must keep the rules above (memory only, fingerprint the only trace).
+ */
+export function createRequestCredential(broker) {
+  return function requestCredential(provider) {
+    return broker.request(provider);
+  };
+}

package/lib/quoxon/onboarding/detect.js

@@ -0,0 +1,22 @@
+/**
+ * Should bare `quox` open Getting started instead of the chat client?
+ *
+ * Yes only when nothing says a server exists: no profile is signed in (human or resident), no profile points
+ * anywhere but the built-in default URL, no QUOX_URL, and the user did not ask for a specific profile or for
+ * the ambient service key. Anyone who has ever configured a server keeps today's honest "Not signed in"
+ * message instead (they need `quox login`, not an installer).
+ */
+export const DEFAULT_URL = 'http://localhost:3000';
+
+export function needsGettingStarted({ profiles = [], residents = [], profileArg = null, env = process.env, serviceKeyFlag = false, journey = null } = {}) {
+  if (profileArg) return false;
+  if (env.QUOX_URL) return false;
+  if ((serviceKeyFlag || env.QUOX_FORCE_SERVICE_KEY) && env.QUOX_SERVICE_KEY) return false;
+  if (residents.length) return false;
+  if (profiles.some(p => p.loggedIn)) return false;
+  // A journey this guide started (install or finish under way) keeps it here, even after the
+  // finish step pointed the profile at the new instance: nobody is signed in yet.
+  if (journey?.installStage || journey?.step === 'owner' || journey?.step === 'finishing') return true;
+  if (profiles.some(p => p.url && p.url.replace(/\/+$/, '') !== DEFAULT_URL)) return false;
+  return true;
+}

package/lib/quoxon/onboarding/dockerOffer.js

@@ -0,0 +1,45 @@
+/**
+ * FIRSTRUN (2026-10-19): the guide OFFERS to fix Docker instead of saying "install Docker, then press r".
+ *
+ *   install   Docker missing (Linux): Docker's official script, then add this user to the docker group
+ *   group     Docker installed, this user not in the docker group: add them
+ *   relaunch  in the group, but this terminal started before that: nothing to run with sudo
+ *
+ * A yes leaves the Ink view (the journey is saved at preflight), runs the command with the real terminal
+ * attached so sudo can ask for a password, then starts quox again under `sg docker`, so the new group applies
+ * without logging out. The relaunched quox picks up where the guide left off.
+ */
+import { spawnSync } from 'node:child_process';
+import { askText } from '../ask.js';
+import * as T from './copy.js';
+
+export const DOCKER_INSTALL_CMD = 'curl -fsSL https://get.docker.com | sudo sh && sudo usermod -aG docker "$USER"';
+export const DOCKER_GROUP_CMD = 'sudo usermod -aG docker "$USER"';
+const COMMANDS = { install: DOCKER_INSTALL_CMD, group: DOCKER_GROUP_CMD, relaunch: null };
+
+/** rows -> { kind, command, ask } for the first row the guide can fix, or null. */
+export function dockerOffer(rows) {
+  const r = (rows || []).find(x => x?.status === 'fail' && x.offer && x.offer in COMMANDS);
+  if (!r) return null;
+  const kind = r.offer;
+  const command = COMMANDS[kind];
+  const q = T.DOCKER_OFFER_QUESTION[kind];
+  const action = command ? `run: ${command}  then start quox again with the docker group` : 'start quox again with the docker group (sg docker), no sudo';
+  return { kind, command, ask: askText(q, { keys: 'y/N', who: 'Quox', action }) };
+}
+
+const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+/** Runs the offer with the terminal attached. -> { action: 'exit', status } */
+export function runDockerOffer(kind, { spawn = spawnSync, out = (s) => process.stdout.write(s), node = process.execPath, bin } = {}) {
+  const command = COMMANDS[kind];
+  if (command) {
+    out(`\n${T.DOCKER_OFFER_RUNNING}\n  ${command}\n\n`);
+    const r = spawn('sh', ['-c', command], { stdio: 'inherit' });
+    if (r?.status !== 0) { out(`\n${T.DOCKER_OFFER_FAILED}\n`); return { action: 'exit', status: r?.status ?? 1 }; }
+  }
+  out(`\n${T.DOCKER_OFFER_RELAUNCH}\n`);
+  const again = spawn('sg', ['docker', '-c', `exec ${shq(node)} ${shq(bin)}`], { stdio: 'inherit' });
+  if (again?.error) { out(`${T.CHECK.docker.permStaleFix}\n`); return { action: 'exit', status: 1 }; }
+  return { action: 'exit', status: again?.status ?? 0 };
+}

package/lib/quoxon/onboarding/failureCause.js

@@ -0,0 +1,33 @@
+/**
+ * FIRSTRUN (2026-10-19): a failed install says WHY in one plain line, for the causes a stranger can act on.
+ * Input: installer output plus the tail of the build log setup.sh names. Output: { kind, host?, message } | null.
+ * Prebuilt images being unavailable ("error from registry: denied") is never a cause: the installer builds instead.
+ */
+const RETRY = 'then press r to try again.';
+
+const NETWORK = [
+  /Could not connect to ([a-z0-9.-]+\.[a-z]{2,}):\d+/i,
+  /Temporary failure resolving '([^']+)'/i,
+  /Failed to fetch https?:\/\/([a-z0-9.-]+\.[a-z]{2,})\/\S*\s+(?:Could not connect|Unable to connect|Connection failed|Temporary failure)/i,
+  /request to https?:\/\/([a-z0-9.-]+\.[a-z]{2,})\/\S* failed, reason: (?:connect )?(?:ETIMEDOUT|ECONNRESET|ECONNREFUSED|EAI_AGAIN|ENOTFOUND)/i,
+  /getaddrinfo (?:EAI_AGAIN|ENOTFOUND) ([a-z0-9.-]+\.[a-z]{2,})/i
+];
+
+export function explainInstallFailure(text) {
+  const t = String(text ?? '');
+  if (!t.trim()) return null;
+  for (const re of NETWORK) {
+    const m = re.exec(t);
+    if (m) {
+      const host = m[1].toLowerCase();
+      return { kind: 'network', host, message: `The build could not reach ${host}, a package server. Check this machine's internet connection, firewall or proxy, ${RETRY}` };
+    }
+  }
+  if (/no space left on device/i.test(t)) {
+    return { kind: 'disk', message: `The disk filled up during the build. Free some space (docker system prune -f frees old build cache), ${RETRY}` };
+  }
+  if (/heap out of memory|exit code: 137\b|\bOOMKilled\b|Cannot allocate memory/i.test(t)) {
+    return { kind: 'memory', message: `The build ran out of memory. Close other programs or give this machine more RAM (8 GB is recommended), ${RETRY}` };
+  }
+  return null;
+}

package/lib/quoxon/onboarding/finish.js

@@ -0,0 +1,134 @@
+/**
+ * C2c: finishing a fresh install from the CLI (FIRST_RUN_JOURNEY.md steps 6, 7 and 9).
+ *
+ *   createOwner  POST /api/setup/admin        the instance's own first-owner route (refuses once an
+ *                                             owner exists; creates user, default org, membership)
+ *   signIn       POST /api/auth/login          via core/auth.js login(): the profile stores the login
+ *                                             token in its existing format. The password is never stored.
+ *   storeCredential  connect.js connectFlow    server-side test, then the governed vault write as the
+ *                                             org default (POST /api/orgs/:org/vault, audited, label
+ *                                             "<Name> …last4"). The held key is dropped right after.
+ *   loginLink    POST /api/auth/login-link     a 10 minute, single-use, user+org bound sign-in link,
+ *                                             joined to the dashboard URL the installer printed.
+ *
+ * The CLI talks to the services the way every other command does: profile url https://localhost:3000,
+ * services derived to their loopback ports (auth 127.0.0.1:3101), so the self-signed edge certificate
+ * never meets the CLI. Only the browser sees it, through the link.
+ */
+import { randomBytes, randomInt } from 'node:crypto';
+import { connectFlow } from '../connect.js';
+
+export const LOCAL_PROFILE_URL = 'https://localhost:3000';
+
+// The auth service's rules (services/auth/utils/passwordValidation.js).
+const SPECIAL = /[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?`~]/;
+export function passwordProblem(pw) {
+  const p = String(pw ?? '');
+  if (p.length < 12) return 'Use at least 12 characters.';
+  if (p.length > 256) return 'Use at most 256 characters.';
+  if (!/[A-Z]/.test(p)) return 'Add an uppercase letter.';
+  if (!/[a-z]/.test(p)) return 'Add a lowercase letter.';
+  if (!/[0-9]/.test(p)) return 'Add a number.';
+  if (!SPECIAL.test(p)) return 'Add a special character, for example - or !';
+  return null;
+}
+export const emailOk = (e) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(e ?? '').trim());
+
+/** 3 groups of 6 from an unambiguous alphabet, joined with '-', plus one guaranteed digit and capital. */
+export function generatePassword() {
+  const A = 'abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+  for (;;) {
+    const bytes = randomBytes(18);
+    const groups = [0, 1, 2].map(g => Array.from(bytes.subarray(g * 6, g * 6 + 6), b => A[b % A.length]).join(''));
+    const pw = `${groups.join('-')}-${randomInt(2, 10)}${'ABCDEFGHJKLMNPQRSTUVWXYZ'[randomInt(0, 24)]}`;
+    if (!passwordProblem(pw)) return pw;
+  }
+}
+
+const apiError = (e, fallback) => (e?.message && !/^\s*$/.test(e.message) ? e.message : fallback);
+
+/**
+ * -> finisher { kind, profileUrl, createOwner, signIn, storeCredential, loginLink }
+ * Dependencies are the CLI's own modules; tests run them for real against a fake instance.
+ */
+export async function createFinisher({ profileUrl = LOCAL_PROFILE_URL, fetchImpl = globalThis.fetch } = {}) {
+  const { loadConfig } = await import('../../core/config.js');
+  const { createAuth } = await import('../../core/auth.js');
+  const { createClient } = await import('../../core/client.js');
+  const { createApi } = await import('../api.js');
+
+  // Nothing is written here: the profile is pointed at the new instance only at sign-in, so leaving
+  // Getting started early never leaves a half-configured profile behind.
+  const config = loadConfig();
+  const auth = createAuth(config);
+  const client = createClient(config, auth);
+  const authUrl = () => config.getServiceUrl('auth');
+
+  return {
+    kind: 'real',
+    profileUrl,
+    authUrl,
+
+    /** -> { ok: true } | { ok: false, existed?: true, error } */
+    async createOwner({ email, password, name }) {
+      const display = name || String(email).split('@')[0];
+      let r;
+      try {
+        r = await fetchImpl(`${authUrl()}/api/setup/admin`, {
+          method: 'POST', headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ email: String(email).trim(), password, name: display, display_name: display })
+        });
+      } catch (e) { return { ok: false, error: `the auth service did not answer: ${e?.cause?.code || e?.message}` }; }
+      let body = null;
+      try { body = await r.json(); } catch { /* not json */ }
+      if (r.ok && body?.success) return { ok: true };
+      if (r.status === 400 && body?.error === 'admin_exists') return { ok: false, existed: true, error: body.message };
+      return { ok: false, error: body?.message || `HTTP ${r.status}` };
+    },
+
+    /** -> { ok: true, org } | { ok: false, error }. Stores the login token in the active profile. */
+    async signIn({ email, password }) {
+      try {
+        config.setProfileConnection({ url: profileUrl });
+        const data = await auth.login(authUrl(), String(email).trim(), password);
+        if (data?.mfa_required) return { ok: false, error: 'This account uses MFA. Finish signing in with: quox login' };
+        return { ok: true, org: data?.org?.name || null };
+      } catch (e) { return { ok: false, error: apiError(e, 'sign-in failed') }; }
+    },
+
+    /** held: a held secret from credential.js (or null). -> connectFlow result | { ok: false, skipped: true } */
+    async storeCredential(held) {
+      if (!held || typeof held.reveal !== 'function') return { ok: false, skipped: true };
+      try {
+        const api = createApi({ client, config, auth });
+        return await connectFlow(api, held.provider, held.reveal());
+      } finally {
+        held.drop();
+      }
+    },
+
+    /** QUOXON-Z2H lane R: the owner said yes at the credential step; record it as their own act. -> { ok } | { ok: false, error } */
+    async grantConsent(provider) {
+      try { await createApi({ client, config, auth }).grantConsent(provider); return { ok: true }; }
+      catch (e) { return { ok: false, error: apiError(e, 'consent not recorded') }; }
+    },
+
+    /** Z2H-R5 E: can this server serve its host installer? -> { ok, status } | null (unknown). Reads only. */
+    async hostInstaller() {
+      try {
+        const api = createApi({ client, config, auth });
+        const base = await api.hostsBaseUrl();
+        return await api.hostInstallCheck(base);
+      } catch { return null; }
+    },
+
+    /** -> { ok: true, url, expiresAt, ttlSeconds } | { ok: false, error } */
+    async loginLink(dashboardUrl) {
+      try {
+        const r = await client.post('/api/auth/login-link', { service: 'auth', body: {}, retries: 0 });
+        if (!r?.path || !/^\/api\/auth\/login-link\/consume\?t=/.test(r.path)) return { ok: false, error: 'unexpected answer from the auth service' };
+        return { ok: true, url: new URL(r.path, dashboardUrl || profileUrl).href, expiresAt: r.expires_at, ttlSeconds: r.ttl_seconds };
+      } catch (e) { return { ok: false, error: apiError(e, 'could not create the link') }; }
+    }
+  };
+}