# AGENTS.md — Papa Weekly Expenses Workflow

## Workflow (weekly)

```
new-week [YYYY-MM-DD]   ← one command: fetch + decrypt + OCR + draft
  ↓ agent reviews draft, fills tables, corrects OCR
build-pdf <report.md>  ← pandoc → typst → ghostscript
commit-week <period>   ← git add + commit
```

---

## Step 1-3 — Automated via `new-week`

`new-week` does all of the following in one pass:
1. Computes period (Wed → Tue) from start date or last Wednesday
2. Creates `reports/PERIOD/receipts/` folder structure
3. Fetches all WA messages in the period window
4. Decrypts all new images (media keys from SQLite)
5. OCRs each image via Ollama VLM (`qwen3-vl:235b-cloud`)
6. Writes a pre-filled draft `.md` with:
   - Blank tables (correct structure, recurring items pre-seeded)
   - Raw WA text messages appended as a comment block
   - Raw OCR output appended as a comment block

Agent then reviews the draft, fills in the tables from the raw data, and removes the comment blocks.

---

## Report format

### File naming
`YYYY-MM-DD_YYYY-MM-DD_expenses-papa.md` / `.pdf`

### Template source
Use the **most recent completed weekly report** as the template for the next one. Start from the previous report's Markdown structure and preserve its PDF-facing formatting conventions: headings, summary tables, section order, blank-section handling, total rows, spacing, and table alignment. Only change dates, line items, category totals, receipt archive contents, and any week-specific details.

### Report structure
1. **Summary** — two tables: *Weekly costs* (opex) and *One-time costs* (capex), plus grand total
2. **1. Setup** — one-off purchases (USD)
3. **2. Groceries** — Toters Fresh + other shops (LBP); delivery & tips consolidated as one line at the bottom
4. **3. Household** — small household supplies (USD)
5. **4. Food** — restaurant & delivery orders (LBP); delivery & tips consolidated as one line; FX total row (both LBP and USD)
6. **5. Medical** — physiotherapy, nurse provision, medical supplies
7. **6. Cleaning** — housecleaner (hourly)

### Table format
All breakdown tables use:
```
| # | Date | Description | Amount (LBP) | Amount (USD) |
```
- Fill **LBP only** for items priced in LBP
- Fill **USD only** for items priced in USD
- Fill **both** only when doing explicit FX conversion (e.g. section totals)
- Items numbered sequentially within each section
- Sorted by date ascending; undated items (`—`) at the bottom
- Delivery & tips consolidated into a single line per section

### Currency & FX
- Lebanese pound rate: **~89,500 LBP/USD** (verify against latest receipts)
- Food section total row: fill both columns (LBP sum + USD equivalent)

### Recurring known rates
| Item | Rate |
|------|------|
| Live-in nurse | $60 / 24h |
| Housecleaner | $5 / hour |
| Physiotherapy | $40 / 45-min session |

### Categorisation rules
- Groceries: food items, cleaning supplies, personal care, medical consumables (underpads, etc.)
- Household: non-consumable small hardware/tools
- Medical: physio sessions, nurse (mark nurse as *provision* if not yet invoiced)
- Cleaning: housecleaner sessions (log hours × rate)
- Setup (capex): equipment, furniture, one-off installations

---

## Step 4 — Generate PDF

Use the same PDF renderer/template as the previous completed report: **pandoc Markdown → HTML with `pdf-template.css` → HeadlessChrome print-to-PDF → ghostscript compress**.

```bash
# <REPORT> is the path without extension, e.g.
# reports/YYYY-MM-DD_YYYY-MM-DD/YYYY-MM-DD_YYYY-MM-DD_expenses-papa

tmpdir="${TMPDIR:-/tmp}/papa-pdf"; mkdir -p "$tmpdir"
HTML="$tmpdir/$(basename <REPORT>).html"
RAW="<REPORT>.raw.pdf"
OUT="<REPORT>.pdf"
CHROMIUM="$(find /nix/store -maxdepth 3 -type f -path '*/chromium-*/bin/chromium' | sort | tail -1)"

nix run nixpkgs#pandoc -- \
  "<REPORT>.md" \
  --standalone \
  --embed-resources \
  --css=/home/mnm/workspaces/papa/pdf-template.css \
  -o "$HTML"

"$CHROMIUM" \
  --headless=new \
  --no-sandbox \
  --print-to-pdf="$RAW" \
  --print-to-pdf-no-header \
  --no-pdf-header-footer \
  "file://$HTML"

gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/ebook \
  -dNOPAUSE -dQUIET -dBATCH \
  -sOutputFile="$OUT" "$RAW"

qpdf --linearize "$OUT" "$OUT.tmp"
mv "$OUT.tmp" "$OUT"

rm "$RAW"
```

Do **not** use a Typst-based `build-pdf`. Only run the explicit Chrome command above.
---

## Step 5 — Archive

```bash
PERIOD="YYYY-MM-DD_YYYY-MM-DD"
mkdir -p /home/mnm/workspaces/papa/reports/$PERIOD/receipts
# Move MD and PDF into reports/$PERIOD/
# Copy decrypted receipt JPGs into reports/$PERIOD/receipts/
```

---

## Notes
- The WA REST service runs on port 19283 (not the default 3000).
- The `messaging.js` helper has a bug with the `messages` action when multiple devices are logged in — use the REST API directly instead.
- Do **not** use `ollama run` with image files via stdin for large images — it hangs. Use the Ollama HTTP API with base64.
- For the Chrome/CSS PDF template, do **not** pass `--metadata title` to pandoc; omit it completely so the visible HTML title does not duplicate the H1.
- PDF template/engine: pandoc → standalone HTML using `pdf-template.css` → HeadlessChrome with `--print-to-pdf-no-header --no-pdf-header-footer` → ghostscript. Match the previous completed PDF's metadata (`Creator: HeadlessChrome`, `Title: expenses-report-papa`).