> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handauncle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor workflow

> Shared rules for using Cursor with the Handa Uncle backend

Cursor is our primary editor for navigating the Bun monorepo, updating services,
and editing these docs. Configure it once so every engineer (and AI assistant)
shares the same guardrails.

## 1. Project rules

```bash theme={null}
mkdir -p .cursor
```

`./.cursor/rules.md`:

```markdown theme={null}
# Handa Uncle backend

- Stack: Bun + Hono server, MongoDB, Redis, Auth0, Pinecone, Langfuse.
- Never delete user code unless asked. Prefer minimal diffs.
- Cite exact files (e.g. `src/services/app/services/app-launch.service.ts`).

## Critical invariants

1. `/app/launch` requires `x-device-id` + `x-platform` headers.
2. OTP flow uses Exotel with retries defined in `otp.service.ts`.
3. Rate limiting + request metadata live under `src/shared/middlewares/`.
4. Documentation must align with `docs/api-reference/openapi.json`.

## Workflow

- Run `git status` before editing and summarize existing changes.
- Use Bun for scripts/tests: `bun run dev`, `bun run typecheck`, `bun test`.
- Keep `X-Request-ID` in all new logs.
- Update MDX pages + `docs.json` together so navigation stays valid.

## Language

- Write instructions in second person.
- Include verification steps (curl response, log snippet, etc.).
- Keep tone concise and technical—this is an internal engineering audience.
```

Restart Cursor or reload the workspace so the new rules are applied.

## 2. Command palette shortcuts

| Command                | When to run                             |
| ---------------------- | --------------------------------------- |
| `bun run dev`          | Boot the API on `http://localhost:8080` |
| `bun run typecheck`    | Before every commit/PR                  |
| `bun test --watch`     | Iterate on service logic                |
| `mint dev --port 3334` | Preview the Mintlify docs               |

Add them to Cursor’s “Custom Commands” so they’re one keystroke away.

## 3. Supplying context to AI

When Cursor asks for more information:

* Point it to `APP_LAUNCH_IMPLEMENTATION.md` for device boot flow context.
* Use `MOBILE_API_ENDPOINTS.md` when editing auth/app contracts.
* Link `docs/api-reference/openapi.json` whenever modifying API responses.
* Reference the exact service/controller file instead of paraphrasing.

## 4. Things to avoid

* Don’t touch `.env.*` files or rotate secrets from within Cursor.
* Don’t run destructive git commands (`reset --hard`, `clean -fd`) without
  explicit approval.
* Don’t invent API payloads—copy from the code, tests, or Langfuse traces.