evan-moon/firma

What's changed

v0.9 cached historical FX rates from FRED. v0.10 actually uses them.

Historical FX in every display layer

Every `show` and `report` command that converts to a non-USD display currency now uses the FX rate from the entry's own date — not today's rate.

```
firma show balance --currency KRW 2018-12
```

```
ASSETS
cash ₩263,421
overseas_stock ₩9,436,514
LIABILITIES
...
─────────────────────
Assets ₩9,699,630
Liabilities ₩0
Net Worth ₩9,699,630

FX @ 2018-12-28: 1 USD = 1114.9000 KRW (from 2018-12-28)
```

The footer makes the conversion auditable. Compare with the same balance shown for 2026-03 — it uses 2026-03's rate (₩1,523.50/USD), not today's.

This affects:

• `show balance --currency ` — per-entry historical conversion
• `show flow --currency ` — same
• `report` (combined, balance, flow, settle) — per-period aggregations use that period's rate. Time series no longer distorts under FX moves.
• `show portfolio` Net Worth Breakdown — historical FX. Portfolio MV stays on live FX (it's "right now" value), so the two lines now have distinct semantics with a clear label.

The general rule: anything tagged with a date uses historical. Anything representing "current value as of now" (Portfolio MV, brief MACRO TODAY, FX impact since yesterday) stays on live rates.

Inspect the cache

• CLI: `firma show fx` (coverage summary) · `firma show fx KRW` (recent rates) · `--from` / `--to` for ranges
• MCP: `show_fx_history({ currency?, from?, to?, limit? })` — Claude can audit the cache or pull a series directly

Internals

• `@firma/db` FxRepository gains `getRange` + `getCoverage`
• New `utils/historical-fx.ts`: `storedToUsdAtDate` + `usdToDisplayAtDate` helpers (both fall back to live rates if the cache misses a date)
• `formatCurrencyValue` extracted from `fmtAmount` for callers that already have a value in the target currency

Upgrade

```bash
npm install -g firma-app@latest
firma sync # populates the FX cache if you haven't already
```