feat: add observability api foundation

docs/admin-api.md

@@ -126,6 +126,14 @@
 - `GET /api/admin/workspaces/{workspace_id}/usage/operations/{operation_id}`
 - `GET /api/admin/workspaces/{workspace_id}/usage/agents/{agent_id}`
 
+Контракт:
+
+- `GET /logs` поддерживает `level`, `search`, `source`, `operation_id`, `agent_id`, `period`, `limit`;
+- `period` использует UI-friendly значения `30m`, `1h`, `6h`, `24h`, `7d`, `30d`, `90d`, `this_month`;
+- `source` различает `admin_test_run` и `agent_tool_call`;
+- `GET /usage` возвращает `summary`, `timeline`, `operations`, `agents` одним ответом;
+- detail endpoints по operation и agent возвращают rollup для выбранного периода.
+
 ## 6. Page-to-endpoint mapping
 
 ### Operations catalog
@@ -185,6 +193,11 @@
 - breakdown по agent;
 - CSV export.
 
+Текущая реализация:
+
+- summary и breakdown считаются по `invocation_logs`;
+- materialized `usage_rollups` остаются совместимым storage-слоем для дальнейшей оптимизации, но не являются единственным source of truth в MVP.
+
 ## 7. Принцип совместимости
 
 Если UI расходится с текущим backend, приоритет отдается целевой продуктовой модели, но конфликт должен быть явно разобран в `docs/as-is-to-be.md` до начала реализации.