# Contributing to yedir-ai

Thank you for contributing. yedir-ai is maintained as a production-oriented AI design workspace, so changes should be easy to review, safe to roll back, and supported by clear verification evidence.

## Development Setup

Use Node.js 20 and pnpm 9.12.3.

```bash
pnpm install
cp .env.example .env.local
pnpm db:migrate
AUTH_TRUST_HOST=true PORT=3001 pnpm dev
```

Never commit `.env.local` or real credentials.

## Branches and Commits

- Use focused branches for a single theme, such as `refactor/settings-local-ai` or `chore/log-hygiene-canvas`.
- Keep commits small enough to review and revert independently.
- Do not mix broad formatting changes with functional changes.
- Do not push generated local artifacts, worktrees, swap files, migration backups, or `tsconfig.tsbuildinfo`.

## Change Scope

Prefer narrow, explicit scopes:

- UI changes should preserve existing product behavior unless the PR states otherwise.
- API changes must describe compatibility impact and response-shape changes.
- Settings changes must preserve existing setting keys, SWR keys, and save semantics unless a migration is included.
- Logging/security changes must avoid exposing prompts, URLs, base64 data, provider payloads, user content, tokens, cookies, or signed URLs.

`/api/chat` is currently an internal Canvas/Agent generation API. Do not treat it as a public legacy Chat UI contract unless the PR explicitly migrates callers.

## Required Checks

Before opening or updating a PR, run:

```bash
pnpm check:quality
AUTH_TRUST_HOST=true PORT=3001 pnpm dev
SMOKE_BASE_URL=http://127.0.0.1:3001 pnpm smoke:routes
```

`pnpm check:quality` covers lint, scoped log hygiene, typecheck, diff hygiene, and tracked artifact checks.

If a route or workflow cannot be tested locally, explain the gap in the PR.

## Pull Requests

Use the PR template and include:

- What changed and why.
- The user or operational impact.
- Verification output or screenshots when relevant.
- Any intentional follow-up work.

For frontend changes, include screenshots or a short visual verification note. For route/API changes, include status codes, response-shape notes, or targeted test evidence.

## Security

Follow `SECURITY.md` for vulnerability reporting and sensitive-data handling. Report suspected vulnerabilities privately; do not open public issues for secrets, auth bypasses, signed URL leaks, or data exposure.