# TrueWealth replacement: Portfolio Advisor dashboard pattern

Use when building the user's Finance Dashboard into a TrueWealth-style robo-advisor replacement: total-wealth allocation, ETF/self-managed position lookthrough, risk/return analytics, and rebalancing proposals.

## Goal

Build the Finance Dashboard first. Crypto_Agent is only a read-only data source for crypto/trading context, never the primary UI and never an execution authority.

The target is not a 1:1 TrueWealth clone. It should preserve familiar TrueWealth workflows while improving them across the user's full wealth:

- TrueWealth portfolio/ETFs
- self-managed ETFs
- single stocks
- cash accounts
- crypto holdings
- other assets as they become available

Dashboard may show exact amounts locally. Chat/status summaries should remain amount-light unless explicitly asked for a scoped finance report.

## Source inspection workflow

1. Load `finance-system-architecture`, `workspace-api-integrations`, and document/OCR skills if Drive PDFs/screenshots are involved.
2. Use configured `gog` account, typically:
   ```bash
   export HOME=/home/agent
   export XDG_CONFIG_HOME=/home/agent/.config
   export GOG_KEYRING_PASSWORD=<configured secret; never print>
   gog -a friday.uplink@gmail.com drive search "TrueWealth OR True Wealth" --json --results-only --no-input
   gog -a friday.uplink@gmail.com drive ls --parent <folder_id> --json --results-only --no-input
   gog -a friday.uplink@gmail.com drive download <file_id> --no-input
   ```
3. If `gog` reports `no TTY available ... set GOG_KEYRING_PASSWORD`, do not declare Drive inaccessible. Inspect existing configured scripts/cron prompts for the env-var setup pattern, but never print the password value.
4. Download Drive artifacts to a task-local temp folder, not a Git repo. Make a screenshot contact sheet for visual review and use `pdftotext`/OCR for PDFs.
5. Do not commit screenshots/PDFs or raw extracted finance values.

## TrueWealth UI features to reproduce

### Portfolio / strategy cockpit

TrueWealth-style top screen:

- total wealth and performance badge
- investment strategy status
- risk level/status
- diversification status
- investment universe
- currency hedging status
- central donut chart
- right-side `Investiert` vs `Ziel` allocation table
- actions: help, determine risk tolerance again, edit strategy

JARVIS improvement: add a concise advisor answer above the analytics: `status`, `top recommendation`, `main reason`, and `next safe action`.

### Donut drilldown

Core pattern:

```text
Total wealth
→ asset class (Aktien, Rohstoffe, Immobilien, Cash, Obligations, Crypto, ...)
→ subcategory (region/sector/instrument type)
→ effective instruments / ETF holdings / single stocks
```

Each level should show:

- donut chart
- breadcrumb/back action
- left risk/diversification context
- right `invested %`, `target %`, drift, and recommendation
- detail drawer for positions

Use progressive disclosure rather than one dense page.

### Detail tabs

Mirror and extend TrueWealth's tabs:

- Bestand / holdings
- Transaktionen
- Unternehmen / effective companies
- Instrumente
- Währungsrisiko
- Produkttyp
- Liquidität
- Gesamtkosten
- Produktkosten
- Datenqualität (JARVIS extension)
- Empfehlungen / Audit (JARVIS extension)

### Risk and return suite

TrueWealth has the useful `Risiko und Rendite` subnav:

- Performance
- Beitrag
- Benchmarking
- Projizierte Rendite
- Simulierte Historie
- Risiko

Implement equivalent pages:

- performance chart with portfolio vs deposits/withdrawals, TWR/MWR, range selector `1M/YTD/1J/5J/Max/calendar`, and toggle to show rebalancing events
- return contribution by asset class including local return, FX effects, hedging effects, fees/costs, total CHF contribution
- benchmarking vs multi-asset benchmark, target portfolio, MSCI World/SPI/S&P 500/cash/custom benchmark; include cost and target-weight toggles
- projected return with conservative/expected/optimistic paths, horizon, contributions and fee assumptions
- simulated history/backtest with yearly returns, drawdowns, best/worst periods, volatility
- risk histogram with loss/gain probability, horizon slider, mean return, volatility, and explanatory caution text

## Data model additions

Recommended class/table concepts:

```text
PortfolioSource
PortfolioSnapshot
PortfolioPosition
InstrumentMaster
InstrumentClassification
EtfLookthrough
TargetAllocation
AllocationBand
DiversificationScore
RebalanceProposal
AdvisorRecommendation
ScenarioResult
AdvisorAuditLog
```

Important fields for positions:

```text
source, account/depot, instrument_id, quantity, price, value_original,
currency, value_chf, asset_class, subcategory, region, sector,
risk_bucket, liquidity_bucket, cost_bucket, data_quality
```

ETF lookthrough should support:

```text
asset_class, region, country, sector, currency, holding/company
weight_pct, source, as_of_date, confidence
```

## Rebalancing policy

Default advisor behavior:

1. Compute full-wealth current allocation using ETF lookthrough where available.
2. Compare to target allocation and tolerance bands.
3. Prefer new deposits to correct underweights.
4. Avoid selling for tiny drift.
5. Recommend sells only for meaningful drift, concentration risk, strategy change, or risk reduction.
6. Account for costs, spreads, FX, and tax caveats as notes.
7. Produce preview proposals only; no broker execution.

Every proposal should include:

```text
action: BUY_MORE | REDUCE | HOLD | WATCH | REBALANCE | REVIEW_DATA
reason
affected positions
expected allocation effect
risks / caveats
data quality
execution_allowed=false
requires_user_confirmation=true
audit status
```

## UX guardrails

- Finance Dashboard is the primary UI; do not put this workflow primarily inside Crypto_Agent.
- Use filter chips everywhere: all assets, TrueWealth, self-managed ETFs, single stocks, cash, crypto, depot/source, currency, high-risk, only drifts, only recommendations.
- On iPad/mobile, show cards and bottom sheets/drawers instead of dense tables.
- Local dashboard may show exact amounts; command-center/chat summaries should avoid raw amounts unless the user explicitly requests a scoped report.
- Always label read-only/advisor mode and avoid dangerous buttons like `Jetzt kaufen` or `Jetzt verkaufen` in v1.
- Allowed buttons: details, postpone, mark reviewed, add note, generate report, prepare order proposal.
- Forbidden v1 buttons: execute order, auto-rebalance, broker submit, vault deposit.

## Crypto_Agent integration

Crypto_Agent contributes context only:

- crypto exposure
- v76 lifecycle scorecard
- strategy sleeves
- copytrading research status
- market/confluence state
- live/copy blocked status

Do not recommend increasing portfolio risk solely from bot signals. If bot evidence is paper/research/blocked, represent it as a risk/context note.

## Acceptance checks

Backend:

- snapshot covers all sources and partial filters
- positions normalize values, currencies, classification, and source
- no secrets, account IDs, credential paths, or raw Drive IDs in public API output
- advisor recommendations deterministic and auditable
- all execution flags remain false in v1

Frontend:

- overview answers status/recommendation/reason quickly
- donut drilldown works across at least asset class → subcategory → position
- TrueWealth-like `Investiert` vs `Ziel` table appears at each allocation level
- details are on-demand, not all visible at once
- mobile/iPad remains readable

Advisor:

- target allocation validates sum/bands
- diversification checks cover asset class, region, country, sector, currency, single-position, ETF overlap, liquidity, cost, and crypto risk
- rebalancing supports new-deposit-first mode
- recommendations write audit entries without execution side effects