docs: add docs folder (architecture, developer, usage); update README; wire probe TTL cache + concurrency notes into docs

docs/usage/api.md

@@ -0,0 +1,38 @@
+# Usage: API Examples
+
+## Projection Query via Gateway (HTTP → gRPC)
+```bash
+curl -sS -X POST \
+  -H "x-tenant-id: tenant-a" \
+  -H "x-correlation-id: demo" \
+  -H "traceparent: 00-00000000000000000000000000000001-0000000000000001-01" \
+  http://localhost:8080/v1/query/User \
+  -d '{"uqf":"{\"eq\":{\"id\":\"u1\"}}"}'
+```
+
+## Projection Query via gRPC (direct, internal)
+```bash
+grpcurl -d '{"tenant_id":"tenant-a","view_type":"User","uqf":"{}"}' \
+  -H 'x-tenant-id: tenant-a' \
+  -H 'x-correlation-id: demo' \
+  -H 'traceparent: 00-00000000000000000000000000000001-0000000000000001-01' \
+  -plaintext localhost:9090 projection.gateway.v1.QueryService/ExecuteQuery
+```
+
+## Aggregate Command via Gateway (HTTP → gRPC)
+```bash
+curl -sS -X POST \
+  -H "x-tenant-id: tenant-a" \
+  -H "x-correlation-id: demo" \
+  -H "traceparent: 00-00000000000000000000000000000001-0000000000000001-01" \
+  http://localhost:8080/v1/aggregate/BankAccount/command \
+  -d '{"id":"acc-1","command_type":"Open","payload":{"owner":"Alice"}}'
+```
+
+## Runner Admin via Gateway (HTTP → gRPC)
+```bash
+curl -sS -X POST \
+  -H "x-tenant-id: tenant-a" \
+  -H "authorization: Bearer <token>" \
+  http://localhost:8080/admin/runner/drain?wait_ms=0
+```

docs/usage/nats.md

@@ -0,0 +1,17 @@
+# NATS Reference
+
+## Subjects
+- Aggregate events: tenant.<tenant>.aggregate.<type>.<id>
+- Workflow commands/events: shared helpers define exact formats
+
+## Headers (Producers)
+- tenant-id: required
+- Nats-Msg-Id: idempotency key (event_id, command_id, etc.)
+- x-correlation-id and correlation-id
+- traceparent and trace-id
+
+## Consumers
+- AckPolicy::Explicit
+- ack_wait: bounded timeout
+- max_deliver: bounded
+- max_ack_pending: aligned with concurrency

docs/usage/quickstart.md

@@ -0,0 +1,26 @@
+# Quick Start
+
+## Compose
+```bash
+docker compose up -d --build
+```
+
+Full stack with observability:
+```bash
+docker compose -f docker-compose.yml -f observability/docker-compose.yml up -d --build
+```
+
+## Local Dev (minimal)
+- Start NATS locally
+- Run services:
+```bash
+cargo run -p aggregate
+cargo run -p projection
+cargo run -p runner
+cargo run -p gateway
+```
+
+## Verify
+- Gateway: GET /health, /ready, /metrics
+- Projection: GET /health, /ready, /metrics
+- Runner: GET /health, /ready, /metrics