kenso 0.1.12 → 0.1.14

package/dist/kenso.js

@@ -2397,7 +2397,7 @@ var VERSION;
 var init_version = __esm({
   "src/core/version.ts"() {
     "use strict";
-    VERSION = true ? "0.1.12" : "0.0.0-dev";
+    VERSION = true ? "0.1.14" : "0.0.0-dev";
   }
 });
 
@@ -6215,7 +6215,9 @@ var init_each = __esm({
 var execute_exports = {};
 __export(execute_exports, {
   DATA_KEY: () => DATA_KEY,
+  HELP_NOTES_MAX: () => HELP_NOTES_MAX,
   buildRequest: () => buildRequest,
+  helpNotes: () => helpNotes,
   operationExamples: () => operationExamples,
   operationFlags: () => operationFlags,
   operationToCommand: () => operationToCommand
@@ -6233,7 +6235,7 @@ function fileProp(op) {
 }
 function describeParam(param, location, list2) {
   const fallback = list2 && location === "query" && LIST_PARAM_TEXT[param.name] || `${param.name} (${location === "route" ? "path" : location}, ${param.type})`;
-  const base = param.description ?? fallback;
+  const base = param.description?.replace(/\s*\n\s*/g, " ") ?? fallback;
   return param.enum ? `${base} One of: ${param.enum.join(", ")}.` : base;
 }
 function operationFlags(op) {
@@ -6309,9 +6311,9 @@ function usageLine(op) {
 function operationExamples(op) {
   const required = operationFlags(op).filter((f) => f.required && f.flag !== "file").map(flagUsage);
   const base = [commandOf(op), ...required].join(" ");
-  const examples = [base];
-  if (op.body?.format === "multipart") examples[0] = `${base} --file ./file.csv`;
-  else if (op.body) examples.push(`${base} --data @body.json`);
+  const first = op.body?.format === "multipart" ? `${base} --file ./file.csv` : base;
+  const examples = op.method === "GET" ? [first] : [`${first} --dry-run`, first];
+  if (op.body && op.body.format !== "multipart") examples.push(`${base} --data @body.json`);
   if (op.list) examples.push(`${base} --all`);
   return examples;
 }
@@ -6520,6 +6522,15 @@ async function runOperation(ctx, op, flags) {
   ctx.output.object(unwrap(res.body));
   return ExitCode.Ok;
 }
+function helpNotes(op) {
+  const text2 = (op.description ?? "").trim().replace(/\n[ \t]+/g, "\n");
+  if (text2.length <= HELP_NOTES_MAX) return text2;
+  const head = text2.slice(0, HELP_NOTES_MAX);
+  const end = Math.max(head.lastIndexOf(". "), head.lastIndexOf(".\n"));
+  const cut = end > HELP_NOTES_MAX / 3 ? head.slice(0, end + 1) : `${head.trimEnd()}...`;
+  return `${cut}
+More notes: kenso describe ${op.resource} ${op.action}.`;
+}
 function operationToCommand(op) {
   const flags = {};
   for (const f of operationFlags(op)) {
@@ -6531,12 +6542,13 @@ function operationToCommand(op) {
     if (f.multiple) spec.multiple = true;
     flags[f.flag] = spec;
   }
-  const api = `API: ${op.method} ${op.path} (${op.id}).`;
+  const write2 = op.method === "GET" ? "" : "\n\nA write: it sends at once. Run it with --dry-run first, then without. Many rows: --each <file> --dry-run, then --yes.";
+  const api = `API: ${op.method} ${op.path} (${op.id}).${write2}`;
   return {
     resource: op.resource,
     action: op.action,
     summary: op.summary ?? `${op.method} ${op.path}`,
-    description: op.description ? `${op.description}
+    description: op.description ? `${helpNotes(op)}
 
 ${api}` : api,
     flags,
@@ -6546,7 +6558,7 @@ ${api}` : api,
     run: (ctx, args) => runOperation(ctx, op, args.flags)
   };
 }
-var DATA_KEY, SCALAR_TYPES, LIST_PARAM_TEXT;
+var DATA_KEY, SCALAR_TYPES, LIST_PARAM_TEXT, HELP_NOTES_MAX;
 var init_execute = __esm({
   "src/generated/execute.ts"() {
     "use strict";
@@ -6560,6 +6572,7 @@ var init_execute = __esm({
       limit: "Page size.",
       cursor: "Start at this cursor (the next: hint of a previous page)."
     };
+    HELP_NOTES_MAX = 600;
   }
 });
 
@@ -6895,7 +6908,7 @@ var init_import = __esm({
     command = {
       resource: "accounts",
       action: "import",
-      summary: "Create accounts from a CSV or JSONL file (research is charged per created account)",
+      summary: "Create accounts (companies) from a CSV or JSONL file, charged per created account; a file of people: people import",
       description: "Sends the rows to accounts.bulk-create, 100 per call. Columns map by name (case, spaces and dashes ignored) to the account fields: name (or company), domains (split on , or ;) or one domain (domain, website, companyDomain), industry, employeeCount, hqLocation, linkedinUrl, stage, angle, whyNow, fitScore, fundingRound, cadenceDays, ownerMemberId, kenCompanyId, sendsFromInboxId, sendsFromLinkedInAccountId and source. A company that is already an account is skipped (domain_taken) with that account's id. Without --yes it prints the plan with a credit estimate; research runs for each created account.",
       flags: {
         file: { type: "string", required: true, description: "The CSV or JSONL file, or - for stdin" },
@@ -7307,7 +7320,7 @@ var init_login = __esm({
       resource: "auth",
       action: "login",
       summary: "Save an API key on this machine (--with-key reads it from stdin)",
-      description: "With --with-key, reads one API key from stdin, checks it with GET /v1/me and saves it to the profile (--profile, KENSO_PROFILE or the active one) in ~/.kenso/config.json with mode 0600. The workspace is --workspace when the key can reach it, else the key's only workspace. The key is never a flag value.",
+      description: "With --with-key, reads one API key from stdin, checks it with GET /v1/me and saves it to the profile (--profile, KENSO_PROFILE or the active one) in ~/.kenso/config.json with mode 0600. The workspace is --workspace when the key can reach it, else the key's only workspace. The key is never a flag value. A key in any environment variable: pipe that variable in as the example shows, with no check first (an empty or malformed key is refused, exit 2, without printing it).",
       flags: {
         "with-key": { type: "boolean", description: "Read the API key from stdin" },
         "device-name": { type: "string", description: "Name this machine on the browser sign-in page" },
@@ -8382,10 +8395,10 @@ async function readCampaign(ctx, campaignId) {
   const channel = isRecord4(campaign) && typeof campaign.channel === "string" ? campaign.channel.toLowerCase() : "";
   return { linkedInOnly: LINKEDIN_ONLY_CHANNELS.has(channel) ? true : void 0 };
 }
-async function estimate(ctx, campaignId, leadCount) {
+async function estimate(ctx, leadCount) {
   if (leadCount === 0) return { estimate: null };
   try {
-    const res = await ctx.client.request({ method: "POST", path: "/v1/credits/estimates", body: { kind: "leads", leadCount, campaignId } });
+    const res = await ctx.client.request({ method: "POST", path: "/v1/credits/estimates", body: { kind: "leads", leadCount } });
     const data = unwrap(res.body);
     if (!isRecord4(data)) return { estimate: data ?? null };
     const credits = (key) => typeof data[key] === "number" ? data[key] / 1e3 : void 0;
@@ -8489,7 +8502,7 @@ var init_import2 = __esm({
           ...Object.keys(mapping.dropped).length > 0 ? { droppedColumns: mapping.dropped } : {},
           ...emailLess > 0 ? { emailLessRows: emailLess } : {}
         };
-        if (dryRun2) Object.assign(dryRunExtra, await estimate(ctx, campaignId, items.length));
+        if (dryRun2) Object.assign(dryRunExtra, await estimate(ctx, items.length));
         const outcome = await runBatch(
           {
             command: "contacts import",
@@ -8634,7 +8647,7 @@ var init_update = __esm({
     command8 = {
       resource: "contacts",
       action: "update",
-      summary: "Edit leads in bulk from a CSV or JSONL file",
+      summary: "Edit leads from a CSV or JSONL file, matched by id or by email (also one lead)",
       description: "Matches each row to a contact by its id (--match id, an id or contactId column) or by email within a campaign (--match email --campaign <id>), then sends 1,000 items per call to POST /v1/contacts/bulk-update. A column that is absent or a blank cell leaves the field unchanged; the literal null clears it. Other columns are custom variables. Without --yes it prints the plan. Exit 5 when some rows failed or were not found.",
       flags: {
         file: { type: "string", description: "CSV (with a header row) or JSONL file, or - for stdin" },
@@ -8907,20 +8920,20 @@ function bulkCommand(kind) {
     ids: { type: "string", description: "Contact ids: one per line, or a CSV/JSONL with an id column; - for stdin" }
   };
   if (kind === "restore") flags.run = { type: "string", description: "Restore what an earlier contacts remove run removed" };
-  else flags.where = { type: "string", description: "contacts search filters as JSON, @file or - (the body of POST /v1/contacts/search)" };
+  else flags.where = { type: "string", description: "contacts search filters as JSON, @file or - (the body of POST /v1/contacts/search). The dry-run plan shows what matches: no separate search first" };
   if (kind === "remove") flags.confirm = { type: "string", description: "Required to remove more than 1,000 contacts: the exact count" };
   flags.out = OUT_FLAG;
   flags.concurrency = CONCURRENCY_FLAG;
   return {
     resource: "contacts",
     action: kind,
-    summary: `${route.verb} contacts by id, 1,000 per call`,
+    summary: kind === "restore" ? `${route.verb} contacts by id (--ids) or by a remove run (--run)` : `${route.verb} contacts by id (--ids file) or by search (--where), 1,000 per call`,
     description: `Sends the ids to POST ${route.path} in chunks of 1,000 and reports each id: ok, skipped (nothing to do), not_found or failed. Ids come from --ids` + (kind === "restore" ? " or from an earlier remove run (--run <runId>)" : " or from a contacts search (--where); a rerun of an unfinished --where run keeps its ids") + ". Without --yes it prints the count and the first ids." + (kind === "remove" ? " More than 1,000 ids also needs --confirm <count>. The summary prints the undo command." : ""),
     flags,
     examples: [
       `kenso contacts ${kind} --ids ids.txt`,
       `kenso contacts ${kind} --ids ids.txt --yes`,
-      ...kind === "restore" ? ["kenso contacts restore --run r_ab3dxk2q --yes"] : [`kenso contacts ${kind} --where '{"campaignIds": [812], "q": "acme"}' --yes`],
+      ...kind === "restore" ? ["kenso contacts restore --run r_ab3dxk2q --yes"] : [`kenso contacts ${kind} --where '{"campaignIds": [812], "q": "acme"}' --dry-run`],
       ...kind === "remove" ? ["kenso contacts remove --ids big.csv --confirm 2500 --yes"] : []
     ],
     ...kind === "pause" ? { beta: { featureGates: { all: ["pause_leads"] } } } : {},
@@ -9061,7 +9074,7 @@ function tagCommand(kind) {
   return {
     resource: "contacts",
     action: kind,
-    summary: kind === "tag" ? "Add a tag to contacts by id" : "Remove a tag from contacts by id",
+    summary: `${kind === "tag" ? "Add a tag to" : "Remove a tag from"} contacts by id (--ids only: for a campaign, contacts list its ids first)`,
     description: (kind === "tag" ? "Calls POST /v1/tags/{tagId}/assignments once per contact id (a contact that already has the tag is skipped). " : "Calls DELETE /v1/tags/{tagId}/assignments once per contact id. ") + "Ids come one per line, or from a CSV/JSONL with an id column. Without --yes it prints the count. Exit 5 when some ids failed or were not found.",
     flags: {
       tag: { type: "string", description: "The tag id (see kenso tags list)" },
@@ -9184,7 +9197,7 @@ var init_export = __esm({
     command9 = {
       resource: "contacts",
       action: "export",
-      summary: "Export a campaign's contacts to a CSV file",
+      summary: "Export a campaign's contacts to a CSV file (a segment: kenso contact-exports create)",
       description: "Creates a contact export of the campaign (POST /v1/contact-exports, kind contacts), waits for the contact_export job, then downloads GET /v1/contact-exports/{exportId}/content to --out. Without --out it prints the job (add --wait to wait for it).",
       flags: {
         campaign: { type: "string", description: "The campaign id" },
@@ -9432,7 +9445,7 @@ var init_describe2 = __esm({
 var agents_default;
 var init_agents = __esm({
   "docs/agents.md"() {
-    agents_default = '# Coding agents\n\nThe CLI is built to be driven by a coding agent: Claude Code, Codex, Cursor, Gemini CLI or anything else that runs shell commands. An agent learns it from the Agent Skill, `kenso --help` and `kenso describe`, and never needs these web pages.\n\n## Set up an agent in three steps\n\n1. Install the CLI where the agent runs: `npm i -g kenso` (Node 22 or newer).\n2. Give it a key. Either set `KENSO_API_KEY` (and `KENSO_WORKSPACE_ID` when the key reaches several workspaces) in the agent\'s environment, or log in once on that machine:\n\n```bash\necho $KEY | kenso auth login --with-key\nkenso workspace use 1234\n```\n\n3. Install the Agent Skill, so the agent knows the rules before its first command:\n\n```bash\nkenso skill install\n```\n\n## The Agent Skill\n\n`kenso skill install` writes the skill `kenso-cli` (one `SKILL.md`) where each agent looks for skills:\n\n| Agent | `--client` | Folder |\n|---|---|---|\n| Claude Code | `claude-code` | `~/.claude/skills/kenso-cli/` |\n| Codex | `codex` | `~/.agents/skills/kenso-cli/` |\n| Cursor | `cursor` | `~/.cursor/skills/kenso-cli/` |\n\nWithout `--client`, it installs for the agent that runs it when that is Claude Code, Codex or Cursor (detected from the environment, see below), else for all three. It prints what it wrote:\n\n```json\n{"installed":[{"client":"claude-code","path":"/home/you/.claude/skills/kenso-cli/SKILL.md","status":"created"}]}\n```\n\n```bash\nkenso skill install --client claude-code\nkenso skill install --client all\nkenso skill install --dir .claude/skills/kenso-cli\nkenso skill install --force\n```\n\n- `--dir` writes the skill into that folder instead, for example a project\'s own skills folder. Name the folder `kenso-cli`, as agents expect the folder to match the skill name.\n- A different `SKILL.md` already in a target folder is replaced only with `--force`; without it the command exits 7, writes nothing, and its `next` adds `--force`. The same file is left alone (`"status":"unchanged"`).\n- `--dry-run` writes nothing and exits 0. It prints each target\'s status (`replaced` marks a different file there) and a `next` that applies it, with `--force` when a file would be replaced.\n- Cursor also reads `~/.claude/skills/` and `~/.agents/skills/`, so after a default install for all three it may list `kenso-cli` more than once. To avoid that, install with `--client cursor` only, or remove the copies you do not need.\n\nThe skill also ships in the Kenso plugin for Claude Code (`Ken-Technology/ken-ai-plugin`), so `npx skills add Ken-Technology/ken-ai-plugin` installs it along with the MCP skills. To read it without installing, open `skill/kenso-cli/SKILL.md` in the package.\n\n## Rules the skill teaches\n\n- **Data is on stdout, as JSON when piped.** Progress, warnings and errors are on stderr. Parse stdout; read stderr when the exit code is not 0.\n- **Plan, then apply.** Run a write with `--dry-run`, read the plan, then run the exact command in its `next` (the same command with `--yes`).\n- **Pass files, not rows.** Never paste a CSV into the conversation. Write the file, pass its path with `--file`, and read the summary.\n- **Read failures only.** If the summary\'s `failed`, `notFound` and `invalid` are 0, the work is done. Otherwise read just the problem rows from `results.csv` or `invalid.csv`.\n- **Follow `next`.** Every error with a known fix carries the exact command to run.\n- **Branch on the exit code:** 0 ok, 2 fix the command, 3 fix the key, 5 some rows failed, 6 wait or raise a limit, 130 resume.\n- **Look things up, do not guess.** `kenso describe <resource> <action>` prints any command\'s flags and body schema as JSON.\n\n## The token-saving pattern\n\nAdding 5,000 leads through the MCP sends every lead through the model, hundreds of thousands of tokens. Through the CLI it is two commands and two short JSON objects:\n\n```bash\nkenso contacts import --campaign 812 --file leads.csv --dry-run\nkenso contacts import --campaign 812 --file leads.csv --yes\n```\n\nThen, only if the summary shows failures:\n\n```bash\ngrep -E \'^[0-9]+,(failed|not_found|invalid),\' ~/.kenso/runs/r_tdi5cdnx/results.csv | head -50\n```\n\n## Environment variables\n\n| Variable | What it does |\n|---|---|\n| `KENSO_API_KEY` | The API key. Wins over any saved profile |\n| `KENSO_WORKSPACE_ID` | The workspace for every command. `--workspace` wins over it |\n| `KENSO_PROFILE` | The saved profile to use. `--profile` wins over it |\n| `KENSO_API_URL` | The API, default `https://api.ken.so` |\n| `KENSO_CONFIG_DIR` | Where the config file and cache live, default `~/.kenso` |\n| `KENSO_RUNS_DIR` | Where run folders live, default `<config dir>/runs` |\n| `KENSO_MCP_URL` | The MCP for `kenso mcp`, default `https://mcp.ken.so/mcp` |\n\n## Cloud sandboxes\n\nCloud agents (Claude Code on the web, Codex cloud, Cursor background agents and similar) often run with a network allowlist. Allow:\n\n- `api.ken.so`: every command\n- `mcp.ken.so`: only `kenso mcp tools` and `kenso mcp call`\n- `registry.npmjs.org`: to install the CLI with npm\n\nStore the key as the platform\'s secret and expose it as `KENSO_API_KEY`. Run `kenso doctor` as the first command: it checks Node, the config, that the API is reachable and that the key works, and exits 0 when all four pass.\n\n```bash\nkenso doctor\n```\n\nPoint the run folders at the workspace if the home folder does not persist between sessions: `KENSO_RUNS_DIR=./.kenso-runs`. Keep that folder out of git.\n\n## How Kenso knows an agent ran a command\n\nThe CLI checks these environment variables, in this order: `CLAUDECODE` and `CLAUDE_CODE_ENTRYPOINT` (Claude Code), `CODEX_SANDBOX` and `CODEX_THREAD_ID` (Codex), `CURSOR_AGENT` (Cursor), `GEMINI_CLI` (Gemini CLI), `OPENCODE` (OpenCode), then `AI_AGENT`, a free-form name any other agent can set. When one is set:\n\n- every request carries `X-Ken-Client: Kenso CLI via <agent>`, and writes carry `X-Ken-Actor: agent`, so Kenso shows the change as made by you through that agent;\n- help ends with a short "For agents" block;\n- browser login never opens a browser itself: it prints the link for you to open.\n\n`kenso doctor` shows the agent it detected.\n\n## MCP-only tools\n\nA few Kenso MCP tools have no API route, such as the skills Kenso\'s own agents use. Reach them from the shell with the same key:\n\n```bash\nkenso mcp tools\nkenso mcp call skills --operation list\nkenso mcp call contacts --operation list --args \'{"limit":5}\'\n```\n\n`mcp call` prints the tool\'s structured result, else its text parsed as JSON, else the text. A tool error exits 1 with `mcp_tool_error`.\n';
+    agents_default = '# Coding agents\n\nThe CLI is built to be driven by a coding agent: Claude Code, Codex, Cursor, Gemini CLI or anything else that runs shell commands. An agent learns it from the Agent Skill, `kenso --help` and `kenso describe`, and never needs these web pages.\n\n## Set up an agent in three steps\n\n1. Install the CLI where the agent runs: `npm i -g kenso` (Node 22 or newer).\n2. Give it a key. Either set `KENSO_API_KEY` (and `KENSO_WORKSPACE_ID` when the key reaches several workspaces) in the agent\'s environment, or log in once on that machine:\n\n```bash\necho $KEY | kenso auth login --with-key\nkenso workspace use 1234\n```\n\n3. Install the Agent Skill, so the agent knows the rules before its first command:\n\n```bash\nkenso skill install\n```\n\n## The Agent Skill\n\n`kenso skill install` writes the skill `kenso-cli` (one `SKILL.md`) where each agent looks for skills:\n\n| Agent | `--client` | Folder |\n|---|---|---|\n| Claude Code | `claude-code` | `~/.claude/skills/kenso-cli/` |\n| Codex | `codex` | `~/.agents/skills/kenso-cli/` |\n| Cursor | `cursor` | `~/.cursor/skills/kenso-cli/` |\n\nWithout `--client`, it installs for the agent that runs it when that is Claude Code, Codex or Cursor (detected from the environment, see below), else for all three. It prints what it wrote:\n\n```json\n{"installed":[{"client":"claude-code","path":"/home/you/.claude/skills/kenso-cli/SKILL.md","status":"created"}]}\n```\n\n```bash\nkenso skill install --client claude-code\nkenso skill install --client all\nkenso skill install --dir .claude/skills/kenso-cli\nkenso skill install --force\n```\n\n- `--dir` writes the skill into that folder instead, for example a project\'s own skills folder. Name the folder `kenso-cli`, as agents expect the folder to match the skill name.\n- A different `SKILL.md` already in a target folder is replaced only with `--force`; without it the command exits 7, writes nothing, and its `next` adds `--force`. The same file is left alone (`"status":"unchanged"`).\n- `--dry-run` writes nothing and exits 0. It prints each target\'s status (`replaced` marks a different file there) and a `next` that applies it, with `--force` when a file would be replaced.\n- Cursor also reads `~/.claude/skills/` and `~/.agents/skills/`, so after a default install for all three it may list `kenso-cli` more than once. To avoid that, install with `--client cursor` only, or remove the copies you do not need.\n\nThe skill also ships in the Kenso plugin for Claude Code (`Ken-Technology/ken-ai-plugin`), so `npx skills add Ken-Technology/ken-ai-plugin` installs it along with the MCP skills. To read it without installing, open `skill/kenso-cli/SKILL.md` in the package.\n\n## Rules the skill teaches\n\n- **Data is on stdout, as JSON when piped.** Progress, warnings and errors are on stderr. Parse stdout; read stderr when the exit code is not 0.\n- **Plan, then apply.** Run a write with `--dry-run`, read the plan, then run the exact command in its `next` (the same command with `--yes`).\n- **Pass files, not rows.** Never paste a CSV into the conversation. Write the file, pass its path with `--file`, and read the summary.\n- **Read failures only.** If the summary\'s `failed`, `notFound` and `invalid` are 0, the work is done. Otherwise read just the problem rows from `results.csv` or `invalid.csv`.\n- **Follow `next`.** Every error with a known fix carries the exact command to run.\n- **Branch on the exit code:** 0 ok, 2 fix the command, 3 fix the key, 5 some rows failed, 6 wait or raise a limit, 130 resume.\n- **Look things up, do not guess.** `kenso describe <resource> <action>` prints any command\'s flags and body schema as JSON.\n\n## The token-saving pattern\n\nAdding 5,000 leads through the MCP sends every lead through the model, hundreds of thousands of tokens. Through the CLI it is two commands and two short JSON objects:\n\n```bash\nkenso contacts import --campaign 812 --file leads.csv --dry-run\nkenso contacts import --campaign 812 --file leads.csv --yes\n```\n\nThen, only if the summary shows failures:\n\n```bash\ngrep -E \'^[0-9]+,(failed|not_found|invalid),\' ~/.kenso/runs/r_tdi5cdnx/results.csv | head -50\n```\n\n## Environment variables\n\n| Variable | What it does |\n|---|---|\n| `KENSO_API_KEY` | The API key. Wins over any saved profile |\n| `KENSO_WORKSPACE_ID` | The workspace for every command. `--workspace` wins over it |\n| `KENSO_PROFILE` | The saved profile to use. `--profile` wins over it |\n| `KENSO_API_URL` | The API, default `https://api.ken.so` |\n| `KENSO_CONFIG_DIR` | Where the config file and cache live, default `~/.kenso` |\n| `KENSO_RUNS_DIR` | Where run folders live, default `<config dir>/runs` |\n| `KENSO_MCP_URL` | The MCP for `kenso mcp`, default `https://mcp.ken.so/mcp` |\n\n## Cloud sandboxes\n\nCloud agents (Claude Code on the web, Codex cloud, Cursor background agents and similar) often run with a network allowlist. Allow:\n\n- `api.ken.so`: every command\n- `mcp.ken.so`: only `kenso mcp tools` and `kenso mcp call`\n- `registry.npmjs.org`: to install the CLI with npm\n\nStore the key as the platform\'s secret and expose it as `KENSO_API_KEY`. Run `kenso doctor` as the first command: it checks Node, the config, that the API is reachable and that the key works, and exits 0 when all four pass.\n\n```bash\nkenso doctor\n```\n\nPoint the run folders at the workspace if the home folder does not persist between sessions: `KENSO_RUNS_DIR=./.kenso-runs`. Keep that folder out of git.\n\n## How Kenso knows an agent ran a command\n\nThe CLI checks these environment variables, in this order: `CLAUDECODE` and `CLAUDE_CODE_ENTRYPOINT` (Claude Code), `CODEX_SANDBOX` and `CODEX_THREAD_ID` (Codex), `CURSOR_AGENT` (Cursor), `GEMINI_CLI` (Gemini CLI), `OPENCODE` (OpenCode), then `AI_AGENT`, a free-form name any other agent can set. When one is set:\n\n- every request carries `X-Ken-Client: Kenso CLI via <agent>`, and writes carry `X-Ken-Actor: agent`, so Kenso shows the change as made by you through that agent;\n- help ends with a short "For agents" block;\n- browser login never opens a browser itself: it prints the link for you to open.\n\n`kenso doctor` shows the agent it detected.\n\n## MCP-only tools\n\nA few Kenso MCP tools have no API route, such as the skills Kenso\'s own agents use. Reach them from the shell with the same key:\n\n```bash\nkenso mcp tools\nkenso mcp call list_skills\nkenso mcp call load_skill --args \'{"name":"create-campaign"}\'\nkenso mcp call contacts --operation list --args \'{"limit":5}\'\n```\n\n`mcp call` prints the tool\'s structured result, else its text parsed as JSON, else the text. A tool error exits 1 with `mcp_tool_error`.\n';
   }
 });
 
@@ -9464,7 +9477,7 @@ var init_crm = __esm({
 var leads_default;
 var init_leads = __esm({
   "docs/leads.md"() {
-    leads_default = '# Leads\n\nLeads are contacts in a campaign. The lead commands live under `kenso contacts`, and `kenso leads` is the same thing: `kenso leads import` runs `kenso contacts import`.\n\n| Command | What it does |\n|---|---|\n| `contacts import` | Add leads from a CSV or JSONL file to a campaign, with one result per row |\n| `contacts update` | Edit leads in bulk from a file, matched by id or by email |\n| `contacts remove` / `restore` | Remove (soft-delete) leads by id, and undo it |\n| `contacts pause` / `resume` | Pause and resume the campaign sequence of leads (pause is beta, `pause_leads` flag) |\n| `contacts tag` / `untag` | Add or remove a tag on leads by id |\n| `contacts export` | Download a campaign\'s leads as one CSV file |\n\nAll of them except `export` are batch commands: without `--yes` they print a plan and change nothing. [Batch runs](batch.md) explains plans, run folders, results files and resume.\n\n## Import a CSV into a campaign\n\n```bash\nkenso contacts import --template\nkenso contacts import --campaign 812 --file leads.csv --dry-run\nkenso contacts import --campaign 812 --file leads.csv --yes\n```\n\n`--template` prints the accepted columns. A minimal file:\n\n```csv\nemail,firstName,lastName,companyName,Pain Point\nann@acme.io,Ann,Lee,Acme,Slow onboarding\ncid@globex.com,Cid,Moe,Globex,Churn\n```\n\n### Columns\n\nHeaders are matched without regard to case, spaces or punctuation. The known fields and the other headers each one reads:\n\n| Field | Also read from | Rule |\n|---|---|---|\n| `email` | email address, e-mail, work email | Required, unless the campaign is LinkedIn-only and the row has a linkedin.com/in/ URL |\n| `firstName` | first name, first, given name | Required |\n| `lastName` | last name, last, surname, family name | Required |\n| `title` | job title, position, role | Optional |\n| `linkedInUrl` | linkedin, linkedin url, linkedin profile, profile url | Optional |\n| `companyName` | company, organization, account, account name | `companyName` or `companyDomain` is required |\n| `companyDomain` | website, domain, company website, url | `companyName` or `companyDomain` is required |\n\nEvery other column becomes a custom variable, named like its header in snake_case: a `Pain Point` column fills `{{pain_point}}` in your sequence. Names Kenso keeps for its own fields (`city`, `country`, `phone_number` and others) are not sent: the CLI warns and the plan lists them under `droppedColumns`. Rename them with `--map`.\n\n### Cells\n\n- A blank cell is never sent, so importing a file never erases data on a lead that is already in the campaign.\n- The literal value `null` clears a custom variable.\n\n### Rename or drop columns with --map\n\n`--map` takes a JSON object, `@file` or `-` for stdin. A value names the target field, and `null` drops the column:\n\n```bash\nkenso contacts import --campaign 812 --file leads.csv --map \'{"Pain": "customVariables.pain_point", "Notes": null}\' --yes\n```\n\n### JSONL\n\nEach line is one lead. Keys work like CSV headers, and a `customVariables` object is spread into custom variables:\n\n```json\n{"email":"ann@acme.io","firstName":"Ann","lastName":"Lee","companyName":"Acme","customVariables":{"pain_point":"Slow onboarding"}}\n```\n\n```bash\nkenso contacts import --campaign 812 --file leads.jsonl --yes\ncat leads.jsonl | kenso contacts import --campaign 812 --file - --yes\n```\n\nA run read from stdin cannot be resumed with `kenso runs resume`, so prefer a file for large imports.\n\n### What the CLI checks before sending\n\nEvery row is checked locally first. A row that fails goes to `invalid.csv` with one of these reasons and is not sent:\n\n| Reason | Meaning |\n|---|---|\n| `missing_email` | The row has no email (and is not a LinkedIn-only lead) |\n| `invalid_email` | The email is not a valid address |\n| `missing_first_name` | The row has no first name |\n| `missing_last_name` | The row has no last name |\n| `missing_company` | The row has neither a company name nor a company domain |\n| `sales_navigator_url` | An email-less row whose LinkedIn URL is a Sales Navigator link: add the email or a linkedin.com/in/ URL |\n| `duplicate_in_file` | An earlier row of the file has the same email |\n\nKenso stays the authority and checks every row again.\n\n### What the dry run shows\n\nThe dry run maps the columns, checks the rows, reads the campaign, and asks for a credit estimate (`credit-estimates create`, kind `leads`). Its plan holds `rows`, `valid`, `invalid`, `mapping`, `customVariableKeys`, `estimate`, `credits` (`needed`, `available`, `sufficient`) and `next`, the exact apply command. If the estimate call fails, the plan still prints with `"estimate":null` and an `estimateError`.\n\n### How rows are sent\n\nThe CLI sends 1,000 rows per call to `POST /v1/campaigns/{campaignId}/contacts`, one call at a time per campaign, because two overlapping upserts of the same email could create duplicates. After a 5xx answer or a dropped connection it does not retry right away: it waits 130 seconds, so the first request has finished on the server, then resends the chunk once. Rows the first request saved come back `updated`.\n\n### Reading the result\n\nEach row in `results.csv` gets one status:\n\n| Status | Meaning |\n|---|---|\n| `created` | A new lead in the campaign |\n| `updated` | The lead was already there and was updated |\n| `skipped` | Kenso kept the lead out on purpose. `reason` is `duplicate`, `blocklisted`, `already_contacted`, `excluded` or another code |\n| `failed` | Kenso refused the row (`reason` such as `invalid_email` or `validation`, and an `error` message), or the call failed |\n| `invalid` | The CLI refused the row before sending it (see the table above) |\n\nA saved lead that cannot be emailed yet has `sendable` false, and the summary counts those leads in `notSendable` with a warning on stderr.\n\nExit codes: 0 when no row failed (skipped rows are not failures), 5 when some rows failed or were invalid, 6 when the plan\'s or campaign\'s lead limit stopped the run (`limit_reached`; raise the limit, then rerun the same command to send the rest).\n\n## Import a very large file on the server\n\nFor up to 100,000 rows, `--server-import` uploads the CSV as one server import job and waits for it (default 30 minutes, `--timeout`). It reports the job\'s counts but no per-row results.\n\n```bash\nkenso contacts import --campaign 812 --file big.csv --server-import --yes\nkenso contacts import --campaign 812 --file big.csv --server-import --timeout 1h --yes\n```\n\n## Update leads in bulk\n\n```bash\nkenso contacts update --file edits.csv --match id\nkenso contacts update --file edits.csv --match id --yes\nkenso contacts update --file edits.csv --match email --campaign 812 --yes\n```\n\n- `--match id` reads the contact id from an `id` or `contactId` column.\n- `--match email` finds each email among the leads of `--campaign`. An email it cannot find is `not_found`. The email column only finds the lead; it is never sent as an edit.\n- A column that is absent, or a blank cell, leaves that field unchanged. The literal `null` clears it.\n- The lead fields you can edit are `firstName`, `lastName`, `title`, `linkedInUrl`, and `email` with `--match id`. `companyName` and `companyDomain` cannot change here and are not sent. Every other column is a custom variable, mapped the same way as in an import, and `--map` works here too.\n- A row with nothing to change is `skipped` with reason `no_changes` and is not sent. Rows go 1,000 per call to `POST /v1/contacts/bulk-update`.\n\nTo edit one lead, use a one-row file from stdin:\n\n```bash\nprintf \'id,title\\n9001,VP Sales\\n\' | kenso contacts update --file - --match id --yes\n```\n\n## Remove, restore, pause and resume\n\nThese four take contact ids from `--ids` (one id per line, or a CSV or JSONL file with an `id` or `contactId` column, or `-` for stdin), or from a search with `--where` (remove, pause and resume). `--where` takes the body of `POST /v1/contacts/search` as JSON, `@file` or `-`.\n\n```bash\nkenso contacts remove --ids ids.txt\nkenso contacts remove --ids ids.txt --yes\nkenso contacts remove --where \'{"campaignIds": [812], "q": "acme"}\' --yes\nkenso contacts remove --ids big.csv --confirm 2500 --yes\n```\n\n- Without `--yes`, the plan prints the count and the first ids.\n- Removing more than 1,000 contacts also needs `--confirm <count>`, and the count must match. The plan\'s `next` already carries the right `--confirm`.\n- Each id comes back `ok`, `skipped` when there was nothing to do (for example `not_deleted` when you restore a contact that is not removed), `not_found` or `failed`.\n- The remove summary carries the undo command, `"undo":"kenso contacts restore --run r_ubqu7wtx"`.\n\n```bash\nkenso contacts restore --run r_ubqu7wtx --yes\nkenso contacts restore --ids ids.txt --yes\nkenso contacts pause --where \'{"campaignIds": [812]}\' --yes\nkenso contacts resume --ids ids.txt --yes\n```\n\n`restore` takes `--ids` or `--run <runId>` of an earlier remove, not `--where`: a search cannot find removed contacts. `pause` is a beta command for workspaces with the `pause_leads` flag.\n\n## Tag and untag\n\n```bash\nkenso tags list\nkenso contacts tag --tag 31 --ids ids.txt --yes\nkenso contacts untag --tag 31 --ids ids.txt --yes\n```\n\n`tag` calls `POST /v1/tags/{tagId}/assignments` once per contact. A contact that already has the tag is `skipped` with reason `already_tagged`.\n\n## Export a campaign\'s leads\n\n```bash\nkenso contacts export --campaign 812 --out contacts.csv\nkenso contacts export --campaign 812 --wait\n```\n\nWith `--out`, the CLI creates the export, waits for the job (default 30 minutes, `--timeout`) and writes one CSV file (mode 0600). Without `--out` it prints the export job; `--wait` waits for it, or run the `next` it prints, `kenso jobs wait <jobId> --type contact_export`.\n\n## Recipes\n\n**Tag every lead of a campaign.** List the ids, then tag them:\n\n```bash\nkenso contacts list --campaign-id 812 --all -o ids > ids.txt\nkenso contacts tag --tag 31 --ids ids.txt --yes\n```\n\n**Fix the invalid rows and send them.** `invalid.csv` keeps each refused row\'s number and reason. Fix those rows in a new file and import it. Rerunning the original file also works: rows Kenso already saved come back `updated` or `skipped`.\n\n**Retry only what failed.** Filter `results.csv` to the `failed` rows, take those rows from the input by `row` number, and import that file.\n\n**Pause leads who replied elsewhere.** Search by filter, check the count, then apply:\n\n```bash\nkenso contacts pause --where @replied.json\nkenso contacts pause --where @replied.json --yes\n```\n\n**Edit one field on many leads by email.**\n\n```bash\nkenso contacts update --file titles.csv --match email --campaign 812 --dry-run\nkenso contacts update --file titles.csv --match email --campaign 812 --yes\n```\n';
+    leads_default = '# Leads\n\nLeads are contacts in a campaign. The lead commands live under `kenso contacts`, and `kenso leads` is the same thing: `kenso leads import` runs `kenso contacts import`.\n\n| Command | What it does |\n|---|---|\n| `contacts import` | Add leads from a CSV or JSONL file to a campaign, with one result per row |\n| `contacts update` | Edit leads in bulk from a file, matched by id or by email |\n| `contacts remove` / `restore` | Remove (soft-delete) leads by id, and undo it |\n| `contacts pause` / `resume` | Pause and resume the campaign sequence of leads (pause is beta, `pause_leads` flag) |\n| `contacts tag` / `untag` | Add or remove a tag on leads by id |\n| `contacts export` | Download a campaign\'s leads as one CSV file |\n\nAll of them except `export` are batch commands: without `--yes` they print a plan and change nothing. [Batch runs](batch.md) explains plans, run folders, results files and resume.\n\n## Import a CSV into a campaign\n\n```bash\nkenso contacts import --template\nkenso contacts import --campaign 812 --file leads.csv --dry-run\nkenso contacts import --campaign 812 --file leads.csv --yes\n```\n\n`--template` prints the accepted columns. A minimal file:\n\n```csv\nemail,firstName,lastName,companyName,Pain Point\nann@acme.io,Ann,Lee,Acme,Slow onboarding\ncid@globex.com,Cid,Moe,Globex,Churn\n```\n\n### Columns\n\nHeaders are matched without regard to case, spaces or punctuation. The known fields and the other headers each one reads:\n\n| Field | Also read from | Rule |\n|---|---|---|\n| `email` | email address, e-mail, work email | Required, unless the campaign is LinkedIn-only and the row has a linkedin.com/in/ URL |\n| `firstName` | first name, first, given name | Required |\n| `lastName` | last name, last, surname, family name | Required |\n| `title` | job title, position, role | Optional |\n| `linkedInUrl` | linkedin, linkedin url, linkedin profile, profile url | Optional |\n| `companyName` | company, organization, account, account name | `companyName` or `companyDomain` is required |\n| `companyDomain` | website, domain, company website, url | `companyName` or `companyDomain` is required |\n\nEvery other column becomes a custom variable, named like its header in snake_case: a `Pain Point` column fills `{{pain_point}}` in your sequence. Names Kenso keeps for its own fields (`city`, `country`, `phone_number` and others) are not sent: the CLI warns and the plan lists them under `droppedColumns`. Rename them with `--map`.\n\n### Cells\n\n- A blank cell is never sent, so importing a file never erases data on a lead that is already in the campaign.\n- The literal value `null` clears a custom variable.\n\n### Rename or drop columns with --map\n\n`--map` takes a JSON object, `@file` or `-` for stdin. A value names the target field, and `null` drops the column:\n\n```bash\nkenso contacts import --campaign 812 --file leads.csv --map \'{"Pain": "customVariables.pain_point", "Notes": null}\' --yes\n```\n\n### JSONL\n\nEach line is one lead. Keys work like CSV headers, and a `customVariables` object is spread into custom variables:\n\n```json\n{"email":"ann@acme.io","firstName":"Ann","lastName":"Lee","companyName":"Acme","customVariables":{"pain_point":"Slow onboarding"}}\n```\n\n```bash\nkenso contacts import --campaign 812 --file leads.jsonl --yes\ncat leads.jsonl | kenso contacts import --campaign 812 --file - --yes\n```\n\nA run read from stdin cannot be resumed with `kenso runs resume`, so prefer a file for large imports.\n\n### What the CLI checks before sending\n\nEvery row is checked locally first. A row that fails goes to `invalid.csv` with one of these reasons and is not sent:\n\n| Reason | Meaning |\n|---|---|\n| `missing_email` | The row has no email (and is not a LinkedIn-only lead) |\n| `invalid_email` | The email is not a valid address |\n| `missing_first_name` | The row has no first name |\n| `missing_last_name` | The row has no last name |\n| `missing_company` | The row has neither a company name nor a company domain |\n| `sales_navigator_url` | An email-less row whose LinkedIn URL is a Sales Navigator link: add the email or a linkedin.com/in/ URL |\n| `duplicate_in_file` | An earlier row of the file has the same email |\n\nKenso stays the authority and checks every row again.\n\n### What the dry run shows\n\nThe dry run maps the columns, checks the rows, reads the campaign, and asks for a credit estimate (`credit-estimates create`, kind `leads`). Its plan holds `rows`, `valid`, `invalid`, `mapping`, `customVariableKeys`, `estimate`, `credits` (`needed`, `available`, `sufficient`) and `next`, the exact apply command. If the estimate call fails, the plan still prints with `"estimate":null` and an `estimateError`.\n\n### How rows are sent\n\nThe CLI sends 1,000 rows per call to `POST /v1/campaigns/{campaignId}/contacts`, one call at a time per campaign, because two overlapping upserts of the same email could create duplicates. After a 5xx answer or a dropped connection it does not retry right away: it waits 130 seconds, so the first request has finished on the server, then resends the chunk once. Rows the first request saved come back `updated`.\n\n### Reading the result\n\nEach row in `results.csv` gets one status:\n\n| Status | Meaning |\n|---|---|\n| `created` | A new lead in the campaign |\n| `updated` | The lead was already there and was updated |\n| `skipped` | Kenso kept the lead out on purpose. `reason` is `duplicate`, `blocklisted`, `already_contacted`, `excluded` or another code |\n| `failed` | Kenso refused the row (`reason` such as `invalid_email` or `validation`, and an `error` message), or the call failed |\n| `invalid` | The CLI refused the row before sending it (see the table above) |\n\nA saved lead that cannot be emailed yet has `sendable` false, and the summary counts those leads in `notSendable` with a warning on stderr.\n\nExit codes: 0 when no row failed (skipped rows are not failures), 5 when some rows failed or were invalid, 6 when the plan\'s or campaign\'s lead limit stopped the run (`limit_reached`; raise the limit, then rerun the same command to send the rest).\n\n## Import a very large file on the server\n\nFor up to 100,000 rows, `--server-import` uploads the CSV as one server import job and waits for it (default 30 minutes, `--timeout`). It reports the job\'s counts but no per-row results.\n\n```bash\nkenso contacts import --campaign 812 --file big.csv --server-import --yes\nkenso contacts import --campaign 812 --file big.csv --server-import --timeout 1h --yes\n```\n\n## Update leads in bulk\n\n```bash\nkenso contacts update --file edits.csv --match id\nkenso contacts update --file edits.csv --match id --yes\nkenso contacts update --file edits.csv --match email --campaign 812 --yes\n```\n\n- `--match id` reads the contact id from an `id` or `contactId` column.\n- `--match email` finds each email among the leads of `--campaign`. An email it cannot find is `not_found`. The email column only finds the lead; it is never sent as an edit.\n- A column that is absent, or a blank cell, leaves that field unchanged. The literal `null` clears it.\n- The lead fields you can edit are `firstName`, `lastName`, `title`, `linkedInUrl`, and `email` with `--match id`. `companyName` and `companyDomain` cannot change here and are not sent. Every other column is a custom variable, mapped the same way as in an import, and `--map` works here too.\n- A row with nothing to change is `skipped` with reason `no_changes` and is not sent. Rows go 1,000 per call to `POST /v1/contacts/bulk-update`.\n\nTo edit one lead, use a one-row file from stdin:\n\n```bash\nprintf \'id,title\\n9001,VP Sales\\n\' | kenso contacts update --file - --match id --yes\n```\n\n## Remove, restore, pause and resume\n\nThese four take contact ids from `--ids` (one id per line, or a CSV or JSONL file with an `id` or `contactId` column, or `-` for stdin), or from a search with `--where` (remove, pause and resume). `--where` takes the body of `POST /v1/contacts/search` as JSON, `@file` or `-`, and does the search itself: its plan shows how many contacts match and the first ids, so run no separate search or list first.\n\n```bash\nkenso contacts remove --ids ids.txt\nkenso contacts remove --ids ids.txt --yes\nkenso contacts remove --where \'{"campaignIds": [812], "q": "acme"}\'\nkenso contacts remove --where \'{"campaignIds": [812], "q": "acme"}\' --yes\nkenso contacts remove --ids big.csv --confirm 2500 --yes\n```\n\n- Without `--yes`, the plan prints the count and the first ids.\n- Removing more than 1,000 contacts also needs `--confirm <count>`, and the count must match. The plan\'s `next` already carries the right `--confirm`.\n- Each id comes back `ok`, `skipped` when there was nothing to do (for example `not_deleted` when you restore a contact that is not removed), `not_found` or `failed`.\n- The remove summary carries the undo command, `"undo":"kenso contacts restore --run r_ubqu7wtx"`.\n\n```bash\nkenso contacts restore --run r_ubqu7wtx --yes\nkenso contacts restore --ids ids.txt --yes\nkenso contacts pause --where \'{"campaignIds": [812]}\' --yes\nkenso contacts resume --ids ids.txt --yes\n```\n\n`restore` takes `--ids` or `--run <runId>` of an earlier remove, not `--where`: a search cannot find removed contacts. `pause` is a beta command for workspaces with the `pause_leads` flag.\n\n## Tag and untag\n\n```bash\nkenso tags list\nkenso contacts tag --tag 31 --ids ids.txt --yes\nkenso contacts untag --tag 31 --ids ids.txt --yes\n```\n\n`tag` calls `POST /v1/tags/{tagId}/assignments` once per contact. A contact that already has the tag is `skipped` with reason `already_tagged`.\n\n## Export a campaign\'s leads\n\n```bash\nkenso contacts export --campaign 812 --out contacts.csv\nkenso contacts export --campaign 812 --wait\n```\n\nWith `--out`, the CLI creates the export, waits for the job (default 30 minutes, `--timeout`) and writes one CSV file (mode 0600). Without `--out` it prints the export job; `--wait` waits for it, or run the `next` it prints, `kenso jobs wait <jobId> --type contact_export`.\n\n## Recipes\n\n**Tag every lead of a campaign.** List the ids, then tag them:\n\n```bash\nkenso contacts list --campaign-id 812 --all -o ids > ids.txt\nkenso contacts tag --tag 31 --ids ids.txt --yes\n```\n\n**Fix the invalid rows and send them.** `invalid.csv` keeps each refused row\'s number and reason. Fix those rows in a new file and import it. Rerunning the original file also works: rows Kenso already saved come back `updated` or `skipped`.\n\n**Retry only what failed.** Filter `results.csv` to the `failed` rows, take those rows from the input by `row` number, and import that file.\n\n**Pause leads who replied elsewhere.** Plan with the filter (the plan shows the count), then apply:\n\n```bash\nkenso contacts pause --where @replied.json\nkenso contacts pause --where @replied.json --yes\n```\n\n**Edit one field on many leads by email.**\n\n```bash\nkenso contacts update --file titles.csv --match email --campaign 812 --dry-run\nkenso contacts update --file titles.csv --match email --campaign 812 --yes\n```\n';
   }
 });
 
@@ -9496,7 +9509,7 @@ var init_studio = __esm({
 var SKILL_default;
 var init_SKILL = __esm({
   "skill/kenso-cli/SKILL.md"() {
-    SKILL_default = '---\nname: kenso-cli\ndescription: Use the Kenso CLI (kenso) for bulk lead, CRM and Studio work in a Kenso workspace from files - import, update, remove, pause or tag leads in campaigns, import accounts and people, fill Studio templates, or call any Kenso API operation from the shell. Prefer it over the Kenso MCP for anything over about 50 records.\n---\n\n# Kenso CLI\n\n`kenso` does bulk work in Kenso from files and prints JSON. Use it instead of the Kenso MCP when the work starts from a file or touches more than about 50 records: the rows stay on disk, and you read a short summary.\n\n## Install and auth\n\n```bash\nnpm i -g kenso\nkenso doctor\n```\n\nNeeds Node 22+. Auth, in order of precedence:\n\n- `KENSO_API_KEY` in the environment (plus `KENSO_WORKSPACE_ID` when the key reaches several workspaces). Nothing else to do.\n- Or a saved key. The key is never a flag value; pipe it in. The person creates it in app.ken.so at Settings > Integrations > API keys.\n\n```bash\necho $KEY | kenso auth login --with-key\nkenso workspace list --q acme\nkenso workspace use 1234\nkenso auth status\n```\n\nNever print, echo to the conversation, or write the key into a file in the repo. `kenso auth login` alone is browser login: it may answer `browser_login_unavailable`; then use `--with-key`. If it works, it prints a link: ask the person to open it.\n\n## Golden rules\n\n1. **stdout is data, stderr is everything else.** Piped output is JSON: one object, NDJSON for lists, one JSON summary for a batch. Errors are one JSON line on stderr: `{"error":{"code","message","field","hint","next","httpStatus","requestId"}}`.\n2. **Plan, then apply.** A batch command (import, update, remove, tag, `--each`) only plans without `--yes`: run it with `--dry-run`, read the plan, then run the exact command in its `next` (the same command with `--yes`). Never pass both. A single `kenso <resource> <action>` write and `kenso api` send at once: run it with `--dry-run` to see the request, then without it.\n3. **Pass files, not rows.** Never paste a CSV or a list of records into the conversation or a command line. Write a file and pass `--file path` (or `--ids path`).\n4. **Read the summary, then failures only.** If `failed`, `notFound` and `invalid` are 0, you are done. Otherwise read only the problem rows: `grep -E \'^[0-9]+,(failed|not_found|invalid),\' <results> | head -50`, or `invalidRows`. Do not read the whole results file.\n5. **Follow `next`.** An error with a known fix carries the exact command to run in `next`, and what to change in `hint`.\n6. **Branch on the exit code:**\n\n| Exit | Meaning | Do |\n|---|---|---|\n| 0 | OK (skipped rows are not failures) | Report the summary |\n| 1 | Unexpected error | Rerun with `--verbose`, report |\n| 2 | Usage or validation error | Fix the flags or the file (see `field`, `hint`) |\n| 3 | No key, bad key, or 401/403 | Ask for a key or a permission; do not retry |\n| 4 | Not found | Check the id |\n| 5 | Some rows failed, not found or invalid | Read the failed rows only, fix, resend those |\n| 6 | Rate limited, or a lead limit (`limit_reached`) stopped the run | Wait, or ask the person to raise the limit, then rerun |\n| 7 | Conflict, or another process holds the run | Read `message`; run a `next` with `--force` only after the person agrees |\n| 8 | Server error after retries | Wait a minute, rerun the same command |\n| 130 | Interrupted | Run the `next`: `kenso runs resume <runId>` |\n\n## Leads: import\n\n```bash\nkenso contacts import --template\nkenso contacts import --campaign 812 --file leads.csv --dry-run\nkenso contacts import --campaign 812 --file leads.csv --yes\n```\n\n- CSV with a header row, or JSONL. Known columns: `email`, `firstName`, `lastName`, `title`, `linkedInUrl`, `companyName`, `companyDomain` (common header spellings are matched). Every other column becomes a custom variable in snake_case (`Pain Point` fills `{{pain_point}}`).\n- Rename or drop columns: `--map \'{"Pain": "customVariables.pain_point", "Notes": null}\'`.\n- Blank cells are never sent; the literal `null` clears a custom variable.\n- The dry run checks every row locally (`invalid_email`, `missing_first_name`, `duplicate_in_file` ...), shows the column `mapping` and the credit estimate. Check the mapping before you apply.\n- Row statuses: `created`, `updated`, `skipped` (with `reason`: `duplicate`, `blocklisted`, `already_contacted` ...), `failed`, `invalid`. `notSendable` counts saved leads that cannot be emailed yet.\n- Up to 100,000 rows without per-row results: add `--server-import`.\n\n## Leads: update and cleanup\n\n```bash\nkenso contacts update --file edits.csv --match id --dry-run\nkenso contacts update --file edits.csv --match email --campaign 812 --yes\nkenso contacts remove --ids ids.txt --dry-run\nkenso contacts remove --where \'{"campaignIds": [812], "q": "acme"}\' --yes\nkenso contacts restore --run r_ab3dxk2q --yes\nkenso contacts pause --ids ids.txt --yes\nkenso contacts resume --ids ids.txt --yes\nkenso contacts tag --tag 31 --ids ids.txt --yes\nkenso contacts export --campaign 812 --out contacts.csv\n```\n\n- `update`: match by an `id`/`contactId` column, or by email within `--campaign`. A missing column or blank cell leaves a field unchanged; `null` clears it.\n- `--ids` takes one id per line, or a CSV/JSONL with an `id` column, or `-` for stdin. Get ids with `kenso contacts list --campaign-id 812 --all -o ids > ids.txt`.\n- Removing more than 1,000 needs `--confirm <count>` (the dry run\'s `next` has it). The remove summary has `undo`: keep it.\n\n## Runs and resume\n\nEvery batch run has an id (`r_...`) and a folder with `results.csv` (one line per input row: `row,status,id,reason,error`), `invalid.csv`, `plan.json` and `run.json`. The summary prints their absolute paths.\n\n- Rerunning the same command on the same file continues an unfinished run (`"resumed":true`) or, when every row already succeeded, answers `"changed":0` and sends no writes. Writes match existing records, so a resend never duplicates.\n- `kenso runs list`, `kenso runs show <runId>`, `kenso runs resume <runId>`.\n- `--concurrency` (1-16, default 4) works on `contacts update`, `remove`, `restore`, `pause`, `resume`, `tag`, `untag`, `people import`, `accounts import` and `--each`. `contacts import` sends one chunk at a time per campaign and has no such flag. 429s and transient 5xx are retried for you. Do not add your own retry loop.\n\n## CRM and Studio (beta)\n\nNeed the `accounts` or `studio` flag. Same plan-then-apply rules.\n\n```bash\nkenso accounts import --file accounts.csv --dry-run\nkenso people import --file people.csv --dry-run\nkenso studio pull 12 --dir ./tpl\nkenso studio push 12 --dir ./tpl\nkenso studio fill 12 --accounts ids.txt\n```\n\n`accounts import` charges research per created account: show the person the estimate first. `studio fill` charges per page and refuses to rerun a fill of the same file with the same flags (exit 7), but the same ids in another file are charged again. Read `kenso docs crm` and `kenso docs studio` before using them.\n\n## Workflows in plain steps (beta)\n\nNeeds the `workflows` and `workflows_plain` flags. Your own model writes the workflow from the person\'s words, in plain steps or as custom JSON/code; Kenso only runs it, so writing costs no Kenso AI credits.\n\n```bash\nkenso workflows brief > brief.json\nkenso workflows brief --types ai.qualify@1,logic.filter@1 --include stepTypes\nkenso workflows create --data @create.json --dry-run\nkenso workflows validate --workflow-id 42\nkenso workflow-builder test --workflow-id 42 --data @test.json\nkenso workflows publish --workflow-id 42\n```\n\n- Start with `brief`: `authoring` (how plain steps become engine steps), `stepTypes`, `triggers`, `examples` and `workspace` (campaigns, Slack, secret names). `--workflow-id` returns the current definition to change; save it with `kenso workflows update --workflow-id 42 --data @update.json` and its `baseVersion`.\n- `create.json` is `{"definition": {...}}`, the definition with its `plain` block. Fix every issue `validate` names, test on one record (`{"record": {"type": "person", "id": 123}}`), then publish.\n- Never write a secret\'s value into a definition or the conversation: reference `{{secrets.NAME}}` and ask the person to add it in app.ken.so at Settings > Integrations > Secrets.\n\n## Everything else\n\nEvery API operation is a command: `kenso <resource> <action>` (`kenso campaigns list`, `kenso tags create --name VIP`). A write like that runs at once, without `--yes`: check it with `--dry-run` first. Look commands up instead of guessing flags:\n\n```bash\nkenso describe\nkenso describe campaigns\nkenso describe campaigns update\nkenso campaigns update --help\n```\n\n- Lists print one page; `--all` streams every page, `--limit` and `--cursor` page by hand. `--fields a,b` and `--query \'<JMESPath>\'` shape output without `jq`.\n- Many records: `--each file.csv` runs a generated command once per row (row keys are flag or API names), with results and resume. It needs `--yes` or `--dry-run` unless it is a GET.\n- Beta commands are hidden from help until the workspace has the flag; `--all-commands` shows them.\n- Raw route: `kenso api GET /v1/me`, `kenso api POST /v1/tags --data @tag.json`. Writes through `kenso api` run without `--yes`, so be sure first.\n- MCP-only tools (such as skills): `kenso mcp tools`, `kenso mcp call skills --operation list`.\n- Offline docs: `kenso docs`, `kenso docs leads`.\n';
+    SKILL_default = '---\nname: kenso-cli\ndescription: The Kenso CLI (kenso) for work from a file or over about 50 records - import, update, remove, pause, tag or export leads, import CRM accounts and people, edit Studio templates as local files and fill them, run an API operation per file row. For one record or a question, use the Kenso MCP.\n---\n\n1. Every write runs first with `--dry-run`, never `--yes`; apply with the plan\'s `next`. `--yes` at once only to continue an interrupted run or apply what the person confirmed.\n2. Many rows are one command with the file as it is (`--file`, `--ids`, `--each`), never a command per row. Run kenso only: no python, awk or shell tests, not even on a file or variable.\n3. Errors are JSON on stderr: follow `next`. `--force` only with the person\'s OK.\n4. Ids are flags: `--campaign 812` on contacts import, update, export; `--campaign-id 812` on API commands (`contacts list`). `--workspace <id>`; by name `kenso workspace list --q acme`.\n\n```bash\nkenso contacts import --campaign 812 --file leads.csv --dry-run   # skips leads already in; --map \'{"Pain": "customVariables.pain_point", "Notes": null}\'; over 200 MB --server-import\nkenso contacts update --file edits.csv --match id --dry-run   # also one contact; or --match email --campaign 812\nkenso contacts remove --ids ids.txt --dry-run   # same for pause, resume, restore, tag --tag 31; over 1,000 add --confirm <count>\nkenso contacts remove --where \'{"campaignIds": [812], "q": "acme"}\' --dry-run   # also pause, resume; the plan shows the matches: no search first\nkenso contacts list --campaign-id 812 --all -o ids > ids.txt   # tag and restore take --ids only: list the ids first\nkenso contacts export --campaign 812 --out leads.csv   # a segment: kenso contact-exports create --segment-id 55\nkenso runs list   # an interrupted run (terminal lost): find it, then kenso runs resume <runId>. A changed file is a new run\nkenso accounts import --file accounts.csv --dry-run   # companies; people (any file of people) go in with kenso people import --file people.csv\nkenso studio push 12 --dir ./tpl   # to preview local edits push first (draft only; live needs --publish), then studio preview 12\nkenso studio fill 12 --accounts ids.txt --dry-run   # or --campaign 10546 --contacts leads.csv\nkenso campaigns update --campaign-id 812 --name Q4 --dry-run   # any API operation; --each rows.csv for many\nkenso mcp call list_skills\n```\n\n`accounts import` charges per new account, `studio fill` per page (again for the same ids in another file): show the estimate first. `pinned_by_user`: with the person\'s OK, `--overwrite-pinned`. Workflows: `kenso workflows brief` first; secrets only as `{{secrets.NAME}}`. Key: `KENSO_API_KEY`, or any variable piped as the first command, no check or printenv (an empty key is refused): `printf \'%s\' "$KEY" | kenso auth login --with-key`; never in a flag, output or file. `kenso api` only when no command fits. Flags: `kenso <resource> <action> --help`. More: `kenso docs leads|batch|crm|studio`.\n';
   }
 });
 
@@ -9993,14 +10006,14 @@ var init_call = __esm({
     command13 = {
       resource: "mcp",
       action: "call",
-      summary: "Call a hosted Kenso MCP tool",
-      description: "Calls one Kenso MCP tool with the same API key and prints its result: structuredContent when the tool returns it, else its text parsed as JSON, else the text. Covers MCP-only tools such as skills. A tool error exits 1 with the tool's message. Tools are facades: pass the facade's operation with --operation.",
+      summary: "Call a hosted Kenso MCP tool, such as list_skills or load_skill",
+      description: "Calls one Kenso MCP tool with the same API key and prints its result: structuredContent when the tool returns it, else its text parsed as JSON, else the text. Covers MCP-only tools, such as the skills (list_skills, load_skill). A tool error exits 1 with the tool's message. A facade tool takes its operation with --operation.",
       flags: {
         operation: { type: "string", description: "The facade operation, for example list" },
         args: { type: "string", description: "Tool arguments as a JSON object: inline, @file or - for stdin" }
       },
       positionals: [{ name: "tool", required: true, description: "The tool name (see kenso mcp tools)" }],
-      examples: [`kenso mcp call contacts --operation list --args '{"limit":5}'`, "kenso mcp call skills --operation list"],
+      examples: [`kenso mcp call contacts --operation list --args '{"limit":5}'`, "kenso mcp call list_skills", `kenso mcp call load_skill --args '{"name":"create-campaign"}'`],
       operationIds: [],
       async run(ctx, { flags, positionals }) {
         const tool = positionals[0];
@@ -11142,7 +11155,7 @@ var init_preview = __esm({
     command23 = {
       resource: "studio",
       action: "preview",
-      summary: "Render a template version for up to 3 accounts and print the preview links",
+      summary: "Render a saved version for up to 3 accounts; for local edits, studio push them to the draft first",
       description: "Calls asset-templates.preview: renders the draft (else the latest published version, or --version-id) for --account-ids (up to 3; default the 3 most recently touched accounts, else the bundle's samples) and prints each preview's link, screenshots, console errors and link issues. It takes up to a minute per account. The preview renders what is saved, not local files: with --dir it compares the folder to that version and warns when they differ (run kenso studio push first).",
       flags: {
         dir: { type: "string", description: "A template folder to compare with the version being rendered" },
@@ -11688,13 +11701,28 @@ async function visibleSpecs(specs, opts, getFeatures, hidden) {
       visible.push(spec);
     } else {
       hidden.count++;
+      hidden.names.push(`${spec.resource} ${spec.action}`);
       hidden.gates.add(describeGates(gates));
     }
   }
   return visible;
 }
-function columns(rows, indent = "  ") {
-  const width = Math.max(0, ...rows.map(([left]) => left.length));
+function wrap(text2, indent) {
+  const out = [];
+  let line = "";
+  for (const word of text2.split(" ")) {
+    if (line && indent.length + line.length + 1 + word.length > 110) {
+      out.push(indent + line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) out.push(indent + line);
+  return out.join("\n");
+}
+function columns(rows, indent = "  ", maxWidth = 28) {
+  const width = Math.min(maxWidth, Math.max(0, ...rows.map(([left]) => left.length)));
   return rows.map(([left, right]) => `${indent}${left.padEnd(width)}  ${right}`.trimEnd()).join("\n");
 }
 function withAgentBlock(text2, agent) {
@@ -11730,10 +11758,18 @@ async function renderTopHelp(opts) {
     "  kenso <resource> <action> [flags]",
     "  kenso <resource> <action> --help",
     "",
+    "Rules:",
+    "  Run every write with --dry-run first and read the plan. Then apply: a batch command (import, update, remove,",
+    "  tag, --each) with the plan's next (--yes); any other write without --dry-run.",
+    "  Many rows are one command with the file as it is (--file, --ids, --each), never one command per row: kenso",
+    "  checks and counts the rows. No scripts or shell tests.",
+    "  API resource commands take ids as flags (kenso campaigns get --campaign-id 812), never as bare arguments.",
+    "  An error is one JSON line on stderr: run its next.",
+    "",
     "Commands:"
   ];
   const getFeatures = lazyFeatures(opts);
-  const hiddenSpecs = { count: 0, gates: /* @__PURE__ */ new Set() };
+  const hiddenSpecs = { count: 0, gates: /* @__PURE__ */ new Set(), names: [] };
   const rows = [];
   for (const resource of Object.keys(handWritten).sort()) {
     for (const spec of await visibleSpecs(await loadArea(resource), opts, getFeatures, hiddenSpecs)) {
@@ -11743,6 +11779,9 @@ async function renderTopHelp(opts) {
     }
   }
   lines.push(columns(rows));
+  if (hiddenSpecs.names.length > 0) {
+    lines.push(`  Beta, hidden for this workspace (they still run; the server decides): ${hiddenSpecs.names.sort().join(", ")}.`);
+  }
   const generated = await listGenerated({ features: opts.allCommands ? [] : getFeatures, env: opts.env });
   const visible = generated.filter((g) => opts.allCommands || !g.beta);
   if (visible.length > 0) {
@@ -11752,18 +11791,31 @@ async function renderTopHelp(opts) {
       actions15.push(`${g.action}${g.beta ? " (beta)" : ""}`);
       byResource.set(g.resource, actions15);
     }
-    const generatedRows = [...byResource.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([resource, actions15]) => [resource, actions15.sort().join(", ")]);
-    lines.push("", "API resources (kenso <resource> <action>):", columns(generatedRows));
+    const sorted = [...byResource.entries()].sort(([a], [b]) => a.localeCompare(b));
+    if (opts.allCommands) {
+      const generatedRows = sorted.map(([resource, actions15]) => [resource, actions15.sort().join(", ")]);
+      lines.push("", "API resources (kenso <resource> <action>):", columns(generatedRows));
+    } else {
+      const names = new Set(sorted.map(([resource]) => resource));
+      const common = COMMON_RESOURCES.filter((r) => names.has(r)).join(", ");
+      lines.push(
+        "",
+        `API resources (${names.size}), one per /v1 route group and named like it (/v1/contact-exports: kenso contact-exports).`,
+        wrap(`Common: ${common}.`, "  "),
+        "  kenso <resource> --help lists its actions; kenso --help --all-commands lists every resource."
+      );
+    }
   }
   const hidden = generated.length - visible.length + hiddenSpecs.count;
   if (hidden > 0) lines.push("", `${hidden} beta command${hidden === 1 ? " is" : "s are"} hidden; --all-commands shows them.`);
-  lines.push("", "Global flags:", columns(GLOBAL_FLAG_HELP), "", EXIT_CODES);
+  if (opts.allCommands) lines.push("", "Global flags:", columns(GLOBAL_FLAG_HELP), "", EXIT_CODES);
+  else lines.push("", GLOBAL_FLAGS_LINE, EXIT_CODES);
   return withAgentBlock(lines.join("\n"), opts.agent);
 }
 async function renderResourceHelp(resource, opts) {
   const getFeatures = lazyFeatures(opts);
   const all = await loadArea(resource);
-  const hidden = { count: 0, gates: /* @__PURE__ */ new Set() };
+  const hidden = { count: 0, gates: /* @__PURE__ */ new Set(), names: [] };
   const specs = await visibleSpecs(all, opts, getFeatures, hidden);
   const handWrittenActions = new Set(all.map((s) => s.action));
   const listed = (await listGenerated({ features: opts.allCommands ? [] : getFeatures, env: opts.env })).filter(
@@ -11787,10 +11839,18 @@ async function renderResourceHelp(resource, opts) {
     });
   }
   const rows = [
-    ...specs.map((s) => [usageLine2(s).slice("kenso ".length), `${s.summary}${s.beta ? " (beta)" : ""}`]),
-    ...generated.map((g) => [`${resource} ${g.action}`, `${g.summary}${g.beta ? " (beta)" : ""}`])
+    ...specs.map((s) => [usageLine2(s).slice(`kenso ${resource} `.length).replace(/ ?\[flags\]$/, ""), `${s.summary}${s.beta ? " (beta)" : ""}`]),
+    ...generated.map((g) => [g.action, `${g.summary}${g.beta ? " (beta)" : ""}`])
   ].sort(([a], [b]) => a.localeCompare(b));
-  const lines = [`Usage: kenso ${resource} <action> [flags]`, "", "Actions:", columns(rows), "", `Run kenso ${resource} <action> --help for an action's flags.`];
+  const lines = [`Usage: kenso ${resource} <action> [flags]`, "", "Actions:", columns(rows)];
+  const hiddenActions = [
+    ...all.filter((s) => !specs.includes(s)).map((s) => s.action),
+    ...listed.filter((g) => !generated.includes(g)).map((g) => g.action)
+  ].sort();
+  if (hiddenActions.length > 0) {
+    lines.push("", `Beta, hidden for this workspace (they still run; the server decides): ${hiddenActions.join(", ")}.`);
+  }
+  lines.push("", `Run kenso ${resource} <action> --help for an action's flags.`);
   return withAgentBlock(lines.join("\n"), opts.agent);
 }
 function renderCommandHelp(spec, opts) {
@@ -11799,16 +11859,18 @@ function renderCommandHelp(spec, opts) {
   if (spec.positionals && spec.positionals.length > 0) {
     lines.push("", "Arguments:", columns(spec.positionals.map((p) => [`<${p.name}>`, `${p.description}${p.required ? "" : " (optional)"}`])));
   }
-  const flagRows = Object.entries(spec.flags).sort(([a], [b]) => a.localeCompare(b)).map(([name, flag]) => {
+  const paired = (name) => spec.flags[name]?.type === "boolean" && spec.flags[`no-${name}`]?.type === "boolean";
+  const flagRows = Object.entries(spec.flags).filter(([name]) => !(name.startsWith("no-") && paired(name.slice(3)))).sort(([a], [b]) => a.localeCompare(b)).map(([name, flag]) => {
     const notes = [flag.required ? "required" : "", flag.default !== void 0 ? `default ${String(flag.default)}` : ""].filter(Boolean);
-    return [flagLabel(name, flag), `${flag.description}${notes.length ? ` (${notes.join(", ")})` : ""}`];
+    const label = paired(name) ? flagLabel(name, flag).replace(`--${name}`, `--[no-]${name}`) : flagLabel(name, flag);
+    return [label, `${flag.description}${notes.length ? ` (${notes.join(", ")})` : ""}`];
   });
   if (flagRows.length > 0) lines.push("", "Flags:", columns(flagRows));
-  lines.push("", "Global flags:", columns(GLOBAL_FLAG_HELP));
+  lines.push("", GLOBAL_FLAGS_LINE);
   if (spec.examples.length > 0) lines.push("", "Examples:", ...spec.examples.map((e) => `  ${e}`));
   return withAgentBlock(lines.join("\n"), opts.agent);
 }
-var GLOBAL_FLAG_HELP, EXIT_CODES, FOR_AGENTS;
+var GLOBAL_FLAG_HELP, GLOBAL_FLAGS_LINE, COMMON_RESOURCES, EXIT_CODES, FOR_AGENTS;
 var init_help = __esm({
   "src/commands/help.ts"() {
     "use strict";
@@ -11832,6 +11894,26 @@ var init_help = __esm({
       ["-h, --help", "Show help"],
       ["--version", "Print the version"]
     ];
+    GLOBAL_FLAGS_LINE = "Global flags: --dry-run, -y/--yes, --workspace <id>, --profile, -o/--output json|ndjson|table|ids, --fields, --query, -v, --progress (kenso --help --all-commands explains them).";
+    COMMON_RESOURCES = [
+      "accounts",
+      "analytics",
+      "blocklist-entries",
+      "campaigns",
+      "contact-exports",
+      "contact-imports",
+      "contacts",
+      "domains",
+      "inboxes",
+      "lists",
+      "members",
+      "prompts",
+      "segments",
+      "tags",
+      "threads",
+      "webhook-endpoints",
+      "workspaces"
+    ];
     EXIT_CODES = "Exit codes: 0 ok, 1 error, 2 usage, 3 auth, 4 not found, 5 some rows failed, 6 rate limited or limit reached, 7 conflict, 8 server error, 130 interrupted.";
     FOR_AGENTS = [
       "For agents:",
@@ -11950,11 +12032,13 @@ async function unknownCommand(tokens, resource) {
   const all = await knownCommands();
   const scoped = tokens.length > 1 && all.has(resource) ? [...all].filter((c) => c.startsWith(`${resource} `)) : [...all];
   const best = closest(typed, scoped);
+  const related = all.has(resource) ? [] : [...all].filter((c) => !c.includes(" ") && c !== best && (c.includes(resource) || c.length >= 4 && resource.includes(c))).sort().slice(0, 6);
+  const hints = [best ? `did you mean "kenso ${best}"?` : "", related.length ? `Resources named like it: ${related.join(", ")}.` : ""];
   return new KensoError({
     code: "unknown_command",
     message: `Unknown command "kenso ${tokens.join(" ")}".`,
     exitCode: ExitCode.Usage,
-    hint: best ? `did you mean "kenso ${best}"?` : "Run kenso --help to list the commands.",
+    hint: hints.filter(Boolean).join(" ") || "Run kenso --help to list the commands.",
     next: "kenso --help"
   });
 }