record-management

name	record-management
description	How to save, load, and manage tax filing records. Covers directory structure, summary.json schema, screenshot conventions, and annual totals. Used by agents that need to persist or read operation results.

Record Management

Directory Structure

.user/records/
├── YYYY/
│   ├── MM/
│   │   └── YYYY-MM-DD/
│   │       ├── summary.json      ← Operation data
│   │       ├── screenshots/      ← Evidence captures
│   │       └── pdfs/             ← Invoices and receipts
│   ├── IRP/
│   │   └── YYYY-MM-DD/           ← Annual IRP records
│   ├── health/
│   │   └── YYYY-MM-DD/           ← Health check reports
│   ├── profile/
│   │   └── latest.json           ← Latest profile scrape
│   └── communications/
│       └── latest.json           ← Latest communications check

summary.json Schema

See src/record.ts for the full TypeScript interface (TaxRecord).

Key fields:

• date: ISO date of operation (YYYY-MM-DD)
• period: Fiscal period (YYYY-MM)
• type: "monthly" or "annual"
• gs_amount: Amount in guaranies (REQUIRED)
• invoice: Invoice details (number, timbrado, date, status)
• iva: IVA declaration details (form, amount_exempt, status)
• irp: IRP details (for annual records)

Screenshot Naming Convention

Number screenshots sequentially with descriptive names:

01-bcp-exchange-rate.png
02-marangatu-login.png
03-invoice-form-before.png
04-invoice-form-filled.png
05-invoice-confirmation.png
06-iva-form-before.png
07-iva-form-filled.png
08-iva-confirmation.png

After EVERY Operation

1. Save summary.json to .user/records/YYYY/MM/YYYY-MM-DD/
2. Download invoice PDF to .user/facturas/
3. Save screenshots to .user/records/YYYY/MM/YYYY-MM-DD/screenshots/
4. Update .user/memory/MEMORY.md with the new declaration state

Helper Scripts

Script	Purpose
npm run check-records	List all records with totals per year
npm run irp-calc	Calculate annual IRP (supports -- YEAR --json)
npm run exchange-rate	Get current BCP USD/PYG exchange rate
npm run health-check	Automated Marangatu health check

Reading Records Programmatically

The TypeScript functions in src/record.ts:

• listRecords() — all records sorted by date
• loadRecord(period) — latest record for a YYYY-MM period
• getAnnualTotal(year) — sum of Gs amounts for a year (excludes annulled)
• getAnnualRecords(year) — all valid records for a year
• isAnnulled(record) — check if invoice was cancelled