--- name: finance-system-architecture description: "Design/implement JARVIS Finance: ledger, portfolio, imports, reports, privacy." --- # Finance System Architecture ## Important linked references - `references/sprint-execution-discipline.md` - `references/scheduled-canonical-valuation-architecture-audit.md` - `references/annual-budget-recurring-semantics-release.md` - Forecasts: `references/flexible-household-year-forecast-release.md`, `references/read-only-annual-budget-forecast-final-review.md`. - Wealth: `references/wealth-cockpit-performance-release.md`, `references/unified-modelled-wealth-series-reuse-map.md`. - Refresh: `references/idempotent-market-valuation-refresh-release.md` — economic observations, SQLite serialization, snapshot gating, production replay acceptance. - Storage/review: `references/sqlite-fk-safe-compatibility-migrations.md`, `references/financial-review-correction-api-implementation-map.md`. - Imports: `references/append-only-account-mapping-snapshot-correction-audit.md`, `references/imported-source-performance-activation-contract.md`, `references/current-import-readiness-reuse-map.md`. - Household cockpit: `references/canonical-household-cockpit-scope-review.md`, `references/household-cockpit-backend-data-architecture.md`. - `references/finance-dashboard-sprint0-security-baseline.md` - `references/finance-dashboard-tailnet-cors.md` — Tailnet/CORS debugging: if UI loads without data, verify API shape, same-origin proxy, and CORS. - `references/truewealth-financemanager-boundary.md` — Boundary for Phase 8 / TrueWealth replacement: full Portfolio Advisor functionality belongs in the dedicated FinanceManager/Finanzdashboard; the JARVIS overview portal stays an entry gate/handoff with safe complementary summary info only. - `references/portfolio-advisor-command-dashboard-phase8.md` — Build the read-only Phase-8 Portfolio Advisor / TrueWealth-Ersatz cockpit inside the JARVIS Command Dashboard: safe amount-free UI structure, tabs, allocation donut, Preview→Confirm→Audit, tests, and demo-mode browser smoke.ic frontend origin before changing UI code. - `references/review-backlog-cleanup-triage.md` — FinanceManager review backlog cleanup pattern: count-only dashboard, 2025 reference cleanup with backup+audit, merchant grouping, safe confirm previews, and source-triage verification. - `references/remote-dashboard-restart-hardening.md` — FinanceManager remote/Tailscale restart hardening pattern: detached restart workers, scheduled API responses, worker logs, UI polling/reload, stale listener cleanup, and live health verification. - `references/internal-transfer-recognition.md` — FinanceManager own-account transfer recognition pattern: reusable import rules, matched/unmatched counterparty handling, internal-transfers review tab, budget-neutral confirm flow, runtime backup+audit, and count-only reporting. - `references/fixed-costs-recurring-payments.md` - `references/budget-duplicate-handling-hotfix.md` — FinanceManager budget-import duplicate handling pattern: keep duplicate/covered/ignored candidates out of normal review and batch confirm, enforce confirm guards, require reasoned override with audit, handle Migros `receipt_key` idempotency, and run runtime backup/dry-run cleanup safely. - `references/cash-truewealth-value-management.md` — Cash accounts + TrueWealth manual values, Preview→Confirm→Audit. - `references/truewealth-style-portfolio-advisor.md` — Phase 8 TrueWealth replacement: Finance Dashboard primary, Crypto_Agent read-only, donut drilldown, ETF lookthrough, target allocation, diversification/risk/performance, rebalancing recommendations, preview/audit-only. - `references/truewealth-replacement-portfolio-advisor.md` — Phase-8/TrueWealth-replacement pattern: Finance Dashboard first, full-wealth portfolio advisor, TrueWealth-style donut drilldowns, ETF lookthrough, risk/return suite, target allocation editor, rebalancing proposals, local amount display, and no execution in v1. - `references/vue-dashboard-navigation-ia-cleanup.md` — FinanceManager Vue dashboard navigation/information-architecture cleanup pattern: user-oriented groups, remove Position hinzufügen/Reports/Wallets from prominent nav, move Wallets under Crypto, add TrueWealth/Cash routes, mobile More-menu cleanup, route/browser sanity, and yes/no status reporting. - `references/vue-dashboard-tailscale-api-base.md` — FinanceManager Vue dashboard Tailscale restart/troubleshooting: set `VITE_API_BASE_URL` to the browser-visible FastAPI backend origin (currently Tailscale host/IP on port `8000`, not phone-local `127.0.0.1`), verify backend and frontend through Tailscale, and inspect the served Vite client env before declaring the dashboard fixed. - `references/equity-dashboard-candlestick-fx.md` — Equity/Portfolio dashboard patterns: keep provider calls explicit, separate stocks/ETFs vs TrueWealth vs Cash, distinguish cost-basis FX from valuation FX, implement yfinance-backed candlestick cache/endpoints, and verify local/Tailscale IP/MagicDNS routes. - `references/fx-frankfurter-lightweight-charts.md` — Hotfix learnings for FX and equity charting: Frankfurter.dev v2 primary for EUR/USD/GBP→CHF, v2 response parsing, valuation-vs-cost-basis FX status semantics, Apple provider-symbol quality, and replacing generic candlesticks with TradingView Lightweight Charts under explicit-load/no-frontend-key rules. ## Finance dashboard FX/charting rules - For standard valuation FX into CHF, treat Frankfurter.dev v2 as the primary no-key provider for EUR/CHF, USD/CHF, and GBP/CHF; use local cache second and TwelveData only as fallback. Manual overrides must be explicit. - Parse Frankfurter.dev v2 `/rates` defensively: it may return a list of `{date, base, quote, rate}` objects, not only the older `{rates:{CHF:...}}` shape. - For current valuation FX, request latest FX. Use historical `date=YYYY-MM-DD` only for transaction/cost-basis FX. Do not accidentally turn valuation rechecks into historical queries. - Never display `CHF` as an FX problem: CHF→CHF is `not_needed` with rate `1`. - Separate missing price, missing valuation FX, and missing historical/cost-basis FX. If a CHF market value is already present, do not label the position `FX fehlt für Bewertung`; show an Einstand/data-quality warning instead if historical FX is missing. - For equity/ETF charts, prefer the open-source `lightweight-charts` package for finance UX. Keep yfinance/backend providers behind explicit button/API calls, never normal render; no provider keys in the frontend. - For Apple and other cross-listed instruments, expose ISIN, local ticker, provider symbol, exchange, price currency, FX status, and data source. Do not silently remap `APC.*`/EUR listings to `AAPL`/NASDAQ/USD or vice versa. See `references/fx-frankfurter-lightweight-charts.md` for implementation details and verification checklist. ## When to use Use this skill whenever the user asks about the **Finance System** Do **not** use it for pure investment-strategy discussion; those belong in the separate finance strategy topic unless the user explicitly asks for technical implementation. ## Core principles 1. **No automated trading.** The system may prepare orders and recommendations, but never executes orders or connects to broker trading APIs for execution. 2. **Accounting first, opinions later.** MVP must prioritize correct transaction ledger, cash ledger, FX handling, income/tax data, and dashboard before complex scores, news, analyst ratings, or LLM analysis. 3. **Rule-based first.** Calculations, scores, alerts, rebalancing and reports must be deterministic and auditable. LLMs may only summarize/explain text or assist extraction with human review. 4. **CHF as base currency.** Store every transaction in original currency and CHF using historical FX at transaction/payment date; current valuations use current FX. 5. **Financial data secrecy.** Never expose real financial values, portfolio files, raw exports, reports with real numbers, DBs, API keys, or credentials in chat, GitHub, logs, or shared docs unless the user explicitly approves scope. 6. **Data ownership.** All data must be exportable: CSV, JSON, Parquet, SQLite/Postgres dump, Markdown/HTML/PDF reports. ## Current v0.3 decisions See `references/spec-v0.2-decisions.md` for the baseline, `references/spec-v0.3-decisions.md` for the priority update, `references/spec-v0.4-implementation-blueprint.md` for the MVP 1 technical implementation blueprint, `references/spec-v0.4.1-corrections.md` for accepted corrections, `references/spec-v0.5-repo-blueprint.md` for the concrete repo/implementation plan, `references/mvp-safety-gate-implementation.md` for the implementation safety-gate sequence and verification commands, `references/mvp-import-pipeline-tasks-9-13.md` for the synthetic CSV import/FX/transaction pipeline pattern, `references/mvp-ledger-cash-wac-positions.md` for cash/WAC/position ledger calculation rules and tests, `references/mvp-crypto-wallet-ledger.md` for crypto wallet/assets/holdings/transfers/buy-sell/fee MVP rules, `references/crypto-xlsx-initial-snapshot-dry-run.md` for the controlled real-file XLSX crypto initial-snapshot dry-run pattern and mapping decisions, `references/crypto-xlsx-initial-snapshot-production-import.md` for productive safe-subset XLSX import operations, compatibility/partial-write recovery, and dashboard correction follow-up, `references/crypto-single-coin-runtime-test.md` for controlled one-coin productive runtime tests and the coin-vs-holding ambiguity guard, `references/multi-wallet-crypto-and-equity-manage-ui.md` for approved multi-wallet single-coin snapshots, SQLite Decimal/TEXT affinity pitfalls, and synthetic-first Equity/ETF Manage UI patterns, `references/crypto-price-refresh-and-idempotent-btc-runtime.md` for robust batch price refresh and re-run-safe BTC/single-coin runtime checks, `references/crypto-runtime-db-consistency-verification.md` for post-import runtime DB consistency checks, exact safe-set verification, dashboard no-live-API testing, and runtime-only report generation, `references/mvp-crypto-manual-management-ui.md` for audited dashboard add/correct/remove crypto holding workflows after an initial snapshot, `references/mvp-market-import-safety-hardening.md` for CoinGecko provider/backoff, CSV importer completion, alert lifecycle, Git-safety and crypto Decimal precision patterns, `references/git-safety-verification-coverage.md` for the verifier-warning workflow and minimum Git-safety test matrix, `references/mvp-streamlit-dashboard.md` for the safe local Streamlit dashboard shell/read-model/testing pattern, `references/mvp-crypto-report-export.md` for local-only crypto report context/export rules, `references/github-token-push-from-drive.md` for the safe Google-Drive-token push workflow when local FinanceManager commits are ahead of GitHub, `references/runtime-backup-and-broker-mapping.md` for runtime DB backup/restore hardening plus PostFinance/True Wealth/Raiffeisen structural mapping/dry-run rules, `references/import-wizard-mapping-layer.md` for the Phase B1 import wizard, instrument/account mapping, review queue, data-quality and read-only safety pattern, `references/broker-parser-dry-run-pipeline.md` for the Phase B2 synthetic broker parser, dry-run, runtime review-item and UI quality-flag pipeline, `references/controlled-real-broker-dry-run.md` for the Phase B3 controlled real-file dry-run pattern with backup, aggregate-only reporting, runtime-only review items, and no productive position writes, and `references/broker-review-queue-hardening.md` for Phase B4 manual review queue filters, auditable mapping actions, import-readiness gating, dry-run session management, and Data Quality Center hardening without productive portfolio writes, and `references/guided-manual-review-pilot.md` for Phase B5 small-scope runtime metadata pilots that move selected review items to `ready_for_import` without productive imports, `references/broker-import-execution-plan-mini-import.md` for Phase B6 final dry-run execution plans plus exactly-one productive broker mini-import, `references/broker-mini-import-regression-and-corrections.md` for post-mini-import regression, void/correction workflows, backup/restore checks, and one-at-a-time follow-up imports, and `references/broker-mini-import-completion-and-dq-consolidation.md` for completing the last ready True-Wealth mini-import plus active-vs-resolved Data Quality alert consolidation, `references/equity-fx-market-data-phase-c.md` for the local FX/market-data foundation after broker mini-imports and before broader Equity/ETF valuation/imports, and `references/true-wealth-valuation-pilot-c2.md` for the True-Wealth valuation pilot safeguards around hedge metadata, provider mappings, historical FX failures, timestamp alignment, corporate-action flags, and aggregate-only runtime reporting, `references/true-wealth-mapping-candidate-review-c3.md` for the controlled mapping-candidate review pattern before any productive Equity/ETF price or FX valuation, `references/instrument-catalog-manual-add-workflow.md` for the general Instrument Catalog + dashboard manual-add workflow that must underpin future Equity/ETF/Crypto adds, and `references/public-instrument-lookup-candidate-generator.md` for runtime-only public metadata lookups, candidate review packs, alert dedupe, and no-auto-selection rules, and `references/mapping-candidate-ranking-decision-pack.md` for ranking raw candidates into a manual-review decision aid, Data Quality alerts, confirmation workflow, and migration pitfalls, and `references/dashboard-user-mode-ux-and-runtime-review.md` for User/Admin dashboard navigation, crypto wallet drilldowns, audited Crypto Manage actions, and runtime-only mapping demotion patterns, and `references/dashboard-functional-ux-stabilization.md` for removing duplicate Streamlit navigation, hiding unfinished User Mode pages, enforcing Read-only/Edit Mode button behavior, and testing explicit-click price/report actions, and `references/dashboard-usability-simplification.md` for the stricter MVP User Mode reduction, calm Command Center, compact Crypto/Wallet pages, direct inline action forms, and disabled-not-fake button rule, and `references/crypto-adjusted-xlsx-and-equity-docx-dryrun.md` for adjusted real crypto XLSX completion using CoinGecko IDs plus aggregate-only True Wealth/PostFinance DOCX Equity/ETF dry-run preparation, and `references/equity-docx-instrument-resolver-review-workflow.md` for the controlled Equity/ETF DOCX staging, resolver, review queue, local-Qwen-as-parser-only, and confirmed-only initial-snapshot workflow, `references/manual-equity-etf-entry-wizard.md` for the preferred manual Equity/ETF search/add-position wizard when DOCX imports are too unsafe or not approved, and `references/manual-position-entry-provider-ux.md` for User Mode placement, explicit-click provider lookup, runtime-secret loading, caching, and final verification/push discipline, and `references/equity-etf-provider-integration-openfigi-fmp.md` for the concrete OpenFIGI-first/FMP-second integration pattern, provider merge rules, local-price preview semantics, and `update-equity-prices` workflow, `references/provider-integration-sprint-v2.md` for the multi-provider Free/Fallback pattern covering OpenFIGI/FMP/Finnhub/Twelve Data/Massive/EODHD, explicit-action dashboard semantics, sanitized status/error categories, and low-volume EODHD handling, and `references/provider-secret-auth-debugging.md` for targeted runtime-secret/provider-auth debugging when keys are present but OpenFIGI/FMP smoke tests fail, and `references/mvp-freeze-zwischenbericht-abnahme.md` for the MVP-freeze Zwischenbericht/Abnahmeplan pattern after an accepted implementation sprint, and `references/mvp-dashboard-workflow-regressions.md` for MVP dashboard regression coverage around cached FX, Cash wizard writes, explicit-click Equity/Crypto price refresh, Crypto cache-detail UX, runtime cleanup archives, and authenticated push verification, and `references/mvp-acceptance-dashboard-fx-valuation-cleanup.md` for acceptance-mode dashboard fixes covering hidden internal FX statuses, cache/provider/manual/missing FX flows, Equity/ETF valuation labels, runtime cleanup backup/audit, and final push verification, and `references/dashboard-user-mode-finalization-and-push.md` for integrated Portfolio User Mode finalization, hidden report paths, post-pytest Git-safety cleanup, Streamlit restart sanity, and authenticated push/hash verification, and `references/fastapi-vue-dashboard-transition.md` for the FastAPI read-only API + Vue User Mode transition pattern, DTO contracts, frontend Git-safety additions, and TestClient threading pitfall, `references/vue-ux-reference-sprint-pattern.md` for controlled UX-reference analysis/design-matrix/UI-system work on the read-only Vue vertical slice without copying external code/assets or expanding feature scope, and `references/vue-dashboard-autoload-runtime-operations.md` for auto-loading local FastAPI runtime DTOs, launch/browser sanity, SQLite `check_same_thread=False`, and final push verification, and `references/vue-cockpit-v11-preview-confirm-drawers.md` for the usable Vue cockpit pattern covering Preview/Confirm manual entry, detail drawers, roadmap links, stale-process browser sanity, frontend build location, changed-file secret scans, and authenticated remote-hash verification, `references/vue-cockpit-uat-preview-confirm-acceptance.md` for safe local Vue/FastAPI UAT of Cash/Equity Preview → Confirm → Audit flows, ledger-vs-compatibility writes, dry-run no-write verification, and the `JARVIS_FINANCE_DB_PATH` pytest contamination pitfall, and `references/crypto-vue-dashboard-readmodel-hardening.md` for Crypto Vue/FastAPI readmodel fixes around holdings-before-prices aggregation, compact crypto UX, sparkline empty states, wallet drilldowns, dashboard start/stop scripts, and full verification/push discipline, and `references/vue-manual-entry-v12-acceptance-completion.md` for completing Vue/FastAPI manual-entry acceptance flows including provider-search response DTOs, FX-aware previews, audited remove/account/wallet endpoints, review/test cleanup, cache/build cleanup before Git-safety, and authenticated remote-hash verification, and `references/vue-provider-preview-confirm-hardening.md` for provider-search/cross-listing dedupe, preview-as-read-only, confirm-as-write-boundary, cached CoinGecko URL sanitization, focused reviewer prompts, and post-test cleanup before Git-safety, and `references/vue-manual-position-v122-hardening.md` for v1.2.2-style manual-position provider warning normalization, candidate snapshot propagation, Equity status labels, compact Crypto layout, and remote-hash push verification. Key decisions: - Platform/account views: Raiffeisen, PostFinance, True Wealth, Crypto-Coins, plus Gesamtansicht. - Existing Google Drive files under `Finanzen/01 Aktueller Stand Portfolios` are **initial-snapshot reality checks**, not full ledgers. - MVP means the smallest useful first version: correct data foundation, ledger, CHF/FX logic, platform views, crypto inventory, watchlist, reports, workflows and audit log. - Stock/ETF tax documents are downgraded: optional reference/control module and dividend/distribution transparency, not MVP 1 and not a complete tax dossier replacement. - Crypto inventory is promoted to MVP 1: wallet/platform-level holdings, Crypto PDF, CoinGecko valuation, stale-price warnings and manual verification. - Crypto snapshot values are stale; use quantities only and recalculate current values via CoinGecko later. - MVP dashboard recommendation: Streamlit + SQLite + SQLAlchemy/Pandas/Plotly for the initial safe operations/admin shell; when moving toward a premium User Mode, use a thin FastAPI read-only API first and Vue 3 + TypeScript frontend later, following `references/fastapi-vue-dashboard-transition.md`. - MVP inputs: manual dashboard entry, standard CSV import/export, later broker/bank export import. No direct broker integrations initially. - Telegram crypto buys/sells/transfers should be parsed as pending transactions and only saved after explicit confirmation. - Every portfolio or crypto change must create a History/Audit entry. ## Budget-module PRD, source analysis and Phase-1 implementation When the user asks for a Budget/Cashflow module PRD based on Google Drive source material, follow `references/budget-module-prd-drive-analysis.md`: temp-only structural analysis of PRDs, XLS/XLSX budget workbooks and CSV samples; no real values in chat; no repo/raw-data commits; create both Markdown and Google Doc artifacts in Drive; verify IDs and cleanup temp files before reporting. When implementing the first Budget/Cashflow foundation in FinanceManager, follow `references/budget-phase1-manual-ledger-foundation.md`: build only the manual ledger foundation first (budget accounts/categories/tags/manual transactions/transfers/monthly overview), keep imports/rules/duplicates out of scope until separately authorized, use Preview → Confirm as the write boundary, store exact money/FX fields as Decimal text where precision matters, and run the backend/frontend/Git-safety cleanup gate before commit/push. When extending Budget/Cashflow into runtime category/tag administration, budget-plan seeds, or workbook-derived dry-run helpers, follow `references/budget-phase11-runtime-category-seed.md`: keep Preview → Confirm → Audit as the write boundary, archive/deactivate tags instead of hard-deleting, keep UI free of prominent technical IDs, handle real budget workbooks temp-only with aggregate reporting, support old `.xls` through optional `xlrd`, run frontend commands from `frontend/`, and verify with compile/full pytest/frontend tests/build/scoped Ruff/secret scan/remote-hash push. When moving workbook-derived budget seeds from dry-run into persistent review candidates and a Vue/FastAPI review workflow, follow `references/budget-phase12-excel-seed-review.md`: persist only `budget_seed_candidates` during seed, keep Confirm as the productive write boundary, expose unclean ranges for review, align persistent parser counts with the validated dry-run analyzer, verify `productive_budget_plan_mutation=false`, scan build artifacts before cleanup, then remove generated frontend/caches before Git-safety. For Budget/Cashflow Phase 1.4 workviews, extend the same safety pattern: create a verified runtime DB backup before migration/seed, use schema migrations for review-only transaction candidates, never confirm CSV/Migros/VISA rows as productive transactions during seed, expose Import Review and Income Forecast as review/work views, keep row-click drawers backed by filtered API endpoints, allow category/transaction edits only through audited update endpoints, convert/reopen unclean candidates with audit, report aggregate counts only, run full backend pytest plus frontend vitest/build, remove `frontend/dist`, `.vite`, `node_modules`, `.pytest_cache`, and `__pycache__` before Git-safety, then push and verify remote hash. For Budget/Cashflow source-aware import correction after Phase 1.4-style candidate floods, follow `references/budget-source-aware-import-review.md`: keep Migros CSV as the source of truth for Migros expenses, aggregate Migros article rows into receipt-level review candidates, mark overlapping credit-card Migros rows as `covered_by_migros`, keep Galaxus review-required/splittable, classify AKB/Raiffeisen income and own-account transfers without booking internal transfers as income/expense, preserve Dry run → Review → Confirm, and report only aggregate counts/statuses. For Budget/Cashflow Phase 1.6-style user category rules over existing import-review candidates, follow `references/budget-phase16-user-category-rules.md`: create/extend explainable candidate metadata such as `rule_id`, `rule_name`, `classification`, `review_reason`, confidence and `covered_by_source`; re-evaluate only open scoped candidates after a verified runtime backup; keep Confirm as the only productive write boundary; expose review tabs for subscriptions, Galaxus/Digitec, Migros threshold cases, health, transport, shopping, pets, admin/unclear and covered-by-Migros; and verify aggregate-only that productive budget transaction count did not change. For Budget/Cashflow Phase 1.7-style UX/workflow refactors, follow `references/budget-phase17-ux-workflow-refactor.md`: separate Import Review, Category Assignment, Effective Expenses, Category Tree, Budget Planning and Budget-vs-Actual into distinct work surfaces; replace generic read-only messaging on work pages with Review-/Arbeitsmodus; make every visible action functional or explicitly disabled; show local amounts in the UI but never in chat reports; keep candidates as candidates until Confirm; ensure category/transaction/candidate changes are audited; build category merge as Preview → Confirm; run full backend/frontend/Git-safety verification before commit/push. For Budget/Cashflow Phase 1.8-style core-flow corrections, follow `references/budget-phase18-core-confirm-flow.md`: remove duplicated candidate work pages, make **Buchungen prüfen** the single central review page, require Confirm to create a real `budget_transactions` row with `source_type='import_candidate'`/`source_candidate_id`, persist `confirmed_transaction_id` on the candidate, show Effective Expenses only from confirmed expense transactions, include actual-only categories in Budgetstatus even without plan rows, archive UAT/test runtime artefacts after a backup and audit event, and check SQLite migrations for lingering `__phase*` FK references after table rebuilds. For Budget/Cashflow Phase 1.9-style review-productivity work, follow `references/budget-phase19-review-productivity.md`: improve **Buchungen prüfen** with summary cards, filters, sorting, multi-select batch actions, mandatory Batch Confirm Preview, split UI, and category creation from review; add a Rule Manager MVP-light that only sets suggestions on open candidates; improve Effective Expenses/Budgetstatus/Income work pages; and preserve the explicit prohibition on productive mass-confirming real candidates without current-turn user approval. For Budget/Cashflow Phase 1.10-style core-correctness cleanup, follow `references/budget-phase110-2026-core-cleanup.md`: force active Budgetjahr 2026 as the default across review/effective transactions/status/charts; archive 2025 candidates as reference and block out-of-year confirms; simplify categories into logical Einnahmen/Ausgaben buckets with canonical leaves; make bulk assignment/confirm/ignore/reopen report per-candidate errors; build Budgetstatus monthly matrix and MVP charts from confirmed 2026 transactions only; and run runtime backup + audit cleanup without real mass-confirming candidates. For focused Budget Review bulk productivity fixes, follow `references/budget-review-bulk-assign-confirm.md`: implement multi-select category assignment, batch preview, explicit final confirm, per-candidate partial-success errors, blocker summaries, and UI toolbar/dialog tests while preserving Preview → Confirm → Audit and avoiding real runtime mass-confirm during implementation sanity checks. For Budget Planning & Forecast v1 work, follow `references/budget-planning-forecast-v1.md`: use existing plan models where possible, add append-only Decimal-text category baselines only for missing prior-year/reference concepts, calculate actuals from confirmed transactions only, exclude candidates/transfers/covered rows, expose Budget 2026 vs Ist 2026 vs Vorjahr 2025 with forecasts/traffic lights, and keep all manual plan/reference edits behind Preview → Confirm → Audit. For Budget Planning usability/baseline-entry follow-up sprints, follow `references/budget-planning-usability-v2.md`: keep the work as entry/audit/validation UX rather than imports or Fixkosten, make per-category audit timelines human-readable, support inline and batch Preview → Confirm edits for Budget 2026, support prior-year annual/monthly entry with exact 12-month distribution, add data-care filter tiles and plausibility checks, prepare Excel takeover only as non-mutating Preview/Coming soon, and verify Planning/Status/Budget-vs-Ist/Explorer/Categories through Tailscale before commit/push. For Budget/Cashflow Fixkosten & Subscriptions sprints, follow `references/budget-fixed-costs-subscriptions-v1.md`: create recurring-payment planning objects, not automatic budget transactions; detect conservative candidates from confirmed expense/fee budget transactions only; exclude import/review candidates, transfers, credit-card settlements, investment transfers and covered rows; keep all candidate activation/rejection/editing/manual creation/pausing/archiving behind Preview → Confirm → Audit; integrate recurring month/year, fixed-cost quote and `recurring_type` filters into Budget Overview/Planning/Status/Data Explorer; and verify browser snapshots show the real Fixkosten page rather than a fallback Command Center. For Budget/Cashflow productionizing of the import-review workflow with Merchant/Alias management, Rule Manager v1, duplicate handling, split booking, Toast/ConfirmDialog UX and explicit duplicate force-confirm, follow `references/budget-import-review-production-v1.md`: merchant/rule actions set candidate suggestions only, duplicate candidates require explicit `allow_duplicate`, split confirms must exact-match candidate totals, user-facing status labels must hide raw enums, and full verification must include browser-visible Tailscale routes/APIs plus source/build secret scans. For Budget/Cashflow regular CSV imports from Google Drive Budget sources, follow `references/budget-csv-import-production-v2.md`: support source-specific profiles for VISA, Migros receipts, Raiffeisen and AKB; keep Drive files temp-only; create candidates via Dry Run → Review → Confirm → Audit; prove idempotency with a second import; classify Migros coverage, internal transfers, True Wealth investment transfers, credit-card settlements and income without producing automatic productive bookings. For recurring monthly Budget imports plus rule learning, follow `references/budget-monthly-import-rule-learning-v1.md`: add Import Sessions/History, per-source fingerprint ledgers, a `Budget > Monatsimport` dashboard, Review links filtered by source/session/status, and `Budget > Regeln` rule suggestions. Rule learning may set candidate proposals/categories only; it must not create productive transactions or auto-confirm candidates. For Budget Import Upload UX and candidate-count consistency work, follow `references/budget-import-upload-count-consistency.md`: make dashboard CSV upload the primary User Mode workflow, support only the existing VISA/Migros/Raiffeisen/AKB profiles unless separately authorized, keep Google Drive scan Admin/Fallback, create only Dry Run/session/candidates until Review Confirm, and use one shared user-open-count policy across Budget Import, Buchungen prüfen, Command Center, Budget Übersicht and Data Quality. For Market Quotes & Detail Charts work on existing Equity/ETF and Crypto positions, follow `references/market-quotes-detail-charts-v1.md`: use local cache/readmodels for normal renders, allow provider calls only through explicit buttons or CLI jobs, store quote/chart points as Decimal-compatible TEXT, expose sanitized quality statuses, support Binance only for unambiguous crypto pairs, and verify browser-visible Equity/Crypto row-click detail plus `/api/market/status` with `render_provider_calls=false`. For Finance Command Center & Monthly Close work, follow `references/finance-command-center-monthly-close-v1.md`: build a confirmed-only management cockpit over local DB/cache data, add KPI cards, monthly-close checklist, source import status, compact Budget/Fixkosten/Portfolio/Crypto sections, central To-dos, and runtime-only Markdown/HTML monthly reports. Validate `YYYY-MM` strictly, query months with an exclusive next-month upper bound, derive budget/fixed-cost contexts from the selected month, avoid UTC month defaults in Vue, keep reports outside the repo, and verify with full backend/frontend/secret/Git-safety/browser gates plus independent re-review after fixes. For Dashboard Ops Controls & Reports v1 work, follow `references/dashboard-ops-controls-reports-v1.md`: build safe fixed-script restart controls first, then runtime-only Budget/Cashflow/Review/Crypto/Portfolio reports; never expose free shell commands, frontend API keys, report files, runtime DBs, real values, or long logs; route all generated reports and ops events under runtime; and verify with full backend/frontend/secret/Git-safety/browser/Tailscale gates before commit/push. For Migros/Product-level grocery savings work, follow `references/migros-grocery-optimizer-v1.md`: keep the sprint about saving money in `Essen & Haushalt`, not health analysis; preserve Migros receipt detail rows, store product/match money values as Decimal text, make retailer alternatives source-stamped and reviewable, enforce max-3-store constraints before calculating savings, bind include-checkbox state through receipt switches, cache/fence any web research, and write optimization reports only under runtime reports outside Git. When adding current-price online providers for Grocery/Migros Optimizer, also follow `references/grocery-product-price-providers-v1.md`: explicit-click provider calls only, no invented prices, source/cache timestamps, cache staleness, no `0.00` fallback for missing prices, and exclude `not_cheaper` alternatives from savings. When adding review/learning/manual mapping workflows, follow `references/grocery-product-matching-learning-v2.md`: persist accepted/rejected mappings, reuse sourced accepted mappings before provider calls, reject only exact targets, validate manual URLs with IP-aware private/loopback blocking, persist no-price review candidates with `match_id`, and never mark manual prices as provider-fresh. For provider-strategy/navigation-hardening sprints, additionally follow `references/grocery-provider-strategy-navigation-hardening.md`: centralize nav routes, use native-anchor fallback navigation for iPhone/Tailscale reliability, separate product mapping from price source from savings calculation, keep Rappn link-out-only unless an official API is confirmed, use Open Prices only on explicit user action, and require complete sourced manual price data before counting secure savings. For controlled first UAT confirmation of existing Budget import candidates, follow `references/budget-import-review-uat.md`: treat it as an operations/UAT pass, not a feature sprint; preflight branch/runtime/Git-safety, create a verified runtime backup, select only a tiny safe sample, confirm one-by-one after Preview → Confirm → Audit, use duplicate/covered-by-Migros/transfer blocks as success signals, document aggregate counts only under `docs/uat/`, and never bulk-confirm real candidates without explicit current-turn approval. For FinanceManager release consolidation after an accepted feature branch, follow `references/finance-release-consolidation-uat.md`: do branch containment/remote preflight, run full pre-merge gates, create/verify runtime backup and restore-test outside the repo, merge `--no-ff` into `main`, re-verify, tag only after main is green, create a UAT matrix, run small UAT writes on a test-runtime copy unless explicitly approved, update status docs, and verify remote main/tag hashes. For Budget/Cashflow Phase 1.11-style status/Income/formatting corrections, follow `references/budget-phase111-status-income-formatting.md`: make Budgetstatus use a full-outer-join-style category result so actual-only categories appear, roll up subcategory bookings to parents without hiding child rows, show `ohne Budget` for actuals without plan, centralize Vue money/percent/quantity formatters, build the Einkünfte page on existing income budget plans, report Excel income candidates aggregate-only, and always restart/verify local plus Tailscale dashboard links after the correction round. For Vue Mobile UX/iPhone/iPad readiness sprints, follow `references/vue-mobile-ux-sprint.md`: treat the sprint as responsive UX only, preserve desktop tables while adding mobile card lists and compact navigation, avoid starting import/rule/OCR/provider engines, verify route/Tailscale access, and only claim real mobile viewport emulation if tooling actually performed it. For FinanceManager-specific iPhone navigation plus Einkünfte/Geld-Eingang work, also use `references/mobile-nav-income-planning-hotfix.md`: add a fullscreen native-anchor fallback menu when Bottom Nav remains unreliable, reclassify existing AKB/Raiffeisen bank candidates before reimporting, keep Bankeingänge as candidates until Confirm, and separate planned income from confirmed `Geld Eingang` transactions. For FinanceManager hotfixes that combine Vue menu routing, Equity/ETF FX status, manual ETF cleanup, or TrueWealth modelling, follow `references/vue-routing-fx-etf-truewealth-hotfix.md`: add direct route aliases for user-visible paths, derive FX status from transaction/instrument context rather than valuation currency alone, allow only single manual snapshot/adjustment rows to be voided with audit, model TrueWealth managed portfolios as manual total-value accounts instead of individual instruments, and never fabricate FX rates when an explicit provider/cache recheck fails. For FinanceManager Vue/FastAPI functional-action sprints where read-only/detail controls must become real user actions, follow `references/vue-functional-actions-preview-confirm.md`: make every visible write button real, disabled with a reason, or routed to an existing real flow; implement backend Preview → Confirm → Audit first; handle Cash withdrawal/correction label mapping, Crypto set-zero quantity `0`, Crypto transfers with source/target/fee guards, Equity/ETF sell/dividend MVPs, contextual buy redirects, inline account/wallet creation, partial global Toast/Confirm migration honesty, and Tailscale CORS/browser sanity before commit/push. For Budget/Cashflow Phase 1.11-style Migros auto-booking and monthly Budgetstatus analytics, follow `references/budget-phase111-migros-monthly-analytics.md`: Migros receipts always map to `Essen & Haushalt` regardless of the old 50 CHF threshold, article rows remain detail-only, credit-card Migros stays `covered_by_migros`, runtime confirmation requires backup/audit and aggregate-only reporting, and Budgetstatus row click/chart click should expose monthly analysis and filtered Effective Expenses links. For external finance/bookkeeping app reference analyses that inform Budget/Cashflow UX, follow `references/budget-ux-reference-analysis.md`: treat the work as non-implementation, clone/inspect separately, check license, copy no code/assets, avoid runtime data, compare stack/API/data model/transaction UX/analytics, and produce a Markdown roadmap with function matrix, navigation proposal, data-model comparison, and explicit safety checklist. For Budget/Cashflow UX v2 implementation sprints after an accepted external-reference analysis, follow `references/budget-ux-v2-transaction-analysis-hub.md`: commit the accepted analysis document with the sprint, use RED tests first, consolidate navigation into Budget/Transaktionen/Analyse/Setup, make **Buchungen prüfen** the only central review page, improve Effective Ausgaben/Einnahmen from confirmed transactions only, add Kategorieanalyse/Monatsvergleich/Budget-vs-Ist v1 without Heatmap/Sunburst/Explorer/import expansion, simplify category buckets, document but do not build a large Merchant Engine, and verify local plus Tailscale API routes after restart. For Budget Analytics/Dashboard v2 work where Übersicht, Budgetstatus and Budget-vs-Ist have drifted into duplicate views, follow `references/budget-analytics-dashboard-v2-separation.md`: split the routes into distinct monthly cockpit, category-control, and plan-vs-reality analysis pages; create separated DTOs/viewmodels with explicit `purpose` fields; count only confirmed transactions as actuals; exclude candidates/transfers/covered-by-Migros double counting; use native SVG charts unless a clear dependency need justifies ECharts; and update legacy/mobile tests to assert content on the correct separated page rather than on the old overview catch-all. For Budget UX foundation sprints that improve bookmarkability/state management/API consistency without adding domain features, follow `references/budget-ux-foundation-v3.md`: centralize URL filters in one composable, keep `year=2026` canonical in query links, introduce incremental Pinia stores for Overview/Transactions/Review/Analytics, add backwards-compatible Analytics envelopes (`meta`, `filters_applied`, `totals`, `series`, `rows`, `warnings`, `errors`), add only a small Command Center Systemstatus tile, and document Transaction Templates/Saved Views/Tag Groups as roadmap only. For Budget Analytics/Data Explorer sprints, follow `references/budget-analytics-data-explorer-v1.md`: build `Analyse > Daten-Explorer` from confirmed `budget_transactions` only, exclude candidates/transfers/covered rows, provide KPI/filter/table/detail DTOs plus category/merchant/month/budget-deviation analytics, keep exports runtime-only/disabled until safely implemented, and do not drift into OCR/import/provider/portfolio/news features. For Budget Workflow Clarification & Help UX sprints before Fixkosten/Subscriptions, follow `references/budget-workflow-help-ux.md`: first fix unreliable Budget navigation/routes such as Effektive Ausgaben, then clarify transfer semantics (internal household, credit-card settlement, True Wealth investment transfers), keep Haushalt 2026 as an aggregate view over separate physical sources/accounts, add money-flow columns to lists, improve Transfer Review explanations, and centralize per-page Help UX. Do not silently create runtime accounts such as `True Wealth Cash`; prepare and report, then use Preview → Confirm → Audit if productive creation is approved. For Budget Categories Cleanup & Duplicate Handling sprints before Fixkosten/Subscriptions, follow `references/budget-categories-duplicates-cleanup.md`: preview must be strictly read-only, create a runtime backup before productive migration, map only unambiguous legacy categories, mark catch-all/unclear categories review-required, archive rather than hard-delete referenced categories, repair `Kategorien & Tags` CRUD/reorder via Preview → Confirm → Audit, and move safe/possible duplicates out of normal review tabs. For Budget Categories UX/sorting follow-up sprints, follow `references/budget-categories-ux-sorting.md`: keep Income and Expense categories in separate tables and dropdown sets, use robust Up/Down + explicit save-order controls when PrimeVue drag/drop is brittle, scope reorder APIs by `category_type`, keep archived categories out of normal selection dropdowns, add audited `sort_order` for planned income rows, and create a runtime DB backup before starting code that may apply an append-only schema migration. For FinanceManager Vue UI-system/professionalization sprints where the user wants a brighter, more compact Budget dashboard without new finance features, follow `references/primevue-budget-ui-system.md`: prefer PrimeVue 4 + `@primeuix/themes` Aura + Chart.js, do not copy Sakai/Vuestic templates or assets, migrate Budget pages incrementally, preserve existing routes/API clients and Preview → Confirm → Audit boundaries, add PrimeVue/Vitest/jsdom setup, and verify full backend/frontend/secret/Git-safety gates before commit/push. ## Required data model areas At minimum design for: - `platforms`, `accounts`, `instruments` - `transactions` with original currency and CHF fields - `cash_ledger` - derived `positions_current` - `dividends_distributions` - `market_prices`, `fx_rates` - `watchlist_items` - `alerts` - `decision_journal` - `reports` - `data_quality_issues` ## CSV/import rules - For broker/bank imports (PostFinance, True Wealth, Raiffeisen), build the safe review layer before productive imports: Import Wizard, instrument mappings, platform/account mappings, dry-run summaries, Manual Review Queue, Data Quality Center and visible read-only/write-enabled state. Follow `references/import-wizard-mapping-layer.md`. When wiring parser output into the wizard, use the synthetic-first parser/dry-run/review-item pipeline in `references/broker-parser-dry-run-pipeline.md`. After explicit approval for real-file dry-runs, follow `references/controlled-real-broker-dry-run.md`: preflight, verified runtime backup, temp-only file handling, aggregate-only reporting, runtime-only review items, and verification that productive positions/ledger rows stayed unchanged. For DOCX portfolio extracts from True Wealth/PostFinance, follow `references/crypto-adjusted-xlsx-and-equity-docx-dryrun.md`: use structural/masked parsing only, count field coverage and mapping status, treat ticker-without-exchange as review-needed, and stop before productive import. If the DOCX dry run shows low ISIN coverage/no cost basis/no transaction history or the user withholds final import approval, switch to `references/equity-docx-instrument-resolver-review-workflow.md`: create `instrument_import_candidates`-style staging, use local Qwen only as an assistive parser if available, classify ticker-only rows as `needs_manual_review`, expose a Mapping Review Queue, and import only later from `confirmed` candidates after explicit approval. If the user rejects productive DOCX import or wants direct manual control, follow `references/manual-equity-etf-entry-wizard.md`: make the main path an audited portfolio-app-style search/add-position wizard with explicit candidate selection, no live API on render, no ticker-only auto-selection, hidden technical IDs in User Mode, cost-basis/FX quality alerts, and audit-log writes. When the user asks to make real dry-run results manually editable, follow `references/broker-review-queue-hardening.md`: add filters/detail views, auditable review-metadata actions, per-item/session import-readiness status, dry-run session management, and Data Quality Center counts while keeping productive portfolio writes disabled. For a guided manual-review pilot on real runtime items, follow `references/guided-manual-review-pilot.md`: select 1–3 clear ETF/equity items (prefer True Wealth), write only audited review metadata, correct only presence booleans if needed, derive `ready_for_import` via readiness logic, and verify productive tables remain unchanged. Before the first productive broker position import, follow `references/broker-import-execution-plan-mini-import.md`: create runtime-only execution plans from the ready review items, validate exact Decimal-text payloads from the runtime source, preserve missing FX/cost-basis quality flags, then import exactly one ledger `initial_position_snapshot` after a verified backup; do not write `positions_snapshot` as the source of truth. After the first mini-import and before broader imports, follow `references/broker-mini-import-regression-and-corrections.md`: verify import links/audit/Decimal handling/re-import blocking, add or test safe void/correction flows, run backup/restore-to-test-DB regression, and only then optionally import one more ready plan. When the user approves finishing a remaining small set, follow `references/broker-mini-import-completion-and-dq-consolidation.md`: first disambiguate active vs resolved stale crypto alerts with `check-data-quality --scope crypto --resolve-fixed`, then import exactly one remaining ready execution plan after backup/verify, and consolidate Review Queue/Data Quality counts without exposing values. - Do not pivot into later analytics modules while the user has asked for import/mapping hardening. Monte Carlo, backtesting, rebalancing, scores, heatmaps and projections are later phases unless explicitly re-authorized. - Use a canonical CSV format before broker-specific importers. - Imports must be idempotent via external transaction ID or row hash. - Importers must separate dry-run and commit modes, collect validation errors explicitly, and always create an `import_sessions` record even for dry runs or failed imports. - Import results should classify rows as new, existing, duplicate, or failed; do not rely on `INSERT OR IGNORE` as the only duplicate-detection mechanism. - Row hashes must be stable and deterministic: normalize key order, whitespace, and `None` versus empty strings while leaving domain-specific canonicalization to the importer. - If a source file has only current holdings and no full history, import it as `initial_position_snapshot` / `initial_cash_snapshot`, not fake historical buys. - Missing historic FX, fees, taxes, dates, investment case, target weights, or dividend details must be flagged as data-quality gaps. ## FX and return rules For acceptance-mode dashboard fixes around manual position entry and valuation UX, follow `references/mvp-acceptance-dashboard-fx-valuation-cleanup.md`: hide internal FX status codes from User Mode, treat CHF as `not_needed`, resolve USD/EUR via cache/provider on explicit save, require a conscious manual-or-missing choice when FX cannot be resolved, and never store `ok` without a rate. For real Runtime-DB Streamlit regression sprints spanning Alerts, navigation, FX/Cash, Equity/ETF interaction, cleanup, no-live-render, browser sanity, and final push verification, also follow `references/dashboard-real-ui-acceptance-regression.md`. For foreign currency assets, always distinguish: - price/security performance in original currency - FX effect to CHF - realized P&L - unrealized P&L - dividends/distributions/income - fees and taxes - Total Return in CHF Every transaction/income event needs: - original amount and currency - historical FX rate to CHF, or explicit `fx_status=missing` with a critical data-quality alert - FX source and timestamp - CHF equivalent at event date when FX is known Manual FX overrides require a non-empty note and an audit-log entry. ## Ledger calculation rules - Cash after system start must be calculated from `transactions`; `cash_balances` is only a snapshot/cache/control view. - `initial_cash_snapshot` and `initial_position_snapshot` are explicit starting truths, not fabricated historical trades. - Implement Weighted Average Cost as the MVP internal performance method: buy fees increase cost basis, partial sells remove proportional cost basis, realized P&L is calculated against average cost, full sells zero remaining quantity/cost basis, and dividends do not alter quantity or cost basis. - WAC is not tax-complete; do not add FIFO/LIFO/tax-lot logic in MVP 1, but keep transaction granularity so it can be added later. - Position calculations must keep zero-quantity historical positions visible when sale history exists. - Missing market price or FX must degrade data quality and suppress precise Total Return CHF rather than inventing a value. - Before productive dashboard use, add alert deduplication per rule/entity/date. - Market-FX for non-CHF market prices belongs to the later Market/FX provider block. ## Crypto MVP rules - Crypto inventory is MVP-critical but must remain dummy-first until mapper/dry-run layers are ready; do not touch real coin/wallet files during core implementation. After explicit user approval, real files may be read only from temp/runtime for controlled dry runs using `references/crypto-xlsx-initial-snapshot-dry-run.md`; report only aggregate counts/labels and never quantities or values. Productive safe-subset imports require a second explicit approval and must follow `references/crypto-xlsx-initial-snapshot-production-import.md`: external runtime DB only, no real CSV/XLSX/reports/DBs in Git, Git-safety before/after, import-session + audit-log creation, and aggregate-only reporting. When the user supplies an adjusted real crypto workbook with CoinGecko IDs for missing/previously skipped assets, follow `references/crypto-adjusted-xlsx-and-equity-docx-dryrun.md`: detect the actual structure first, validate IDs against CoinGecko metadata, import only clear missing asset/holding subsets after verified backup, preserve Decimal/Text quantities, ignore legacy CHF values, and delete temporary source files. - Wallet names must be unique; wallet addresses are optional and must not appear in tests/fixtures. - Validate wallet type against: Hardware Wallet, Software Wallet, Exchange, Bank/Broker, DeFi, Sonstiges. - CoinGecko ID is strongly recommended but not hard-required; missing ID creates a data-quality warning and blocks reliable valuation. - Crypto symbols are not globally unique; symbol conflicts require warning/manual selection, never silent merging. - Initial crypto holdings are confirmed snapshots by wallet+asset. Store legacy values for provenance/control only, never current valuation. - Crypto holdings should be calculated/controlled from initial snapshots plus crypto transactions, not silently overwritten. - Crypto transfers require different source/target wallets, quantity > 0, and same asset; coin fees reduce source-wallet balance. - Negative wallet balances should be blocked in MVP and produce a critical alert unless a future explicit correction workflow is implemented. - Crypto buys/sells with fiat impact must create/reference general ledger transactions via `source_type='crypto'`/`source_id` so cash remains ledger-consistent. - Fiat fees should be ledger fees when unambiguous; avoid double counting when a fee is already embedded in sell net proceeds. - Unknown fee currency creates a data-quality warning instead of invented accounting. - Crypto Cost Basis/WAC is not required for MVP 1; MVP 1 prioritizes crypto holdings, wallet structure, current valuation, reports and audit. - Crypto report context/export must be renderer-neutral and local-only: build from SQLite, aggregate by coin and wallet, use local cached prices only, preserve Decimal/Text values, ignore legacy snapshot values for current valuation, include data-quality warnings, and write generated files only to the external runtime reports directory. - Crypto PDF export should be optional-dependency tolerant: prefer PDF when a renderer is available, otherwise fall back to HTML/Markdown with a clear warning while still recording report metadata and audit. - After productive real-data crypto imports, run the post-import runtime verification in `references/crypto-runtime-db-consistency-verification.md`: exact safe-set membership checks, aggregate-only counts, audit/import-session traceability, dashboard render with no live API, runtime-only report generation, and Git-safety before/after. - Manual dashboard additions/corrections/removals after an initial snapshot must follow `references/mvp-crypto-manual-management-ui.md`: no silent `crypto_holdings` mutation, explicit confirmation, mandatory notes for adjustments/removals, audit-log entries with old/new values, Decimal/TEXT quantity handling, no negative holdings, and no live API lookup during render. For dashboard UX/read-model work, also follow `references/dashboard-user-mode-ux-and-runtime-review.md`: split User Mode from Admin/Review/Debug, aggregate coins across wallets, hide technical IDs in normal views, keep cached-price semantics explicit, and make Crypto Manage actions audited workflows rather than raw table edits. For Vue/FastAPI Crypto page hardening, follow `references/crypto-vue-dashboard-readmodel-hardening.md`: aggregate holdings by asset/wallet before applying the latest price, test duplicate-price-row regressions, keep crypto UI compact, hide weak sparklines behind an empty state, and make wallet rows drill into wallet detail. - Crypto tax logic, tax lots, FIFO/LIFO and detailed cost basis are later modules. - Keep crypto assets separate from `instruments` for MVP 1, but later evaluate a shared Asset Master if it improves reporting, performance views or watchlists. ## Income/tax rules For dividends and ETF distributions, separately store: - gross dividend/distribution - Swiss withholding tax 35% - foreign withholding tax - other tax/withholding if present - net amount - original currency - historic FX to CHF - gross/net CHF equivalents - platform/account - ISIN/ticker - payment date - ex-dividend date if available Plan later ESTV/ICTax support for Swiss year-end values and tax reports, but label outputs as technical reports, not tax advice. ## Market-data rules - Dashboard reads primarily from local DB, not directly from APIs on page load. - For Equity/ETF FX and market-data hardening after broker mini-imports, follow `references/equity-fx-market-data-phase-c.md`: validate active `missing_fx` alerts by original transaction currency first, correct only CHF false positives with audit, keep foreign-currency missing-FX alerts active until local historical rates exist, use ISIN as instrument identity and provider symbols only as market-data mappings, and run market-price providers only from explicit CLI/scheduled jobs. - For the True-Wealth valuation pilot, follow `references/true-wealth-valuation-pilot-c2.md`: do not import more positions, do not guess provider symbols or hedge status, extend instrument metadata for currency hedging/status/valuation policy/corporate-action state, handle historical-FX paywalls as `manual_override_required` without crashing, align price/FX timestamps before claiming valuation precision, and report only aggregate runtime counts. - For True-Wealth mapping-candidate review after the valuation pilot, follow `references/true-wealth-mapping-candidate-review-c3.md`: create runtime-only provider-symbol candidates keyed by ISIN/instrument, keep name-only or ticker-without-exchange candidates review-required, mark multiple candidates `needs_manual_review`, do not auto-select final mappings on ambiguity, keep hedge/instrument status unknown until confirmed, and ensure market-price dry runs call no provider when there are zero confirmed mappings. For public metadata lookup implementation details, provider result caps, OpenFIGI/Yahoo evidence handling, alert dedupe, runtime-only review templates, and UI/test requirements, use `references/public-instrument-lookup-candidate-generator.md`. For ranking/scoring candidates, generating a runtime-only user decision pack, surfacing `candidate_review_required` and same-ISIN multiple-listing risks, and confirming/rejecting candidates with audit logs, use `references/mapping-candidate-ranking-decision-pack.md`. - For the broader Instrument Catalog + manual-add workflow, follow `references/instrument-catalog-manual-add-workflow.md`: documents/import files are initial-population aids, but the dashboard must allow audited manual add of equities/ETFs and later coins via search, candidate selection, account/wallet selection, Decimal/Text quantity, date, cost-basis/snapshot info and notes. ISIN is primary for equities/ETFs but can have multiple listings; ticker/symbol alone is never unique; provider symbols are market-data mappings only; CoinGecko ID is primary for crypto provider identity. External lookups may use only non-confidential instrument metadata and must never send quantities, balances, account/wallet IDs, cost basis, private notes or source documents. If DOCX/Broker import is not approved or structurally weak, use `references/manual-equity-etf-entry-wizard.md` as the preferred user path: search on explicit click, show candidates, require conscious selection, allow warned manual creation, then review/confirm an audited initial snapshot or transaction. For the concrete Dashboard/User-Mode implementation pattern, provider order (local/OpenFIGI/FMP/Finnhub/manual), runtime `.env` secret lookup, provider-result caching, and final compile/test/Git-safety/commit/push discipline, also follow `references/manual-position-entry-provider-ux.md` and `references/equity-etf-provider-integration-openfigi-fmp.md`. For multi-provider hardening across OpenFIGI/FMP/Finnhub/Twelve Data/Massive/EODHD, follow `references/provider-integration-sprint-v2.md`: support all documented secret aliases including `TWELVEDATA_API_KEY`, keep FMP primary, use Twelve/Finnhub/Massive as fallback, keep EODHD explicit low-volume only, sanitize status/error output, and ensure dashboard status uses non-probing render mode. If provider smoke tests report missing candidates or unreachable providers despite keys being stored, first follow `references/provider-secret-auth-debugging.md`: verify runtime secret loading without printing values, classify 401/403 as `auth_failed` rather than generic reachability failure, and improve status diagnostics before adding features. - First Streamlit MVP should be a safe, local, read-first shell over SQLite with explicit synthetic demo DB creation only; page render functions must not call CoinGecko/market APIs, and tests should prove that by monkeypatching provider methods to fail. When the user asks to move beyond Streamlit, do not mutate the working Streamlit UI first; add a small FastAPI read-only boundary with DTOs and tests, then build a Vue vertical slice. Follow `references/fastapi-vue-dashboard-transition.md`. - Functional UX stabilization work must prioritize making the existing dashboard genuinely usable before adding more pages. Follow `references/dashboard-functional-ux-stabilization.md`: use one navigation system, move executable page modules out of Streamlit `pages/` when using a custom router, hide unfinished pages from User Mode, replace text-link/fake actions with real buttons or disabled controls, enforce session-based Edit Mode for writes, keep IDs/debug notes out of User Mode, and test price/report provider calls happen only on explicit clicks. If the user says the dashboard is still too busy or prototype-like, follow `references/dashboard-usability-simplification.md`: reduce User Mode to only currently useful pages, keep the Command Center calm, avoid misleading `CHF 0.00` Equity/ETF displays when valuation is incomplete, make Crypto the primary MVP surface, and ensure every visible button either works immediately, opens an inline form, or is disabled with a reason. For regression hardening after manual-position/provider work, also follow `references/mvp-dashboard-workflow-regressions.md`: cache-first historical FX, audited Cash wizard writes, explicit-click Equity/ETF and Crypto refreshes, no live API on render, User Mode cache-source labels without raw IDs, and manifest-based runtime cleanup. - Use scheduled jobs to update prices/FX/news. - Store provider, timestamp, quality status and freshness for every price/FX point. - Implement caching, local historical storage, batch requests where possible, provider rate-limit queues, and backoff on HTTP 429. - CoinGecko integrations must be mockable and unit-tested without real API calls; treat HTTP 429 as non-fatal and return a non-fresh data-quality status plus alert after configured retries. - Crypto price refresh belongs in CLI/scheduled-job commands, not dashboard/report rendering. Prefer CoinGecko batch requests over per-coin requests; expose conservative controls (`--sleep-seconds`, `--max-retries`, `--initial-backoff`, `--max-backoff`, `--only-missing`, `--only-stale`, `--only-symbol`, `--limit`, `--dry-run`, `--currency`). Commands should use aggregate-only output (`total_assets/updated/cached/skipped/stale/warnings/errors/assets_still_missing_local_price`), cache by configurable `max_age_seconds`, store exact Decimal prices as TEXT in `crypto_prices`, and verify dashboard/report contexts read local prices with `live_api_calls=False`. For details and tests see `references/crypto-price-refresh-and-idempotent-btc-runtime.md`. - After an accepted sprint, respect an explicit MVP freeze: do not add providers or large features; write/update the sanitized repo report and acceptance checklist, verify with compile/tests/Git-safety, commit/push, and prepare the next real end-to-end runtime test. See `references/mvp-freeze-zwischenbericht-abnahme.md`. - Candidate providers: Finnhub, Financial Modeling Prep, Twelve Data, Stooq, Alpha Vantage selectively, Yahoo Finance fallback only; CoinGecko for crypto; later DefiLlama; ESTV/ICTax for Swiss tax values. ## Crypto Decimal precision rules SQLite has no exact native DECIMAL. In the crypto context, store quantities, prices, crypto fees and valuation-relevant amounts as exact Decimal strings (`TEXT`) and compute with Python `Decimal`. Never convert crypto quantity/price/fee/valuation through float/REAL. Format Decimal writes with `format(value, "f")` so small quantities such as `0.00000001` do not become scientific notation. CSV importers must validate Decimal strings, and tests should assert high-precision preservation plus SQLite text storage. For multi-wallet real-data snapshots and Equity/ETF ledger fields, also see `references/multi-wallet-crypto-and-equity-manage-ui.md`; SQLite `NUMERIC` affinity can coerce Decimal-looking text to `real`, so schema/migrations should use `TEXT` for exact quantities, FX rates, original amounts and CHF equivalents where precision matters. ## Alert lifecycle rules Alerts must be deduplicated and lifecycle-aware before dashboards run repeated calculations. Use a dedup key from `rule_id`, `entity_type`, `entity_id`, `priority` and an error fingerprint. Alerts should carry `status` (`active`, `resolved`, `muted`), `resolved_at`, optional `muted_until`, `last_seen_at`, `occurrence_count`, `fingerprint` and `dedup_key`. Re-seeing an identical active/resolved/muted alert should update `last_seen_at`/`occurrence_count` rather than create a new active row; changed fingerprints may create a new alert. ## Git/GitHub and worker safety Never commit financial data; `.gitignore` blocks runtime data, reports, exports, backups, DBs, spreadsheets, raw imports and secrets. For bounded worker checkout verification, use `references/worker-worktree-integrity.md`. ## MVP implementation safety gate Before any real broker/bank/portfolio/crypto data is imported, build and verify the safety foundation described in `references/mvp-safety-gate-implementation.md`: repo skeleton, `.gitignore`, `.env.example`, runtime outside repo, settings validation, SQLite schema, synthetic fixtures, audit log, CSV dry-run, duplicate protection, and Git-safety scan. Run the safety scan before staging, committing, or pushing. If GitHub credentials are needed from Drive, use them only in a temporary location and never echo token values. - Before broader productive imports, implement or verify the runtime backup loop in `references/runtime-backup-and-broker-mapping.md`: backup outside Git, SHA256 verification, restore requiring explicit confirmation, tests for backup/restore/checksum, and Git-safety coverage that blocks backup artifacts in the repo. For PostFinance/True Wealth/Raiffeisen, perform structural mapping and dry-runs only until the user approves import; report aggregate counts/field coverage/quality flags only, never real values or raw rows. If backup CLI output is too terse to evidence the backup path/checksum, call `jarvis_finance.runtime.backup.backup_runtime_db(...)` and `verify_backup(...)` directly and report only path-existence/outside-repo/checksum status, not DB contents. ## Common pitfalls - In Budget category UX work, do not rely on PrimeVue/DataTable drag-and-drop if it is flaky or hard to test. A robust Up/Down + explicit `Sortierung speichern` flow is acceptable and preferred for this user when it works on desktop and mobile, persists `sort_order`, writes audit events, and reloads in the same order. Reorder endpoints must be scoped by `category_type` so Income and Expense orderings cannot mix, and planned income rows need their own audited `sort_order` flow. See `references/budget-categories-ux-sorting.md`. - Starting later analytics (Monte Carlo, backtesting, rebalancing, scoring, heatmaps, projections) while import/mapping/data-quality phases are still being hardened or while the user explicitly asked to postpone them. - Letting the Budget/Cashflow foundation become a hidden import/rule-engine sprint. Phase 1 should be manual accounts/categories/tags/transactions/transfers/overview only, with Preview → Confirm writes and no VISA/Migros/Cumulus import, duplicate engine, or rule engine unless the user explicitly opens that next phase. See `references/budget-phase1-manual-ledger-foundation.md`. - Treating workbook-derived Budget/Cashflow seeds as safe productive imports. Excel seed parsing may persist review candidates, but must not mutate productive budget plans until explicit Confirm. Always compare candidate counts with the validated dry-run analyzer, preserve ambiguous rows as unclean ranges, and verify aggregate-only that productive budget table counts did not change during seed. See `references/budget-phase12-excel-seed-review.md`. - Letting Phase 1.5-style source-aware Budget/Cashflow import corrections remain row-granular. Migros/Cumulus article rows are detail data, not normal review candidates; aggregate them to receipts and mark previous article candidates `superseded`/archived with audit after a verified runtime backup. Credit-card Migros rows must be `covered_by_migros`, Galaxus must stay review-required/splittable, and AKB/Raiffeisen own-account transfers must be transfer candidates rather than income/expense. See `references/budget-source-aware-import-review.md`. - Over-broad merchant matching in Budget user-category rules. A plain pattern such as `M ` can falsely classify unrelated merchants as Migros; use normalized explicit merchant tokens, guard special abbreviations, and exclude `Migrol` from grocery/Migros coverage when it should classify as fuel/transport. User-rule passes must update candidate metadata only, keep Galaxus/Digitec review-required/splittable, and prove no productive transactions were created. See `references/budget-phase16-user-category-rules.md`. - In Budget/Cashflow workflow-clarification sprints, do not treat transfers as merely a label on expense/income rows. Internal household transfers, credit-card settlements, and True Wealth investment transfers must be explained in Review UX, excluded from Budget income/expense actuals, and surfaced in a dedicated transfer view with from/to accounts. `True Wealth Cash` can be prepared as a target account, but missing runtime accounts must not be silently created; report absence and require Preview → Confirm → Audit for productive creation. Help text belongs in a central help registry/component, not scattered page prose. See `references/budget-workflow-help-ux.md`. - In FinanceManager Vue/FastAPI hotfixes, do not treat route failures, FX labels, cleanup guards, and portfolio buckets as unrelated if the user reports them together. First reproduce route/menu paths from `router` + `userNav`, then add tests before fixing. For FX, transaction `currency_original`/stored rate/status outranks the display valuation currency; CHF is `not_needed`, foreign currency needs a real cached/provider/manual rate, and failed provider rechecks must not lead to invented rates. For ETF cleanup, void only exactly-one-row manual snapshot/legacy adjustment positions after backup/dry-run/audit; block real histories. For TrueWealth, gate on managed-account metadata rather than label substring, keep it out of single-position wizards, and show it as a separate manual total-value bucket. See `references/vue-routing-fx-etf-truewealth-hotfix.md`. - Treating a holdings snapshot as a real transaction history. - Mixing price P&L and FX P&L. - Letting dashboard refreshes hammer APIs. - Committing realistic sample data to Git because the repo is private. Private GitHub is not a financial data vault. - Showing real portfolio values back to the user unnecessarily in summaries. - Designing Git-safety scans that block source package names like `src/.../imports` or `src/.../reports`; block top-level runtime/data directories instead. - In broker/bank real-file dry-runs, aggregating Data Quality flags only for `review_status='open'`. Blocked review items are still actionable data-quality issues; include `open` and `blocked` so defensive Raiffeisen aggregate-only rows remain visible. - Letting manual review actions blur into productive import actions. Review-metadata writes (ISIN/ticker/exchange/account/instrument confirmations, ignore/resolve, dry-run archive/current status) may be allowed with audit logs, but they must not write `positions_snapshot`, `transactions`, `cash_balances`, ledger rows, or cash snapshots. Name-only mapping must never become `mapped`/`ready_for_import`; ticker-only without exchange remains review-needed; `aggregate_only` remains blocked for instrument import. In guided pilots, do not force `ready_for_import` by direct status edits; let readiness logic derive it after audited metadata actions, and if parser presence flags were missed, correct only boolean presence metadata with an audit event, never actual quantities/values. - Skipping the execution-plan layer between ready review items and productive broker imports. A final dry-run should materialize runtime-only execution plans with source row hash, target IDs, exact Decimal-text payload summary, quality flags and planned write status. Productive mini-imports should consume exactly one planned ready payload, write exactly one ledger `initial_position_snapshot`, mark that plan/review item imported, leave the other ready plans untouched, and verify zero direct `positions_snapshot`/cash writes. After the first productive mini-import, do not proceed straight to mass import: run regression checks, implement/test void and correction audit paths, verify backup/restore to a separate test DB, and import at most one additional ready plan. When later completing the final ready plan, first resolve Data Quality alert ambiguity by counting only active alerts (`status='active'`) and treating resolved rows as history; then import exactly one plan and consolidate counts. See `references/broker-import-execution-plan-mini-import.md`, `references/broker-mini-import-regression-and-corrections.md`, and `references/broker-mini-import-completion-and-dq-consolidation.md`. - Running compile/tests before Git-safety and forgetting generated `__pycache__`; remove or ignore generated caches before safety scans. `pytest` may recreate `.pytest_cache`, so remove `__pycache__`/`.pytest_cache` again after test execution and before `git-safety-scan`. - Treating every active `missing_fx` alert after a broker mini-import as a bug. First aggregate by original currency: CHF rows may be false positives (`fx=1`, `not_needed`, resolve with audit), but foreign-currency rows without local historical FX should remain active and block precise CHF valuation until rates are populated. - Auto-mapping Equity/ETF market prices by instrument name or ticker alone. ISIN is the instrument identity, but one ISIN can have multiple listings across exchange/currency, so even ISIN matches may need candidate selection. Provider symbols are separate market-data mappings, ticker without exchange is review-needed, and missing provider symbols should create deduplicated Data Quality alerts rather than triggering provider guesses. For mapping-candidate phases, candidate creation is allowed in the runtime DB, but final selection must remain manual/audited unless the user explicitly approves and the match is unambiguous. Public lookup endpoints can return dozens of listings; cap result sets, dedupe active mapping alerts by rule/entity, and do not treat search-fallback results as ISIN-confirmed unless the provider response supplies ISIN evidence. - Designing future portfolio entry as import-file-only. Imports/documents are for initial population and existing holdings; the system must also support dashboard manual add/search workflows with audited ledger writes, explicit candidate selection, Decimal/Text quantities, required notes where history is incomplete, and no silent overwrites. If the user says DOCX/Broker files are too unsafe or not approved, stop the productive import path and pivot to the manual Equity/ETF wizard in `references/manual-equity-etf-entry-wizard.md`; keep the review queue optional/admin-only, ensure manual-entry broker accounts exist, and do not expose technical IDs in User Mode. The manual entry path must be visible in normal User Mode (e.g. `Position hinzufügen`) with Command Center routing; provider lookup must be explicit-click only, cache results locally, load provider keys from runtime secrets, and degrade missing keys to warnings. See `references/instrument-catalog-manual-add-workflow.md` and `references/manual-position-entry-provider-ux.md`. - Letting an Equity/ETF market-price dry run call providers when no confirmed mappings exist. The safe outcome is `total_mappings=0`, no provider calls, and aggregate reporting only. - For valuation pilots on historical broker snapshots, treating a computable current market value as a clean performance result. `snapshot_only`, `cost_basis_uncertain`, missing hedge confirmation, missing historical FX, stale price/FX timestamp alignment, or suspected corporate actions must keep valuation `partially_valuable` or suppress precise Total Return until reviewed. - Inferring CHF-hedged ETF behavior from the name alone. Hedge status is methodology-critical: unknown status should create a warning/review item; confirmed CHF hedging must prevent naive free FX-PnL attribution. - Crashing or blocking on historical-FX provider paywalls. Persist `manual_override_required`, create deduplicated alerts, keep the flow moving, and require a noted audited manual override instead of guessing latest FX. - Productive real-data imports can partially write before surfacing schema/importer compatibility issues. Do not rerun blindly or dump row-level data; inspect aggregate counts and unique identifiers needed for idempotency, patch/complete via missing-only inserts, then verify committed import session, audit log, Git clean and Git-safety OK. - In controlled one-coin runtime tests from a real XLSX, distinguish **one coin/asset** from **one holding/wallet row**. A coin may be split across multiple wallet columns; if the user required an unambiguous target wallet or one holding, stop and ask rather than choosing a wallet silently. If the user explicitly approves multi-wallet import for that coin, import exactly one asset plus one audited holding per non-empty approved wallet cell; verify aggregate counts only. If re-running a BTC/single-coin test finds the exact approved asset and holdings already present, do not import duplicates; perform the aggregate-only idempotency checks and report that asset/holding counts did not increase because duplicate prevention succeeded. See `references/crypto-single-coin-runtime-test.md`, `references/multi-wallet-crypto-and-equity-manage-ui.md`, and `references/crypto-price-refresh-and-idempotent-btc-runtime.md`. - After productive crypto imports, do a separate aggregate-only consistency pass before building new features: DB/runtime outside repo, exact safe-subset membership, no duplicate/negative/orphan holdings, correct snapshot date, null legacy-value fields when ignored, import sessions committed, holding-level audit traces present, dashboard local-read/no-live-API verified, and report generated only under runtime reports. - Letting a dashboard correction UI mutate crypto holdings directly. Add/remove/edit operations must become audited transactions or `manual_adjustment` events with mandatory notes where appropriate; preserve history instead of silently overwriting balances. - Letting normal dashboard pages become technical raw-table dumps. For this user's Finance dashboard, implement an Alltag/User Mode that hides internal IDs/provider internals and presents aggregate, actionable read models; keep raw identifiers, candidate details and audit/debug fields in Admin/Review/Data Quality views. See `references/dashboard-user-mode-ux-and-runtime-review.md`. - Treating Streamlit/dashboard UX stabilization as a chance to build more modules. When the user complains about prototype feel or duplicated workflows, first eliminate duplicate navigation, empty User Mode pages, fake/text buttons, unclear Read-only/Edit state, and raw technical IDs. Keep unfinished pages in Admin/Debug or hide them; every visible button must work, prefill a real workflow, or be disabled with a reason. For Budget candidate workflows specifically, do not keep Import Review and Category Assignment as two pages over the same rows; centralize them as **Buchungen prüfen** and ensure Confirm really books a productive transaction before claiming acceptance. See `references/dashboard-functional-ux-stabilization.md`, `references/dashboard-usability-simplification.md`, and `references/budget-phase18-core-confirm-flow.md`. - In Finance Command Center / Monthly Close work, do not let a management dashboard become another feature engine. It should summarize confirmed-only local DB/cache data and route to existing work pages; no live provider calls on render, no new import sources, no OCR, no auto-booking. Validate month input as strict `YYYY-MM`, use `>= first_day` and `< next_month` for monthly actuals, derive budget/fixed-cost contexts from the selected month, and use local-date `YYYY-MM` in Vue rather than UTC ISO slicing. Runtime reports must resolve under the runtime reports directory outside Git before writing. See `references/finance-command-center-monthly-close-v1.md`. - In Dashboard Ops Controls / Reports work, never turn restart buttons into a remote shell. Use an allowlist of fixed repo scripts, write PID/log/audit-like events under runtime, sanitize responses, require confirm in the UI, and return only short status/error fields. Reports must be generated from local runtime data, count confirmed actuals only, keep candidates/transfers/covered rows separate, write only under runtime reports, and fall back to HTML when PDF rendering is unavailable. See `references/dashboard-ops-controls-reports-v1.md`. - In Migros grocery optimizer work, do not calculate optimized totals from more stores than the emitted shopping list allows. Choose/enforce the allowed retailer subset (`max_store_count <= 3`) before calculating totals/savings; products whose cheapest safe match is outside the subset must keep their Migros price and be marked `not_selected_due_to_store_limit`. Also do not render include checkboxes as decorative controls: bind them to state, send `included_product_item_ids`, filter backend items before totals, and reset include state whenever the user switches receipts. See `references/migros-grocery-optimizer-v1.md`. - In Budget/Cashflow review-productivity/core-correctness sprints, confusing built batch tooling with permission to use it productively. Build and test batch confirm on synthetic/test DB data, but for real runtime candidates keep Batch Confirm behind Preview → explicit user Confirm and do not mass-confirm real candidates during the implementation sprint. Rule MVP and Merchant/Alias actions must set candidate suggestions only, never create `budget_transactions`; split Confirm must exact-match candidate totals and audit all created linked transactions. Duplicate candidates require an explicit `allow_duplicate`/`Trotzdem bestätigen` path with category/account/year and audit; normal Confirm must block them. User Mode must show labels like `Prüfung nötig`/`Vorgeschlagen` instead of raw enums such as `needs_review`/`auto_categorized`. When the active budget year is fixed (e.g. 2026), make every default Review/Summary/Effective/Budgetstatus/Chart query year-aware, archive old-year candidates as reference, and block out-of-year confirms. For bulk review fixes specifically, centralize blocker checks so preview and confirm agree; normal bulk category assignment must skip blocked statuses with per-candidate errors; final confirm stays disabled until all selected candidates have categories and no duplicate/covered/transfer/missing-field blockers. For planning/forecast work, do not invent a parallel actuals model: use confirmed transactions for actuals, existing budget-plan structures for plan values where possible, and a small Decimal-text baseline/reference table for prior-year/manual values only when the existing schema lacks that concept. See `references/budget-phase19-review-productivity.md`, `references/budget-phase110-2026-core-cleanup.md`, `references/budget-import-review-production-v1.md`, `references/budget-review-bulk-assign-confirm.md`, and `references/budget-planning-forecast-v1.md`. - In Budgetstatus work, accidentally showing only categories with budget plans. The table must be Full-Outer-Join-style over active plans and confirmed active-year actuals: actual-only categories must appear with `ohne Budget`, plan-only categories must remain visible with neutral/no-actuals status, and empty categories without plan/actuals stay hidden. Subcategory postings must appear on the booked subcategory and aggregate into parent rollups; do not move transactions just to make a parent row visible. See `references/budget-phase111-status-income-formatting.md`. - Letting dashboard Decimal strings leak raw into the Vue UI. Long values such as `4019.308333333333482` are unacceptable in User Mode: use central Vue formatters for money/percent/quantity, keep Decimal/TEXT storage and domain calculations intact, and update contract tests when DTO display output intentionally standardizes to `0.00`. See `references/budget-phase111-status-income-formatting.md`. - Treating mobile readiness as a narrow CSS tweak or, worse, as permission to start new finance modules. For iPhone/iPad FinanceManager work, preserve desktop tables but add mobile card lists, compact navigation, touch-friendly drawers/buttons, and route/Tailscale sanity; do not start VISA/Migros/OCR/rule/duplicate/provider engines, and do not claim viewport emulation unless browser tooling actually did it. See `references/vue-mobile-ux-sprint.md`. - Building a parallel model for Budget Einkünfte when existing budget plans are enough. Income MVP should use `budget_plan_items` with income categories, add/archive with audit, derive monthly/yearly values from cadence, list Excel income candidates aggregate-only, and keep Review/Confirm as the productive write boundary. See `references/budget-phase111-status-income-formatting.md`. - Letting an accepted sprint half-finished because the next feature is tempting. If cleanup, final tests, Git-safety, commit, and push are still missing, finish those in order before starting new work. Remove `.pytest_cache`/`__pycache__` before and after tests, then run Git-safety, `git diff --check`, verify clean status, commit, push, and fetch/update `origin/main` to prove sync. If normal `origin` verification is unauthenticated but a FinanceManager runtime GitHub token is available, verify the remote hash through a temporary authenticated URL and unset it immediately; do not set token-bearing remotes or print the token. See `references/dashboard-usability-simplification.md` and `references/dashboard-user-mode-finalization-and-push.md`. - Breaking an explicit MVP freeze by adding more providers/features after the user accepted the sprint. In freeze mode, produce the sanitized Zwischenbericht/Abnahmeplan, separate implemented vs not-finished vs risks, include concrete user acceptance checklists, and run the same verification/push discipline as code changes. See `references/mvp-freeze-zwischenbericht-abnahme.md`. - During Budget/Cashflow runtime cleanup or UAT, allowing test/seed rows to leak into User Mode is a correctness bug. Create a runtime backup first, report dry-run counts only, archive/deactivate UAT artefacts with audit, then verify user-facing APIs/pages return zero matching visible objects. If you create temporary runtime UAT rows to prove Confirm/category/ignore flows, archive them immediately after verification. See `references/budget-phase18-core-confirm-flow.md`. - Rebuilding SQLite tables with `ALTER TABLE ... RENAME TO ...` without checking dependent foreign keys. SQLite can rewrite dependent table references to the temporary table name, causing later inserts to fail with `no such table: main.`. After migrations that rebuild budget transactions/candidates, inspect `sqlite_master` for `__phase` references and regression-test dependent inserts into tags/transfers/line-items/splits. See `references/budget-phase18-core-confirm-flow.md`. - Running Git-safety immediately after pytest without cleaning generated caches. Pytest can recreate `.pytest_cache`; remove `.pytest_cache` and `__pycache__` after the final test run, then run Git-safety before staging/commit/push. - In MVP acceptance mode, exposing raw internal workflow states (`ok`, `missing`, `manual_override_required`, `not_needed`) to User Mode is a bug, not documentation. Convert them into plain choices such as automatic FX, manual FX, or save incomplete; keep the stored internal status deterministic and audited. - Treating absent CoinGecko/Crypto detailcache code as something to invent during an acceptance bugfix sprint. If the codebase has no implementation, report it as an explicit open gap unless the user authorizes a new feature mini-sprint. - Relying on the user's prose description of a spreadsheet layout instead of detecting the actual workbook structure. In adjusted crypto XLSX files, CoinGecko IDs may appear as an `API ID` column in the same row rather than a preceding row; use the detected structure, validate IDs, and report the difference aggregate-only. - Treating formula/scientific-notation source cells as automatic import blockers. Count them, but block only when exact Decimal/Text conversion fails; never use float arithmetic for crypto quantities. - Printing raw DOCX/table rows while analyzing real broker files. Use masked structural flags and aggregate counts only; real position names/values/quantities stay out of chat/log summaries. - Counting ticker-like tokens from DOCX as confirmed Equity/ETF mappings. Without ISIN plus exchange/provider confirmation, mappings are `probable` or `needs_manual_review`, not productive-import ready. - Treating low-confidence Equity/ETF DOCX extraction as enough for import. If most positions lack ISIN, cost basis or transaction history, build/operate a staging resolver and Mapping Review Queue first. Ticker-only rows stay `needs_manual_review`; local Qwen may help extract candidates but must not decide mappings or write ledger rows. See `references/equity-docx-instrument-resolver-review-workflow.md`. - Treating verifier/file-mutation warnings as either automatically true or automatically false. Check the exact commit with `git show --name-status --patch -- `, then separately verify whether the test matrix actually covers the promised cases. - Treating provider lookup smoke-test failures as simple `not reachable` / `no candidates` when runtime keys exist. Follow `references/provider-secret-auth-debugging.md`: confirm the runtime secret file is loaded without printing values, verify OpenFIGI uses `X-OPENFIGI-APIKEY` header and FMP uses `apikey`, split network reachability from provider auth, and classify HTTP 401/403 as `auth_failed`, 429 as `rate_limited`, empty 2xx as `no_results`, and DNS/timeout as `network_error`. Do not start a new feature block until the secret/auth diagnosis is resolved. - Letting multi-provider market-data integration become implicit dashboard behavior or an API-call spray. Follow `references/provider-integration-sprint-v2.md` and `references/market-quotes-detail-charts-v1.md`: normal dashboard render must use local DB/non-probing status only; provider calls require explicit click/CLI/schedule; FMP remains primary for search/price preview; Twelve Data/Finnhub/Massive are fallbacks; EODHD is never default and requires explicit low-volume opt-in; provider statuses and errors must be sanitized categories, not raw responses or secret-bearing URLs. Market quote/chart detail work should add cache/status endpoints and explicit UI buttons, not hidden render-time refreshes. - Adding a browser frontend without expanding Git-safety and secret boundaries. For FinanceManager Vue/FastAPI work, block `frontend/dist`, `frontend/node_modules`, `.vite`, and `.env.*` except `.env.example`; provider keys stay backend/runtime-only and must not appear in `VITE_*` variables. FastAPI tests that inject an in-memory SQLite connection through `TestClient` need `check_same_thread=False`, otherwise SQLite may fail in the worker thread. - Implementing Vue auto-load as hidden provider refresh. Auto-load is allowed only for local FastAPI/runtime DTOs; render must not call CoinGecko/OpenFIGI/FMP/Finnhub/Yahoo/etc. Add visible local-data status, explicit refresh semantics, and browser performance checks for zero external provider resources. For launch/browser sanity/process hygiene, follow `references/vue-dashboard-autoload-runtime-operations.md`. - Claiming the Vue/FastAPI dashboard was restarted before proving the browser-visible Tailscale path works. For remote/iPhone use, localhost checks are insufficient: kill stale listeners, restart backend/frontend, verify `ss` listener bind addresses, verify `/api/runtime/status` through `http://:5173`, and confirm the delivered Vite client has `VITE_API_BASE_URL=http://:5173`. See `references/vue-dashboard-tailscale-api-base.md`. - In Budget UX v2-style transaction/analysis sprints, letting an accepted reference analysis remain uncommitted or letting the sprint drift into Heatmap/Sunburst/Explorer/import-wizard work. Commit the accepted Markdown analysis with the feature, keep scope to navigation, confirmed transaction lists, calm review UX, category/month/budget-vs-actual analysis, and category bucket/merge-preview work. For Tailscale/iPhone, do not start Vite with `VITE_API_BASE_URL=http://127.0.0.1:8000`; use the browser-visible Tailscale Vite origin so `/api` proxy calls work remotely. See `references/budget-ux-v2-transaction-analysis-hub.md`. - In Budget UX foundation work, implementing query filters ad hoc per page or hiding the active year because it equals the default. Use one composable, keep canonical `year=2026` in bookmarkable URLs, sanitize invalid query values back to safe defaults, and use `replace` for initial sync versus `push` for user Apply actions. Translate internal API aliases such as `budget_year` at the store/API boundary rather than leaking them into normal URLs. See `references/budget-ux-foundation-v3.md`. - When adding an Analytics envelope, breaking legacy consumers by removing old keys too early. Add `meta`/`filters_applied`/`totals`/`series`/`rows`/`warnings`/`errors` backwards-compatibly, keep old DTO keys during transition, and make charts render explicit empty states on empty data. See `references/budget-ux-foundation-v3.md`. - In Budget import UX work, do not leave Google Drive scan as the prominent User Mode workflow once the user asks for dashboard file upload. The normal path should be CSV upload → profile detection/selection → Dry Run → candidate creation → Buchungen prüfen → explicit Confirm; Drive scan belongs in Admin/Fallback unless explicitly promoted again. Also do not let Budget Import, Buchungen prüfen, Command Center, Budget Übersicht, or Data Quality use separate candidate-count SQL: centralize user-open counts, count duplicates/covered/already-processed separately, exclude old-year/reference/superseded/ignored/confirmed rows from normal user KPIs, and browser-check Command Center after API tests because it may have legacy KPI queries. See `references/budget-import-upload-count-consistency.md`. - Treating a frontend build secret scan as a naive substring search. Broad patterns such as `sk-` can match harmless bundled CSS (`mask-background`); use realistic token regexes and inspect matches before claiming a secret leak. For Git-safety, distinguish new/changed runtime artefacts from pre-existing synthetic CSV fixtures. See `references/budget-ux-foundation-v3.md`. - Treating `npm install` as part of the normal Vue dashboard restart. If `frontend/node_modules` exists, start Vite directly with the correct environment; reserve install for dependency changes or missing modules. - Joining crypto holdings directly to historical/current price rows in detail or wallet readmodels. Multiple price rows per asset can duplicate wallet allocations and inflate values. Aggregate holdings by asset/wallet first, fetch the latest price once per asset, then value the aggregate; regression-test one asset split across wallets plus multiple price rows. See `references/crypto-vue-dashboard-readmodel-hardening.md`. - Shipping a Vue/FastAPI cockpit update after tests pass but before real browser/API sanity from the current checkout. Stale uvicorn/node processes can mask route changes; if OpenAPI or click behavior looks stale, check/kill the process bound to the port and restart from the working tree. Verify `/positions/add`, `/equity` row-click drawers, `/openapi.json` endpoint registration, frontend tests/build from `frontend/`, changed-file/build-artifact secret scans, commit, push, and remote hash equality. See `references/vue-cockpit-v11-preview-confirm-drawers.md`. - During Vue/FastAPI UAT, letting `JARVIS_FINANCE_DB_PATH` leak from the UAT server environment into pytest can make unit tests hit the UAT DB instead of their temporary runtime; unset it before full pytest unless the test explicitly requires a fixed DB path. For manual Cash and Equity/ETF Preview → Confirm flows, verify both persisted domain state and audit rows; Cash may currently need a bridge write to both ledger `transactions` and `cash_balances` compatibility/control rows. For the v1.2 completion pass, use `references/vue-manual-entry-v12-acceptance-completion.md`: update frontend mocks when moving from bare `searchInstruments` to provider-search DTOs, archive review/test accounts even when they have no remaining equity transactions, remove `.pytest_cache` and `frontend/dist` after tests/build before Git-safety, and verify authenticated push by remote-hash equality without printing or storing the token. For provider-search/preview-confirm hardening, use `references/vue-provider-preview-confirm-hardening.md`: Preview must not materialize provider/catalog instruments, Confirm is the write boundary, provider dedupe must preserve ISIN cross-listings by exchange/currency, cached CoinGecko URLs must be sanitized before DTO/DOM use, and independent re-review should focus on these exact failure modes. See `references/vue-cockpit-uat-preview-confirm-acceptance.md`. - In FinanceManager Vue UI-system sprints, confusing design-system adoption with a template migration or feature sprint. Do not copy full Sakai/Vuestic templates or assets, do not expand Budget/import logic, and do not replace routes/API clients wholesale. Prefer incremental PrimeVue/Aura page refactors with visible user semantics around charts/tables, Vitest PrimeVue/jsdom setup, and full compile/test/build/secret/Git-safety verification. See `references/primevue-budget-ui-system.md`. - Treating external Vue/finance-dashboard references as a license-free component source or as authorization for a new feature sprint. When the user provides reference apps, first produce a reference analysis, design matrix, small UI design system, layout sketch, and component hierarchy; then apply only controlled read-only UX improvements. Copy no code/assets/branding, keep Streamlit as Admin/Fallback if applicable, avoid normal-render API calls, and park budgeting/FIRE/forecast/goal modules as roadmap unless explicitly authorized. See `references/vue-ux-reference-sprint-pattern.md`.