Correct the documentation against what the code actually does

README.md

@@ -8,9 +8,12 @@ Waymark is a schema-driven journey orchestration engine for onboarding and compl
 ## Documentation map
 
 - [`getting-started.md`](./getting-started.md) — prerequisites, local setup, and contribution workflow
-- [`user-guide.md`](./user-guide.md) — persona model, session lifecycle, and webhook integration
+- [`user-guide.md`](./user-guide.md) — persona model, credentials, session lifecycle, rate limits, and webhook integration
 - [`docs/journey-json.md`](./docs/journey-json.md) — journey JSON notation, structure, frontend linkage, and visualization
-- [`docs/issues/`](./docs/issues/) — known gaps tracked as GitHub issues
+- [`docs/runbook.md`](./docs/runbook.md) — configuration reference, credentials, rate limits, scaling, and operations
+- [`docs/troubleshooting.md`](./docs/troubleshooting.md) — symptoms, causes and fixes for common failures
+- [`docs/architecture/`](./docs/architecture/) — C4 context, container and component diagrams
+- [`docs/issues/`](./docs/issues/) — staging area for backlog items the CI workflow turns into GitHub issues. Currently empty; open work lives on the [issue tracker](https://github.com/MaximumTrainer/Waymark/issues).
 
 ## Repository structure
 

docs/architecture/components.md

@@ -8,12 +8,12 @@ C4Component
 
     Container_Boundary(api, "ASP.NET Core API (.NET 10)") {
 
-        Component(workflow_ctrl, "WorkflowController", "ASP.NET Controller", "POST /sessions/start, POST /sessions/{id}/steps/{nodeId}/submit, GET /sessions/{id}/next, GET /sessions/{id}/submissions, GET /sessions/{id}/stream (SSE)")
+        Component(workflow_ctrl, "WorkflowController", "ASP.NET Controller", "POST /sessions/start, POST /sessions/{id}/steps/{nodeId}/submit, GET /sessions/{id}/next, GET /sessions/{id}/submissions, GET /sessions/{id}/events (SSE)")
         Component(flows_ctrl, "FlowsController", "ASP.NET Controller", "CRUD endpoints for Flows, Nodes, Connections. Operator-only.")
         Component(customers_ctrl, "CustomersController", "ASP.NET Controller", "CRUD for CustomerProfiles. GET by externalId.")
         Component(webhooks_ctrl, "WebhooksController", "ASP.NET Controller", "Register/list/delete webhooks. Inspect delivery history.")
-        Component(analytics_ctrl, "AnalyticsController", "ASP.NET Controller", "GET /analytics/flows/{id} — session counts, completion rate, avg duration, abandonment node.")
-        Component(auth_ctrl, "AuthController", "ASP.NET Controller", "GET /auth/me — returns authenticated caller identity.")
+        Component(analytics_ctrl, "AnalyticsController", "ASP.NET Controller", "POST /analytics/events — ingests browser-raised events. GET /analytics/sessions/{id}/events — one session trail in order. GET /analytics/flows/{id} — session counts, completion rate, avg duration, abandonment node.")
+        Component(auth_ctrl, "AuthController", "ASP.NET Controller", "GET /api/auth/me — returns authenticated caller identity.")
 
         Component(workflow_svc, "WorkflowService", "Application Service", "Orchestrates session lifecycle: start, submit, advance, abandon. Evaluates compliance rules. Executes logic nodes. Emits SSE events. Dispatches webhooks.")
         Component(flow_svc, "FlowService", "Application Service", "CRUD for flows, nodes, connections. Validates node types and connection structure.")

docs/architecture/containers.md

@@ -10,11 +10,12 @@ C4Container
     Person(applicant, "Applicant", "Completes onboarding journey")
 
     System_Boundary(waymark, "Waymark") {
-        Container(spa, "React SPA", "React 18 + TypeScript + Vite", "Flow builder UI, step renderer, analytics dashboard, session history. Communicates with API via REST and SSE.")
+        Container(spa, "React SPA", "React 18 + TypeScript + Vite", "Applicant journey on the public route; flow builder, analytics and session history behind the operator SSO check. Communicates with API via REST and SSE.")
         Container(api, "ASP.NET Core API", ".NET 10, C#", "Hosts all REST endpoints. Handles auth, rate limiting, compliance evaluation, webhook dispatch, file uploads, SSE streaming.")
         Container(db, "PostgreSQL 16", "Relational database", "Stores flows, nodes, sessions, submissions, customer profiles, webhooks, webhook delivery logs.")
         Container(file_store, "File Store", "Local filesystem (dev) / Object Storage (prod)", "Stores uploaded documents. Files referenced by fileId in submissions.")
-        Container(bg_service, "Session Timeout Service", ".NET IHostedService", "Background service: abandons sessions inactive beyond configured timeout (default: 60 minutes). Runs inside the API process.")
+        Container(bg_service, "Session Timeout Service", ".NET IHostedService", "Background service: abandons sessions inactive beyond configured timeout (default: 1440 minutes). Runs inside the API process.")
+        Container(broker, "RabbitMQ", "Message broker", "Optional, required above one API replica. Fans session events out to every instance so SSE streams stay live, and carries domain events.")
     }
 
     System_Ext(idp, "Identity Provider", "OIDC/JWT issuer (Auth0, Keycloak, etc.)")
@@ -30,15 +31,20 @@ C4Container
     Rel(api, webhook_consumer, "Dispatches events", "HTTPS POST")
     Rel(api, virus_scanner, "Scans uploaded documents", "HTTP API")
     Rel(bg_service, db, "Reads active sessions, writes abandoned status", "PostgreSQL")
+    Rel(api, broker, "Publishes and consumes session events", "AMQP")
 ```
 
 ## Container Responsibilities
 
 ### React SPA (`src/frontend/`)
-- Flow builder: drag-and-drop node/connection editor
+
+Applicant route (`/`, public):
 - Step renderer: schema-driven form engine (renders fields from `jsonContent`)
+
+Operator routes (`/admin`, behind SSO — no operator surface renders on the public route):
+- Flow builder: drag-and-drop node/connection editor
 - Analytics dashboard: flow performance metrics
-- Session history: paginated list + detail view
+- Session history: paginated list + detail view, including the per-session analytics event trail
 - Webhook delivery inspector: delivery logs + manual retry
 - Version history: snapshot diffs + rollback
 
@@ -51,12 +57,23 @@ C4Container
 
 ### PostgreSQL Database
 - Schema managed via **EF Core migrations** (`OpenOnboarding.Infrastructure/Migrations/`)
-- Tables: `Flows`, `Nodes`, `Connections`, `Sessions`, `Submissions`, `CustomerProfiles`, `Webhooks`, `WebhookDeliveries`
+- Tables: `Flows`, `Nodes`, `Connections`, `Sessions`, `Submissions`, `CustomerProfiles`, `Webhooks`, `WebhookDeliveries`, `AnalyticsEvents`
+
+### RabbitMQ (optional)
+- Not required for a single replica; the API falls back to an in-process emitter and logs a startup
+  warning outside Development.
+- **Session event fan-out** — an SSE stream is pinned to the instance that accepted it, so events
+  raised on another instance must travel between them. Enabled with `SessionEvents__Transport=rabbitmq`.
+- Each instance binds its own exclusive, auto-delete queue to a shared fanout exchange. Messages are
+  transient: an event is only useful to a stream that is open right now.
+- Connection and topology recovery are enabled explicitly, so a dropped connection re-declares the
+  queue and re-attaches the consumer rather than leaving a stream silently dead.
 
 ### Session Timeout Service
 - Polls every minute for sessions where `UpdatedAt < now - SessionTimeoutMinutes`
 - Marks timed-out sessions as `Abandoned`
-- Configured via `SessionTimeoutMinutes` (default: 60)
+- Configured via `SessionTimeoutMinutes` (default: 1440). Set it to `0` or less to disable the
+  sweep entirely; the service logs that it is disabled and stops.
 
 ## Technology Stack