API docs: WebSocket event catalog & usage guide

[codebestia]

Write apps/backend/docs/api-websocket-events.md — a usage-oriented guide covering: connection + auth handshake, every inbound event a client can emit (send_message, send_file_message, edit_message, delete_message, message_read, typing_start/typing_stop, join_room, message_history, resume, ask_assistant, etc.) and every outbound event the server emits, each with a realistic example payload and when it fires.

Acceptance criteria:

• Every event currently handled by the dispatcher/socket layer is documented with an example payload
• The doc explains the current envelope-wrapper vs. legacy-raw-emit situation as it actually is in the code today
• ask_assistant's call-out to the AI agent service is documented as part of that event's entry

[Israel-light]

@Israel-light has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I'd like to work on this issue because clear API documentation makes it much easier for developers to integrate with the WebSocket layer and understand the expected event flows.

I'm interested in improving developer experience through accurate, implementation-driven documentation. I understand the goal is to document the connection and authentication flow, every supported inbound and outbound WebSocket event with realistic payload examples, explain the current envelope and legacy formats, and describe how the ask_assistant event interacts with the AI service.

I'll carefully review the existing socket implementation to ensure the documentation reflects the current behavior of the codebase, keep the examples practical and easy to follow, and organize the guide so it's useful for both new and existing contributors.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Israel-light to this issue.

[badmusdare4]

@badmusdare4 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hello maintainer, I have thoroughly read through the issue and I’m confident I can resolve it. Please consider assigning it to me.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @badmusdare4 to this issue.

[drips-wave]

Congratulations, @Israel-light! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @Israel-light: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊