# Command Dashboard Read-only Domain Adapter Pattern

Use when adding the first real domain integration behind a sensitive multi-domain command dashboard while preserving the existing frontend contract.

## Core rule

Default remains `mock`. Live access must be explicit (`*_ADAPTER_MODE=live_readonly`) and read-only. The frontend should continue consuming the same gateway `ModuleSnapshot`/overview contract — no special UI payload shape.

## Adapter modes

Implement three modes:

- `mock`: default; existing synthetic adapter.
- `live_readonly`: explicit ENV opt-in; requires a base URL; calls only approved `GET` endpoints.
- `disabled`: returns a safe degraded/disabled snapshot; no domain access.

Reject dangerous config early. For finance, `ALLOW_EXACT_FINANCE_VALUES=1` should fail config validation or still be ignored by the adapter.

## TDD slice

1. Write failing tests first for sanitizer, live adapter, mode wiring, redaction, and gateway resilience.
2. Verify RED on missing modules/API.
3. Implement only enough to pass.
4. Run domain gateway tests, dashboard tests/build, repo safety, full verify, and local E2E/UX if browsers are present.

## Sanitizer-first design

- Treat domain responses as hostile.
- Build an allowlisted `ModuleSnapshot` from safe derived fields only.
- Drop everything not explicitly needed.
- Validate with Pydantic `ModuleSnapshot`.
- Run redaction/forbidden-field checks after sanitizing and before returning.

For finance, allow only summaries such as review count, provider connected yes/no, runtime reachable yes/no, import audit status, and safe timestamps. Never expose amounts, account names, transactions, portfolio values, budgets, file paths, Drive links, tokens, secrets, or DB/runtime paths.

## Gateway resilience

- `/api/overview` must remain 200 even when the live adapter is offline or an endpoint fails.
- Convert live failures into offline/degraded snapshots with redacted messages.
- Other modules stay mock unless explicitly in scope.
- No mutation endpoints in adapter code; no POST/PUT/PATCH/DELETE helpers.

## Local live smoke

Add an optional smoke target outside `make verify`, because it requires a running domain backend:

- Check required base URL is set.
- Restrict smoke base URL to local hosts unless the user explicitly approves broader policy.
- Start Jarvis Gateway in `live_readonly` mode.
- Fetch `/api/modules` and `/api/overview`.
- Assert no forbidden strings, amounts, paths, or secrets leak.
- If backend is absent, report exact reason; do not claim live smoke ran.

## Safety-script pitfall

Dedicated sanitizer/tests may intentionally contain forbidden terms as blocklists or dirty fixtures. Add only targeted allowlist entries for those exact files. Never allowlist whole adapter/test directories or page/store components.