@ghostystudio/cli 0.7.1 → 0.8.0

package/README.md

@@ -18,9 +18,16 @@ ghosty agents ls
 ghosty agents get <id> [--fields name,model,prompt]
 ghosty agents set <id> [--name] [--model] [--prompt | --prompt-file FILE]
 ghosty agents restart <id>
+ghosty agents doctor <id> [--verbose]                 # exits 1 when it finds a problem
+ghosty agents docs ls|grant|revoke <id> [doc]         [--write] [--no-deliver]
+ghosty agents set <id> --voice elevenlabs:ID --voice-replies auto --auto-stage on
 
 ghosty files ls|get|put|rm <id> [path]   [--file LOCAL] [--out LOCAL]
-ghosty skills ls|add|rm <id> [slug]      [--file SKILL.md]
+ghosty skills ls|get|add|rm <id> [slug]  [--file SKILL.md | --dir FOLDER] [--out DIR]
+ghosty dbs ls|tables|query|import|grant|revoke <id> [db]   [--write] [--external-write t1,t2] [--from easybits:ID --dry-run]
+ghosty turns ls <id>                     [--errors] [--since 1h] [--limit N]
+ghosty channels whatsapp ls|enable|disable <id> [number]   [--dry-run]
+ghosty board archive <id>                --integration X | --column X | --before 30d   [--dry-run]
 ghosty mcp get|set <id>                  [--file servers.json]
 
 ghosty try <id> "message"                [--session] [--reset] [--whatsapp]
@@ -32,11 +39,20 @@ ghosty schedule ls <id>
 ghosty schedule rm <id> <schedule-id>
 
 ghosty me files ls|upload|rm             [--kind image|video|audio|document|other]
+ghosty credentials ls|set|rm [provider]  [--from-env VAR]   # never as an argument
 ghosty docs
 ```
 
 Global: `--json` (stdout is JSON only), `--token <token>` / `GHOSTY_TOKEN` (a `gat_…` agent token reaches only that agent), `--help`, `--version`.
 
+Every command has its own help with examples: `ghosty <command> --help` or `ghosty help <command>`.
+
 Exit codes: `0` ok · `1` API error · `2` usage error · `3` not signed in.
 
+### Changes in 0.8.0
+
+- Destructive commands (`agents rm`, `files rm`, `skills rm`, `credentials rm`, `board archive`, `dbs import` over existing rows, `channels whatsapp enable`) ask first. **Without a terminal they need `--yes`** or exit `2`.
+- `skills rm` keeps a local copy under `~/.config/ghosty/trash/` and prints the undo command.
+- New: `agents doctor`, `agents docs`, `dbs`, `turns`, `channels whatsapp`, `board archive`, `credentials`, `skills get`, `skills add --dir`, voice and auto-stage flags on `agents set`, per-command help and "did you mean".
+
 Requires Node 22+. Docs: https://www.ghosty.studio/docs/cli · Skill for coding agents: `npx skills add https://www.ghosty.studio`

package/dist/index.js

@@ -290,7 +290,7 @@ async function request(path, opts = {}, retried = false) {
     method: opts.method ?? (opts.body !== void 0 || opts.raw !== void 0 ? "POST" : "GET"),
     headers: {
       authorization: `Bearer ${token}`,
-      "user-agent": `ghosty-cli/${"0.7.1"}`,
+      "user-agent": `ghosty-cli/${"0.8.0"}`,
       ...opts.body !== void 0 ? { "content-type": "application/json" } : {},
       ...opts.headers
     },
@@ -313,7 +313,7 @@ async function toError(res) {
   }
   const detail = body.message || body.error_description || (body.detalle && body.error ? `${body.error}: ${body.detalle}` : body.error) || text.slice(0, 300) || res.statusText;
   if (res.status === 401) return new CliError("Your session is not valid anymore.", EXIT.AUTH, "Run: ghosty login");
-  if (res.status === 403) return new CliError(`Not allowed: ${detail}`, EXIT.API, "Run: ghosty login   (to refresh your permissions)");
+  if (res.status === 403) return new CliError(`Not allowed: ${detail}`, EXIT.API, "If the agent was shared with you, its workspace (board, channels, numbers) stays with the owner: ask them to add you to that workspace. Otherwise run: ghosty login");
   if (res.status === 404) return new CliError("Not found.", EXIT.API, "Check the agent id (ghosty agents ls) or that your token belongs to that agent.");
   if (body.error === "restart_no_aplica" || body.error === "agente_sin_maquina") {
     return new CliError("This agent doesn't need a restart: new files, skills and MCP load on its next turn.", EXIT.API);
@@ -322,7 +322,44 @@ async function toError(res) {
 }
 
 // src/commands/agents.ts
-import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { mkdir as mkdir2, readdir, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname2, join as join2, relative } from "node:path";
+
+// src/prompt.ts
+import { createInterface } from "node:readline/promises";
+var canPrompt = () => Boolean(process.stdin.isTTY && process.stderr.isTTY);
+function requireYesIfHeadless(yes, retry) {
+  if (!yes && !canPrompt()) throw usage("--yes required when not running interactively.", `Run: ${retry} --yes`);
+}
+async function confirm(question, opts) {
+  if (opts.yes) return;
+  if (!canPrompt()) throw usage("--yes required when not running interactively.", `Run: ${opts.retry} --yes`);
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const ask = opts.expect ? `${question}
+Type ${bold(opts.expect)} to confirm: ` : `${question} [y/N] `;
+    const a = (await rl.question(ask)).trim();
+    const ok = opts.expect ? a === opts.expect : /^y(es)?$/i.test(a);
+    if (!ok) throw usage("Cancelled.");
+  } finally {
+    rl.close();
+  }
+}
+function distance(a, b) {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) d[0][j] = j;
+  for (let i = 1; i <= a.length; i++)
+    for (let j = 1; j <= b.length; j++) d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+  return d[a.length][b.length];
+}
+function suggest(input, known) {
+  const best = known.map((k) => [k, distance(input, k)]).sort((x, y) => x[1] - y[1])[0];
+  if (best && best[1] <= 2) return best[0];
+  return known.find((k) => k.startsWith(input) && input.length >= 2);
+}
+
+// src/commands/agents.ts
 var enc = encodeURIComponent;
 var agentPath = (id, rest = "") => `/api/v2/agents/${enc(id)}${rest}`;
 var need = (v, what, example) => {
@@ -383,12 +420,33 @@ async function agentsSet(id, v) {
   for (const c of (v.connect ?? "").split(",").map((s) => s.trim()).filter(Boolean)) connectors[c] = {};
   for (const c of (v.disconnect ?? "").split(",").map((s) => s.trim()).filter(Boolean)) connectors[c] = null;
   if (Object.keys(connectors).length) body.connectors = connectors;
-  if (!Object.keys(body).length) throw usage("Nothing to change.", "Use --name, --engine, --model, --prompt, --prompt-file, --env, --connect or --disconnect.");
+  const voice = {};
+  if (v.voice) {
+    const [engine, ...rest] = v.voice.split(":");
+    if (engine !== "elevenlabs" && engine !== "kokoro" || !rest.join(":")) throw usage(`Bad --voice: ${v.voice}.`, "Use elevenlabs:<voiceId> or kokoro:em_santa|em_alex|ef_dora");
+    voice.engine = engine;
+    voice.voiceId = rest.join(":");
+  }
+  if (v["voice-replies"]) {
+    if (v["voice-replies"] !== "auto" && v["voice-replies"] !== "off") throw usage("--voice-replies takes auto or off.");
+    voice.replies = v["voice-replies"];
+  }
+  if (Object.keys(voice).length) body.voice = voice;
+  if (v["auto-stage"]) {
+    if (v["auto-stage"] !== "on" && v["auto-stage"] !== "off") throw usage("--auto-stage takes on or off.");
+    body.autoStage = v["auto-stage"] === "on";
+  }
+  if (!Object.keys(body).length) throw usage("Nothing to change.", "Use --name, --engine, --model, --prompt, --prompt-file, --env, --connect, --disconnect, --voice, --voice-replies or --auto-stage.");
   const r = await api(agentPath(id), { method: "PATCH", body });
   out(r, () => `${lavender("\u2713")} Updated ${Object.keys(body).join(", ")}.`);
 }
-async function agentsRm(id) {
+async function agentsRm(id, v = {}) {
   id = need(id, "agent id", "ghosty agents rm <agent-id>");
+  requireYesIfHeadless(v.yes, `ghosty agents rm ${id}`);
+  if (!v.yes) {
+    const a = await api(agentPath(id, "?fields=name"));
+    await confirm(`Delete agent ${a.name ?? id}? Its machine, memory and files go too. This can't be undone.`, { expect: a.name || id, retry: `ghosty agents rm ${id}` });
+  }
   out(await api(agentPath(id), { method: "DELETE" }), () => `${lavender("\u2713")} Deleted ${id}.`);
 }
 async function agentsRestart(id) {
@@ -437,6 +495,7 @@ ${table(r.files ?? [], cols)}`);
     }
     case "rm": {
       need(path, "path", ex);
+      await confirm(`Delete ${p} from the agent's machine?`, { yes: v.yes, retry: `ghosty files rm ${id} ${p}` });
       out(await api(agentPath(id, `/files/${p}`), { method: "DELETE" }) ?? { deleted: p }, () => `${lavender("\u2713")} Deleted ${p}`);
       return;
     }
@@ -450,11 +509,38 @@ async function readStdin() {
   for await (const c of process.stdin) parts.push(c);
   return Buffer.concat(parts);
 }
+async function writeSkill(dir, sk) {
+  let bytes = 0;
+  for (const f of sk.files) {
+    const full = join2(dir, f.path);
+    if (relative(dir, full).startsWith("..")) continue;
+    await mkdir2(dirname2(full), { recursive: true });
+    const b = Buffer.from(f.contentBase64, "base64");
+    await writeFile2(full, b);
+    bytes += b.length;
+  }
+  return bytes;
+}
+async function readSkillDir(dir) {
+  const files = (await readdir(dir, { recursive: true, withFileTypes: true })).filter((e) => e.isFile());
+  let markdown;
+  const assets = [];
+  for (const e of files) {
+    const full = join2(e.parentPath, e.name);
+    const rel = relative(dir, full).split("\\").join("/");
+    if (rel === "SKILL.md") markdown = await readFile2(full, "utf8");
+    else if (!rel.split("/").some((part) => part.startsWith("."))) assets.push({ name: rel, contentBase64: (await readFile2(full)).toString("base64") });
+  }
+  if (!markdown) throw usage(`No SKILL.md in ${dir}.`, "A skill folder has SKILL.md at its root (agentskills.io).");
+  return { markdown, assets };
+}
+var trashDir = (id, slug) => join2(process.env.XDG_CONFIG_HOME || join2(homedir2(), ".config"), "ghosty", "trash", id, `${slug}-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`);
 async function skillsCmd(sub, id, slug, v) {
-  const ex = "ghosty skills ls <agent-id> | add <agent-id> <slug> [--file SKILL.md] | rm <agent-id> <slug>";
+  const ex = "ghosty skills ls <agent-id> | get <agent-id> <slug> | add <agent-id> <slug> [--file SKILL.md | --dir FOLDER] | rm <agent-id> <slug>";
   id = need(id, "agent id", ex);
-  switch (sub) {
-    case "ls": {
+  switch (sub ?? "ls") {
+    case "ls":
+    case "list": {
       const r = await api(agentPath(id, "/skills"));
       const short2 = (d) => (d ?? "").replace(/\s+/g, " ").slice(0, 70);
       const rows = [
@@ -463,22 +549,42 @@ async function skillsCmd(sub, id, slug, v) {
       ];
       const more = r.community.filter((c) => !c.installed).length;
       out(r, () => `${table(rows, ["slug", "source", "on", "description"])}
-${dim(`${more} more in the community catalog: ghosty skills add <agent-id> <slug> (--json lists them)`)}`);
+${dim(`${more} more in the community catalog: ghosty skills add <agent-id> <slug> (--json lists them) \xB7 overlaps: ghosty agents doctor ${id}`)}`);
+      return;
+    }
+    case "get": {
+      slug = need(slug, "skill slug", "ghosty skills get <agent-id> <slug> [--out DIR]");
+      const sk = await api(agentPath(id, `/skills/${enc(slug)}`));
+      const dir = v.out ?? slug;
+      const bytes = await writeSkill(dir, sk);
+      out({ slug, saved: dir, files: sk.files.map((f) => f.path), bytes }, () => `${lavender("\u2713")} ${slug} \u2192 ${dir}/ ${dim(`(${sk.files.length} file(s), ${bytes} bytes)`)}`);
       return;
     }
     case "add": {
       slug = need(slug, "skill slug", ex);
-      const body = v.file ? { markdown: await readFile2(v.file, "utf8") } : { fromCatalog: true };
+      if (v.file && v.dir) throw usage("Use --file or --dir, not both.");
+      const body = v.dir ? await readSkillDir(v.dir) : v.file ? { markdown: await readFile2(v.file, "utf8") } : { fromCatalog: true };
       const r = await api(agentPath(id, `/skills/${enc(slug)}`), { method: "PUT", body });
       out(r, () => `${lavender("\u2713")} Skill ${slug} installed.${r?.nota ? dim(` (${r.nota})`) : ""}`);
       return;
     }
     case "rm":
+    case "remove": {
       slug = need(slug, "skill slug", ex);
-      out(await api(agentPath(id, `/skills/${enc(slug)}`), { method: "DELETE" }) ?? { removed: slug }, () => `${lavender("\u2713")} Skill ${slug} removed.`);
+      requireYesIfHeadless(v.yes, `ghosty skills rm ${id} ${slug}`);
+      const sk = await api(agentPath(id, `/skills/${enc(slug)}`)).catch(() => null);
+      await confirm(`Remove skill ${slug} from agent ${id}?${sk ? " A local copy is kept." : ""}`, { yes: v.yes, retry: `ghosty skills rm ${id} ${slug}` });
+      const backup = sk ? trashDir(id, slug) : null;
+      if (sk && backup) await writeSkill(backup, sk);
+      const r = await api(agentPath(id, `/skills/${enc(slug)}`), { method: "DELETE" }) ?? { deleted: slug };
+      const restore = backup ? `ghosty skills add ${id} ${slug} --dir "${backup}"` : null;
+      out({ ...r, backup, restore }, () => `${lavender("\u2713")} Skill ${slug} removed.${restore ? `
+${dim(`Backup: ${backup}
+Undo:   ${restore}`)}` : ""}`);
       return;
+    }
     default:
-      throw usage(`Unknown skills subcommand: ${sub ?? "(none)"}.`, ex);
+      throw usage(`Unknown skills subcommand: ${sub}.`, ex);
   }
 }
 async function mcpCmd(sub, id, v) {
@@ -502,9 +608,11 @@ async function agentsDemo(id, v) {
   if (v.on) body.enabled = true;
   if (v.off) body.enabled = false;
   if (v.turns) body.maxTurns = Number(v.turns);
+  if (v.hours) body.trialHours = Number(v.hours);
   if (v["per-ip"]) body.perIpDay = Number(v["per-ip"]);
   if (v.welcome !== void 0) body.welcome = v.welcome;
   if (v.chips !== void 0) body.chips = v.chips.split("|").map((c) => c.trim()).filter(Boolean);
+  if (v.starter !== void 0) body.starter = v.starter || null;
   if (v.sponsor !== void 0) {
     if (v.sponsor !== "on" && v.sponsor !== "off") throw usage("--sponsor takes on or off.");
     body.sponsor = v.sponsor === "on";
@@ -514,8 +622,9 @@ async function agentsDemo(id, v) {
     d,
     () => [
       `${d.enabled ? lavender("\u25CF on") : dim("\u25CB off")}  ${d.url ?? dim("(no link yet: --slug NAME)")}`,
-      dim(`limits: ${d.maxTurns} messages per visitor \xB7 ${d.perIpDay} per IP per day`),
+      dim(`trial: ${d.trialHours} h from the first message \xB7 cap ${d.maxTurns} messages per visitor \xB7 ${d.perIpDay} per IP per day`),
       d.welcome ? `welcome: ${d.welcome}` : dim("welcome: (default greeting)"),
+      d.starter ? `starter: \u2728 ${d.starter}` : dim("starter: (none)"),
       d.chips.length ? `chips: ${d.chips.join(" | ")}` : dim("chips: (default)"),
       `tried ${d.stats.pruebas} \xB7 messages ${d.stats.mensajes} \xB7 kept ${d.stats.clones} (${d.stats.patrocinados} on your key)`,
       ...d.lastError ? [red(`last failure ${d.lastError.at}: ${d.lastError.message ?? d.lastError.error}`)] : []
@@ -525,7 +634,7 @@ async function agentsDemo(id, v) {
 
 // src/commands/chat.ts
 import { randomUUID } from "node:crypto";
-import { createInterface } from "node:readline/promises";
+import { createInterface as createInterface2 } from "node:readline/promises";
 import { readFile as readFile3 } from "node:fs/promises";
 import { basename } from "node:path";
 
@@ -635,7 +744,7 @@ async function chat(agent, message, v) {
     await turn(agent, sid, piped, first);
     return;
   }
-  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const rl = createInterface2({ input: process.stdin, output: process.stderr });
   info(dim("Type your message. Ctrl-C cancels a turn, Ctrl-D exits."));
   for (; ; ) {
     let line;
@@ -844,7 +953,7 @@ async function call(path, v, init = {}) {
         "x-ghosty-ts": ts,
         "x-ghosty-sig": sig,
         "content-type": "application/json",
-        "user-agent": `ghosty-cli/${"0.7.1"}`
+        "user-agent": `ghosty-cli/${"0.8.0"}`
       },
       body: method === "GET" ? void 0 : raw
     });
@@ -1009,6 +1118,484 @@ async function partnerCmd(sub, a1, a2, v) {
   }
 }
 
+// src/commands/data.ts
+var enc5 = encodeURIComponent;
+var agentPath2 = (id, rest = "") => `/api/v2/agents/${enc5(id)}${rest}`;
+var need2 = (v, what, example) => {
+  if (!v) throw usage(`Missing ${what}.`, `Example: ${example}`);
+  return v;
+};
+var csv = (s) => (s ?? "").split(",").map((x) => x.trim()).filter(Boolean);
+function planText(plan) {
+  return plan.map((p) => p.action === "create" ? `  + ${p.table}  create, ${p.sourceRows} row(s)` : `  ~ ${p.table}  ${p.action} ${p.targetRows} \u2192 ${p.resultRows} row(s)`).join("\n");
+}
+async function dbsImport(id, db, v) {
+  const ex = "ghosty dbs import <agent-id> <db> --from easybits:<db-id> [--tables a,b] [--dry-run]";
+  const m = /^easybits:(.+)$/.exec(v.from ?? "");
+  if (!m) throw usage("Missing or bad --from.", `Example: ${ex}`);
+  const easybitsKey = process.env.EASYBITS_API_KEY;
+  if (!easybitsKey) throw usage("EASYBITS_API_KEY is not set.", "Export your EasyBits API key (https://www.easybits.cloud/dash/developer) and run again.");
+  const body = { from: "easybits", sourceDb: m[1], easybitsKey, mode: v.append ? "append" : "replace", ...v.tables ? { tables: csv(v.tables) } : {} };
+  const path = agentPath2(id, `/dbs/${enc5(db)}/import`);
+  const dry = await api(path, { body: { ...body, dryRun: true } });
+  if (v["dry-run"]) return out(dry, () => `${dry.db} \u2190 easybits:${m[1]}
+${planText(dry.plan)}
+${dim("Dry run: nothing changed.")}`);
+  const destructive = dry.plan.some((p) => p.action === "replace" && p.targetRows > 0);
+  if (destructive) await confirm(`${planText(dry.plan)}
+Replace the rows above in ${dry.db}?`, { yes: v.yes, retry: `ghosty dbs import ${id} ${db} --from ${v.from}${v.tables ? ` --tables ${v.tables}` : ""}` });
+  const r = await api(path, { body });
+  return out(r, () => `${planText(r.plan)}
+${lavender("\u2713")} Imported into ${r.db}. ${dim("Run it again any time: with replace it ends in the same state.")}`);
+}
+async function dbsCmd(sub, id, db, rest, v) {
+  const ex = "ghosty dbs ls <agent-id>";
+  id = need2(id, "agent id", ex);
+  switch (sub ?? "ls") {
+    case "ls":
+    case "list": {
+      const r = await api(agentPath2(id, "/dbs"));
+      const rows = r.dbs.map((d) => ({ name: d.name, access: d.granted ? "granted" : "\u2014", "writes from customers": d.granted ? d.externalWriteTables.join(", ") || "(none)" : "", id: d.id }));
+      return out(r.dbs, () => rows.length ? table(rows, ["name", "access", "writes from customers", "id"]) : dim("This account has no databases yet: create one at /app/dbs."));
+    }
+    case "tables": {
+      db = need2(db, "database (id or name)", "ghosty dbs tables <agent-id> <db>");
+      const r = await api(agentPath2(id, `/dbs/${enc5(db)}`));
+      const ext = new Set(r.externalWriteTables);
+      const rows = r.tables.map((t) => ({ table: t.name, rows: t.rows, "customer writes": ext.has(t.name) ? "yes" : "", columns: t.columns.map((c) => `${c.name}${c.pk ? "*" : ""}`).join(", ") }));
+      return out(r, () => `${bold(r.name)} ${r.granted ? lavender("granted") : dim("not granted")}
+${table(rows, ["table", "rows", "customer writes", "columns"])}`);
+    }
+    case "query":
+    case "sql": {
+      db = need2(db, "database (id or name)", 'ghosty dbs query <agent-id> <db> "SELECT \u2026"');
+      const sql = need2(rest.join(" ").trim() || void 0, "SQL", 'ghosty dbs query <agent-id> <db> "SELECT * FROM t LIMIT 10"');
+      const r = await api(agentPath2(id, `/dbs/${enc5(db)}/query`), { body: { sql, args: v.arg ?? [], write: v.write === true } }).catch((e) => {
+        if (e instanceof CliError && !v.write && /lectura|SELECT|escribir/i.test(e.message)) throw new CliError(e.message, EXIT.API, "To write on purpose, add --write.");
+        throw e;
+      });
+      return out(r, () => {
+        if (!r.cols.length) return `${lavender("\u2713")} ${r.affected} row(s) affected ${dim(`(${Math.round(r.ms)} ms)`)}`;
+        const rows = r.rows.map((row) => Object.fromEntries(r.cols.map((c, i) => [c, row[i]])));
+        return `${table(rows, r.cols)}
+${dim(`${rows.length} row(s) \xB7 ${Math.round(r.ms)} ms`)}`;
+      });
+    }
+    case "grant": {
+      db = need2(db, "database (id or name)", "ghosty dbs grant <agent-id> <db> [--external-write t1,t2]");
+      const body = v["external-write"] !== void 0 ? { externalWriteTables: csv(v["external-write"]) } : {};
+      const r = await api(agentPath2(id, `/dbs/${enc5(db)}`), { method: "PUT", body });
+      return out(r, () => `${lavender("\u2713")} ${r.name} granted. ${dim(`From customer channels it writes to: ${r.externalWriteTables.join(", ") || "nothing (read only)"}.`)}`);
+    }
+    case "import": {
+      db = need2(db, "database (id or name)", "ghosty dbs import <agent-id> <db> --from easybits:<db-id>");
+      return dbsImport(id, db, v);
+    }
+    case "revoke": {
+      db = need2(db, "database (id or name)", "ghosty dbs revoke <agent-id> <db>");
+      const r = await api(agentPath2(id, `/dbs/${enc5(db)}`), { method: "DELETE" });
+      return out(r, () => `${lavender("\u2713")} ${r.name} revoked. ${dim(`Undo: ghosty dbs grant ${id} ${r.name}`)}`);
+    }
+    default:
+      throw usage(`Unknown dbs subcommand: ${sub}.`, "Try: ghosty dbs ls | tables | query | import | grant | revoke   (ghosty dbs --help)");
+  }
+}
+async function agentDocsCmd(sub, id, doc, v) {
+  id = need2(id, "agent id", "ghosty agents docs ls <agent-id>");
+  switch (sub ?? "ls") {
+    case "ls":
+    case "list": {
+      const r = await api(agentPath2(id, "/documents"));
+      const rows = r.documents.map((d) => ({ name: d.name, access: d.granted ? d.mode === "write" ? "read+replace" : "read" : "\u2014", delivers: d.granted ? d.deliverable ? "yes" : "no" : "", id: d.id }));
+      return out(r.documents, () => rows.length ? table(rows, ["name", "access", "delivers", "id"]) : dim("This account has no documents yet: upload them at /app/datos."));
+    }
+    case "grant": {
+      doc = need2(doc, "document (id or exact name)", 'ghosty agents docs grant <agent-id> "Cat\xE1logo.pdf"');
+      const body = {};
+      if (v.write) body.mode = "write";
+      if (v["no-deliver"]) body.deliverable = false;
+      else if (v.deliver) body.deliverable = true;
+      const r = await api(agentPath2(id, `/documents/${enc5(doc)}`), { method: "PUT", body });
+      return out(r, () => `${lavender("\u2713")} ${r.name}: ${r.mode === "write" ? "reads and replaces it" : "reads it"}${r.deliverable ? ", and can send it" : ", never sends it"}.`);
+    }
+    case "revoke": {
+      doc = need2(doc, "document (id or exact name)", 'ghosty agents docs revoke <agent-id> "Cat\xE1logo.pdf"');
+      const r = await api(agentPath2(id, `/documents/${enc5(doc)}`), { method: "DELETE" });
+      return out(r, () => `${lavender("\u2713")} ${r.name} revoked. ${dim(`Undo: ghosty agents docs grant ${id} "${r.name}"`)}`);
+    }
+    default:
+      throw usage(`Unknown agents docs subcommand: ${sub}.`, "Try: ghosty agents docs ls | grant | revoke");
+  }
+}
+async function turnsCmd(sub, id, v) {
+  if (sub && sub !== "ls" && sub !== "list") throw usage(`Unknown turns subcommand: ${sub}.`, "Try: ghosty turns ls <agent-id> --errors --since 1h");
+  id = need2(id, "agent id", "ghosty turns ls <agent-id> --errors --since 1h");
+  const q = new URLSearchParams();
+  const status = v.errors ? "error" : v.status;
+  if (status) q.set("state", status);
+  if (v.since) q.set("since", v.since);
+  q.set("limit", v.limit ?? "20");
+  const r = await api(agentPath2(id, `/turns?${q}`));
+  const when = (s) => s.slice(0, 16).replace("T", " ");
+  const rows = r.turns.map((t) => ({
+    started: when(t.startedAt),
+    state: t.state === "error" ? red(t.state) : t.state,
+    secs: t.ms == null ? "" : Math.round(t.ms / 1e3),
+    from: t.surface ?? "",
+    session: t.sessionId.slice(0, 24),
+    error: (t.error ?? "").replace(/\s+/g, " ").slice(0, 90)
+  }));
+  const tally = Object.entries(r.counts).map(([k, n]) => `${k} ${n}`).join(" \xB7 ");
+  out(r, () => rows.length ? `${table(rows, ["started", "state", "secs", "from", "session", "error"])}
+${dim(`${v.since ? `since ${v.since}: ` : ""}${tally}`)}` : dim(`No ${status ?? ""} turns${v.since ? ` since ${v.since}` : ""}.`));
+}
+async function agentsDoctor(id, v) {
+  id = need2(id, "agent id", "ghosty agents doctor <agent-id>");
+  const r = await api(agentPath2(id, "/doctor"));
+  const problems = r.summary.warn + r.summary.error;
+  if (globals.json) out(r);
+  else {
+    const mark = { ok: lavender("\u2713"), warn: "\x1B[33m!\x1B[0m", error: red("\u2717") };
+    const lines = [];
+    for (const c of r.checks) {
+      if (c.level === "ok" && !v.verbose) continue;
+      lines.push(`${process.stdout.isTTY ? mark[c.level] : { ok: "\u2713", warn: "!", error: "\u2717" }[c.level]} ${c.title}`);
+      if (c.detail && c.level !== "ok") lines.push(...c.detail.split("\n").map((l) => `    ${dim(l)}`));
+      if (c.fix && c.level !== "ok") lines.push(`    ${dim("fix:")} ${c.fix}`);
+    }
+    lines.push(problems ? `Doctor found ${r.summary.error} error(s) and ${r.summary.warn} warning(s) in ${r.checks.length} checks.` : `${lavender("\u2713")} No issues found (${r.checks.length} checks).`);
+    process.stdout.write(lines.join("\n") + "\n");
+  }
+  if (problems) {
+    if (!globals.json) info(dim("Exit 1: problems found."));
+    process.exit(EXIT.API);
+  }
+}
+
+// src/commands/credentials.ts
+async function hiddenPrompt(label) {
+  process.stderr.write(label);
+  const stdin = process.stdin;
+  stdin.setRawMode(true);
+  stdin.resume();
+  stdin.setEncoding("utf8");
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const onData = (chunk) => {
+      for (const ch of chunk) {
+        if (ch === "\r" || ch === "\n") {
+          stdin.setRawMode(false);
+          stdin.pause();
+          stdin.off("data", onData);
+          process.stderr.write("\n");
+          return resolve(value);
+        }
+        if (ch === "") {
+          stdin.setRawMode(false);
+          process.stderr.write("\n");
+          return reject(usage("Cancelled."));
+        }
+        if (ch === "\x7F") value = value.slice(0, -1);
+        else value += ch;
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+async function readSecret(provider, fromEnv) {
+  if (fromEnv) {
+    const v = process.env[fromEnv];
+    if (!v) throw usage(`$${fromEnv} is empty or not set.`, `Example: export ${fromEnv}=\u2026 && ghosty credentials set ${provider} --from-env ${fromEnv}`);
+    return v;
+  }
+  if (!process.stdin.isTTY) {
+    const parts = [];
+    for await (const c of process.stdin) parts.push(c);
+    return Buffer.concat(parts).toString("utf8").replace(/\r?\n$/, "");
+  }
+  if (!canPrompt()) throw usage("No value to save.", `Pipe it (\u2026 | ghosty credentials set ${provider}) or use --from-env VAR.`);
+  return hiddenPrompt(`${provider} key (hidden): `);
+}
+async function credentialsCmd2(sub, provider, v) {
+  switch (sub ?? "ls") {
+    case "ls":
+    case "list": {
+      const r = await api("/api/v2/me/credentials");
+      const rows = r.credentials.map((c) => ({ provider: c.provider, set: c.configured ? `\u2026${c.lastFour ?? ""}` : "\u2014", updated: c.updatedAt?.slice(0, 10) ?? "" }));
+      return out(r.credentials, () => table(rows, ["provider", "set", "updated"]));
+    }
+    case "set": {
+      if (!provider) throw usage("Missing provider.", "Example: ghosty credentials set elevenlabs --from-env ELEVENLABS_API_KEY   (ghosty credentials ls lists them)");
+      const key = (await readSecret(provider, v["from-env"])).trim();
+      if (!key) throw usage("Empty key: nothing saved.");
+      const r = await api(`/api/v2/me/credentials/${encodeURIComponent(provider)}`, { method: "PUT", body: { key } });
+      return out(r, () => `${lavender("\u2713")} ${provider} saved ${dim(`(\u2026${r.lastFour ?? ""}). Agents with a machine pick it up on their next turn.`)}`);
+    }
+    case "rm":
+    case "remove": {
+      if (!provider) throw usage("Missing provider.", "Example: ghosty credentials rm elevenlabs");
+      await confirm(`Remove your ${provider} key? Agents using it stop working until you set another.`, { yes: v.yes, retry: `ghosty credentials rm ${provider}` });
+      const r = await api(`/api/v2/me/credentials/${encodeURIComponent(provider)}`, { method: "DELETE" });
+      return out(r, () => `${lavender("\u2713")} ${provider} removed.`);
+    }
+    default:
+      throw usage(`Unknown credentials subcommand: ${sub}.`, "Try: ghosty credentials ls | set | rm   (ghosty credentials --help)");
+  }
+}
+
+// src/commands/channels.ts
+var enc6 = encodeURIComponent;
+var digits = (s) => s.replace(/\D/g, "");
+function find(nums, ref) {
+  const d = digits(ref);
+  const hit = nums.find((n) => n.id === ref) ?? nums.find((n) => n.label.toLowerCase() === ref.toLowerCase()) ?? (d.length >= 6 ? nums.find((n) => digits(n.label).endsWith(d)) : void 0);
+  if (!hit) throw usage(`No WhatsApp number "${ref}" for this agent.`, nums.length ? `Available: ${nums.map((n) => n.label).join(", ")}` : "Pair a number first in the web (the agent's Channels page).");
+  return hit;
+}
+async function channelsCmd(kind, sub, id, ref, v) {
+  if (kind !== "whatsapp" && kind !== "wa") throw usage(`Unknown channel: ${kind ?? "(none)"}.`, "Try: ghosty channels whatsapp ls <agent-id>");
+  if (!id) throw usage("Missing agent id.", "Example: ghosty channels whatsapp ls <agent-id>");
+  if (sub === "enable" && !v["dry-run"]) requireYesIfHeadless(v.yes, `ghosty channels whatsapp enable ${id} ${ref ?? "<number>"}`);
+  const path = `/api/v2/agents/${enc6(id)}/whatsapp`;
+  const cur = await api(path);
+  if (!sub || sub === "ls" || sub === "list") {
+    const rows = cur.numbers.map((n2) => ({ number: n2.label, answers: n2.mine ? lavender("this agent") : n2.takenByOther ? "another agent" : dim("nobody (silent)"), id: n2.id }));
+    return out(cur, () => rows.length ? table(rows, ["number", "answers", "id"]) : dim(`No WhatsApp Business numbers yet. Pair one at ${cur.salesUrl}`));
+  }
+  if (sub !== "enable" && sub !== "disable") throw usage(`Unknown subcommand: ${sub}.`, "Try: ghosty channels whatsapp ls | enable | disable <agent-id> <number>");
+  if (!ref) throw usage("Missing number.", `Example: ghosty channels whatsapp ${sub} ${id} +52 55 1234 5678`);
+  const n = find(cur.numbers, ref);
+  const on = sub === "enable";
+  if (on === n.mine) return out({ changed: 0, number: n.label, answers: on }, () => dim(`Nothing to do: ${n.label} is already ${on ? "answered by this agent" : "not answered by it"}.`));
+  const plan = on ? `+ ${n.label}: this agent starts answering its customers${n.takenByOther ? " (takes it from the agent answering today)" : ""}` : `- ${n.label}: this agent stops answering (messages are still logged)`;
+  if (v["dry-run"]) return out({ dryRun: true, plan: [plan] }, () => `${plan}
+${dim("Dry run: nothing changed.")}`);
+  if (on) await confirm(`${bold(plan)}
+Real customers will get answers from this agent.`, { yes: v.yes, expect: digits(n.label).slice(-4) || n.id, retry: `ghosty channels whatsapp enable ${id} ${ref}` });
+  const wanted = cur.numbers.filter((x) => x.id === n.id ? on : x.mine).map((x) => x.id);
+  const r = await api(path, { method: "PUT", body: { numbers: wanted } });
+  return out(r, () => `${lavender("\u2713")} ${plan.slice(2)}`);
+}
+
+// src/commands/board.ts
+async function boardCmd(sub, id, v) {
+  if (sub !== "archive") throw usage(`Unknown board subcommand: ${sub ?? "(none)"}.`, "Try: ghosty board archive <agent-id> --integration prueba --dry-run");
+  if (!id) throw usage("Missing agent id.", "Example: ghosty board archive <agent-id> --integration prueba --dry-run");
+  const filter = { ...v.integration ? { integration: v.integration } : {}, ...v.column ? { column: v.column } : {}, ...v.before ? { before: v.before } : {} };
+  if (!Object.keys(filter).length) throw usage("Add at least one filter: --integration, --column or --before.", "A filter-less archive would empty the board.");
+  const retry = `ghosty board archive ${id} ${Object.entries(filter).map(([k, x]) => `--${k} ${JSON.stringify(x)}`).join(" ")}`;
+  if (!v["dry-run"]) requireYesIfHeadless(v.yes, retry);
+  const path = `/api/v2/agents/${encodeURIComponent(id)}/board/archive`;
+  const plan = await api(path, { body: { ...filter, dryRun: true } });
+  const sample = () => table(plan.sample.map((c) => ({ name: c.name ?? "", phone: c.phone, column: c.estado_label ?? "" })), ["name", "phone", "column"]);
+  if (v["dry-run"] || plan.matched === 0) {
+    return out(plan, () => plan.matched ? `${sample()}
+${dim(`Would archive ${plan.matched} card(s) on \xAB${plan.board}\xBB. Dry run: nothing changed.`)}` : dim(`No cards match on \xAB${plan.board}\xBB.`));
+  }
+  await confirm(`${sample()}
+Archive ${plan.matched} card(s) on \xAB${plan.board}\xBB? (reversible: a new message brings a card back)`, { yes: v.yes, retry });
+  const r = await api(path, { body: filter });
+  out(r, () => `${lavender("\u2713")} Archived ${r.archived} card(s) on \xAB${r.board}\xBB.`);
+}
+
+// src/help.ts
+var DOCS = "https://www.ghosty.studio/docs/cli";
+var HELPS = {
+  agents: {
+    summary: "Create, inspect, change, check and delete agents.",
+    usage: [
+      "ghosty agents ls",
+      "ghosty agents create --name NAME [--engine E] [--model M] [--prompt TEXT | --prompt-file FILE] [--env K=V,\u2026]",
+      "ghosty agents get <agent-id> [--fields name,model,prompt]",
+      "ghosty agents set <agent-id> [--name] [--engine] [--model] [--prompt | --prompt-file] [--env K=V,\u2026] [--connect ID,\u2026] [--disconnect ID,\u2026] [--voice E:ID] [--voice-replies auto|off] [--auto-stage on|off]",
+      "ghosty agents doctor <agent-id> [--verbose]",
+      "ghosty agents docs ls|grant|revoke <agent-id> [doc] [--write] [--no-deliver]",
+      "ghosty agents restart <agent-id>",
+      "ghosty agents demo <agent-id> [--slug NAME] [--on | --off] \u2026",
+      "ghosty agents rm <agent-id> [--yes]"
+    ],
+    flags: [
+      ["--fields a,b", "get: return only these fields"],
+      ["--voice E:ID", "set: voice for voice notes: elevenlabs:<voiceId> or kokoro:em_santa|em_alex|ef_dora"],
+      ["--voice-replies M", "set: auto = answer with a voice note when the customer sends or asks for audio; off = always text"],
+      ["--auto-stage on|off", "set: move board cards by itself after each customer turn (one extra model call per turn)"],
+      ["--verbose", "doctor: also list the checks that passed"],
+      ["--write", "docs grant: the agent may replace the document (default: read only)"],
+      ["--no-deliver", "docs grant: it can read it but never send it to whoever writes"],
+      ["--yes", "rm: skip the confirmation (required without a terminal)"]
+    ],
+    examples: [
+      "ghosty agents doctor cmu7pgbyr0001gee3ruk172mm",
+      "ghosty agents set <id> --prompt-file PROMPT.md",
+      "ghosty agents set <id> --voice elevenlabs:21m00Tcm4TlvDq8ikWAM --voice-replies auto --auto-stage on",
+      'ghosty agents docs grant <id> "Cat\xE1logo 2026.pdf"',
+      "ghosty agents docs grant <id> precios.xlsx --write --no-deliver"
+    ],
+    notes: ["doctor exits 1 when it finds a problem, so it can gate a script or CI."],
+    learn: `${DOCS}#agents`
+  },
+  skills: {
+    summary: "Skills of an agent (agentskills.io format: a folder with SKILL.md).",
+    usage: [
+      "ghosty skills ls <agent-id>",
+      "ghosty skills get <agent-id> <slug> [--out DIR]",
+      "ghosty skills add <agent-id> <slug> [--file SKILL.md | --dir FOLDER]",
+      "ghosty skills rm <agent-id> <slug> [--yes]"
+    ],
+    flags: [
+      ["--out DIR", "get: folder to write into (default ./<slug>)"],
+      ["--file FILE", "add: upload one SKILL.md"],
+      ["--dir FOLDER", "add: upload a whole skill folder (SKILL.md + assets); restores a backup"],
+      ["--yes", "rm: skip the confirmation (required without a terminal)"]
+    ],
+    examples: [
+      "ghosty skills get <id> cotizar --out ./backup/cotizar",
+      "ghosty skills add <id> cotizar --dir ./backup/cotizar",
+      "ghosty skills add <id> pdf-doc          # from the community catalog",
+      "ghosty skills rm <id> cotizacion        # keeps a local copy first"
+    ],
+    notes: ["rm saves a copy under ~/.config/ghosty/trash/ and prints the command that restores it."],
+    learn: `${DOCS}#skills`
+  },
+  dbs: {
+    summary: "Databases an agent can use, and what it may write from customer channels.",
+    usage: [
+      "ghosty dbs ls <agent-id>",
+      "ghosty dbs tables <agent-id> <db>",
+      'ghosty dbs query <agent-id> <db> "SQL" [--arg V]\u2026 [--write]',
+      "ghosty dbs import <agent-id> <db> --from easybits:<db-id> [--tables a,b] [--append] [--dry-run] [--yes]",
+      "ghosty dbs grant <agent-id> <db> [--external-write t1,t2]",
+      "ghosty dbs revoke <agent-id> <db>"
+    ],
+    flags: [
+      ["--arg V", "query: value for a ? placeholder (repeatable)"],
+      ["--write", "query: allow INSERT/UPDATE/DELETE/DDL (default: read only)"],
+      ["--external-write t1,t2", 'grant: tables it may write from WhatsApp/Messenger ("" = none)'],
+      ["--from easybits:ID", "import: source database in EasyBits (key from $EASYBITS_API_KEY)"],
+      ["--tables a,b", "import: only these tables (default: all)"],
+      ["--append", "import: add rows instead of replacing them (replace is the idempotent default)"],
+      ["-n, --dry-run", "import: print the plan (+ create, ~ replace N \u2192 M rows), change nothing"]
+    ],
+    examples: [
+      "ghosty dbs ls <id>",
+      "ghosty dbs tables <id> totequim",
+      'ghosty dbs query <id> totequim "SELECT count(*) AS n FROM productos"',
+      "ghosty dbs grant <id> totequim --external-write cotizaciones,folio",
+      "ghosty dbs import <id> totequim --from easybits:6a10c84c\u2026 --dry-run   # reads $EASYBITS_API_KEY"
+    ],
+    notes: ["<db> is the database id or its name. From owner channels the agent reads and writes everything granted."],
+    learn: `${DOCS}#dbs`
+  },
+  turns: {
+    summary: "An agent's recent turns: what answered, what failed and why.",
+    usage: ["ghosty turns ls <agent-id> [--errors | --status STATE] [--since 1h] [--limit N]"],
+    flags: [
+      ["--errors", "only failed turns (same as --status error)"],
+      ["--status S", "running | done | stopped | error"],
+      ["--since T", "30m, 1h, 2d or an ISO date"],
+      ["--limit N", "max rows (default 20, max 500)"]
+    ],
+    examples: ["ghosty turns ls <id> --errors --since 1h", "ghosty turns ls <id> --json --limit 100"],
+    learn: `${DOCS}#turns`
+  },
+  files: {
+    summary: "Files in the agent's machine.",
+    usage: ["ghosty files ls <agent-id> [dir]", "ghosty files get <agent-id> <path> [--out LOCAL]", "ghosty files put <agent-id> <path> [--file LOCAL | < stdin]", "ghosty files rm <agent-id> <path> [--yes]"],
+    examples: ["ghosty files put <id> knowledge/precios.md --file precios.md", "cat notas.md | ghosty files put <id> notas.md"],
+    learn: `${DOCS}#files`
+  },
+  mcp: {
+    summary: "MCP servers of an agent. set REPLACES the whole list.",
+    usage: ["ghosty mcp get <agent-id>", "ghosty mcp set <agent-id> --file servers.json"],
+    examples: ["ghosty mcp get <id> > servers.json && $EDITOR servers.json && ghosty mcp set <id> --file servers.json"],
+    learn: `${DOCS}#mcp`
+  },
+  try: {
+    summary: "One test turn; prints the whole answer.",
+    usage: ['ghosty try <agent-id> "message" [--session ID] [--reset] [--whatsapp]'],
+    examples: ['ghosty try <id> "\xBFcu\xE1nto cuesta el gal\xF3n?"', "ghosty try <id> --reset --session s1"],
+    learn: `${DOCS}#try`
+  },
+  chat: {
+    summary: "Stream a conversation; with no message it is interactive.",
+    usage: ['ghosty chat <agent-id> ["message"] [--conversation ID]', "ghosty conversations ls <agent-id>"],
+    examples: ['ghosty chat <id> "hola"', "ghosty chat <id>"],
+    learn: `${DOCS}#chat`
+  },
+  schedule: {
+    summary: "Turns that run later, on the agent's own clock.",
+    usage: ['ghosty schedule add <agent-id> "what to do" --in 30m | --at ISO [--every 12h --until ISO] [--conversation ID] [--title T]', "ghosty schedule ls <agent-id>", "ghosty schedule rm <agent-id> <schedule-id>"],
+    examples: ['ghosty schedule add <id> "revisa pedidos pendientes" --every 12h --in 1h'],
+    learn: `${DOCS}#schedule`
+  },
+  me: {
+    summary: "Your account: files and usage.",
+    usage: ["ghosty me files ls|upload|rm [--kind image|video|audio|document|other]", "ghosty usage"],
+    examples: ["ghosty me files ls --kind document"],
+    learn: `${DOCS}#me`
+  }
+};
+HELPS.credentials = {
+  summary: "Provider keys in your account's vault (encrypted; only the last 4 characters come back).",
+  usage: ["ghosty credentials ls", "ghosty credentials set <provider> [--from-env VAR | < stdin]", "ghosty credentials rm <provider> [--yes]"],
+  flags: [
+    ["--from-env VAR", "set: read the key from this environment variable (pass its NAME)"],
+    ["--yes", "rm: skip the confirmation"]
+  ],
+  examples: [
+    "ghosty credentials set elevenlabs            # hidden prompt",
+    "ghosty credentials set mercadopago --from-env MP_ACCESS_TOKEN",
+    "op read op://vault/claude/token | ghosty credentials set anthropic-oauth"
+  ],
+  notes: ["The key is never accepted as an argument: it would stay in your shell history and in `ps`."],
+  learn: `${DOCS}#credentials`
+};
+HELPS.creds = HELPS.credentials;
+HELPS.channels = {
+  summary: "Which WhatsApp Business numbers an agent answers. Pair new numbers in the web.",
+  usage: ["ghosty channels whatsapp ls <agent-id>", "ghosty channels whatsapp enable <agent-id> <number> [--dry-run] [--yes]", "ghosty channels whatsapp disable <agent-id> <number> [--dry-run]"],
+  flags: [
+    ["-n, --dry-run", "print the plan (+ starts answering, - stops) and change nothing"],
+    ["--yes", "enable: skip typing the last 4 digits (required without a terminal)"]
+  ],
+  examples: ["ghosty channels whatsapp ls <id>", "ghosty channels whatsapp enable <id> 5512345678 --dry-run", "ghosty channels whatsapp disable <id> 5512345678"],
+  notes: ["<number> is its id, its label or its last digits. One number, one agent: enabling it takes it from the other agent.", "Disabling keeps logging messages; nobody answers them."],
+  learn: `${DOCS}#channels`
+};
+HELPS.board = {
+  summary: "The agent's sales board. It belongs to the WORKSPACE: you must be a member, a shared agent is not enough.",
+  usage: ["ghosty board archive <agent-id> [--integration ID] [--column NAME] [--before 30d|ISO] [--dry-run] [--yes]"],
+  flags: [
+    ["--integration ID", "cards from this channel/integration (e.g. prueba)"],
+    ["--column NAME", "cards in this column"],
+    ["--before T", "cards with no activity since T (30d, 12h or an ISO date)"],
+    ["-n, --dry-run", "count and show a sample, change nothing"],
+    ["--yes", "skip the confirmation (required without a terminal)"]
+  ],
+  examples: ["ghosty board archive <id> --integration prueba --dry-run", "ghosty board archive <id> --column Perdido --before 30d --yes"],
+  notes: ["Archiving is reversible: when the customer writes again the card comes back. At least one filter is required."],
+  learn: `${DOCS}#board`
+};
+HELPS.conversations = HELPS.chat;
+HELPS.usage = HELPS.me;
+function helpText(cmd) {
+  const h = HELPS[cmd];
+  if (!h) return void 0;
+  const section = (t, lines) => [bold(t), ...lines.map((l) => `  ${l}`), ""];
+  const w = Math.max(0, ...(h.flags ?? []).map(([f]) => f.length)) + 2;
+  return [
+    h.summary,
+    "",
+    ...section("USAGE", h.usage),
+    ...h.flags?.length ? section("FLAGS", h.flags.map(([f, d]) => `${f.padEnd(w)}${d}`)) : [],
+    ...section("EXAMPLES", h.examples.map((e) => `$ ${e}`)),
+    ...h.notes?.length ? section("NOTES", h.notes) : [],
+    bold("LEARN MORE"),
+    `  Add --json for machine output. Exit codes: 0 ok \xB7 1 API error \xB7 2 usage \xB7 3 not signed in.`,
+    `  ${dim(h.learn ?? DOCS)}`
+  ].join("\n");
+}
+
 // src/index.ts
 var HELP = `${bold("Usage:")} ghosty <command> [options]
 
@@ -1025,20 +1612,27 @@ ${bold("Agents")}
   agents get <id>           Show an agent's config            [--fields name,model,prompt]
   agents set <id>           Change identity or engine         [--name] [--engine] [--model] [--prompt | --prompt-file FILE] [--env K=V,\u2026]
                             [--connect google-drive,\u2026] [--disconnect \u2026]  give/remove access to your connectors
-  agents rm <id>            Delete an agent (owner only)
+                            [--voice elevenlabs:ID | kokoro:em_santa] [--voice-replies auto|off] [--auto-stage on|off]
+  agents doctor <id>        Check the config: overlapping skills, tools the prompt names, broken grants, failing turns
+  agents docs ls|grant|revoke <id> [doc]   Documents it reads and may send   [--write] [--no-deliver]
+  agents rm <id>            Delete an agent (owner only; asks you to type its name, or --yes)
   agents restart <id>       Restart an ACP agent (needsRestart) so it loads new skills
   agents demo <id>          Public demo link /p/<slug>: anyone tries it without an account, "Keep it" clones it to theirs
-                            [--slug NAME] [--on | --off] [--turns N] [--per-ip N] [--welcome TEXT] [--chips "a|b|c"] [--sponsor on|off]
+                            [--slug NAME] [--on | --off] [--hours N] [--turns N] [--per-ip N] [--welcome TEXT] [--chips "a|b|c"] [--starter TEXT] [--sponsor on|off]
 
 ${bold("Configure an agent")}
   files ls|get|put|rm <id> [path]    Files in the agent's machine   [--file LOCAL] [--out LOCAL]
-  skills ls|add|rm <id> [slug]       Skills (add from catalog, or --file SKILL.md)
+  skills ls|get|add|rm <id> [slug]   Skills (add from catalog, --file SKILL.md or --dir FOLDER; rm keeps a copy)
+  dbs ls|tables|query|import|grant|revoke <id> [db]   Databases it uses   [--write] [--external-write t1,t2] [--from easybits:ID --dry-run]
   mcp get|set <id>                   MCP servers                    [--file servers.json]
+  channels whatsapp ls|enable|disable <id> [number]   Which WhatsApp Business numbers it answers   [--dry-run]
+  board archive <id>        Archive cards in bulk (reversible)   --integration X | --column X | --before 30d   [--dry-run]
 
 ${bold("Talk to an agent")}
   try <id> "message"        One test turn, prints the full answer   [--session] [--reset] [--whatsapp]
   chat <id> ["message"]     Stream a conversation (no message = interactive)   [--conversation ID]
   conversations ls <id>     List conversations
+  turns ls <id>             Recent turns and why they failed   [--errors] [--since 1h] [--limit N]
 
 ${bold("Schedule turns")}  ${dim("(each run lands in a conversation and notifies your phone; an answer of exactly OK stays silent)")}
   schedule ls <id>                   Pending turns and recent runs
@@ -1050,18 +1644,26 @@ ${bold("Partners")}  ${dim("(give an agent to each of YOUR customers \u2014 see:
 
 ${bold("Your account")}
   me files ls|upload|rm     Files in your account        [--kind image|video|audio|document|other]
+  credentials ls|set|rm [provider]   Provider keys in your vault (hidden prompt, stdin or --from-env VAR; never as an argument)
   docs [topic]              Open the docs
 
 ${bold("Global options")}
   --json                    Machine-readable output (stdout is JSON only)
   --token <token>           Use this token (or env GHOSTY_TOKEN). A gat_\u2026 agent token reaches only that agent.
   --profile <name>          Use a separate saved session (or env GHOSTY_PROFILE), e.g. one per account
-  -h, --help                Show help
+  --yes                     Skip confirmations (required for rm without a terminal)
+  -h, --help                Show help (also: ghosty <command> --help, ghosty help <command>)
   -v, --version             Show version
 
 ${bold("Exit codes")}  0 ok \xB7 1 API error \xB7 2 usage error \xB7 3 not signed in
 ${dim("Note: `ghosty` may collide with another binary on your PATH (e.g. the Ghosty TUI). Check with `which -a ghosty`; run `npx @ghostystudio/cli` to be sure.")}
 ${dim("Docs: https://www.ghosty.studio/docs/cli")}`;
+var COMMANDS = ["login", "logout", "whoami", "usage", "agents", "files", "skills", "mcp", "dbs", "turns", "try", "chat", "conversations", "schedule", "partner", "me", "channels", "board", "credentials", "docs", "help"];
+var AGENTS_SUBS = ["ls", "create", "get", "set", "doctor", "docs", "rm", "restart", "demo"];
+function unknown(what, input, known, helpCmd) {
+  const s = suggest(input, known);
+  return usage(`Unknown command: ${what}.`, s ? `Did you mean "${s}"? Run: ${helpCmd}` : `Run: ${helpCmd}`);
+}
 function showHelp() {
   if (process.stdout.isTTY && !process.env.NO_COLOR && !globals.json) process.stdout.write(BANNER + "\n\n");
   process.stdout.write(HELP + "\n");
@@ -1108,19 +1710,47 @@ async function main() {
       on: { type: "boolean" },
       off: { type: "boolean" },
       turns: { type: "string" },
+      hours: { type: "string" },
       "per-ip": { type: "string" },
       welcome: { type: "string" },
       chips: { type: "string" },
-      sponsor: { type: "string" }
+      starter: { type: "string" },
+      sponsor: { type: "string" },
+      yes: { type: "boolean", short: "y" },
+      dir: { type: "string" },
+      arg: { type: "string", multiple: true },
+      write: { type: "boolean" },
+      "external-write": { type: "string" },
+      "no-deliver": { type: "boolean" },
+      deliver: { type: "boolean" },
+      errors: { type: "boolean" },
+      status: { type: "string" },
+      since: { type: "string" },
+      limit: { type: "string" },
+      verbose: { type: "boolean" },
+      voice: { type: "string" },
+      "voice-replies": { type: "string" },
+      "auto-stage": { type: "string" },
+      "from-env": { type: "string" },
+      "dry-run": { type: "boolean", short: "n" },
+      integration: { type: "string" },
+      from: { type: "string" },
+      tables: { type: "string" },
+      append: { type: "boolean" },
+      column: { type: "string" },
+      before: { type: "string" }
     }
   });
   globals.json = Boolean(v.json);
   const tokens = splitTokens(pos, v);
   globals.token = tokens.session;
   globals.profile = v.profile;
-  if (v.version) return out({ version: "0.7.1" }, () => "0.7.1");
+  if (v.version) return out({ version: "0.8.0" }, () => "0.8.0");
   const [cmd, sub, a1, a2] = pos;
   if (cmd === "partner" && (v.help || !sub || sub === "help")) return out({ help: PARTNER_HELP }, () => PARTNER_HELP);
+  const topic = cmd === "help" ? sub : v.help ? cmd : void 0;
+  if (topic === "partner") return out({ help: PARTNER_HELP }, () => PARTNER_HELP);
+  if (topic && helpText(topic)) return out({ help: helpText(topic) }, () => helpText(topic));
   if (!cmd || v.help || cmd === "help") return showHelp();
   switch (cmd) {
     case "login": {
@@ -1146,16 +1776,30 @@ async function main() {
       if (sub === "create" || sub === "new") return agentsCreate(v);
       if (sub === "get") return agentsGet(a1, v.fields);
       if (sub === "set") return agentsSet(a1, v);
-      if (sub === "rm" || sub === "delete") return agentsRm(a1);
+      if (sub === "rm" || sub === "delete") return agentsRm(a1, v);
+      if (sub === "doctor") return agentsDoctor(a1, v);
+      if (sub === "docs" || sub === "documents") return agentDocsCmd(a1, a2, pos[4], v);
       if (sub === "restart") return agentsRestart(a1);
       if (sub === "demo") return agentsDemo(a1, v);
-      throw usage(`Unknown agents subcommand: ${sub}.`, "Try: ghosty agents ls | create | get | set | rm | restart | demo");
+      throw unknown(`agents ${sub}`, sub, AGENTS_SUBS, "ghosty agents --help");
     case "files":
       return filesCmd(sub, a1, a2, v);
     case "skills":
       return skillsCmd(sub, a1, a2, v);
     case "mcp":
       return mcpCmd(sub, a1, v);
+    case "dbs":
+    case "db":
+      return dbsCmd(sub, a1, a2, pos.slice(4).filter((x) => x !== void 0), v);
+    case "turns":
+      return turnsCmd(sub, a1, v);
+    case "board":
+      return boardCmd(sub, a1, v);
+    case "channels":
+      return channelsCmd(sub, a1, a2, pos.slice(4).join(" ") || void 0, v);
+    case "credentials":
+    case "creds":
+      return credentialsCmd2(sub, a1, v);
     case "try":
       return tryTurn(sub, a1, v);
     case "chat":
@@ -1180,7 +1824,7 @@ async function main() {
       return openUrl(url);
     }
     default:
-      throw usage(`Unknown command: ${cmd}.`, "Run: ghosty --help");
+      throw unknown(cmd, cmd, COMMANDS, "ghosty --help");
   }
 }
 main().then(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostystudio/cli",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Official Ghosty Studio CLI — configure, test and chat with your agents from the terminal. Built for humans and coding agents.",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --outfile=dist/index.js --banner:js='#!/usr/bin/env node' --define:__VERSION__=\\\"$npm_package_version\\\"",
     "prepack": "npm run build",
-    "test": "esbuild src/flags.test.ts --bundle --platform=node --format=esm --outfile=/tmp/ghosty-cli-test.mjs --log-level=error && node --test /tmp/ghosty-cli-test.mjs"
+    "test": "for t in flags prompt; do esbuild src/$t.test.ts --bundle --platform=node --format=esm --outfile=/tmp/ghosty-cli-$t.test.mjs --log-level=error || exit 1; done && node --test /tmp/ghosty-cli-*.test.mjs"
   },
   "keywords": [
     "ghosty",