[PBI] Documentation and API reference

[cjlapao]

Description

Document the notification system for both internal contributors (how to emit a notification from a new feature) and for operators/integrators (the full REST API reference and WebSocket message format).

User Story

As a backend engineer adding a new feature that needs to raise alerts, I want clear documentation on how to use the notification dispatcher, so that I can integrate correctly without reading through the implementation.

Acceptance Criteria

• Dispatcher usage guide: A short internal doc (or prominent GoDoc comment block on the Dispatcher interface) showing how to emit each notification type, how to set a correlation_id, and how to attach actions.
• REST API reference: All five endpoints documented with request parameters, response shapes, and example payloads.
• WebSocket message format: The notification.created message envelope is documented with a full example JSON payload.
• Action type guide: Both action types (navigate, api_call) are documented with field definitions and worked examples.
• meta usage guide: A brief explanation of the meta field with examples of when and how to use it (e.g. tagging a notification with a service name or environment label).
• Docs reviewed: Documentation reviewed by at least one team member who is not the author.

Definition of Done

• Code implemented following best practices.
• Unit tests written and passing.
• Code reviewed and approved.
• Merged into the main branch.
• Documentation updated (if applicable).
• Deployed to staging/production environment.

Assumptions and Constraints

• Assumption: Documentation lives in the repository alongside the code.
• Constraint: This PBI should be the last merged in the sequence — it documents the final, reviewed API surface.

Dependencies

No response

Additional Notes

No response