docs: update documentation for Docker orchestration and env var rename

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -64,6 +64,16 @@ java -jar cameleer3-server-app/target/cameleer3-server-app-1.0-SNAPSHOT.jar
 - Docker build uses buildx registry cache + `--provenance=false` for Gitea compatibility
 - CI: branch slug sanitization extracted to `.gitea/sanitize-branch.sh`, sourced by docker and deploy-feature jobs
 
+## UI Structure
+
+The UI has 4 main tabs: **Exchanges**, **Dashboard**, **Runtime**, **Deployments**.
+
+- **Exchanges** — route execution search and detail
+- **Dashboard** — metrics and stats
+- **Runtime** — live agent status, logs (previously separate Logs tab merged here)
+- **Deployments** — deployment lifecycle. Config sub-tabs: **Variables | Monitoring | Traces & Taps | Route Recording | Resources** (previously a separate Config tab, now merged into Deployments)
+- **Create app** — full page at `/apps/new` (not a modal)
+
 ## UI Styling
 
 - Always use `@cameleer/design-system` CSS variables for colors (`var(--amber)`, `var(--error)`, `var(--success)`, etc.) — never hardcode hex values. This applies to CSS modules, inline styles, and SVG `fill`/`stroke` attributes. SVG presentation attributes resolve `var()` correctly.
@@ -71,6 +81,47 @@ java -jar cameleer3-server-app/target/cameleer3-server-app-1.0-SNAPSHOT.jar
 - Sidebar generates `/exchanges/` paths directly (no legacy `/apps/` redirects). basePath is centralized in `ui/src/config.ts`; router.tsx imports it instead of re-reading `<base>` tag.
 - Global user preferences (environment selection) use Zustand stores with localStorage persistence — never URL search params. URL params are for page-specific state only (e.g. `?text=` search query). Switching environment resets all filters and remounts pages.
 
+## Docker Orchestration
+
+When deployed via the cameleer-saas platform, this server orchestrates customer app containers using Docker. Key components:
+
+- **ConfigMerger** — merges config at three levels: global → environment → app. Lower levels override higher. Used to produce the final env var set for a deployment.
+- **TraefikLabelBuilder** — generates Traefik Docker labels for path-based or subdomain-based routing to each deployed container. Two routing strategies: path prefix (`/app/{slug}`) and subdomain (`{slug}.domain`).
+- **DockerNetworkManager** — manages two Docker network tiers:
+  - `cameleer-traefik` — shared network that Traefik joins; all routable containers attach here
+  - `cameleer-env-{slug}` — per-environment isolated network; containers in the same environment can reach each other and the cameleer3-server
+- **DockerEventMonitor** — listens to the Docker event stream to detect container exits, OOM kills, and health state changes. Updates deployment status in real time.
+- **DeploymentProgress** — tracks deploy stages and broadcasts progress events via SSE for the UI progress indicator.
+
+### Deployment Status Model
+
+Deployments move through these statuses:
+
+| Status | Meaning |
+|--------|---------|
+| `PENDING` | Queued, not started |
+| `RUNNING` | Container healthy and serving |
+| `DEGRADED` | Container up but health check failing or some replicas down |
+| `STOPPING` | Graceful shutdown in progress |
+| `STOPPED` | Intentionally stopped |
+| `FAILED` | Terminal failure |
+
+**Replica support**: deployments can specify a replica count. `DEGRADED` is used when at least one but not all replicas are healthy.
+
+**Deploy stages** (`DeployStage`): BUILD → PUSH → PULL → STOP_OLD → START → HEALTH_CHECK → DONE (or FAILED at any stage).
+
+**Blue/green strategy**: when re-deploying, the new container is started and health-checked before the old one is stopped, minimising downtime.
+
+### JAR Management
+
+- **Retention policy** per environment: configurable maximum number of JAR versions to keep. Older JARs are deleted automatically.
+- **Nightly cleanup job** (Spring `@Scheduled`): purges JARs exceeding the retention limit and removes orphaned files not referenced by any app version.
+- **Volume-based JAR mounting** for Docker-in-Docker setups: set `CAMELEER_JAR_DOCKER_VOLUME` to the Docker volume name that contains the JAR storage directory. When set, the orchestrator mounts this volume into the container instead of bind-mounting the host path (required when the SaaS container itself runs inside Docker and the host path is not accessible from sibling containers).
+
+### nginx / Reverse Proxy
+
+- `client_max_body_size 200m` is required in the nginx config to allow JAR uploads up to 200 MB. Without this, large JAR uploads return 413.
+
 ## Disabled Skills
 
 - Do NOT use any `gsd:*` skills in this project. This includes all `/gsd:` prefixed commands.