npm - lazyclaw - Versions diffs - 3.99.5 → 3.99.8 - Mend

lazyclaw 3.99.5 → 3.99.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/cli.mjs CHANGED Viewed

@@ -877,6 +877,8 @@ const SUBCOMMANDS = [
   'rates',
   // OpenClaw-parity subsurfaces (v3.93–v3.98)
   'auth', 'pairing', 'nodes', 'message', 'workspace', 'browse', 'cron',
+  // v3.99.6 — multi-step setup wizard + lazyclaw-only dashboard
+  'setup', 'dashboard',
 ];
 const SUBCOMMAND_SUBS = {
@@ -1107,6 +1109,8 @@ const HELP_SUMMARIES = {
   workspace:  'AGENTS.md / SOUL.md / TOOLS.md system-prompt convention (workspace list|init|show|remove|path)',
   browse:     'Fetch a URL and emit Markdown on stdout (browse <url> [--max-bytes <N>])',
   cron:       'Schedule recurring agent runs via launchd / crontab (cron list|add|remove|show|sync|run)',
+  setup:      'OpenClaw-style multi-step first-run wizard (provider + workspace + skill + webhook + ping)',
+  dashboard:  'Launch the lazyclaw-only web UI (lighter than the full lazyclaude dashboard)',
   inspect:    'Print persisted workflow state without executing',
   clear:      'Delete a persisted workflow state file (idempotent)',
   validate:   'Static-check a workflow file: shape, deps, cycles, parallelism',
@@ -1144,6 +1148,8 @@ const HELP_DETAILS = {
   workspace: 'Usage: lazyclaw workspace <list | init <name> | show <name> [<file>] | remove <name> | path <name>>\n  Workspace = a directory under <configDir>/workspaces/<name>/ containing AGENTS.md, SOUL.md, TOOLS.md.\n  When `chat` or `agent` is invoked with --workspace <name>, the three files are stitched into a single system prompt at the head of the conversation. Missing files are skipped silently.\n  init scaffolds the three files with short stubs you replace.\n  show prints the composed prompt; show <name> AGENTS.md (etc) prints just one file.',
   browse: 'Usage: lazyclaw browse <url> [--max-bytes <N>] [--timeout-ms <N>] [--user-agent <ua>] [--meta]\n  Fetches the URL and emits Markdown on stdout. Pipes cleanly into `agent`:\n      lazyclaw browse https://example.com/docs | lazyclaw agent -\n  Strips <script>/<style>/<svg>/comments, prefers <main>/<article>, falls back to <body>.\n  --max-bytes caps the body read (default 2 MB) so a misconfigured upstream can\'t OOM the process.\n  --meta prints { url, title, bytes, truncated } as JSON to stderr alongside the markdown on stdout.',
   cron: 'Usage: lazyclaw cron <list | add <name> "<cron-spec>" -- <cmd> ... | remove <name> | show <name> | sync | run <name>>\n  Schedule recurring agent runs. macOS uses launchd (~/Library/LaunchAgents/com.lazyclaw.<name>.plist); Linux / WSL uses the user crontab.\n  Cron spec is the standard 5-field form (minute hour dom month dow). Supports *, range a-b, list a,b,c, step */N.\n  add: pass the command after `--`. Typical use:\n      lazyclaw cron add daily-summary "0 9 * * 1-5" -- lazyclaw agent "Summarise today\'s TODOs"\n  list / show: read from cfg.cron[name] (config is the source of truth).\n  sync: re-installs every job in cfg.cron into the system scheduler — handy after a reinstall.\n  run: one-shot in-process execution of the named job; the OS scheduler does the same thing on its trigger.\n  Logs: ~/.lazyclaw/logs/cron-<name>.{out,err}.log (macOS launchd path).',
+  setup: 'Usage: lazyclaw setup [--skip-test]\n  OpenClaw-style multi-step first-run wizard. Walks through:\n    1. Provider + model + api-key (delegates to onboard --pick)\n    2. Optional workspace init  (AGENTS.md / SOUL.md / TOOLS.md)\n    3. Optional skill bundle install from GitHub\n    4. Optional outbound webhook (Slack / Discord)\n    5. Reachability test against the picked provider\n  Each optional step takes Enter or "skip" to bypass. Re-runnable safely.\n  Also fires automatically on first run when `lazyclaw` is invoked with no config.',
+  dashboard: 'Usage: lazyclaw dashboard [--port <N>] [--no-open]\n  Launches the lazyclaw-only web UI on http://127.0.0.1:<port> (default 19600) and opens it in the default browser.\n  Wraps `lazyclaw daemon` + a static HTML; no Python / lazyclaude dashboard required.\n  Tabs: Chat · Sessions · Skills · Workspace · Providers · Status. Each tab calls existing daemon endpoints.\n  --no-open keeps the browser closed (handy for SSH / headless / dev). The bound URL is always printed to stdout.',
 };
 function cmdHelp(name) {
@@ -1312,14 +1318,18 @@ async function cmdAgent(prompt, flags) {
 // (replaces rl.line with the full command). Tab still goes through
 // readline's tab-completer for cycling.
 function _attachGhostAutocomplete(rl) {
-  // Returns a `dispose()` callback that detaches the keypress listener
-  // and the rl 'line' listener installed below. Without disposal the
-  // process never exits — Node keeps the event loop alive while
-  // process.stdin has a 'keypress' listener attached. (This was the
-  // root cause of the slow `/exit` users reported.)
-  if (!process.stdout.isTTY) return () => {};
+  // Returns `{ dispose, suspend, resume }`. Dispose detaches the
+  // keypress + rl 'line' listeners (failure to do so leaks the
+  // event-loop ref, which is exactly the slow-exit bug v3.92
+  // fixed). Suspend / resume gate the keypress handler so the
+  // streaming chat output isn't interleaved with `\x1b[s\x1b[K\x1b[u`
+  // ghost-render escapes — that interleaving is what surfaces as
+  // visible gaps between Korean characters in long replies.
+  const noop = () => {};
+  if (!process.stdout.isTTY) return { dispose: noop, suspend: noop, resume: noop };
   const cmds = SLASH_COMMANDS.map((c) => c.cmd);
   let lastGhost = '';
+  let suspended = false;
   // Find the longest match for the current input. Returns '' when
   // nothing matches or when the input already equals a command.
   const findMatch = () => {
@@ -1356,6 +1366,10 @@ function _attachGhostAutocomplete(rl) {
   // _refreshLine, then return without forwarding the keypress.
   const onKeypress = (_str, key) => {
     if (!key) return;
+    // While a streaming response is being printed, do nothing —
+    // any ANSI cursor save / restore we emit would tear the wide-
+    // character (CJK) output apart on the visible terminal.
+    if (suspended) return;
     if (key.name === 'right' && lastGhost && rl.line === rl.line.trim() &&
         rl.cursor === (rl.line || '').length && (rl.line || '').length < lastGhost.length) {
       const accepted = lastGhost;
@@ -1381,33 +1395,81 @@ function _attachGhostAutocomplete(rl) {
   // over between turns.
   const onLine = () => { lastGhost = ''; };
   rl.on('line', onLine);
-  return () => {
+  const dispose = () => {
     try { process.stdin.removeListener('keypress', onKeypress); } catch (_) {}
     try { rl.removeListener('line', onLine); } catch (_) {}
     // Wipe any leftover ghost on screen so the user's terminal doesn't
     // keep a dim suffix after we exit.
     try { process.stdout.write('\x1b[s\x1b[K\x1b[u'); } catch (_) {}
   };
+  return {
+    dispose,
+    suspend: () => {
+      suspended = true;
+      // Wipe any half-rendered ghost before streaming starts so the
+      // first chunk lands at the same column as the prompt.
+      try { process.stdout.write('\x1b[s\x1b[K\x1b[u'); } catch (_) {}
+    },
+    resume: () => { suspended = false; },
+  };
 }
 // LazyClaw banner — printed once at the top of every interactive chat
 // session so users see the active provider/model before they start
 // typing. Plain ANSI; auto-skipped when stdout isn't a TTY (so piped
 // invocations stay clean for tests/scripts).
+// Single source of truth for the LazyClaw banner — used by the chat
+// REPL header, the no-arg launcher, and the first-run welcome panel.
+// Returns an array of pre-formatted lines (with ANSI colour) so the
+// caller can splice in additional rows without re-implementing the
+// alignment.
+//
+// Width-management rule: every inner line is forced through
+// `.padEnd(W)` so a stray width miscount can't punch the right
+// border off the box (which is exactly the bug v3.99.5 shipped:
+// two of the inner lines were 33 cols vs the others' 32, so the
+// ╮ rendered into the next line).
+function _renderBanner(version) {
+  const W = 30;
+  const accent = (s) => `\x1b[38;5;208m${s}\x1b[0m`;
+  const dim    = (s) => `\x1b[2m${s}\x1b[0m`;
+  // Inner content of each banner row — DO NOT pad here, the wrapper
+  // does it. Backslashes are JS-escaped so each `\\` renders as one
+  // literal `\` in the output.
+  const inner = [
+    '   _',
+    '  | |__ _ _____  _ _',
+    "  | / _` |_ / || | '_|",
+    '  |_\\__,_/__\\_, |_|',
+    '  LazyClaw  |__/  ' + String(version || '?.?.?').padEnd(10).slice(0, 10),
+  ];
+  // Sleepy-cat mascot on the right, lined up with the busiest part
+  // of the wordmark. Three rows of ASCII art + "zz" trail. Plain
+  // ASCII (no box-drawing on the cat) so it lands well in any font.
+  const mascot = [
+    '',
+    '',
+    '   /\\_/\\',
+    '  ( -.- )  ' + dim('z z'),
+    '   > ^ <    ' + dim('z'),
+    '',
+    '',
+  ];
+  const banner = [
+    '╭' + '─'.repeat(W) + '╮',
+    ...inner.map((s) => '│' + s.padEnd(W).slice(0, W) + '│'),
+    '╰' + '─'.repeat(W) + '╯',
+  ];
+  return banner.map((l, i) => '  ' + accent(l) + (mascot[i] ? '  ' + mascot[i] : ''));
+}
 function _printChatBanner(activeProvName, activeModel, version) {
   if (!process.stdout.isTTY) return;
   const dim = (s) => `\x1b[2m${s}\x1b[0m`;
-  const accent = (s) => `\x1b[38;5;208m${s}\x1b[0m`;
   const ok = (s) => `\x1b[32m${s}\x1b[0m`;
   const lines = [
     '',
-    accent('  ╭──────────────────────────────╮'),
-    accent('  │   _                          │'),
-    accent('  │  | |__ _ _____  _ _          │'),
-    accent('  │  | / _` |_ / || | \'_|         │'),
-    accent('  │  |_\\__,_/__\\_, |_|            │'),
-    accent('  │  LazyClaw  |__/  ' + (version || '').padEnd(10) + '  │'),
-    accent('  ╰──────────────────────────────╯'),
+    ..._renderBanner(version),
     '',
     `  ${dim('provider ·')} ${ok(activeProvName)}`,
     `  ${dim('model    ·')} ${ok(activeModel || '(default)')}`,
@@ -1422,31 +1484,25 @@ function _printChatBanner(activeProvName, activeModel, version) {
 // when the user passes --pick. Falls back to plain stdin reads when
 // stdout isn't a TTY (CI/script callers should pass --non-interactive
 // equivalents instead).
-async function _pickProviderInteractive() {
-  const providers = Object.keys(_registryMod.PROVIDERS);
-  if (!providers.length) return { provider: 'mock', model: null };
-  const info = _registryMod.PROVIDER_INFO || {};
-  // Build one row per (provider, model) pair using the static
-  // PROVIDER_INFO.suggestedModels list (registry.mjs is the single
-  // source of truth). When a provider has no models (mock), we emit
-  // one row for the provider itself.
-  const items = [];
-  for (const name of providers) {
-    const meta = info[name] || {};
-    const models = (Array.isArray(meta.suggestedModels) && meta.suggestedModels.length)
-      ? meta.suggestedModels
-      : [null];
-    const keyTag = meta.requiresApiKey
-      ? '\x1b[38;5;245m[api key]\x1b[0m'
-      : (name === 'claude-cli' ? '\x1b[38;5;208m[subscription]\x1b[0m' : '\x1b[38;5;245m[no key]\x1b[0m');
-    for (const m of models) {
-      const label = m ? `${name.padEnd(11)}  ${m}` : `${name.padEnd(11)}  (no model)`;
-      items.push({ provider: name, model: m, label, keyTag });
-    }
-  }
+// Generic arrow-key menu used by the multi-step provider/model
+// picker below. Returns the picked item, or one of the sentinel
+// strings 'BACK' (Esc — caller should retry the previous step) or
+// 'CANCEL' (q — caller should bail entirely). Ctrl-C exits the
+// process directly, matching every other interactive prompt in the
+// CLI.
+//
+// `items` is an array of { id, label, desc, tag }. `tag` is an
+// optional pre-coloured pill (e.g. "[api key]") that lands on the
+// right side of the row. `defaultIdx` lets the caller pin where the
+// cursor lands; default 0.
+async function _arrowMenu({ title, subtitle, footer, items, defaultIdx = 0 }) {
   if (!process.stdout.isTTY || !process.stdin.isTTY) {
-    // Fall back to a single prompt — the picker UI is purely cosmetic.
-    process.stdout.write(`provider [${providers.join('|')}]: `);
+    // Non-TTY fallback: print the labels on stderr and read a single
+    // line of stdin. Used when somebody pipes input to `lazyclaw
+    // setup` — the wizard still works, just without arrows.
+    process.stderr.write(`${title}\n`);
+    items.forEach((it, i) => process.stderr.write(`  ${i + 1}. ${it.label}${it.desc ? ' — ' + it.desc : ''}\n`));
+    process.stderr.write('pick (number / id, blank for first): ');
     const ans = await new Promise((resolve) => {
       let buf = '';
       const onData = (chunk) => {
@@ -1455,38 +1511,47 @@ async function _pickProviderInteractive() {
       };
       process.stdin.on('data', onData);
     });
-    return { provider: ans || providers[0], model: null };
+    if (!ans) return items[0];
+    const byNum = parseInt(ans, 10);
+    if (Number.isFinite(byNum) && byNum >= 1 && byNum <= items.length) return items[byNum - 1];
+    const byId = items.find((it) => it.id === ans || it.label === ans);
+    return byId || items[0];
   }
-  // Default cursor: lands on item 0 (= the first row from PROVIDERS
-  // insertion order, which registry.mjs deliberately curates as the
-  // most user-familiar vendor — gemini at the time of writing).
-  let idx = 0;
   const readline = await import('node:readline');
   readline.emitKeypressEvents(process.stdin);
   if (process.stdin.setRawMode) process.stdin.setRawMode(true);
-  // Long lists need scrolling so the picker fits the terminal height.
-  // Reserve 6 rows for header + footer + breathing room.
+  let idx = Math.max(0, Math.min(items.length - 1, defaultIdx));
+  const accent = (s) => `\x1b[38;5;208m${s}\x1b[0m`;
+  const dim    = (s) => `\x1b[2m${s}\x1b[0m`;
+  const bold   = (s) => `\x1b[1m${s}\x1b[0m`;
   const draw = () => {
-    process.stdout.write('\x1b[?25l');     // hide cursor
-    process.stdout.write('\x1b[2J\x1b[H'); // clear screen
-    process.stdout.write('\x1b[38;5;208mLazyClaw — pick a provider/model\x1b[0m\n');
-    process.stdout.write('\x1b[2m↑/↓ to move · Enter to confirm · q to quit\x1b[0m\n');
-    process.stdout.write('\x1b[2m[subscription] = uses `claude` login (no key)  ·  [api key] = needs sk-... key  ·  [no key] = local\x1b[0m\n\n');
-    const rows = Math.max(6, (process.stdout.rows || 24) - 6);
+    process.stdout.write('\x1b[?25l\x1b[2J\x1b[H');
+    process.stdout.write(accent(title) + '\n');
+    if (subtitle) process.stdout.write(dim(subtitle) + '\n');
+    process.stdout.write(dim('↑/↓ to move · Enter to confirm · Esc to back · q to quit') + '\n\n');
+    const rows = Math.max(6, (process.stdout.rows || 24) - 8);
     let from = Math.max(0, idx - Math.floor(rows / 2));
     if (from + rows > items.length) from = Math.max(0, items.length - rows);
     const to = Math.min(items.length, from + rows);
+    // Pre-compute label width so descriptions line up across rows.
+    const labelW = items.reduce((w, it) => Math.max(w, (it.label || '').length), 12);
     for (let i = from; i < to; i++) {
       const it = items[i];
-      const marker = i === idx ? '\x1b[38;5;208m❯\x1b[0m ' : '  ';
-      const text = i === idx ? `\x1b[1m${it.label}\x1b[0m` : it.label;
-      process.stdout.write(`${marker}${text}  ${it.keyTag}\n`);
+      const marker = i === idx ? accent('❯ ') : '  ';
+      const lbl = (it.label || '').padEnd(labelW);
+      const lblOut = i === idx ? bold(lbl) : lbl;
+      const desc = it.desc ? '  ' + dim(it.desc) : '';
+      const tag = it.tag ? '  ' + it.tag : '';
+      process.stdout.write(`${marker}${lblOut}${desc}${tag}\n`);
     }
     if (to < items.length) {
-      process.stdout.write(`\x1b[2m  …(${items.length - to} more)\x1b[0m\n`);
+      process.stdout.write(`${dim(`  …(${items.length - to} more)`)}\n`);
     }
+    if (footer) process.stdout.write('\n' + dim(footer) + '\n');
   };
   draw();
   return await new Promise((resolve) => {
     const onKey = (_str, key) => {
@@ -1499,18 +1564,145 @@ async function _pickProviderInteractive() {
       else if (key.name === 'end')  { idx = items.length - 1; draw(); }
       else if (key.name === 'return') { cleanup(); resolve(items[idx]); }
       else if (key.ctrl && key.name === 'c') { cleanup(); process.exit(130); }
-      else if (key.name === 'q' || key.name === 'escape') { cleanup(); resolve(items[idx]); }
+      else if (key.name === 'escape') { cleanup(); resolve('BACK'); }
+      else if (key.name === 'q')      { cleanup(); resolve('CANCEL'); }
     };
     const cleanup = () => {
       process.stdin.off('keypress', onKey);
       if (process.stdin.setRawMode) process.stdin.setRawMode(false);
-      process.stdout.write('\x1b[?25h');     // show cursor
-      process.stdout.write('\x1b[2J\x1b[H'); // clear screen
+      process.stdout.write('\x1b[?25h\x1b[2J\x1b[H');
     };
     process.stdin.on('keypress', onKey);
   });
 }
+// Bucket every registered provider into one of three auth-method
+// families. The picker's first step asks the user which family
+// they want before drilling into specific providers — much less
+// overwhelming than a flat 40-row list. Bucket assignment lives
+// here (rather than registry.mjs) because it's a UX concept, not
+// an intrinsic provider attribute.
+function _providerFamilies() {
+  const info = _registryMod.PROVIDER_INFO || {};
+  const all = Object.keys(_registryMod.PROVIDERS);
+  const buckets = {
+    api: { label: 'API key', desc: 'paste an sk-... key during setup',  tag: '\x1b[38;5;245m[needs key]\x1b[0m', members: [] },
+    cli: { label: 'CLI / Local', desc: 'keyless — uses an existing CLI login or a local daemon', tag: '\x1b[38;5;208m[no key]\x1b[0m', members: [] },
+    mock: { label: 'Mock', desc: 'offline echo, only useful for testing', tag: '\x1b[38;5;245m[test]\x1b[0m', members: [] },
+  };
+  for (const name of all) {
+    if (name === 'mock') buckets.mock.members.push(name);
+    else if ((info[name] || {}).requiresApiKey) buckets.api.members.push(name);
+    else buckets.cli.members.push(name);
+  }
+  return buckets;
+}
+// Multi-step provider / model picker — replaces the flat 40-row
+// list of v3.99.5 with a drill-in:
+//
+//   Step 1 — auth family (API key / CLI-Local / Mock)
+//   Step 2 — provider in that family (gemini / openai / claude-cli / …)
+//   Step 3 — model in that provider's suggestedModels
+//
+// Esc at any step goes back one. q or Ctrl-C cancels entirely.
+// Steps that have only one option auto-advance so the user doesn't
+// stare at a single-row menu (e.g. the Mock family has just `mock`).
+async function _pickProviderInteractive() {
+  const providers = Object.keys(_registryMod.PROVIDERS);
+  if (!providers.length) return { provider: 'mock', model: null };
+  const info = _registryMod.PROVIDER_INFO || {};
+  const families = _providerFamilies();
+  // Non-TTY fallback — single-prompt picker, identical to before.
+  if (!process.stdout.isTTY || !process.stdin.isTTY) {
+    process.stdout.write(`provider [${providers.join('|')}]: `);
+    const ans = await new Promise((resolve) => {
+      let buf = '';
+      const onData = (chunk) => {
+        buf += chunk.toString();
+        if (buf.includes('\n')) { process.stdin.off('data', onData); resolve(buf.trim()); }
+      };
+      process.stdin.on('data', onData);
+    });
+    return { provider: ans || providers[0], model: null };
+  }
+  // ── Step 1 — auth family ──────────────────────────────────────
+  let family = null;
+  while (!family) {
+    const familyItems = Object.entries(families)
+      .filter(([, b]) => b.members.length > 0)
+      .map(([id, b]) => ({
+        id,
+        label: b.label,
+        desc: `${b.desc}  ·  ${b.members.join(' / ')}`,
+        tag: b.tag,
+      }));
+    const picked = await _arrowMenu({
+      title: 'LazyClaw setup — Step 1 of 3:  pick how you want to auth',
+      subtitle: 'API: bring your own key  ·  CLI/Local: use what\'s already on this machine  ·  Mock: offline test',
+      items: familyItems,
+    });
+    if (picked === 'CANCEL' || picked === 'BACK') return null;
+    family = picked;
+  }
+  // ── Step 2 — provider in that family ──────────────────────────
+  let provider = null;
+  while (!provider) {
+    const memberNames = families[family.id].members;
+    if (memberNames.length === 1) {
+      // Auto-advance — no point making the user pick from a single
+      // row.
+      provider = { id: memberNames[0] };
+      break;
+    }
+    const provItems = memberNames.map((name) => {
+      const meta = info[name] || {};
+      const models = (meta.suggestedModels || []).slice(0, 4).join(' · ') || '(default)';
+      return {
+        id: name,
+        label: name,
+        desc: `models: ${models}`,
+        tag: meta.requiresApiKey ? '\x1b[38;5;245m[api key]\x1b[0m' : '\x1b[38;5;208m[no key]\x1b[0m',
+      };
+    });
+    const picked = await _arrowMenu({
+      title: `LazyClaw setup — Step 2 of 3:  pick a ${family.label} provider`,
+      subtitle: `Showing ${memberNames.length} ${family.label.toLowerCase()} provider(s).`,
+      items: provItems,
+    });
+    if (picked === 'CANCEL') return null;
+    if (picked === 'BACK')   { family = null; return _pickProviderInteractive(); }
+    provider = picked;
+  }
+  // ── Step 3 — model ────────────────────────────────────────────
+  const meta = info[provider.id] || {};
+  const models = Array.isArray(meta.suggestedModels) ? meta.suggestedModels : [];
+  if (!models.length) {
+    // Provider has no curated models (mock) — return without a
+    // model so the underlying call uses the provider default.
+    return { provider: provider.id, model: null };
+  }
+  while (true) {
+    const modelItems = models.map((m) => ({ id: m, label: m, desc: '' }));
+    // Pin the cursor to the provider's defaultModel so Enter without
+    // navigation picks the most-recommended one.
+    const defaultIdx = Math.max(0, models.indexOf(meta.defaultModel || models[0]));
+    const picked = await _arrowMenu({
+      title: `LazyClaw setup — Step 3 of 3:  pick a model for ${provider.id}`,
+      subtitle: `Showing ${models.length} suggested model(s). Type the model id directly later via /model in chat to use anything not listed here.`,
+      items: modelItems,
+      defaultIdx,
+    });
+    if (picked === 'CANCEL') return null;
+    if (picked === 'BACK')   return _pickProviderInteractive(); // back to step 1
+    return { provider: provider.id, model: picked.id };
+  }
+}
 async function cmdChat(flags = {}) {
   await ensureRegistry();
   const sessionsMod = await import('./sessions.mjs');
@@ -1553,13 +1745,13 @@ async function cmdChat(flags = {}) {
     terminal: useTerminal,
     prompt: useTerminal ? '\x1b[38;5;208m›\x1b[0m ' : '',
   });
-  let _disposeGhost = () => {};
+  let _ghost = { dispose: () => {}, suspend: () => {}, resume: () => {} };
   if (useTerminal) {
     // Cursor-style ghost autocomplete: when the buffer starts with `/`,
     // render the longest matching command after the cursor in dim grey.
     // Right-arrow at end-of-line accepts. Tab still cycles via the
     // existing handleSlash branch; this only adds the inline preview.
-    _disposeGhost = _attachGhostAutocomplete(rl) || (() => {});
+    _ghost = _attachGhostAutocomplete(rl) || _ghost;
     rl.prompt();
   }
@@ -1811,6 +2003,32 @@ async function cmdChat(flags = {}) {
       process.stdout.write('\n^C interrupted — prompt is back\n');
     };
     process.on('SIGINT', onSigint);
+    // Pause the ghost-autocomplete keypress handler while the
+    // provider is streaming. Without this, every stale stdin event
+    // would trigger `\x1b[s\x1b[K\x1b[u` cursor save/restore writes
+    // that interleave with the streamed text and surface as visible
+    // gaps between CJK characters (visible in user-reported screen
+    // captures of Korean replies).
+    if (useTerminal) _ghost.suspend();
+    // Buffered writer — coalesce single-character streaming chunks
+    // into ~30 ms windows. Two reasons:
+    //   1. Korean / Japanese / Chinese tokens often arrive as one
+    //      character per chunk. Each individual `process.stdout.write`
+    //      can race against terminal redraw on a wide-cell character,
+    //      producing the same "visible space between every character"
+    //      symptom the suspend above also addresses.
+    //   2. Far fewer syscalls. A 200-char Korean reply was ~200
+    //      separate writes; this collapses to ~7-10.
+    let _writeBuf = '';
+    let _writeTimer = null;
+    const _flush = () => {
+      if (_writeBuf) { process.stdout.write(_writeBuf); _writeBuf = ''; }
+      _writeTimer = null;
+    };
+    const _writeChunk = (s) => {
+      _writeBuf += s;
+      if (!_writeTimer) _writeTimer = setTimeout(_flush, 30);
+    };
     try {
       for await (const chunk of prov.sendMessage(messages, {
         apiKey: _resolveAuthKey(cfg, activeProvName),
@@ -1819,13 +2037,21 @@ async function cmdChat(flags = {}) {
         signal: turnAc.signal,
         onUsage: accumulateUsage,
       })) {
-        process.stdout.write(chunk);
+        _writeChunk(chunk);
         acc += chunk;
       }
+      // Drain anything still buffered before the trailing newline so
+      // the prompt lands on its own line cleanly.
+      if (_writeTimer) clearTimeout(_writeTimer);
+      _flush();
       process.stdout.write('\n');
       messages.push({ role: 'assistant', content: acc });
       persistTurn('assistant', acc);
     } catch (err) {
+      // Drain pending buffer so partial reply stays on screen even
+      // when the stream errors mid-flight.
+      if (_writeTimer) clearTimeout(_writeTimer);
+      _flush();
       // ABORT errors are user-initiated; partial assistant output is
       // discarded (we don't append a half-reply to the message history
       // because the next turn would treat it as a complete reply and
@@ -1835,6 +2061,7 @@ async function cmdChat(flags = {}) {
       }
     } finally {
       process.off('SIGINT', onSigint);
+      if (useTerminal) _ghost.resume();
     }
     if (useTerminal) rl.prompt();
   } } finally {
@@ -1842,7 +2069,7 @@ async function cmdChat(flags = {}) {
     // hung for ~3-5 s while Node waited for stdin's keypress listener
     // and raw mode to release. Tearing them down explicitly drops the
     // exit time to <100 ms.
-    try { _disposeGhost(); } catch (_) {}
+    try { _ghost.dispose(); } catch (_) {}
     try { rl.close(); } catch (_) {}
     if (useTerminal && process.stdin.isTTY && process.stdin.setRawMode) {
       try { process.stdin.setRawMode(false); } catch (_) {}
@@ -1855,6 +2082,69 @@ async function cmdChat(flags = {}) {
   }
 }
+// Light wrapper around the daemon — meant for users who installed
+// via npm and don't want to remember `daemon` flags. Boots the
+// daemon on a fixed default port (override with --port), then opens
+// the dashboard URL in the user's default browser.
+//
+// Why a separate command: typing `lazyclaw daemon` works too, but
+// `dashboard` is the discoverable name and it auto-opens the browser
+// (which the bare daemon doesn't, since most daemon callers are
+// scripts).
+async function cmdDashboard(flags = {}) {
+  await ensureRegistry();
+  const sessionsMod = await import('./sessions.mjs');
+  const { startDaemon } = await import('./daemon.mjs');
+  const port = flags.port !== undefined ? parseInt(flags.port, 10) : 19600;
+  const cfgDir = path.dirname(configPath());
+  const d = await startDaemon({
+    port,
+    once: false,
+    readConfig,
+    sessionsDirGetter: () => cfgDir,
+    sessionsMod,
+    version: () => readVersionFromRepo(),
+    workflowStateDir: () => process.env.LAZYCLAW_WORKFLOW_STATE_DIR || '.workflow-state',
+    // No auth token by default — same loopback-only assumption the
+    // bare daemon uses. Users who want to expose the dashboard set
+    // LAZYCLAW_AUTH_TOKEN + --allow-origin via the daemon command.
+    authToken: undefined,
+    allowedOrigins: [],
+    rateLimit: null,
+    responseCache: null,
+    logger: null,
+    costCap: null,
+  });
+  const url = `http://127.0.0.1:${d.port}/dashboard`;
+  process.stdout.write(`🦞 LazyClaw dashboard listening at ${url}\n`);
+  if (!flags['no-open']) {
+    // macOS uses `open`; Linux generally `xdg-open`; Windows
+    // `cmd /c start`. Detect by platform; bail silently if the
+    // helper fails — the URL is already on stdout for fallback.
+    const { spawn } = await import('node:child_process');
+    let cmd, args;
+    if (process.platform === 'darwin')      { cmd = 'open';      args = [url]; }
+    else if (process.platform === 'win32')  { cmd = 'cmd';       args = ['/c', 'start', '""', url]; }
+    else                                    { cmd = 'xdg-open';  args = [url]; }
+    try {
+      spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+    } catch (_) { /* user can click the URL above */ }
+  }
+  // Forward SIGINT/SIGTERM to a graceful shutdown so Ctrl-C doesn't
+  // strand a port-bound server. Same shape cmdDaemon uses.
+  const { gracefulShutdown } = await import('./daemon.mjs');
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return process.exit(1);
+    shuttingDown = true;
+    process.stdout.write('\n  shutting down…\n');
+    const result = await gracefulShutdown(d.server, 5_000);
+    process.exit(result.forced ? 1 : 0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
 async function cmdDaemon(flags) {
   await ensureRegistry();
   const sessionsMod = await import('./sessions.mjs');
@@ -3082,6 +3372,144 @@ function parseArgs(argv) {
 // so chat / agent / etc. behave bit-identically to typing them
 // directly. Non-TTY (piped, scripted) callers still see the
 // classic "Usage: …" line so automation isn't surprised.
+// Multi-step setup wizard — OpenClaw-style first-run experience.
+// Provider/model/key + optional workspace + optional sample skill
+// + reachability ping. Each step can be skipped (Enter on prompt /
+// "n" on yes-no). Re-runnable safely: existing state is reused, not
+// clobbered, except when the user explicitly opts in.
+//
+// `lazyclaw setup` exposes this directly so users can re-run the
+// wizard any time. The first-run code path also funnels through it
+// so a fresh install sees the same flow whether they typed
+// `lazyclaw` or `lazyclaw setup`.
+async function cmdSetup(_sub, _positional, flags = {}) {
+  await ensureRegistry();
+  const accent = (s) => `\x1b[38;5;208m${s}\x1b[0m`;
+  const bold   = (s) => `\x1b[1m${s}\x1b[0m`;
+  const dim    = (s) => `\x1b[2m${s}\x1b[0m`;
+  const ok     = (s) => `\x1b[32m${s}\x1b[0m`;
+  const warn   = (s) => `\x1b[33m${s}\x1b[0m`;
+  // Header.
+  if (process.stdout.isTTY) process.stdout.write('\x1b[2J\x1b[H');
+  _renderBanner(readVersionFromRepo()).forEach((l) => process.stdout.write(l + '\n'));
+  process.stdout.write('\n');
+  process.stdout.write(`  ${bold('🔧 Setup wizard')}\n`);
+  process.stdout.write(`  ${dim('Five short steps. Press Enter to accept the default; type "skip" or "n" to bypass an optional step.')}\n\n`);
+  const cfg = readConfig();
+  const cfgDir = path.dirname(configPath());
+  // ── Step 1: Provider + model (mandatory) ────────────────────
+  process.stdout.write(`  ${accent('Step 1/5 ·')} ${bold('Pick a provider + model')}\n`);
+  process.stdout.write(`  ${dim('Opens the arrow-key picker. The list leads with gemini / openai / claude-cli — pick the one you have an account or login for.')}\n\n`);
+  await _quickPrompt('  ▶ press Enter to open the picker ');
+  try {
+    await cmdOnboard({ pick: true });
+  } catch (e) {
+    process.stderr.write(`onboard error: ${e?.message || e}\n`);
+    process.exit(1);
+  }
+  // Re-read config after onboard wrote it. If the user aborted with
+  // no provider set, bail out early — the rest of the wizard depends
+  // on a provider being configured.
+  const cfgAfterOnboard = readConfig();
+  if (!cfgAfterOnboard.provider) {
+    process.stdout.write(`\n  ${warn('Setup aborted — no provider configured. Run `lazyclaw setup` again when ready.')}\n\n`);
+    process.exit(0);
+  }
+  process.stdout.write(`\n  ${ok('✓ provider:')} ${cfgAfterOnboard.provider}  ${dim('model:')} ${cfgAfterOnboard.model || '(default)'}\n\n`);
+  // ── Step 2: Optional workspace ──────────────────────────────
+  process.stdout.write(`  ${accent('Step 2/5 ·')} ${bold('Initialise a workspace?')} ${dim('(optional)')}\n`);
+  process.stdout.write(`  ${dim('A workspace is a folder of AGENTS.md / SOUL.md / TOOLS.md prompt files that auto-inject into chat / agent. Skip if you don\'t need project-specific personas yet.')}\n\n`);
+  const wsName = (await _quickPrompt('  workspace name (Enter to skip): ')).trim();
+  if (wsName && /^[A-Za-z0-9_.-]+$/.test(wsName)) {
+    try {
+      const ws = await import('./workspace.mjs');
+      const dir = ws.initWorkspace(cfgDir, wsName);
+      process.stdout.write(`  ${ok('✓ workspace created:')} ${dir}\n`);
+      process.stdout.write(`  ${dim('Edit AGENTS.md / SOUL.md / TOOLS.md any time. Use with: lazyclaw chat --workspace ' + wsName)}\n\n`);
+    } catch (e) {
+      process.stdout.write(`  ${warn('skipped:')} ${e?.message || e}\n\n`);
+    }
+  } else if (wsName) {
+    process.stdout.write(`  ${warn('skipped:')} workspace name must match [A-Za-z0-9_.-]+\n\n`);
+  } else {
+    process.stdout.write(`  ${dim('— skipped —')}\n\n`);
+  }
+  // ── Step 3: Optional skill bundle install ───────────────────
+  process.stdout.write(`  ${accent('Step 3/5 ·')} ${bold('Install a skill bundle from GitHub?')} ${dim('(optional)')}\n`);
+  process.stdout.write(`  ${dim('Format: <user>/<repo>[@<ref>]. Skills are .md prompt fragments that compose into the system prompt via --skill.')}\n\n`);
+  const skillSpec = (await _quickPrompt('  github spec (Enter to skip): ')).trim();
+  if (skillSpec) {
+    try {
+      const inst = await import('./skills_install.mjs');
+      const r = await inst.installFromGithub(skillSpec, cfgDir, { force: false });
+      process.stdout.write(`  ${ok('✓ installed')} ${r.installed.length} ${dim('skill(s) from')} ${skillSpec}\n`);
+      r.installed.forEach((s) => process.stdout.write(`    · ${s.name} ${dim(`(${s.bytes} bytes)`)}\n`));
+      if (r.skipped.length) {
+        process.stdout.write(`  ${dim('skipped (already installed):')} ${r.skipped.map((s) => s.name).join(', ')}\n`);
+      }
+      process.stdout.write('\n');
+    } catch (e) {
+      process.stdout.write(`  ${warn('skipped:')} ${e?.message || e}\n\n`);
+    }
+  } else {
+    process.stdout.write(`  ${dim('— skipped —')}\n\n`);
+  }
+  // ── Step 4: Optional outbound webhook ───────────────────────
+  process.stdout.write(`  ${accent('Step 4/5 ·')} ${bold('Add an outbound webhook?')} ${dim('(optional)')}\n`);
+  process.stdout.write(`  ${dim('Use with: lazyclaw message send <name> <text>. Slack / Discord Incoming Webhook URLs work as-is.')}\n\n`);
+  const hookName = (await _quickPrompt('  webhook name (Enter to skip): ')).trim();
+  if (hookName) {
+    const hookUrl = (await _quickPrompt('  webhook URL: ')).trim();
+    if (!hookUrl) {
+      process.stdout.write(`  ${warn('skipped:')} URL required\n\n`);
+    } else {
+      try {
+        const cf = await import('./config_features.mjs');
+        const fresh = readConfig();
+        cf.messageAdd(fresh, hookName, hookUrl);
+        writeConfig(fresh);
+        process.stdout.write(`  ${ok('✓ webhook saved:')} ${hookName}\n\n`);
+      } catch (e) {
+        process.stdout.write(`  ${warn('skipped:')} ${e?.message || e}\n\n`);
+      }
+    }
+  } else {
+    process.stdout.write(`  ${dim('— skipped —')}\n\n`);
+  }
+  // ── Step 5: Reachability check ──────────────────────────────
+  process.stdout.write(`  ${accent('Step 5/5 ·')} ${bold('Verify the picked provider responds')}\n`);
+  process.stdout.write(`  ${dim('Sends a 1-token "ping" via `lazyclaw providers test`. Confirms your key / subscription / local daemon is wired up.')}\n\n`);
+  const wantPing = !flags['skip-test'] && (await _quickPrompt('  test now? [Y/n] ')).trim().toLowerCase() !== 'n';
+  if (wantPing) {
+    try {
+      // Reuse the existing providers-test path so behaviour matches
+      // a manual `lazyclaw providers test`.
+      await cmdProviders('test', [cfgAfterOnboard.provider], {});
+    } catch (e) {
+      process.stdout.write(`  ${warn('test errored:')} ${e?.message || e}\n`);
+      process.stdout.write(`  ${dim('Setup still completed; you can retry with:')} lazyclaw providers test ${cfgAfterOnboard.provider}\n`);
+    }
+  } else {
+    process.stdout.write(`  ${dim('— skipped —')}\n`);
+  }
+  // ── Wrap up ─────────────────────────────────────────────────
+  process.stdout.write('\n');
+  process.stdout.write(`  ${ok(bold('🎉 Setup complete.'))}\n`);
+  process.stdout.write(`  ${dim('Run')} ${bold('lazyclaw')} ${dim('any time to open the menu, or jump in directly:')}\n`);
+  process.stdout.write(`    ${dim('•')} lazyclaw chat                ${dim('— REPL with the configured provider')}\n`);
+  process.stdout.write(`    ${dim('•')} lazyclaw agent "..."          ${dim('— one-shot prompt')}\n`);
+  process.stdout.write(`    ${dim('•')} lazyclaw doctor              ${dim('— diagnostic JSON')}\n`);
+  process.stdout.write(`    ${dim('•')} lazyclaw setup               ${dim('— re-run this wizard any time')}\n\n`);
+}
 // First-run welcome panel + delegated onboard. Drawn once before the
 // main launcher menu when the config has no provider yet. Walks the
 // user through the same arrow-key picker that `lazyclaw onboard`
@@ -3093,16 +3521,7 @@ async function _runFirstTimeOnboard() {
   const dim    = (s) => `\x1b[2m${s}\x1b[0m`;
   const bold   = (s) => `\x1b[1m${s}\x1b[0m`;
   process.stdout.write('\x1b[2J\x1b[H');
-  const banner = [
-    accent('  ╭──────────────────────────────╮'),
-    accent('  │   _                          │'),
-    accent('  │  | |__ _ _____  _ _          │'),
-    accent('  │  | / _` |_ / || | \'_|         │'),
-    accent('  │  |_\\__,_/__\\_, |_|            │'),
-    accent('  │  LazyClaw  |__/  ' + (readVersionFromRepo() || '').padEnd(10) + '  │'),
-    accent('  ╰──────────────────────────────╯'),
-  ];
-  banner.forEach((l) => process.stdout.write(l + '\n'));
+  _renderBanner(readVersionFromRepo()).forEach((l) => process.stdout.write(l + '\n'));
   process.stdout.write('\n');
   process.stdout.write(`  ${bold('👋 Welcome — first-time setup')}\n\n`);
   process.stdout.write(`  ${dim('No provider configured yet at')} ${configPath()}\n`);
@@ -3124,31 +3543,46 @@ async function _runFirstTimeOnboard() {
   process.stdout.write('\n');
 }
+// Direct dispatch from a launcher pick. Replaces the previous
+// `process.argv = [...]; await main()` round-trip so we can reuse
+// the launcher across multiple iterations without compounding
+// state. Each menu choice maps to its native cmd handler with the
+// same flag defaults the bare CLI would parse.
+async function _dispatchMenuChoice(argv) {
+  const sub = argv[0];
+  const rest = argv.slice(1);
+  switch (sub) {
+    case 'chat':       return cmdChat({});
+    case 'agent':      return cmdAgent(rest[0] || '-', {});
+    case 'onboard':    return cmdOnboard({});
+    case 'setup':      return cmdSetup(undefined, rest, {});
+    case 'workspace':  return cmdWorkspace(rest[0], rest.slice(1), {});
+    case 'browse':     return cmdBrowse(rest[0], {});
+    case 'skills':     return cmdSkills(rest[0], rest.slice(1), {});
+    case 'sessions':   return cmdSessions(rest[0], rest.slice(1), {});
+    case 'providers':  return cmdProviders(rest[0], rest.slice(1), {});
+    case 'cron':       return cmdCron(rest[0], rest.slice(1), {});
+    case 'auth':       return cmdAuth(rest[0], rest.slice(1), {});
+    case 'pairing':    return cmdPairing(rest[0], rest.slice(1), {});
+    case 'nodes':      return cmdNodes(rest[0], rest.slice(1), {});
+    case 'message':    return cmdMessage(rest[0], rest.slice(1), {});
+    case 'doctor':     return cmdDoctor();
+    case 'status':     return cmdStatus();
+    case 'help':       return cmdHelp();
+    case 'dashboard':  return cmdDashboard({});
+    default:           throw new Error(`unknown menu choice: ${sub}`);
+  }
+}
 async function cmdLauncher() {
   await ensureRegistry();
-  let cfg = readConfig();
-  // First-run guard: a fresh install has no `provider` set, so any
-  // menu pick that calls a provider (Chat / Agent / Doctor / etc.)
-  // would error halfway through with a confusing "missing api key"
-  // or "unknown provider". Detect that state up front and walk the
-  // user through onboard before showing the menu — once they've
-  // picked, re-read the config and continue normally.
-  if (!cfg.provider) {
-    await _runFirstTimeOnboard();
-    cfg = readConfig();
-    // If they cancelled / aborted onboard we still don't have a
-    // provider — drop straight out instead of showing a menu where
-    // every item leads to the same error.
-    if (!cfg.provider) {
-      process.stdout.write('\n  Setup not completed — exiting.\n  Run `lazyclaw onboard` when ready, then try `lazyclaw` again.\n\n');
-      process.exit(0);
-    }
-  }
-  const provider = cfg.provider;
-  const model = cfg.model || '(default)';
+  // Item table is fixed across iterations — only the dispatcher and
+  // the per-iteration draw redraw on each loop tick.
   const items = [
     { id: 'chat',      label: 'Chat',          desc: 'interactive REPL with the configured provider', argv: ['chat'] },
     { id: 'agent',     label: 'Agent',         desc: 'one-shot prompt — read text and exit',           argv: ['agent'], promptForBody: true },
+    { id: 'dashboard', label: 'Dashboard',     desc: 'open the lazyclaw web UI in your browser',       argv: ['dashboard'] },
+    { id: 'setup',     label: 'Setup',         desc: 'multi-step provider / workspace / skill wizard', argv: ['setup'] },
     { id: 'onboard',   label: 'Onboard',       desc: 'pick provider / model / api-key',                argv: ['onboard'] },
     { id: 'workspace', label: 'Workspace',     desc: 'AGENTS.md / SOUL.md / TOOLS.md prompt bundles',  argv: ['workspace', 'list'] },
     { id: 'browse',    label: 'Browse',        desc: 'fetch a URL → markdown',                         argv: ['browse'], promptForUrl: true },
@@ -3159,106 +3593,131 @@ async function cmdLauncher() {
     { id: 'doctor',    label: 'Doctor',        desc: 'diagnostic — config, providers, workflows',     argv: ['doctor'] },
     { id: 'status',    label: 'Status',        desc: 'current provider / model / masked key',          argv: ['status'] },
     { id: 'help',      label: 'Help',          desc: 'one-line summary of every subcommand',           argv: ['help'] },
-    { id: 'quit',      label: 'Quit',          desc: 'exit without doing anything',                    argv: null },
+    { id: 'quit',      label: 'Quit',          desc: 'exit lazyclaw',                                  argv: null },
   ];
-  const readline = await import('node:readline');
-  readline.emitKeypressEvents(process.stdin);
-  if (process.stdin.setRawMode) process.stdin.setRawMode(true);
-  let idx = 0;
-  // Pretty header — same accent palette as _printChatBanner so
-  // returning users recognise it.
   const accent = (s) => `\x1b[38;5;208m${s}\x1b[0m`;
   const dim    = (s) => `\x1b[2m${s}\x1b[0m`;
   const bold   = (s) => `\x1b[1m${s}\x1b[0m`;
   const ok     = (s) => `\x1b[32m${s}\x1b[0m`;
   const warn   = (s) => `\x1b[33m${s}\x1b[0m`;
-  const draw = () => {
-    process.stdout.write('\x1b[?25l\x1b[2J\x1b[H'); // hide cursor + clear
-    const banner = [
-      accent('  ╭──────────────────────────────╮'),
-      accent('  │   _                          │'),
-      accent('  │  | |__ _ _____  _ _          │'),
-      accent('  │  | / _` |_ / || | \'_|         │'),
-      accent('  │  |_\\__,_/__\\_, |_|            │'),
-      accent('  │  LazyClaw  |__/  ' + (readVersionFromRepo() || '').padEnd(10) + '  │'),
-      accent('  ╰──────────────────────────────╯'),
-    ];
-    banner.forEach((l) => process.stdout.write(l + '\n'));
-    process.stdout.write('\n');
-    const provDisplay = provider === '(unset — pick during onboard)'
-      ? warn(provider)
-      : ok(provider);
-    process.stdout.write(`  ${dim('provider ·')} ${provDisplay}\n`);
-    process.stdout.write(`  ${dim('model    ·')} ${ok(model)}\n`);
-    process.stdout.write(`  ${dim('config   ·')} ${dim(configPath())}\n`);
-    process.stdout.write('\n');
-    process.stdout.write(`  ${dim('↑/↓ to move · Enter to select · q or Esc to quit')}\n\n`);
-    // Trim list to terminal height so the menu still fits when
-    // someone shrinks the window or runs in a small split pane.
-    const rowsAvail = Math.max(items.length, (process.stdout.rows || 30) - 14);
-    const fromIdx = Math.max(0, Math.min(items.length - rowsAvail, idx - Math.floor(rowsAvail / 2)));
-    const toIdx = Math.min(items.length, fromIdx + rowsAvail);
-    for (let i = fromIdx; i < toIdx; i++) {
-      const it = items[i];
-      const marker = i === idx ? accent('❯ ') : '  ';
-      const lbl = i === idx ? bold(it.label.padEnd(11)) : it.label.padEnd(11);
-      process.stdout.write(`${marker}${lbl}  ${dim(it.desc)}\n`);
+  let idx = 0;
+  // Outer loop — each iteration is one menu render → pick →
+  // dispatch round. Subcommand return drops back here and the menu
+  // is redrawn. Quit / Esc / Ctrl-C breaks the loop and returns,
+  // which lets the calling main() exit naturally (no process.exit
+  // so the buffered writer / open file descriptors close cleanly).
+  while (true) {
+    // First-run / config-missing guard: a fresh install has no
+    // `provider` set, so any menu pick that calls a provider would
+    // error halfway through. Funnel through cmdSetup before
+    // rendering the menu the first time around.
+    let cfg = readConfig();
+    if (!cfg.provider) {
+      try { await cmdSetup(undefined, [], {}); }
+      catch (e) {
+        process.stderr.write(`setup error: ${e?.message || e}\n`);
+      }
+      cfg = readConfig();
+      if (!cfg.provider) {
+        process.stdout.write('\n  Setup not completed — exiting.\n  Run `lazyclaw setup` when ready, then try `lazyclaw` again.\n\n');
+        return;
+      }
     }
-    process.stdout.write('\n');
-  };
-  // Tear down raw mode + listeners cleanly so the next subcommand
-  // starts with a sane stdin (otherwise `chat` after launcher inherits
-  // the launcher's raw mode and behaves weirdly).
-  const teardown = (onKey) => {
-    if (onKey) process.stdin.off('keypress', onKey);
-    if (process.stdin.setRawMode) process.stdin.setRawMode(false);
-    process.stdout.write('\x1b[?25h'); // show cursor
-    process.stdout.write('\x1b[2J\x1b[H'); // clear screen
-  };
+    const provider = cfg.provider;
+    const model = cfg.model || '(default)';
-  draw();
-  const picked = await new Promise((resolve) => {
-    const onKey = (_str, key) => {
-      if (!key) return;
-      if (key.name === 'up')        { idx = (idx - 1 + items.length) % items.length; draw(); }
-      else if (key.name === 'down') { idx = (idx + 1) % items.length; draw(); }
-      else if (key.name === 'home') { idx = 0; draw(); }
-      else if (key.name === 'end')  { idx = items.length - 1; draw(); }
-      else if (key.name === 'pageup')   { idx = Math.max(0, idx - 5); draw(); }
-      else if (key.name === 'pagedown') { idx = Math.min(items.length - 1, idx + 5); draw(); }
-      else if (key.name === 'return')   { teardown(onKey); resolve(items[idx]); }
-      else if (key.ctrl && key.name === 'c') { teardown(onKey); resolve({ id: 'quit', argv: null }); }
-      else if (key.name === 'escape' || key.name === 'q') { teardown(onKey); resolve({ id: 'quit', argv: null }); }
+    // Re-establish stdin in raw / ref'd mode. A previous iteration
+    // (e.g. `chat`) deliberately paused + unref'd stdin in its
+    // exit-cleanup path so the process could end on /exit; now that
+    // we want to keep going, re-attach.
+    const readline = await import('node:readline');
+    readline.emitKeypressEvents(process.stdin);
+    if (process.stdin.setRawMode) process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.ref();
+    const draw = () => {
+      process.stdout.write('\x1b[?25l\x1b[2J\x1b[H'); // hide cursor + clear
+      _renderBanner(readVersionFromRepo()).forEach((l) => process.stdout.write(l + '\n'));
+      process.stdout.write('\n');
+      process.stdout.write(`  ${dim('provider ·')} ${ok(provider)}\n`);
+      process.stdout.write(`  ${dim('model    ·')} ${ok(model)}\n`);
+      process.stdout.write(`  ${dim('config   ·')} ${dim(configPath())}\n`);
+      process.stdout.write('\n');
+      process.stdout.write(`  ${dim('↑/↓ to move · Enter to select · q or Esc to quit')}\n\n`);
+      const rowsAvail = Math.max(items.length, (process.stdout.rows || 30) - 14);
+      const fromIdx = Math.max(0, Math.min(items.length - rowsAvail, idx - Math.floor(rowsAvail / 2)));
+      const toIdx = Math.min(items.length, fromIdx + rowsAvail);
+      for (let i = fromIdx; i < toIdx; i++) {
+        const it = items[i];
+        const marker = i === idx ? accent('❯ ') : '  ';
+        const lbl = i === idx ? bold(it.label.padEnd(11)) : it.label.padEnd(11);
+        process.stdout.write(`${marker}${lbl}  ${dim(it.desc)}\n`);
+      }
+      process.stdout.write('\n');
     };
-    process.stdin.on('keypress', onKey);
-  });
-  if (!picked || !picked.argv) {
-    process.exit(0);
+    draw();
+    const picked = await new Promise((resolve) => {
+      const onKey = (_str, key) => {
+        if (!key) return;
+        if (key.name === 'up')        { idx = (idx - 1 + items.length) % items.length; draw(); }
+        else if (key.name === 'down') { idx = (idx + 1) % items.length; draw(); }
+        else if (key.name === 'home') { idx = 0; draw(); }
+        else if (key.name === 'end')  { idx = items.length - 1; draw(); }
+        else if (key.name === 'pageup')   { idx = Math.max(0, idx - 5); draw(); }
+        else if (key.name === 'pagedown') { idx = Math.min(items.length - 1, idx + 5); draw(); }
+        else if (key.name === 'return')   { cleanup(); resolve(items[idx]); }
+        else if (key.ctrl && key.name === 'c') { cleanup(); resolve({ id: 'quit', argv: null }); }
+        else if (key.name === 'escape' || key.name === 'q') { cleanup(); resolve({ id: 'quit', argv: null }); }
+        function cleanup() {
+          process.stdin.off('keypress', onKey);
+          if (process.stdin.setRawMode) process.stdin.setRawMode(false);
+          process.stdout.write('\x1b[?25h\x1b[2J\x1b[H');
+        }
+      };
+      process.stdin.on('keypress', onKey);
+    });
+    if (!picked || picked.id === 'quit' || !picked.argv) {
+      // Plain return so main() can exit naturally.
+      return;
+    }
+    // Two menu items need a follow-up question before they can run:
+    // agent (prompt body), browse (URL). Ask once, then dispatch.
+    let argv = picked.argv;
+    if (picked.promptForBody) {
+      const body = await _quickPrompt('prompt: ');
+      if (!body) continue; // back to menu
+      argv = ['agent', body];
+    } else if (picked.promptForUrl) {
+      const url = await _quickPrompt('url: ');
+      if (!url) continue; // back to menu
+      argv = ['browse', url];
+    }
+    // Dispatch. Errors don't terminate the launcher — they're
+    // surfaced as a stderr line and the menu redraws. Lets the
+    // user recover from a transient API hiccup without a relaunch.
+    try {
+      await _dispatchMenuChoice(argv);
+    } catch (e) {
+      process.stderr.write(`\n  ${accent('✗')} ${e?.message || String(e)}\n`);
+    }
+    // Pause before re-drawing so the user can read the subcommand's
+    // output. `chat` is the special case: its REPL has already kept
+    // the user oriented for a long session, and they typed /exit
+    // explicitly, so jumping straight back to the menu reads as
+    // "ok, done with that conversation, back to the dashboard."
+    if (picked.id !== 'chat') {
+      process.stdout.write('\n');
+      await _quickPrompt(`  ${dim('Press Enter to return to the menu… ')}`);
+    }
   }
-  // Two surfaces need a follow-up question before they can run:
-  // - `agent`: needs a prompt body
-  // - `browse`: needs a URL
-  // Ask via a simple readline prompt so the launcher stays
-  // self-contained instead of forwarding into a half-typed argv.
-  if (picked.promptForBody) {
-    const body = await _quickPrompt('prompt: ');
-    if (!body) process.exit(0);
-    picked.argv = ['agent', body];
-  } else if (picked.promptForUrl) {
-    const url = await _quickPrompt('url: ');
-    if (!url) process.exit(0);
-    picked.argv = ['browse', url];
-  }
-  // Replace argv and re-enter main(). The chosen subcommand sees
-  // the same parser surface as if the user had typed it directly.
-  process.argv = [process.argv[0], process.argv[1], ...picked.argv];
-  await main();
 }
 async function _quickPrompt(label) {
@@ -3444,6 +3903,14 @@ async function main() {
       await cmdCron(sub, rest.positional.slice(1), rest.flags);
       break;
     }
+    case 'setup': {
+      await cmdSetup(undefined, rest.positional, rest.flags);
+      break;
+    }
+    case 'dashboard': {
+      await cmdDashboard(rest.flags);
+      break;
+    }
     case 'daemon': {
       await cmdDaemon(rest.flags);
       break;