# FinanceManager Read-only Adapter

Phase 5A introduces the first real domain integration. It is strictly read-only and defaults to mock mode. The adapter returns the existing `ModuleSnapshot` contract; the frontend receives no special finance structure.

## Modes

- `FINANCE_ADAPTER_MODE=mock` — default; existing synthetic Finance snapshot.
- `FINANCE_ADAPTER_MODE=live_readonly` — calls FinanceManager with HTTP GET only. Requires `FINANCE_API_BASE_URL`.
- `FINANCE_ADAPTER_MODE=disabled` — returns a safe degraded/disabled Finance snapshot.

Rollback:

```bash
FINANCE_ADAPTER_MODE=mock
```

## Environment

```bash
FINANCE_ADAPTER_MODE=mock
FINANCE_API_BASE_URL=
FINANCE_LEGACY_DASHBOARD_URL=
FINANCE_READ_TIMEOUT_SECONDS=3
ALLOW_EXACT_FINANCE_VALUES=0
```

`ALLOW_EXACT_FINANCE_VALUES=1` is rejected by runtime config and exact values remain blocked.

## Allowed FinanceManager endpoints

The live adapter calls only:

- `GET /api/health`
- `GET /api/provider/status`
- `GET /api/runtime/status`
- `GET /api/system/status`
- `GET /api/budget/import-status-audit`

No POST, PUT, PATCH, DELETE, confirm, restart, archive, generate or update endpoint exists in the adapter.

## Visible in JARVIS Dashboard

Allowed summary fields only:

- Finance module status: `ok`, `attention`, `degraded`, `offline`
- Review item count
- Provider connected: yes/no/unknown
- Runtime reachable: yes/no
- Import audit warning status
- Last successful sync timestamp if safe
- Source health metadata: reachable, stale, source_type, contract_version, last_success_at, last_attempt_at
- Read-only `/finance` action
- Optional local legacy dashboard link from `FINANCE_LEGACY_DASHBOARD_URL`

## Never visible

- exact amounts
- account names or account identifiers
- transactions
- portfolio values
- budget sums
- category amounts
- CSV/XLSX/PDF paths
- DB/runtime/local paths
- Drive links
- tokens/secrets/password/API keys

## Smoke test

Requires a local FinanceManager and local base URL only:

```bash
export FINANCE_API_BASE_URL=http://127.0.0.1:<finance-port>
make smoke-finance-live-readonly
```

The smoke starts a local JARVIS Gateway in `live_readonly` mode and checks `/api/modules` and `/api/overview` for forbidden finance strings.


## Phase 5B Finance Live Smoke

FinanceManager was validated locally in read-only mode against `http://127.0.0.1:8001`. The local start shape was `python -m uvicorn jarvis_finance.api.main:app --host 127.0.0.1 --port 8001` from the FinanceManager source repository using the existing local venv.

Validation command:

```bash
FINANCE_API_BASE_URL=http://127.0.0.1:8001 \
FINANCE_ADAPTER_MODE=live_readonly \
ALLOW_EXACT_FINANCE_VALUES=0 \
make smoke-finance-live-readonly
```

The smoke checks allowed GET endpoints, `/api/modules`, `/api/overview`, `source_type=http_api`, safe Finance `ModuleSnapshot` shape, and forbidden string absence. Raw Finance responses are not committed; see `docs/integrations/finance-live-contract-review.md` and `docs/integrations/finance-sanitizer-mapping.md` for redacted structural mapping. Rollback remains `FINANCE_ADAPTER_MODE=mock`.