# Codex project rules The complete build specification and phase acceptance criteria live in [PLAN.md](./PLAN.md). Read the relevant phase before making changes. ## Required workflow 1. Work one phase at a time, in order. At the end of each phase, run every Verify step for that phase. Do not start the next phase until they all pass. Commit completed work as `phase-N: ` and tick the phase in the Progress Log in `PLAN.md`. 2. Never commit secrets. Put deployment values in `.env`, which is ignored, and document every variable with a comment in `.env.example`. 3. Use Node.js 22 LTS, pnpm, the latest stable Next.js with the App Router and strict TypeScript, Tailwind CSS v4, shadcn/ui, TanStack Query, Recharts, Prisma, PostgreSQL 16, Auth.js v5, zod, Vitest, and Playwright. Pin exact versions in `package.json` and pin the n8n Docker image to a stable version, never `latest`. Check versions on the server with `npm view <package> version` and `docker pull`. 4. The UI is Arabic and right-to-left by default (`<html dir="rtl" lang="ar">`) with an English left-to-right toggle. Use a dark theme by default and offer a light theme. Put every user-facing string in `messages/ar.json` and `messages/en.json`. 5. Store money as Prisma `Decimal(12,2)` and display it like `150 ج.م`. A deployment has one currency, configured in settings and defaulting to `EGP`. 6. Store timestamps in UTC. Interpret crons, digests, and quiet hours in `Africa/Cairo` using `TZ`. 7. Generate order IDs as `ORD-<Date.now()>` with 13 digits and retry unique conflicts. Generate AWBs as `WB-<8 digits>`; draft labels show `DRAFT`. 8. Every n8n workflow must pass `pnpm n8n:validate`. Keep Code-node logic only in `n8n/code/*.ts`; never edit bundled code inside workflow JSON. 9. Validate every internal API input with zod. Invalid input returns HTTP 422 as `{error, details}`. 10. When a step is ambiguous, choose the simplest option consistent with `PLAN.md` and record the choice under "Decisions made" in its Progress Log. ## Common commands Commands become available as their owning phase is implemented. ```bash # Install the monorepo pnpm install # Web development, checks, and production build pnpm dev pnpm --filter web test pnpm --filter web build pnpm --filter web exec playwright test # n8n logic and workflow checks pnpm --filter n8n test pnpm n8n:build pnpm n8n:validate # Local deployment loop docker compose up -d --build docker compose ps scripts/n8n-import.sh scripts/smoke-test.sh all ```