From 9e850d3b00432fcc73189d528693ff65464d0373 Mon Sep 17 00:00:00 2001
From: Daniel Legt <contact@danlegt.com>
Date: Sat, 7 Mar 2026 02:09:44 +0200
Subject: [PATCH] README.md env vars

---
 README.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 95 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index d773c9a..6a7b970 100644
--- a/README.md
+++ b/README.md
@@ -40,13 +40,100 @@ Enterprise-style Scrum Poker application using Go, Gin, and SSE for real-time ro
 
 ## Environment Variables
 
-- `HOST`: server host/interface to bind (default all interfaces, equivalent to `0.0.0.0`)
-- `PORT`: server port (default `8002`)
-- `DATA_PATH`: directory for room JSON files (default `./data`)
-- `MAX_ACTIVITY_LOG_ENTRIES`: max stored activity log entries per room (default `400`)
-- `ADMIN_LOG_BROADCAST_LIMIT`: max recent admin log entries sent in SSE payloads (default `200`)
-- `STALE_ROOM_CLEANUP_INTERVAL`: cleanup ticker interval for stale rooms as Go duration (default `5m`)
-- `STALE_ROOM_TTL`: delete empty rooms when last activity is older than this Go duration (default `30m`)
+### Quick Reference
+
+- `HOST` (default: `0.0.0.0`): network interface/address the server binds to.
+- `PORT` (default: `8002`): HTTP port the server listens on.
+- `DATA_PATH` (default: `./data`): folder where room JSON files are stored.
+- `MAX_ACTIVITY_LOG_ENTRIES` (default: `400`): max activity entries retained per room.
+- `ADMIN_LOG_BROADCAST_LIMIT` (default: `200`): max recent log entries sent to admins over SSE.
+- `STALE_ROOM_CLEANUP_INTERVAL` (default: `5m`): how often stale-room cleanup runs.
+- `STALE_ROOM_TTL` (default: `30m`): empty rooms older than this are deleted.
+
+### Variable Guide With Use Cases
+
+`HOST`
+- What it controls: where the web server is reachable from.
+- Use case: local-only dev on one machine.
+```bash
+HOST=localhost PORT=8002 go run ./src
+```
+- Use case: allow access from LAN/Docker/k8s ingress.
+```bash
+HOST=0.0.0.0 PORT=8002 go run ./src
+```
+
+`PORT`
+- What it controls: server port.
+- Use case: avoid conflicts with another app already on `8002`.
+```bash
+PORT=9000 go run ./src
+```
+- Use case: common reverse-proxy port mapping.
+```bash
+HOST=0.0.0.0 PORT=8080 go run ./src
+```
+
+`DATA_PATH`
+- What it controls: disk location for persisted rooms.
+- Use case: keep data in a dedicated local directory.
+```bash
+DATA_PATH=./tmp/rooms go run ./src
+```
+- Use case: persistent mount in containers.
+```bash
+docker run --rm -p 8002:8002 -e DATA_PATH=/app/data -v $(pwd)/data:/app/data scrum-solitare
+```
+
+`MAX_ACTIVITY_LOG_ENTRIES`
+- What it controls: per-room in-memory/disk activity history cap.
+- Use case: retain more history for auditing/debugging.
+```bash
+MAX_ACTIVITY_LOG_ENTRIES=1000 go run ./src
+```
+- Use case: reduce memory/storage in lightweight deployments.
+```bash
+MAX_ACTIVITY_LOG_ENTRIES=100 go run ./src
+```
+
+`ADMIN_LOG_BROADCAST_LIMIT`
+- What it controls: maximum recent activity entries included in admin SSE payloads.
+- Use case: richer admin timeline in active rooms.
+```bash
+ADMIN_LOG_BROADCAST_LIMIT=400 go run ./src
+```
+- Use case: smaller SSE payloads for lower bandwidth.
+```bash
+ADMIN_LOG_BROADCAST_LIMIT=50 go run ./src
+```
+
+`STALE_ROOM_CLEANUP_INTERVAL`
+- What it controls: scheduler frequency for checking stale empty rooms.
+- Use case: aggressive cleanup in ephemeral environments.
+```bash
+STALE_ROOM_CLEANUP_INTERVAL=1m go run ./src
+```
+- Use case: reduce cleanup churn in stable environments.
+```bash
+STALE_ROOM_CLEANUP_INTERVAL=15m go run ./src
+```
+
+`STALE_ROOM_TTL`
+- What it controls: time since last room activity before an empty room is deleted.
+- Use case: auto-prune quickly for temporary team rooms.
+```bash
+STALE_ROOM_TTL=10m go run ./src
+```
+- Use case: keep empty rooms around longer between sessions.
+```bash
+STALE_ROOM_TTL=2h go run ./src
+```
+
+### Duration Format Notes
+
+`STALE_ROOM_CLEANUP_INTERVAL` and `STALE_ROOM_TTL` use Go duration syntax:
+- valid examples: `30s`, `5m`, `45m`, `2h`
+- invalid examples: `5` (missing unit), `five minutes`
 
 ## Run Locally
 
@@ -57,7 +144,7 @@ go run ./src
 
 Open `http://localhost:8002`.
 
-To bind explicitly:
+Host binding examples:
 
 ```bash
 HOST=localhost PORT=8002 go run ./src