Document full architecture, design, API, features, deployment, and security.

Adds diagrams and expands the ATC demo path so the cockpit is fully described in-repo.

docs/SECURITY.md

@@ -0,0 +1,46 @@
+# Security
+
+Lab-oriented controls. This is **not** a hardened public multi-tenant SaaS.
+
+## Secrets
+
+| Secret | Location | Git |
+|--------|----------|-----|
+| OME password | `.env` | **Excluded** |
+| Open WebUI service password | `.env` | **Excluded** |
+| Ticket DB | `/data/ops.db` | **Excluded** |
+| SSH user passwords | Never stored server-side; transient WS auth only | N/A |
+
+Use `.env.example` as a template with `CHANGE_ME` placeholders.
+
+## Network exposure
+
+- Cockpit has **no application auth** in the current lab build — rely on ATC network segmentation / VPN / reverse proxy if exposed beyond trusted LAN.
+- Prefer binding publish ports to trusted interfaces only in stricter environments.
+
+## SSH bridge
+
+- Destination host must match a **current fleet management IP**
+- Concurrency caps: 25 global, 3 per client IP
+- `known_hosts=None` for lab self-signed/changing keys — tighten for production
+- Idle timeout terminates abandoned sessions
+- Passwords are not logged; avoid verbose debug of auth payloads
+
+## Chat / LLM
+
+- Fleet context is sent to vLLM / Open WebUI — treat as sensitive operational data
+- Service account for Open WebUI should be least-privilege if possible
+
+## Multi-user stability (related)
+
+- Single worker process shares STATE safely for reads with asyncio
+- SSH sessions are isolated per WebSocket
+- OME poll uses short-lived API sessions and deletes them after fetch
+
+## Recommendations for hardening (future)
+
+1. Add OIDC / reverse-proxy auth in front of `:3090`
+2. Persist SSH host key policy / CA trust
+3. Audit log for SSH session start/stop (user, target, client IP)
+4. Encrypt ticket DB at rest if tickets contain sensitive notes
+5. Rotate lab service passwords regularly