kenso 0.1.16 → 0.1.17

package/dist/kenso.js

@@ -2397,7 +2397,7 @@ var VERSION;
 var init_version = __esm({
   "src/core/version.ts"() {
     "use strict";
-    VERSION = true ? "0.1.16" : "0.0.0-dev";
+    VERSION = true ? "0.1.17" : "0.0.0-dev";
   }
 });
 
@@ -6215,8 +6215,10 @@ var init_each = __esm({
 var execute_exports = {};
 __export(execute_exports, {
   DATA_KEY: () => DATA_KEY,
+  HELP_FLAG_MAX: () => HELP_FLAG_MAX,
   HELP_NOTES_MAX: () => HELP_NOTES_MAX,
   buildRequest: () => buildRequest,
+  helpFlagText: () => helpFlagText,
   helpNotes: () => helpNotes,
   operationExamples: () => operationExamples,
   operationFlags: () => operationFlags,
@@ -6522,28 +6524,57 @@ async function runOperation(ctx, op, flags) {
   ctx.output.object(unwrap(res.body));
   return ExitCode.Ok;
 }
+function normalizedNotes(op) {
+  return (op.description ?? "").trim().replace(/\n[ \t]+/g, "\n");
+}
 function helpNotes(op) {
-  const text2 = (op.description ?? "").trim().replace(/\n[ \t]+/g, "\n");
+  const text2 = normalizedNotes(op);
   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}.`;
+  return end > HELP_NOTES_MAX / 3 ? head.slice(0, end + 1) : `${head.trimEnd()}...`;
+}
+function helpFlagText(f) {
+  const enumText = f.enum ? ` One of: ${f.enum.join(", ")}.` : "";
+  let base = f.description;
+  if (enumText && base.endsWith(enumText)) base = base.slice(0, -enumText.length);
+  const placeholder = f.param ? /^\S+ \((?:path|query|body), ([\w-]+)\)$/.exec(base) : null;
+  if (placeholder) return { text: `${placeholder[1]}${enumText}`, cut: false };
+  let text2 = base;
+  const sentence = /\.(?=\s+[A-Z])/.exec(text2);
+  if (sentence) text2 = text2.slice(0, sentence.index + 1);
+  if (text2.length > HELP_FLAG_MAX) {
+    const head = text2.slice(0, HELP_FLAG_MAX);
+    text2 = `${head.slice(0, Math.max(head.lastIndexOf(" "), HELP_FLAG_MAX / 2)).replace(/[,;:]$/, "")}...`;
+  }
+  return { text: `${text2}${enumText}`, cut: text2 !== base };
 }
 function operationToCommand(op) {
   const flags = {};
+  let cut = false;
   for (const f of operationFlags(op)) {
+    const shown = helpFlagText(f);
+    cut ||= shown.cut;
     const spec = {
       type: f.type === "boolean" ? "boolean" : "string",
       // The dispatcher would enforce `required` before --each rows can fill it, so the command checks it instead.
-      description: f.required ? `${f.description} (required)` : f.description
+      description: f.required ? `${shown.text} (required)` : shown.text
     };
     if (f.multiple) spec.multiple = true;
+    if (FOOTER_FLAGS.has(f.flag) && !f.param) spec.helpHidden = true;
     flags[f.flag] = spec;
   }
-  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 write2 = op.method === "GET" ? "" : "\nA write: it sends at once. Run it with --dry-run first, then without.";
   const api = `API: ${op.method} ${op.path} (${op.id}).${write2}`;
+  const named = [...op.routeParams, ...op.queryParams].find((p) => p.flag !== p.name);
+  const keys = named ? `keys fill flags, by flag or API name: ${named.flag} or ${named.name}` : "keys fill flags";
+  const rows = `Many rows: --each <file>, once per CSV or JSONL row (${keys}${op.body ? "; other keys the body" : ""}; --concurrency 1-16)${op.method === "GET" ? "" : ", --dry-run then --yes"}.`;
+  const more = [
+    op.body ? "--data <json|@file|->: the body (flags win)." : "",
+    // The same text helpNotes measures, so the pointer shows only when something was left out.
+    cut || normalizedNotes(op).length > HELP_NOTES_MAX ? `Full notes: kenso describe ${op.resource} ${op.action}.` : ""
+  ].filter(Boolean);
+  const footer = [rows, ...more.length ? [more.join(" ")] : []];
   return {
     resource: op.resource,
     action: op.action,
@@ -6552,13 +6583,19 @@ function operationToCommand(op) {
 
 ${api}` : api,
     flags,
-    examples: operationExamples(op),
+    // describe keeps the --data example; help shows the dry run and the apply, and for a write the file of rows
+    // (agents copy examples, and one with only --<id> flags led them to one call per row).
+    examples: [
+      ...operationExamples(op).filter((e) => !e.endsWith(" --data @body.json")),
+      ...op.method === "GET" ? [] : [`${commandOf(op)} --each rows.csv --dry-run   # a file of rows: one command`]
+    ],
+    helpFooter: footer,
     ...op.featureGates ? { beta: { featureGates: op.featureGates } } : {},
     operationIds: [op.id],
     run: (ctx, args) => runOperation(ctx, op, args.flags)
   };
 }
-var DATA_KEY, SCALAR_TYPES, LIST_PARAM_TEXT, HELP_NOTES_MAX;
+var DATA_KEY, SCALAR_TYPES, LIST_PARAM_TEXT, HELP_NOTES_MAX, HELP_FLAG_MAX, FOOTER_FLAGS;
 var init_execute = __esm({
   "src/generated/execute.ts"() {
     "use strict";
@@ -6572,7 +6609,9 @@ var init_execute = __esm({
       limit: "Page size.",
       cursor: "Start at this cursor (the next: hint of a previous page)."
     };
-    HELP_NOTES_MAX = 600;
+    HELP_NOTES_MAX = 320;
+    HELP_FLAG_MAX = 140;
+    FOOTER_FLAGS = /* @__PURE__ */ new Set(["each", "concurrency", "data"]);
   }
 });
 
@@ -6909,13 +6948,14 @@ var init_import = __esm({
       resource: "accounts",
       action: "import",
       summary: "Create accounts (companies) from a CSV or JSONL file, charged per created account; a file of people: people import",
+      brief: "companies, charged per new account",
       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" },
         concurrency: { type: "string", description: "Calls in flight, 1 to 16 (default 4)" },
         out: { type: "string", description: "Keep the run's files in this directory instead of ~/.kenso/runs" }
       },
-      examples: ["kenso accounts import --file accounts.csv", "kenso accounts import --file accounts.csv --yes"],
+      examples: ["kenso accounts import --file accounts.csv --dry-run", "kenso accounts import --file accounts.csv --yes"],
       beta: { featureGates: { all: ["accounts"] } },
       operationIds: ["accounts.bulk-create", "credit-estimates.create"],
       async run(ctx, args) {
@@ -7008,7 +7048,8 @@ var init_api3 = __esm({
     command2 = {
       resource: "api",
       action: "",
-      summary: "Call any Kenso API route with auth and headers set",
+      summary: "Call any API route, only when no command fits",
+      brief: "only when no command fits",
       description: "The raw escape hatch: sends Authorization, Ken-Version: 1.1 and X-Ken-Workspace-Id, prints the full JSON body. The path may carry a query string. --all (GET only) follows pagination.nextCursor and prints the data[] items as a list. Writes run without --yes.",
       flags: {
         data: { type: "string", description: "Request body: inline JSON, @file or - for stdin" },
@@ -7319,7 +7360,8 @@ var init_login = __esm({
     command3 = {
       resource: "auth",
       action: "login",
-      summary: "Save an API key on this machine (--with-key reads it from stdin)",
+      summary: "Save an API key (--with-key reads it from stdin: pipe a variable in, no check first)",
+      brief: "--with-key reads the key from stdin: pipe a variable in, no check first",
       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" },
@@ -7434,7 +7476,7 @@ var init_logout = __esm({
     command4 = {
       resource: "auth",
       action: "logout",
-      summary: "Remove a saved profile and its key from this machine",
+      summary: "Remove a saved profile and its key",
       description: "Removes the profile (--profile, KENSO_PROFILE or the active one) from ~/.kenso/config.json. The key itself stays valid: revoke it at Settings > Integrations > API keys.",
       flags: {},
       examples: ["kenso auth logout", "kenso auth logout --profile client-a"],
@@ -7470,7 +7512,7 @@ var init_status = __esm({
     command5 = {
       resource: "auth",
       action: "status",
-      summary: "Show who the key belongs to, the active workspace and when the key expires",
+      summary: "Show the key's user, workspace and expiry",
       description: `Reads GET /v1/me for the email and workspaces, and GET /v1/api-keys for the key's expiry. Warns on stderr when the key expires within ${EXPIRY_WARNING_DAYS} days.`,
       flags: {},
       examples: ["kenso auth status", "kenso auth status --profile client-a"],
@@ -8200,7 +8242,7 @@ var init_wait = __esm({
     command6 = {
       resource: "jobs",
       action: "wait",
-      summary: "Wait for a background job to finish and print it",
+      summary: "Wait for a background job and print it",
       description: "Polls GET /v1/jobs/{jobId}?type=<type> every 2 s (every 10 s after the first minute) until the job succeeds, fails or is canceled, then prints the job. Exit 0 when it succeeded, 1 when it failed, was canceled or is still running when --timeout passes.",
       flags: {
         type: { type: "string", required: true, description: "The job type, for example contact_import or contact_export" },
@@ -8440,7 +8482,8 @@ var init_import2 = __esm({
     command7 = {
       resource: "contacts",
       action: "import",
-      summary: "Add leads from a CSV or JSONL file to a campaign, with one result per row",
+      summary: "Add leads from a CSV or JSONL file to a campaign",
+      brief: "a file into a campaign",
       description: "Maps columns by header (email, firstName, lastName, title, linkedInUrl, companyName, companyDomain; every other column becomes a custom variable), checks every row locally, then sends 1,000 rows per call to POST /v1/campaigns/{campaignId}/contacts. Without --yes it prints the plan and the credit estimate. Rerunning the same command on the same file resumes the run. Exit 5 when some rows failed or were invalid, 6 when the contact limit stopped the run.",
       flags: {
         campaign: { type: "string", description: "The campaign id (required unless --template)" },
@@ -8452,10 +8495,8 @@ var init_import2 = __esm({
         out: OUT_FLAG
       },
       examples: [
-        "kenso contacts import --template",
-        "kenso contacts import --campaign 812 --file leads.csv",
+        "kenso contacts import --campaign 812 --file leads.csv --dry-run",
         "kenso contacts import --campaign 812 --file leads.csv --yes",
-        `kenso contacts import --campaign 812 --file leads.csv --map '{"Pain": "customVariables.pain_point", "Notes": null}' --yes`,
         "kenso contacts import --campaign 812 --file big.csv --server-import --yes"
       ],
       operationIds: ["contacts.create", "campaigns.get", "credit-estimates.create", "contact-imports.create", "jobs.get"],
@@ -8647,7 +8688,8 @@ var init_update = __esm({
     command8 = {
       resource: "contacts",
       action: "update",
-      summary: "Edit leads from a CSV or JSONL file, matched by id or by email (also one lead)",
+      summary: "Edit leads from a CSV or JSONL file, by id or email (also one lead)",
+      brief: "a file, by id or 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" },
@@ -8658,9 +8700,10 @@ var init_update = __esm({
         concurrency: CONCURRENCY_FLAG
       },
       examples: [
-        "kenso contacts update --file edits.csv --match id",
+        "kenso contacts update --file edits.csv --match id --dry-run",
         "kenso contacts update --file edits.csv --match id --yes",
-        "kenso contacts update --file edits.csv --match email --campaign 812 --yes"
+        "kenso contacts update --file edits.csv --match email --campaign 812 --dry-run",
+        "printf 'id,title\\n9001,VP Sales\\n' | kenso contacts update --file - --match id --dry-run   # one lead"
       ],
       operationIds: ["contacts.bulk-update", "contacts.list"],
       async run(ctx, { flags }) {
@@ -8920,20 +8963,21 @@ 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). The dry-run plan shows what matches: no separate search first" };
+  else flags.where = { type: "string", description: "contacts search filters as JSON, @file or - (the body of POST /v1/contacts/search: campaignIds, q matches names and emails, filters match fields such as ContactCompany.Name). Its dry-run plan shows the count and first ids: check the match there, never with a search or list 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: 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`,
+    summary: kind === "restore" ? `${route.verb} contacts by --ids or by a remove run (--run)` : `${route.verb} contacts by --ids file or --where filters`,
+    brief: kind === "restore" ? "--ids or --run" : "--ids file or --where, no search first",
     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"}' --dry-run`],
+      ...kind === "restore" ? ["kenso contacts restore --run r_ab3dxk2q --yes"] : [`kenso contacts ${kind} --where '{"campaignIds": [812], "filters": [{"conditions": {"field": "ContactCompany.Name", "operator": 2, "value": "acme"}}]}' --dry-run`],
       ...kind === "remove" ? ["kenso contacts remove --ids big.csv --confirm 2500 --yes"] : []
     ],
     ...kind === "pause" ? { beta: { featureGates: { all: ["pause_leads"] } } } : {},
@@ -9074,7 +9118,8 @@ function tagCommand(kind) {
   return {
     resource: "contacts",
     action: kind,
-    summary: `${kind === "tag" ? "Add a tag to" : "Remove a tag from"} contacts by id (--ids only: for a campaign, contacts list its ids first)`,
+    summary: `${kind === "tag" ? "Add a tag to" : "Remove a tag from"} contacts by --ids only (a campaign: list its ids first)`,
+    brief: "--ids only",
     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)" },
@@ -9082,7 +9127,7 @@ function tagCommand(kind) {
       out: OUT_FLAG,
       concurrency: CONCURRENCY_FLAG
     },
-    examples: [`kenso contacts ${kind} --tag 31 --ids ids.txt`, `kenso contacts ${kind} --tag 31 --ids ids.txt --yes`],
+    examples: [`kenso contacts ${kind} --tag 31 --ids ids.txt --dry-run`, `kenso contacts ${kind} --tag 31 --ids ids.txt --yes`],
     operationIds: [kind === "tag" ? "tags.assign" : "tags.unassign"],
     async run(ctx, { flags }) {
       const tagId = idFlag(flags, "tag", name);
@@ -9197,7 +9242,8 @@ var init_export = __esm({
     command9 = {
       resource: "contacts",
       action: "export",
-      summary: "Export a campaign's contacts to a CSV file (a segment: kenso contact-exports create)",
+      summary: "Export a campaign's contacts to CSV (a segment: contact-exports create)",
+      brief: "a campaign to CSV; a segment: 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" },
@@ -9389,7 +9435,8 @@ var init_describe = __esm({
     command10 = {
       resource: "describe",
       action: "",
-      summary: "Print the command map as JSON: every command, its flags and body schema",
+      summary: "The command map as JSON: commands, flags, body schemas",
+      brief: "",
       description: "Always JSON. No arguments: every command with its summary. A resource: its commands with their flags. A resource and an action: one command in full (method, path, flags, body schema, examples). Beta commands your workspace has not enabled are left out unless --all-commands; calling one still works.",
       flags: {
         // Used by scripts/build-reference.ts to write docs/reference.md in one call.
@@ -9469,7 +9516,7 @@ var init_batch = __esm({
 var crm_default;
 var init_crm = __esm({
   "docs/crm.md"() {
-    crm_default = "# CRM (beta)\n\nThe CRM commands work on Kenso's Accounts lane: accounts (companies), the people on them, and opportunities. They are beta: they need the `accounts` feature flag on your workspace (opportunities need `opportunities`, CRM sync needs `ingestion`). Help and `kenso describe` hide them until your workspace has the flag; `--all-commands` shows them.\n\n| Command | What it does |\n|---|---|\n| `accounts import` | Create accounts from a CSV or JSONL file. Research is charged per created account |\n| `people import` | Create or match people from a file, optionally onto accounts |\n| `accounts update --each`, `people update --each`, `opportunities update --each` | Edit many records from a file, one call per row |\n| `crm-connections`, `crm-imports`, `crm-sync-issues` | Read and run CRM sync. Connecting a CRM stays in the app |\n\nImport accounts first, then people: `people import` never creates an account.\n\n## Import accounts\n\n```bash\nkenso accounts import --file accounts.csv\nkenso accounts import --file accounts.csv --yes\n```\n\n```csv\nname,domain,industry,employeeCount\nAcme,acme.io,Software,120\nGlobex,globex.com,Manufacturing,\"1,200\"\n```\n\n- **Columns** map by name, ignoring case, spaces and dashes: `name` (or `company`, `companyName`, `accountName`), `domains` (several, split on `,` or `;`) or one `domain` (or `website`, `companyDomain`), `industry`, `employeeCount`, `hqLocation`, `linkedinUrl`, `stage`, `angle`, `whyNow`, `fitScore`, `fundingRound`, `cadenceDays`, `ownerMemberId`, `kenCompanyId`, `sendsFromInboxId`, `sendsFromLinkedInAccountId` and `source`.\n- **A domain is required.** A file with no domain column is a usage error, and a row without a domain is `invalid` (`domain_required`).\n- **The dry run prices the research.** It asks for a credit estimate per 1,000 accounts and puts the sum in the plan: `kind`, `accountCount`, `totalMillicredits`, `availableMillicredits` and `sufficient`.\n- **Rows go 100 per call** to `POST /v1/accounts/bulk-create`.\n\nEach row comes back:\n\n| Status | Meaning |\n|---|---|\n| `created` | A new account; `id` is the account id. Research is queued (`researchQueued` in the summary), or waits for credits (`researchWaitingCredits`) |\n| `skipped`, reason `domain_taken` | A company that is already an account; `id` is that account |\n| `failed` | Kenso refused the row (`reason` is the API's code, `error` names the field) or failed to save it. An item Kenso failed to save is sent once more before it counts as failed |\n\nRerunning the same file is safe: accounts that exist come back `domain_taken`.\n\n## Import people\n\n```bash\nkenso people import --file people.csv\nkenso people import --file people.csv --find-emails --yes\nkenso people import --file people.jsonl --dry-run\n```\n\n```csv\nfullName,email,title,accountDomain,role\nAnn Lee,ann@acme.io,VP Sales,acme.io,champion\nBob Ray,,CTO,acme.io,\n```\n\n- **Columns** map by name, ignoring case, spaces and dashes: `email`, `fullName` (or `name`), `firstName`, `lastName`, `title`, `linkedinUrl` (or `linkedin`, `profileUrl`), `accountDomain` (or `domain`, `website`, `companyDomain`), `accountId`, `role` and `priority`. Other columns are ignored with one warning.\n- **A person needs a name:** `fullName`, or `firstName`, `lastName` or both (the CLI joins them). A row with none of them is `invalid` (`name_required`).\n- **To put a person on an account,** give `accountDomain` or `accountId`. A row with both sends only `accountId`.\n- **`--find-emails`** queues an email find (charged in credits) for each person without an email.\n- **Rows go 200 per call** to `POST /v1/people/batch`.\n\nPeople already in the workspace are matched by email, then LinkedIn URL, so running the same file again creates nobody twice.\n\n| Result | Row status | reason |\n|---|---|---|\n| A new person | `created` | |\n| An existing person, added to the account | `updated` | |\n| An existing person already on the account | `skipped` | `already_on_account` |\n| An existing person, no account asked | `skipped` | `matched` |\n| The person was removed from the account before | `skipped` | `previously_removed` |\n| The account does not exist | `failed` | `account_not_found`: the person was saved without an account. Import the account, then rerun to place them |\n| Kenso refused the row | `failed` | the API's reason |\n\nThe summary adds `matched`, `addedToAccounts` and `emailFindsQueued`.\n\n## Edit accounts, people and opportunities\n\nApart from `accounts bulk-update`, which sets one `accountType` on up to 500 accounts, there is no bulk edit route, so run the generated `update` command once per row with `--each`. Columns are the command's flags by API name or flag name, and the id column fills the route:\n\n```bash\nkenso accounts update --each accounts-edit.csv --dry-run\nkenso accounts update --each accounts-edit.csv --yes\nkenso people update --each people-edit.csv --yes\nkenso opportunities update --each deals.csv --yes\n```\n\n```csv\naccountId,stage,ownerMemberId,overwritePinned\n501,engaged,42,true\n502,customer,42,true\n```\n\nA row that changes a field someone pinned in the app fails as a whole (`409 conflict`, `pinned_by_user`: nothing on that record changes, the other fields of the row included), unless the row sets `overwritePinned` to `true` (or you pass `--overwrite-pinned`). To see every flag of an update command:\n\n```bash\nkenso describe accounts update\nkenso accounts update --help\n```\n\n## CRM sync\n\nCRM sync has generated commands only: read connections, preview, start an import, and work through sync issues. Connect the CRM itself in the app.\n\n```bash\nkenso crm-connections list\nkenso crm-connections get --connection-id 7\nkenso crm-imports create --connection-id 7 --dry-run\nkenso crm-sync-issues list --connection-id 7 --all\n```\n\nRun `kenso crm-connections --help` (or add `--all-commands` when the actions are hidden) to see every action.\n";
+    crm_default = "# CRM (beta)\n\nThe CRM commands work on Kenso's Accounts lane: accounts (companies), the people on them, and opportunities. They are beta: they need the `accounts` feature flag on your workspace (opportunities need `opportunities`, CRM sync needs `ingestion`). Help and `kenso describe` hide them until your workspace has the flag; `--all-commands` shows them.\n\n| Command | What it does |\n|---|---|\n| `accounts import` | Create accounts from a CSV or JSONL file. Research is charged per created account |\n| `people import` | Create or match people from a file, optionally onto accounts |\n| `accounts update --each`, `people update --each`, `opportunities update --each` | Edit many records from a file, one call per row |\n| `crm-connections`, `crm-imports`, `crm-sync-issues` | Read and run CRM sync. Connecting a CRM stays in the app |\n\nImport accounts first, then people: `people import` never creates an account.\n\n## Import accounts\n\n```bash\nkenso accounts import --file accounts.csv\nkenso accounts import --file accounts.csv --yes\n```\n\n```csv\nname,domain,industry,employeeCount\nAcme,acme.io,Software,120\nGlobex,globex.com,Manufacturing,\"1,200\"\n```\n\n- **Columns** map by name, ignoring case, spaces and dashes: `name` (or `company`, `companyName`, `accountName`), `domains` (several, split on `,` or `;`) or one `domain` (or `website`, `companyDomain`), `industry`, `employeeCount`, `hqLocation`, `linkedinUrl`, `stage`, `angle`, `whyNow`, `fitScore`, `fundingRound`, `cadenceDays`, `ownerMemberId`, `kenCompanyId`, `sendsFromInboxId`, `sendsFromLinkedInAccountId` and `source`.\n- **A domain is required.** A file with no domain column is a usage error, and a row without a domain is `invalid` (`domain_required`).\n- **The dry run prices the research.** It asks for a credit estimate per 1,000 accounts and puts the sum in the plan: `kind`, `accountCount`, `totalMillicredits`, `availableMillicredits` and `sufficient`.\n- **Rows go 100 per call** to `POST /v1/accounts/bulk-create`.\n\nEach row comes back `created` (`id` is the new account; its research is queued, `researchQueued`, or waits for credits, `researchWaitingCredits`), `skipped` with reason `domain_taken` (already an account; `id` is that account) or `failed` (`reason` is the API's code, `error` names the field; an item Kenso failed to save is sent once more first). Rerunning the same file is safe: accounts that exist come back `domain_taken`.\n\n## Import people\n\n```bash\nkenso people import --file people.csv\nkenso people import --file people.csv --find-emails --yes\nkenso people import --file people.jsonl --dry-run\n```\n\n```csv\nfullName,email,title,accountDomain,role\nAnn Lee,ann@acme.io,VP Sales,acme.io,champion\nBob Ray,,CTO,acme.io,\n```\n\n- **Columns** map by name, ignoring case, spaces and dashes: `email`, `fullName` (or `name`), `firstName`, `lastName`, `title`, `linkedinUrl` (or `linkedin`, `profileUrl`), `accountDomain` (or `domain`, `website`, `companyDomain`), `accountId`, `role` and `priority`. Other columns are ignored with one warning.\n- **A person needs a name:** `fullName`, or `firstName`, `lastName` or both (the CLI joins them). A row with none of them is `invalid` (`name_required`).\n- **To put a person on an account,** give `accountDomain` or `accountId`. A row with both sends only `accountId`.\n- **`--find-emails`** queues an email find (charged in credits) for each person without an email.\n- **Rows go 200 per call** to `POST /v1/people/batch`.\n\nPeople already in the workspace are matched by email, then LinkedIn URL, so running the same file again creates nobody twice. A row comes back `created` (a new person), `updated` (an existing person added to the account), `skipped` with reason `already_on_account`, `matched` (no account asked) or `previously_removed`, or `failed`: `account_not_found` saves the person without an account (import the account, then rerun to place them), any other reason is the API's. The summary adds `matched`, `addedToAccounts` and `emailFindsQueued`.\n\n## Edit accounts, people and opportunities\n\nApart from `accounts bulk-update`, which sets one `accountType` on up to 500 accounts, there is no bulk edit route, so run the generated `update` command once per row with `--each`. Columns are the command's flags by API name or flag name, and the id column fills the route:\n\n```bash\nkenso accounts update --each accounts-edit.csv --dry-run   # then the same with --yes\nkenso people update --each people-edit.csv --dry-run\nkenso opportunities update --each deals.csv --dry-run\n```\n\n```csv\naccountId,stage,ownerMemberId,overwritePinned\n501,engaged,42,true\n502,customer,42,true\n```\n\nA row that changes a field someone pinned in the app fails as a whole (`409 conflict`, `pinned_by_user`: nothing on that record changes, the other fields of the row included), unless the row sets `overwritePinned` to `true` (or you pass `--overwrite-pinned`, only with the person's OK). Every flag of an update command: `kenso accounts update --help`.\n\n## CRM sync\n\nCRM sync has generated commands only: read connections, preview, start an import, and work through sync issues. Connect the CRM itself in the app.\n\n```bash\nkenso crm-connections list\nkenso crm-connections get --connection-id 7\nkenso crm-imports create --connection-id 7 --dry-run\nkenso crm-sync-issues list --connection-id 7 --all\n```\n\nRun `kenso crm-connections --help` (or add `--all-commands` when the actions are hidden) to see every action.\n";
   }
 });
 
@@ -9477,7 +9524,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 `-`, 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';
+    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. `q` matches names and email addresses only; a company is a `filters` condition on `ContactCompany.Name` (`operator` 2 is contains; `kenso describe contacts search` lists the fields and operators).\n\n```bash\nkenso contacts remove --ids ids.txt --dry-run\nkenso contacts remove --ids ids.txt --yes\nkenso contacts remove --where \'{"campaignIds": [812], "filters": [{"conditions": {"field": "ContactCompany.Name", "operator": 2, "value": "acme"}}]}\' --dry-run\nkenso contacts remove --where \'{"campaignIds": [812], "filters": [{"conditions": {"field": "ContactCompany.Name", "operator": 2, "value": "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';
   }
 });
 
@@ -9509,7 +9556,7 @@ var init_studio = __esm({
 var SKILL_default;
 var init_SKILL = __esm({
   "skill/kenso-cli/SKILL.md"() {
-    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';
+    SKILL_default = '---\nname: kenso-cli\ndescription: The Kenso CLI (kenso) for work from a file (of any size, even a few ids) or over about 50 records - import, update, remove (delete), 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, resume an interrupted run, sign in with a key from a variable (pipe it to kenso auth login --with-key, no check first). For records listed in the message (under about 50), one record or a question, use the Kenso MCP.\n---\n\n1. Every write runs first with `--dry-run`; apply with the plan\'s `next`. `--yes` at once only to continue an interrupted run or apply what the person confirmed.\n2. Many rows: one command on the file as it is (`--file`, `--ids`, `--each`). Run kenso only: no python, awk or shell tests, not even on a file or variable.\n3. Any output\'s `next` is the command to run; errors are JSON on stderr. `--force` only with the person\'s OK.\n4. Ids are flags: `--campaign 812` on contacts import, update, export; `--campaign-id 812` on API commands. `--workspace <id>`; by name `kenso workspace list --q acme`. Other commands: `kenso --help`; `kenso api <METHOD> <path>` only when none fits.\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 lead; or --match email --campaign 812\nkenso contacts remove --ids ids.txt --dry-run   # also pause, resume, restore; over 1,000: --confirm <count>\nkenso contacts remove --where \'{"campaignIds": [812], "filters": [{"conditions": {"field": "ContactCompany.Name", "operator": 2, "value": "acme"}}]}\' --dry-run   # also pause, resume; 2 = contains; no search first\nkenso contacts tag --tag 31 --ids ids.txt --dry-run   # tag, restore: --ids only, so first kenso contacts list --campaign-id 812 --all -o ids > ids.txt\nkenso contact-imports create --source campaign --source-campaign-id 10601 --campaign-id 812 --dry-run   # copy another campaign\'s leads in\nkenso contacts export --campaign 812 --out leads.csv   # a segment: kenso contact-exports create --segment-id 55\nkenso runs resume <runId>   # an interrupted run; terminal lost: kenso runs list finds it. A changed file is a new run\nkenso accounts import --file accounts.csv --dry-run   # companies; a file of people: kenso people import --file people.csv\nkenso studio push 12 --dir ./tpl   # to preview local edits push first (draft; live needs --publish), then studio preview 12\nkenso studio fill 12 --accounts ids.txt --dry-run   # or --campaign 10546 --contacts leads.csv\nkenso opportunities update --each rows.csv --dry-run   # any API command on a file of rows (CSV or JSONL; keys fill flags and body). One record: kenso campaigns update --campaign-id 812 --name Q4 --dry-run\nkenso mcp call list_skills   # only to list Ken\'s skills\n```\n\nCharges: `accounts import` per new account, `studio fill` per page (again for ids from another file): show the estimate. `pinned_by_user`: with the person\'s OK, rerun with `--overwrite-pinned`. Workflows: `kenso workflows brief` first; secrets only as `{{secrets.NAME}}`. Key: `KENSO_API_KEY`, or pipe a variable, no check: `printf \'%s\' "$KEY" | kenso auth login --with-key`; never in a flag, output or file.\n';
   }
 });
 
@@ -9603,7 +9650,8 @@ var init_docs = __esm({
     command11 = {
       resource: "docs",
       action: "",
-      summary: "Read the CLI docs offline: the topic list, or one topic as Markdown",
+      summary: "Offline docs: the topic list, or one topic",
+      brief: "",
       description: "Without a topic, lists the topics with one line each (NDJSON when piped). With a topic, prints that page's Markdown to stdout. The same pages are in the package's docs/ folder.",
       flags: {},
       positionals: [{ name: "topic", description: `One of ${NAMES}` }],
@@ -9690,7 +9738,8 @@ var init_doctor = __esm({
     command12 = {
       resource: "doctor",
       action: "",
-      summary: "Check the setup: Node, the config file, the API and the key",
+      summary: "Check Node, the config, the API and the key",
+      brief: "",
       description: "Prints the version, Node, platform, config location, profile, key source, API URL, workspace and detected agent, plus checks node_version, config_permissions, api_reachable and key_valid. Exits 0 when every check passes, 3 when the key check fails, else 1.",
       flags: {},
       examples: ["kenso doctor", "kenso doctor --profile client-a --output json"],
@@ -10006,13 +10055,14 @@ var init_call = __esm({
     command13 = {
       resource: "mcp",
       action: "call",
-      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.",
+      summary: "Call a hosted Kenso MCP tool, such as list_skills (no mcp tools first)",
+      brief: "list_skills runs directly",
+      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 and load_skill take no kenso mcp tools first. 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)" }],
+      positionals: [{ name: "tool", required: true, description: "The tool name: list_skills, load_skill, or one from kenso mcp tools" }],
       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 }) {
@@ -10069,6 +10119,7 @@ var init_tools = __esm({
       resource: "mcp",
       action: "tools",
       summary: "List the hosted Kenso MCP's tools",
+      brief: "only to find a tool name",
       description: "Lists every tool of the Kenso MCP (KENSO_MCP_URL, default https://mcp.ken.so/mcp) as { name, description }, with the same API key. Call one with kenso mcp call <tool>.",
       flags: {},
       examples: ["kenso mcp tools", "kenso mcp tools --fields name"],
@@ -10202,6 +10253,7 @@ var init_import3 = __esm({
       resource: "people",
       action: "import",
       summary: "Create or match people from a CSV or JSONL file, optionally onto accounts",
+      brief: "a file of people",
       description: "Sends the rows to people.batch, 200 per call. Columns map by name (case, spaces and dashes ignored): email, fullName (or name), firstName, lastName, linkedinUrl (or linkedin, profileUrl), title, accountDomain (or domain, website, companyDomain), accountId, role and priority. A person needs a name: fullName, or firstName and lastName. Other columns are ignored with a warning. People already in the workspace are matched by email, then LinkedIn URL, so running the same file again creates nothing. It never creates accounts: a row whose accountDomain matches no account fails with account_not_found. Without --yes it only prints the plan.",
       flags: {
         file: { type: "string", required: true, description: "The CSV or JSONL file, or - for stdin" },
@@ -10210,7 +10262,7 @@ var init_import3 = __esm({
         out: { type: "string", description: "Keep the run's files in this directory instead of ~/.kenso/runs" }
       },
       examples: [
-        "kenso people import --file people.csv",
+        "kenso people import --file people.csv --dry-run",
         "kenso people import --file people.csv --find-emails --yes",
         "kenso people import --file people.jsonl --dry-run"
       ],
@@ -10291,7 +10343,8 @@ var init_list = __esm({
     command16 = {
       resource: "runs",
       action: "list",
-      summary: "List batch runs, newest first",
+      summary: "List batch runs, newest first (finds an interrupted run)",
+      brief: "finds an interrupted run",
       description: "Lists the runs under the runs directory (KENSO_RUNS_DIR, else ~/.kenso/runs). Needs no API key.",
       flags: {
         limit: { type: "string", default: "20", description: "How many runs to list, 1-1000 (default 20)" }
@@ -10337,7 +10390,7 @@ var init_show = __esm({
     command17 = {
       resource: "runs",
       action: "show",
-      summary: "Show one batch run: its run.json, its last summary and its files",
+      summary: "Show one batch run and its files",
       flags: {},
       positionals: [{ name: "runId", required: true, description: "The run id (see kenso runs list)" }],
       examples: ["kenso runs show r_ab3dxk2q"],
@@ -10430,7 +10483,8 @@ var init_resume = __esm({
     command18 = {
       resource: "runs",
       action: "resume",
-      summary: "Continue a batch run: rerun its command with --yes",
+      summary: "Continue an interrupted batch run (its command with --yes, no dry run)",
+      brief: "with --yes, no dry run",
       description: "Rebuilds the run's command from run.json and runs it with --yes from the directory it started in. The engine finds the run by its identity and skips the chunks already done. Refused when the input file is gone or changed.",
       flags: {},
       positionals: [{ name: "runId", required: true, description: "The run id (see kenso runs list)" }],
@@ -10558,7 +10612,8 @@ var init_install = __esm({
     command19 = {
       resource: "skill",
       action: "install",
-      summary: "Install the kenso-cli Agent Skill for Claude Code, Codex or Cursor",
+      summary: "Install the kenso-cli skill for Claude Code, Codex or Cursor",
+      brief: "",
       description: "Writes the Agent Skill bundled with this CLI to SKILL.md in each agent's skills folder: ~/.claude/skills/kenso-cli (Claude Code), ~/.agents/skills/kenso-cli (Codex) and ~/.cursor/skills/kenso-cli (Cursor). The default client is the coding agent running the command, else all three. --dir writes into that folder instead. A different SKILL.md already there is replaced only with --force (exit 7 without it). --dry-run prints the plan and writes nothing.",
       flags: {
         client: { type: "string", description: "claude-code, codex, cursor or all (default: the detected agent, else all)" },
@@ -11156,9 +11211,10 @@ var init_preview = __esm({
       resource: "studio",
       action: "preview",
       summary: "Render a saved version for up to 3 accounts; for local edits, studio push them to the draft first",
+      brief: "push local edits 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" },
+        dir: { type: "string", description: "A template folder to compare with the version being rendered; it renders no local edits (studio push them first)" },
         "account-ids": { type: "string", description: "Up to 3 account ids, separated by commas" },
         mode: { type: "string", description: "render (default) or interact" },
         sample: { type: "string", description: "A bundle sample to render, such as samples/acme.json" },
@@ -11421,6 +11477,7 @@ var init_fill = __esm({
       resource: "studio",
       action: "fill",
       summary: "Fill a template on many accounts or campaign leads (estimate first)",
+      brief: "estimate first",
       description: "Reads ids one per line, or a CSV/JSONL with an id column (--column, else id, else contactId), from --accounts, or from --contacts with --campaign for a campaign's leads. It always asks for the cost first (asset-runs.estimate) and prints it; --yes then creates one fill run per 500 ids, one after another, and --wait follows each run (every 5 s) until it completes, fails or is cancelled. The summary lists the run ids and their states. A fill charges for every page it builds, so the same ids are not filled twice: an unfinished fill continues, and a finished one is refused (exit 7) with how to retry only the failed ids.",
       flags: {
         accounts: { type: "string", description: "Account ids: a file, or - for stdin" },
@@ -11432,7 +11489,7 @@ var init_fill = __esm({
       },
       positionals: [TEMPLATE_ID],
       examples: [
-        "kenso studio fill 12 --accounts accounts.txt",
+        "kenso studio fill 12 --accounts accounts.txt --dry-run",
         "kenso studio fill 12 --accounts accounts.csv --column accountId --yes --wait",
         "kenso studio fill 12 --campaign 345 --contacts leads.csv --yes"
       ],
@@ -11563,7 +11620,7 @@ var init_use = __esm({
     command26 = {
       resource: "workspace",
       action: "use",
-      summary: "Make a workspace the default for the profile",
+      summary: "Set the profile's default workspace",
       description: "Checks the workspace with GET /v1/workspaces/{workspaceId}, then saves it to the profile (--profile, KENSO_PROFILE or the active one). --workspace and KENSO_WORKSPACE_ID still win for a single command.",
       flags: {},
       positionals: [{ name: "workspaceId", required: true, description: "The workspace id (see kenso workspace list)" }],
@@ -11721,6 +11778,24 @@ function wrap(text2, indent) {
   if (line) out.push(indent + line);
   return out.join("\n");
 }
+function wrapCell(line, at) {
+  const indent = " ".repeat(at);
+  const out = [];
+  let current = line.slice(0, at).trimEnd();
+  let first = true;
+  for (const word of line.slice(at).split(" ")) {
+    const start = first ? `${line.slice(0, at)}` : `${indent}`;
+    if (!first && current.length + 1 + word.length > 110) {
+      out.push(current);
+      current = `${indent}${word}`;
+    } else {
+      current = first ? `${start}${word}` : `${current} ${word}`;
+    }
+    first = false;
+  }
+  out.push(current);
+  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");
@@ -11752,35 +11827,59 @@ async function loadArea(resource) {
 }
 async function renderTopHelp(opts) {
   const lines = [
-    `kenso ${VERSION} - the Kenso CLI: bulk lead, CRM and Studio work for people and coding agents.`,
+    `kenso ${VERSION}, the Kenso CLI. Usage: kenso <resource> <action> [flags]; add --help to any of them.`,
     "",
-    "Usage:",
-    "  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.",
+    "Rules: every write runs first with --dry-run. Then a batch command (import, update, remove, tag, --each) applies",
+    "with the plan's next (--yes), any other write by running again without --dry-run. A file is one command as it is",
+    "(--file, --ids, --each), never one per row; no python, awk or shell tests. Ids are flags (--campaign-id 812).",
+    "Any output's next is the command to run; errors are JSON on stderr.",
     "",
     "Commands:"
   ];
   const getFeatures = lazyFeatures(opts);
   const hiddenSpecs = { count: 0, gates: /* @__PURE__ */ new Set(), names: [] };
   const rows = [];
+  const also = [];
   for (const resource of Object.keys(handWritten).sort()) {
-    for (const spec of await visibleSpecs(await loadArea(resource), opts, getFeatures, hiddenSpecs)) {
+    const specs = await visibleSpecs(await loadArea(resource), opts, getFeatures, hiddenSpecs);
+    const withPositionals = (spec, name) => {
       const positionals = (spec.positionals ?? []).map((p) => p.required ? `<${p.name}>` : `[${p.name}]`).join(" ");
-      const label = `${commandName(spec).slice("kenso ".length)}${positionals ? ` ${positionals}` : ""}`;
-      rows.push([label, `${spec.summary}${spec.beta ? " (beta)" : ""}`]);
+      return `${name}${positionals ? ` ${positionals}` : ""}`;
+    };
+    if (opts.allCommands) {
+      for (const spec of specs) {
+        rows.push([withPositionals(spec, commandName(spec).slice("kenso ".length)), `${spec.summary}${spec.beta ? " (beta)" : ""}`]);
+      }
+      continue;
     }
+    const groups = /* @__PURE__ */ new Map();
+    for (const spec of specs) {
+      if (!spec.action) {
+        if (spec.brief !== void 0) also.push(`${withPositionals(spec, spec.resource)}${spec.brief ? ` (${spec.brief})` : ""}`);
+        else rows.push([withPositionals(spec, spec.resource), spec.summary]);
+        continue;
+      }
+      const hint = `${spec.brief ? ` (${spec.brief})` : ""}${spec.beta ? " (beta)" : ""}`;
+      const names = groups.get(hint) ?? [];
+      names.push(withPositionals(spec, spec.action));
+      groups.set(hint, names);
+    }
+    const actions15 = [...groups.entries()].map(([hint, names]) => `${names.join(", ")}${hint}`);
+    if (actions15.length > 0) rows.push([resource, actions15.join(", ")]);
   }
-  lines.push(columns(rows));
+  const at = 4 + Math.min(22, Math.max(0, ...rows.map(([left]) => left.length)));
+  lines.push(
+    columns(rows, "  ", 22).split("\n").map((line) => line.length > 110 && line.slice(at - 2, at) === "  " && line[at] !== " " ? wrapCell(line, at) : line).join("\n")
+  );
+  if (also.length > 0) lines.push(wrap(`Also: ${also.join(", ")}.`, "  "));
   if (hiddenSpecs.names.length > 0) {
-    lines.push(`  Beta, hidden for this workspace (they still run; the server decides): ${hiddenSpecs.names.sort().join(", ")}.`);
+    const byArea = /* @__PURE__ */ new Map();
+    for (const name of hiddenSpecs.names.sort()) {
+      const [area = "", action = ""] = name.split(" ");
+      byArea.set(area, [...byArea.get(area) ?? [], action]);
+    }
+    const named = [...byArea.entries()].map(([area, actions15]) => `${area} ${actions15.join("|")}`);
+    lines.push(wrap(`Beta, hidden here but they run (the server decides): ${named.join(", ")}.`, "  "));
   }
   const generated = await listGenerated({ features: opts.allCommands ? [] : getFeatures, env: opts.env });
   const visible = generated.filter((g) => opts.allCommands || !g.beta);
@@ -11798,18 +11897,17 @@ async function renderTopHelp(opts) {
     } else {
       const names = new Set(sorted.map(([resource]) => resource));
       const common = COMMON_RESOURCES.filter((r) => names.has(r)).join(", ");
+      const hidden = generated.length - visible.length + hiddenSpecs.count;
       lines.push(
         "",
-        `API resources (${names.size}), one per /v1 route group and named like it (/v1/contact-exports: kenso contact-exports).`,
+        `API resources (${names.size}), named like their /v1 route (kenso contact-exports); kenso <resource> --help lists actions.`,
         wrap(`Common: ${common}.`, "  "),
-        "  kenso <resource> --help lists its actions; kenso --help --all-commands lists every resource."
+        `  Every resource: kenso --help --all-commands${hidden > 0 ? ` (also shows ${hidden} hidden beta commands)` : ""}.`
       );
     }
   }
-  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.`);
   if (opts.allCommands) lines.push("", "Global flags:", columns(GLOBAL_FLAG_HELP), "", EXIT_CODES);
-  else lines.push("", GLOBAL_FLAGS_LINE, EXIT_CODES);
+  else lines.push("", GLOBAL_FLAGS_LINE);
   return withAgentBlock(lines.join("\n"), opts.agent);
 }
 async function renderResourceHelp(resource, opts) {
@@ -11851,6 +11949,7 @@ async function renderResourceHelp(resource, opts) {
     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.`);
+  if (all.length === 0) lines.push("A file of rows is one command, never one per row: kenso " + resource + " <action> --each <file> --dry-run.");
   return withAgentBlock(lines.join("\n"), opts.agent);
 }
 function renderCommandHelp(spec, opts) {
@@ -11860,13 +11959,13 @@ function renderCommandHelp(spec, opts) {
     lines.push("", "Arguments:", columns(spec.positionals.map((p) => [`<${p.name}>`, `${p.description}${p.required ? "" : " (optional)"}`])));
   }
   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 flagRows = Object.entries(spec.flags).filter(([name, flag]) => !flag.helpHidden && !(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);
     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_LINE);
+  lines.push("", ...spec.helpFooter ?? [], GLOBAL_FLAGS_LINE);
   if (spec.examples.length > 0) lines.push("", "Examples:", ...spec.examples.map((e) => `  ${e}`));
   return withAgentBlock(lines.join("\n"), opts.agent);
 }
@@ -11894,7 +11993,7 @@ var init_help = __esm({
       ["-h, --help", "Show help"],
       ["--version", "Print the CLI version (only on its own: kenso --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).";
+    GLOBAL_FLAGS_LINE = "Global flags: --dry-run, -y/--yes, --workspace <id>, -o json|ndjson|table|ids, --fields, --query, -v.";
     COMMON_RESOURCES = [
       "accounts",
       "analytics",