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

{autotouch_cli-0.2.20 → autotouch_cli-0.2.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.20
+Version: 0.2.22
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -72,12 +72,12 @@ Reference:
 # 1) Verify target table exists and copy the exact id
 autotouch tables list --view-mode org --output human
 
-# 2) Parse CSV only (no write)
+# 2) Validate server-side CSV parse/shape (no write)
 autotouch rows import-csv \
   --table-id <TABLE_ID> \
   --confirm-table-id <TABLE_ID> \
   --file contacts.csv \
-  --dry-run \
+  --validate-only \
   --output json
 ```
 
@@ -101,7 +101,56 @@ Notes:
 - `--transport optimized` is default (`/import-optimized`).
 - `--wait` polls import status to terminal state.
 - `--checkpoint-file` stores state and blocks accidental duplicate re-imports.
+- `--validate-only` validates CSV parse/shape on server 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:
+  - `--expected-rows <N>`
+  - `--require-columns col_a,col_b`
+  - `--duplicate-key col_a,col_b`
+  - `--require-non-empty key:ratio`
+- For async imports with `--wait`, assertions are rechecked postflight via task manifest verification.
 - Use `--allow-reimport` if you intentionally want to run the same file again.
+- Import responses include `blacklist_summary` with company/email `skipped_count` and `enforced` flags.
+
+Example enabling both company and email enforcement:
+
+```bash
+autotouch rows import-csv \
+  --table-id <TABLE_ID> \
+  --confirm-table-id <TABLE_ID> \
+  --file contacts.csv \
+  --checkpoint-file .autotouch-import.json \
+  --check-email-blacklist \
+  --wait \
+  --output json
+```
+
+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/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:
+- Add suppressions early (unsubscribed addresses, existing customers, competitors, and clear non-ICP domains).
+- Before billable enrichments (`llm_enrichment`, `email_finder`, `phone_finder`), run blacklist filtering and enrich only clean candidates.
+- Run one final blacklist check/filter before outreach execution.
 
 ## Import modes
 
@@ -133,6 +182,7 @@ Auto-run is configured per column (`autoRun`), not per table.
 Important:
 - Insert events do not run `onSourceUpdate` columns.
 - Imports may queue auto-run dispatch evaluation, but only columns whose `autoRun` policy matches the event are queued.
+- Formatter columns are normalized server-side to `onSourceUpdate` (attempted `never`/`onInsert` values are overridden).
 
 ## Create a column
 
@@ -157,6 +207,7 @@ Notes:
 - `add_to_crm` is optional and non-billable.
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
+- Formatter formulas must use row references (`row['first_name']`, `row.last_name`), not bare template placeholders like ``${first_name}``.
 - `sync_to_table` supports both:
   - single destination: `destinationTableId` + `columnMappings`
   - router mode: `routes[]` (first matching route wins)
@@ -164,6 +215,7 @@ Notes:
   - `sequenceId`
   - `sourceLeadColumn` pointing to a lead-id producing column (`add_to_crm` or `lead_finder` output)
   - auto-attaches research context defaults during enrollment (`source_table_id`, plus optional table name); favorite fields resolve from current starred columns when explicit `fieldIds` are not provided
+  - star/favorite high-signal fields so call-sidecar context stays quick to scan and AI draft context stays focused
 
 If you create custom `llm_enrichment` schemas:
 - Use strict field-map schema shape (no root `type/properties` wrapper).
@@ -209,6 +261,65 @@ This keeps quickstart short while documenting the full strategy:
 - one-person-per-row output contract,
 - JSON split + downstream enrichment chaining.
 
+## First-principles shape: intent + context
+
+For most workflows, useful output combines:
+- context: source evidence (what happened / what was observed)
+- intent: interpretation signal (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 explicitly mark truncation
+- keep intent separate from raw context so downstream logic can change without losing source data
+- for calling workflows, favorite/star key fields so users can access the most relevant context quickly in sidecar views
+- for AI-generated emails/copy, include both intent and full context in imports so drafts are grounded, not generic
+- keep one entity per row and dedupe on a stable identity key
+- keep snippets/summaries optional and derived from raw context, never a replacement for it
+- normalize intent labels if you need deterministic automation
+
+Optional field pattern (adapt to your workflow):
+- `post_content` or `context_raw`: full long-form context
+- `context_url`: source URL
+- `context_timestamp`: recency marker
+- `intent_label`: normalized intent category
+- `intent_reason`: concise rationale
+
+CSV import note for context fields:
+- long text fields like `post_content` can contain newlines and commas
+- that is valid CSV when fields are properly quoted
+- always run `rows import-csv --validate-only` (or `--dry-run`) before write
+- for strict guardrails, add assertions: `--expected-rows`, `--require-columns`, `--duplicate-key`, `--require-non-empty`
+- import does not intentionally truncate text values; very large single-cell payloads are still bounded by Mongo document limits
+
+Verification + rollback commands:
+- `autotouch rows import-verify --table-id <TABLE_ID> --task-id <TASK_ID> --expected-rows <N>`
+- `autotouch rows import-rollback --table-id <TABLE_ID> --task-id <TASK_ID>`
+
+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
+
 ## Sequences/Tasks workflow APIs (current CLI coverage)
 
 The installable `autotouch` CLI currently provides first-class commands for research-table APIs.
@@ -452,6 +563,15 @@ autotouch columns run-next \
   --wait
 ```
 
+Blacklist gate (recommended before billable runs):
+
+```bash
+autotouch blacklist filter \
+  --emails-file candidates.csv \
+  --emails-column work_email \
+  --output json
+```
+
 ## Job truth contract (agent-safe)
 
 - Treat a run as started only when you receive `job_id`.
@@ -507,12 +627,16 @@ If either failure status appears, treat the run as unconfirmed/inconsistent, ver
 - Re-run with same `--checkpoint-file` and `--wait`.
 - CLI can resume/poll an in-flight task from checkpoint state.
 
-4. Run queued but job id missing from local output:
+4. Need proof before saying "fixed":
+- Run `autotouch rows import-verify --table-id <TABLE_ID> --task-id <TASK_ID> ...assertions...`
+- Treat `passed=false` as a failed import outcome.
+
+5. Run queued but job id missing from local output:
 - Recover from backend history:
   - `autotouch jobs list --table-id <TABLE_ID> --column-id <COLUMN_ID> --limit 5 --output json`
 - Then poll the returned `job_id` with `autotouch jobs get` / `autotouch jobs watch`.
 
-5. Need to stop a running column job:
+6. Need to stop a running column job:
 
 ```bash
 autotouch columns stop --table-id <TABLE_ID> --column-id <COLUMN_ID>

{autotouch_cli-0.2.20 → autotouch_cli-0.2.22}/autotouch_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.20
+Version: 0.2.22
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -72,12 +72,12 @@ Reference:
 # 1) Verify target table exists and copy the exact id
 autotouch tables list --view-mode org --output human
 
-# 2) Parse CSV only (no write)
+# 2) Validate server-side CSV parse/shape (no write)
 autotouch rows import-csv \
   --table-id <TABLE_ID> \
   --confirm-table-id <TABLE_ID> \
   --file contacts.csv \
-  --dry-run \
+  --validate-only \
   --output json
 ```
 
@@ -101,7 +101,56 @@ Notes:
 - `--transport optimized` is default (`/import-optimized`).
 - `--wait` polls import status to terminal state.
 - `--checkpoint-file` stores state and blocks accidental duplicate re-imports.
+- `--validate-only` validates CSV parse/shape on server 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:
+  - `--expected-rows <N>`
+  - `--require-columns col_a,col_b`
+  - `--duplicate-key col_a,col_b`
+  - `--require-non-empty key:ratio`
+- For async imports with `--wait`, assertions are rechecked postflight via task manifest verification.
 - Use `--allow-reimport` if you intentionally want to run the same file again.
+- Import responses include `blacklist_summary` with company/email `skipped_count` and `enforced` flags.
+
+Example enabling both company and email enforcement:
+
+```bash
+autotouch rows import-csv \
+  --table-id <TABLE_ID> \
+  --confirm-table-id <TABLE_ID> \
+  --file contacts.csv \
+  --checkpoint-file .autotouch-import.json \
+  --check-email-blacklist \
+  --wait \
+  --output json
+```
+
+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/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:
+- Add suppressions early (unsubscribed addresses, existing customers, competitors, and clear non-ICP domains).
+- Before billable enrichments (`llm_enrichment`, `email_finder`, `phone_finder`), run blacklist filtering and enrich only clean candidates.
+- Run one final blacklist check/filter before outreach execution.
 
 ## Import modes
 
@@ -133,6 +182,7 @@ Auto-run is configured per column (`autoRun`), not per table.
 Important:
 - Insert events do not run `onSourceUpdate` columns.
 - Imports may queue auto-run dispatch evaluation, but only columns whose `autoRun` policy matches the event are queued.
+- Formatter columns are normalized server-side to `onSourceUpdate` (attempted `never`/`onInsert` values are overridden).
 
 ## Create a column
 
@@ -157,6 +207,7 @@ Notes:
 - `add_to_crm` is optional and non-billable.
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
+- Formatter formulas must use row references (`row['first_name']`, `row.last_name`), not bare template placeholders like ``${first_name}``.
 - `sync_to_table` supports both:
   - single destination: `destinationTableId` + `columnMappings`
   - router mode: `routes[]` (first matching route wins)
@@ -164,6 +215,7 @@ Notes:
   - `sequenceId`
   - `sourceLeadColumn` pointing to a lead-id producing column (`add_to_crm` or `lead_finder` output)
   - auto-attaches research context defaults during enrollment (`source_table_id`, plus optional table name); favorite fields resolve from current starred columns when explicit `fieldIds` are not provided
+  - star/favorite high-signal fields so call-sidecar context stays quick to scan and AI draft context stays focused
 
 If you create custom `llm_enrichment` schemas:
 - Use strict field-map schema shape (no root `type/properties` wrapper).
@@ -209,6 +261,65 @@ This keeps quickstart short while documenting the full strategy:
 - one-person-per-row output contract,
 - JSON split + downstream enrichment chaining.
 
+## First-principles shape: intent + context
+
+For most workflows, useful output combines:
+- context: source evidence (what happened / what was observed)
+- intent: interpretation signal (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 explicitly mark truncation
+- keep intent separate from raw context so downstream logic can change without losing source data
+- for calling workflows, favorite/star key fields so users can access the most relevant context quickly in sidecar views
+- for AI-generated emails/copy, include both intent and full context in imports so drafts are grounded, not generic
+- keep one entity per row and dedupe on a stable identity key
+- keep snippets/summaries optional and derived from raw context, never a replacement for it
+- normalize intent labels if you need deterministic automation
+
+Optional field pattern (adapt to your workflow):
+- `post_content` or `context_raw`: full long-form context
+- `context_url`: source URL
+- `context_timestamp`: recency marker
+- `intent_label`: normalized intent category
+- `intent_reason`: concise rationale
+
+CSV import note for context fields:
+- long text fields like `post_content` can contain newlines and commas
+- that is valid CSV when fields are properly quoted
+- always run `rows import-csv --validate-only` (or `--dry-run`) before write
+- for strict guardrails, add assertions: `--expected-rows`, `--require-columns`, `--duplicate-key`, `--require-non-empty`
+- import does not intentionally truncate text values; very large single-cell payloads are still bounded by Mongo document limits
+
+Verification + rollback commands:
+- `autotouch rows import-verify --table-id <TABLE_ID> --task-id <TASK_ID> --expected-rows <N>`
+- `autotouch rows import-rollback --table-id <TABLE_ID> --task-id <TASK_ID>`
+
+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
+
 ## Sequences/Tasks workflow APIs (current CLI coverage)
 
 The installable `autotouch` CLI currently provides first-class commands for research-table APIs.
@@ -452,6 +563,15 @@ autotouch columns run-next \
   --wait
 ```
 
+Blacklist gate (recommended before billable runs):
+
+```bash
+autotouch blacklist filter \
+  --emails-file candidates.csv \
+  --emails-column work_email \
+  --output json
+```
+
 ## Job truth contract (agent-safe)
 
 - Treat a run as started only when you receive `job_id`.
@@ -507,12 +627,16 @@ If either failure status appears, treat the run as unconfirmed/inconsistent, ver
 - Re-run with same `--checkpoint-file` and `--wait`.
 - CLI can resume/poll an in-flight task from checkpoint state.
 
-4. Run queued but job id missing from local output:
+4. Need proof before saying "fixed":
+- Run `autotouch rows import-verify --table-id <TABLE_ID> --task-id <TASK_ID> ...assertions...`
+- Treat `passed=false` as a failed import outcome.
+
+5. Run queued but job id missing from local output:
 - Recover from backend history:
   - `autotouch jobs list --table-id <TABLE_ID> --column-id <COLUMN_ID> --limit 5 --output json`
 - Then poll the returned `job_id` with `autotouch jobs get` / `autotouch jobs watch`.
 
-5. Need to stop a running column job:
+6. Need to stop a running column job:
 
 ```bash
 autotouch columns stop --table-id <TABLE_ID> --column-id <COLUMN_ID>

{autotouch_cli-0.2.20 → autotouch_cli-0.2.22}/autotouch_cli.egg-info/SOURCES.txt

@@ -48,6 +48,7 @@ scripts/migrations/20260113_normalize_table_filter_operators.py
 scripts/migrations/20260113_set_user_permissions_user_admin.py
 scripts/migrations/20260204_sync_lead_owner_from_tasks.py
 scripts/migrations/20260303_add_webhook_subscription_collections.py
+scripts/migrations/20260305_force_formatter_autorun_on_source_update.py
 scripts/migrations/migrate_org_user_credits.py
 scripts/migrations/set_default_lead_status.py
 scripts/migrations/update_lead_owner_from_tasks.py

{autotouch_cli-0.2.20 → autotouch_cli-0.2.22}/docs/research-table/reference/autotouch-cli-pypi.md

@@ -63,12 +63,12 @@ Reference:
 # 1) Verify target table exists and copy the exact id
 autotouch tables list --view-mode org --output human
 
-# 2) Parse CSV only (no write)
+# 2) Validate server-side CSV parse/shape (no write)
 autotouch rows import-csv \
   --table-id <TABLE_ID> \
   --confirm-table-id <TABLE_ID> \
   --file contacts.csv \
-  --dry-run \
+  --validate-only \
   --output json
 ```
 
@@ -92,7 +92,56 @@ Notes:
 - `--transport optimized` is default (`/import-optimized`).
 - `--wait` polls import status to terminal state.
 - `--checkpoint-file` stores state and blocks accidental duplicate re-imports.
+- `--validate-only` validates CSV parse/shape on server 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:
+  - `--expected-rows <N>`
+  - `--require-columns col_a,col_b`
+  - `--duplicate-key col_a,col_b`
+  - `--require-non-empty key:ratio`
+- For async imports with `--wait`, assertions are rechecked postflight via task manifest verification.
 - Use `--allow-reimport` if you intentionally want to run the same file again.
+- Import responses include `blacklist_summary` with company/email `skipped_count` and `enforced` flags.
+
+Example enabling both company and email enforcement:
+
+```bash
+autotouch rows import-csv \
+  --table-id <TABLE_ID> \
+  --confirm-table-id <TABLE_ID> \
+  --file contacts.csv \
+  --checkpoint-file .autotouch-import.json \
+  --check-email-blacklist \
+  --wait \
+  --output json
+```
+
+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/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:
+- Add suppressions early (unsubscribed addresses, existing customers, competitors, and clear non-ICP domains).
+- Before billable enrichments (`llm_enrichment`, `email_finder`, `phone_finder`), run blacklist filtering and enrich only clean candidates.
+- Run one final blacklist check/filter before outreach execution.
 
 ## Import modes
 
@@ -124,6 +173,7 @@ Auto-run is configured per column (`autoRun`), not per table.
 Important:
 - Insert events do not run `onSourceUpdate` columns.
 - Imports may queue auto-run dispatch evaluation, but only columns whose `autoRun` policy matches the event are queued.
+- Formatter columns are normalized server-side to `onSourceUpdate` (attempted `never`/`onInsert` values are overridden).
 
 ## Create a column
 
@@ -148,6 +198,7 @@ Notes:
 - `add_to_crm` is optional and non-billable.
 - Email/phone enrichment does not require creating/running `add_to_crm`.
 - For `add_to_crm`, required mapping keys are `linkedinUrl` and `companyDomain`.
+- Formatter formulas must use row references (`row['first_name']`, `row.last_name`), not bare template placeholders like ``${first_name}``.
 - `sync_to_table` supports both:
   - single destination: `destinationTableId` + `columnMappings`
   - router mode: `routes[]` (first matching route wins)
@@ -155,6 +206,7 @@ Notes:
   - `sequenceId`
   - `sourceLeadColumn` pointing to a lead-id producing column (`add_to_crm` or `lead_finder` output)
   - auto-attaches research context defaults during enrollment (`source_table_id`, plus optional table name); favorite fields resolve from current starred columns when explicit `fieldIds` are not provided
+  - star/favorite high-signal fields so call-sidecar context stays quick to scan and AI draft context stays focused
 
 If you create custom `llm_enrichment` schemas:
 - Use strict field-map schema shape (no root `type/properties` wrapper).
@@ -200,6 +252,65 @@ This keeps quickstart short while documenting the full strategy:
 - one-person-per-row output contract,
 - JSON split + downstream enrichment chaining.
 
+## First-principles shape: intent + context
+
+For most workflows, useful output combines:
+- context: source evidence (what happened / what was observed)
+- intent: interpretation signal (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 explicitly mark truncation
+- keep intent separate from raw context so downstream logic can change without losing source data
+- for calling workflows, favorite/star key fields so users can access the most relevant context quickly in sidecar views
+- for AI-generated emails/copy, include both intent and full context in imports so drafts are grounded, not generic
+- keep one entity per row and dedupe on a stable identity key
+- keep snippets/summaries optional and derived from raw context, never a replacement for it
+- normalize intent labels if you need deterministic automation
+
+Optional field pattern (adapt to your workflow):
+- `post_content` or `context_raw`: full long-form context
+- `context_url`: source URL
+- `context_timestamp`: recency marker
+- `intent_label`: normalized intent category
+- `intent_reason`: concise rationale
+
+CSV import note for context fields:
+- long text fields like `post_content` can contain newlines and commas
+- that is valid CSV when fields are properly quoted
+- always run `rows import-csv --validate-only` (or `--dry-run`) before write
+- for strict guardrails, add assertions: `--expected-rows`, `--require-columns`, `--duplicate-key`, `--require-non-empty`
+- import does not intentionally truncate text values; very large single-cell payloads are still bounded by Mongo document limits
+
+Verification + rollback commands:
+- `autotouch rows import-verify --table-id <TABLE_ID> --task-id <TASK_ID> --expected-rows <N>`
+- `autotouch rows import-rollback --table-id <TABLE_ID> --task-id <TASK_ID>`
+
+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
+
 ## Sequences/Tasks workflow APIs (current CLI coverage)
 
 The installable `autotouch` CLI currently provides first-class commands for research-table APIs.
@@ -443,6 +554,15 @@ autotouch columns run-next \
   --wait
 ```
 
+Blacklist gate (recommended before billable runs):
+
+```bash
+autotouch blacklist filter \
+  --emails-file candidates.csv \
+  --emails-column work_email \
+  --output json
+```
+
 ## Job truth contract (agent-safe)
 
 - Treat a run as started only when you receive `job_id`.
@@ -498,12 +618,16 @@ If either failure status appears, treat the run as unconfirmed/inconsistent, ver
 - Re-run with same `--checkpoint-file` and `--wait`.
 - CLI can resume/poll an in-flight task from checkpoint state.
 
-4. Run queued but job id missing from local output:
+4. Need proof before saying "fixed":
+- Run `autotouch rows import-verify --table-id <TABLE_ID> --task-id <TASK_ID> ...assertions...`
+- Treat `passed=false` as a failed import outcome.
+
+5. Run queued but job id missing from local output:
 - Recover from backend history:
   - `autotouch jobs list --table-id <TABLE_ID> --column-id <COLUMN_ID> --limit 5 --output json`
 - Then poll the returned `job_id` with `autotouch jobs get` / `autotouch jobs watch`.
 
-5. Need to stop a running column job:
+6. Need to stop a running column job:
 
 ```bash
 autotouch columns stop --table-id <TABLE_ID> --column-id <COLUMN_ID>

{autotouch_cli-0.2.20 → autotouch_cli-0.2.22}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "autotouch-cli"
-version = "0.2.20"
+version = "0.2.22"
 description = "Autotouch Smart Table CLI"
 readme = "docs/research-table/reference/autotouch-cli-pypi.md"
 requires-python = ">=3.9"