# Gmail inbox-scan setup (5 min)

`scripts/inbox_scan.py` reads CVs out of your Gmail inbox and turns them
into the same candidate JSON shape the web-search flow produces. Same
scorer, same dashboard.

It uses **read-only** Gmail scope (`gmail.readonly`). The script never
sends mail or modifies anything.

---

## What you need to do once (Google Cloud Console)

I can't grant Gmail access for you — Google has to do that, signed in as
you. These steps take ~5 minutes and only need to happen once per
machine.

1. Go to <https://console.cloud.google.com/> and create a new project
   (e.g. `cvfast-local`).
2. **APIs & Services → Library** → search **Gmail API** → **Enable**.
3. **APIs & Services → OAuth consent screen**:
   - User type: **External**
   - App name: `CVfast Local`, support email: your address
   - Scopes: add `https://www.googleapis.com/auth/gmail.readonly`
   - Test users: add your own Gmail address
4. **APIs & Services → Credentials → + Create Credentials → OAuth client ID**:
   - Application type: **Desktop app**
   - Name: `cvfast-local`
   - Click **Create**, then **Download JSON**.
5. Save the downloaded file as **`gmail-credentials.json`** in the
   `eatcookjoy-recruiter/` folder. (`.gitignore` already excludes it.)

## First-time auth on your laptop

```bash
cd eatcookjoy-recruiter
source .venv/bin/activate
pip install -r requirements.txt        # picks up gmail libs
python scripts/inbox_scan.py auth      # opens browser, sign in, approve
# → writes gmail-token.json (also gitignored)
```

The token auto-refreshes thereafter. Delete `gmail-token.json` to revoke
locally and re-auth.

## Running a scan

```bash
# default: derives a query from the brief role title + last 180 days
make inbox-scan

# or full control:
python scripts/inbox_scan.py briefs/eatcookjoy-uae-chef.yaml \
    --query 'subject:(cv OR resume OR application) has:attachment newer_than:120d' \
    --max 100
```

It produces `candidates/inbox-run-NN.json`. Then:

```bash
make score CANDIDATES=candidates/inbox-run-01.json
make outreach
make serve
```

## What it does, step by step

1. Searches Gmail with your query (read-only).
2. For each match, downloads PDF / DOCX / DOC / TXT attachments.
3. Extracts text (`pypdf` for PDF, `python-docx` for DOCX).
4. Sends the text + the brief to Claude (`claude-opus-4-7`), asks for the
   structured candidate JSON shape.
5. Writes `candidates/inbox-run-NN.json`.

## Privacy notes

- `gmail-credentials.json` and `gmail-token.json` are both gitignored.
  They never leave your machine.
- CV text gets sent to the Anthropic API for extraction. If you don't
  want that, run `scripts/inbox_scan.py --query '...' --dry-run` (TODO)
  or write a regex-only extractor — the rest of the pipeline doesn't
  care which extractor produced the JSON.
- The script uses **read-only** Gmail scope. It cannot send, label,
  archive or delete anything.

## Revoking access

- Per machine: delete `gmail-token.json`.
- Globally: <https://myaccount.google.com/permissions> → find **CVfast
  Local** → Remove access.