autotouch-cli 0.2.22__tar.gz → 0.2.24__tar.gz

autotouch_cli-0.2.24/PKG-INFO

@@ -0,0 +1,1124 @@
+Metadata-Version: 2.4
+Name: autotouch-cli
+Version: 0.2.24
+Summary: Autotouch Smart Table CLI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+
+# Autotouch CLI Reference (`autotouch`)
+
+This page documents the installable CLI for the Smart Table developer API.
+It is the canonical CLI doc in this repo and the package readme shipped to PyPI.
+Use it when you want less boilerplate than raw HTTP/cURL while keeping the same API behavior, auth, and scopes.
+
+## Start here
+
+Use this order when you are orienting in the CLI:
+
+1. Configure auth and confirm scopes with `autotouch auth check` and `autotouch capabilities`.
+2. Use the API endpoint -> CLI command map when translating an existing API workflow.
+3. Use `autotouch columns recipe` before creating provider-backed workflow columns.
+4. Use `autotouch jobs get` as the source of truth for async run state.
+5. Use raw HTTP for sequences/tasks workflows; those endpoints share the same developer-key model but do not yet have dedicated CLI commands.
+
+### Quick decision guide
+
+| If you want to... | Start here |
+| --- | --- |
+| create a table or inspect available tables | `autotouch tables create` / `autotouch tables list` |
+| import CSV data safely | `autotouch rows import-csv --validate-only`, then `autotouch rows import-csv --wait` |
+| create a provider-backed column | `autotouch columns recipe --type <TYPE>`, then `autotouch columns create` |
+| run exactly `N` rows | `autotouch columns run-next` |
+| stage a gradual rollout | `autotouch columns run --scope firstN --unprocessed-only` |
+| run only the current filtered segment | `autotouch columns run --scope filtered --filters-file ...` |
+| run one exact row or an explicit list of row IDs | `scope=row` for one ID, `scope=subset` for many IDs |
+| verify whether a job is really done | `autotouch jobs get --job-id <JOB_ID>` |
+| create projections from JSON output | `autotouch columns projections` |
+| work with sequences/tasks | raw HTTP plus `docs/platform/external-workflows-api.md` |
+
+### Operating model
+
+- This file is the full CLI reference and the package readme published to PyPI.
+- The installed package gives you CLI entrypoints and package metadata; do not assume there is a separate installed docs directory.
+- Research-table APIs are the primary CLI surface today; workflow APIs (sequences/tasks) are still HTTP-first.
+- For async operations, backend bulk-job state is authoritative; local terminal output is only a convenience layer.
+- For staged or cost-sensitive runs, estimate first and prefer filtered scopes plus `firstN` or `run-next`.
+
+## Install
+
+```bash
+pipx install autotouch-cli
+# or
+pip install autotouch-cli
+```
+
+## Configure auth
+
+Developer keys and scopes are identical to raw API usage (`stk_...`, same scope checks).
+
+```bash
+autotouch auth set-key --api-key stk_... --base-url https://app.autotouch.ai
+autotouch auth check
+autotouch auth show
+```
+
+Credentials are stored in `~/.config/autotouch/config.json` by default.
+Override path with `AUTOTOUCH_CONFIG_PATH`.
+
+Developer key scope reference (including workflow scopes like `sequences:*` and `tasks:*`):
+- `docs/platform/authentication.md`
+
+## Agent bootstrap (one-call signup + key)
+
+If an agent/user does not have an account + developer key yet, bootstrap both in one call:
+
+```bash
+curl -X POST "https://app.autotouch.ai/api/auth/agent-bootstrap" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "first_name": "Ada",
+    "last_name": "Lovelace",
+    "email": "ada@yourcompany.com",
+    "password": "use-a-strong-random-password",
+    "organization_name": "Your Company",
+    "key_name": "Agent bootstrap key"
+  }'
+```
+
+Then store the returned `apiKey`:
+
+```bash
+autotouch auth set-key --api-key stk_... --base-url https://app.autotouch.ai
+autotouch auth check
+```
+
+Notes:
+- New orgs created through signup/bootstrap start with `50` credits.
+- Identity linking is email-based: later human sign-in with the same normalized email maps to the same user/org.
+
+## API endpoint -> CLI command map
+
+| API endpoint | CLI command |
+| --- | --- |
+| `GET /api/capabilities` | `autotouch capabilities` |
+| `POST /api/tables` | `autotouch tables create --name "My Table"` |
+| `GET /api/tables?view_mode=org` | `autotouch tables list --view-mode org` |
+| `POST /api/tables/{table_id}/rows` | `autotouch rows add --table-id <TABLE_ID> --records-file rows.json` |
+| `POST /api/tables/{table_id}/import-optimized` | `autotouch rows import-csv --table-id <TABLE_ID> --file contacts.csv` |
+| `POST /api/tables/{table_id}/csv-validate` | `autotouch rows import-csv --table-id <TABLE_ID> --file contacts.csv --validate-only` |
+| `GET /api/tables/{table_id}/import-status/{task_id}` | `autotouch rows import-status --table-id <TABLE_ID> --task-id <TASK_ID>` |
+| `GET /api/tables/{table_id}/import-verify/{task_id}` | `autotouch rows import-verify --table-id <TABLE_ID> --task-id <TASK_ID> --expected-rows <N>` |
+| `POST /api/tables/{table_id}/import-rollback/{task_id}` | `autotouch rows import-rollback --table-id <TABLE_ID> --task-id <TASK_ID>` |
+| `GET /api/blacklist` | `autotouch blacklist list --type-filter all --limit 100` |
+| `POST /api/blacklist` | `autotouch blacklist add --type domain --value competitor.com` |
+| `DELETE /api/blacklist/{entry_id}` | `autotouch blacklist remove --entry-id <ENTRY_ID>` |
+| `POST /api/blacklist/import` | `autotouch blacklist import --file blacklist.csv` |
+| `POST /api/blacklist/check` | `autotouch blacklist check --emails-file recipients.csv --emails-column email` |
+| `POST /api/blacklist/filter` | `autotouch blacklist filter --emails-file recipients.csv --emails-column email` |
+| `PATCH /api/tables/{table_id}/cells` | `autotouch cells patch --table-id <TABLE_ID> --updates-file updates.json` |
+| `GET /api/tables/{table_id}/columns` | `autotouch columns list --table-id <TABLE_ID>` |
+| `POST /api/tables/{table_id}/columns` | `autotouch columns create --table-id <TABLE_ID> --data-file column.json` |
+| `PATCH /api/tables/{table_id}/columns/{column_id}` | `autotouch columns update --table-id <TABLE_ID> --column-id <COLUMN_ID> --data-file column-update.json` |
+| `POST /api/tables/{table_id}/columns/projections` | `autotouch columns projections --table-id <TABLE_ID> --data-file projections.json` |
+| `POST /api/tables/{table_id}/columns/{column_id}/estimate` | `autotouch columns estimate --table-id <TABLE_ID> --column-id <COLUMN_ID> --scope all` |
+| `POST /api/tables/{table_id}/columns/{column_id}/run` | `autotouch columns run --table-id <TABLE_ID> --column-id <COLUMN_ID> --scope all` |
+| `POST /api/tables/{table_id}/columns/{column_id}/stop` | `autotouch columns stop --table-id <TABLE_ID> --column-id <COLUMN_ID>` |
+| `GET /api/bulk-jobs` | `autotouch jobs list --table-id <TABLE_ID> --column-id <COLUMN_ID> --limit 10` |
+| `GET /api/bulk-jobs/{job_id}` | `autotouch jobs get --job-id <JOB_ID>` |
+| `GET /api/tables/{table_id}/webhook` | `autotouch webhooks get --table-id <TABLE_ID>` |
+| `POST /api/tables/{table_id}/webhook` | `autotouch webhooks rotate --table-id <TABLE_ID>` |
+| `POST /api/webhooks/tables/{table_id}/ingest` | `autotouch webhooks ingest --table-id <TABLE_ID> --records-file records.json --webhook-token <WEBHOOK_TOKEN>` |
+| `POST /api/auth/agent-bootstrap` | HTTP-only bootstrap (no direct CLI wrapper yet) |
+
+## Workflow API coverage (sequences/tasks)
+
+Sequences/tasks APIs are supported by the backend developer-key model but do not yet have dedicated `autotouch` CLI commands.
+
+Use raw HTTP for these endpoints today, with the same `stk_...` key:
+- `POST /api/sequences`
+- `PUT /api/sequences/{sequence_id}`
+- `PATCH /api/sequences/{sequence_id}/status`
+- `POST /api/sequences/{sequence_id}/enroll`
+- `POST /api/task-queue/create`
+- `PUT /api/task-queue/{task_id}`
+- `POST /api/task-queue/{task_id}/draft`
+- `POST /api/task-queue/{task_id}/email/schedule`
+
+Reference contract (actor model + manual/automated/AI-draft nuances):
+- `docs/platform/external-workflows-api.md`
+
+Signature controls for sequence payloads:
+- `defaultAppendSignature` (optional, sequence-level) sets the default signature-append behavior for email steps.
+- `steps[].appendSignature` (optional, step-level) overrides signature behavior for a specific email step.
+- Signature append is deterministic at send time when enabled for the step.
+
+## Bulk job status contract (authoritative run state)
+
+Use bulk jobs as the source of truth for run lifecycle:
+
+```bash
+autotouch jobs get --job-id <JOB_ID> --output json
+```
+
+Important fields:
+- `status`: `queued` | `distributing` | `processing` | `completed` | `partial` | `cancelled` | `error`
+- `processed_rows`: successful rows
+- `error_rows`: error rows
+- `skipped_rows`: intentionally skipped/ineligible rows
+- `total_rows`: scoped row count for the run
+- `pending_batches`: derived remaining batches
+- `terminal_reason`: terminal classifier
+
+Terminal states:
+- `completed`
+- `partial`
+- `cancelled`
+- `error`
+
+Agent rule:
+- Do not infer completion from local process output alone.
+- Use `jobs get` counters + terminal status as canonical truth.
+- If `job_id` is missing from local logs, recover it with `jobs list` filtered by `table_id` + `column_id`.
+
+## Column create payload recipes (CLI-ready)
+
+All examples below are used with:
+
+```bash
+autotouch columns create --table-id <TABLE_ID> --data-file <payload.json>
+```
+
+Recommendation:
+- For provider-backed workflow columns, start with `autotouch columns recipe`:
+  `add_to_crm`, `sync_to_table`, `add_to_sequence`.
+- Email/phone enrichment does not require creating `add_to_crm` first.
+- `add_to_crm` is an optional, non-billable export action.
+
+### 1) `email_finder`
+
+`email-finder.json`:
+
+```json
+{
+  "key": "work_email",
+  "label": "Work Email",
+  "kind": "enrichment",
+  "dataType": "json",
+  "origin": "email_finder",
+  "autoRun": "never",
+  "config": {
+    "provider": "smart_email_finder",
+    "strategy": "cost_optimized",
+    "lookupStrategy": "linkedin",
+    "linkedinOnly": true,
+    "enableProfileFallback": false,
+    "linkedinUrl": "linkedin_url"
+  }
+}
+```
+
+### 2) `phone_finder`
+
+`phone-finder.json`:
+
+```json
+{
+  "key": "mobile_phone",
+  "label": "Mobile Phone",
+  "kind": "enrichment",
+  "dataType": "json",
+  "origin": "phone_finder",
+  "autoRun": "never",
+  "config": {
+    "provider": "smart_phone_finder",
+    "firstName": "first_name",
+    "lastName": "last_name",
+    "company": "company",
+    "linkedinUrl": "linkedin_url"
+  }
+}
+```
+
+### 3) `lead_finder`
+
+`lead-finder.json`:
+
+```json
+{
+  "key": "lead_contacts",
+  "label": "Lead Contacts",
+  "kind": "enrichment",
+  "dataType": "json",
+  "origin": "ai",
+  "autoRun": "never",
+  "config": {
+    "provider": "lead_finder",
+    "sourceMode": "bulk_companies",
+    "companyDomain": "domain",
+    "strictness": "flexible_roles",
+    "storeAsLeads": true,
+    "autoEnrichEmails": true,
+    "autoEnrichPhones": false,
+    "jobTitles": ["Head of Sales", "VP Sales"],
+    "locations": ["United States"],
+    "maxResults": 10
+  }
+}
+```
+
+### 4) `llm_enrichment`
+
+`llm-enrichment.json`:
+
+```json
+{
+  "key": "company_research",
+  "label": "Company Research",
+  "kind": "enrichment",
+  "dataType": "json",
+  "origin": "ai",
+  "autoRun": "never",
+  "config": {
+    "prompt": "Research this company and return JSON with icp_fit, summary, and risks.",
+    "mode": "agent",
+    "temperature": 0.7,
+    "batchSize": 50,
+    "promptSource": "manual",
+    "structuredOutput": true,
+    "useAutoSchema": true
+  }
+}
+```
+
+If you provide a custom schema, use strict Schema V2 field-map shape:
+
+```json
+{
+  "key": "district_it_contact",
+  "label": "District IT Contact",
+  "kind": "enrichment",
+  "dataType": "json",
+  "origin": "ai",
+  "autoRun": "never",
+  "config": {
+    "provider": "xai",
+    "mode": "agent",
+    "structuredOutput": true,
+    "useAutoSchema": false,
+    "response_schema": {
+      "first_name": "string",
+      "last_name": "string",
+      "title": "string",
+      "email": "string",
+      "evidence_sources": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "type": "string",
+            "url": "string",
+            "snippet": "string"
+          }
+        }
+      },
+      "reasoning": "string"
+    },
+    "user_schema": {
+      "first_name": "string",
+      "last_name": "string",
+      "title": "string",
+      "email": "string",
+      "evidence_sources": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "type": "string",
+            "url": "string",
+            "snippet": "string"
+          }
+        }
+      },
+      "reasoning": "string"
+    }
+  }
+}
+```
+
+Schema guardrails:
+- Root must be a field map (no root `{"type":"object","properties":...}` wrapper).
+- Arrays must be explicit `{"type":"array","items":...}`.
+- Never use list-literal schema values like `["string"]` or `[{...}]`.
+- Prefer snake_case schema keys (`response_schema`, `user_schema`, `use_auto_schema`); camelCase variants are accepted in compatibility paths.
+
+### 5) `formatter`
+
+`formatter.json`:
+
+```json
+{
+  "key": "engagement_statement",
+  "label": "Engagement Statement",
+  "kind": "formatter",
+  "dataType": "text",
+  "origin": "manual",
+  "autoRun": "onSourceUpdate",
+  "config": {
+    "formula": "return (row['first_name'] || '') + ' ' + (row['last_name'] || '') + \" reacted to David Wilkins' post: \\\"\" + (row['post_content'] || '') + \"\\\"\";",
+    "sourceColumns": ["first_name", "last_name", "post_content"]
+  }
+}
+```
+
+Notes:
+- Formatter formulas must reference `row` keys (`row['first_name']`, `row.last_name`).
+- Bare template placeholders like ``${first_name}`` are invalid and rejected.
+- Formatter columns are source-driven; backend policy normalizes formatter `autoRun` to `onSourceUpdate`.
+
+### 6) `add_to_crm`
+
+`add-to-crm.json`:
+
+```json
+{
+  "key": "add_to_leads",
+  "label": "Add to Leads",
+  "kind": "enrichment",
+  "dataType": "json",
+  "origin": "manual",
+  "autoRun": "onSourceUpdate",
+  "config": {
+    "provider": "add_to_crm",
+    "leadSource": "research_table_export",
+    "fieldMappings": {
+      "mode": "single",
+      "linkedinUrl": "linkedin_url",
+      "companyDomain": "domain",
+      "firstName": "first_name",
+      "lastName": "last_name",
+      "title": "title",
+      "companyName": "company",
+      "emailAddresses": [
+        { "column": "work_email", "type": "work" }
+      ],
+      "phoneNumbers": [
+        { "column": "mobile_phone", "type": "mobile" }
+      ]
+    },
+    "sourceColumns": [
+      "linkedin_url",
+      "domain",
+      "first_name",
+      "last_name",
+      "title",
+      "company",
+      "work_email",
+      "mobile_phone"
+    ]
+  }
+}
+```
+
+Add-to-Leads note: mapped LinkedIn URL + company domain are required; run is non-billable.
+If `companyDomain` is missing in the table, derive or enrich that domain column first, then rerun `add_to_crm`.
+
+CRM data model expectations (recommended before `add_to_crm`):
+- Lead identity/dedupe expects `linkedin_url` + `company_domain` (clean domain like `example.com`).
+- `company_domain` is required; `company_name` is only a display hint and is applied to the linked Company record when provided.
+- Lead records link to Company via `company_id`; company names live on Company docs, not as canonical lead fields.
+- Canonical contact fields are arrays (`email_addresses[]`, `phone_numbers[]`); top-level `email`/`mobile_number` may exist on legacy rows but should not be treated as source of truth.
+- Reference docs:
+  - `docs/data/leads.md`
+  - `docs/data/companies.md`
+
+### 7) `sync_to_table`
+
+`sync-to-table.json`:
+
+```json
+{
+  "key": "sync_to_table",
+  "label": "Sync to Table",
+  "kind": "enrichment",
+  "dataType": "json",
+  "origin": "manual",
+  "autoRun": "onSourceUpdate",
+  "config": {
+    "provider": "sync_to_table",
+    "destinationTableId": "<DESTINATION_TABLE_ID>",
+    "columnMappings": [
+      { "sourceKey": "company", "destKey": "company" },
+      { "sourceKey": "domain", "destKey": "company_domain" },
+      { "sourceKey": "work_email", "destKey": "work_email" }
+    ]
+  }
+}
+```
+
+Notes:
+- Single-destination mode uses `destinationTableId` + `columnMappings`.
+- Router mode is also supported with `config.routes[]` (top-to-bottom matching, first hit wins, default route catches unmatched rows).
+
+### 8) `add_to_sequence`
+
+`add-to-sequence.json`:
+
+```json
+{
+  "key": "add_to_sequence",
+  "label": "Add to Sequence",
+  "kind": "enrichment",
+  "dataType": "json",
+  "origin": "manual",
+  "autoRun": "onSourceUpdate",
+  "config": {
+    "provider": "add_to_sequence",
+    "sequenceId": "<SEQUENCE_ID>",
+    "sourceLeadColumn": "add_to_leads"
+  }
+}
+```
+
+Notes:
+- `sourceLeadColumn` must point to a column that stores lead IDs (for example `add_to_crm` or `lead_finder` output).
+- `sequenceId` is the target sequence workflow ID.
+- The target sequence must already be `ACTIVE` for real enrollment. Table `add_to_sequence` runs and direct `POST /api/sequences/{id}/enroll` share the same activation check.
+- `add_to_sequence` runs auto-attach `research_context.source_table_id` (and table name when available). Field selection stays implicit so sequence drafts/audience resolve favorites from current starred columns by default.
+- Star/favorite the highest-signal fields so callers can see them quickly in the sidecar during live call workflows.
+- The same favorite set is also the default AI drafting context when explicit `fieldIds` are not provided.
+
+## Common workflow
+
+```bash
+autotouch capabilities
+autotouch tables create --name "CLI Contacts"
+autotouch rows import-csv --table-id <TABLE_ID> --file contacts.csv
+autotouch columns recipe --type add_to_crm --out-file column.json
+autotouch columns create --table-id <TABLE_ID> --data-file column.json
+autotouch columns recipe --type add_to_sequence --out-file add-to-sequence.json
+autotouch columns create --table-id <TABLE_ID> --data-file add-to-sequence.json
+autotouch columns run-next --table-id <TABLE_ID> --column-id <COLUMN_ID> --count 25 --filters-file filters.json --show-estimate --wait
+autotouch jobs get --job-id <JOB_ID>
+```
+
+## Safe run patterns (`firstN` + `--unprocessed-only`)
+
+Use this pattern for progressive rollouts.
+
+```bash
+# Pilot first 10 rows
+autotouch columns run \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --scope firstN \
+  --first-n 10 \
+  --unprocessed-only \
+  --show-estimate \
+  --wait
+
+# Extend to first 15 rows (processes the next 5 if first 10 are already done)
+autotouch columns run \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --scope firstN \
+  --first-n 15 \
+  --unprocessed-only \
+  --show-estimate \
+  --wait
+```
+
+Notes:
+- `firstN` without `--unprocessed-only` can re-run already-processed rows.
+- With `--unprocessed-only`, `firstN` means "first N currently eligible unprocessed rows", not "exactly N new rows since your last check".
+- If you need an exact count (for example exactly 5 rows), use `run-next` below.
+- Run-scope rule of thumb: use `row` for one exact ID, `subset` for exact many IDs, `filtered` for the current filtered view, `firstN` for staged rollouts, and `all` for full-table runs.
+- `--wait` polls `/api/bulk-jobs/{job_id}` until terminal status.
+- If a job stays `queued`, workers for that provider queue may be scaled to `0`.
+- During execution, non-final batches remain `processing`; they should not be treated as complete.
+
+## Exact count runs (`run-next`)
+
+Use this when you need exactly `N` rows in one run.
+The CLI selects candidate row IDs first, then executes `/run` with `scope=subset`.
+
+```bash
+# Run exactly 5 unprocessed rows from the current view
+autotouch columns run-next \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --count 5 \
+  --filters-file filters.json \
+  --show-estimate \
+  --wait
+```
+
+Notes:
+- Default behavior is unprocessed-only selection.
+- Add `--include-processed` to allow already-processed rows into candidate selection.
+- `run-next` is deterministic on count (subject to available eligible rows).
+- If fewer than `N` eligible rows exist, it runs the available subset and reports selected count.
+
+### Agent execution contract (strict)
+
+When operating this CLI as an agent, use backend job state as source of truth:
+
+1. Treat a run as started only if `/run` returns a `jobId` (`job_id`).
+2. Treat a run as completed only when `GET /api/bulk-jobs/{job_id}` returns terminal status.
+3. Never infer progress/completion from local process liveness alone.
+4. If polling is blocked by local network/approval/sandbox constraints, report "run state not confirmed" (do not claim still running/completed).
+5. If polling returns `not_found` or `unknown_not_found`, treat that run as failed/ambiguous and verify row state before retry.
+
+Agent output contract:
+- Prefer `--output json` (and `--compact` when token budget matters).
+- Parse machine fields only (`job_id`, `status`, `processed_rows`, `error_rows`, `skipped_rows`, `total_rows`).
+- Do not infer success from human-readable log lines.
+- If response parsing fails, treat run state as unknown and recover via `autotouch jobs list` + `autotouch jobs get`.
+
+### Enrichment value parsing contract (phone + email)
+
+When summarizing enrichment results, use this sequence:
+
+1. Inspect raw outputs first (at least 3 sample rows).
+2. Choose parser mode from column `dataType`.
+3. For `dataType=json`, apply key precedence below.
+4. For scalar types (`text`, `number`, `date`, `boolean`, `email`, `url`), read direct scalar values (no JSON key-path parsing).
+
+For JSON outputs, parse value payloads by precedence instead of a single key.
+
+Phone value extraction order:
+
+1. `mobile_number`
+2. `phone_numbers[0].number`
+3. `primary_phone`
+
+Email value extraction order:
+
+1. `response`
+2. `email`
+3. `work_email`
+
+Important:
+- Do not treat missing `response`/`phone` as a hard miss for phone finder.
+- If top-level path is missing, continue to fallback paths before reporting `not_found`.
+- Validate the parser against a few raw sample rows before publishing counts.
+
+JSON split note:
+- `columns projections` is optional by default.
+- Use it when downstream filtering/mapping/sequence variable binding needs stable flat keys.
+- Creating the projection is enough for existing rows; the backend backfills/materializes those values automatically.
+- If source columns are JSON enrichments (email/phone/LLM), run the source column first with `--wait` and confirm terminal job status before splitting.
+- CLI behavior: `columns projections` will emit preflight warnings when a JSON enrichment source appears unrun/unverified.
+- Warning output contract: when warnings exist, JSON output is wrapped as `{ "event": "projections.created_with_warnings", "warnings": [...], "result": <api_response> }`.
+
+Reference playbook + runbook:
+- `docs/research-table/guides/context-first-sequence-playbook.md`
+- `docs/research-table/reference/runbooks/context-first-sequence.json`
+
+### Wait output contract (CLI >= 0.2.11)
+
+`columns run --wait` and `columns run-next --wait` now emit structured lifecycle events:
+
+- `run.wait_started`
+- `job.progress`
+- `run.completed` / `run.timed_out`
+
+Run outputs include:
+
+- `job_id`
+- `job_status_url`
+- `watch_command` (copy-paste fallback for explicit polling)
+
+Terminal status values:
+
+- `completed`
+- `partial`
+- `error`
+- `cancelled`
+
+CLI-protected failure statuses:
+
+- `not_found`
+- `unknown_not_found`
+
+Non-terminal status values:
+
+- `queued`
+- `distributing`
+- `processing`
+
+Recommended fields to read from `jobs get` while waiting:
+- `processed_rows`
+- `error_rows`
+- `skipped_rows`
+- `total_rows`
+- `pending_batches`
+- `terminal_reason`
+
+### Canonical fallback (when `--wait` is noisy in your runtime)
+
+```bash
+# 1) Queue run and capture jobId
+autotouch columns run \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --scope firstN \
+  --first-n 15 \
+  --unprocessed-only \
+  --show-estimate \
+  --output json
+
+# 2) If jobId was not captured, recover latest from backend history
+autotouch jobs list \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --limit 1 \
+  --output json
+
+# 3) Poll backend truth directly
+autotouch jobs get --job-id <JOB_ID> --output json
+```
+
+Repeat `jobs get` until status is terminal.
+
+## CSV import (agent-safe, async-first)
+
+`rows import-csv` defaults to optimized import transport (`/import-optimized`) so large files do not fail on a single long request.
+
+```bash
+# Queue background import and return task_id quickly
+autotouch rows import-csv \
+  --table-id <TABLE_ID> \
+  --confirm-table-id <TABLE_ID> \
+  --file contacts.csv \
+  --checkpoint-file .autotouch-import.json
+
+# Wait for completion
+autotouch rows import-status \
+  --table-id <TABLE_ID> \
+  --task-id <TASK_ID> \
+  --wait
+```
+
+Notes:
+- Use `--sync` only when you explicitly want synchronous behavior.
+- Legacy direct path is still available with `--transport direct`.
+- Optimized import emits progressive events while processing, and starts with a small first batch for fast initial row visibility.
+- Use `--dry-run` for parse-only preview before writing rows.
+- Use `--validate-only` to test server-side CSV parsing/shape without writing rows.
+- Blacklist controls on optimized import:
+  - company-domain filtering is ON by default
+  - email filtering is OFF by default
+  - disable company filtering with `--no-check-company-blacklist`
+  - enable email filtering with `--check-email-blacklist`
+- Safety assertions are available on import:
+  - `--expected-rows <N>`
+  - `--require-columns col_a,col_b`
+  - `--duplicate-key col_a,col_b`
+  - `--require-non-empty post_content:0.95`
+- Assertions run as preflight checks. For async imports with `--wait`, postflight verification runs against the persisted task manifest automatically.
+- Use `--allow-reimport` only when intentionally importing the same file again.
+- Import responses include `blacklist_summary` with company/email `skipped_count` and `enforced` flags.
+
+Safe protocol:
+
+```bash
+# 1) Validate parse/shape only (no writes)
+autotouch rows import-csv --table-id <TABLE_ID> --confirm-table-id <TABLE_ID> --file contacts.csv --validate-only
+
+# 2) Import with strict assertions + wait
+autotouch rows import-csv \
+  --table-id <TABLE_ID> \
+  --confirm-table-id <TABLE_ID> \
+  --file contacts.csv \
+  --checkpoint-file .autotouch-import.json \
+  --check-email-blacklist \
+  --expected-rows 57 \
+  --require-columns first_name,last_name,post_content \
+  --duplicate-key linkedin_url,post_url \
+  --require-non-empty post_content:1 \
+  --wait
+
+# 3) Re-verify later (optional)
+autotouch rows import-verify --table-id <TABLE_ID> --task-id <TASK_ID> --expected-rows 57
+
+# 4) Roll back by task_id if needed
+autotouch rows import-rollback --table-id <TABLE_ID> --task-id <TASK_ID>
+```
+
+Manage blacklist entries (native CLI, admin identity required):
+
+```bash
+# List current entries
+autotouch blacklist list --type-filter all --limit 100
+
+# Add entries
+autotouch blacklist add --type domain --value competitor.com --reason "Do not contact"
+autotouch blacklist add --type email --value blocked@example.com --reason "Unsubscribed"
+
+# Bulk-import entries from CSV/TXT
+autotouch blacklist import --file blacklist.csv
+
+# Check or filter email sets (auto-chunked for large lists)
+autotouch blacklist check --emails-file recipients.csv --emails-column email --summary-only
+autotouch blacklist filter --emails-file recipients.csv --emails-column email --summary-only
+```
+
+Recommended timing (cost + ICP guardrail):
+- Add known suppressions early (unsubscribed addresses, do-not-contact domains, existing customers, competitors, and clear non-ICP targets).
+- Before billable enrichments (`llm_enrichment`, `email_finder`, `phone_finder`), run blacklist filtering on candidate emails and enrich only clean rows.
+- Run a final blacklist check/filter again before downstream outreach or dialing.
+
+```bash
+# Example: pre-enrichment blacklist gate
+autotouch blacklist filter \
+  --emails-file candidates.csv \
+  --emails-column work_email \
+  --output json
+```
+
+## Capabilities for agents
+
+Use capabilities as the source of truth before generating payloads:
+
+```bash
+autotouch capabilities
+```
+
+Agent expectations:
+
+- `column_types` tells you which column types are runnable and which are non-billable transforms (`json_split`, `formatter_formula`).
+- `filtering` describes valid scope/filter semantics for estimate/run.
+- `automation.auto_run` describes supported auto-run modes + config field names.
+- `execution_policies.llm.output_contract` describes output behavior by mode:
+  - `agent` => JSON-oriented structured output
+  - `basic` => text or JSON (`dataType=json` for structured JSON output)
+- `webhooks.table_ingest` describes webhook ingest auth contract (metadata only; no secret tokens).
+
+For a built-in machine-readable run playbook, use:
+
+```bash
+autotouch sop --output json
+```
+
+## JSON output pipeline pattern
+
+For enrichment responses that return structured JSON, use this chain:
+
+1. Run enrichment into a JSON column.
+2. Wait for terminal status (`completed`/`partial`/`error`/`cancelled`) using `--wait` or `jobs get/watch`.
+3. Split JSON into projection columns (optional; only when stable flat keys are needed).
+4. Optional formatter normalization.
+5. Feed extracted/normalized keys into downstream enrichment columns.
+
+Important mode distinction:
+
+- Agent mode is JSON-oriented and is intended for structured outputs.
+- Basic mode can return plain text or JSON depending on your column `dataType`/schema setup.
+
+### Recommended ICP buyer pattern (agent mode)
+
+For go-to-market workflows, prefer one best-fit buyer per row in this stage.
+
+- Ask for exactly one person (not a list/array) with a flat JSON object.
+- Recommended keys: `first_name`, `last_name`, `title`, `company_name`, `company_website`, `linkedin_url`.
+- Then split those keys into projection columns and run email/phone enrichment on those outputs.
+- Use `lead_finder` first for larger companies when role ownership is clear; use agent research for hard-to-find or low-coverage cases.
+- Target responsibilities, not exact titles (for example: "most likely responsible for buying social/cell engagement software").
+
+Prompt shape recommendation:
+
+```text
+Find the single most likely buyer of cell engagement software for this company.
+Return exactly one JSON object with keys:
+first_name, last_name, title, company_name, company_website, linkedin_url.
+Use empty string when unknown.
+```
+
+Full strategy and examples:
+
+- `docs/research-table/guides/icp-buyer-discovery.md`
+
+```bash
+# Create projections from a JSON source column
+autotouch columns projections \
+  --table-id <TABLE_ID> \
+  --data-file projections.json
+
+# Optional: update downstream column config to reference projected keys
+autotouch columns update \
+  --table-id <TABLE_ID> \
+  --column-id <DOWNSTREAM_COLUMN_ID> \
+  --data-file column-update.json
+```
+
+`projections.json`:
+
+```json
+{
+  "items": [
+    {
+      "key": "person_name",
+      "label": "Person Name",
+      "sourceColumnId": "<JSON_COLUMN_ID>",
+      "path": "person_name",
+      "dataType": "text"
+    },
+    {
+      "key": "school_domain",
+      "label": "School Domain",
+      "sourceColumnId": "<JSON_COLUMN_ID>",
+      "path": "school_domain",
+      "dataType": "text"
+    }
+  ]
+}
+```
+
+### First principles: intent + context
+
+For most workflows, useful output has two layers:
+- context: source evidence (what happened / what was observed)
+- intent: interpretation of that evidence (what to prioritize / do next)
+
+Design guidance:
+- preserve full-fidelity context in at least one raw field (for example full post/body text)
+- default behavior for agents: write full context/content, not summaries or truncation
+- only truncate/summarize when there is a hard limit (storage/model/provider/payload), and mark that it was truncated
+- keep intent separate from raw context so automation can evolve without data loss
+- for calling workflows, star/favorite high-signal fields so sidecar context is immediately useful without extra clicks
+- for AI-generated emails/copy, keep intent + full context together in imports so drafts are grounded in source evidence
+- keep one entity per row and dedupe using a stable identity key
+- treat snippets/summaries as optional derived fields, never the source of truth
+- if automation depends on intent values, use a small normalized label taxonomy
+
+Optional field pattern (adapt as needed):
+- `post_content` or `context_raw`: full long-form context text
+- `context_url`: source URL
+- `context_timestamp`: recency marker
+- `intent_label`: normalized intent category
+- `intent_reason`: human-readable explanation
+
+CSV handling note:
+- long context fields may include newlines/commas and are valid when properly quoted
+- run `autotouch rows import-csv --validate-only` (or `--dry-run`) first
+- for strict guardrails, add assertions: `--expected-rows`, `--require-columns`, `--duplicate-key`, `--require-non-empty`
+- for mutating imports, use `--confirm-table-id` and `--checkpoint-file` to reduce accidental corruption/duplicates
+- import does not intentionally truncate text values; practical limits are the underlying MongoDB document-size limits
+
+Multiline `post_content` examples:
+
+```csv
+# bad (unquoted multiline content breaks row shape)
+first_name,linkedin_url,post_content
+Ada,https://linkedin.com/in/ada,Line 1
+Line 2
+```
+
+```csv
+# good (quoted multiline content is valid CSV)
+first_name,linkedin_url,post_content
+Ada,https://linkedin.com/in/ada,"Line 1
+Line 2"
+```
+
+Do not re-import blind (recovery flow):
+- stop and keep the original `task_id`
+- inspect status: `autotouch rows import-status --table-id <TABLE_ID> --task-id <TASK_ID>`
+- prove postflight: `autotouch rows import-verify --table-id <TABLE_ID> --task-id <TASK_ID> ...assertions...`
+- if verification fails, preview rollback: `autotouch rows import-rollback --table-id <TABLE_ID> --task-id <TASK_ID> --dry-run`
+- then rollback: `autotouch rows import-rollback --table-id <TABLE_ID> --task-id <TASK_ID>`
+- fix CSV quoting/mapping and run `--validate-only` before any new import
+
+## Filtering (credit control)
+
+Use `scope=filtered` to run only matching rows.
+
+`filters.json`:
+
+```json
+{
+  "mode": "and",
+  "filters": [
+    { "columnKey": "linkedin_url", "operator": "isNotEmpty" },
+    { "columnKey": "country", "operator": "equals", "value": "United States" }
+  ]
+}
+```
+
+```bash
+# Estimate first (non-billable)
+autotouch columns estimate \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --scope filtered \
+  --filters-file filters.json \
+  --unprocessed-only
+
+# Run same payload with rollout cap
+autotouch columns run \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --scope filtered \
+  --filters-file filters.json \
+  --unprocessed-only \
+  --first-n 200 \
+  --show-estimate --wait
+```
+
+### Cost tip: filter out empty rows between enrichments
+
+Most teams run paid enrichments only on rows that already have required upstream data.
+This avoids spending credits on rows that cannot produce useful results yet.
+
+Example: run email finder only when `linkedin_url` exists and `work_email_address` is still empty.
+
+```json
+{
+  "mode": "and",
+  "filters": [
+    { "columnKey": "linkedin_url", "operator": "isNotEmpty" },
+    { "columnKey": "work_email_address", "operator": "isEmpty" }
+  ]
+}
+```
+
+Pattern to reuse:
+- Step 1: create/select a filter that excludes empty prerequisite fields.
+- Step 2: run small (`firstN` or `run-next`) with `--show-estimate`.
+- Step 3: expand only after output quality looks good.
+
+### Cost tip: run blacklist gate before billable enrichments
+
+Before `llm_enrichment`, `email_finder`, or `phone_finder`, run blacklist check/filter so credit spend stays focused on eligible ICP rows (and excludes suppressions like customers/competitors).
+
+```bash
+autotouch blacklist filter \
+  --emails-file candidates.csv \
+  --emails-column work_email \
+  --output json
+```
+
+## Auto-run configuration
+
+Auto-run is set on the column definition (`autoRun`) and can be changed later with `columns update`.
+
+Formatter-specific rule:
+- Formatter columns are always normalized to `autoRun: "onSourceUpdate"` by the backend.
+- Attempting to set formatter `autoRun` to `never` or `onInsert` is ignored/overridden server-side.
+
+`column-update.json`:
+
+```json
+{
+  "autoRun": "onInsert",
+  "config": {
+    "autoRunMode": "conditional",
+    "autoRunFilters": {
+      "mode": "and",
+      "filters": [
+        { "columnKey": "linkedin_url", "operator": "isNotEmpty" }
+      ]
+    }
+  }
+}
+```
+
+```bash
+autotouch columns update \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --data-file column-update.json
+```
+
+## Table webhooks (ingest)
+
+Webhook ingestion uses a per-table token, not developer API key scopes.
+
+```bash
+# Read current webhook config
+autotouch webhooks get --table-id <TABLE_ID>
+
+# Create/rotate token (token is returned once)
+autotouch webhooks rotate --table-id <TABLE_ID>
+```
+
+`records.json`:
+
+```json
+{
+  "records": [
+    { "first_name": "Ada", "email": "ada@example.com" }
+  ]
+}
+```
+
+```bash
+# Send records with webhook token
+autotouch webhooks ingest \
+  --table-id <TABLE_ID> \
+  --records-file records.json \
+  --webhook-token <WEBHOOK_TOKEN>
+```
+
+## Outbound webhook subscriptions
+
+Use outbound subscriptions to receive business events (`bulk_job.*`, `lead.*`, `sequence_enrollment.created`, `task.created`).
+
+```bash
+# List subscriptions
+autotouch webhooks subscriptions list
+
+# Create subscription
+autotouch webhooks subscriptions create \
+  --url https://example.com/webhooks/smart-table \
+  --events bulk_job.* lead.status_changed task.created
+
+# Pause/resume
+autotouch webhooks subscriptions pause --subscription-id <SUBSCRIPTION_ID>
+autotouch webhooks subscriptions resume --subscription-id <SUBSCRIPTION_ID>
+
+# Rotate signing secret
+autotouch webhooks subscriptions rotate-secret --subscription-id <SUBSCRIPTION_ID>
+
+# Fire test event
+autotouch webhooks subscriptions test \
+  --subscription-id <SUBSCRIPTION_ID> \
+  --event-type lead.created \
+  --data-json '{"ping":"ok"}'
+
+# Inspect deliveries + attempts
+autotouch webhooks deliveries list --subscription-id <SUBSCRIPTION_ID> --limit 50
+autotouch webhooks deliveries attempts --delivery-id <DELIVERY_ID>
+```
+
+Required scopes for developer API keys:
+- `webhooks:read` (list/get/deliveries)
+- `webhooks:write` (create/update/delete/pause/resume/rotate/test)
+
+Retention note:
+- Webhook event cache and delivery-attempt logs default to 7 days
+  (`WEBHOOK_EVENTS_TTL_DAYS`, `WEBHOOK_DELIVERY_ATTEMPTS_TTL_DAYS`).
+
+## Budget and safety controls
+
+```bash
+# Estimate only (no execution)
+autotouch columns run --table-id <TABLE_ID> --column-id <COLUMN_ID> --scope filtered --filters-file filters.json --unprocessed-only --dry-run
+
+# Guard against overspend
+autotouch columns run --table-id <TABLE_ID> --column-id <COLUMN_ID> --scope filtered --filters-file filters.json --unprocessed-only --max-credits 50
+
+# Poll until terminal status
+autotouch jobs watch --job-id <JOB_ID>
+
+# Stop a running column
+autotouch columns stop --table-id <TABLE_ID> --column-id <COLUMN_ID>
+```
+
+## Notes
+
+- The CLI is a thin wrapper around the same HTTP endpoints documented in `docs/research-table/reference/tables-api.md`.
+- If a key is missing scope, CLI commands fail the same way raw API calls do (`403`).
+- Use `--base-url` and `--token` per command for CI/ephemeral environments.