microdao-daarion/docs/runbook/team-onboarding-console.md

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

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)

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), потім:

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

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

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

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

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

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

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:

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

---

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

Перевірити стан run:

GET /api/runbooks/runs/{run_id}
# → status, current_step, кожен крок зі статусом

Подивитись деталі кроку — у полі result:

• exit_code — для script кроків
• stderr_tail — лог помилки
• timeout: true — якщо перевищено timeout
• ok: false — крок не пройшов

Abort run:

POST /api/runbooks/runs/{run_id}/abort
{"operator_id": "your_name"}

---

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

Обов'язково перед:

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

---

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

# Список останніх 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