# JARVIS Command Dashboard

## Local operator demo

```bash
make handoff
# opens JARVIS + existing Finance/AutoShorts dashboards as runtime-configured link-only handoffs
make handoff-stop

make demo
# mock-only fallback; open the Frontend URL printed by the command, usually http://127.0.0.1:5173
make demo-stop
```

`make demo` starts the API Gateway and Vue Dashboard locally in `demo_mock` mode. If a default port is occupied, the script selects a free localhost port and prints the actual URLs. No domain runtimes, external services, uploads, renders, publishing actions or mutations are enabled. Legacy dashboard handoff buttons are link-only and runtime-configured; missing links appear disabled. Tailscale/Tailnet test access can be bound at runtime by the operator, but IPs and ports must never be hardcoded. See `docs/runbooks/operator-test-release.md` for the operator checklist.

JARVIS Command Dashboard is the future central, local/Tailscale-reachable command surface for existing domain systems such as FinanceManager, HealthManager, AutoShorts and JARVIS/Hermes system status.

## What it is

- A Command Layer over existing systems.
- A read-only-first overview for module health, safe KPIs, attention items and legacy links.
- A contract-driven integration point using redaction by default.
- An iPad-first operational cockpit.

## What it is not

- Not a replacement for FinanceManager, HealthManager or AutoShorts.
- Not a shared super database.
- Not a place for Health/Finance raw data.
- Not a public internet service.
- Not a write/action automation layer in MVP.

## Current status

Current phase: **Mock-only Gateway + Mock-only iPad-first Frontend Shell**.

Implemented so far:

- inventory docs
- architecture docs
- security docs
- ADRs
- contract examples
- Health Safe Status Marker contract and safe-marker adapter (`HEALTH_ADAPTER_MODE=safe_marker`)
- AutoShorts read-only status adapter (`AUTOSHORTS_ADAPTER_MODE=mock|disabled|local_probe|live_readonly`)
- AutoShorts local live read-only contract review (`docs/integrations/autoshorts-live-contract-review.md`)
- repository safety bootstrap
- mock-only FastAPI Gateway skeleton
- Pydantic contracts
- JSON Schema export
- mock adapters and tests
- Vue/Vite/TypeScript dashboard shell
- Pinia Store + API Client integration against mock Gateway
- local E2E/Visual smoke harness for mock Gateway + mock Dashboard
- controlled fixture fallback only for test/demo mode
- iPad BottomNav and desktop Sidebar
- Home overview with 4 module cards, max 5 attention items and no tables

Still not implemented:

- real FinanceManager adapter
- real HealthManager adapter
- AutoShorts live adapter
- write actions
- report generation
- uploads/restarts/confirms
- iframes
- exact Finance values or Health raw details

## Safety check

Run before every commit:

```bash
make verify
```

CI template:

- `.github/workflows/verify.yml`
- safe/mock-only
- no secrets
- no deployment
- runs `make verify`, `make test-gateway`, `make openapi-check`

## Gateway tests

```bash
make test-gateway
```

## Local mock Gateway

```bash
make gateway-dev
```

This starts only on `127.0.0.1` with demo/mock data.

## Local mock Dashboard

Install once:

```bash
cd apps/dashboard && npm install
```

Run tests/build:

```bash
make dashboard-test
make dashboard-build
make smoke-local
make e2e-local
```

Start frontend:

```bash
make dashboard-dev
```

Frontend URL: `http://127.0.0.1:5174`.

## Local E2E / Visual Smoke

`make e2e-local` starts the mock Gateway and Dashboard on `127.0.0.1` and runs Playwright smoke tests against the real local UI/API flow. Default ports remain Gateway `8080` and Dashboard `5174`, but the harness chooses free alternative ports when those are occupied. It never kills foreign processes.

Optional overrides:

```bash
JARVIS_E2E_GATEWAY_PORT=18080 JARVIS_E2E_DASHBOARD_PORT=15174 make e2e-local
```

If Playwright browsers are missing:

```bash
cd apps/dashboard
npx playwright install --with-deps chromium
```

Artefacts stay ignored: `.tmp/`, `tmp/`, `test-results/`, `playwright-report/`.

## Security rules

Never commit:

- real Health or Finance data
- SQLite databases
- CSV/XLSX/PDF exports or reports
- OAuth files
- tokens/secrets/API keys
- runtime logs
- media/raw files

Read-only first remains mandatory. Future write actions require Preview -> Confirm -> Audit and are currently disabled.

## Key documents

- [Concept Review](docs/inventory/concept_review.md)
- [Integration Candidates](docs/inventory/integration_candidates.md)
- [Architecture Overview](docs/architecture/overview.md)
- [Security Architecture](docs/architecture/security.md)
- [Module Contracts](docs/architecture/module-contracts.md)
- [Forbidden Fields](docs/security/forbidden-fields.md)
- [Git Safety](docs/security/git-safety.md)
- [Repository Safety Rules](docs/security/repo-safety-rules.md)
- [Developer Workflow](docs/runbooks/developer-workflow.md)
- [API Gateway Local Dev](docs/runbooks/api-gateway-local-dev.md)
- [Dashboard Local Dev](docs/runbooks/dashboard-local-dev.md)
- [Visual QA Checklist](docs/qa/visual-qa-checklist.md)
- [E2E Smoke Report Template](docs/qa/e2e-smoke-report-template.md)
- [UX Product Spec](docs/ux/product-spec.md)
- [UI Acceptance Checklist](docs/ux/ui-acceptance-checklist.md)


## Phase 4D UX Acceptance

The mock-only Dashboard now includes a read-only module detail layout for Finance, Health, AutoShorts and System. `/autoshorts` is available as a safe mock detail route because AutoShorts is a first-class module card. Detail pages share ModuleDetailShell components, show max 3 safe KPIs, source health metadata, blocked actions and safe links only.

Local commands:

```bash
make dashboard-test
make dashboard-build
make e2e-local
make ux-acceptance
```

Still deliberately absent: real adapters, Health DB, Finance runtime, POST/mutation flows, uploads, report generation, iframes, charts, exact finance values and Health raw data.


## FinanceManager Read-only Adapter

Phase 5A adds an optional FinanceManager read-only adapter behind `FINANCE_ADAPTER_MODE`. Default is `mock`. `live_readonly` requires `FINANCE_API_BASE_URL` and calls only the approved GET endpoints documented in `docs/integrations/finance-readonly-adapter.md`. `disabled` returns a safe degraded Finance snapshot. Exact Finance values remain blocked; `ALLOW_EXACT_FINANCE_VALUES=1` is rejected.

Smoke, only with local FinanceManager running:

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

Rollback:

```bash
FINANCE_ADAPTER_MODE=mock
```


## 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`.

## HealthManager safe local probe (Phase 6A)

HealthManager is integrated more conservatively than Finance. The default remains `HEALTH_ADAPTER_MODE=mock`. The optional `local_probe` mode reads only local filesystem metadata from `HEALTH_RUNTIME_BASE` and emits a redacted `ModuleSnapshot` with status/freshness counts only.

```bash
HEALTH_ADAPTER_MODE=local_probe \
HEALTH_RUNTIME_BASE=/absolute/local/health/runtime \
ALLOW_HEALTH_DETAIL_LINKS=0 \
make smoke-health-local-probe
```

Rollback:

```bash
HEALTH_ADAPTER_MODE=mock
```

The probe must not read medical files, database rows, PDFs, OCR output, tracker exports, report text, or raw JSON. It never returns paths or filenames.

## Health safe inventory gate

Health integration remains limited to safe status metadata. Phase 6B classifies HealthManager sources into safe-now metadata, future-gated sources, and forbidden sources. The current adapter must not parse Health database rows, reports, PDFs, OCR, tracker exports, logs, or source documents.