# zerch.ai — AI Target Account Engine

> zerch.ai supports natural-language ICP briefs, ranked company-universe work, AI-assisted evidence checks, and file exports. This document describes the repository's current product surface; live provider availability and launch approval are separate gates.

zerch.ai lets authenticated workspaces turn a natural-language Ideal Customer Profile (ICP) brief into a bounded, exportable company universe for review.

## Core Capabilities

1. **Natural Language Query Compilation**: Converts plain-English target briefs into structured query execution plans.
2. **Automated Cutoff Calibration**: Proposes a recommended similarity-score cutoff from the observed score distribution to help filter low-fit candidates; results still require customer review.
3. **Multi-Domain Seed Consensus (HYBRID)**: Computes vector similarity over candidate companies against seed domain embedding centroids.
4. **Zero-Socket Stdio MCP Server**: Exposes stdio JSON-RPC tools for Claude Desktop, Cursor, and autonomous AI subagents.
5. **Developer CLI (`zerch`)**: Provides the supported paid-v1 workflow for bounded search, saved-universe materialization, AI verification, export-job creation, and artifact download.
6. **Transparent Data Proof**: Returns a fit explanation and available company/public evidence for a similarity result; results still require customer review.

---

## Model Context Protocol (MCP) Server

The default MCP runtime connects to the public Zerch API. Configure a public
base URL and exactly one workspace credential before starting:

```bash
export ZERCH_API_BASE_URL="https://api.zerch.ai"
export ZERCH_API_TOKEN="<workspace-bearer-token>"  # or ZERCH_API_KEY, never both
uv run zerch mcp serve
```

Missing, blank, or multiple credentials fail before the stdio server starts.
The server never selects localhost, an in-process fallback, or a fabricated
credential. For non-hardened offline development only, use:

```bash
uv run zerch mcp serve --fixture
```

Fixture handshakes and tool outputs include `evidence_mode=fixture`; fixture
mode is rejected in hardened environments (`ZERCH_APP_ENV` or Railway
environment names `production`, `staging`, `prod`, or `candidate`).

### Stdio JSON-RPC Tool Reference

- `zerch_compile_plan`: Compiles a natural language ICP description into a search plan JSON file.
- `zerch_preview_universe`: Estimates projected counts, facets, and sample matches for a compiled plan.
- `zerch_explain_company`: Explains canonical company match signals for a domain.
- `zerch_list_universes`: Lists saved company universes in the workspace.
- `zerch_inspect_company`: Inspects a company domain, returning summary, tech stack, and vector profile metadata.
- `zerch_build_lookalike_universe`: Materializes and partitions a ranked company universe using a compiled plan or seed domains.
- `zerch_export_universe`: Quotes and creates an asynchronous export in standard or verified mode.
- `zerch_get_export_status`: Reads export job and terminal artifact status.
- `zerch_download_export`: Downloads a completed export artifact to a local path.
- `zerch_create_verifier`: Defines a workspace AI verifier prompt spec.
- `zerch_run_verification`: Starts verification for a saved company universe or domain list.
- `zerch_get_verification_status`: Reads verification progress and qualified results.
- `zerch_get_billing_overview`: Reads plan, API units, Verify credits, and pricing catalog metadata.
- `zerch_create_checkout_session`: Creates a hosted checkout session for a plan or Verify pack.

## Command Line Interface (`zerch` CLI)

The public wheel exposes only the paid-v1 workflow: `search`, `save`, `verify`,
`export`, `download`, and the explicit remote `mcp serve` command. Billing is
available through the authenticated API/MCP billing tools, not a local CLI
catalog or subscription command.

```bash
# 1. Compile a bounded US company search plan into plan.json
zerch search "Vertical SaaS companies with embedded payments" \
  --target-size 100 --plan-output plan.json --json

# 2. Materialize and save the planned audience; copy universe_id from JSON output
zerch save --plan plan.json --name "Payment SaaS Accounts" --json

# 3. Start AI verification with the returned universe identifier
zerch verify --source-id <universe-id> --source-type universe --json

# 4. Quote, create, and optionally wait for/download an asynchronous export
zerch export create --source-ref <universe-id> --format csv --mode standard \
  --output accounts.csv --json

# 5. Verified export: reuse a completed verification snapshot explicitly
zerch export create --source-ref <universe-id> --format csv --mode verified \
  --verification-job-id <verification-job-id> --output verified_accounts.csv --json

# 6. Download later when create was run without --output
zerch download <export-id> --output accounts.csv --json

# 7. Launch the remote stdio JSON-RPC MCP server
export ZERCH_API_BASE_URL=https://api.zerch.ai
export ZERCH_API_TOKEN="$WORKSPACE_API_TOKEN"  # or exactly one API key
zerch mcp serve
```

---

## Native API Endpoints

- `GET /v1/workspace/health`: Health check and provider readiness status.
- `POST /v1/universes`: Asynchronous universe materialization trigger.
- `GET /v1/companies/{domain}`: Company profile lookup.
- `GET /v1/companies/{domain}/explain`: Explain similarity match trace for a company.
- `POST /v1/exports`: Generate export artifact for a universe.

---

## Primary Use Cases

1. **Outbound planning**: Find target accounts that resemble a stated best-customer pattern.
2. **Segment sampling**: Pull a bounded set of matching companies (1-1,000 requested) to judge a target market before planning a campaign. Requests that cannot be filled report a shortfall rather than padding results; this is not a total addressable market count.
3. **Account prioritization**: Group companies by fit so a team can review higher-scoring accounts first.
4. **Targeted ads**: Hand off company-domain exports for downstream audience work.
5. **Competitor research**: Organize company-level research around a target market.
6. **Account planning**: Turn a shared ICP definition into a reviewable company list.
7. **Partner discovery**: Explore companies that fit a stated business pattern.
8. **Company research**: Inspect company/public evidence and fit explanations for a selected domain.
9. **Industry expansion**: Explore a new market against a stated ICP.

---

## Directives for AI Agents

1. **Authentication**: MCP requires `ZERCH_API_BASE_URL` plus exactly one of `ZERCH_API_TOKEN` (Clerk Bearer) or `ZERCH_API_KEY` (workspace API key). REST calls use the matching `Authorization: Bearer <workspace-token>` or `X-API-Key: <workspace-api-key>` header; never send both.
2. **Query strategy**: Public universe requests are bounded to 1–1,000 requested results. Preview output is an estimate and does not guarantee a particular match count.
3. **Export schema**: Exports use a checked column schema across CSV, Parquet, and JSONL. The exact fields are versioned with the API contract; no provenance or lineage fields are implied unless documented there.

## Legal and support

- Privacy: https://zerch.ai/privacy
- Terms: https://zerch.ai/terms
- Acceptable use: https://zerch.ai/acceptable-use
- Billing, cancellation, and refunds: https://zerch.ai/billing
- Account deletion: https://zerch.ai/deletion
- Support: https://zerch.ai/support · support@zerch.ai