Extend docblocks and type annotations for AI comprehension

[tyler-dane]

Review and improve docblocks and type annotations in the codebase, focusing on common, util, hooks, backend, and web layers. Clarify function purpose, parameters, return values, and stateful logic entry points for agent readability. Where missing, add comments to support semantic code search and automated code understanding.

Goal: Normalize and enrich type information and comments so agents can confidently change code without breaking invariants.

Proposed scope & tasks:

T1: Establish docblock & typing guidelines

In SwitchbackTech/compass create/extend:
docs/coding-standards.md or add a “Docblocks & Types” section in README/CONTRIBUTING.
Define:
Preferred JSDoc style for TS/JS.
When to add comments (public exports, complex logic, side-effectful functions).
How to document temporal/domain invariants (e.g. “endTime > startTime”, “tasks must be associated with a calendar”).
T2: Backend sweep (APIs & services)

Target: packages/backend/src/**
For:
Route handlers/controllers (routes/, controllers/).
Service modules (services/, usecases/).
Add/ensure:
Explicit Request/Response types where possible.
JSDoc with:
@param and @returns
“Side effects” subsection (e.g. writes to DB, enqueues jobs).
High-signal comments describing:
What business rule is enforced.
Any important edge cases (time zones, all-day events, overlapping events).