docs(snapshot): sync workspace documentation

2026-03-29 13:14:30 +02:00
parent 93a6e4aa2f
commit 0d3d110026
37 changed files with 8500 additions and 123 deletions
--- a/observer-right-rail-v1.md
+++ b/observer-right-rail-v1.md
@@ -0,0 +1,126 @@
+# Observer Right Rail V1
+
+Ten dokument opisuje kompaktowy widget `Bot State Machine` w prawej kolumnie visualizera.
+
+## Cel
+
+Prawy panel ma pokazywać operatorowi stale widoczny summary stanu bota bez przełączania na dolny tab `Bot`.
+
+Widget nie zastępuje pełnego panelu debugowego na dole.
+
+Podział odpowiedzialności:
+- prawa kolumna: aktualny stan operacyjny bota
+- dolny tab `Bot`: szczegóły, event feed, feature snapshot, debug
+
+## Źródło danych
+
+Widget używa dokładnie tego samego payloadu co dolny panel:
+
+- `GET /api/v1/bots?limit=100`
+- `GET /api/v1/bots/:id/state`
+- `GET /api/v1/bots/:id/events?limit=24`
+
+Nie wprowadza nowych endpointów.
+
+## Schema summary
+
+Widget czyta tylko podzbiór istniejącego kontraktu `bot_state.state`.
+
+### `bot_config`
+
+- `id`
+- `name`
+- `market_name`
+- `mode`
+- `kill_switch`
+
+### `bot_state`
+
+- `last_heartbeat_at`
+- `last_error`
+- `state`
+
+### `bot_state.state`
+
+Pola używane w prawym panelu:
+
+```json
+{
+  "status": "observe",
+  "mode": "observe",
+  "observe_only": true,
+  "last_snapshot": {
+    "query_latency_ms": 82,
+    "data_age_ms": 214
+  },
+  "last_gates": {
+    "fresh": true,
+    "spread_ok": true,
+    "slippage_ok": true,
+    "depth_ok": true,
+    "all": true
+  },
+  "last_decision": {
+    "side": "long",
+    "confidence": 0.72,
+    "target_notional_usd": 500,
+    "skip_reason": null
+  },
+  "counters": {
+    "loops": 1012,
+    "errors": 1
+  }
+}
+```
+
+## Sekcje widgetu
+
+### 1. State Machine
+
+Stała linia etapów:
+
+- `off`
+- `observe`
+- `paper`
+- `trade`
+- `panic`
+
+Aktywny etap wybieramy z:
+1. `state.status`
+2. `state.mode`
+3. `bot.mode`
+
+Jeśli `kill_switch === true`, etap `panic` ma priorytet wizualny.
+
+### 2. Runtime Summary
+
+- `desired mode`
+- `runtime status`
+- `heartbeat age`
+- `data age`
+- `query latency`
+
+### 3. Decision Summary
+
+- `side`
+- `confidence`
+- `target_notional_usd`
+- `skip_reason` jeśli istnieje
+
+### 4. Gates
+
+Kompaktowe chipy:
+- `fresh`
+- `spread`
+- `slippage`
+- `depth`
+
+## Zakres V1
+
+V1 dodaje tylko read-only summary do prawej kolumny.
+
+Poza zakresem:
+- mutacje `mode`
+- `kill-switch` z UI
+- event feed po prawej
+- pełna historia decyzji po prawej