# Command Dashboard Mock Gateway Hardening

Use after repository safety/bootstrap is complete and before building a real frontend or domain adapters for a sensitive multi-domain command dashboard.

## Trigger

The project has architecture/contracts and a mock-only API gateway skeleton, and the next risk is contract drift or UI sprawl before real integrations exist.

## Goals

- Keep gateway mock-only: no domain API calls, no DB/runtime reads, no POST/mutation flows.
- Align documentation, Pydantic models, JSON Schemas, OpenAPI, fixtures, and tests.
- Prepare local frontend development safely without public exposure.
- Freeze a concrete iPad/desktop UX blueprint before Vue/React implementation.

## Steps

1. **State the phase boundaries first**
   - No Vue/React UI yet unless explicitly approved.
   - No npm install unless the phase requires frontend code.
   - No real Finance/Health/AutoShorts calls.
   - No runtime paths, reports, uploads, restarts, confirms, applies, or iframes.

2. **Write/extend tests before contract changes**
   Add tests for the intended drift fixes and safety rules, e.g.:
   - enum restrictions fail on bad values (`ApprovalItem.status`).
   - newly required fields exist (`ReportLink.kind`).
   - package fixtures match golden fixtures byte-for-byte.
   - all GET responses pass forbidden-field checks.
   - OpenAPI contains expected paths and no runtime/path leaks.
   - CORS allows only configured local dev origins in development and is off in production.

3. **Patch contract drift deliberately**
   - Add missing contract fields/enums in Pydantic first.
   - Regenerate JSON Schemas from models.
   - Export OpenAPI from the FastAPI app without starting a server.
   - Update contract docs and changelog in the same commit.
   - Decide field naming explicitly; for ENV-aligned config, prefer `jarvis_*` Pydantic fields if docs and schemas use the same names.

4. **Prevent fixture drift**
   - Treat `docs/contracts/examples/*.json` as golden fixtures.
   - If package-local fixtures are needed, enforce byte-identical copies until a documented transform exists.
   - Add `test_fixture_sync.py` rather than relying on convention.

5. **Implement local-dev CORS safely**
   - Enable only when `JARVIS_ENV=development`.
   - Read origins from `JARVIS_DEV_CORS_ORIGINS`.
   - Default to localhost/127.0.0.1 dev frontend origins only.
   - Never use wildcard `*`.
   - Keep credentials disabled in MVP.
   - Document in the local-dev runbook and security architecture.

6. **Add OpenAPI export/check targets**
   - `scripts/export-openapi.py` imports the app and writes `schemas/openapi.json`; no server start.
   - `make openapi-export` writes it.
   - `make openapi-check` validates JSON and required endpoint paths.
   - Include `openapi-check` in `make verify`.

7. **Create the UX blueprint before UI code**
   Required docs for iPad/desktop command dashboards:
   - `docs/ux/product-spec.md`
   - `docs/ux/navigation.md`
   - `docs/ux/component-rules.md`
   - `docs/ux/ipad-pc-layouts.md`
   - `docs/ux/empty-error-loading-states.md`
   - `docs/ux/visual-language.md`
   - `docs/ux/page-inventory.md`
   - `docs/ux/ui-acceptance-checklist.md`

   Encode hard UI limits:
   - Home max 5 attention items.
   - Exactly 4 module cards.
   - Max 3 KPIs/card.
   - No tables on Home.
   - No iframes.
   - iPad bottom nav, desktop sidebar.
   - Touch targets >= 44 px.
   - No hover-only behavior.
   - No exact Finance values or Health raw data.

8. **CI template without side effects**
   A safe template can run on push/PR with Python 3.11:
   - install only mock gateway dev deps.
   - run `make verify`, `make test-gateway`, `make openapi-check`.
   - no secrets, deployment, Tailscale, runtime paths, or domain calls.

## Pitfalls

- Do not include the actual forbidden field names in response payloads or OpenAPI examples just because the endpoint is called redaction-policy; use a safe pointer like `see docs/security/forbidden-fields.md`.
- Avoid broad safety-script allowlists like `apps/**`. If tests need unsafe sample strings, add narrow file-specific allowlist entries.
- Makefile inline Python is brittle; keep commands one-line or move logic to scripts.
- Schema generation after model changes is easy to forget — run it before tests/commit.
- If GitHub workflow files are added, verify the push actually succeeds; token workflow permissions may be required.

## Verification

Run and report real outputs:

```bash
make openapi-export
make openapi-check
make test-gateway
python3 scripts/verify-repo-safety.py
make verify
git status --short
git diff --stat
```

Only commit/push after all checks pass and remote SHA is verified.