evan-moon/firma

What's changed

A quality pass before adding more features. No big new headline functionality beyond `firma doctor` — focuses on bugs, dead code, UX gaps, and visual polish.

Bugs fixed

• Brief cache invalidation. Previously `firma add txn` followed by `firma brief` returned a stale cached brief. Cache now compares its mtime to the local DB (and WAL) and regenerates when data changes. Same fix in MCP `get_brief`.
• TTY-safe currency picker. No longer hangs / errors in non-interactive shells. Falls back to your configured default with a clear notice. Pass `--currency` to override silently.

`firma doctor` / `setup_status` MCP

One-shot setup diagnostic. Reports API key status, data counts, FX cache coverage, and prints concrete next steps:

```
firma doctor

✓ Finnhub API key set
✓ FRED API key set
✓ Display currency USD (default)
✓ Transactions 117 recorded · 4 active holdings
✓ Balance entries 1204 entries
✓ Cash flow entries 633 entries
✓ FX rate cache 9525 rows · 5 currencies · 2018-08-28 → 2026-04-17

All systems ready. Run `firma brief` for a daily snapshot.
```

The MCP equivalent (`setup_status`) returns a `next_steps` array Claude can act on without making you run anything.

Semantic color palette

New `utils/palette.ts` defines tiers (good / neutral / caution / alert) and delta polarity (up_good / up_bad / neutral). Applied per-indicator across `show macro`, `show stress`, `show regime`, and the brief's MACRO TODAY section so colors mean the same thing across commands.

Examples:

• VIX green when <15, caution 20–30, alert >30; rising VIX colored as alert (up_bad).
• Yield curve green when positive, alert when deeply inverted; rising curve = good (up_good).
• HY spread tightens green / widens alert.

MCP tool descriptions

Beefed up the 8 shortest tool descriptions (show_portfolio, show_txns, show_balance, show_flow, show_prices, add_txn, delete_txn, delete_snapshot, show_news). Each now describes WHEN to call vs alternatives, the return shape, and gotchas — Claude picks the right tool more reliably.

Empty-state UX

"No transactions found" / "No balance entries" / "No data" now point to both the Claude-led path (preferred) and the CLI fallback, plus suggest `firma doctor`.

Cleanup

• Removed dead exports (knip-clean): `getHistoricalFxRate`, `entryKrw`, `stalenessLevel`, several internal-only types, redundant Brief* re-exports.
• Removed dead imports in portfolio/balance/flow/report after Phase 2 historical-FX migration.

Upgrade

```bash
npm install -g firma-app@latest
firma doctor # see the new diagnostic in action
```