lazyclaw 3.88.0 → 3.99.3

package/cli.mjs

@@ -28,6 +28,20 @@ function writeConfig(cfg) {
   fs.writeFileSync(p, JSON.stringify(cfg, null, 2));
 }
 
+// Synchronous, dependency-free resolver for the api-key the
+// chat / agent flow sends. Mirrors config_features.resolveApiKey
+// without forcing the dynamic import on every hot-path call.
+//   1. cfg.authProfiles[provider] active label, if set
+//   2. first profile in the array
+//   3. legacy single `cfg["api-key"]` (pre-v3.93 configs)
+function _resolveAuthKey(cfg, provider) {
+  const arr = (cfg.authProfiles || {})[provider] || [];
+  const active = (cfg.authActiveProfile || {})[provider];
+  const hit = arr.find((p) => p && p.label === active) || arr[0];
+  if (hit?.key) return hit.key;
+  return cfg['api-key'] || '';
+}
+
 async function importWorkflow(file) {
   const abs = path.resolve(file);
   const url = pathToFileURL(abs).href;
@@ -678,12 +692,39 @@ async function cmdOnboard(flags) {
   if (!flags['non-interactive']) {
     // Interactive onboarding is a single guided prompt sequence — kept tiny.
     // For automation always use --non-interactive plus the value flags.
+    // Skip the prompts entirely when the user passed --pick (or no
+    // provider yet AND we're on a TTY) so they get the full picker.
+    const wantPicker = !!flags.pick;
+    if (wantPicker || (!flags.provider && process.stdin.isTTY)) {
+      const picked = await _pickProviderInteractive();
+      if (picked) {
+        flags.provider = flags.provider || picked.provider;
+        if (picked.model && !flags.model) flags.model = picked.model;
+      }
+    }
     const readline = await import('node:readline');
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     const ask = q => new Promise(resolve => rl.question(q, resolve));
-    flags.provider = flags.provider || (await ask('provider [mock|anthropic]: ')).trim();
-    flags.model = flags.model || (await ask('model (or "anthropic/claude-opus-4-7"): ')).trim();
-    flags['api-key'] = flags['api-key'] || (await ask('api-key (leave blank for mock): ')).trim();
+    if (!flags.provider) {
+      const provs = Object.keys(_registryMod.PROVIDERS).join('|');
+      const noKeyHint = '\x1b[38;5;208mclaude-cli\x1b[0m (subscription, no key) is the default';
+      process.stdout.write(`hint: ${noKeyHint}\n`);
+      flags.provider = (await ask(`provider [${provs}]: `)).trim() || 'claude-cli';
+    }
+    if (!flags.model) {
+      const meta = (_registryMod.PROVIDER_INFO || {})[flags.provider] || {};
+      const sample = (meta.suggestedModels || []).slice(0, 4).join(' · ') || '(any)';
+      const dflt = meta.defaultModel || '';
+      flags.model = (await ask(`model (e.g. ${sample}) [${dflt}]: `)).trim() || dflt;
+    }
+    // Only ask for api-key when the picked provider actually needs one.
+    // claude-cli / ollama / mock all skip this — that's the whole point
+    // of supporting them.
+    const meta = (_registryMod.PROVIDER_INFO || {})[flags.provider] || {};
+    if (meta.requiresApiKey && !flags['api-key']) {
+      const prefix = meta.keyPrefix ? ` (starts with "${meta.keyPrefix}")` : '';
+      flags['api-key'] = (await ask(`api-key${prefix}: `)).trim();
+    }
     rl.close();
   }
   const next = applyOnboardConfig(readConfig(), flags);
@@ -697,7 +738,11 @@ async function cmdDoctor() {
   const cfg = readConfig();
   const issues = [];
   if (!cfg.provider) issues.push('config.provider is missing — run `lazyclaw onboard`');
-  if (cfg.provider && cfg.provider !== 'mock' && !cfg['api-key']) {
+  // Only flag a missing api-key when the picked provider actually
+  // requires one. claude-cli / ollama / mock all run keylessly, so the
+  // previous `provider !== 'mock'` check produced false positives.
+  const _meta = (_registryMod.PROVIDER_INFO || {})[cfg.provider] || {};
+  if (cfg.provider && _meta.requiresApiKey && !cfg['api-key']) {
     issues.push(`config['api-key'] is missing for provider "${cfg.provider}"`);
   }
   if (cfg.provider && !PROVIDERS_HAS(_registryMod.PROVIDERS, cfg.provider)) {
@@ -830,6 +875,8 @@ const SUBCOMMANDS = [
   'daemon', 'version', 'completion', 'help',
   'export', 'import',
   'rates',
+  // OpenClaw-parity subsurfaces (v3.93–v3.98)
+  'auth', 'pairing', 'nodes', 'message', 'workspace', 'browse', 'cron',
 ];
 
 const SUBCOMMAND_SUBS = {
@@ -839,6 +886,12 @@ const SUBCOMMAND_SUBS = {
   providers: ['list', 'info', 'test'],
   rates:     ['list', 'set', 'delete', 'shape', 'validate', 'copy'],
   completion: ['bash', 'zsh'],
+  auth:      ['list', 'add', 'remove', 'use', 'rotate'],
+  pairing:   ['list', 'add', 'remove'],
+  nodes:     ['list', 'register', 'remove'],
+  message:   ['list', 'add', 'remove', 'send'],
+  workspace: ['list', 'init', 'show', 'remove', 'path'],
+  cron:      ['list', 'add', 'remove', 'show', 'sync', 'run'],
 };
 
 function bashCompletion() {
@@ -1047,6 +1100,13 @@ const HELP_SUMMARIES = {
   export:     'Dump config + skills (+ optional sessions) as a JSON bundle',
   import:     'Apply a JSON bundle from stdin or --from <path>',
   rates:      'Manage cost rate-cards in config (rates list|set <provider/model>|delete|shape)',
+  auth:       'Multiple keys per provider (auth list|add|remove|use|rotate <provider>)',
+  pairing:    'Sender allowlist for the messaging surface (pairing list|add|remove <id>)',
+  nodes:      'Companion device registration (nodes list|register|remove <id>)',
+  message:    'Outbound webhook messaging (message list|add|remove|send <name>)',
+  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)',
   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',
@@ -1063,13 +1123,13 @@ const HELP_DETAILS = {
   validate: 'Usage: lazyclaw validate <workflow.mjs>\n  Static check: load + shape + dep + cycle + parallelism estimate.\n  Exit 0 valid · 1 hard failure (issues populated) · 2 file/import error.',
   graph: 'Usage: lazyclaw graph <workflow.mjs> [--lr] [--state <session-id>] [--dir <state-dir>]\n  Emit the workflow DAG as Mermaid syntax (graph TD by default; --lr for left-right).\n  --state overlays a persisted run\'s status (success ✓ / running ⏳ / failed ✗ / pending) with classDef styling.\n  Output is paste-ready for GitHub markdown / Notion / Obsidian.',
   config: 'Usage: lazyclaw config <get|set|list|delete|path|edit|validate> [key] [value]\n  Local key-value config at $LAZYCLAW_CONFIG_DIR/config.json (default ~/.lazyclaw).\n  `path` prints the file location; `edit` opens it in $EDITOR (or $LAZYCLAW_EDITOR / $VISUAL / vi) and validates JSON on save.\n  `validate` checks the structural integrity of the whole config file (typed values, known providers, rate-card shape).',
-  chat: 'Usage: lazyclaw chat [--session <id>] [--skill name1,name2] [--pick]\n  --session persists turns to <configDir>/sessions/<id>.jsonl across invocations.\n  --skill composes named skills into a system message at the head of the conversation.\n  --pick opens an interactive provider/model picker before the prompt (also auto-fires on first run).',
-  agent: 'Usage: lazyclaw agent <prompt|-> [--provider X] [--model Y] [--skill list] [--thinking N] [--show-thinking] [--usage] [--cost]\n  One-shot non-interactive call. Pass "-" as the prompt to read from stdin.\n  --usage prints normalized {inputTokens, outputTokens, ...} to stderr after the response.\n  --cost adds a cost line on stderr when config.rates has a card for the active provider/model.',
+  chat: 'Usage: lazyclaw chat [--session <id>] [--skill name1,name2] [--workspace <name>] [--pick] [--sandbox docker:<image>] [--sandbox-network <net>] [--sandbox-mount <m>] [--sandbox-env <e>]\n  --session persists turns to <configDir>/sessions/<id>.jsonl across invocations.\n  --skill composes named skills into a system message at the head of the conversation.\n  --workspace stitches AGENTS.md/SOUL.md/TOOLS.md from <configDir>/workspaces/<name>/ into the system prompt.\n  --pick opens an interactive provider/model picker before the prompt (also auto-fires on first run).\n  --sandbox routes the underlying claude CLI through `docker run --rm -i --network <net> -v cwd:cwd ...` (default --network=none).',
+  agent: 'Usage: lazyclaw agent <prompt|-> [--provider X] [--model Y] [--skill list] [--workspace <name>] [--thinking N] [--show-thinking] [--usage] [--cost] [--sandbox docker:<image>]\n  One-shot non-interactive call. Pass "-" as the prompt to read from stdin.\n  --workspace stitches AGENTS.md/SOUL.md/TOOLS.md into the system prompt (combines with --skill).\n  --usage prints normalized {inputTokens, outputTokens, ...} to stderr after the response.\n  --cost adds a cost line on stderr when config.rates has a card for the active provider/model.\n  --sandbox docker:<image> wraps the subprocess provider (claude-cli) in a Docker container; --sandbox-network defaults to none.',
   doctor: 'Usage: lazyclaw doctor\n  Validates configuration and registered providers. Exits 0 only when no issues.',
   status: 'Usage: lazyclaw status\n  Provider, model, and masked API key. Never prints the raw key.',
   onboard: 'Usage: lazyclaw onboard [--non-interactive] [--provider X] [--model Y] [--api-key Z]\n  --model accepts the unified "provider/model" string (e.g. anthropic/claude-opus-4-7).',
   sessions: 'Usage: lazyclaw sessions <list [--filter <substr>] [--limit <N>]|show <id>|clear <id>|export <id> [--format md|json|text]|search <query> [--regex]>\n  list — recent sessions by mtime; --filter caps to ids containing substring (case-insensitive); --limit caps result count.\n  export — render in chosen format (md default for human sharing, json for tooling, text for paste).\n  search — case-insensitive substring (or --regex pattern) match across all session content; returns first excerpt + match count per matching session.',
-  skills: 'Usage: lazyclaw skills <list [--filter <substr>] [--limit <N>]|show <name>|install <name> [--from <path> | --from-url <https://...>]|remove <name>|search <query> [--regex]>\n  list — installed skills; --filter caps to names containing substring (case-insensitive); --limit caps result count.\n  --from-url fetches over HTTPS only; 1 MiB body cap.\n  search — case-insensitive substring (or --regex) match across all skill markdown bodies; returns first excerpt + match count per skill.',
+  skills: 'Usage: lazyclaw skills <list [--filter <substr>] [--limit <N>]|show <name>|install <user/repo[@ref][:path]> [--prefix <p>] [--force] | install <name> [--from <path> | --from-url <https://...>]|remove <name>|search <query> [--regex]>\n  list — installed skills; --filter caps to names containing substring (case-insensitive); --limit caps result count.\n  install <user>/<repo>[@<ref>][:<subpath>] — fetch a GitHub tarball, install every .md under skills/ (or the explicit subpath, or repo root). Default ref is `main`.\n    --prefix prepends a name prefix so a multi-skill repo doesn\'t collide with locally-managed skills. --force overwrites existing names.\n  install <name> --from <path> | --from-url <https://...> — single-file install. --from-url is HTTPS-only with a 1 MiB cap.\n  search — case-insensitive substring (or --regex) match across all skill markdown bodies; returns first excerpt + match count per skill.',
   providers: 'Usage: lazyclaw providers <list [--filter <substr>] [--limit <N>] | info <name> | test <name> [--model X] [--prompt T] | test [--all] [--prompt T]>\n  list — registered providers (--filter case-insensitive name substring; --limit caps post-filter count).\n  info — static metadata: requiresApiKey, defaultModel, suggestedModels, endpoint.\n  test — send a 1-token "ping" through the provider and report ok/error + duration.\n         Useful after configuring an API key to verify it works before relying on it.\n         No name OR --all: tests every registered provider in parallel; exits 0 only when ALL pass.',
   daemon: 'Usage: lazyclaw daemon [--port <N>] [--once] [--auth-token <token>] [--allow-origin <origin>] [--rate-limit <N>] [--response-cache] [--log <level>] [--shutdown-timeout-ms <N>] [--cost-cap-<currency> <N> ...] [--workflow-state-dir <dir>]\n  Always binds 127.0.0.1. --port 0 picks a random port and prints the URL.\n  --auth-token also reads $LAZYCLAW_AUTH_TOKEN; --allow-origin also reads $LAZYCLAW_ALLOW_ORIGINS.\n  --rate-limit <N> caps each remote IP at N requests / 60 s.\n  --response-cache enables process-scoped memoization; per-request opt-in via body.cache.\n  --log <debug|info|warn|error> emits JSON-line access logs on stderr (also reads $LAZYCLAW_LOG_LEVEL).\n  --shutdown-timeout-ms <N> caps graceful drain on SIGINT/SIGTERM (default 10000). Second signal forces immediate exit.\n  --cost-cap-usd 100 (or any currency code in lowercase) rejects POST /agent + /chat with 402 once cumulative cost reaches the cap.\n  --workflow-state-dir <dir> backs GET /workflows + GET /workflows/<id> (default .workflow-state, also reads $LAZYCLAW_WORKFLOW_STATE_DIR).',
   version: 'Usage: lazyclaw version\n  Aliases: --version, -v.',
@@ -1077,6 +1137,13 @@ const HELP_DETAILS = {
   export: 'Usage: lazyclaw export [--include-secrets] [--include-sessions] > bundle.json\n  --include-secrets keeps the raw api-key in the bundle (default redacts it).\n  --include-sessions adds full turn content (default keeps metadata only).',
   import: 'Usage: lazyclaw import [--from <path>] [--overwrite-skills] [--no-overwrite-config] [--import-sessions]\n  Reads JSON from stdin (or --from <path>). Sessions are NEVER overwritten.\n  Redacted api-keys (***REDACTED***) are dropped, never written.',
   rates: 'Usage: lazyclaw rates <list [--filter <substr>] [--limit <N>] | set <provider/model> --input <N> --output <N> [--cache-read <N>] [--cache-create <N>] [--currency USD] | delete <key> | shape | validate | copy <src> <dst> [--force]>\n  Rates are per million tokens. costFromUsage uses cfg.rates to compute the cost block in /usage and body.cost.\n  `list` accepts --filter (case-insensitive key substring) and --limit (post-filter cap), same shape sessions/skills/workflows lists use.\n  `shape` prints the reference template (zero-filled) you can copy into config.\n  `validate` checks the cfg.rates shape: required fields, non-negative numbers, known providers (warn-only).\n  `copy` clones an existing card to a new key (use when a new model launches at the same price as an old one).',
+  auth: 'Usage: lazyclaw auth <list <provider> | add <provider> <key> [--label <name>] | remove <provider> <label> | use <provider> <label> | rotate <provider>>\n  Multiple keys per provider for rate-limit rotation. The active label is sent on every chat / agent call.\n  `rotate` advances the cursor to the next label; pair with a 429 hook for auto-failover.',
+  pairing: 'Usage: lazyclaw pairing <list | add <id> [--label <name>] | remove <id>>\n  Sender allowlist for the messaging surface. Inbound senders not on this list are rejected.\n  Sender ids are opaque per-channel: Slack member id, Discord user id, phone number for SMS, etc.',
+  nodes: 'Usage: lazyclaw nodes <list | register <id> [--platform macos|ios|android|web|cli] [--label <name>] | remove <id>>\n  Companion device registration table. CLI only — the actual mobile / menu-bar apps are out of scope here.\n  Platform is free-form lower-case; future surfaces (iOS / Android nodes) authenticate against the daemon using these ids.',
+  message: 'Usage: lazyclaw message <list | add <name> <webhook-url> [--kind slack|discord|generic] | remove <name> | send <name> <text>>\n  Outbound webhook messaging — Slack / Discord Incoming Webhooks. Auto-detects kind from the URL pattern.\n  send accepts a literal string, or `-` to read the body from stdin.',
+  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).',
 };
 
 function cmdHelp(name) {
@@ -1140,11 +1207,27 @@ async function cmdAgent(prompt, flags) {
   // Defaults from config.skills (same shape) if --skill not passed.
   const skillNames = (flags.skill ? String(flags.skill) : (Array.isArray(cfg.skills) ? cfg.skills.join(',') : ''))
     .split(',').map(s => s.trim()).filter(Boolean);
-  let systemPrompt = null;
+  // --workspace <name> stitches AGENTS.md / SOUL.md / TOOLS.md from
+  // <configDir>/workspaces/<name>/ at the head of the system prompt.
+  // Workspace + skill compose: workspace block first, skill block
+  // after — same order as `lazyclaw workspace show` so the user can
+  // preview exactly what the LLM will see.
+  const workspaceName = flags.workspace || cfg.workspace || '';
+  const promptParts = [];
+  if (workspaceName) {
+    try {
+      const ws = await import('./workspace.mjs');
+      const wsPrompt = ws.composeWorkspacePrompt(path.dirname(configPath()), workspaceName);
+      if (wsPrompt) promptParts.push(wsPrompt);
+    } catch (e) { console.error(`workspace error: ${e.message}`); process.exit(2); }
+  }
   if (skillNames.length > 0) {
-    try { systemPrompt = skillsMod.composeSystemPrompt(skillNames, path.dirname(configPath())); }
-    catch (e) { console.error(`skill error: ${e.message}`); process.exit(2); }
+    try {
+      const skillPrompt = skillsMod.composeSystemPrompt(skillNames, path.dirname(configPath()));
+      if (skillPrompt) promptParts.push(skillPrompt);
+    } catch (e) { console.error(`skill error: ${e.message}`); process.exit(2); }
   }
+  const systemPrompt = promptParts.length ? promptParts.join('\n\n---\n\n') : null;
 
   let text = prompt;
   if (text === '-' || text === undefined) {
@@ -1182,10 +1265,24 @@ async function cmdAgent(prompt, flags) {
     const ratesMod = await import('./providers/rates.mjs');
     costFromUsage = ratesMod.costFromUsage;
   }
+  // --sandbox docker:<image> routes the underlying subprocess
+  // (currently only the claude-cli provider hits this branch)
+  // through `docker run`. parseSandboxSpec returns null when the
+  // flag is absent / "off" so the no-flag path is bit-identical.
+  let sandboxSpec = null;
+  if (flags.sandbox) {
+    const sb = await import('./sandbox.mjs');
+    try { sandboxSpec = sb.parseSandboxSpec(flags.sandbox, flags); }
+    catch (e) { console.error(`error: ${e.message}`); process.exit(2); }
+    if (sandboxSpec && provName !== 'claude-cli') {
+      process.stderr.write(`warn: --sandbox only wraps subprocess providers; ${provName} ignores it\n`);
+    }
+  }
   try {
     for await (const chunk of prov.sendMessage(messages, {
-      apiKey: cfg['api-key'],
+      apiKey: _resolveAuthKey(cfg, provName),
       model: flags.model || cfg.model,
+      sandbox: sandboxSpec,
       thinking: thinkingBudget > 0 ? { enabled: true, budgetTokens: thinkingBudget } : undefined,
       onThinking: showThinking ? t => process.stderr.write(t) : undefined,
       onUsage: (showUsage || showCost) ? (u) => {
@@ -1215,7 +1312,12 @@ 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) {
-  if (!process.stdout.isTTY) return;
+  // 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 () => {};
   const cmds = SLASH_COMMANDS.map((c) => c.cmd);
   let lastGhost = '';
   // Find the longest match for the current input. Returns '' when
@@ -1277,7 +1379,15 @@ function _attachGhostAutocomplete(rl) {
   process.stdin.on('keypress', onKeypress);
   // Clear ghost on each new prompt so a stale dim hint doesn't carry
   // over between turns.
-  rl.on('line', () => { lastGhost = ''; });
+  const onLine = () => { lastGhost = ''; };
+  rl.on('line', onLine);
+  return () => {
+    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 (_) {}
+  };
 }
 
 // LazyClaw banner — printed once at the top of every interactive chat
@@ -1315,15 +1425,23 @@ function _printChatBanner(activeProvName, activeModel, version) {
 async function _pickProviderInteractive() {
   const providers = Object.keys(_registryMod.PROVIDERS);
   if (!providers.length) return { provider: 'mock', model: null };
-  // Build the picker list: one row per provider, models surfaced inline
-  // when the provider exposes them via a `models` array (anthropic/openai/
-  // gemini/ollama do; mock doesn't).
+  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 p = _registryMod.PROVIDERS[name];
-    const ms = (p && Array.isArray(p.models) && p.models.length) ? p.models : [null];
-    for (const m of ms) {
-      items.push({ provider: name, model: m, label: m ? `${name}  ${m}` : name });
+    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 });
     }
   }
   if (!process.stdout.isTTY || !process.stdin.isTTY) {
@@ -1339,21 +1457,35 @@ async function _pickProviderInteractive() {
     });
     return { provider: ans || providers[0], model: null };
   }
+  // Default cursor: prefer claude-cli (subscription, no key) so first-
+  // time users with Claude Code already installed don't have to scroll.
+  let idx = items.findIndex(it => it.provider === 'claude-cli');
+  if (idx < 0) idx = 0;
+
   const readline = await import('node:readline');
   readline.emitKeypressEvents(process.stdin);
   if (process.stdin.setRawMode) process.stdin.setRawMode(true);
-  let idx = 0;
+  // Long lists need scrolling so the picker fits the terminal height.
+  // Reserve 6 rows for header + footer + breathing room.
   const draw = () => {
-    // Move to top of picker block, redraw rows, leave cursor at the bottom.
-    process.stdout.write('\x1b[?25l'); // hide cursor
+    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\n');
-    items.forEach((it, i) => {
+    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);
+    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);
+    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}\n`);
-    });
+      process.stdout.write(`${marker}${text}  ${it.keyTag}\n`);
+    }
+    if (to < items.length) {
+      process.stdout.write(`\x1b[2m  …(${items.length - to} more)\x1b[0m\n`);
+    }
   };
   draw();
   return await new Promise((resolve) => {
@@ -1361,6 +1493,10 @@ async function _pickProviderInteractive() {
       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 === 'pageup')   { idx = Math.max(0, idx - 10); draw(); }
+      else if (key.name === 'pagedown') { idx = Math.min(items.length - 1, idx + 10); draw(); }
+      else if (key.name === 'home') { idx = 0; draw(); }
+      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]); }
@@ -1368,8 +1504,8 @@ async function _pickProviderInteractive() {
     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');
+      process.stdout.write('\x1b[?25h');     // show cursor
+      process.stdout.write('\x1b[2J\x1b[H'); // clear screen
     };
     process.stdin.on('keypress', onKey);
   });
@@ -1417,15 +1553,26 @@ async function cmdChat(flags = {}) {
     terminal: useTerminal,
     prompt: useTerminal ? '\x1b[38;5;208m›\x1b[0m ' : '',
   });
+  let _disposeGhost = () => {};
   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.
-    _attachGhostAutocomplete(rl);
+    _disposeGhost = _attachGhostAutocomplete(rl) || (() => {});
     rl.prompt();
   }
 
+  // --sandbox docker:<image> wraps subprocess-providers (claude-cli)
+  // in a docker container. Parsed once up front so a slash-command
+  // model switch doesn't have to re-parse every turn.
+  let sandboxSpec = null;
+  if (flags.sandbox) {
+    const sb = await import('./sandbox.mjs');
+    try { sandboxSpec = sb.parseSandboxSpec(flags.sandbox, flags); }
+    catch (e) { console.error(`error: ${e.message}`); process.exit(2); }
+  }
+
   // Persistent session ID. When --session is set we hydrate prior turns from
   // <configDir>/sessions/<id>.jsonl and append every new turn back to it.
   // Without --session, chat is in-memory only (matches phase 4 behavior).
@@ -1442,18 +1589,33 @@ async function cmdChat(flags = {}) {
   // double-prepend skills that the prior invocation already added).
   const skillNames = (flags.skill ? String(flags.skill) : (Array.isArray(cfg.skills) ? cfg.skills.join(',') : ''))
     .split(',').map(s => s.trim()).filter(Boolean);
+  // --workspace <name> sits at the head of the system prompt, then
+  // any --skill block. The two compose with the same `\n---\n`
+  // separator the agent path uses, so `lazyclaw workspace show` is
+  // a faithful preview.
+  const workspaceName = flags.workspace || cfg.workspace || '';
+  const sysParts = [];
+  if (workspaceName && !messages.some(m => m.role === 'system')) {
+    try {
+      const ws = await import('./workspace.mjs');
+      const wsPrompt = ws.composeWorkspacePrompt(cfgDir, workspaceName);
+      if (wsPrompt) sysParts.push(wsPrompt);
+    } catch (e) { console.error(`workspace error: ${e.message}`); process.exit(2); }
+  }
   if (skillNames.length > 0 && !messages.some(m => m.role === 'system')) {
     try {
       const sys = skillsMod.composeSystemPrompt(skillNames, cfgDir);
-      if (sys) {
-        messages.unshift({ role: 'system', content: sys });
-        if (sessionId) sessionsMod.appendTurn(sessionId, 'system', sys, cfgDir);
-      }
+      if (sys) sysParts.push(sys);
     } catch (e) {
       console.error(`skill error: ${e.message}`);
       process.exit(2);
     }
   }
+  if (sysParts.length && !messages.some(m => m.role === 'system')) {
+    const merged = sysParts.join('\n\n---\n\n');
+    messages.unshift({ role: 'system', content: merged });
+    if (sessionId) sessionsMod.appendTurn(sessionId, 'system', merged, cfgDir);
+  }
 
   let charsSent = messages.reduce((n, m) => n + (m.role === 'user' ? String(m.content || '').length : 0), 0);
   if (sessionId && messages.length > (skillNames.length > 0 ? 1 : 0)) {
@@ -1626,7 +1788,7 @@ async function cmdChat(flags = {}) {
     }
   };
 
-  for await (const line of rl) {
+  try { for await (const line of rl) {
     const text = line.trim();
     if (!text) { if (useTerminal) rl.prompt(); continue; }
     if (text.startsWith('/')) {
@@ -1651,8 +1813,9 @@ async function cmdChat(flags = {}) {
     process.on('SIGINT', onSigint);
     try {
       for await (const chunk of prov.sendMessage(messages, {
-        apiKey: cfg['api-key'],
+        apiKey: _resolveAuthKey(cfg, activeProvName),
         model: activeModel,
+        sandbox: sandboxSpec,
         signal: turnAc.signal,
         onUsage: accumulateUsage,
       })) {
@@ -1674,6 +1837,21 @@ async function cmdChat(flags = {}) {
       process.off('SIGINT', onSigint);
     }
     if (useTerminal) rl.prompt();
+  } } finally {
+    // Clean shutdown — without this, /exit "worked" but the process
+    // 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 { rl.close(); } catch (_) {}
+    if (useTerminal && process.stdin.isTTY && process.stdin.setRawMode) {
+      try { process.stdin.setRawMode(false); } catch (_) {}
+    }
+    // process.stdin keeps the event loop alive in raw / readline mode.
+    // Pause + unref releases the hold so the process can exit cleanly
+    // from natural completion (no need for a hard process.exit).
+    try { process.stdin.pause(); } catch (_) {}
+    try { process.stdin.unref(); } catch (_) {}
   }
 }
 
@@ -1902,6 +2080,399 @@ async function cmdRates(sub, positional, flags = {}) {
   }
 }
 
+// Loads on first use to avoid paying the import cost when the user
+// only ran `lazyclaw chat` or similar; cli.mjs is already a 2700-line
+// hot path and we don't need every helper paged in.
+let _configFeatures = null;
+async function _ensureConfigFeatures() {
+  if (!_configFeatures) _configFeatures = await import('./config_features.mjs');
+  return _configFeatures;
+}
+
+async function cmdAuth(sub, positional, flags = {}) {
+  const m = await _ensureConfigFeatures();
+  const cfg = readConfig();
+  switch (sub) {
+    case undefined:
+    case 'list': {
+      const provider = positional[0];
+      if (!provider) {
+        // No provider given → return the active-label map for every
+        // provider that has at least one profile so the user can see
+        // their full auth state at once.
+        const out = {};
+        for (const p of Object.keys(cfg.authProfiles || {})) {
+          out[p] = {
+            active: (cfg.authActiveProfile || {})[p] || null,
+            profiles: m.authList(cfg, p),
+          };
+        }
+        console.log(JSON.stringify(out, null, 2));
+        return;
+      }
+      const profiles = m.authList(cfg, provider);
+      console.log(JSON.stringify({
+        provider,
+        active: (cfg.authActiveProfile || {})[provider] || null,
+        profiles,
+      }, null, 2));
+      return;
+    }
+    case 'add': {
+      const [provider, key] = positional;
+      if (!provider || !key) {
+        console.error('Usage: lazyclaw auth add <provider> <key> [--label <name>]');
+        process.exit(2);
+      }
+      try {
+        const lbl = m.authAdd(cfg, provider, key, flags.label);
+        writeConfig(cfg);
+        console.log(JSON.stringify({ ok: true, provider, label: lbl }));
+      } catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      return;
+    }
+    case 'remove': {
+      const [provider, label] = positional;
+      if (!provider || !label) {
+        console.error('Usage: lazyclaw auth remove <provider> <label>');
+        process.exit(2);
+      }
+      try { m.authRemove(cfg, provider, label); writeConfig(cfg); }
+      catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      console.log(JSON.stringify({ ok: true, provider, removed: label }));
+      return;
+    }
+    case 'use': {
+      const [provider, label] = positional;
+      if (!provider || !label) {
+        console.error('Usage: lazyclaw auth use <provider> <label>');
+        process.exit(2);
+      }
+      try { m.authUse(cfg, provider, label); writeConfig(cfg); }
+      catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      console.log(JSON.stringify({ ok: true, provider, active: label }));
+      return;
+    }
+    case 'rotate': {
+      const provider = positional[0];
+      if (!provider) {
+        console.error('Usage: lazyclaw auth rotate <provider>');
+        process.exit(2);
+      }
+      const next = m.authRotate(cfg, provider);
+      if (!next) {
+        console.error(`error: need at least 2 profiles to rotate (provider "${provider}")`);
+        process.exit(1);
+      }
+      writeConfig(cfg);
+      console.log(JSON.stringify({ ok: true, provider, active: next }));
+      return;
+    }
+    default:
+      console.error('Usage: lazyclaw auth <list|add|remove|use|rotate> ...');
+      process.exit(2);
+  }
+}
+
+async function cmdPairing(sub, positional, flags = {}) {
+  const m = await _ensureConfigFeatures();
+  const cfg = readConfig();
+  switch (sub) {
+    case undefined:
+    case 'list':
+      console.log(JSON.stringify(m.pairingList(cfg), null, 2));
+      return;
+    case 'add': {
+      const id = positional[0];
+      if (!id) {
+        console.error('Usage: lazyclaw pairing add <id> [--label <name>]');
+        process.exit(2);
+      }
+      try { m.pairingAdd(cfg, id, flags.label); writeConfig(cfg); }
+      catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      console.log(JSON.stringify({ ok: true, id }));
+      return;
+    }
+    case 'remove': {
+      const id = positional[0];
+      if (!id) {
+        console.error('Usage: lazyclaw pairing remove <id>');
+        process.exit(2);
+      }
+      try { m.pairingRemove(cfg, id); writeConfig(cfg); }
+      catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      console.log(JSON.stringify({ ok: true, removed: id }));
+      return;
+    }
+    default:
+      console.error('Usage: lazyclaw pairing <list|add|remove> ...');
+      process.exit(2);
+  }
+}
+
+async function cmdNodes(sub, positional, flags = {}) {
+  const m = await _ensureConfigFeatures();
+  const cfg = readConfig();
+  switch (sub) {
+    case undefined:
+    case 'list':
+      console.log(JSON.stringify(m.nodesList(cfg), null, 2));
+      return;
+    case 'register': {
+      const id = positional[0];
+      if (!id) {
+        console.error('Usage: lazyclaw nodes register <id> [--platform macos|ios|android|web|cli] [--label <name>]');
+        process.exit(2);
+      }
+      try { m.nodesRegister(cfg, id, flags.platform || 'cli', flags.label || ''); writeConfig(cfg); }
+      catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      console.log(JSON.stringify({ ok: true, id, platform: flags.platform || 'cli' }));
+      return;
+    }
+    case 'remove': {
+      const id = positional[0];
+      if (!id) {
+        console.error('Usage: lazyclaw nodes remove <id>');
+        process.exit(2);
+      }
+      try { m.nodesRemove(cfg, id); writeConfig(cfg); }
+      catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      console.log(JSON.stringify({ ok: true, removed: id }));
+      return;
+    }
+    default:
+      console.error('Usage: lazyclaw nodes <list|register|remove> ...');
+      process.exit(2);
+  }
+}
+
+async function cmdMessage(sub, positional, flags = {}) {
+  const m = await _ensureConfigFeatures();
+  const cfg = readConfig();
+  switch (sub) {
+    case undefined:
+    case 'list':
+      console.log(JSON.stringify(m.messageList(cfg), null, 2));
+      return;
+    case 'add': {
+      const [name, url] = positional;
+      if (!name || !url) {
+        console.error('Usage: lazyclaw message add <name> <webhook-url> [--kind slack|discord|generic]');
+        process.exit(2);
+      }
+      try { m.messageAdd(cfg, name, url, flags.kind); writeConfig(cfg); }
+      catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      console.log(JSON.stringify({ ok: true, name }));
+      return;
+    }
+    case 'remove': {
+      const name = positional[0];
+      if (!name) {
+        console.error('Usage: lazyclaw message remove <name>');
+        process.exit(2);
+      }
+      try { m.messageRemove(cfg, name); writeConfig(cfg); }
+      catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      console.log(JSON.stringify({ ok: true, removed: name }));
+      return;
+    }
+    case 'send': {
+      const [name, ...textParts] = positional;
+      if (!name) {
+        console.error('Usage: lazyclaw message send <name> <text|->');
+        process.exit(2);
+      }
+      let text = textParts.join(' ');
+      // `-` reads body from stdin so a long agent reply can be piped:
+      //   lazyclaw agent "summarize foo" | lazyclaw message send team -
+      if (text === '-' || (!text && !process.stdin.isTTY)) {
+        text = await new Promise((resolve) => {
+          let buf = '';
+          process.stdin.on('data', (c) => { buf += c; });
+          process.stdin.on('end', () => resolve(buf.trim()));
+        });
+      }
+      if (!text) {
+        console.error('error: empty message body');
+        process.exit(1);
+      }
+      try {
+        const r = await m.messageSend(cfg, name, text);
+        console.log(JSON.stringify(r));
+      } catch (e) {
+        console.error(`error: ${e.message}`); process.exit(1);
+      }
+      return;
+    }
+    default:
+      console.error('Usage: lazyclaw message <list|add|remove|send> ...');
+      process.exit(2);
+  }
+}
+
+async function cmdWorkspace(sub, positional, flags = {}) {
+  const ws = await import('./workspace.mjs');
+  const cfgDir = path.dirname(configPath());
+  switch (sub) {
+    case undefined:
+    case 'list': {
+      console.log(JSON.stringify(ws.listWorkspaces(cfgDir), null, 2));
+      return;
+    }
+    case 'init': {
+      const name = positional[0];
+      if (!name) { console.error('Usage: lazyclaw workspace init <name>'); process.exit(2); }
+      try {
+        const dir = ws.initWorkspace(cfgDir, name);
+        console.log(JSON.stringify({ ok: true, name, dir, files: ws.WORKSPACE_FILES }));
+      } catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      return;
+    }
+    case 'show': {
+      const [name, fileName] = positional;
+      if (!name) { console.error('Usage: lazyclaw workspace show <name> [<file>]'); process.exit(2); }
+      try {
+        if (fileName) process.stdout.write(ws.readWorkspaceFile(cfgDir, name, fileName));
+        else          process.stdout.write(ws.composeWorkspacePrompt(cfgDir, name) + '\n');
+      } catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      return;
+    }
+    case 'remove': {
+      const name = positional[0];
+      if (!name) { console.error('Usage: lazyclaw workspace remove <name>'); process.exit(2); }
+      try { ws.removeWorkspace(cfgDir, name); }
+      catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      console.log(JSON.stringify({ ok: true, removed: name }));
+      return;
+    }
+    case 'path': {
+      const name = positional[0];
+      if (!name) { console.log(ws.workspaceRoot(cfgDir)); return; }
+      try { console.log(ws.workspaceDir(cfgDir, name)); }
+      catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      return;
+    }
+    default:
+      console.error('Usage: lazyclaw workspace <list|init|show|remove|path> ...');
+      process.exit(2);
+  }
+}
+
+async function cmdBrowse(url, flags = {}) {
+  if (!url) { console.error('Usage: lazyclaw browse <url> [--max-bytes <N>] [--timeout-ms <N>] [--meta]'); process.exit(2); }
+  const { browse } = await import('./browse.mjs');
+  const opts = {};
+  if (flags['max-bytes'] !== undefined) opts.maxBytes = parseInt(flags['max-bytes'], 10);
+  if (flags['timeout-ms'] !== undefined) opts.timeoutMs = parseInt(flags['timeout-ms'], 10);
+  if (flags['user-agent']) opts.userAgent = flags['user-agent'];
+  try {
+    const r = await browse(url, opts);
+    if (flags.meta) {
+      process.stderr.write(JSON.stringify({
+        url: r.url, title: r.title, bytes: r.bytes, truncated: r.truncated,
+      }) + '\n');
+    }
+    process.stdout.write(r.markdown);
+  } catch (e) {
+    console.error(`error: ${e?.message || e}`);
+    process.exit(1);
+  }
+}
+
+async function cmdCron(sub, positional, flags = {}) {
+  const cron = await import('./cron.mjs');
+  const cfg = readConfig();
+  const backend = cron.pickBackend();
+  switch (sub) {
+    case undefined:
+    case 'list': {
+      const jobs = cron.listJobs(cfg);
+      console.log(JSON.stringify({ backend, jobs }, null, 2));
+      return;
+    }
+    case 'show': {
+      const name = positional[0];
+      if (!name) { console.error('Usage: lazyclaw cron show <name>'); process.exit(2); }
+      const job = cron.getJob(cfg, name);
+      if (!job) { console.error(`error: no job "${name}"`); process.exit(1); }
+      console.log(JSON.stringify({ backend, name, ...job }, null, 2));
+      return;
+    }
+    case 'add': {
+      // Shape: lazyclaw cron add <name> "<cron-spec>" -- <cmd> [args...]
+      // The `--` separator was already consumed by parseArgs, but
+      // the spec is the second positional and the command is
+      // everything after it. parseArgs preserves order, so:
+      //   positional[0] = name
+      //   positional[1] = "0 9 * * *"
+      //   positional[2..] = cmd argv
+      const [name, schedule, ...cmd] = positional;
+      if (!name || !schedule || !cmd.length) {
+        console.error('Usage: lazyclaw cron add <name> "<cron-spec>" -- <cmd> ...');
+        process.exit(2);
+      }
+      try {
+        cron.upsertJob(cfg, name, schedule, cmd);
+      } catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      writeConfig(cfg);
+      // Install to system scheduler — failure here doesn't roll
+      // back the config write because the job is "scheduled in
+      // intent". `cron sync` reconciles.
+      try {
+        if (backend === 'launchd') cron.installLaunchdJob(name, schedule, cmd);
+        else                       cron.installCrontabJob(name, schedule, cmd);
+      } catch (e) {
+        console.error(`warn: backend install failed: ${e.message} — config saved; run \`cron sync\` to retry`);
+        process.exit(1);
+      }
+      console.log(JSON.stringify({ ok: true, backend, name, schedule, command: cmd }, null, 2));
+      return;
+    }
+    case 'remove': {
+      const name = positional[0];
+      if (!name) { console.error('Usage: lazyclaw cron remove <name>'); process.exit(2); }
+      try { cron.removeJob(cfg, name); } catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      writeConfig(cfg);
+      try {
+        if (backend === 'launchd') cron.uninstallLaunchdJob(name);
+        else                       cron.uninstallCrontabJob(name);
+      } catch (e) {
+        console.error(`warn: backend uninstall failed: ${e.message}`);
+      }
+      console.log(JSON.stringify({ ok: true, backend, removed: name }));
+      return;
+    }
+    case 'sync': {
+      // Re-install every job in cfg.cron — useful after a fresh
+      // OS image where the launchd plists / crontab were wiped.
+      const out = [];
+      for (const [name, job] of Object.entries(cfg.cron || {})) {
+        try {
+          if (backend === 'launchd') cron.installLaunchdJob(name, job.schedule, job.command);
+          else                       cron.installCrontabJob(name, job.schedule, job.command);
+          out.push({ name, ok: true });
+        } catch (e) {
+          out.push({ name, ok: false, error: e.message });
+        }
+      }
+      console.log(JSON.stringify({ backend, results: out }, null, 2));
+      return;
+    }
+    case 'run': {
+      const name = positional[0];
+      if (!name) { console.error('Usage: lazyclaw cron run <name>'); process.exit(2); }
+      try {
+        const code = cron.runJob(cfg, name);
+        process.exit(code || 0);
+      } catch (e) { console.error(`error: ${e.message}`); process.exit(1); }
+      return;
+    }
+    default:
+      console.error('Usage: lazyclaw cron <list|add|remove|show|sync|run> ...');
+      process.exit(2);
+  }
+}
+
 async function cmdSkills(sub, positional, flags = {}) {
   const skillsMod = await import('./skills.mjs');
   const cfgDir = path.dirname(configPath());
@@ -1930,9 +2501,38 @@ async function cmdSkills(sub, positional, flags = {}) {
       return;
     }
     case 'install': {
-      // Three forms: --from <path>, --from-url <https://...>, or stdin.
+      // Four forms:
+      //   1. install user/repo[@ref][:subpath]   — GitHub bundle
+      //   2. install <name> --from <path>
+      //   3. install <name> --from-url <https://...>
+      //   4. install <name>                       — body via stdin
+      // Detect form 1 via a slash in the first positional and the
+      // absence of any --from* flag (so a literal local skill name
+      // with `/` still routes to the explicit-flag branch — though
+      // skillPath() rejects slashes anyway).
       const name = positional[0];
-      if (!name) { console.error('Usage: lazyclaw skills install <name> [--from <path> | --from-url <https://...>]'); process.exit(2); }
+      if (!name) { console.error('Usage: lazyclaw skills install <user/repo[@ref][:path]> | <name> [--from <path> | --from-url <https://...>]'); process.exit(2); }
+      if (name.includes('/') && !flags.from && !flags['from-url']) {
+        const inst = await import('./skills_install.mjs');
+        try {
+          const r = await inst.installFromGithub(name, cfgDir, {
+            prefix: flags.prefix || '',
+            force: !!flags.force,
+            maxBytes: flags['max-bytes'] !== undefined ? parseInt(flags['max-bytes'], 10) : undefined,
+            timeoutMs: flags['timeout-ms'] !== undefined ? parseInt(flags['timeout-ms'], 10) : undefined,
+          });
+          console.log(JSON.stringify({
+            ok: true,
+            spec: `${r.spec.owner}/${r.spec.repo}@${r.spec.ref}${r.spec.subpath ? ':' + r.spec.subpath : ''}`,
+            installed: r.installed,
+            skipped: r.skipped,
+          }, null, 2));
+          return;
+        } catch (e) {
+          console.error(`error: ${e?.message || e}`);
+          process.exit(1);
+        }
+      }
       let content;
       if (flags['from-url']) {
         const url = String(flags['from-url']);
@@ -2442,6 +3042,13 @@ function parseArgs(argv) {
   const out = { positional: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
+    // POSIX `--`: everything after is positional verbatim. Used by
+    // `cron add <name> "<spec>" -- <cmd> [args...]` so a recurring
+    // command with --flag of its own doesn't get parsed as our flag.
+    if (a === '--') {
+      for (let j = i + 1; j < argv.length; j++) out.positional.push(argv[j]);
+      break;
+    }
     if (a.startsWith('--')) {
       const eq = a.indexOf('=');
       if (eq >= 0) {
@@ -2467,10 +3074,161 @@ function parseArgs(argv) {
   return out;
 }
 
+// Interactive launcher — fired when the user types `lazyclaw` with
+// no subcommand AND we're attached to a TTY. OpenClaw's launcher
+// pattern: ASCII banner + provider/model status + arrow-key menu of
+// every common action. Selecting a row drops the user into the
+// matching subcommand via process.argv mutation + main() re-entry,
+// 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.
+async function cmdLauncher() {
+  await ensureRegistry();
+  const cfg = readConfig();
+  const provider = cfg.provider || '(unset — pick during onboard)';
+  const model = cfg.model || '(default)';
+  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: '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 },
+    { id: 'skills',    label: 'Skills',        desc: 'installed skill bundles',                        argv: ['skills', 'list'] },
+    { id: 'sessions',  label: 'Sessions',      desc: 'persisted chat sessions',                        argv: ['sessions', 'list'] },
+    { id: 'providers', label: 'Providers',     desc: 'registered providers + reachability',            argv: ['providers', 'list'] },
+    { id: 'cron',      label: 'Cron',          desc: 'recurring agent runs (launchd / crontab)',       argv: ['cron', 'list'] },
+    { 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 },
+  ];
+
+  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`);
+    }
+    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
+  };
+
+  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 }); }
+    };
+    process.stdin.on('keypress', onKey);
+  });
+
+  if (!picked || !picked.argv) {
+    process.exit(0);
+  }
+  // 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) {
+  const readline = await import('node:readline');
+  process.stdout.write('\n');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ans = await new Promise((resolve) => rl.question(label, resolve));
+  rl.close();
+  return ans.trim();
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   const cmd = argv[0];
   const rest = parseArgs(argv.slice(1));
+  // No subcommand at all: drop into the interactive launcher when we
+  // can render one (TTY both ways), otherwise fall through to the
+  // historical "Usage: ..." line so scripts / piped callers stay
+  // predictable.
+  if (cmd === undefined) {
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      await cmdLauncher();
+      return;
+    }
+    console.error('Usage: lazyclaw <' + SUBCOMMANDS.join('|') + '> ...');
+    console.error('Run `lazyclaw help` for a one-line summary of each subcommand.');
+    console.error('Tip: launch in an interactive terminal to get the arrow-key menu.');
+    process.exit(2);
+  }
   switch (cmd) {
     case 'run': {
       const [sessionId, file] = rest.positional;
@@ -2593,6 +3351,40 @@ async function main() {
       await cmdRates(sub, rest.positional.slice(1), rest.flags);
       break;
     }
+    case 'auth': {
+      const sub = rest.positional[0];
+      await cmdAuth(sub, rest.positional.slice(1), rest.flags);
+      break;
+    }
+    case 'pairing': {
+      const sub = rest.positional[0];
+      await cmdPairing(sub, rest.positional.slice(1), rest.flags);
+      break;
+    }
+    case 'nodes': {
+      const sub = rest.positional[0];
+      await cmdNodes(sub, rest.positional.slice(1), rest.flags);
+      break;
+    }
+    case 'message': {
+      const sub = rest.positional[0];
+      await cmdMessage(sub, rest.positional.slice(1), rest.flags);
+      break;
+    }
+    case 'workspace': {
+      const sub = rest.positional[0];
+      await cmdWorkspace(sub, rest.positional.slice(1), rest.flags);
+      break;
+    }
+    case 'browse': {
+      await cmdBrowse(rest.positional[0], rest.flags);
+      break;
+    }
+    case 'cron': {
+      const sub = rest.positional[0];
+      await cmdCron(sub, rest.positional.slice(1), rest.flags);
+      break;
+    }
     case 'daemon': {
       await cmdDaemon(rest.flags);
       break;