# Recoil Console v2

The unified desktop + mobile production console for the Recoil engine.

## Layout

```
console-v2/
├── CONTEXT.md           — Ubiquitous language (Law 9)
├── .out-of-scope/       — Explicitly rejected ideas (Law 14)
├── packages/
│   ├── contracts/       — Typed contracts (Pydantic codegen + zod manual)
│   ├── fixtures/        — Static demo data (P1–P12)
│   ├── http-adapter/    — Live engine binding (P17+)
│   ├── design-system/   — Tokens + primitives
│   ├── desktop/         — 3-panel React shell (P4)
│   └── mobile/          — 4-tab mobile shell (P13)
└── scripts/
    └── launchagent/     — Studio LaunchAgent (always-on backend)
```

## Backend

The FastAPI backend lives at `recoil/api/` (sibling to `console-v2/`) and runs on
port **8431** via the LaunchAgent installed by `scripts/launchagent/install.sh`.

State is persisted to SQLite WAL at `~/.recoil/v2_workspace_state.db`
(deliberately OUTSIDE Dropbox — sync-mid-write corrupts WAL).

## Phase 1 surface

- `GET /api/health` — liveness probe.
- `GET /api/workspace-state/{id}` — read opaque workspace JSON.
- `POST /api/workspace-state/{id}` — upsert opaque workspace JSON.
- `DELETE /api/workspace-state/{id}` — remove workspace JSON.

Engine entity routes land in Phase 16. Mutations + EventBus SSE land in Phase 19.

## Quickstart

```bash
# install deps
pnpm install --frozen-lockfile=false

# typecheck everything
pnpm -r typecheck

# install backend on Studio (idempotent)
bash scripts/launchagent/install.sh

# verify
curl -fsS http://127.0.0.1:8431/api/health
```

## Where state lives

- Engine entities: server SSOT (FastAPI + Pydantic) → codegen TS via `@recoil/contracts`.
- Workspace state: server SSOT (FastAPI + SQLite) ↔ TypeScript zod-typed in
  `@recoil/contracts/manual`.
- Selection / per-session caches: React state, ephemeral, NOT persisted.