Mail Invoice Archiver

Quick Start

• In the first session after installation, ask the user which credential storage mode they want before doing anything else.
• Run python3 {baseDir}/scripts/cli.py providers --json when you need to show the currently supported mailbox providers and their setup notes.
• Run python3 {baseDir}/scripts/cli.py doctor --json first. If it returns setup_required: true, guide the user through setup and wait for confirmation.
• Use python3 {baseDir}/scripts/cli.py setup for an interactive setup wizard, or pass --mail-provider 126|163|gmail|custom plus --provider system|env|config|prompt for scripted setup.
• Use python3 {baseDir}/scripts/cli.py sync --month YYYY-MM --json to pull a month into the local archive.
• Use python3 {baseDir}/scripts/cli.py report --month YYYY-MM --json to inspect totals, duplicates, conflicts, and failures.
• Use python3 {baseDir}/scripts/cli.py deliver --month YYYY-MM --json to prepare a zip plus summary for the current chat.

Workflow

1. Run doctor.
2. If doctor reports setup_required, ask the user which mailbox provider they want first: 126, 163, gmail, or custom.
3. Ask the user which auth mode they want: system credential store, environment variables, config file, or prompt-each-session.
4. Run setup with the chosen mailbox provider and auth mode, then wait for the user to confirm they completed any external steps, such as exporting environment variables.
5. Run doctor again to confirm the setup works.
6. Run list --month YYYY-MM --limit 20 --json when you need a quick mailbox preview without downloading files.
7. Run sync --month YYYY-MM --json to archive candidate invoices into ~/Documents/invoice-archive/YYYY-MM/.
8. Run report --month YYYY-MM --json after sync and summarize: total amount, canonical invoice count, high-value invoices, duplicates, conflicts, and failures.
9. Run deliver --month YYYY-MM --json, then attach the returned zip file in the current chat and paste the summary.

Windows Env Setup

• If the user chooses env on Windows, offer one of these exact snippets and wait for confirmation before rerunning doctor.

$env:MAIL_INVOICE_ARCHIVER_EMAIL = "[email protected]"
$env:MAIL_INVOICE_ARCHIVER_AUTH_CODE = "your-provider-secret"
python "{baseDir}/scripts/cli.py" doctor --json

set [email protected]
set MAIL_INVOICE_ARCHIVER_AUTH_CODE=your-provider-secret
python "{baseDir}\scripts\cli.py" doctor --json

• For Gmail, MAIL_INVOICE_ARCHIVER_AUTH_CODE must be a Gmail app password, not the normal Google account password.

Rules