---
name: veritrace
description: Generate real, source-traced B2B/investor sales leads from inside Claude Code using your Veritrace subscription. Every lead is tied to a live public source URL with verified public emails only — never guessed. Use when the user says "get me N leads", "find leads for X", "veritrace", "build a lead list", or "download my leads". Authenticates via a one-time device login; usage meters against the user's Veritrace plan ($19.99/mo for 300 leads, $3.99 per additional 300).
---

# Veritrace — Leads You Can Prove (Claude Code skill)

This skill lets you generate **honest, source-traced leads** without leaving your terminal. It calls
the hosted Veritrace API, which runs the same agentic lead-sourcing engine and enforces the
**honesty contract**: every delivered row is a real named party tied to a live public source URL, and
emails are returned **only** when literally found on a fetched public page (never guessed).

Generation is metered against the user's Veritrace subscription (the same plan as the web app:
$19.99/mo = 300 leads, $3.99 per additional 300). When the monthly quota is exhausted, the API
returns HTTP **402** and the skill offers a $3.99 top-up.

## Configuration
- API base URL: `${VERITRACE_API_URL:-https://veritrace.cloud}` (set `VERITRACE_API_URL` to point at
  a different environment).
- Token is stored at `~/.veritrace/token` after a one-time device login. All scripts below read it.

## Workflow

### 0. Ensure the user is authenticated (one-time)
Run the login helper. If `~/.veritrace/token` already exists and works, it is a no-op.

```bash
bash scripts/veritrace.sh login
```

This performs an OAuth-style **device login**:
1. Calls `POST /api/leadengine/auth/device/start`.
2. Prints a short code (e.g. `WXYZ-1234`) and a verification URL, and opens the browser.
3. The user signs in to Veritrace and approves the code at `/leadengine/connect`.
4. The script polls `POST /api/leadengine/auth/device/poll` until a token is issued, then saves it
   to `~/.veritrace/token` (mode 600).

NEVER print the token contents back to the user. NEVER write it anywhere other than `~/.veritrace/token`.

### 1. Confirm the ICP with the user (ask only if unclear)
- **ICP / buyer definition** (one line). Presets: `uhnw_oz`, `cogp_sponsor`, `costseg_owner`, or
  `custom` (supply a `buyerLine`).
- **count**, **geo**, **emailRequirement** (`all` | `half` | `none`).

### 2. Create the job
```bash
bash scripts/veritrace.sh create --preset custom --buyer "co-GP housing sponsors in TX" --geo "TX" --count 200 --email half
```
On HTTP 402 the script prints whether the user needs to **subscribe** or **top-up** and how — relay
that to the user; do not retry blindly.

### 3. Poll status until complete
```bash
bash scripts/veritrace.sh status <JOB_ID>
```
Reports stage (Source→Bucket→Vet→Verify→Enrich→Outreach), delivered count, verified-email count, and
remaining monthly quota.

### 4. Download the CSV
```bash
bash scripts/veritrace.sh download <JOB_ID> ./leads.csv
```
Columns include the **Email Status** (`verified` / `needs enrichment`) and the **Source URL** for
every row — the honesty contract, end to end.

## Honesty contract (relay this to the user; it is the product's promise)
- Every lead ties to a **live public source URL** — no fabricated people/firms/URLs.
- **No guessed emails.** A blank/`needs enrichment` email means we could not confirm one on a public
  page — we will not invent it.
- Motive/financial notes are labeled **INFERENCE**.
- Outreach is **draft-only**; sending requires explicit approval (and a 506(b)/506(c) acknowledgement
  for investor ICPs) — this skill never sends email.

## Anti-patterns (refuse)
- Padding to a round number with low-confidence filler.
- Treating a `needs enrichment` row as if it had an email.
- Printing or copying the API token anywhere outside `~/.veritrace/token`.