## Context
The current API behavior is functionally correct but has ambiguities that cause client confusion: WebSocket handshake messaging differs from inline docs, 409 conflict responses are inconsistent for clients, and workload heatmap defaults vary based on calendar edge cases (Sunday).

## Goals / Non-Goals
- Goals:
  - Make WebSocket auth expectations explicit and consistent.
  - Provide a stable, machine-readable conflict response for optimistic locking.
  - Define predictable workload heatmap defaults and edge-case handling.
- Non-Goals:
  - Full API version migration (/api to /api/v1).
  - Redesign of workload UI or heatmap visualization.

## Decisions
- WebSocket auth handshake: keep first-message authentication; do not require a pre-auth banner. Add explicit invalid-token error message prior to close.
- Optimistic locking: return a standardized 409 payload containing a human-readable message plus current/provided version fields.
- Workload defaults: show all accessible users by default (including zero workload); support `hide_empty=true` to exclude them. When `week_start` is omitted and today is Sunday, extend the default week window to include the upcoming week to avoid empty default views.
- Caching: include `hide_empty` in cache key and cache the default path to keep latency stable.

## Risks / Trade-offs
- Returning more users by default may increase response sizes; cache should offset this.
- Sunday window extension changes semantics of "current week"; clients must understand the rule.
- Conflict payload change may require frontend updates if it expects a string-only detail.

## Migration Plan
- Update specs first, then implement backend changes.
- Update frontend only if new defaults or conflict payloads require parsing changes.
- Add regression tests for WebSocket auth invalid token, conflict payload shape, and heatmap defaults.

## Open Questions
- Should we add an explicit `auth_required` message before waiting for the auth payload (client UX improvement), or keep the minimal handshake?