docs(dox): build out the DOX AGENTS.md hierarchy

Root Child DOX Index assembled, plus a per-module AGENTS.md across the tree (core/*, infrastructure/*, apps/*, testing/*, and docs/examples/frontend/etc), each following the DOX section shape: Purpose, Ownership, Local Contracts, Work Guidance, Verification, Child DOX Index.
2026-06-28 20:43:27 +04:00
parent 1cb7fec677
commit d26f20c316
48 changed files with 1783 additions and 0 deletions
@@ -0,0 +1,45 @@
+# apps/server
+
+## Purpose
+
+Ktor HTTP + WebSocket server. Exposes the orchestration kernel to CLI and TUI clients, manages session lifecycle, and streams events over WebSocket.
+
+## Ownership
+
+All sources under `apps/server/src/`.
+
+## Local Contracts
+
+### HTTP REST routes
+- `GET/POST /sessions` — session browse and start
+- `POST /sessions/{id}/resume` — resume a session after restart
+- `GET/POST /tasks` — task listing and management
+- `GET/POST /providers` — provider configuration
+- `GET/POST /workflows` — workflow management
+- `GET /health` — health report (probes: event-store, llama-server, disk watermark)
+- `GET /stats` — metrics report (MetricsProjection)
+
+### WebSocket protocol (`/ws`)
+- **ServerMessage** (server → client): sealed hierarchy — `SessionMessage` (event-derived, carries `sequence` + `sessionSequence`) and `NonEventMessage` (control/infra). Variants include session lifecycle, approval requests, clarification requests, narration, proposed workflows, health/metrics pushes.
+- **ClientMessage** (client → server): `StartSession`, `ApproveToolCall`, `RejectToolCall`, `GrantApproval`, `AnswerClarification`, `SetChatMode`, and others.
+- All protocol types are in `protocol/` (Dtos.kt, ServerMessage.kt, ClientMessage.kt, ProtocolSerializer.kt).
+
+### Health monitoring
+- `HealthMonitor` runs probes on a schedule; results folded via `HealthProjection` into `HealthState`.
+- Adding a probe: implement `HealthProbe`, register in `ServerModule`.
+
+## Work Guidance
+
+- Follow Kotlin rules in root CLAUDE.md.
+- Route handlers must not contain domain logic — delegate to core services injected via `ServerModule`.
+- New WS message variants require updating both `ServerMessage`/`ClientMessage` sealed classes and `ProtocolSerializer`.
+
+## Verification
+
+```
+./gradlew :apps:server:test --rerun-tasks
+```
+
+## Child DOX Index
+
+No child AGENTS.md (leaf module).