Windsurf setup - Handa Uncle Platform

Windsurf’s Cascade assistant can take on longer refactors or runbooks. Configure workspace rules so it follows the same expectations as the rest of the team.

1. Workspace rules

Create .windsurf/rules.md in the repo root:

# Handa Uncle Cascade rules

## Project context

- Bun runtime, Hono router, MongoDB, Redis, Auth0, Langfuse, Exotel.
- `/api/v1/*` requires Auth0 bearer tokens. `/app/*` relies on device headers.
- Documentation sits in `/docs` and must match `docs/api-reference/openapi.json`.

## Workflow

1. Summarize `git status` and ask how to handle dirty files before editing.
2. Use Bun (`bun run dev`, `bun run typecheck`, `bun test`) for all commands.
3. Prefer additive diffs. If removal is necessary, explain why in the PR summary.

## Style guide

- Controllers extend `BaseController` and return `successResponse`.
- Services log via `logger` with `{ requestId, ... }`.
- Error types come from `src/shared/utils/errors.ts`.
- Docs use second-person voice + verification steps.

## Required checks

- `bun run typecheck`
- `bun test` (or targeted suites)
- Update docs + OpenAPI for any API contract change
- Mention `X-Request-ID` handling in new endpoints

## Forbidden

- Running `git reset --hard` or `git clean -fd`
- Touching `.env*` files
- Inventing API payloads without citing the source

Reload Windsurf so Cascade reads the new rules.

2. Templates

Incident note

Summarize outage <INCIDENT-ID>:
- Trigger (log snippet, requestId)
- Blast radius (endpoints, platforms)
- Mitigation
- Follow-up tasks

API doc draft

Write Mintlify MDX for /api/v1/profile/preferences:
- Include headers, sample request/response, and error codes
- Link to the controller file

Refactor plan

Propose steps to split otp.service.ts into orchestration + provider modules.
Explain impact on tests and docs.