1 files changed, 96 insertions, 0 deletions
diff --git a/docs/sessions.md b/docs/sessions.md
new file mode 100644
index 000000000..593c95283
--- /dev/null
+++ b/docs/sessions.md
@@ -0,0 +1,96 @@
+# Sessions
+
+The Sessions service tracks client connections to zenserver. Each session
+represents a logical connection from a client application — an Unreal Editor
+instance, a build agent, a CLI tool, or any other process interacting with the
+server.
+
+## Concepts
+
+### Session
+
+A session is identified by a unique OID and carries:
+
+- **AppName** — the name of the connecting application (e.g. `UnrealEditor`,
+  `zen`)
+- **Mode** — the operational mode of the client
+- **JobId** — an optional job identifier for build farm scenarios
+- **Metadata** — arbitrary key-value data attached by the client
+- **Timestamps** — creation, last update, and end times
+
+### Session Log
+
+Each session has an associated log stream that can receive entries from the
+client or from zenserver itself. The server's own session captures internal log
+output, making it visible in the web dashboard.
+
+Log entries contain a timestamp, severity level (`debug`, `info`, `warn`,
+`error`), a message string, and optional structured data fields.
+
+Logs are kept in memory with a maximum of 10,000 entries per session. When the
+limit is exceeded, the oldest entries are evicted.
+
+## API
+
+**Base URI:** `/sessions/`
+
+### Listing Sessions
+
+```
+GET /sessions/                  # Active sessions (default)
+GET /sessions/?status=ended     # Ended sessions
+GET /sessions/?status=all       # All sessions
+```
+
+### Managing Sessions
+
+```
+POST   /sessions/{id}           # Create or update a session
+PUT    /sessions/{id}           # Update session metadata
+DELETE /sessions/{id}           # End and remove a session
+GET    /sessions/{id}           # Get session details
+```
+
+When creating a session, the request body should contain:
+
+- `appname` — application name
+- `mode` — operational mode
+- `jobid` — optional job identifier
+- `metadata` — optional key-value metadata
+
+### Session Logs
+
+```
+GET  /sessions/{id}/log             # Retrieve log entries
+POST /sessions/{id}/log             # Append log entries
+```
+
+**Retrieving logs** supports two modes:
+
+- **Cursor-based** (recommended): pass `?cursor=N` where N is the cursor value
+  from the previous response. Returns only entries appended since that cursor.
+- **Offset/limit**: pass `?offset=N&limit=M` for traditional pagination.
+
+**Appending logs** accepts:
+
+- **Plain text** — each line becomes a separate log entry
+- **JSON** — a single log object or `{"entries": [...]}` array, each with
+  `level`, `message`, and optional `data` fields
+
+### Live Updates
+
+```
+GET /sessions/ws                # WebSocket connection
+```
+
+The WebSocket endpoint pushes the full session list to connected clients
+periodically. This powers the real-time session table in the web dashboard.
+
+## Web Dashboard
+
+The Sessions page in the dashboard provides:
+
+- A table of active, ended, or all sessions with sorting and pagination
+- Session detail panel showing metadata and properties
+- Live log viewer with follow mode, newest-first ordering, and text filtering
+- The server's own session is selected by default on page load