# Manual Equity/ETF Entry Wizard

Use this reference when the user rejects productive broker/DOCX Equity/ETF imports and wants reliable manual entry instead.

## Trigger

- DOCX/broker statement extraction is structurally unsafe.
- ISIN coverage is low, ticker/name mappings are ambiguous, or cost basis is missing.
- Qwen/LLM resolver cannot produce additional exact mappings.
- User explicitly says not to import PostFinance/True Wealth/Raiffeisen files productively.

## Required pivot

Stop the productive DOCX import path. Keep existing staging/review queues as reminders or admin review surfaces only. The main user path becomes an audited manual wizard:

1. Search instrument by ISIN, name, or ticker.
2. Show candidate list.
3. Require explicit user selection if more than one result or if identity is not exact.
4. Allow manual instrument creation with warnings.
5. Capture depot/account, quantity, date, cost-basis/FX information and note.
6. Show a review summary.
7. Save only after explicit confirmation.
8. Write audit log and Data Quality alerts.

## Instrument search rules

Priority order:

1. ISIN
2. ISIN + name
3. Ticker + exchange + currency
4. Name search with candidate list
5. Manual creation

Rules:

- ISIN is primary for equities/ETFs, but a single ISIN can have multiple exchange/currency listings.
- Ticker alone is never globally unique and must never auto-import or auto-select.
- Name search returns candidates only; selection is manual.
- If provider/API key is unavailable, show a clear warning and continue with local/manual workflow.
- External provider calls happen only on explicit user search action, never on normal dashboard render.
- Cache provider/search results locally where useful.
- For concrete implementation, prefer provider order: local SQLite catalog → OpenFIGI → Finnhub symbol lookup → Financial Modeling Prep search → manual creation.
- Load provider keys from runtime-only env or `.env` files outside Git (`~/jarvis_runtime/finance-system/secrets/.env` or `~/jarvis_runtime/finance-system/.env`); missing keys are warnings, not crashes.
- Do not send holdings, balances, cost basis, account IDs, notes, raw documents, or source files to public providers or LLMs.

Candidate list should show user-facing fields only: name, ISIN, ticker, exchange, currency, asset class, data source, mapping status, local last price and local price date if available.

## Manual position / transaction write rules

Supported MVP actions:

- `initial_position_snapshot`
- `buy`
- `partial_sell`
- `full_sell`
- `dividend`
- `etf_distribution`
- `fee`
- `manual_adjustment`

For initial snapshots:

- Do not invent purchase history.
- Cost basis is optional; missing cost basis becomes `cost_basis_uncertain` and must not be treated as zero.
- Prevent duplicate initial snapshots for the same account/instrument unless a correction/void workflow is explicitly used.

For all writes:

- Require a review/confirm step.
- Write an audit-log entry.
- Do not silently overwrite instruments, positions, holdings, or transactions.
- Use exact Decimal/Text handling for quantities and monetary/FX inputs where precision matters.
- Require notes for `manual_adjustment` or incomplete history.

## FX and CHF handling

- Store original currency.
- For USD/EUR/non-CHF events, store FX rate and FX source when known.
- If FX is missing, persist `fx_status=missing`/`manual_override_required` and create a deduplicated Data Quality alert.
- Current valuation may later use current prices and current FX, but historical performance remains incomplete when historical FX or cost basis is missing.

## UX rules

User Mode should look like a portfolio-app wizard, not an admin table:

1. Suchen
2. Instrument auswählen
3. Depot & Menge
4. Einstand/Datum/Notiz
5. Review
6. Bestätigen

Hide in User Mode:

- `instrument_id`
- `source_id`
- `catalog_entry_id`
- raw provider fields
- long internal IDs
- technical JSON/debug tables

Keep technical detail in Admin/Review/Data Quality views.

## Platform/account setup

When moving to manual entry, ensure placeholder/manual-entry platforms and brokerage accounts exist for:

- PostFinance
- True Wealth
- Raiffeisen
- Other/Anderes Konto

This setup must not import holdings or broker documents.

## Test checklist

Add/keep tests for:

- ISIN search returns candidates.
- Name search returns a candidate list.
- Ticker alone does not auto-import or auto-select.
- Multiple hits require manual selection.
- Manual instrument creation works and warns where identity is incomplete.
- Initial snapshot from selected instrument.
- Missing cost basis produces `cost_basis_uncertain`.
- USD/EUR/non-CHF event with FX fields.
- Missing FX produces `fx_status=missing`/Data Quality alert.
- Review confirmation is required before save.
- Audit log is written for saves.
- Dashboard render performs no live provider/API call.
- User Mode does not expose technical IDs.
- Git-safety remains clean after pytest cache cleanup.

## Reporting to the user

Report aggregate implementation state only. Do not print real prices, quantities, values, position names from private documents, source rows, or raw broker extracts.