quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/onboarding/credential.js

@@ -0,0 +1,95 @@
+/**
+ * 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. Ollama is always offered (B3): "on this machine" when localhost:11434
+ * answered, else "on another machine" (listed last), which asks for its LAN URL.
+ */
+export function credentialOptions({ ollama = false, chatgpt = CHATGPT_ENABLED } = {}) {
+  // Not detected: "on another machine" goes last, so the familiar numbering (4 = Skip) holds.
+  const order = ollama ? PROVIDERS : [...PROVIDERS.filter(p => p !== 'ollama'), 'ollama'];
+  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 };
+  });
+}
+
+/** 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/finish.js

@@ -0,0 +1,119 @@
+/**
+ * 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();
+      }
+    },
+
+    /** -> { 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') }; }
+    }
+  };
+}

package/lib/quoxon/onboarding/index.js

@@ -0,0 +1,67 @@
+/**
+ * Entry for Getting started (main.js calls this when no server is configured, or for --demo-onboarding).
+ * Runs the Ink view, then performs what it asked for: exit, or hand off to the existing `quox login` flow for
+ * `/connect server <url>`.
+ */
+import React from 'react';
+import { render } from 'ink';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { GettingStarted } from './view.js';
+import { inkStdout } from '../term.js';
+import { createCredentialBroker, createRequestCredential } from './credential.js';
+import { createDryRunRunner } from './runner.js';
+import { createInstallRunner, defaultInstallDir, probeAuthHealth } from './installRunner.js';
+import { createFinisher } from './finish.js';
+import { journeyPath as defaultJourneyPath, clearJourney, loadJourney } from './journey.js';
+import * as T from './copy.js';
+
+const QUOX_BIN = fileURLToPath(new URL('../../../bin/quox.js', import.meta.url));
+
+/** The real install: get.quox.ai -> scripts/setup.sh, health = the new instance's auth service on loopback. */
+export async function realInstall({ env = process.env } = {}) {
+  // The CLI's own service resolution (honours the per-service overrides); with no server configured
+  // yet it derives auth on loopback 127.0.0.1:3101, where the new instance's auth service listens.
+  const { loadConfig } = await import('../../core/config.js');
+  const authUrl = loadConfig().getServiceUrl('auth');
+  const saved = loadJourney();
+  return {
+    runner: createInstallRunner({ env, installDir: saved?.installDir || defaultInstallDir(), probeHealth: () => probeAuthHealth(authUrl) }),
+    finisher: await createFinisher()
+  };
+}
+
+/** -> { action: 'exit' } | { action: 'connected', replay? } | { action: 'connect-failed' } */
+export async function runGettingStarted({ version, cwd, welcome = false, earlyInput = null, demo = false, stdout = process.stdout } = {}) {
+  const broker = createCredentialBroker();
+  const requestCredential = createRequestCredential(broker);
+  let result = { action: 'exit' };
+  const real = demo ? { runner: createDryRunRunner(), finisher: null } : await realInstall();
+  const props = {
+    version, cwd, welcome, earlyInput, broker, requestCredential,
+    dryRun: demo,
+    runner: real.runner,
+    finisher: real.finisher, // owner account, vault, one-time link (C2c); none in the dry run
+    journeyPath: demo ? null : defaultJourneyPath(), // the demo never leaves state behind
+    onExit: (r) => { result = r || result; app.unmount(); }
+  };
+  const app = render(React.createElement(GettingStarted, props), { exitOnCtrlC: false, stdout: inkStdout(stdout) });
+  await app.waitUntilExit();
+  broker.cancel();
+  if (result.action === 'connect') return connectServer(result.url, { demo });
+  return result;
+}
+
+/** /connect server <url>: point the active profile at it and run the existing login. Restores the URL on failure. */
+export async function connectServer(url, { demo = false, spawn = spawnSync, out = (s) => process.stdout.write(s) } = {}) {
+  if (demo) { out(`${T.connectHandoff(url)}\n(demo: not connecting)\n`); return { action: 'exit' }; }
+  const { loadConfig } = await import('../../core/config.js');
+  const config = loadConfig();
+  const prev = config.getActiveProfile()?.url || null;
+  config.setProfileConnection({ url });
+  const r = spawn(process.execPath, [QUOX_BIN, 'login'], { stdio: 'inherit' });
+  if (r.status === 0) { clearJourney(); out(`${T.CONNECT_DONE}\n`); return { action: 'connected' }; }
+  if (prev) loadConfig().setProfileConnection({ url: prev });
+  out(`${T.connectFailed(url)}\n`);
+  return { action: 'connect-failed' };
+}

package/lib/quoxon/onboarding/installRunner.js

@@ -0,0 +1,225 @@
+/**
+ * C2b: the real install runner (the runner interface in ./runner.js).
+ *
+ * Wraps the existing installer, never a second one: get.quox.ai serves install.sh (quox-website
+ * public/install.sh), which clones quox, quoxflow and quoxmcp into $QUOX_DIR and runs
+ * scripts/setup.sh --yes (non-interactive). We download it to a private temp file, show its
+ * SHA256, run it with `sh`, and map its own step markers onto the five honest stages:
+ *
+ *   fetch      start .. "[setup] Step 2/7"     (install.sh clones; setup.sh step 1 preflight)
+ *   configure  Step 2/7 .. Step 6/7            (.env secrets, SSL cert, deps, stale cleanup)
+ *   build      Step 6/7 .. "Starting services" (docker compose build)
+ *   start      "Starting services" .. Step 7/7 (docker compose up -d)
+ *   health     Step 7/7 .. "full platform is ready" + our own probe of the auth service
+ *
+ * Re-running (setup.sh read, 2026-10-12): clone() pulls instead of re-cloning; an existing complete
+ * .env and ssl/quox.crt are kept (so the Postgres password still matches its volume); the image
+ * build is cached. Step 5 however REMOVES running quox-* containers (compose down, volumes kept)
+ * before rebuilding. So: interrupted before `start` completed -> run the whole installer again;
+ * `start` completed -> never re-run it, only check health.
+ *
+ * Never a fake percentage: elapsed time per stage, and the real log lines (`v` in the view).
+ */
+import { spawn as defaultSpawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { STAGE_IDS, stageList } from './runner.js';
+
+export const INSTALLER_URL = 'https://get.quox.ai';
+export const defaultInstallDir = (home = homedir()) => join(home, 'quox-install');
+
+const ANSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const RED = /^\x1b\[(0;)?31m/;
+const MARKS = [
+  [/^\[setup\] Step 2\/7\b/, 'configure'],
+  [/^\[setup\] Step 6\/7\b/, 'build'],
+  [/Starting services\.\.\./, 'start'],
+  [/^\[setup\] Step 7\/7\b/, 'health']
+];
+
+/**
+ * Line-by-line stage machine over the installer's output.
+ * push(rawLine) -> { line: cleaned text | null, moves: [[stageId, 'ok'|'running']] }
+ */
+export function createStageParser() {
+  const state = { current: 'fetch', ready: false, degraded: false, dashboardUrl: null, lastError: null };
+  return {
+    state,
+    push(raw, { stderr = false } = {}) {
+      const text = String(raw ?? '').replace(ANSI, '').replace(/\s+$/, '');
+      const moves = [];
+      if (!text.trim()) return { line: null, moves };
+      const line = text.replace(/^\s+/, (m) => (m.length > 2 ? '  ' : m));
+      for (const [re, next] of MARKS) {
+        if (!re.test(line.trim())) continue;
+        const from = STAGE_IDS.indexOf(state.current); const to = STAGE_IDS.indexOf(next);
+        if (to <= from) break;
+        for (let i = from; i < to; i++) { moves.push([STAGE_IDS[i], 'ok']); if (i + 1 < to) moves.push([STAGE_IDS[i + 1], 'running']); }
+        moves.push([next, 'running']);
+        state.current = next;
+        break;
+      }
+      if (/QuoxCORE full platform is ready/.test(line)) state.ready = true;
+      if (/core shell is up, but platform features are degraded/.test(line)) state.degraded = true;
+      const open = /^\s*Open:\s+(https?:\/\/\S+)/.exec(line);
+      if (open) state.dashboardUrl = open[1];
+      if (stderr || RED.test(String(raw))) state.lastError = line.trim();
+      return { line: line.trim(), moves };
+    }
+  };
+}
+
+/** GET <authUrl>/health once. -> { ok, error? } */
+export async function probeAuthHealth(authUrl, { fetchImpl = globalThis.fetch, timeout = 3000 } = {}) {
+  try {
+    const r = await fetchImpl(`${authUrl.replace(/\/+$/, '')}/health`, { signal: AbortSignal.timeout(timeout) });
+    return r.ok ? { ok: true } : { ok: false, error: `auth /health answered HTTP ${r.status}` };
+  } catch (e) { return { ok: false, error: e?.cause?.code ? `${e.message} (${e.cause.code})` : (e?.message || 'no answer') }; }
+}
+
+const sleep = (ms, signal) => new Promise((res) => {
+  const t = setTimeout(res, ms);
+  signal?.addEventListener?.('abort', () => { clearTimeout(t); res(); }, { once: true });
+});
+
+export function createInstallRunner({
+  env = process.env,
+  url = env.QUOX_INSTALLER_URL || INSTALLER_URL,
+  installDir = defaultInstallDir(),
+  fetchImpl = globalThis.fetch,
+  spawnImpl = defaultSpawn,
+  tmpRoot = tmpdir(),
+  probeHealth = async () => ({ ok: true }),
+  healthTries = 20,
+  healthIntervalMs = 3000,
+  resumeFrom = null,
+  resumeDashboardUrl = null,
+  onCheckpoint = () => {},
+  killGraceMs = 5000,
+  now = () => Date.now()
+} = {}) {
+  async function checkHealth(emit, signal) {
+    let last = null;
+    for (let i = 0; i < Math.max(1, healthTries); i++) {
+      if (signal?.aborted) return { ok: false, interrupted: true };
+      last = await probeHealth();
+      if (last?.ok) return { ok: true };
+      emit({ type: 'log', line: `waiting for the auth service: ${last?.error || 'not ready'}` });
+      if (i + 1 < healthTries) await sleep(healthIntervalMs, signal);
+    }
+    return { ok: false, error: last?.error || 'the auth service did not answer' };
+  }
+
+  return {
+    kind: 'real',
+    url,
+    installDir,
+    stages: stageList(),
+    /** Per-run overrides (the view passes the journey's checkpoint): resumeFrom, resumeDashboardUrl, onCheckpoint. */
+    async run({ onEvent = () => {}, signal, resumeFrom: rf = resumeFrom, resumeDashboardUrl: rd = resumeDashboardUrl, onCheckpoint: oc = onCheckpoint } = {}) {
+      const resumeAfterStart = rf === 'start' || rf === 'health';
+      const started = {};
+      const stage = (id, status) => {
+        const at = now();
+        if (status === 'running') started[id] = at;
+        onEvent({ type: 'stage', id, status, at, ...(status !== 'running' ? { ms: started[id] != null ? at - started[id] : null } : {}) });
+      };
+      const emit = (e) => onEvent(e);
+
+      if (resumeAfterStart) {
+        for (const id of ['fetch', 'configure', 'build', 'start']) onEvent({ type: 'stage', id, status: 'ok', at: now(), ms: null, earlier: true });
+        emit({ type: 'log', line: 'the services were already started; checking their health' });
+        stage('health', 'running');
+        const h = await checkHealth(emit, signal);
+        if (h.interrupted) return { ok: false, interrupted: true };
+        if (!h.ok) { stage('health', 'fail'); return { ok: false, failedStage: 'health', error: h.error, dashboardUrl: rd }; }
+        stage('health', 'ok');
+        oc('health', { dashboardUrl: rd });
+        return { ok: true, dashboardUrl: rd, resumed: true };
+      }
+
+      // ---- fetch: download the installer, show what will run -------------------------------------
+      stage('fetch', 'running');
+      let body;
+      try {
+        const r = await fetchImpl(url, { signal });
+        if (!r.ok) { stage('fetch', 'fail'); return { ok: false, failedStage: 'fetch', error: `${url} answered HTTP ${r.status}` }; }
+        body = await r.text();
+      } catch (e) {
+        if (signal?.aborted) return { ok: false, interrupted: true };
+        stage('fetch', 'fail');
+        return { ok: false, failedStage: 'fetch', error: `could not download ${url}: ${e?.message || e}` };
+      }
+      if (!/^#!\s*\/bin\/(ba)?sh\b/.test(body)) { stage('fetch', 'fail'); return { ok: false, failedStage: 'fetch', error: `${url} did not return a shell script, so nothing was run` }; }
+      const sha256 = createHash('sha256').update(body).digest('hex');
+      emit({ type: 'script', url, sha256, bytes: Buffer.byteLength(body) });
+      emit({ type: 'log', line: `installer ${url} sha256 ${sha256}` });
+
+      const dir = mkdtempSync(join(tmpRoot, 'quox-installer-'));
+      const file = join(dir, 'install.sh');
+      writeFileSync(file, body, { mode: 0o600 });
+
+      const parser = createStageParser();
+      try {
+        const code = await new Promise((resolve) => {
+          const child = spawnImpl('sh', [file], {
+            cwd: homedir(),
+            env: { ...env, QUOX_DIR: installDir },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: true // own process group: abort stops docker compose too
+          });
+          let killTimer = null;
+          const onAbort = () => {
+            try { process.kill(-child.pid, 'SIGTERM'); } catch { /* already gone */ }
+            killTimer = setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* gone */ } }, killGraceMs);
+          };
+          if (signal) { if (signal.aborted) onAbort(); else signal.addEventListener('abort', onAbort, { once: true }); }
+          const feed = (stderr) => {
+            let rest = '';
+            return (chunk) => {
+              const parts = (rest + chunk.toString('utf8')).split(/\r\n|\r|\n/);
+              rest = parts.pop();
+              for (const raw of parts) take(raw, stderr);
+            };
+          };
+          const take = (raw, stderr) => {
+            const { line, moves } = parser.push(raw, { stderr });
+            for (const [id, status] of moves) {
+              if (status === 'ok') { stage(id, 'ok'); if (id !== 'health') oc(id, {}); }
+              else stage(id, 'running');
+            }
+            if (line) emit({ type: 'log', line });
+          };
+          child.stdout.on('data', feed(false));
+          child.stderr.on('data', feed(true));
+          child.on('error', (e) => { parser.state.lastError = `could not run sh: ${e.message}`; resolve(127); });
+          child.on('close', (c, sig) => { clearTimeout(killTimer); signal?.removeEventListener?.('abort', onAbort); resolve(sig ? 128 : c); });
+        });
+
+        if (signal?.aborted) return { ok: false, interrupted: true };
+        const at = parser.state.current;
+        if (code !== 0) {
+          stage(at, 'fail');
+          return { ok: false, failedStage: at, error: parser.state.lastError || `the installer exited with code ${code}`, dashboardUrl: parser.state.dashboardUrl };
+        }
+        if (at !== 'health' || !parser.state.ready) {
+          if (at !== 'health') stage(at, 'fail'); else stage('health', 'fail');
+          return {
+            ok: false, failedStage: at === 'health' ? 'health' : at, degraded: parser.state.degraded, dashboardUrl: parser.state.dashboardUrl,
+            error: parser.state.degraded ? 'the core is up, but some services are not healthy yet' : 'the installer finished without saying the platform is ready'
+          };
+        }
+        const h = await checkHealth(emit, signal);
+        if (h.interrupted) return { ok: false, interrupted: true };
+        if (!h.ok) { stage('health', 'fail'); return { ok: false, failedStage: 'health', error: h.error, dashboardUrl: parser.state.dashboardUrl }; }
+        stage('health', 'ok');
+        oc('health', { dashboardUrl: parser.state.dashboardUrl });
+        return { ok: true, dashboardUrl: parser.state.dashboardUrl, sha256 };
+      } finally {
+        try { rmSync(dir, { recursive: true, force: true }); } catch { /* temp cleanup only */ }
+      }
+    }
+  };
+}

package/lib/quoxon/onboarding/intent.js

@@ -0,0 +1,53 @@
+/**
+ * Local intent matcher for Getting started. No model, no network: a keyword table, so the answer is instant
+ * and predictable. Anything it does not recognise is "offscript" and gets an honest deferral.
+ */
+
+export const INTENTS = ['servers', 'automate', 'code', 'email', 'explore'];
+
+// Order matters: the first rule whose pattern matches wins ("connect" first, so "I already have a server"
+// is never read as "watch my servers").
+const RULES = [
+  ['connect', /\b(already (have|got|run)|have (a|my|an?) (own )?(server|quox|instance)|existing (server|quox|instance)|my (own )?quox(core)?|connect (to )?(a |my )?(server|quox))\b/i],
+  ['servers', /\b(servers?|hosts?|fleet|monitor(ing)?|watch(ing)?|uptime|infra(structure)?|machines?|homelab|proxmox|vms?|nodes?|cluster|disk space|logs?)\b/i],
+  ['email', /\b(e-?mails?|mail|inbox|gmail|outlook|newsletters?|replies)\b/i],
+  ['code', /\b(code|coding|coder|repos?|repository|github|gitlab|pull requests?|prs?|bugs?|refactor|programm(ing|er)|develop(er|ment)?|tests?)\b/i],
+  ['automate', /\b(automat(e|ion|ing)|workflows?|schedul(e|ed|ing)|cron|routines?|repetitive|every (day|morning|week|hour)|n8n|zapier|tasks?|jobs?)\b/i],
+  ['explore', /\b(look(ing)? around|explore|just looking|curious|show me|demo|tour|not sure|no idea|anything|surprise me|what can (you|it|quox) do|browse)\b/i]
+];
+
+/** -> { intent: one of INTENTS | 'connect' | 'offscript' | 'empty', text } */
+export function matchIntent(input) {
+  const text = String(input ?? '').trim();
+  if (!text) return { intent: 'empty', text };
+  const n = /^[1-5]$/.exec(text);
+  if (n) return { intent: INTENTS[Number(n[0]) - 1], text };
+  for (const [intent, re] of RULES) if (re.test(text)) return { intent, text };
+  return { intent: 'offscript', text };
+}
+
+/** Y/n answer: Enter alone means yes. -> true | false | null (not an answer) */
+export function yesNo(input) {
+  const t = String(input ?? '').trim().toLowerCase();
+  if (t === '' || /^(y|yes|yeah|yep|sure|ok|okay|go|do it|set it up|please)\b/.test(t)) return true;
+  if (/^(n|no|nope|not now|later|skip|cancel)\b/.test(t)) return false;
+  return null;
+}
+
+/** `/connect server <url>` -> { ok, url } | { ok: false, reason: 'usage' | 'url', value } | null (not /connect) */
+export function parseConnect(input) {
+  const t = String(input ?? '').trim();
+  if (!/^\/connect\b/i.test(t)) return null;
+  const m = /^\/connect\s+server(?:\s+(\S+))?\s*$/i.exec(t);
+  if (!m) return { ok: false, reason: 'usage' };
+  if (!m[1]) return { ok: false, reason: 'usage' };
+  let raw = m[1];
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) raw = `https://${raw}`;
+  try {
+    const u = new URL(raw);
+    if (!['http:', 'https:'].includes(u.protocol) || !u.hostname) return { ok: false, reason: 'url', value: m[1] };
+    return { ok: true, url: u.origin + (u.pathname === '/' ? '' : u.pathname.replace(/\/+$/, '')) };
+  } catch {
+    return { ok: false, reason: 'url', value: m[1] };
+  }
+}

package/lib/quoxon/onboarding/journey.js

@@ -0,0 +1,73 @@
+/**
+ * Journey state for Getting started: ~/.config/quox/onboarding.json, so an interrupted journey resumes.
+ * ALLOWLIST ONLY: the file holds exactly the fields named here (never a key, token or password), whatever the
+ * caller passes in.
+ */
+import { readFileSync, writeFileSync, mkdirSync, rmSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+export const JOURNEY_VERSION = 1;
+export const STEPS = ['ask', 'offer', 'declined', 'preflight', 'credential', 'install', 'owner', 'finishing', 'finale'];
+// installStage = the last install stage that COMPLETED (installRunner.js decides what re-running means).
+const FIELDS = ['step', 'intent', 'request', 'provider', 'installStage', 'installDir', 'dashboardUrl', 'ownerEmail', 'ollamaUrl', 'startedAt', 'updatedAt'];
+const INSTALL_STAGES = ['fetch', 'configure', 'build', 'start', 'health'];
+const MAX = { request: 500, installDir: 300, dashboardUrl: 300, ownerEmail: 254, ollamaUrl: 200 };
+
+export const journeyPath = () => join(homedir(), '.config', 'quox', 'onboarding.json');
+
+export function sanitize(state) {
+  const out = { version: JOURNEY_VERSION };
+  for (const k of FIELDS) {
+    const v = state?.[k];
+    if (v === undefined || v === null) continue;
+    if (typeof v !== 'string') continue;
+    out[k] = v.slice(0, MAX[k] || 64);
+  }
+  if (out.installStage && !INSTALL_STAGES.includes(out.installStage)) delete out.installStage;
+  if (out.dashboardUrl && !/^https?:\/\/[^\s]+$/.test(out.dashboardUrl)) delete out.dashboardUrl;
+  if (out.installDir && !out.installDir.startsWith('/')) delete out.installDir;
+  if (out.step && !STEPS.includes(out.step)) delete out.step;
+  if (out.provider && !['chatgpt', 'openai', 'anthropic', 'ollama', 'skip'].includes(out.provider)) delete out.provider;
+  if (out.ollamaUrl !== undefined && (typeof out.ollamaUrl !== 'string' || !/^https?:\/\//.test(out.ollamaUrl))) delete out.ollamaUrl; // B3: a URL, never a secret
+  return out;
+}
+
+export function loadJourney(path = journeyPath()) {
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (!raw || raw.version !== JOURNEY_VERSION) return null;
+    const s = sanitize(raw);
+    return s.step ? s : null;
+  } catch { return null; }
+}
+
+export function saveJourney(state, path = journeyPath(), now = () => new Date().toISOString()) {
+  if (!path) return false;
+  try {
+    const prev = loadJourney(path);
+    const t = now();
+    const next = sanitize({ ...state, startedAt: prev?.startedAt || state.startedAt || t, updatedAt: t });
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+    return true;
+  } catch { return false; }
+}
+
+export function clearJourney(path = journeyPath()) {
+  if (!path) return;
+  try { rmSync(path, { force: true }); } catch { /* nothing to clear */ }
+}
+
+/**
+ * Where a resumed journey starts. The AI key only ever lived in memory, so anything past the credential
+ * step goes back through preflight (cheap, and the machine may have changed) and asks for the key again.
+ */
+export function resumeStep(saved) {
+  if (!saved?.step) return null;
+  if (saved.step === 'ask' || saved.step === 'finale') return null;
+  if (saved.step === 'offer' || saved.step === 'declined') return 'offer';
+  return 'preflight';
+}