# Contributing

## Session workflow

Start of a working session:
1. Read TASKS.md and recent CHANGELOG entries.
2. `npm test && npm run typecheck && npm run lint` — start from green.
3. Pick the highest-priority incomplete task; note the approach in the task.

End of every task:
1. Tests, typecheck, lint — all green.
2. Security review of anything touching auth, tenancy, fetching or publishing.
3. Update TASKS.md status + CHANGELOG.md.
4. Update any affected docs (API.md for routes, DATABASE.md for schema…).

## Ground rules

- **Tenancy:** never query org-owned data without `requireOrgAccess` /
  `loadWebsiteForUser`. Unknown org/website → 404, not 403.
- **Fetching:** user-supplied URLs go through `safeFetch` only. No exceptions.
- **Reversibility:** anything that will modify a customer site must persist
  the original value first (`ProposedChange.originalValue`).
- **Honesty:** no fake data, no dead buttons, no "done" for half-built
  features; failures must surface to the user with a recovery path.
- **Secrets:** env only; never logged; tokens stored hashed.
- **Validation:** every route body/query parses through zod.
- **Audit:** important actions call `recordAudit`.
- **Migrations:** schema changes only via `prisma migrate dev`; destructive
  changes need a documented backup step.

## Style

- TypeScript strict; no `any` unless justified with a comment.
- British English in all user-facing copy.
- Plain-English explanations for SEO issues — the audience is business
  owners, not SEO consultants.
- Comments state constraints the code can't (why, not what).

## Definition of Done

Master brief §68 applies verbatim: end-to-end working, real data, permissions
and tenant separation enforced, error/loading/empty states, green checks,
docs updated, audit logging, mobile layout, no known critical defects.