invoices

name	Invoices
description	Capture, extract, and organize received invoices with automatic OCR, provider detection, and searchable archive.

Trigger

Use when user receives invoices (email, photo, PDF) and wants them organized automatically.

Key difference: This skill MANAGES received invoices. The invoice skill CREATES invoices to send.

---

Storage

~/invoices/
├── inbox/                    # Unprocessed files awaiting extraction
├── archive/                  # Organized by year/month
│   └── 2026/
│       └── 02/
│           └── 2026-02-13_Hetzner_INV-12345_89.50.pdf
├── providers/                # Provider metadata
│   └── index.json
├── entries.json              # All invoice metadata (searchable)
└── state.json                # Processing state

---

Quick Reference

Topic	File
Capture and extraction workflow	process.md
Fields to extract	extraction.md
Search queries and reports	search.md
Legal requirements by country	legal.md

---

Process Summary

1. Capture — Receive invoice (email attachment, photo, direct PDF). Copy to inbox/.
2. Extract — OCR if needed, parse fields (provider, date, amounts, tax).
3. Validate — Check required fields, detect duplicates.
4. Organize — Rename, move to archive/YYYY/MM/, update entries.json.
5. Confirm — Show extracted data, allow corrections.

See process.md for detailed workflow.

---

Critical Rules

• Never delete originals — Keep PDFs permanently. Legal requirement (4-6 years depending on country).
• Detect duplicates — Same invoice number + provider = duplicate. Alert, don't overwrite.
• Validate tax math — Base + tax should equal total. Flag discrepancies.
• Provider normalization — "HETZNER ONLINE GMBH" = "Hetzner". Maintain provider aliases.

---

Alerts

• Invoice pending >48h in inbox
• Payment due in <7 days
• Unusual amount (>50% higher than same provider average)
• Missing expected recurring invoice