feat(billing): implement tenant subscription entitlements system (milestones 0-6)

README.md

@@ -1,38 +1,55 @@
-# cloudlysis (monorepo)
+# Cloudlysis (monorepo)
 
-## Layout
-- Rust services (Cargo workspace): `aggregate/`, `gateway/`, `projection/`, `runner/`, `control/api/`, `shared/`
-- Control UI: `control/ui/`
-- Docker + Swarm + Compose: `docker/`, `docker-compose.yml`, `swarm/`, `observability/`
+Production-oriented, multi-service Rust workspace with an operator-facing Control Plane (API + Admin UI), S3-backed document storage, and an optional observability stack for local parity.
 
-## Documentation
-- docs/README.md
-- Architecture: docs/architecture/overview.md, docs/architecture/transport.md
-- Developer: docs/developer/setup.md, docs/developer/testing.md
-- Usage: docs/usage/quickstart.md, docs/usage/api.md, docs/usage/nats.md
-- Gitea Wiki: run `scripts/publish_gitea_wiki.sh` (publishes `wiki/` to the repo wiki)
+## Quickstart (local dev)
 
-## Quick Start (Docker Compose)
+Core stack (includes MinIO + MailHog + Control Plane):
 
 ```bash
 docker compose up -d --build
 ```
 
-Full local stack with observability:
+Full local stack with observability (Grafana/Loki/Tempo/VictoriaMetrics):
 
 ```bash
-docker compose -f docker-compose.yml -f observability/docker-compose.yml up -d --build
+docker compose --profile observability up -d --build
 ```
 
-## Commands
-- `make compose-up`, `make compose-down`
-- `make compose-up-observability`, `make compose-down-observability`
-- `make docker-build-all`
-- `make swarm-deploy-all`, `make swarm-rm-all`
+Full local stack + Loki/Tempo using MinIO (S3 mode):
 
-More details: `DOCKER.md`
+```bash
+docker compose -f docker-compose.yml -f observability/docker-compose.s3.yml --profile observability up -d --build
+```
 
-## Workspace Verification
+## Local endpoints
+- **Control UI**: `http://localhost:8082`
+- **Control API**: `http://localhost:38080`
+- **Grafana** (observability profile): `http://localhost:3000`
+- **MailHog UI**: `http://localhost:8025` (SMTP on `localhost:1025`)
+- **MinIO console**: `http://localhost:9001` (S3 API on `localhost:9000`)
+
+## Repository layout (high level)
+- **Rust services (Cargo workspace)**: `aggregate/`, `gateway/`, `projection/`, `runner/`, `control/api/`, `shared/`
+- **Admin UI**: `control/ui/`
+- **Docker / Swarm / Compose**: `docker/`, `docker-compose.yml`, `swarm/`, `observability/`
+
+## Production (overview)
+- **Control plane Swarm stack**: `swarm/stacks/control-plane-prod.yml`
+- **S3 docs buckets**: `CONTROL_S3_BUCKET_DOCS` supports a comma-separated shard set (e.g. `cloudlysis-docs-0,cloudlysis-docs-1,cloudlysis-docs-2`). Bucket selection is deterministic per-tenant; keep the full shard set stable to avoid remapping tenants.
+- **S3 provisioning helpers** (idempotent scripts; CI/CD friendly):
+  - `docker/scripts/s3_create_docs_bucket.sh`
+  - `docker/scripts/s3_apply_lifecycle_docs.sh`
+  - `docker/scripts/s3_verify_docs.sh`
+  - Gitea Actions workflow: `.gitea/workflows/s3-provision.yml`
+
+## Docs
+- **Docker / local dev / Swarm**: `DOCKER.md`
+- **Developer docs**: `docs/developer/setup.md`, `docs/developer/testing.md`
+- **Architecture**: `docs/architecture/overview.md`, `docs/architecture/transport.md`
+- **Usage**: `docs/usage/quickstart.md`, `docs/usage/api.md`, `docs/usage/nats.md`
+
+## Workspace verification
 
 ```bash
 cargo fmt --check