# USD Storage + Display-Currency Conversion — Implementation Plan

Date: 2026-05-16
Design: `2026-05-16-usd-storage-currency-display-design.md`
Branch: `feat/domestic-stocks`

Each task: implementer → spec review → code-quality review, TDD.
Build order: `@firma/finnhub` → `@firma/mcp` → `@evan-moon/firma`.

## Task 1 — FX cache covers HKD / INR / TWD

`FX_BY_CURRENCY` (`packages/domain/domain/src/macro/snapshot.ts`) gains
`HKD → DEXHKUS`, `INR → DEXINUS`, `TWD → DEXTAUS` (FRED, not inverted).
`apps/cli/src/utils/currency.ts`: widen `Currency`, add `CURRENCY_SYMBOL`
(HK$/₹/NT$), `CURRENCY_OPTIONS`, `FALLBACK_RATES` entries.
Verify the `sync fx` / `sync_fx_rates` backfill loop iterates the new
currencies. Tests: backfill includes the 3 new series.

## Task 2 — `add txn` (CLI) converts native → USD

`apps/cli/src/commands/add.ts`: after collecting price / cost basis /
dividend / tax in the market's native currency, convert each to USD at
the transaction `date` via `storedToUsdAtDate` (cache + live fallback).
Store `price` in USD, `currency: 'USD'`. Print the applied rate (mirror
`balance.ts`). Tests: KRW input → USD stored at trade-date rate.

## Task 3 — MCP `add_txn` / `edit_txn` / `add_txns` convert native → USD

`apps/mcp/src/tools/mutate.ts`: price params are in the market's native
currency; convert to USD at `date` before insert; store `currency:'USD'`.
Update tool descriptions. Tests: MCP parity with CLI for a KRW txn.

## Task 4 — `sync` converts Yahoo prices to USD

`packages/use-case/portfolio/src/sync.ts` `toPrice`: convert Yahoo
`currentPrice` (native, `d.currency`) to USD at sync time; store
`currency: 'USD'`. Finnhub unchanged (already USD). Tests: Yahoo KRW
snapshot → USD `prices` row.

## Task 5 — `show portfolio` renders in display currency

`apps/cli/src/commands/portfolio.ts`: holding rows, totals, sector/country
allocation convert USD → `pickDisplayCurrency` currency at the current
rate. `--json` stays USD. Confirm `buildHoldings` stays USD-canonical.
Tests: USD holdings → KRW-rendered totals.

## Task 6 — `show txns` renders in display currency

`apps/cli/src/commands/txns.ts`: convert each transaction's USD price to
the display currency at its own trade date (`usdToDisplayAtDate`).
`--json` stays USD. Tests: per-date conversion.

## Task 7 — `show snapshot`, `show dividend`, `brief` display-aware

Apply display-currency conversion to `apps/cli/src/commands/snapshot.ts`,
`dividend.ts`, and `brief` movers/values. `--json` stays USD.

## Task 8 — Parity harness + verification + design doc finalize

Extend `test/parity.test.ts` / `sync-parity.test.ts` for USD-storage
multi-market flows. Run `yarn typecheck`, `yarn build`, `npx vitest run`.
Mark the design doc Status: Implemented.
