# User Guide — Cash Recovery Engine

This guide walks a finance or revenue-operations user from zero to a prioritized
collections worklist in a few minutes.

## 1. The 30-second mental model

You have overdue invoices and limited collector time. Every invoice falls into
one of four buckets:

| Segment | Meaning | What to do |
| --- | --- | --- |
| **Persuadable** | A call meaningfully raises the chance it pays | Work it first — this is where hours convert to cash |
| **Self-Cure** | Will likely pay on its own | Send an automated reminder; don't spend a collector on it |
| **At-Risk** | Shaky, and not very responsive to a call | Structured follow-up / payment plan |
| **Critical** | Low chance to pay and low movability | Escalate (senior collector, dispute, credit hold) |

The engine's whole job is to find the **Persuadable** invoices with the highest
cash-per-hour and put them at the top of the queue.

## 2. Run the demo

```bash
node run.mjs
```

This trains the engine on resolved history, scores a live demo ledger of 900
open invoices ($19.0M), and writes three deliverables to `reports/`:

- `collections-worklist.csv` — the ranked worklist (open in Excel/Sheets).
- `executive-summary.md` — a one-page summary for leadership.
- `engine-output.json` — the full structured result for downstream systems.

The demo packs an 80-hour budget (≈ two collectors for a week) and projects
**$0.52M of cash accelerated from just 61 invoices** — see the generated
`reports/executive-summary.md` for the live figures.

## 3. Use the live tool

Open `public/tool.html` in any browser.

- **Capacity dial** — set the collector-hours you have this period. The worklist
  and every KPI re-optimize instantly.
- **KPI cards** — projected cash accelerated, lift vs. FIFO at equal hours,
  invoices on the worklist, and total open AR.
- **Recovery curve** — cumulative cash recovered as the budget grows, for the
  engine vs. FIFO vs. largest-balance vs. random. The gap above the grey lines
  is the cash a conventional worklist leaves on the table.
- **Where the hours go** — the recovery opportunity by segment.
- **Download worklist (CSV)** — exports exactly the queue shown, for the
  capacity you dialed in.

## 4. Read the worklist

Each row carries the numbers a collector and a controller both need:

| Column | Meaning |
| --- | --- |
| `recovery_segment` | Persuadable / Self-Cure / At-Risk / Critical |
| `self_cure_prob` | Probability it pays within the horizon with no action |
| `uplift` | Extra probability of payment if a collector works it |
| `expected_incremental_cash_usd` | amount × uplift |
| `value_per_hour_usd` | expected incremental cash ÷ estimated effort |
| `recommended_action` | The play for this segment |

The queue is sorted by `value_per_hour_usd` — the engine's ranking key.

## 5. Bring your own data

When you have a real AR export, place two files under `data/official/`
(schema in `run-deploy-instructions.md`) and run `node verify.mjs`. The same
checks then evaluate your data, and `node run.mjs` can be pointed at it to
produce a live worklist. Until you do, treat every figure as a benchmark
demonstration, not a recovery promise for your books.

## 6. What the numbers mean (and don't)

The verified metrics (AUC 0.817, calibration ECE 0.018, +127% cash vs. the
strongest simple baseline, 2.94× FIFO) describe the engine's behaviour on the
synthetic benchmark. They are not a recovery figure for your company; that
requires your data and a holdout or A/B validation. See
[`proof/LIMITATIONS.md`](proof/LIMITATIONS.md).
