first implementation

README.md

@@ -12,9 +12,9 @@ Runs in configurable batches, on a schedule, and is incremental — re-runs proc
 
 ```bash
 python -m venv .venv && source .venv/bin/activate
-pip install -r requirements.txt
-playwright install chromium        # for the browser-agent tier
-cp .env.example .env               # fill keys as available
+uv pip install -r requirements.txt   # uv resolves pydantic deps reliably; pip also works
+playwright install chromium           # for the browser-agent tier
+cp .env.example .env                  # fill keys as available
 ```
 
 ## Run
@@ -66,9 +66,39 @@ crontab (`crontab -e`), adjusting the path to your repo:
 ## Tests
 
 ```bash
-pytest -q
+.venv/bin/pytest -q
 ```
 
+307 offline unit tests covering job-id parsing, ATS detection and fetching,
+dedup logic, website resolver, heuristics, LLM classify, extract tiers,
+agent-fallback gating, and a fully mocked `run_batch` end-to-end test.
+
+## Validate
+
+`validate.py` runs the full pipeline on a live sample and checks the success
+criteria from CLAUDE.md:
+
+```bash
+.venv/bin/python validate.py                          # default: 5 jobs, "software engineer"
+.venv/bin/python validate.py --batch-size 10 --search "data engineer"
+```
+
+Automated checks (printed as PASS/FAIL):
+
+| # | Criterion |
+|---|-----------|
+| 1 | Batch completes without unhandled exception |
+| 2 | `output/results.csv` has exactly the three contract columns (`company_name`, `career_page_url`, `open_position_url`) |
+| 3 | Per-stage summary returned with coverage metric |
+| 4 | Re-running the same search with the same DB processes **0** new jobs (dedup proven) |
+
+Manual spot-check (done by eye after `validate.py` passes):
+
+- Open `output/results.csv`.
+- Pick one complete row (`open_position_url` non-empty).
+- Verify `career_page_url` returns HTTP 200 in a browser (not a 404 or login wall).
+- Verify `open_position_url` returns HTTP 200 in a browser.
+
 ## Output
 
 `output/results.csv` — three columns: `company_name`, `career_page_url`, `open_position_url`.