evan-moon/firma

What's changed

A foundation release. The display layer was always using today's FX rate to convert historical balance/flow amounts — so "what was my KRW net worth in 2018?" returned the wrong answer. v0.9 lays the groundwork to fix this by caching historical FX rates from FRED locally.

Phase 1 — Infrastructure (this release)

New fx_rates table in your local SQLite DB:

• (date, currency, rate_to_usd) with composite PK
• Uniform direction: foreign per 1 USD
• 5 currencies: KRW, JPY, EUR, CNY, GBP (USD is implicit 1.0)

Backfill from FRED:

• On first run, fetches from your earliest transaction/balance/flow date through today
• ~5 FRED API calls (~10 seconds for full backfill)
• Subsequent runs: increment-only, sub-second

CLI:

• `firma sync` (default) now syncs prices + FX rate history together
• `firma sync fx` for FX-only refresh

MCP:

• `sync_fx_rates` — backfill trigger
• `get_fx_rate({ date, currency, lookback_days })` — Claude can look up any historical rate. USD always returns 1.0. Falls back to the most recent cached rate within the lookback window if the exact date isn't available (handles weekends and holidays).

What's NOT in this release (Phase 2 — coming next)

The display layers (`show balance`, `show flow`, `report`) still use the live FX rate for non-USD display. The infrastructure is in place but the integration is the next step. v0.9 ships the foundation so users can populate their cache; v0.10 will switch the display to use historical rates.

Upgrade

```bash
npm install -g firma-app@latest
firma sync # populates the FX cache for the first time
```