lazyclaw 6.3.1 → 6.5.0

package/README.ko.md

@@ -85,12 +85,16 @@ chat에서 `/orchestrator` (빈 입력 = on/off picker) 또는 `/orchestrator on
 |---|---|
 | `/config` | chat 나가고 setup 위저드 재실행 |
 | `/provider` · `/model` | 검색 picker로 provider/model 선택 |
+| `/trainer [set\|fallback]` · `/agent edit <name>` | trainer / agent의 provider+model을 같은 picker로 선택 (`auto`·custom-id 행 포함) |
 | `/channels [<name> on\|off]` | 채널 보기 / 토글 |
 | `/orchestrator [on\|off\|…]` | 멀티에이전트 보기 / 토글 (빈 입력=picker) |
 | `/context [turns N\|tokens N]` | 히스토리 윈도우 조절 |
+| `/agentic [on\|off]` · `/plan [on\|off]` | chat에서 tool 실행(approval 게이트); plan은 읽기전용 "먼저 제안" |
 | `/skill` · `/personality` · `/memory` · `/loop` · `/goal` | 스킬·페르소나·메모리·루프·목표 |
 
-`/help`로 전체 목록. 고스트 자동완성, 한글 IME는 박스 안에서 조합.
+`/help`로 전체 목록. 타이핑하면 자동완성: 명령어(`/...`)와 그 **인자**까지 — `/login`→`codex-cli`/`gemini-cli`, `/hud`→`on`/`off`, `/channels`→채널명, `/task`·`/team`·`/agent`·`/personality`·`/trainer`·`/orchestrator` 서브커맨드 등 — 팝업에 떠서 ↑/↓ 선택, Enter로 채움. provider→model 2단계 선택(`/model`·`/trainer set`·`/orchestrator planner`)은 `↹ pick` 힌트가 뜨고 **Tab**으로 드릴인 모달 열림. 한글 IME는 박스 안에서 조합.
+
+스킬은 markdown 지침 번들로 시스템 프롬프트에 합성된다. `lazyclaw skills starter`로 번들 스타터 팩 8종(`concise` · `korean` · `commit-message` · `code-review` · `channel-style` · `summarize` · `explain` · `debug-coach`) 설치, `lazyclaw skills install <user>/<repo>`로 GitHub에서 추가 설치, chat에서는 `/skills`로 선택.
 
 ## 대시보드
 

package/README.md

@@ -36,7 +36,7 @@ The first run is a **phased wizard** (Hermes-style — get one clean chat workin
 1. **Provider + model** — arrow-key picker (`claude-cli` is keyless; gemini/openai/anthropic take an API key).
 2. **Verify** — a one-token ping confirms the provider answers.
 3. **Context window** — how much history to keep per turn (optional).
-4. **Channel** — Slack / Telegram / Matrix / HTTP built in; Discord / Email / Signal / Voice / WhatsApp via plugins (optional).
+4. **Channel** — Slack / Telegram / Matrix / HTTP built in; Discord / Email / Voice / WhatsApp ship in-tree (need a runtime dep via `lazyclaw channels install <name>`), Signal needs `signal-cli` (optional).
 5. **Workspace / skills / webhook** (optional).
 6. **Orchestration** — turn on the planner + workers pipeline (optional).
 
@@ -67,7 +67,7 @@ After every turn, a fire-and-forget loop records the trajectory and distils reus
 
 ## Talk to it anywhere
 
-Connect a channel and **the same agent** answers there — every listener forwards into the always-on daemon's shared session store, so chat, the dashboard, and all channels are one agent with one memory (and context follows across channels). Slack, Telegram, Matrix, and HTTP are built in; Discord, Email, Signal, Voice, and WhatsApp install as `@lazyclaw/channel-*` plugins.
+Connect a channel and **the same agent** answers there — every listener forwards into the always-on daemon's shared session store, so chat, the dashboard, and all channels are one agent with one memory (and context follows across channels). Slack, Telegram, Matrix, and HTTP are built in; Discord, Email, Voice, and WhatsApp ship in-tree and run once their runtime dependency is installed into the config dir (`lazyclaw channels install <name>`), and Signal needs the external `signal-cli` binary on your PATH.
 
 ```bash
 lazyclaw service install              # 1) the always-on daemon (the shared brain)
@@ -79,7 +79,7 @@ lazyclaw slack listen --daemon-url http://127.0.0.1:19600   # non-default daemon
 
 lazyclaw channels                     # view configured channels
 lazyclaw channels enable|disable slack
-lazyclaw channels install @lazyclaw/channel-discord
+lazyclaw channels install discord     # installs discord.js into ~/.lazyclaw and enables the channel
 ```
 
 A listener is a thin forwarder: it owns the channel socket (Slack Socket Mode needs no public URL, just an app-level `xapp-` token) and POSTs each message to the daemon's `/inbound`, which binds the conversation to a persistent session and runs the provider. It needs a reachable daemon (`lazyclaw service install`, or `lazyclaw daemon`); override the target with `--daemon-url` / `LAZYCLAW_DAEMON_URL`. Set it all up from the wizard's channel step, or `/channels` in chat.
@@ -129,14 +129,16 @@ The REPL has slash commands for everything you'd otherwise edit config for — p
 
 | Slash | Does |
 |---|---|
-| `/config` | leave chat and re-run the setup wizard |
+| `/config` | change one setting in-chat (provider/model/context/channel creds/webhook/…); `/setup` re-runs the whole wizard |
 | `/provider` · `/model` | pick provider / model from a searchable list |
-| `/channels [<name> on\|off]` | view / toggle channels |
+| `/trainer [set\|fallback]` · `/agent edit <name>` | pick the trainer / an agent's provider+model from the same list (with an `auto` and a custom-id row) |
+| `/channels [<name> on\|off\|setup]` | view / toggle channels; `setup` sets the bot token & credentials in-chat |
 | `/orchestrator [on\|off\|…]` | view / toggle multi-agent (picker on bare call) |
 | `/context [turns N\|tokens N]` | resize the chat history window |
+| `/agentic [on\|off]` · `/plan [on\|off]` | let chat run tools (approval-gated); plan mode is read-only "propose first" |
 | `/skill` · `/personality` · `/memory` · `/loop` · `/goal` | skills, personas, memory, loops, goals |
 
-`/help` lists them all. Ghost-text autocomplete completes commands as you type; CJK/Hangul input composes inside the box.
+`/help` lists them all. Autocomplete works as you type: command names (`/...`) and, after a command, its **arguments** — `/login` → `codex-cli`/`gemini-cli`, `/hud` → `on`/`off`, `/channels` → channel names, subcommands for `/task` `/team` `/agent` `/personality` `/trainer` `/orchestrator`, and more — appear in a popup (↑/↓ select, Enter fill). The 2-step provider→model picks (`/model`, `/trainer set`, `/orchestrator planner`) show a `↹ pick` hint; press **Tab** to open the drill-in modal. CJK/Hangul input composes inside the box.
 
 ## The dashboard
 
@@ -144,7 +146,7 @@ The REPL has slash commands for everything you'd otherwise edit config for — p
 lazyclaw dashboard          # local web UI on http://127.0.0.1:19600
 ```
 
-A framework-free SPA over the daemon's JSON API: Chat, Sessions, Workflows, Skills, Providers, Rates, Metrics, Doctor, Config, Status, Agents, Teams, Tasks, Trainer, Recall, Sandbox, Channels — 17 tabs, dark amber theme.
+A framework-free SPA over the daemon's JSON API: Chat, Sessions, Workflows, Skills, Providers, Rates, Metrics, Doctor, Config, Status, Agents, Teams, Tasks, **Team Live**, Trainer, Recall, Sandbox, Channels — 18 tabs, dark amber theme. The **Team Live** tab is a real-time org view: avatar tiles with status rings + harness badges (`provider · model`), live agent-A→B delegation, and click-to-drill-down (harness, current task, recent activity), streamed over Server-Sent Events (`GET /events`).
 
 ## Providers
 
@@ -162,17 +164,19 @@ A framework-free SPA over the daemon's JSON API: Chat, Sessions, Workflows, Skil
 ## What else it ships
 
 - **Tool registry** — 12 categories (`agents`, `browser`, `coding`, `exec`, `fs`, `git`, `iot`, `learning`, `media`, `net`, `os`, `scheduling`) plus stdio MCP. Sensitive tools (shell, write, network) are **fail-closed** behind an approval hook by default.
-- **Durable recall** — one SQLite + FTS5 index over sessions, skills, trajectories, and memory; rebuildable from the corpus.
+- **Skills** — markdown instruction bundles composed into the system prompt. `lazyclaw skills starter` installs the bundled pack (`concise` · `korean` · `commit-message` · `code-review` · `channel-style` · `summarize` · `explain` · `debug-coach`); `lazyclaw skills install <user>/<repo>` pulls more from GitHub; `/skills` picks one in chat.
+- **Durable recall** — one SQLite + FTS5 index over sessions, skills, trajectories, and memory; rebuildable from the corpus (`lazyclaw index rebuild`). Optionally blend in embedding similarity (`cfg.recall.embeddings`, off by default; OpenAI/Gemini key or a local Ollama model — the $0 path stays pure FTS5); `lazyclaw index embed` backfills the vectors.
 - **Loops & goals** — durable foreground/`--detach` loops and cron-scheduled goals that survive restart.
 - **Personas** — layered SOUL / workspace / personality / role / user-model / skills compose into the system prompt.
-- **Sandboxes** — `local` / `docker` / `ssh` / `singularity` / `modal` / `daytona` behind one API.
+- **Agent teams, live** — build a hierarchy (a planner agent with sub-agents on different harnesses, e.g. a data-engineer on `gemini-cli` and a backend on `claude-cli`) via each agent's `manager`; a Slack message to a team's channel auto-routes into the multi-agent loop, and the **Team Live** dashboard tab shows who is doing what, on which harness, and the real-time A→B delegation as it happens.
+- **Default-on confinement** — sensitive tools (`bash`, `python_exec`/`node_exec`, `git_*`, the `os` tools) run confined by default: writes are limited to the workspace + temp, secret dirs (`~/.ssh`, `~/.aws`, the config dir, …) are unreadable, and the secret-scrubbed env still applies. macOS uses `seatbelt`, Linux uses `bubblewrap`/`firejail` (auto-detected). Network is allowed; opt out with `cfg.sandbox.confine=false`. Run `lazyclaw sandbox status` to see the effective posture.
+- **Sandboxes** — `local` / `docker` / `ssh` / `singularity` / `modal` / `daytona` behind one API; pluggable backends for heavier isolation (containers, remote hosts) layered on top of the default local confinement.
+- **MCP** — stdio MCP servers in `cfg.mcp.servers` boot with the daemon; their tools register as `mcp:<server>:<tool>` (always approval-gated). Manage them from the CLI: `lazyclaw mcp list` / `mcp add <name> --command <cmd> [--args "…"] [--allow-glob <glob>]` / `mcp remove <name>` / `mcp call <server> <tool> [--args-json '{…}']` (spawns the server, runs one tool, tears it down).
+- **Daemon lifecycle** — `lazyclaw daemon status | stop | logs` over a pidfile; `maxTokens` in config raises the output cap; `LAZYCLAW_REQUEST_TIMEOUT_MS` sets the per-provider idle timeout (default 120s).
 
 ## Configuration & security
 
-Config is plain JSON at `~/.lazyclaw/config.json`; channel + provider secrets live in `~/.lazyclaw/.env` (written 0600, never logged). Move the dir with `LAZYCLAW_CONFIG_DIR=/path`.
-
-> [!WARNING]
-> Treat `~/.lazyclaw/config.json` like a shell rc — values resolved with `$(...)` execute at load. Don't paste an untrusted snippet without reading it.
+Config is plain JSON at `~/.lazyclaw/config.json` — parsed with `JSON.parse`, no shell or code execution; channel + provider secrets live in `~/.lazyclaw/.env` (written 0600, never logged). Move the dir with `LAZYCLAW_CONFIG_DIR=/path`.
 
 Sensitive tools deny by default unless an approval hook grants them; `config.json` and workflow state are written owner-only; secrets are scrubbed from the `bash` tool's child env and redacted from trajectories and synthesised skills.
 

package/agents.mjs

@@ -16,11 +16,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { ensureValidName as cronEnsureValidName } from './cron.mjs';
+import * as toolRegistry from './mas/tools/registry.mjs';
 
 const AGENTS_DIRNAME = 'agents';
 
 export const DEFAULT_TOOLS = ['bash', 'read', 'write', 'grep', 'skill_view'];
-export const ALL_TOOLS = ['bash', 'read', 'write', 'grep', 'skill_view', 'web_search', 'web_fetch', 'slack_post'];
+
+// The valid tool set is derived from the LIVE tool registry (51+ tools), not a
+// hardcoded 8-name list with a stale, unregistered 'slack_post' — that list
+// rejected recall/delegate/git_*/edit/etc. and silently capped team agents.
+export function knownTools() {
+  return new Set([...DEFAULT_TOOLS, ...toolRegistry.listNames()]);
+}
+
+// Back-compat export: a snapshot of the registered tool names (the registry
+// self-populates at import). mcp:* tools register dynamically; validateTools
+// accepts them even when absent from this snapshot.
+export const ALL_TOOLS = [...knownTools()];
 
 export class AgentError extends Error {
   constructor(message, code) {
@@ -52,9 +64,12 @@ function validateTools(tools) {
   if (!Array.isArray(tools)) {
     throw new AgentError('tools must be an array', 'AGENT_BAD_TOOLS');
   }
-  const bad = tools.filter(t => !ALL_TOOLS.includes(t));
+  // Validate against the LIVE registry; accept mcp:* names (they register when
+  // their server starts) so a config referencing one isn't rejected at edit time.
+  const known = knownTools();
+  const bad = tools.filter(t => !known.has(t) && !/^mcp:/.test(String(t)));
   if (bad.length) {
-    throw new AgentError(`unknown tool(s): ${bad.join(', ')} — known: ${ALL_TOOLS.join(', ')}`, 'AGENT_BAD_TOOLS');
+    throw new AgentError(`unknown tool(s): ${bad.join(', ')}`, 'AGENT_BAD_TOOLS');
   }
   // Dedupe while preserving order.
   return [...new Set(tools)];
@@ -75,6 +90,10 @@ function defaultShape(name) {
     tools: [...DEFAULT_TOOLS],
     tags: [],
     iconEmoji: '',
+    // Optional parent agent (hierarchy). '' = top-level. A team's org tree is
+    // derived from members' manager links (see teams.teamTree). Validated to
+    // reference a registered agent and to never form a cycle.
+    manager: '',
     // Phase 18 — agent memory write trigger. 'auto' means the router
     // fires a reflection LLM call on terminal `done`; 'manual' waits
     // for `lazyclaw agent reflect`; 'off' disables writes entirely.
@@ -105,7 +124,34 @@ function writeAtomic(filePath, obj) {
 const VALID_MEMORY_WRITE = ['auto', 'manual', 'off'];
 const VALID_SKILL_WRITE = ['auto', 'manual', 'off'];
 
-export function registerAgent({ name, displayName, role = '', provider = 'claude-cli', model = '', tools, tags = [], iconEmoji = '', memoryWrite, memoryMaxChars, skillWrite } = {}, configDir = defaultConfigDir()) {
+// Validate a proposed `manager` (parent agent) for `name`: it must reference a
+// registered agent, may not be the agent itself, and may not close a cycle
+// (i.e. `name` must not already be an ancestor of the proposed manager).
+// Returns the normalised manager string ('' when none).
+function validateManager(name, manager, configDir) {
+  if (!manager) return '';
+  const mgr = String(manager);
+  if (mgr === name) {
+    throw new AgentError(`agent "${name}" cannot manage itself`, 'AGENT_BAD_MANAGER');
+  }
+  if (!getAgent(mgr, configDir)) {
+    throw new AgentError(`unknown manager "${mgr}" (not a registered agent)`, 'AGENT_BAD_MANAGER');
+  }
+  let cur = mgr;
+  const visited = new Set();
+  while (cur) {
+    if (cur === name) {
+      throw new AgentError(`manager "${manager}" would create a cycle`, 'AGENT_MANAGER_CYCLE');
+    }
+    if (visited.has(cur)) break; // pre-existing cycle elsewhere — stop walking
+    visited.add(cur);
+    const rec = getAgent(cur, configDir);
+    cur = rec && rec.manager ? String(rec.manager) : null;
+  }
+  return mgr;
+}
+
+export function registerAgent({ name, displayName, role = '', provider = 'claude-cli', model = '', tools, tags = [], iconEmoji = '', memoryWrite, memoryMaxChars, skillWrite, manager } = {}, configDir = defaultConfigDir()) {
   ensureValidName(name);
   const p = agentPath(name, configDir);
   if (fs.existsSync(p)) {
@@ -132,6 +178,7 @@ export function registerAgent({ name, displayName, role = '', provider = 'claude
     memoryWrite: mw,
     memoryMaxChars: Number.isFinite(+memoryMaxChars) && +memoryMaxChars > 0 ? +memoryMaxChars : 12 * 1024,
     skillWrite: sw,
+    manager: validateManager(name, manager, configDir),
   };
   writeAtomic(p, data);
   return data;
@@ -173,6 +220,9 @@ export function patchAgent(name, patch, configDir = defaultConfigDir()) {
   if (patch.skillWrite !== undefined && !VALID_SKILL_WRITE.includes(patch.skillWrite)) {
     throw new AgentError(`skillWrite must be one of ${VALID_SKILL_WRITE.join(', ')}`, 'AGENT_BAD_SKILL_WRITE');
   }
+  if (patch.manager !== undefined) {
+    next.manager = validateManager(name, patch.manager, configDir);
+  }
   writeAtomic(agentPath(name, configDir), next);
   return next;
 }

package/channels-discord/index.mjs

@@ -15,6 +15,10 @@ export class DiscordChannel extends Channel {
   constructor(opts = {}) {
     super('discord');
     this._token = opts.token || process.env.DISCORD_BOT_TOKEN || null;
+    // loadDep resolves the runtime dep from the config dir when the gateway
+    // injects it (lazyclaw channels install discord); falls back to a bare
+    // import so a dep installed alongside lazyclaw still works.
+    this._loadDep = typeof opts.loadDep === 'function' ? opts.loadDep : ((s) => import(s));
     this._client = null;
     this._lib = null;
   }
@@ -22,7 +26,7 @@ export class DiscordChannel extends Channel {
   async start(handler, opts = {}) {
     await super.start(handler, opts);
     if (!this._token) throw new Error('DiscordChannel: DISCORD_BOT_TOKEN missing');
-    this._lib = await import('discord.js');
+    this._lib = await this._loadDep('discord.js');
     const { Client, GatewayIntentBits, Partials } = this._lib;
     this._client = new Client({
       intents: [

package/channels-email/index.mjs

@@ -15,15 +15,16 @@ export class EmailChannel extends Channel {
     this._imapOpts = opts.imap;
     this._smtpOpts = opts.smtp || {};
     this._from = opts.from || opts.imap.user;
+    this._loadDep = typeof opts.loadDep === 'function' ? opts.loadDep : ((s) => import(s));
     this._imap = null;
     this._transporter = null;
   }
 
   async start(handler, opts = {}) {
     await super.start(handler, opts);
-    const Imap = (await import('node-imap')).default;
-    const { simpleParser } = await import('mailparser');
-    const nodemailer = (await import('nodemailer')).default;
+    const Imap = (await this._loadDep('node-imap')).default;
+    const { simpleParser } = await this._loadDep('mailparser');
+    const nodemailer = (await this._loadDep('nodemailer')).default;
 
     this._transporter = nodemailer.createTransport({
       host: this._smtpOpts.host,

package/channels-whatsapp/index.mjs

@@ -10,6 +10,7 @@ export class WhatsappChannel extends Channel {
   constructor(opts = {}) {
     super('whatsapp');
     this._opts = opts || {};
+    this._loadDep = typeof opts.loadDep === 'function' ? opts.loadDep : ((s) => import(s));
     this._client = null;
     this._qrState = 'pending'; // pending | shown | authenticated | failed
     this._lastQr = null;
@@ -20,8 +21,8 @@ export class WhatsappChannel extends Channel {
 
   async start(handler, opts = {}) {
     await super.start(handler, opts);
-    const wweb = await import('whatsapp-web.js');
-    const qrt = await import('qrcode-terminal');
+    const wweb = await this._loadDep('whatsapp-web.js');
+    const qrt = await this._loadDep('qrcode-terminal');
     const { Client, LocalAuth } = wweb;
     this._client = new Client({
       authStrategy: new LocalAuth({ dataPath: this._opts.dataPath || './whatsapp' }),

package/chat_window.mjs

@@ -16,6 +16,16 @@
 export const CHAT_WINDOW_TURNS = Number(process.env.LAZYCLAW_CHAT_WINDOW_TURNS) || 20;
 export const CHAT_WINDOW_TOKEN_BUDGET = Number(process.env.LAZYCLAW_CHAT_WINDOW_TOKENS) || 8000;
 
+// Approximate token count of a messages[] array (4 chars/token, same heuristic
+// the window cap uses). Drives the status-bar context gauge so it reflects the
+// conversation history lazyclaw actually holds — NOT a provider's self-reported
+// usage, which for CLI providers (codex/claude/gemini) includes their own
+// system prompt + tool defs per call and has nothing to do with this budget.
+export function estimateMessagesTokens(messages) {
+  const arr = Array.isArray(messages) ? messages : [];
+  return Math.ceil(arr.reduce((n, m) => n + String(m?.content || '').length, 0) / 4);
+}
+
 // Trim a hydrated messages[] array to fit the sliding window. Returns
 // { messages, dropped } so the caller can log a one-shot "dropped N
 // older turns" line at session start. The first message is preserved
@@ -31,8 +41,7 @@ export function applyChatWindow(messages, { turns = CHAT_WINDOW_TURNS, tokens =
   while (out.length > turns) out.shift();
   // Token budget cap: estimate 4 chars / token, then trim from the
   // front (oldest) until estimated tokens ≤ budget.
-  const estTokens = (arr) => Math.ceil(arr.reduce((n, m) => n + String(m.content || '').length, 0) / 4);
-  while (out.length > 1 && estTokens(out) > tokens) out.shift();
+  while (out.length > 1 && estimateMessagesTokens(out) > tokens) out.shift();
   const dropped = before - out.length;
   if (sys) out.unshift(sys);
   return { messages: out, dropped };

package/cli.mjs

@@ -10,7 +10,8 @@ import {
 // Phase D2 — provider-registry bootstrap (lazy load + per-call re-register).
 import { ensureRegistry, requireRegistry, getRegistry } from './lib/registry_boot.mjs';
 // Phase D2 — argument parsing + subcommand inventory + agent-registry classifier.
-import { SUBCOMMANDS, parseArgs, AGENT_REG_SUBS } from './lib/args.mjs';
+// nearest/usageHint power the unknown-subcommand "did you mean" + `help <name>`.
+import { SUBCOMMANDS, parseArgs, AGENT_REG_SUBS, nearest, usageHint } from './lib/args.mjs';
 // Phase D4 — interactive TUI pickers/banner helpers. Still imported here for the
 // onboard / setup / launcher / chat paths that remain inline in this entrypoint.
 import {
@@ -32,6 +33,11 @@ import { dispatchSlash as _dispatchSlash, parseSlashLine as _parseSlashLine } fr
 // loop reads this same list the Ink path (_help) and the popup use.
 import { SLASH_COMMANDS } from './tui/slash_commands.mjs';
 
+// Sentinel thrown when cmdHelp would process.exit(2) for a known subcommand
+// that lacks a rich HELP_DETAILS entry — caught in the `help` branch so we can
+// fall back to a one-line usage hint instead of exiting non-zero.
+class _HelpFallback extends Error {}
+
 async function main() {
   const argv = process.argv.slice(2);
   const cmd = argv[0];
@@ -189,10 +195,67 @@ async function main() {
       }
       break;
     }
+    case 'index': {
+      // FTS index recovery surface documented by mas/index_db.mjs and the
+      // doctor failure-log. reindexAll (NOT the destructive rebuild) drops the
+      // db and repopulates from the on-disk corpus, so recall is never left empty.
+      const indexSub = rest.positional[0];
+      const cfgDir = path.dirname(configPath());
+      if (indexSub === 'embed') {
+        // Opt-in hybrid recall: embed FTS rows that lack a vector. No-op when
+        // cfg.recall.embeddings is off (then it just reports 0 embedded).
+        try {
+          const indexDb = await import('./mas/index_db.mjs');
+          const embedded = await indexDb.backfillEmbeddings(cfgDir, readConfig());
+          console.log(JSON.stringify({ ok: true, embedded }));
+          process.exit(0);
+        } catch (e) {
+          console.error(`index embed failed: ${e.message}`);
+          process.exit(1);
+        }
+      }
+      if (indexSub !== 'rebuild') {
+        console.error('Usage: lazyclaw index <rebuild|embed>');
+        process.exit(2);
+      }
+      try {
+        const indexDb = await import('./mas/index_db.mjs');
+        indexDb.reindexAll(cfgDir);
+        // reindexAll returns void; derive what landed by counting the FTS rows.
+        const db = indexDb.openIndex(cfgDir);
+        const counts = {};
+        for (const [scope, table] of [
+          ['sessions', 'fts_sessions'], ['skills', 'fts_skills'],
+          ['trajectories', 'fts_trajectories'], ['memories', 'fts_memories'],
+        ]) {
+          counts[scope] = db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n;
+        }
+        console.log(JSON.stringify({ ok: true, counts }));
+        process.exit(0);
+      } catch (e) {
+        console.error(`index rebuild failed: ${e.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+    case 'mcp': {
+      // list (configured + connected) / add / remove / call. Config mutation
+      // (add/remove) edits cfg.mcp.servers; servers (re)spawn at daemon boot.
+      const sub = rest.positional[0];
+      await (await import('./commands/mcp.mjs')).cmdMcp(sub, rest.positional.slice(1), rest.flags);
+      break;
+    }
     case 'chat': {
       await (await import('./commands/chat.mjs')).cmdChat(rest.flags);
       break;
     }
+    case 'workflow': {
+      // Named declarative workflows (cfg.workflows) — add/list/show/remove/run.
+      // Distinct from the top-level `run <session-id> <file.mjs>` engine.
+      const sub = rest.positional[0];
+      await (await import('./commands/workflow_named.mjs')).cmdWorkflow(sub, rest.positional.slice(1), rest.flags);
+      break;
+    }
     case 'sessions': {
       const sub = rest.positional[0];
       await (await import('./commands/sessions.mjs')).cmdSessions(sub, rest.positional.slice(1), rest.flags);
@@ -369,7 +432,38 @@ async function main() {
     case 'help':
     case '--help':
     case '-h': {
-      await (await import('./commands/setup.mjs')).cmdHelp(rest.positional[0]);
+      const name = rest.positional[0];
+      const cmdHelp = (await import('./commands/setup.mjs')).cmdHelp;
+      // Bare `help` / unknown-name handling stays here so we can offer a
+      // did-you-mean and a bounded usage-hint fallback without editing the
+      // rich HELP_DETAILS map in commands/setup.mjs.
+      if (!name) { cmdHelp(undefined); break; }
+      const hint = usageHint(name);
+      if (!hint) {
+        // Unknown subcommand name passed to help — suggest the nearest match.
+        process.stderr.write(`unknown command "${name}"`);
+        const guess = nearest(name, SUBCOMMANDS);
+        process.stderr.write(guess ? ` — did you mean "${guess}"?\n` : `\n`);
+        process.stderr.write('run `lazyclaw help` to see the list\n');
+        process.exit(2);
+      }
+      // Known subcommand: prefer the rich HELP_DETAILS entry. cmdHelp exits 2
+      // for subcommands that lack a detailed entry (writing its own "unknown
+      // subcommand" lines to stderr first), so guard that fatal exit AND buffer
+      // its stderr — on fallback we drop that noise and print the one-line
+      // usage hint instead. `help <name>` must never error on a real command.
+      const realExit = process.exit;
+      const realErr = process.stderr.write.bind(process.stderr);
+      const buffered = [];
+      let detailMissing = false;
+      process.exit = (code) => { if (code === 2) { detailMissing = true; throw new _HelpFallback(); } realExit(code); };
+      process.stderr.write = (chunk, ...a) => { buffered.push([chunk, a]); return true; };
+      try { cmdHelp(name); }
+      catch (e) { if (!(e instanceof _HelpFallback)) { process.exit = realExit; process.stderr.write = realErr; throw e; } }
+      finally { process.exit = realExit; process.stderr.write = realErr; }
+      // Non-fallback path: replay whatever cmdHelp wrote to stderr verbatim.
+      if (detailMissing) process.stdout.write(hint + '\n');
+      else for (const [chunk, a] of buffered) process.stderr.write(chunk, ...a);
       break;
     }
     case 'menu': {
@@ -377,10 +471,16 @@ async function main() {
       await (await import('./commands/setup.mjs')).cmdLauncher();
       break;
     }
-    default:
+    default: {
+      // Unknown top-level subcommand: lead with a closest-match suggestion so
+      // a typo (`sesions` -> `sessions`) is fixable without scanning the dump.
+      const guess = nearest(cmd, SUBCOMMANDS);
+      if (guess) console.error(`unknown command "${cmd}" — did you mean "${guess}"?`);
+      else console.error(`unknown command "${cmd}"`);
       console.error('Usage: lazyclaw <' + SUBCOMMANDS.join('|') + '> ...');
       console.error('Run `lazyclaw help` for a one-line summary of each subcommand.');
       process.exit(2);
+    }
   }
 }