codebase-onboarder 0.3.1 → 0.4.0

package/README.md

@@ -212,7 +212,13 @@ onboarder config show                    # current settings (key masked)
 onboarder config set host 0.0.0.0        # direct VPS/LAN access (domain optional)
 onboarder config set port 4311           # move away from a busy port
 onboarder config key rotate              # mint a new access key
-onboarder status                         # running PID, stopped, or unmanaged port owner
+onboarder start                          # foreground; Ctrl-C stops it
+onboarder start background               # detached; keeps running after you close the terminal
+onboarder logs                           # last 40 log lines  (-n <count>, -f to follow)
+onboarder start startup install          # also start automatically at every login
+onboarder start startup status           # is a login item installed, and is it live?
+onboarder start startup remove           # take the login item back out
+onboarder status                         # running PID, mode, uptime, stopped, or unmanaged port owner
 onboarder stop                           # stop a PID-file-managed instance
 onboarder restart                        # graceful stop, then start
 onboarder tunnel cloudflare              # expose via a Cloudflare quick tunnel
@@ -223,6 +229,38 @@ onboarder https status                   # domain, URL, Caddyfile, and Caddy sta
 onboarder doctor                         # config, access key, ports, DNS, TLS, and tunnels
 ```
 
+### Running it in the background
+
+`onboarder start` runs in the foreground on purpose: it is a normal command, and Ctrl-C stops it. When you want the server to outlive the terminal, use `start background`. It re-launches the same CLI as a detached process with its output going to `onboarder.log` beside your config, then **waits for the server to actually answer** `/api/health` before reporting success. A port conflict comes back as a failure with the log tail attached, not as a cheerful green light that dies a second later.
+
+```bash
+onboarder start background   # returns once it is serving
+onboarder logs -f            # watch it, Ctrl-C to stop watching (not the server)
+onboarder stop               # stop it
+```
+
+Log lines are column-aligned — a fixed-width local timestamp, a fixed-width level, then the message — so a wall of requests stays scannable:
+
+```
+16:09:38.985  INFO   GET /api/health 200 (1ms)
+16:09:46.460  INFO   GET /nope 404 (1ms)
+16:10:21.925  WARN   config port=4310 reason="already in use"
+```
+
+Set `ONBOARDER_LOG=json` for one JSON object per line instead (the log file is plain text by default so it stays readable; `--json` on `status`/`logs` is the machine-readable surface).
+
+### Starting at login
+
+`onboarder start startup install` registers Onboarder with whatever your OS uses for login items, and never asks for `sudo`:
+
+| Platform | What it writes | How it loads |
+|---|---|---|
+| macOS | `~/Library/LaunchAgents/com.onboarder.server.plist` | `launchctl bootstrap gui/$UID` |
+| Linux | `~/.config/systemd/user/onboarder.service` | `systemctl --user enable --now` |
+| Windows | `%APPDATA%\...\Startup\Onboarder.cmd` | the file *is* the registration |
+
+All three run the same `onboarder start --config <your config>`, so a login-started server is indistinguishable from a hand-started one — same config, same pid file, same `onboarder stop`. The generated unit uses `Restart=on-failure` (and launchd's `KeepAlive`/`SuccessfulExit=false`), so a crash is restarted but a deliberate `onboarder stop` stays stopped. `onboarder start startup remove` unloads and deletes it; a running server is left alone. On a platform with no known mechanism, the command says so instead of pretending.
+
 A fresh self-hosted setup uses `0.0.0.0`, so a VPS is reachable at `http://<server-ip>:<port>` without a reverse proxy. The server accepts IPv4 and IPv6 IP literals, including a public address that reaches the host through provider NAT, but still rejects arbitrary DNS Host headers. A domain is optional for direct-IP access. If a domain is entered, setup asks whether to enable automatic HTTPS.
 
 When a remote browser opens the URL, Onboarder shows its themed sign-in page. The access key is sent in a POST body—not in the URL—and the browser stores only the signed session cookie. Opening the same server through `http://localhost:<port>` on that machine skips the page. Caddy and tunnel connections remain authenticated because their public Host is not loopback.
@@ -255,7 +293,10 @@ codebase-onboarder/
 ├── server/          # Zero-dependency Node.js HTTP server
 │   ├── index.js     # createServer / startServer / startup banner
 │   ├── config.js    # Settings schema, normalization, atomic 0600 writes
-│   ├── pidfile.js   # PID ownership for status / stop / restart
+│   ├── pidfile.js   # PID + run record (mode, url, log) for status / stop / restart
+│   ├── daemon.js    # Detached background start, log file, readiness probe
+│   ├── startup.js   # Login items: launchd plist / systemd --user unit / Startup folder
+│   ├── logger.js    # Aligned-text or JSON log lines from one entry shape
 │   ├── router.js    # Route table, live per-request settings, auth & CSRF gates
 │   ├── auth.js      # Signed HttpOnly browser sessions
 │   ├── apiAuth.js   # Login/status/logout endpoints

package/cli/commands.js

@@ -12,13 +12,15 @@ import { spawn } from 'node:child_process';
 
 import {
   DEFAULT_SETTINGS, configPath, configExists, readSettings, writeSettings,
-  publicSettings, serverUrls, maskAccessKey,
+  publicSettings, serverUrls, maskAccessKey, isLoopbackHost,
 } from '../server/config.js';
 import { startServer } from '../server/index.js';
-import { pidIsAlive, readPidFile, removePidFile } from '../server/pidfile.js';
+import { pidIsAlive, readPidFile, removePidFile, readRunInfo, runInfoPath } from '../server/pidfile.js';
+import { logPath, rotateLogIfNeeded, tailLog, followLog, logExists, spawnDetached, waitForPidFile, waitForReady } from '../server/daemon.js';
+import { installStartup, removeStartup, startupStatus, startupTarget } from '../server/startup.js';
 import { tunnelStatus, cloudflareCommand, tailscaleCommand, installHint, findOnPath } from '../server/tunnel.js';
 import { caddyRun, caddyValidate, httpsReadiness, httpsStatus, writeCaddyfile } from '../server/https.js';
-import { bold, cyan, dim, ok, warn, bad, kv, tick, cross, dash, welcomeBanner } from './ui.js';
+import { bold, cyan, dim, ok, warn, bad, paint, kv, tick, cross, dash, welcomeBanner, panel, row, hint } from './ui.js';
 import { buildSteps, unansweredSteps, defaultOf, applyFlags, answersToSettings, summaryLines } from './wizard.js';
 import { runSteps, WizardCancelled } from './prompt.js';
 
@@ -41,6 +43,9 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
       printSummary(out, settings, { revealKey: Boolean(patchHasNewKey(flags)) });
     }
     await printTunnelFollowup(out, settings);
+    // `start` may be the flag `--start` (true) or the mode a subcommand asked
+    // for ('background') — both mean "boot it now", differently.
+    if (flags.start === 'background') return runStartBackground({ flags, out, err });
     if (flags.start) return runStart({ flags, out, err });
     return 0;
   }
@@ -95,9 +100,9 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
   }
   await printTunnelFollowup(out, settings);
 
-  if (flags.start || await confirm(out, 'Start Onboarder now?', true)) {
+  if (flags.start === 'background' || (!flags.start && await confirm(out, 'Start Onboarder now?', true))) {
     out('');
-    return runStart({ flags, out, err });
+    return flags.start === 'background' ? runStartBackground({ flags, out, err }) : runStart({ flags, out, err });
   }
   out(dim(settings.https
     ? '  Later: `onboarder start` (starts Caddy automatically), or `onboarder https status`'
@@ -145,6 +150,38 @@ async function printTunnelFollowup(out, settings) {
 
 // ---------------------------------------------------------------- start ---
 
+// What the person is about to be looking at, as a titled panel instead of a
+// loose run of lines. One function serves the foreground banner and the
+// background confirmation, so "what does `onboarder start` tell me" has exactly
+// one answer no matter which mode you used.
+export function serverDetails(started, { configFile, pid = null, mode = 'foreground', logFile = '' } = {}) {
+  const { settings, host, port } = started;
+  const urls = serverUrls(settings);
+  const rows = [
+    row('URL', bold(cyan(urls.local))),
+    row('Bind', `${host}:${port}`),
+    row('Mode', settings.mode === 'self-hosted'
+      ? (isLoopbackHost(host) ? 'self-hosted (loopback — use a tunnel for remote access)' : 'self-hosted (network reachable, access key required)')
+      : 'local (this machine only)'),
+  ];
+  if (urls.network) rows.push(row('Network', urls.network));
+  if (urls.domain) rows.push(row('Public', urls.domain));
+  if (settings.mode === 'self-hosted') {
+    rows.push(row('Access key', settings.accessKey ? maskAccessKey(settings.accessKey) : bad('NOT SET — every API call is refused')));
+  }
+  rows.push(row('PID', String(pid ?? process.pid)));
+  rows.push(row('Config', dim(configFile || '')));
+  if (logFile) rows.push(row('Logs', dim(logFile)));
+  return { rows, urls, mode };
+}
+
+function printServerDetails(out, started, options) {
+  const { rows } = serverDetails(started, options);
+  out('');
+  out(panel('Onboarder is running', rows));
+  out('');
+}
+
 export async function runStart({ flags = {}, out = console.log, err = console.error } = {}) {
   const file = flags.config || configPath();
   if (!await configExists(file)) {
@@ -165,7 +202,9 @@ export async function runStart({ flags = {}, out = console.log, err = console.er
   }
   if (recorded) removePidFile(file, recorded);
 
-  const started = await startServer({ configFile: file, log: out });
+  // `quiet`: the CLI prints its own details panel below, so the loose banner
+  // would be the same facts twice. `node server/index.js` still gets the banner.
+  const started = await startServer({ configFile: file, log: () => {}, openBrowser: false });
   if (started.settings.https) {
     out('');
     const httpsCode = await runHttps('setup', { flags, out: flags.json ? () => {} : out, err });
@@ -175,13 +214,116 @@ export async function runStart({ flags = {}, out = console.log, err = console.er
     }
   }
   if (flags.json) out(JSON.stringify({ host: started.host, port: started.port, url: serverUrls(started.settings).local }));
+  // `start` foreground prints the details itself rather than letting
+  // `startServer` print the old loose banner — the panel replaces it. The
+  // background child lands here too (that is the point of reusing this path),
+  // and ONBOARDER_BACKGROUND is what tells the two apart: one is attached to a
+  // terminal you are about to close, the other is already detached from it.
+  printServerDetails(out, started, { configFile: file, mode: 'foreground' });
+  if (process.env.ONBOARDER_LAUNCH) {
+    // Started by launchd/systemd/the Startup folder: these lines are going into
+    // a log file nobody is watching, so they say what the supervisor is doing
+    // rather than telling a person to press Ctrl-C.
+    out(dim(`  Launched at login by ${process.env.ONBOARDER_LAUNCH}. This process is supervised — stop it with \`onboarder stop\`.`));
+  } else if (process.env.ONBOARDER_BACKGROUND) {
+    out(dim('  Started in the background — this process is now independent of any terminal.'));
+  } else {
+    out(dim('  Running in the foreground. Ctrl-C stops it; closing this terminal stops it too.'));
+    out(dim('  To keep it alive after you close the terminal: ') + cyan('onboarder start background'));
+  }
+  out('');
   // The listening server holds the event loop; resolve so callers/tests know
   // we are up, but leave the process running.
   return { ...started, code: 0 };
 }
 
+// `onboarder start background` — same server, no terminal attached. The child is
+// an ordinary foreground `start`; all this does is detach it and then *wait for
+// it to answer* before reporting success, so a bind failure surfaces here as a
+// failure with the log tail attached rather than a cheerful lie.
+export async function runStartBackground({ flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  if (!await configExists(file) && process.stdout.isTTY && !flags.nonInteractive) {
+    out(dim('  No settings yet — running setup first.'));
+    return runSetup({ flags: { ...flags, start: 'background' }, out, err });
+  }
+  const recorded = readPidFile(file);
+  if (recorded && pidIsAlive(recorded)) {
+    err(`  Onboarder is already running (PID ${recorded}).`);
+    err(dim('    Use `onboarder status`, `onboarder stop`, or `onboarder restart`.'));
+    return 1;
+  }
+  if (recorded) removePidFile(file, recorded);
+
+  const settings = await readSettings(file);
+  const log = logPath(file);
+  await rotateLogIfNeeded(log);
+
+  spawnDetached({ configFile: file, log });
+  const pid = await waitForPidFile(file, { timeoutMs: flags.timeout ? Number(flags.timeout) * 1000 : 20000 });
+  const urls = serverUrls(settings);
+  const ready = pid ? await waitForReady(new URL('/api/health', urls.local).toString(), { timeoutMs: 8000 }) : false;
+
+  if (!ready) {
+    // Two different failures with two different fixes, so they are reported
+    // differently. No pid record means the child never finished binding — the
+    // log holds the reason (a busy port, an invalid config). A live pid that will
+    // not answer means it bound and then something in front of it is in the way
+    // (a proxy, a firewall), and no amount of log-reading will show that.
+    if (!pid) {
+      err(bad('  Onboarder did not start in the background.'));
+      const tail = await tailLog(log, 15);
+      if (tail.length) {
+        err(dim(`  Last lines of ${log}:`));
+        for (const line of tail) err('    ' + line);
+      }
+      err(dim('    Fix the cause above, then run `onboarder start background` again.'));
+    } else {
+      err(bad(`  Onboarder is running (PID ${pid}) but ${urls.local} is not answering.`));
+      err(dim(`    Its log is ${log}. If a proxy or firewall fronts this port, check that first.`));
+      err(dim('    Otherwise: `onboarder stop`, then `onboarder start background` again.'));
+    }
+    return 1;
+  }
+
+  if (flags.json) {
+    out(JSON.stringify({ background: true, pid, url: urls.local, log, configFile: file }, null, 2));
+    return 0;
+  }
+
+  out('');
+  out(panel('Onboarder is running in the background', [
+    row('URL', bold(cyan(urls.local))),
+    row('PID', String(pid)),
+    row('Mode', 'background — survives closing this terminal'),
+    row('Logs', dim(log)),
+    row('Config', dim(file)),
+  ]));
+  out('');
+  out(dim('  Follow the log: ') + cyan('onboarder logs -f'));
+  out(dim('  Stop it:         ') + cyan('onboarder stop'));
+  out(dim('  Check on it:     ') + cyan('onboarder status'));
+  out('');
+  return 0;
+}
+
+
 // ------------------------------------------------------------- lifecycle ---
 
+// Panel rows carry their own inline marker rather than the `tick`/`cross`/`dash`
+// constants: those bake in a two-column indent for standalone lines, which would
+// push the first row out of the panel's label column.
+const MARK = { yes: (s) => paint('✓ ', 'green') + s, no: (s) => paint('– ', 'gray') + s, warn: (s) => paint('! ', 'yellow') + s };
+
+// How a live instance presents itself, in one sentence per mode. The point of
+// the sentence is the thing someone actually needs to know: can I close my
+// terminal, or will that kill it?
+const MODE_NOTES = {
+  background: 'background — survives closing the terminal',
+  startup: 'started at login — the OS restarts it if it stops',
+  foreground: 'foreground — stops when you press Ctrl-C or close the terminal',
+};
+
 export async function runStatus({ flags = {}, out = console.log } = {}) {
   const file = flags.config || configPath();
   const pid = readPidFile(file);
@@ -190,6 +332,9 @@ export async function runStatus({ flags = {}, out = console.log } = {}) {
   try { settings = await readSettings(file); } catch { /* defaults are still meaningful */ }
   const portBusy = settings ? !(await portIsFree(settings.host, settings.port)) : false;
   if (pid && !running) removePidFile(file, pid);
+  // The pid says whether it is up; the run record says *how* it came up, which
+  // is what tells someone whether closing their terminal will kill it.
+  const info = running ? readRunInfo(file) : null;
   const result = {
     running: Boolean(running || portBusy),
     pid: running ? pid : null,
@@ -197,21 +342,53 @@ export async function runStatus({ flags = {}, out = console.log } = {}) {
     portBusy,
     managed: Boolean(running),
     configFile: file,
+    mode: running ? (info?.mode || 'foreground') : null,
+    url: running ? (info?.url || (settings ? serverUrls(settings).local : null)) : null,
+    uptimeMs: running && info?.startedAt ? Date.now() - Date.parse(info.startedAt) : null,
+    log: running && info?.log ? info.log : null,
+    startup: (await startupStatus()).installed,
   };
   if (flags.json) {
     out(JSON.stringify(result, null, 2));
   } else {
     out('');
-    out(bold('  Onboarder status'));
-    if (running) out(`${tick}Running    PID ${pid}`);
-    else if (portBusy) out(`${warn('!')}Port busy  ${result.port} (no Onboarder PID record)`);
-    else out(`${dash}Stopped`);
-    out(kv('Config', file));
-    if (result.portBusy && !running) out(dim('    Inspect it with `ss -ltnp` or `lsof -i :' + settings.port + '` before stopping another process.'));
+    out(panel('Onboarder status', [
+      row('State', running
+        ? MARK.yes(`Running (PID ${pid})`)
+        : portBusy
+          ? MARK.warn(`Port busy — ${result.port}, but no Onboarder process record`)
+          : MARK.no('Stopped')),
+      ...(running ? [
+        row('URL', cyan(result.url || '')),
+        row('Mode', MODE_NOTES[result.mode] || MODE_NOTES.foreground),
+        ...(result.uptimeMs ? [row('Uptime', humanDuration(result.uptimeMs))] : []),
+        ...(result.log ? [row('Logs', dim(result.log))] : []),
+      ] : []),
+      row('Config', dim(file)),
+      row('At login', result.startup ? MARK.yes('Enabled') : MARK.no('Not enabled — `onboarder start startup install`')),
+      ...(result.portBusy && !running
+        ? [hint('Inspect the listener with `ss -ltnp` or `lsof -i :' + settings.port + '` before stopping another process.')]
+        : []),
+    ]));
+    out('');
   }
   return 0;
 }
 
+// "3d 4h", "12m 5s" — coarse on purpose. Precision past the second is noise on
+// something a person glances at.
+export function humanDuration(ms) {
+  const total = Math.max(0, Math.floor(ms / 1000));
+  const days = Math.floor(total / 86400);
+  const hours = Math.floor((total % 86400) / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const seconds = total % 60;
+  if (days) return `${days}d ${hours}h`;
+  if (hours) return `${hours}h ${minutes}m`;
+  if (minutes) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}
+
 function waitForExit(pid, timeoutMs = 5000) {
   return new Promise((resolve) => {
     const started = Date.now();
@@ -274,6 +451,109 @@ export async function runRestart(options = {}) {
   return runStart(options);
 }
 
+// ----------------------------------------------------------------- logs ---
+
+// `onboarder logs` — the answer to "it is running in the background, what is it
+// doing?". Prints the tail of the same file the background child writes, and
+// `-f` follows it. Line-oriented and level-colored, so a wall of request logs
+// stays scannable instead of being one undifferentiated block.
+export async function runLogs({ flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  const log = logPath(file);
+  const lines = flags.lines === undefined ? 40 : Math.max(1, Number(flags.lines) || 40);
+  if (!await logExists(log)) {
+    if (flags.json) out(JSON.stringify({ log, exists: false, lines: [] }, null, 2));
+    else {
+      err(`  No log file yet at ${log}.`);
+      err(dim('    A foreground `onboarder start` prints to the terminal; only `onboarder start background` writes this file.'));
+    }
+    return flags.json ? 0 : 1;
+  }
+  if (!flags.follow) {
+    const tail = await tailLog(log, lines);
+    if (flags.json) { out(JSON.stringify({ log, exists: true, lines: tail }, null, 2)); return 0; }
+    out('');
+    out(bold(`  ${log}`) + dim(`  (last ${tail.length} of ${lines})`));
+    out('');
+    for (const line of tail) out('  ' + line);
+    out('');
+    return 0;
+  }
+  if (flags.json) { err('  --follow and --json do not combine; pick one.'); return 2; }
+  out('');
+  out(bold(`  Following ${log}`) + dim('  (Ctrl-C to stop)'));
+  out('');
+  const stop = followLog(log, (line) => out('  ' + line), { from: 'start' });
+  const finish = () => { stop(); process.exit(0); };
+  process.once('SIGINT', finish);
+  await new Promise((resolve) => process.once('exit', resolve));
+  return 0;
+}
+
+// -------------------------------------------------------------- startup ---
+
+// `onboarder start startup` — run at login, not just right now. Three verbs
+// because the three actions are genuinely different: `install` writes the
+// artifact and hands it to the OS, `remove` takes it back out, `status` only
+// looks. `install` also starts it once so the person is not left waiting for the
+// next reboot to find out whether it worked.
+export async function runStartup(action = 'status', { flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  const target = startupTarget();
+  const log = logPath(file);
+
+  if (action === 'install' || action === 'enable' || action === 'on') {
+    const result = await installStartup({ configFile: file, log, target });
+    if (!result.ok) {
+      err(bad('  Could not install the startup entry.'));
+      err('    ' + (result.reason || result.output || result.error || 'unknown error'));
+      return 1;
+    }
+    out(tick + `Onboarder will start at login (${target.hint}).`);
+    out(kv('Startup file', result.path));
+    if (result.output) out(dim('    ' + result.output.split('\n').slice(-2).join('\n    ')));
+    out('');
+    out(dim('  Start it right now too: ') + cyan('onboarder start background'));
+    out(dim('  Turn it off again:      ') + cyan('onboarder start startup remove'));
+    out('');
+    return 0;
+  }
+
+  if (action === 'remove' || action === 'disable' || action === 'off' || action === 'uninstall') {
+    const status = await startupStatus(target);
+    if (!status.installed) {
+      out(dash + 'No startup entry is installed — nothing to remove.');
+      return 0;
+    }
+    const result = await removeStartup({ target });
+    if (!result.ok) { err(bad('  Could not remove the startup entry: ' + (result.reason || 'unknown error'))); return 1; }
+    out(tick + 'Startup entry removed. A running server is untouched — use `onboarder stop` for that.');
+    out(kv('Removed', result.path));
+    out('');
+    return 0;
+  }
+
+  if (action === 'status' || action === undefined) {
+    const status = await startupStatus(target);
+    if (flags.json) { out(JSON.stringify(status, null, 2)); return status.installed ? 0 : 1; }
+    out('');
+    out(panel('Onboarder at login', [
+      row('State', status.installed
+        ? (status.active ? MARK.yes('Enabled and running') : MARK.warn('Enabled, not running'))
+        : MARK.no('Not enabled')),
+      row('How', status.detail),
+      ...(status.path ? [row('File', dim(status.path))] : []),
+      ...(status.supported ? [hint(status.installed
+        ? 'Remove it with `onboarder start startup remove`.'
+        : 'Enable it with `onboarder start startup install`.')] : []),
+    ]));
+    out('');
+    return status.installed ? 0 : 1;
+  }
+
+  throw new Error('Usage: onboarder start startup [install|remove|status]');
+}
+
 // --------------------------------------------------------------- config ---
 
 // Keys `config set` may touch — the same allow-list the HTTP API enforces, so

package/cli/main.js

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import { parseArgs } from 'node:util';
 
 import {
-  runSetup, runStart, runStatus, runStop, runRestart,
+  runSetup, runStart, runStartBackground, runStartup, runLogs, runStatus, runStop, runRestart,
   runConfig, runConfigKey, runConfigReset, runDoctor, runTunnel, runHttps,
 } from './commands.js';
 
@@ -20,7 +20,10 @@ const HELP = `
   Usage
     onboarder                     Start the server (runs setup first if needed)
     onboarder setup | onboard     Configure interactively (the wizard)
-    onboarder start               Start the server
+    onboarder start               Start in the foreground (Ctrl-C stops it)
+    onboarder start background    Start detached — keeps running after you close the terminal
+    onboarder start startup       Run automatically at login [install|remove|status]
+    onboarder logs                Show recent log lines  (-n <count>, -f to follow)
     onboarder status              Show whether the server is running
     onboarder stop                Stop the running server
     onboarder restart             Stop and start again
@@ -48,11 +51,16 @@ const HELP = `
   Also accepted
     help | --help       onboarder help | onboarder --help
     config | config show
+    bg | detached       alias for start background
+    fg | foreground     alias for start
 
   Examples
     onboarder setup
+    onboarder start background          # leave it running, close the terminal
+    onboarder logs -f                   # watch what it is doing
+    onboarder start startup install     # also start it every time you log in
+    onboarder start background && open http://localhost:4310
     onboarder setup --non-interactive --mode local --port 4310
-    onboarder setup --non-interactive --mode self-hosted --host 0.0.0.0
     onboarder setup --non-interactive --mode self-hosted --domain map.example.com --https --start
     onboarder config set tunnel.cloudflare true && onboarder tunnel cloudflare
 `;
@@ -82,6 +90,9 @@ const OPTIONS = {
   cloudflare: { type: 'boolean' },
   tailscale: { type: 'boolean' },
   'auto-open': { type: 'boolean' },
+  lines: { type: 'string', short: 'n' },
+  follow: { type: 'boolean', short: 'f' },
+  timeout: { type: 'string' },
 };
 
 // parseArgs speaks kebab-case; the wizard's flags speak camelCase.
@@ -115,8 +126,33 @@ export async function main(argv = process.argv.slice(2)) {
         console.log(HELP);
         return 0;
       case undefined:
+        return codeOf(await runStart({ flags }));
       case 'start':
+        // `onboarder start [background|fg|startup [action]]`. The sub-verb is a
+        // positional, not a flag, because `onboarder start` has to keep working
+        // exactly as it did and `startup install` is a different verb from
+        // `start`.
+        if (sub === 'background' || sub === 'bg' || sub === 'daemon' || sub === 'detached') {
+          return codeOf(await runStartBackground({ flags }));
+        }
+        if (sub === 'startup' || sub === 'login' || sub === 'autostart') {
+          return codeOf(await runStartup(rest[0] || 'status', { flags }));
+        }
+        if (sub === 'fg' || sub === 'foreground') return codeOf(await runStart({ flags }));
+        if (sub === 'status') return codeOf(await runStatus({ flags }));
+        if (sub === 'stop') return codeOf(await runStop({ flags }));
+        if (sub === 'logs') return codeOf(await runLogs({ flags }));
+        if (sub) {
+          console.error('  Unknown start mode: ' + sub + '\n' + HELP);
+          return 2;
+        }
         return codeOf(await runStart({ flags }));
+      case 'logs':
+      case 'log':
+        return codeOf(await runLogs({ flags }));
+      case 'startup':
+      case 'autostart':
+        return codeOf(await runStartup(sub || 'status', { flags }));
       case 'status':
         return codeOf(await runStatus({ flags }));
       case 'stop':

package/cli/ui.js

@@ -53,3 +53,37 @@ export function kv(label, value) {
 export const tick = ok('  ✓ ');
 export const cross = bad('  ✗ ');
 export const dash = dim('  – ');
+
+// Visible width, ANSI codes excluded. Padding has to be computed on what the
+// terminal *shows*, not on the bytes we wrote, or every colored row grows a
+// few columns and the column stops being a column.
+export function width(text) {
+  return String(text).replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+// A titled block of rows. The box is drawn from the widest row rather than a
+// fixed 80 columns, so it stays aligned in a narrow terminal and does not stretch
+// across a wide one.
+export function panel(title, rows, { indent = '  ' } = {}) {
+  const labelWidth = Math.max(...rows.map((r) => width(r.label ?? '')), 0);
+  // Every row starts two columns in; the label column is then as wide as the
+  // longest label, so all the values line up regardless of label length.
+  const body = rows.map((r) => r.hint
+    ? '  ' + ' '.repeat(labelWidth + 4) + dim(r.hint)
+    : '  ' + paint((r.label ?? '').padEnd(labelWidth), 'gray') + '  ' + (r.value ?? ''));
+  // The frame is sized from its contents: a long path widens the box instead of
+  // spilling out of it, and a short one does not stretch to 80 columns.
+  const inner = Math.max(title.length + 4, ...body.map(width), 24);
+  const top = '┌─ ' + bold(title) + ' ' + '─'.repeat(Math.max(1, inner - title.length - 3)) + '┐';
+  const bottom = '└' + '─'.repeat(inner) + '┘';
+  return [top, ...body, bottom].map((line) => indent + (line === top || line === bottom ? paint(line, 'gray') : line)).join('\n');
+}
+
+// A one-line hint under a row, wrapped in the panel's dim voice.
+export const hint = (text) => ({ hint: text });
+
+// Multi-line values (a command, a path list) still align on the first line.
+export function row(label, value) {
+  return { label, value: String(value) };
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-onboarder",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Drop a path. Get a map. A zero-dependency codebase visualizer with a CLI onboarding wizard, a web UI, and an optional key-gated self-hosted mode.",
   "type": "module",
   "bin": {

package/server/daemon.js

@@ -0,0 +1,195 @@
+// Running the server without the terminal that asked for it.
+//
+// `onboarder start` keeps the process attached: closing the shell kills it, and
+// that is the right behavior for a foreground command. `onboarder start
+// background` wants the opposite — the whole point is that the terminal can go
+// away — so this module does what a shell job control cannot do portably: it
+// re-launches the CLI as a **detached** child with its stdio pointed at a log
+// file, unrefs it, and then waits for the port to actually answer before it
+// claims success.
+//
+// Two rules keep this honest:
+//
+//   1. Never report "running" on the strength of the spawn alone. `spawn`
+//      returning a pid proves a process was created, not that it bound the port
+//      or survived settings validation. Readiness is an HTTP answer from
+//      `/api/health`, polled with a deadline; on timeout the caller gets the
+//      child's last log lines, not a false green light.
+//   2. Detach properly, or "background" is a lie. `detached: true` puts the
+//      child in its own process group, and `unref()` drops our handle on it, so
+//      a Ctrl-C in the parent terminal does not take the server down with it.
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { configPath } from './config.js';
+import { readPidFile } from './pidfile.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+// The installed entry point, not `process.argv[1]`: a globally installed
+// `onboarder` is a symlink into node_modules, and the child has to run the real
+// file to find its siblings.
+export const CLI_ENTRY = path.resolve(HERE, '..', 'bin', 'onboarder.js');
+
+// One file per config, beside the config, so `--config` isolation (tests,
+// containers, several profiles) carries the log with it.
+export function logPath(configFile = configPath()) {
+  return path.join(path.dirname(path.resolve(configFile)), 'onboarder.log');
+}
+
+// Rotated history. One generation is deliberate: a log that grows without bound
+// is a bug report waiting to happen, and one previous file is enough to see what
+// happened just before a crash.
+export const MAX_LOG_BYTES = 2 * 1024 * 1024;
+
+export async function rotateLogIfNeeded(file = logPath(), maxBytes = MAX_LOG_BYTES) {
+  try {
+    const { size } = await fsp.stat(file);
+    if (size <= maxBytes) return false;
+    await fsp.rename(file, file + '.1');
+    return true;
+  } catch {
+    return false; // no log yet, or not ours to move
+  }
+}
+
+export async function readLog(file = logPath(), bytes = 64 * 1024) {
+  try {
+    const handle = await fsp.open(file, 'r');
+    try {
+      const { size } = await handle.stat();
+      const start = Math.max(0, size - bytes);
+      const buffer = Buffer.alloc(size - start);
+      await handle.read(buffer, 0, buffer.length, start);
+      return buffer.toString('utf8');
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return '';
+  }
+}
+
+// The last `count` lines, oldest first — the shape `onboarder logs` prints and
+// the shape an error report wants pasted into it.
+export async function tailLog(file = logPath(), count = 40) {
+  const text = await readLog(file);
+  const lines = text.split('\n').filter((line) => line.trim());
+  return lines.slice(-Math.max(1, count));
+}
+
+export async function logExists(file = logPath()) {
+  try { await fsp.access(file); return true; } catch { return false; }
+}
+
+// Ask the server whether it is up. A 2xx–4xx from /api/health means the socket
+// is bound and the router is serving; the body is not interesting, the answer is.
+export function probe(url, timeoutMs = 1000) {
+  return new Promise((resolve) => {
+    const request = http.get(url, { timeout: timeoutMs }, (res) => {
+      res.resume();
+      resolve(res.statusCode >= 200 && res.statusCode < 500);
+    });
+    request.on('timeout', () => { request.destroy(); resolve(false); });
+    request.on('error', () => resolve(false));
+  });
+}
+
+export async function waitForReady(url, { timeoutMs = 20000, intervalMs = 200, check = probe } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (await check(url)) return true;
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+
+// Re-run this same CLI, detached. The child is a plain foreground `start` — it
+// writes the pid file, prints its own banner, and handles signals exactly as it
+// always has. Nothing about the server changes; only who is holding the terminal
+// does.
+export function spawnDetached({ configFile = configPath(), entry = CLI_ENTRY, env = process.env, log = logPath(configFile) } = {}) {
+  const fd = fs.openSync(log, 'a');
+  try {
+    const child = spawn(process.execPath, [entry, 'start', '--config', configFile], {
+      detached: true,
+      stdio: ['ignore', fd, fd],
+      env: { ...env, ONBOARDER_BACKGROUND: '1' },
+    });
+    child.on('error', () => {});
+    child.unref();
+    return child.pid;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Does the OS still have this process? Signal 0 asks without delivering.
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+// Wait for the detached child to become the *recorded* server. The pid file is
+// the authority here, not the spawn pid: it is what `status` and `stop` read,
+// so waiting on it means the process we report is the one the user can control.
+export async function waitForPidFile(configFile, { timeoutMs = 20000, intervalMs = 150, readPid = readPidFile, isAlive = alive } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const pid = readPid(configFile);
+    if (pid && isAlive(pid)) return pid;
+    if (Date.now() >= deadline) return null;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+
+// Follow a growing file. Polling rather than fs.watch: the log is appended by a
+// *different* process, and watchers on a file another process holds open are
+// unreliable across platforms (and absent on some network mounts). Half a second
+// of latency on a human-facing log tail is invisible.
+export function followLog(file, onLine, { intervalMs = 500, from = 'end' } = {}) {
+  let position = 0;
+  let partial = '';
+  let stopped = false;
+  const stop = () => { stopped = true; };
+
+  if (from === 'start') {
+    fsp.readFile(file, 'utf8').then(
+      (text) => { for (const line of text.split('\n')) if (line) onLine(line); },
+      () => {},
+    );
+  }
+
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      const { size } = await fsp.stat(file);
+      if (size < position) { position = 0; partial = ''; } // rotated under us
+      if (size > position) {
+        const handle = await fsp.open(file, 'r');
+        try {
+          const length = size - position;
+          const buffer = Buffer.alloc(length);
+          await handle.read(buffer, 0, length, position);
+          position = size;
+          // A read can land mid-line; hold the remainder until its newline shows.
+          const lines = (partial + buffer.toString('utf8')).split('\n');
+          partial = lines.pop() ?? '';
+          for (const line of lines) onLine(line);
+        } finally {
+          await handle.close();
+        }
+      }
+    } catch {
+      // The file may not exist yet (first run) — try again on the next tick.
+    }
+    if (!stopped) setTimeout(tick, intervalMs).unref();
+  };
+
+  setTimeout(tick, intervalMs).unref();
+  return stop;
+}

package/server/index.js

@@ -23,7 +23,8 @@ import { createLogger } from './logger.js';
 import { createMcpRunner } from './mcp/runner.js';
 import { browserUrl, configPath, isLoopbackHost, readSettings, serverUrls } from './config.js';
 import { tunnelStatus } from './tunnel.js';
-import { pidIsAlive, readPidFile, removePidFile, writePidFile } from './pidfile.js';
+import { pidIsAlive, readPidFile, removePidFile, writePidFile, writeRunInfo, runInfoPath } from './pidfile.js';
+import { logPath } from './daemon.js';
 
 const logger = createLogger();
 
@@ -164,14 +165,33 @@ export async function startServer({ configFile = configPath(), openBrowser, log
     throw listenError(error, { host, port, pid: recorded && pidIsAlive(recorded) ? recorded : null });
   }
 
+  // The process record is optional by design, so each write is guarded on its
+  // own: a read-only config directory must not stop a server that has already
+  // bound its port, but a *programming* error here would otherwise be swallowed
+  // and look like "it started, but nothing recorded it".
+  try { writePidFile(configFile); } catch { /* read-only config dir */ }
+  // How this process was launched. `background` is a detached child with a log
+  // file; `startup` is one the OS supervisor started at login (also with a log
+  // file); anything else is a person typing `onboarder start` in a terminal.
+  const mode = process.env.ONBOARDER_LAUNCH || (process.env.ONBOARDER_BACKGROUND ? 'background' : 'foreground');
+  const logFile = mode === 'foreground' ? null : logPath(configFile);
   try {
-    writePidFile(configFile);
-    server.once('close', () => removePidFile(configFile));
-    process.once('exit', () => removePidFile(configFile));
-  } catch {
-    // The server is useful even when a read-only config directory cannot hold
-    // the optional process record; binding and serving are the real contract.
+    // Beside the pid: how this instance was launched and where its log goes, so
+    // `onboarder status` answers "how long has it been up, and how do I see its
+    // output" from a record instead of guessing.
+    writeRunInfo(configFile, {
+      mode,
+      host,
+      port,
+      url: serverUrls(live).local,
+      log: logFile,
+      node: process.version,
+    });
+  } catch (error) {
+    logger.warn('could not write the run record', { file: runInfoPath(configFile), error: error.message });
   }
+  server.once('close', () => removePidFile(configFile));
+  process.once('exit', () => removePidFile(configFile));
 
   log(startupBanner(live, { configFile }));
 

package/server/logger.js

@@ -1,22 +1,103 @@
+// Every line Onboarder writes, in two faces.
+//
+// The entry itself is data — `{ ts, time, level, msg, ...fields }` — and the
+// renderer decides how it looks. JSON goes to pipes, log files and anything
+// parsing us; the aligned human line goes to a terminal. Picking the face once,
+// here, is what keeps a log file readable *and* machine-parseable instead of
+// half one thing.
+//
+// A `time` field (local HH:MM:SS.mmm) rides along with the ISO `ts` on purpose:
+// tailing a file gives you the string, not a Date, and a reader wants their own
+// clock, not UTC.
+
 const levels = { debug: 0, info: 1, warn: 2, error: 3 };
 
-export function createLogger(level = process.env.LOG_LEVEL || 'info') {
+// Worst first — the order any summary or sort should use.
+export const SEVERITY = { error: 0, warn: 1, info: 2, debug: 3 };
+
+const CODES = { red: 31, green: 32, yellow: 33, cyan: 36, gray: 90 };
+const LEVEL_COLOR = { debug: 'gray', info: 'cyan', warn: 'yellow', error: 'red' };
+
+// The server sits *under* the CLI, so it cannot import `cli/ui.js` without
+// inverting the dependency. These three lines of ANSI are the whole price.
+function paint(text, color, enabled) {
+  return enabled && color ? `\x1b[${CODES[color]}m${text}\x1b[0m` : String(text);
+}
+
+// Fields that are part of the envelope or already rendered into the message.
+const ENVELOPE = new Set(['ts', 'time', 'level', 'msg', 'method', 'path', 'status', 'ms', 'line', 'scope']);
+
+// One line, no styling: what a log file holds and what a test asserts on.
+export function formatMessage(entry) {
+  if (entry.line) return `${entry.msg ?? ''} ${entry.line}`.trim();
+  if (entry.method) {
+    const status = entry.status === undefined ? '' : ` ${entry.status}`;
+    const took = entry.ms === undefined ? '' : ` (${entry.ms}ms)`;
+    return `${entry.method} ${entry.path}${status}${took}`;
+  }
+  const extra = Object.entries(entry)
+    .filter(([key, value]) => !ENVELOPE.has(key) && value !== undefined && value !== null)
+    .map(([key, value]) => `${key}=${typeof value === 'string' ? value : JSON.stringify(value)}`);
+  return [entry.msg ?? '', ...extra].filter(Boolean).join(' ');
+}
+
+// Every log line is `time  LEVEL  message`, with the level in a fixed 5-wide
+// column so the messages of an `INFO` and a `ERROR` line start at the same
+// offset. That alignment is the entire point: a wall of request logs is only
+// scannable if the eye can find the message column without reading.
+const LEVEL_WIDTH = 5;
+const GUTTER = '  ';
+
+export function formatEntry(entry) {
+  const time = String(entry.time || String(entry.ts || '').slice(11, 23));
+  const level = String(entry.level || 'info').toUpperCase().padEnd(LEVEL_WIDTH);
+  return `${time}${GUTTER}${level}${GUTTER}${formatMessage(entry)}`;
+}
+
+export function renderEntry(entry, { color = false } = {}) {
+  const time = String(entry.time || String(entry.ts || '').slice(11, 19));
+  const level = String(entry.level || 'info').toUpperCase().padEnd(LEVEL_WIDTH);
+  return paint(time, 'gray', color) + GUTTER + paint(level, LEVEL_COLOR[entry.level] || 'gray', color) + GUTTER + formatMessage(entry);
+}
+
+export function logEntry(level, msg, extra = {}) {
+  const now = new Date();
+  return {
+    ts: now.toISOString(),
+    // Built from the local parts, not `toTimeString()`: that carries a timezone
+    // abbreviation whose width changes (`GMT` vs ` PDT`), which is exactly what
+    // makes a log column ragged. Always 12 characters, always the reader's clock.
+    time: [now.getHours(), now.getMinutes(), now.getSeconds()]
+      .map((part) => String(part).padStart(2, '0'))
+      .join(':') + '.' + String(now.getMilliseconds()).padStart(3, '0'),
+    level,
+    msg,
+    ...extra,
+  };
+}
+
+export function createLogger(level = process.env.LOG_LEVEL || 'info', options = {}) {
   const minLevel = levels[level] ?? levels.info;
-  
+  // `pretty` is the default for a terminal *and* for a log file (aligned text is
+  // what a person reads at 2am); `ONBOARDER_LOG=json` is the machine escape
+  // hatch, and so is a non-TTY consumer that parses stdout.
+  const format = options.format || process.env.ONBOARDER_LOG || 'pretty';
+  const color = options.color ?? (Boolean(process.stdout.isTTY) && !process.env.NO_COLOR);
+  const out = options.stdout || process.stdout;
+  const err = options.stderr || process.stderr;
+
+  function write(entry) {
+    if (format === 'json') {
+      const line = JSON.stringify(entry) + '\n';
+      (entry.level === 'warn' || entry.level === 'error' ? err : out).write(line);
+      return;
+    }
+    (entry.level === 'warn' || entry.level === 'error' ? err : out).write(renderEntry(entry, { color }) + '\n');
+  }
+
   function log(lvl, msg, extra = {}) {
     if (levels[lvl] < minLevel) return;
-    const entry = {
-      ts: new Date().toISOString(),
-      level: lvl,
-      msg,
-      ...extra
-    };
-    const out = JSON.stringify(entry) + '\\n';
-    if (lvl === 'warn' || lvl === 'error') {
-      process.stderr.write(out);
-    } else {
-      process.stdout.write(out);
-    }
+    write(logEntry(lvl, msg, extra));
   }
 
   return {
@@ -24,6 +105,6 @@ export function createLogger(level = process.env.LOG_LEVEL || 'info') {
     info: (msg, extra) => log('info', msg, extra),
     warn: (msg, extra) => log('warn', msg, extra),
     error: (msg, extra) => log('error', msg, extra),
-    http: (req) => log('info', 'HTTP Request', req)
+    http: (req) => log(req.status >= 500 ? 'error' : 'info', 'http', req),
   };
 }

package/server/pidfile.js

@@ -45,5 +45,42 @@ export function writePidFile(configFile) {
 // Remove the file only when it still points at `pid` — a second server that
 // rewrote the file must not lose its record because the first one exited.
 export function removePidFile(configFile, pid = process.pid) {
-  if (readPidFile(configFile) === pid) fs.rmSync(pidPath(configFile), { force: true });
+  if (readPidFile(configFile) === pid) {
+    fs.rmSync(pidPath(configFile), { force: true });
+    removeRunInfo(configFile);
+  }
+}
+
+// The pid answers "is it running?"; it cannot answer "how is it running?".
+// Which mode a live server was launched in (foreground, background, a login
+// item), where its log file is, and when it booted are all things `onboarder
+// status` should be able to print without guessing — so they are written
+// beside the pid, best effort, exactly like the pid itself.
+export function runInfoPath(configFile) {
+  return path.join(path.dirname(path.resolve(configFile)), 'onboarder.run.json');
+}
+
+export function writeRunInfo(configFile, info = {}) {
+  try {
+    fs.writeFileSync(runInfoPath(configFile), JSON.stringify({
+      pid: process.pid,
+      startedAt: new Date().toISOString(),
+      ...info,
+    }, null, 2) + '\n', { mode: 0o600 });
+  } catch {
+    // A read-only config dir must never stop a server from booting.
+  }
+}
+
+export function readRunInfo(configFile) {
+  try {
+    const value = JSON.parse(fs.readFileSync(runInfoPath(configFile), 'utf8'));
+    return value && typeof value === 'object' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function removeRunInfo(configFile) {
+  try { fs.rmSync(runInfoPath(configFile), { force: true }); } catch { /* nothing to clean */ }
 }

package/server/startup.js

@@ -0,0 +1,261 @@
+// Start Onboarder when the machine boots, the way a person actually wants a
+// server they always want running to behave.
+//
+// "Startup" is three different mechanisms wearing one name, so this module
+// detects the platform and speaks its dialect — and, importantly, the *file
+// writing* is separated from the *service loading* so both are testable without
+// a Mac or a systemd:
+//
+//   macOS    ~/Library/LaunchAgents/<label>.plist   → launchctl bootstrap
+//   Linux    ~/.config/systemd/user/<unit>.service  → systemctl --user enable --now
+//   Windows  %APPDATA%\...\Startup\Onboarder.cmd   → being there is enough
+//   other    nothing; we say so rather than pretending
+//
+// Every artifact is generated from the *same* command line a person would type
+// (`<node> <cli> start background --config <file>`), so a login-started server
+// is indistinguishable from a hand-started one — same config, same pid file,
+// same `onboarder stop`.
+//
+// Deliberately no `sudo`, no writing into launchd's system domain, and nothing
+// outside the user's own home. A login item is a convenience; it must never be
+// the thing that needs an administrator password.
+
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { configPath } from './config.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+export const LABEL = 'com.onboarder.server';
+export const UNIT = 'onboarder.service';
+
+export function cliEntry() {
+  // `bin/onboarder.js` next to `server/`, whether we were run from a checkout
+  // or from a global install. The env override is what lets a test point the
+  // generated unit at a fixture instead of the real machine.
+  return process.env.ONBOARDER_CLI || path.resolve(HERE, '..', 'bin', 'onboarder.js');
+}
+
+// The argv a login item runs.
+//
+// Note what is *not* here: `background`. launchd and systemd are already
+// supervisors — they hold the process, restart it, and capture its output. A
+// login item that spawned a detached grandchild and exited immediately would
+// leave the supervisor watching a corpse, which defeats `KeepAlive` and turns a
+// busy port into a respawn loop. So the generated command is a plain foreground
+// `start`, and the OS owns the lifecycle from there.
+export function startupCommand(configFile = configPath(), { node = process.execPath, entry = cliEntry() } = {}) {
+  return [node, entry, 'start', '--config', configFile];
+}
+
+function xmlEscape(value) {
+  const map = { '<': '&lt;', '>': '&gt;', '&': '&amp;', "'": '&apos;', '"': '&quot;' };
+  return String(value).replace(/[<>&'"]/g, (c) => map[c]);
+}
+
+function argList(args) {
+  return args.map((a) => `    <string>${xmlEscape(a)}</string>`).join('\n');
+}
+
+export function renderLaunchAgent({ configFile = configPath(), log = '', ...options } = {}) {
+  const args = startupCommand(configFile, options);
+  const streams = log
+    ? `  <key>StandardOutPath</key>\n  <string>${xmlEscape(log)}</string>\n  <key>StandardErrorPath</key>\n  <string>${xmlEscape(log)}</string>\n`
+    : '';
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(LABEL)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argList(args)}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+${streams}  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(process.env.PATH || '/usr/local/bin:/usr/bin:/bin')}</string>
+    <key>ONBOARDER_LAUNCH</key>
+    <string>startup</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+export function renderSystemdUnit({ configFile = configPath(), log = '', ...options } = {}) {
+  const args = startupCommand(configFile, options);
+  // `Restart=always` would fight `onboarder stop`: a deliberate stop must stay
+  // stopped, so only a *failed* exit is restarted. `on-failure` is the honest
+  // setting here, and `SuccessfulExit=false` above is its launchd spelling.
+  const exec = args.map((a) => (/[\s"]/.test(a) ? JSON.stringify(a) : a)).join(' ');
+  return `[Unit]
+Description=Onboarder — codebase visualizer and onboarding map
+Documentation=https://github.com/Amitpandey88/onboarder
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${exec}
+Restart=on-failure
+RestartSec=3
+${log ? `StandardOutput=append:${log}\nStandardError=append:${log}\n` : ''}Environment=NO_COLOR=1
+Environment=ONBOARDER_LAUNCH=startup
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export function renderWindowsStartup({ configFile = configPath(), log = '', ...options } = {}) {
+  const args = startupCommand(configFile, options);
+  const line = args.map((a) => `"${a}"`).join(' ');
+  return `@echo off\r\nrem Managed by "onboarder start startup". Edits are replaced.\r\nstart "" /b ${line}${log ? ` >> "${log}" 2>&1` : ''}\r\n`;
+}
+
+// The target carries its own platform, so every message about it can name the
+// platform it was resolved for rather than the one this process happens to run
+// on. A test (or a future cross-platform installer) resolves a plan9 target on a
+// Mac; saying "darwin" in that error would be a lie.
+export function startupTarget({ platform = process.platform, home = os.homedir(), env = process.env } = {}) {
+  // The per-user launchd domain. The system domain needs root, which this tool
+  // never asks for.
+  const domain = `gui/${process.getuid?.() ?? 501}`;
+  if (platform === 'darwin') {
+    return {
+      kind: 'launchd',
+      platform,
+      label: LABEL,
+      path: path.join(home, 'Library', 'LaunchAgents', LABEL + '.plist'),
+      render: renderLaunchAgent,
+      load: ['launchctl', 'bootstrap', domain, '{file}'],
+      unload: ['launchctl', 'bootout', `${domain}/{label}`],
+      status: ['launchctl', 'print', `${domain}/{label}`],
+      hint: 'launchd agent in ~/Library/LaunchAgents',
+    };
+  }
+  if (platform === 'linux') {
+    const configHome = env.XDG_CONFIG_HOME || path.join(home, '.config');
+    return {
+      kind: 'systemd',
+      platform,
+      label: UNIT,
+      path: path.join(configHome, 'systemd', 'user', UNIT),
+      render: renderSystemdUnit,
+      daemonReload: ['systemctl', '--user', 'daemon-reload'],
+      load: ['systemctl', '--user', 'enable', '--now', UNIT],
+      unload: ['systemctl', '--user', 'disable', '--now', UNIT],
+      status: ['systemctl', '--user', 'is-active', UNIT],
+      hint: 'systemd --user unit (no root; starts with your session)',
+    };
+  }
+  if (platform === 'win32') {
+    const appData = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    // Native separators throughout: this string goes into a .cmd file and into
+    // the Startup folder itself, and `path.join` would emit `\` mixed with `/`
+    // — which Windows tolerates in a file path but no one should have to read.
+    return {
+      kind: 'startup-folder',
+      platform,
+      label: 'Onboarder.cmd',
+      path: [
+        appData, 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup', 'Onboarder.cmd',
+      ].join('\\'),
+      render: renderWindowsStartup,
+      load: null,   // the file *is* the registration
+      unload: null,
+      status: null,
+      hint: 'script in the Windows Startup folder',
+    };
+  }
+  return { kind: 'unsupported', platform, label: '', path: '', render: null, load: null, unload: null, status: null, hint: '' };
+}
+
+// Substitute `{file}` / `{label}` and run without a shell — an argument is an
+// argument, never a command line somebody else gets to compose. `spawn` is
+// injected so a test can assert on the argv without touching launchd.
+function exec(argv, { spawn = spawnSync } = {}) {
+  const result = spawn(argv[0], argv.slice(1), { encoding: 'utf8' });
+  return {
+    ok: !result.error && result.status === 0,
+    status: result.status ?? null,
+    output: String(result.stdout || result.stderr || '').trim(),
+    error: result.error?.message || '',
+  };
+}
+
+const fill = (argv, target) => argv
+  .map((a) => a.replace('{file}', target.path).replace('{label}', target.label));
+
+export async function startupInstalled(target = startupTarget()) {
+  if (!target.path) return false;
+  try { await fs.access(target.path); return true; } catch { return false; }
+}
+
+export async function startupStatus(target = startupTarget(), { run = spawnSync } = {}) {
+  const installed = await startupInstalled(target);
+  let active = null;
+  if (installed && target.status) {
+    const result = exec(fill(target.status, target), { spawn: run });
+    // systemd answers `active`/`inactive` on stdout; `launchctl print` succeeds
+    // only for a job that is actually loaded. Both answer "is it live now".
+    const text = result.output.toLowerCase();
+    active = target.kind === 'systemd'
+      ? text.includes('active') && !text.includes('inactive')
+      : result.ok;
+  }
+  return {
+    kind: target.kind,
+    supported: target.kind !== 'unsupported',
+    label: target.label,
+    path: target.path,
+    installed,
+    active,
+    detail: target.kind === 'unsupported'
+      ? `no automatic-startup mechanism for ${target.platform || process.platform}`
+      : installed
+        ? (active ? `running — ${target.hint}` : `installed, not running — ${target.hint}`)
+        : 'not installed',
+    hint: target.hint,
+  };
+}
+
+export async function installStartup({ configFile = configPath(), log = '', target = startupTarget(), run = spawnSync } = {}) {
+  if (target.kind === 'unsupported') {
+    return { ok: false, reason: `There is no automatic-startup mechanism Onboarder knows how to write on ${target.platform || process.platform}. Start it with \`onboarder start background\` from whatever your machine runs at boot.` };
+  }
+  await fs.mkdir(path.dirname(target.path), { recursive: true });
+  await fs.writeFile(target.path, target.render({ configFile, log }), { encoding: 'utf8', mode: 0o600 });
+  if (target.kind === 'systemd' && target.daemonReload) exec(fill(target.daemonReload, target), { spawn: run });
+  if (!target.load) return { ok: true, path: target.path, loaded: true, output: '' };
+  const result = exec(fill(target.load, target), { spawn: run });
+  // A unit that is already loaded is a success, not a failure — installing twice
+  // has to be idempotent, and `launchctl` says so in three different ways.
+  const already = /already (been )?(loaded|active|exists|running)|115|unit .*already/i.test(result.output);
+  if (!result.ok && !already) {
+    return { ok: false, path: target.path, output: result.output || result.error, error: result.error };
+  }
+  return { ok: true, path: target.path, loaded: true, output: result.output };
+}
+
+export async function removeStartup({ target = startupTarget(), run = spawnSync } = {}) {
+  if (target.kind === 'unsupported') return { ok: false, reason: 'Nothing is installed for this platform.' };
+  let output = '';
+  if (target.unload) output = exec(fill(target.unload, target), { spawn: run }).output;
+  await fs.rm(target.path, { force: true });
+  if (target.kind === 'systemd' && target.daemonReload) exec(fill(target.daemonReload, target), { spawn: run });
+  return { ok: true, path: target.path, output };
+}