docs: generate gitea wiki pages + publish script

add wiki/ markdown pages (Home, Sidebar, architecture, transport, developer, usage)

add scripts/publish_gitea_wiki.sh to sync wiki repo

fix: serialize aggregate env-setting tests to avoid parallel env var races

wiki/API-Examples.md

@@ -0,0 +1,28 @@
+# 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
+```
+
+## 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
+```

wiki/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

wiki/Developer-Setup.md

@@ -0,0 +1,24 @@
+# Developer Setup
+
+## Prerequisites
+- Rust toolchain (stable)
+- Node.js (LTS) for control/ui
+- Docker (optional) for local stack
+
+## Build
+```bash
+cargo build
+cd control/ui && npm ci && npm run build
+```
+
+## Workspace Verification
+```bash
+cargo fmt --check
+cargo clippy --workspace --all-targets -- -D warnings
+cargo test --workspace
+cd control/ui && npm ci && npm run lint && npm run typecheck && npm run test && npm run build
+```
+
+## Environment
+- Projection: PROJECTION_GRPC_ADDR
+- Runner: RUNNER_GRPC_ADDR

wiki/Home.md

@@ -0,0 +1,15 @@
+# Cloudlysis Wiki
+
+This wiki is generated from the repository `docs/` directory.
+
+## Start Here
+- Architecture Overview: [[Architecture-Overview]]
+- Transport Contracts: [[Transport-Contracts]]
+- Developer Setup: [[Developer-Setup]]
+- Testing: [[Testing]]
+- Quick Start: [[Quick-Start]]
+- API Examples: [[API-Examples]]
+- NATS Reference: [[NATS-Reference]]
+
+## Repos
+- Source: https://git.madapes.com/madapes/cloudlysis

wiki/NATS-Reference.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

wiki/Quick-Start.md

@@ -0,0 +1,19 @@
+# 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)
+```bash
+cargo run -p aggregate
+cargo run -p projection
+cargo run -p runner
+cargo run -p gateway
+```

wiki/Testing.md

@@ -0,0 +1,16 @@
+# Testing
+
+## Unit and Integration
+```bash
+cargo test --workspace
+```
+
+## Gated Tests (require external services)
+- Runner NATS:
+```bash
+RUNNER_TEST_NATS_URL=nats://127.0.0.1:4222 cargo test -p runner -- --ignored
+```
+- Projection NATS:
+```bash
+PROJECTION_TEST_NATS_URL=nats://127.0.0.1:4222 cargo test -p projection -- --ignored
+```

wiki/Transport-Contracts.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

wiki/_Sidebar.md

@@ -0,0 +1,13 @@
+# Navigation
+
+- [[Home]]
+- Architecture
+  - [[Architecture-Overview]]
+  - [[Transport-Contracts]]
+- Developer
+  - [[Developer-Setup]]
+  - [[Testing]]
+- Usage
+  - [[Quick-Start]]
+  - [[API-Examples]]
+  - [[NATS-Reference]]