# Cursor and Agent Development Rules

These rules apply to all humans and AI agents working on **Anwal Growth Platform**. They are mandatory unless the project owner explicitly overrides them in writing.

## Documentation-first

1. **Always read `/docs` before changing code.** Start with [docs/README.md](./README.md), [00-project-overview.md](./00-project-overview.md), relevant domain docs, and the active task in `/tasks`.
2. **Before starting any task, check [tasks/README.md](../tasks/README.md)** for the current `pending` task and status.
3. **After completing any task, update [tasks/README.md](../tasks/README.md)** status (`done` / `pending` / `future`).
4. **Always update documentation after every task.** Do not consider a task complete until docs reflect the change.
5. **Always update [16-changelog.md](./16-changelog.md)** with a dated entry summarizing what changed.
6. **Always update [02-database-schema.md](./02-database-schema.md)** if Mongoose models, collections, indexes, or relationships change.
7. **Always update [03-api-specification.md](./03-api-specification.md)** if API routes, request/response shapes, or auth behavior change.
8. **If a new route or API is added, update [03-api-specification.md](./03-api-specification.md)** in the same change set.
9. **If a new page is added, update [04-ui-pages.md](./04-ui-pages.md)** in the same change set.
10. **Always update [10-environment-variables.md](./10-environment-variables.md)** if new or renamed environment variables are introduced.
11. **If a new env variable is added, update both [`.env.example`](../.env.example) and [10-environment-variables.md](./10-environment-variables.md).**
12. **If a new file or module is added, document it** in the relevant doc (architecture, API, UI, or domain)—not only in code.
13. **Record non-trivial choices in [13-decisions-log.md](./13-decisions-log.md)** when architecture or product direction shifts.

**Docs are the single source of truth.** Code implements docs; if they disagree, fix both together.

## Code safety and quality

14. **Never remove existing functionality** without explicit instruction from the project owner.
15. **Never hardcode secrets** (API keys, passwords, webhook signing keys, connection strings). Use environment variables and document them in [10-environment-variables.md](./10-environment-variables.md).
16. **Use TypeScript** for all application code under `/src`.
17. **Use clean modular architecture:** separate routes/handlers, services, data access, and UI components; avoid god files.
18. **Keep code production-ready:** typing, error handling, validation, and consistent naming—not prototype-only shortcuts unless the task explicitly allows spikes.
19. **Keep Arabic/English support in mind:** i18n-friendly strings, RTL layout considerations, and UTF-8 safe storage for names and email content.

## Integrations

20. **Use environment variables for all external services** (MongoDB, SMTP, IMAP, OpenAI, Redis, n8n, auth secrets).
21. **Keep n8n integrations through configurable webhook URLs** (`N8N_WEBHOOK_*`). No fixed production URLs in source.
22. **n8n is the automation layer**, not the system of record for CRM data.
23. **Use the internal SMTP sending engine** for campaigns; do not rely on n8n as the primary outbound mail path.

## Task workflow

24. **Work one task at a time** from `/tasks` unless the owner requests parallel work.
25. **Meet all acceptance criteria** in the task file before marking complete.
26. **Update the task file** if scope changes mid-work, with owner approval.

## What not to do

- Do not commit `.env`, `.env.local`, or credential files.
- Do not skip changelog entries for “small” fixes.
- Do not add features outside the current task scope without approval.
- Do not replace internal email sending with n8n-only flows for core campaign delivery.
- Do not initialize app features ahead of the active task (e.g. no Next.js before Task 002 unless tasked).

## Reference

| Need | Document |
|------|----------|
| Doc index | [README.md](./README.md) |
| Task index | [tasks/README.md](../tasks/README.md) |
| Env vars | [10-environment-variables.md](./10-environment-variables.md) |
| Security | [11-security.md](./11-security.md) |
| Architecture | [01-architecture.md](./01-architecture.md) |