docs: update SSE stream docs and retire websocket flow page

[cursor]

Summary

• document the backend SSE stream endpoint contract in API docs
• add an SSE transport troubleshooting runbook
• replace the legacy websocket deep-dive page with a concise pointer to the canonical SSE flow doc

Docs updated

• docs/backend/api-documentation.md
  • added Events Stream Routes section for GET /api/events/stream
  • documented auth requirement, headers/transport behavior (text/event-stream, keepalive comments), stream-connect metadata replay, and event classes delivered over SSE
  • added /api/events/stream to key endpoint list
• docs/development/troubleshoot.md
  • added SSE Stream Not Connected Or Not Receiving Events triage steps with concrete checks and failure-path guidance
• docs/features/google-sync-and-websocket-flow.md
  • converted to a short legacy pointer page linking to google-sync-and-sse-flow.md and current SSE source anchors

Codepaths covered

• backend stream route/controller/server:
  • packages/backend/src/events/events.routes.config.ts
  • packages/backend/src/events/controllers/events.controller.ts
  • packages/backend/src/servers/sse/sse.server.ts
• shared realtime contracts:
  • packages/core/src/constants/sse.constants.ts
  • packages/core/src/types/sse.types.ts
• web SSE entrypoint reference:
  • packages/web/src/sse/provider/SSEProvider.tsx

Knowledge gaps addressed

• explicit public docs for /api/events/stream were missing from API docs
• troubleshooting guidance lacked transport-level SSE diagnostics (session, open stream, keepalive, fan-out/user-id correlation)
• legacy websocket deep-dive content could mislead readers despite SSE being the active runtime path

  

---

Note

Low Risk
Low risk: documentation-only changes that don’t affect runtime behavior. Main risk is minor confusion if the documented SSE contract drifts from implementation.

Overview
Documents the backend SSE realtime stream contract by adding an Events Stream Routes section for GET /api/events/stream (auth requirements, text/event-stream behavior, keepalives, per-user fan-out, and initial USER_METADATA publish) and listing it in Key Endpoints.

Adds an SSE troubleshooting runbook covering how to verify the stream stays connected and how to triage missing events (auth, route registration, base URL/cookie origin, user-id fan-out, and proxy buffering).

Retires the long websocket deep-dive doc by replacing google-sync-and-websocket-flow.md with a short legacy pointer that links to the canonical SSE flow documentation and current source anchors.

^{Written by Cursor Bugbot for commit e515096. This will update automatically on new commits. Configure here.}