/merit-documents

name: merit-documents
version: 1.0.0
description: >
  Keep every Merit Aktiva transaction backed by its source document (receipt / supplier
  invoice). Audits Merit for invoices missing an attachment, searches configured sources
  (local folders, or Gmail/Drive/etc. via a command adapter) for the matching PDF, stages
  or attaches it, and reports what it cannot find to a Slack-compatible webhook. Runs on a
  schedule. Use when: "missing receipts", "which invoices have no document", "attach
  receipts", "receipt audit", "documents without invoices", "find missing invoices",
  "auto-attach receipts", "receipt reminder", "document compliance".
  TRIGGERS: "missing receipt", "missing invoice", "no attachment", "receipt audit",
  "document sync", "attach receipt", "which transactions lack a receipt", "unattached
  invoice", "receipt reminder", "merit documents".

Merit document sync

Every transaction needs its original receipt/invoice for accounting. This skill finds the ones that don't have it, tries to locate the file, and flags the rest.

Full design + config: `docs/document-sync.md`.

Audit (read-only)

List invoices with no attached document. Purchases by default (an expense with no receipt is the real gap); `--sales` also checks issued invoices.

elnora-merit documents list-missing --from 2026-01-01 --to 2026-07-31
elnora-merit documents list-missing --sales

Output: `{ count, missing: [{ kind, id, billNo, partyName, docDate, grossTotal, currency, paid }] }`. The signal is Merit's own `FileExists` flag on each invoice header.

Find + resolve

elnora-merit documents run                 # audit → search → match → digest (READ-ONLY)
elnora-merit documents run --apply         # also stage matched PDFs for a UI upload
elnora-merit documents run --apply --rebook        # attach in place (delete+recreate; unpaid)
elnora-merit documents run --apply --rebook --force  # also paid (drops payment link — re-book it)

**Matching** scores each candidate PDF on amount (0.5) + date (0.3) + party name (0.2); ≥0.9 auto-resolves, 0.6–0.9 is reported to confirm by hand.

**Attach limit:** Merit's API only accepts a file at invoice *creation* time — there is no attach-to-existing endpoint. So `run --apply` defaults to **staging** (copy the PDF to a folder, named by invoice, for a 2-second drag into the Merit UI). `--rebook` delete+recreates instead; avoid it on paid invoices unless you will re-book the payment. Best practice: attach the receipt in the same `purchase-invoices create` call for new bills.

Sources (local + Gmail/Drive/anything)

Configure in `~/.config/elnora-merit/docsync.json` (see `docsync.example.json`):

• `{ "type": "dir", "path": "~/Downloads" }` — scan a local folder for PDFs and image receipts (`.jpg`/`.png`/`.heic`/`.webp`/…).
• `{ "type": "command", "command": "…" }` — run your own fetcher for Gmail/Drive/scanner;

it writes files locally and prints one JSON line per candidate (`{"path":"…","amounts":[…],"dates":[…],"text":"…"}`). No provider SDK or secret lives in this package.

Reporting

Digest goes to `MERIT_DOCSYNC_WEBHOOK` (Slack-compatible incoming webhook), or a `notifyCommand` (stdin), or is printed. Never commit the webhook URL.

Schedule

elnora-merit documents install-schedule --interval-hours 6
launchctl load ~/Library/LaunchAgents/com.merit-aktiva.docsync.plist

Interval-based (not a fixed clock time), plus at-login, so a laptop that is closed at any given moment still catches up on next wake, and it follows the machine's timezone. Remove with `documents uninstall-schedule`. Non-macOS: the command prints a cron snippet.