# Contributing to ShipRex CMS/API

This project is developed **PRP-first**: every non-trivial change starts as a
**PRP** (Product/Project Requirement Prompt) — a self-contained spec + ordered
task list — under `docs/prps/`. This keeps every feature consistent, reviewable,
and safe to hand to any developer (or AI agent) cold.

> New here? Read in this order:
> 1. [architecture.md](architecture.md) — the mental model
> 2. [feature-development-guide.md](feature-development-guide.md) — how to build
> 3. [database-guide.md](database-guide.md) — how to change data
> 4. [PRP-TEMPLATE.md](PRP-TEMPLATE.md) — the spec format
> 5. [postman/README.md](postman/README.md) — the API contract & how to use it

---

## The PRP workflow

```
Idea ──► Author a PRP (copy PRP-TEMPLATE.md → docs/prps/PRP-NNN-<slug>.md)
     ──► Review the PRP (scope, contract, gotchas, tasks ordered & committable)
     ──► Execute task-by-task (one commit per task, validate before commit)
     ──► Update the Postman contract in lockstep
     ──► Final validation checklist ──► merge
```

### Authoring a PRP
1. Copy [PRP-TEMPLATE.md](PRP-TEMPLATE.md) to `docs/prps/PRP-NNN-<short-slug>.md`
   (next number — see `docs/prps/README.md`).
2. Fill **every** section. The "⛔ STOP — read before code" and
   "Known gotchas" sections are not optional — they are what make the PRP
   executable without tribal knowledge.
3. Name the **reference module** to copy (default: Knowledge Base) and the exact
   **Postman folder** that is the contract.
4. Break the work into **small, ordered, independently committable tasks**, each
   ending with its **Verify** + **Commit** lines (and **Postman**/**DB** lines
   where relevant).

### Executing a PRP
- Do tasks **in order**. Don't start a task until the previous one is committed.
- Run the task's **Verify** step before committing.
- **One commit per task**, message `PRP-NNN Task N: <what>`.
- A task that changes a **public endpoint** updates the Postman collection in the
  **same commit**. A task that changes the **schema** ships the migration in the
  **same commit** as the model edit.

---

## Git & commits

- **Never commit directly to `master`.** Branch per PRP: `prp-NNN-<slug>`.
- Commit messages:
  - Per task: `PRP-NNN Task N: <imperative summary>`
  - Standalone fix: `fix: <summary>` / `docs: <summary>` / `chore: <summary>`
- When generated with Claude, end the commit body with:
  `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`
- Keep commits focused; don't mix a schema change, a feature, and a refactor.
- Don't commit `.env`, `node_modules/`, or `tmp/` (already git-ignored).

---

## Standards (enforced by review, since there's no lint/CI yet)

- Follow [feature-development-guide.md](feature-development-guide.md) exactly:
  service/controller/model separation, the `apiResponse` envelope, `validate`
  (zod), `apiKeyAuth('<scope>')`, `ApiError`, `sendAndLog` for email, `config`
  for settings, `logger` (not `console`).
- Follow [database-guide.md](database-guide.md): model ↔ migration lockstep,
  `snake_case`, `utf8mb4`, reversible migrations.
- Keep the **two realms** separate (public API vs admin) — see the Realm rule in
  the architecture doc.
- Update the **Postman contract** whenever an endpoint is added or changed.

---

## Validation before you commit (this stack)

There is no TypeScript/lint/Vite build. Use the layered checks
([feature-development-guide.md §6](feature-development-guide.md)):

```bash
# Load check (syntax + wiring)
node -e "require('dotenv').config(); require('./src/app'); require('./src/models'); console.log('OK')"

# Schema (scratch DB)
DB_NAME=shiprex_cms_test DB_USER=root DB_PASSWORD= npx sequelize-cli db:migrate

# Runtime smoke
PORT=3999 node app.js &     # curl /health, /api/v1/status, the new endpoint
```

Then exercise the admin screen in a browser and run the Postman folder.

---

## Definition of Done (per PRP)

- [ ] All tasks committed separately with `PRP-NNN Task N:` messages.
- [ ] App + models load; migrations run clean (and `down` reverses).
- [ ] Public endpoints: scoped, validated, rate-limited (writes), enveloped.
- [ ] Admin screens: states handled, role-gated, flash on writes.
- [ ] Postman collection updated; live responses match examples.
- [ ] `.env.example` updated for any new settings; no secrets committed.
- [ ] The PRP's Final Validation Checklist is fully ticked.