# Team Onboarding: Sofiia Console + Runbook Runner (v1)

Документ для нових членів команди. Один раз прочитати, далі — практика.

---

## 1. Доступ до Console

**URL:** https://console.daarion.space

### Отримання ключа

1. Запитати у адміністратора персональний ключ.
2. Адміністратор генерує: `python3 -c "import secrets; print(secrets.token_urlsafe(32))"`
3. Ключ додається до `SOFIIA_CONSOLE_TEAM_KEYS` на NODA1 (`name:key` формат).
4. Перезапуск контейнера не потрібен при зміні env — тільки `docker compose up -d`.

### Логін

1. Відкрити https://console.daarion.space
2. Ввести свій ключ у форму Login
3. Cookie встановлюється автоматично на 7 днів
4. Перевірити: `GET /api/auth/check` → `{"ok": true, "identity": "user:<your_name>"}`

### Revocation

Якщо ключ скомпрометований — повідомити адміністратора. Він видаляє `name:key` з env та перезапускає контейнер.

---

## 2. Запуск Rehearsal / Release Run

### Крок 1 — Створити run

```bash
POST /api/runbooks/runs
{
  "runbook_path": "runbook/rehearsal-v1-30min-checklist.md",
  "operator_id": "your_name",
  "node_id": "NODA1",
  "sofiia_url": "http://localhost:8002"
}
```

Отримаєш `run_id`. Зберегти його.

### Крок 2 — Auto steps (натискати `Next`)

```bash
POST /api/runbooks/runs/{run_id}/next
```

Автоматично виконуються:

| # | Крок | Тип |
|---|------|-----|
| 0 | Health check `/api/health` → 200 | http_check |
| 1 | Metrics `/metrics` → 200 | http_check |
| 2 | Audit auth `/api/audit` → 401 | http_check |
| 3 | Preflight script (STRICT=1) | script |
| 4 | Redis idempotency smoke | script |
| 5 | Generate evidence script | script |

### Крок 3 — Manual steps

Runner зупиниться і поверне `{"type": "manual", "instructions_md": "..."}`.

Виконати дію (наприклад, restart), потім:

```bash
POST /api/runbooks/runs/{run_id}/steps/{step_index}/complete
{
  "status": "ok",
  "notes": "restart completed",
  "operator_id": "your_name"
}
```

**Observation Window step** — внести метрики в `data`:

```json
{
  "status": "ok",
  "notes": "observation 15 min",
  "data": {
    "5xx_total": 0,
    "replays_delta": 0,
    "rate_limited_chat_delta": 0,
    "send_latency_p95_ms": null
  }
}
```

### Крок 4 — Артефакти

```bash
POST /api/runbooks/runs/{run_id}/evidence
POST /api/runbooks/runs/{run_id}/post_review
```

Де знаходяться файли:

```bash
GET /api/runbooks/runs/{run_id}/artifacts
# → {"files": [{"name": "release_evidence.md", "path": "...", "bytes": 2048}, ...]}
```

Або напряму на NODA1: `${SOFIIA_DATA_DIR}/release_artifacts/<run_id>/`

---

## 3. Audit trail

**Хто може читати audit:**

| Роль | `/api/audit` |
|------|-------------|
| `operator` (головний ключ) | ✅ |
| `user:<name>` (team key) | ✅ |
| localhost без ключа | ❌ (strict auth) |
| без ключа взагалі | ❌ |

> Audit endpoint **не має** localhost bypass. Потрібен ключ завжди.

**Читання audit trail:**

```bash
curl -H "X-API-Key: $YOUR_KEY" \
  "https://console.daarion.space/api/audit?limit=20"
```

---

## 4. Якщо щось ламається

**Перевірити стан run:**
```bash
GET /api/runbooks/runs/{run_id}
# → status, current_step, кожен крок зі статусом
```

**Подивитись деталі кроку** — у полі `result`:
- `exit_code` — для script кроків
- `stderr_tail` — лог помилки
- `timeout: true` — якщо перевищено timeout
- `ok: false` — крок не пройшов

**Abort run:**
```bash
POST /api/runbooks/runs/{run_id}/abort
{"operator_id": "your_name"}
```

---

## 5. Коли запускати Rehearsal

Обов'язково перед:
- релізом sofiia-console
- підключенням нової ноди
- значними змінами в конфігурації агентів
- масштабуванням (нові ноди в кластері)

---

## 6. Корисні команди (quick ref)

```bash
# Список останніх runs (через API)
GET /api/runbooks/runs  # якщо є list endpoint

# Health console
GET /api/health

# Метрики
GET /metrics

# Версія
GET /api/meta/version

# Auth check
GET /api/auth/check
```

---

_Версія документа: v1 · console.daarion.space · Sofiia Console `e0bea910`_