# Dashboard real-UI acceptance regression workflow

Use when stabilizing the FinanceManager Streamlit dashboard after User Mode / MVP UX regressions, especially if the task mentions real Runtime DB, alerts, navigation, FX/Cash, Equity/ETF interaction, cleanup, no-live-render, or final push verification.

## Proven workflow

1. **Preflight and runtime sanity**
   - Check git branch/status and last commit before editing.
   - Verify the runtime DB exists outside the repo.
   - Start Streamlit against the runtime DB and open at least the core User Mode pages with browser tools.
   - Treat browser JS errors as blockers; chart warnings may be non-blocking if rendering still works.

2. **Regression tests first**
   - Add a focused acceptance test module that uses the existing synthetic DB helpers/FakeStreamlit patterns.
   - Cover class-level regressions, not one-off values:
     - Alert buttons have unique Streamlit keys even with duplicate rule/entity/message cards.
     - User Mode hides raw IDs/provider internals; Admin Mode may expose tables/debug data.
     - Navigation exposes only useful User pages; Review/Debug remains Admin-only.
     - Equity/ETF page renders summary cards, grouped views, selection, details, actions, and history without live provider calls.
     - Position-add/Cash/FX flows explain cache/provider/manual/missing FX states in user language and only write on explicit action.
     - Crypto detail exposes a minimal CoinGecko link without leaking raw `coingecko_id`.
     - Runtime cleanup has dry-run/apply separation, backup/audit, and preserves real manually entered positions.
   - Run the focused tests to establish RED/GREEN evidence; then run the full suite before commit.

3. **Implementation guardrails**
   - Dashboard render functions must be local-read/cache-first. Provider/API calls belong behind explicit buttons/CLI/schedule.
   - User Mode should show polished cards, labels, actions and inline forms; avoid raw tables, IDs, source IDs, rule IDs, provider internals and fake buttons.
   - Any write path must respect Read-only/Edit Mode and create audit trail where data changes.
   - Runtime cleanup must be manifest/dry-run based, backed up, auditable, and never delete productive user-entered positions by broad name/source heuristics.
   - Keep account/instrument IDs available internally if needed for actions, but hide them through `visible_user_columns` and User Mode render filters.

4. **Runtime cleanup pattern**
   - Use `jarvis_finance.runtime.backup.backup_runtime_db(...)` and `verify_backup(...)` directly when CLI output is too terse.
   - Report only backup path/checksum status and aggregate cleanup counts.
   - Dry-run first; apply only if the manifest is specific and safe. Record an audit event even when zero rows match so the cleanup decision is traceable.

5. **Verification and push**
   - Run `python -m compileall -q src tests`, `pytest -q`, and `git diff --check`.
   - Re-open the Streamlit app against the runtime DB after fixes and exercise core User pages.
   - If `git push origin main` cannot authenticate in non-interactive mode, use the approved tokenized-remote pattern from `references/github-token-push-from-drive.md` without printing secrets, then verify remote hash with `git ls-remote`.
   - Update local `origin/main` only after remote hash equals local HEAD.

## Pitfalls

- Do not claim RED if tests were added after the implementation and never failed; label it as regression coverage if strict RED evidence is unavailable.
- Do not let Streamlit Fake objects break because `session_state` is a method/function in older test doubles; guard with `hasattr(session_state, "get")`.
- Do not expose `account_id` just because action internals need it; include it in hidden-column filters.
- Do not add new providers/features while acceptance-mode UX, tests, cleanup, and push verification are unfinished.