kenso 0.0.0-stage → 0.1.8

package/docs/README.md

@@ -0,0 +1,74 @@
+# Kenso CLI
+
+The Kenso CLI (`kenso`) is the command line for Kenso. It does bulk work in your Kenso workspace from files: add thousands of leads to a campaign, update or clean them up, import accounts and people, and build Studio templates. It is made for coding agents (Claude Code, Codex, Cursor) and the people who drive them: JSON on stdout, fixed exit codes, a dry run before every bulk write, and runs you can resume.
+
+Every API operation a workspace member can call is also a command, such as `kenso campaigns list` or `kenso tags create`. So the CLI reaches what the Kenso MCP reaches, straight against `https://api.ken.so`.
+
+## Install
+
+You need Node 22 or newer.
+
+```bash
+npm i -g kenso
+kenso --version
+```
+
+To run it once without installing, use `npx kenso --version`.
+
+## 60-second quickstart
+
+1. Create an API key in app.ken.so at Settings > Integrations > API keys.
+2. Save the key, pick a workspace, then plan and apply a CSV import:
+
+```bash
+echo $KEY | kenso auth login --with-key
+kenso workspace list --q acme
+kenso workspace use 1234
+kenso campaigns list --limit 5
+kenso contacts import --campaign 812 --file leads.csv --dry-run
+kenso contacts import --campaign 812 --file leads.csv --yes
+```
+
+`workspace list` and `workspace use` are only needed when your key reaches more than one workspace.
+
+The dry run reads the file, maps the columns, checks every row, asks Kenso for a credit estimate, and writes nothing. It prints the plan, with the exact apply command in `next`:
+
+```json
+{"run":"r_tdi5cdnx","dryRun":true,"command":"contacts import","rows":4,"valid":2,"invalid":2,"chunks":1,"chunkSize":1000,"campaignId":812,"mapping":{"Email":"email","First Name":"firstName","Last Name":"lastName","Company":"companyName","Pain Point":"customVariables.pain_point"},"customVariableKeys":["pain_point"],"estimate":{"kind":"leads","totalMillicredits":2000,"availableMillicredits":500000,"sufficient":true},"credits":{"needed":2,"available":500,"sufficient":true},"next":"kenso contacts import --campaign 812 --file leads.csv --yes","plan":"/home/you/.kenso/runs/r_tdi5cdnx/plan.json","invalidRows":"/home/you/.kenso/runs/r_tdi5cdnx/invalid.csv"}
+```
+
+The apply sends the rows and prints one summary. Every input row has one line in `results.csv`:
+
+```json
+{"run":"r_tdi5cdnx","rows":4,"ok":0,"created":1,"updated":0,"skipped":{"duplicate":1},"failed":0,"notFound":0,"invalid":2,"changed":1,"results":"/home/you/.kenso/runs/r_tdi5cdnx/results.csv","resultsNdjson":"/home/you/.kenso/runs/r_tdi5cdnx/results.ndjson","invalidRows":"/home/you/.kenso/runs/r_tdi5cdnx/invalid.csv","resumed":false,"durationMs":1840,"campaignId":812,"notSendable":0}
+```
+
+This run exits 5 because two rows were invalid: open `invalid.csv` to see why, fix those rows, and import them again. Running the same command again is safe: an email that is already in the campaign comes back `updated` or `skipped`, never as a second lead.
+
+## CLI or MCP
+
+- **Use the CLI for volume:** anything that starts from a file, anything over about 50 records, anything you may need to rerun or resume. Records never pass through the model's context: the agent passes a file path and reads a short summary.
+- **Use the MCP for conversation and single records:** look up a campaign, draft a reply, read a report. The MCP is at `https://mcp.ken.so/mcp`, signs in with OAuth and needs no install ([connection guide](https://ken.so/mcp)).
+- **Both use the same API and the same permissions.** `kenso mcp call` reaches MCP-only tools, such as skills, from the shell.
+
+## Docs
+
+Every page is in the package and prints offline with `kenso docs <topic>`.
+
+| Page | Topic | What it covers |
+|---|---|---|
+| [Authentication](auth.md) | `auth` | API keys, browser login, profiles, workspaces, `doctor` |
+| [Leads](leads.md) | `leads` | Import, update, remove, pause, tag and export leads, with recipes |
+| [Batch runs](batch.md) | `batch` | Dry run and apply, run folders, results files, resume, rate limits, `--each` |
+| [Output and errors](output-and-errors.md) | `output-and-errors` | The output contract, error JSON, error codes, exit codes |
+| [CRM (beta)](crm.md) | `crm` | Accounts, people, opportunities and CRM sync |
+| [Studio (beta)](studio.md) | `studio` | Pull, push, validate, preview and fill templates |
+| [Coding agents](agents.md) | `agents` | Claude Code, Codex, Cursor, the Agent Skill, environment variables, sandboxes |
+| Command reference | `reference` | Every command with its flags, generated from the CLI at build time: `kenso docs reference`, or `docs/reference.md` in the installed package |
+
+```bash
+kenso docs
+kenso docs leads
+```
+
+For machine-readable help, run `kenso describe`: it prints every command, its flags and its body schema as JSON.

package/docs/agents.md

@@ -0,0 +1,124 @@
+# Coding agents
+
+The 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.
+
+## Set up an agent in three steps
+
+1. Install the CLI where the agent runs: `npm i -g kenso` (Node 22 or newer).
+2. 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:
+
+```bash
+echo $KEY | kenso auth login --with-key
+kenso workspace use 1234
+```
+
+3. Install the Agent Skill, so the agent knows the rules before its first command:
+
+```bash
+kenso skill install
+```
+
+## The Agent Skill
+
+`kenso skill install` writes the skill `kenso-cli` (one `SKILL.md`) where each agent looks for skills:
+
+| Agent | `--client` | Folder |
+|---|---|---|
+| Claude Code | `claude-code` | `~/.claude/skills/kenso-cli/` |
+| Codex | `codex` | `~/.agents/skills/kenso-cli/` |
+| Cursor | `cursor` | `~/.cursor/skills/kenso-cli/` |
+
+Without `--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:
+
+```json
+{"installed":[{"client":"claude-code","path":"/home/you/.claude/skills/kenso-cli/SKILL.md","status":"created"}]}
+```
+
+```bash
+kenso skill install --client claude-code
+kenso skill install --client all
+kenso skill install --dir .claude/skills/kenso-cli
+kenso skill install --force
+```
+
+- `--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.
+- 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"`).
+- `--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.
+- 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.
+
+The 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.
+
+## Rules the skill teaches
+
+- **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.
+- **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`).
+- **Pass files, not rows.** Never paste a CSV into the conversation. Write the file, pass its path with `--file`, and read the summary.
+- **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`.
+- **Follow `next`.** Every error with a known fix carries the exact command to run.
+- **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.
+- **Look things up, do not guess.** `kenso describe <resource> <action>` prints any command's flags and body schema as JSON.
+
+## The token-saving pattern
+
+Adding 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:
+
+```bash
+kenso contacts import --campaign 812 --file leads.csv --dry-run
+kenso contacts import --campaign 812 --file leads.csv --yes
+```
+
+Then, only if the summary shows failures:
+
+```bash
+grep -E '^[0-9]+,(failed|not_found|invalid),' ~/.kenso/runs/r_tdi5cdnx/results.csv | head -50
+```
+
+## Environment variables
+
+| Variable | What it does |
+|---|---|
+| `KENSO_API_KEY` | The API key. Wins over any saved profile |
+| `KENSO_WORKSPACE_ID` | The workspace for every command. `--workspace` wins over it |
+| `KENSO_PROFILE` | The saved profile to use. `--profile` wins over it |
+| `KENSO_API_URL` | The API, default `https://api.ken.so` |
+| `KENSO_CONFIG_DIR` | Where the config file and cache live, default `~/.kenso` |
+| `KENSO_RUNS_DIR` | Where run folders live, default `<config dir>/runs` |
+| `KENSO_MCP_URL` | The MCP for `kenso mcp`, default `https://mcp.ken.so/mcp` |
+
+## Cloud sandboxes
+
+Cloud agents (Claude Code on the web, Codex cloud, Cursor background agents and similar) often run with a network allowlist. Allow:
+
+- `api.ken.so`: every command
+- `mcp.ken.so`: only `kenso mcp tools` and `kenso mcp call`
+- `registry.npmjs.org`: to install the CLI with npm
+
+Store 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.
+
+```bash
+kenso doctor
+```
+
+Point 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.
+
+## How Kenso knows an agent ran a command
+
+The 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:
+
+- 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;
+- help ends with a short "For agents" block;
+- browser login never opens a browser itself: it prints the link for you to open.
+
+`kenso doctor` shows the agent it detected.
+
+## MCP-only tools
+
+A 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:
+
+```bash
+kenso mcp tools
+kenso mcp call skills --operation list
+kenso mcp call contacts --operation list --args '{"limit":5}'
+```
+
+`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`.

package/docs/auth.md

@@ -0,0 +1,108 @@
+# Authentication
+
+The CLI calls the Kenso API with a Kenso API key (`ken_` plus 43 characters). It sends the key as `Authorization: Bearer <key>` and never prints it, logs it or puts it in an error.
+
+## Log in with an API key
+
+1. In app.ken.so, go to Settings > Integrations > API keys and create a key.
+2. Pipe it to `kenso auth login --with-key`. The key is read from stdin, never from a flag, so it stays out of your shell history and process list.
+
+```bash
+echo $KEY | kenso auth login --with-key
+kenso auth login --with-key --profile client-a --workspace 1234 < key.txt
+```
+
+The CLI checks the key with `GET /v1/me`, then saves it to `~/.kenso/config.json` (file mode 0600, folder mode 0700). It prints:
+
+```json
+{"profile":"default","email":"you@acme.io","workspaceId":"1234","workspaceCount":1}
+```
+
+When the key reaches several workspaces and you did not pass `--workspace`, no workspace is saved and the output carries `"next":"kenso workspace list --q <name>"`. A key in the wrong format exits 2 (`invalid_key_format`). A key Kenso rejects exits 3.
+
+## Browser login
+
+```bash
+kenso auth login
+kenso auth login --no-browser --device-name "build box"
+```
+
+Browser login is rolling out. Until it is on for your account, `kenso auth login` answers `browser_login_unavailable` (exit 3) with `"next":"kenso auth login --with-key"`: use an API key as above.
+
+When your workspace has it, the CLI prints a link and a code on stderr. You open the link, check the code and approve. The CLI then saves a new API key to the profile, the same kind you create in the app: it shows in your API key list, where you can revoke it. The CLI opens the browser itself only when no coding agent is detected and the machine has a display. An agent prints the link and asks you to open it. The login expires after 10 minutes (`login_expired`, exit 3), and a denied login exits 3 with `access_denied`.
+
+## CI, scripts and agents: use the environment
+
+You do not need to log in on a machine that has the key in its environment:
+
+```bash
+export KENSO_API_KEY=ken_...
+export KENSO_WORKSPACE_ID=1234
+kenso auth status
+```
+
+`KENSO_API_KEY` wins over any saved profile. Store it as a secret in your CI or agent platform, never in a file in the repo.
+
+## Workspaces
+
+A key reaches every workspace its user belongs to. Each command runs in one workspace, picked in this order:
+
+1. `--workspace <id>` on the command
+2. `KENSO_WORKSPACE_ID`
+3. the workspace saved in the profile (`kenso workspace use`)
+
+```bash
+kenso workspace list --q acme
+kenso workspace use 1234
+kenso campaigns list --workspace 5678
+```
+
+`workspace list` prints one page and says on stderr when there are more: add `--all` for every page. A command that needs a workspace when none is picked fails with `workspace_required` (exit 2) and `"next":"kenso workspace list --q <name>"`.
+
+## Profiles
+
+A profile holds a key, a workspace, an optional API URL and the email. Use one per client or per key:
+
+```bash
+kenso auth login --with-key --profile client-a < client-a-key.txt
+kenso campaigns list --profile client-a
+KENSO_PROFILE=client-a kenso auth status
+```
+
+The profile is `--profile`, else `KENSO_PROFILE`, else the active one (the last one you logged in to).
+
+## Check the setup
+
+```bash
+kenso auth status
+kenso doctor
+```
+
+`auth status` prints who the key belongs to and when it expires, and warns on stderr when that is within 14 days:
+
+```json
+{"email":"you@acme.io","workspaceCount":3,"activeWorkspace":{"id":"1234","name":"Acme"},"keyExpiresAt":"2027-01-31T00:00:00Z","keySource":"profile","profile":"default"}
+```
+
+`doctor` prints the version, Node, the config folder, the profile, the key source, the API URL, the workspace and the detected agent, then four checks: `node_version`, `config_permissions`, `api_reachable` and `key_valid`. It exits 0 when every check passes, 3 when the key is missing or rejected, else 1.
+
+## Log out
+
+```bash
+kenso auth logout
+kenso auth logout --profile client-a
+```
+
+This removes the profile and its key from this machine. The key itself stays valid until you revoke it at Settings > Integrations > API keys.
+
+## Where things live
+
+| What | Default | Override |
+|---|---|---|
+| Config file with profiles and keys | `~/.kenso/config.json` | `KENSO_CONFIG_DIR` |
+| Run folders | `~/.kenso/runs/` | `KENSO_RUNS_DIR` |
+| Cached workspace features (1 hour) | `~/.kenso/cache/` | follows `KENSO_CONFIG_DIR` |
+| API | `https://api.ken.so` | `KENSO_API_URL` |
+| MCP (for `kenso mcp`) | `https://mcp.ken.so/mcp` | `KENSO_MCP_URL` |
+
+`--verbose` prints each request line to stderr with the key redacted.

package/docs/batch.md

@@ -0,0 +1,152 @@
+# Batch runs
+
+A batch command takes a file, sends its rows to Kenso in chunks, and prints one JSON summary. Every input row gets one line in a results file, every run can be resumed, and nothing is written until you pass `--yes`.
+
+The batch commands:
+
+- `contacts import`, `update`, `remove`, `restore`, `pause`, `resume`, `tag`, `untag` ([Leads](leads.md))
+- `people import` and `accounts import` ([CRM](crm.md), beta)
+- `studio fill` ([Studio](studio.md), beta)
+- any generated command run with `--each <file>`, once per row (see below)
+
+## Plan, then apply
+
+Without `--yes` a batch command plans and changes nothing. `--dry-run` asks for the plan explicitly. `--yes` applies. Passing both is a usage error. Two exceptions to the plan below: `studio fill` without `--yes` prints its credit estimate and `next`, with no run or `plan.json` ([Studio](studio.md)), and a non-GET `--each` without `--yes` or `--dry-run` is a usage error (exit 2) rather than a plan.
+
+```bash
+kenso contacts import --campaign 812 --file leads.csv --dry-run
+kenso contacts import --campaign 812 --file leads.csv --yes
+```
+
+The dry run parses and checks every row, may call read-only endpoints (a campaign read, a credit estimate, a contacts search for `--where`), writes `plan.json`, and prints the plan:
+
+```json
+{"run":"r_ubqu7wtx","dryRun":true,"command":"contacts remove","rows":3,"valid":3,"invalid":0,"chunks":1,"chunkSize":1000,"source":"ids","count":3,"firstIds":[11,12,13],"next":"kenso contacts remove --ids ids.txt --yes","plan":"/home/you/.kenso/runs/r_ubqu7wtx/plan.json"}
+```
+
+Every plan has `run`, `dryRun`, `command`, `rows`, `valid`, `invalid`, `chunks`, `chunkSize`, `next` (the exact command that applies it) and `plan` (the file), plus fields of its own command. It adds `invalidRows` when rows were refused, `chunksDone` when it continues an unfinished run, and `alreadyDone: true` when the apply would change nothing.
+
+## The summary
+
+An applied run prints one JSON object:
+
+```json
+{"run":"r_ubqu7wtx","rows":3,"ok":2,"created":0,"updated":0,"skipped":{},"failed":0,"notFound":1,"invalid":0,"changed":2,"results":"/home/you/.kenso/runs/r_ubqu7wtx/results.csv","resultsNdjson":"/home/you/.kenso/runs/r_ubqu7wtx/results.ndjson","resumed":false,"durationMs":412,"undo":"kenso contacts restore --run r_ubqu7wtx"}
+```
+
+| Field | Meaning |
+|---|---|
+| `run` | The run id: `r_` and 8 characters |
+| `rows` | Input rows |
+| `ok`, `created`, `updated` | Rows that succeeded, by kind |
+| `skipped` | Rows Kenso left alone on purpose, counted by reason, for example `{"duplicate":12}` |
+| `failed`, `notFound`, `invalid` | Rows that did not go through: refused or errored, id not found, refused locally |
+| `changed` | Rows this invocation changed. 0 when a rerun had nothing left to do |
+| `results`, `resultsNdjson` | Absolute paths of the results files |
+| `invalidRows` | Path of `invalid.csv`, when rows were refused locally |
+| `resumed` | True when this invocation continued an earlier run |
+| `durationMs` | Wall time of this invocation |
+| `pending` | Rows without a result yet, when the run did not finish |
+| `stopped` | `{code, message, hint}` when a stop condition ended the run (for example `limit_reached`) |
+| `interrupted` | True after Ctrl-C |
+| `next` | `kenso runs resume <runId>` when the run can continue |
+
+Commands add their own fields: `contacts import` adds `campaignId` and `notSendable`, `contacts remove` adds `undo`, `people import` adds `matched`, `addedToAccounts` and `emailFindsQueued`, `accounts import` adds `researchQueued` and `researchWaitingCredits`, `studio fill` adds `templateId`, `runs` and the estimate.
+
+Exit codes: 0 when every row succeeded or was skipped, 5 when some rows are `failed`, `not_found` or `invalid`, 6 when a limit stopped the run, 130 after Ctrl-C. The full table is in [Output and errors](output-and-errors.md).
+
+## The run folder
+
+Each run keeps its files in `~/.kenso/runs/<runId>/` (`KENSO_RUNS_DIR` moves the root), or in `--out <dir>` when you pass it. A run in `--out` is also linked under the runs folder, so `kenso runs` finds it. The folder is mode 0700 and its files 0600.
+
+| File | What it holds |
+|---|---|
+| `run.json` | The command, its arguments, the input path and SHA-256, the workspace, the chunk plan and the status (`planned`, `running`, `done`, `failed`, `interrupted`) |
+| `state.json` | The chunks done so far, rewritten after every chunk |
+| `results.csv` | One line per input row: `row,status,id,reason,error`, then extra columns such as `email` or `sendable` |
+| `results.ndjson` | The same rows as JSON lines |
+| `invalid.csv` | Rows refused before sending, with the reason |
+| `plan.json` | The last dry run's plan |
+| `summary.json` | The last summary printed |
+
+`row` is the 1-based number of the data row in the input (the CSV header is not counted). `status` is one of `created`, `updated`, `ok`, `skipped`, `failed`, `not_found` or `invalid`.
+
+```bash
+kenso runs list
+kenso runs list --limit 5 -o json
+kenso runs show r_ubqu7wtx
+```
+
+## Rerun and resume
+
+A run is identified by its command, its arguments, the SHA-256 of its input file, the workspace and the chunk size. `--yes`, `--dry-run`, `--wait`, `--concurrency` and the output flags are not part of it. Running the same command again on the same file:
+
+- **continues an unfinished run** (interrupted, stopped or crashed): finished chunks are skipped and the summary says `"resumed":true`.
+- **answers from a finished run where every row succeeded:** it prints that run's summary with `"changed":0` and `"alreadyDone":true`, sends no writes and exits 0 (a command may still read first: `contacts import` reads the campaign, and `contacts update --match email` looks up the campaign's contacts).
+- **starts a new run** when the last one finished with failed or invalid rows, or when the file changed. Lead, people and account writes match existing records (an email in a campaign, a person by email or LinkedIn URL, an account by domain), so sending a row twice never creates a duplicate.
+
+`kenso runs resume <runId>` does the same from the run id: it rebuilds the command from `run.json` and runs it with `--yes` from the folder it started in. It refuses when the input was stdin, or the file is gone or changed. Two processes cannot work on one run: the second gets `run_in_progress` (exit 7).
+
+```bash
+kenso runs resume r_ubqu7wtx
+```
+
+`studio fill` is the exception: a fill charges for every page it builds, so it never fills the same ids twice. See [Studio](studio.md).
+
+## Ctrl-C
+
+The first Ctrl-C cancels the requests in flight and starts no new chunks. The CLI writes the state and prints the summary with `"interrupted":true` and `"next":"kenso runs resume <runId>"`, then exits 130. A chunk that did not finish is sent again when you resume, which is safe because the writes match existing records. A second Ctrl-C quits at once.
+
+## Chunks, concurrency and rate limits
+
+| Command | Rows per call | At once |
+|---|---|---|
+| `contacts import` | 1,000 | 1 per campaign |
+| `contacts update`, `remove`, `restore`, `pause`, `resume` | 1,000 | 4 (`--concurrency`) |
+| `contacts tag`, `untag` | 1 per call, 25 per chunk | 4 chunks (`--concurrency`) |
+| `people import` | 200 | 4 (`--concurrency`) |
+| `accounts import` | 100 | 4 (`--concurrency`) |
+| `studio fill` | 500 ids per fill run | 1 |
+| `--each` | 1 | 4 (`--concurrency`) |
+
+`--concurrency` takes 1 to 16. When the API's `RateLimit-Remaining` header drops below 10, the CLI sends one chunk at a time until it is back above 30.
+
+Retries:
+
+- **429:** the CLI waits for `Retry-After` (at least 1 second, at most 60 seconds per wait) and tries again, with up to 15 minutes of waiting per command. After that it exits 6 (`rate_limited`).
+- **502, 503, 504 and network errors:** up to 3 retries with backoff, for GET, PUT, PATCH and DELETE, and for the POST routes the CLI knows are safe to repeat.
+- **`contacts import`:** no quick retry. After a 5xx or a dropped connection it waits 130 seconds, longer than the gateway's request timeout, and resends the chunk once.
+- **`contacts remove`:** after a 5xx or a dropped connection it waits 2 seconds and resends once. Ids the first call already removed are reported `ok` (reason `already_removed`), so the undo still restores them.
+- **Other 4xx answers:** never retried. The row or chunk is marked `failed` with the API's code.
+
+Kenso answers a bulk call with 200 even when some items fail, so the CLI reads each item's result and never trusts the HTTP status alone.
+
+## Progress
+
+Progress goes to stderr, at most one line every 2 seconds (`chunk 7/20, 7000 rows, 6 failed`), and only when stderr is a terminal or you pass `--progress`. An agent gets only the summary.
+
+## Run any API operation once per row: --each
+
+Every generated command takes `--each <file>`, a CSV or JSONL file or `-` for stdin. The command runs once per row through the same engine: one results line per row, resume, `--concurrency`. Row keys fill the route, query and body by API name (`accountId`) or flag name (`account-id`). A blank cell is left out and the literal `null` sends null. A GET runs right away; any other method needs `--yes` or `--dry-run`.
+
+```bash
+kenso accounts update --each stages.csv --dry-run
+kenso accounts update --each stages.csv --yes --concurrency 8
+```
+
+With `stages.csv`:
+
+```csv
+accountId,stage,overwritePinned
+501,engaged,true
+502,customer,true
+```
+
+Each row is `ok` on a 2xx answer (with the created or returned id), `not_found` on 404, `failed` otherwise, or `invalid` when a required value is missing.
+
+## The token-saving pattern for agents
+
+1. Pass a file path, never the rows: `--file leads.csv`.
+2. Run `--dry-run`, read the plan, then run its `next`.
+3. Read the summary. If `failed`, `notFound` and `invalid` are 0, you are done.
+4. Otherwise read only the problem rows, for example `grep -E '^[0-9]+,(failed|not_found|invalid),' results.csv | head -50`, or `invalid.csv`.

package/docs/crm.md

@@ -0,0 +1,111 @@
+# CRM (beta)
+
+The 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.
+
+| Command | What it does |
+|---|---|
+| `accounts import` | Create accounts from a CSV or JSONL file. Research is charged per created account |
+| `people import` | Create or match people from a file, optionally onto accounts |
+| `accounts update --each`, `people update --each`, `opportunities update --each` | Edit many records from a file, one call per row |
+| `crm-connections`, `crm-imports`, `crm-sync-issues` | Read and run CRM sync. Connecting a CRM stays in the app |
+
+Import accounts first, then people: `people import` never creates an account.
+
+## Import accounts
+
+```bash
+kenso accounts import --file accounts.csv
+kenso accounts import --file accounts.csv --yes
+```
+
+```csv
+name,domain,industry,employeeCount
+Acme,acme.io,Software,120
+Globex,globex.com,Manufacturing,"1,200"
+```
+
+- **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`.
+- **A domain is required.** A file with no domain column is a usage error, and a row without a domain is `invalid` (`domain_required`).
+- **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`.
+- **Rows go 100 per call** to `POST /v1/accounts/bulk-create`.
+
+Each row comes back:
+
+| Status | Meaning |
+|---|---|
+| `created` | A new account; `id` is the account id. Research is queued (`researchQueued` in the summary), or waits for credits (`researchWaitingCredits`) |
+| `skipped`, reason `domain_taken` | A company that is already an account; `id` is that account |
+| `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 |
+
+Rerunning the same file is safe: accounts that exist come back `domain_taken`.
+
+## Import people
+
+```bash
+kenso people import --file people.csv
+kenso people import --file people.csv --find-emails --yes
+kenso people import --file people.jsonl --dry-run
+```
+
+```csv
+fullName,email,title,accountDomain,role
+Ann Lee,ann@acme.io,VP Sales,acme.io,champion
+Bob Ray,,CTO,acme.io,
+```
+
+- **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.
+- **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`).
+- **To put a person on an account,** give `accountDomain` or `accountId`. A row with both sends only `accountId`.
+- **`--find-emails`** queues an email find (charged in credits) for each person without an email.
+- **Rows go 200 per call** to `POST /v1/people/batch`.
+
+People already in the workspace are matched by email, then LinkedIn URL, so running the same file again creates nobody twice.
+
+| Result | Row status | reason |
+|---|---|---|
+| A new person | `created` | |
+| An existing person, added to the account | `updated` | |
+| An existing person already on the account | `skipped` | `already_on_account` |
+| An existing person, no account asked | `skipped` | `matched` |
+| The person was removed from the account before | `skipped` | `previously_removed` |
+| The account does not exist | `failed` | `account_not_found`: the person was saved without an account. Import the account, then rerun to place them |
+| Kenso refused the row | `failed` | the API's reason |
+
+The summary adds `matched`, `addedToAccounts` and `emailFindsQueued`.
+
+## Edit accounts, people and opportunities
+
+Apart 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:
+
+```bash
+kenso accounts update --each accounts-edit.csv --dry-run
+kenso accounts update --each accounts-edit.csv --yes
+kenso people update --each people-edit.csv --yes
+kenso opportunities update --each deals.csv --yes
+```
+
+```csv
+accountId,stage,ownerMemberId,overwritePinned
+501,engaged,42,true
+502,customer,42,true
+```
+
+A 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:
+
+```bash
+kenso describe accounts update
+kenso accounts update --help
+```
+
+## CRM sync
+
+CRM sync has generated commands only: read connections, preview, start an import, and work through sync issues. Connect the CRM itself in the app.
+
+```bash
+kenso crm-connections list
+kenso crm-connections get --connection-id 7
+kenso crm-imports create --connection-id 7 --dry-run
+kenso crm-sync-issues list --connection-id 7 --all
+```
+
+Run `kenso crm-connections --help` (or add `--all-commands` when the actions are hidden) to see every action.