# MVP Crypto Manual Management UI

Session learning from implementing the manual Crypto Manage dashboard block after the productive safe-subset crypto initial snapshot.

## Trigger

Use this reference when adding or reviewing dashboard features that let the user manually add, correct, or remove crypto holdings after an initial snapshot.

## Required pattern

- Do not mutate `crypto_holdings` silently from the UI.
- Model manual changes as one of:
  - `initial_snapshot_addition` for a missing initial holding, only if the wallet+asset holding does not already exist.
  - `manual_adjustment` transaction/event for corrections, reductions, and zeroing out a balance.
  - future dedicated `crypto_buy`/sell/transfer workflows when ledger/cash integration is present.
- Always require explicit confirmation before writing.
- Require a non-empty note for `manual_adjustment` and all removal/reduction flows.
- Write an audit-log entry for every confirmed change, including `old_values` and `new_values` for corrections.
- Preserve history; zeroing a holding is a transaction/adjustment, not a row delete.
- Calculate holdings from initial snapshots plus crypto transactions, including `manual_adjustment` deltas.
- Keep quantities as exact `Decimal` strings/TEXT. Never parse through float; format writes with `format(decimal, "f")`.
- Block negative resulting wallet balances.

## CoinGecko/manual mapping rules

- Symbol alone is never automatically unique.
- Let the user manually supply/select CoinGecko ID, but allow saving without one only with a warning/quality alert.
- Missing or uncertain CoinGecko mapping should create a data-quality alert.
- Dashboard render must not perform live CoinGecko/API search. Prepare later cache/provider-backed search separately.

## UI safety checklist

- Show a review summary before save.
- Save only after explicit confirmation checkbox/button.
- No batch/mass updates without a separate review workflow.
- Clear validation errors: wallet required, coin name required, symbol required, date required, quantity > 0 for additions/reductions, new quantity >= 0 for corrections.
- After successful save, show only IDs/status/warnings or refreshed local read-model; avoid echoing real quantities/values into chat/logs.
- Provide a dashboard-visible manual-review/reminder list for skipped/unsafe coins, but do not auto-import them.

## Test checklist

- Add initial snapshot addition.
- Add coin with CoinGecko ID.
- Add coin without CoinGecko ID creates warning/alert.
- Decimal precision such as `0.00000001` remains exact text.
- Manual adjustment with note succeeds.
- Manual adjustment without note fails.
- Reduce/zero holding preserves row/history rather than deleting.
- Negative resulting holding is rejected.
- Every confirmed change has audit log.
- Corrections record `old_values` and `new_values`.
- Dashboard modules import/render without live API calls.
- Compile, full pytest, Git-safety, git status before commit/push.