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

docs/architecture/overview.md

@@ -0,0 +1,21 @@
+# Architecture Overview
+
+## Monorepo
+- Rust workspace: aggregate, projection, runner, gateway, control/api, shared
+- Frontend: control/ui
+- Infra: docker, observability, swarm
+
+## Data Flow
+- Clients → Gateway (HTTP/JSON)
+- Gateway ↔ Nodes (gRPC)
+- Nodes ↔ NATS (JetStream + KV)
+
+## Services
+- Aggregate: command handling + event sourcing; publishes events to JetStream
+- Projection: materialized views; consumes aggregate events; exposes QueryService (gRPC)
+- Runner: workflow/saga engine + effects/outbox; exposes RunnerAdmin (gRPC)
+- Gateway: edge, authn/z, routing to nodes, admin entry points
+
+## Observability
+- /health, /ready, /metrics on all services
+- Correlation and tracing propagated across HTTP, gRPC, and NATS

docs/architecture/transport.md

@@ -0,0 +1,23 @@
+# Transport Contracts
+
+## Context
+- Tenant: HTTP x-tenant-id; NATS tenant-id
+- Correlation: HTTP x-correlation-id; NATS x-correlation-id + correlation-id
+- Trace: HTTP traceparent; NATS traceparent + trace-id
+
+## Internal RPC (gRPC)
+- Aggregate: CommandService (submit commands)
+- Projection: QueryService (execute queries)
+- Runner: RunnerAdmin (drain, status, reload)
+- All calls set deadlines and propagate context metadata
+
+## NATS JetStream
+- Streams:
+  - AGGREGATE_EVENTS: tenant.*.aggregate.*.*
+  - WORKFLOW_COMMANDS, WORKFLOW_EVENTS
+- Producers set headers: tenant-id, Nats-Msg-Id, correlation, traceparent/trace-id
+- Consumers use AckPolicy::Explicit, bounded ack_wait, max_deliver, max_ack_pending
+
+## Routing
+- Gateway routes per-tenant to shards for Aggregate/Projection/Runner
+- Routing tables hot-reload atomically