# Development Setup (Starter Template)

---
**Phase:** Phase 0 (Planning)
**Status:** Draft — finalize when code starts
**Owner:** Tech Leads
**References:**
- `/RECOMMENDATIONS.md`
- `/RULES.md`
---

This file describes how to run the project locally and in CI once code exists.  
Lock concrete commands and versions in Phase 1/2.

## 1. Prerequisites
- **Node.js:** LTS version (specify in `RECOMMENDATIONS.md` and `.nvmrc`/`.tool-versions` later).
- **Package manager:** npm / pnpm / yarn (pick one and lock it).
- **Database/Redis:** only if your modules require them.

## 2. Repo Layout (when using a monorepo)
Example skeleton:
```
apps/
  web/            # frontend app (e.g., Next.js)
  api/            # backend API (e.g., Node/TS)
packages/
  shared/         # shared types/utils
docs/
  ...
```

If you do not use a monorepo, document the real structure here.

## 3. Environment Variables
- Keep local env in `.env.local` (never commit secrets).
- Provide `.env.example` once variables are known.
- Describe required vars per app:
  - `apps/web` — public env (`NEXT_PUBLIC_*`) + auth client config.
  - `apps/api` — DB/Redis URLs, provider secrets, webhook secrets, LLM keys, billing keys.

## 4. Common Commands (fill in when code exists)
> Respect any forbidden commands in `/RULES.md`.

- Install deps: `<pm> install`
- Build: `<pm> run build`
- Tests: `<pm> test` or `<pm> run test:*`
- Lint: `<pm> run lint`
- Format: `<pm> run format`
- Local dev server (if allowed): `<pm> run dev`

## 5. Tooling
- **Type checking:** TypeScript strict mode.
- **Linting:** ESLint (or equivalent).
- **Formatting:** Prettier/Biome (pick one).
- **E2E:** Playwright/Cypress (if applicable).

## 6. CI Notes
- Use the same commands as local (no hidden CI‑only steps).
- Cache package manager store.
- Run unit → integration → e2e in increasing cost order.