# AI Documentation Guide (Mandatory)

> **Audience:** Cursor agents, Copilot, and any AI assistant working on SDM (backend or frontend).
>
> **Rule:** If you change behavior, APIs, roles, or admin UI flows, you **must** update documentation in the same task — not as an optional follow-up.

---

## 1) When documentation is required

Update docs **in the same PR/session** when you:

| Change type | Update these docs |
|---|---|
| New or changed API route / controller | Relevant topic doc (e.g. `03-registration-system.md`) + `00-docs-index.md` if new doc added |
| New admin UI flow (modal, table, role gate) | Topic doc + note in `09-development-guide.md` or frontend rules if UI-only |
| Prisma schema / model field rename | `06-database-and-prisma.md` + any doc referencing the old field |
| Role or authorization change | `02-authentication-and-roles.md` |
| Payment / cashflow / transaction logic | `04-cashflow-and-transactions.md` |
| Registration create/edit/delete/archive | `03-registration-system.md` |
| Registration UI copy / success screen buttons | `03-registration-system.md` + all three locale files (`en.json`, `gu.json`, `hi.json`) |
| New env var or npm script | `01-project-overview.md` |
| New recurring convention for AI/humans | This file (`10-ai-documentation-guide.md`) |

**Do not** create new markdown files unless the feature is large enough to deserve its own doc — prefer extending the closest existing file and adding a row to `00-docs-index.md`.

---

## 2) What “up to date” means

Documentation must reflect **current production intent**, not historical plans:

- Endpoint paths, HTTP methods, and **authorized roles** must match `src/routes/*.js`.
- Field names must match `prisma/schema.prisma` (e.g. `karyakartaHaridhamId`, not `haridhamId` on `Registration`).
- UI behavior must match shipped components (file paths help future agents find code quickly).
- Remove or rewrite sections that describe **removed** behavior (e.g. soft-delete-only registration delete).
- Add a **“Last updated”** line at the top of heavily edited sections when the change is significant.

---

## 3) Documentation workflow for AI agents

Follow this checklist **before** marking a feature complete:

```
[ ] Identify which doc(s) in sdm-backend/docs/ describe this area
[ ] Read those docs first when starting work (do not rely on memory)
[ ] After code changes, update the doc section(s) with:
    - What changed and why (1–3 sentences)
    - API contract (method, path, body fields, role gate)
    - Frontend entry points (component paths) if applicable
    - Edge cases / validation errors returned to the client
[ ] If frontend-only UI rules changed, update sdm-frontend/AI_FRONTEND_RULES.md
[ ] If a new doc file was added, add it to 00-docs-index.md
[ ] Do not document secrets, .env values, or credentials
```

---

## 4) Writing style

- Use **present tense** for current behavior.
- Prefer tables and bullet lists for API fields and role matrices.
- Include **concrete examples** (sample JSON body, sample error message).
- Link related docs with relative paths: `[03-registration-system.md](./03-registration-system.md)`.
- Keep docs **accurate over exhaustive** — one correct paragraph beats a long outdated guide.

---

## 5) Backend + frontend split

| Layer | Primary docs |
|---|---|
| API, Prisma, business rules | `sdm-backend/docs/*.md` |
| UI tables, modals, responsive rules | `sdm-frontend/AI_FRONTEND_RULES.md` |
| Cross-cutting admin features | Both — backend doc owns API; frontend rules or topic doc owns UX |

Example: **Admin registration edit modal** is documented in `03-registration-system.md` (API + rules) with frontend files cited there; table/sheet patterns still follow `AI_FRONTEND_RULES.md`.

---

## 6) Role documentation accuracy

When documenting `authorizeRole([...])`:

- Listing `SUPER_ADMIN` **also allows** `DB_ADMIN` via `normalizeAuthorizedRoles()` in `src/constants/roles.js`.
- `ACCOUNT_ADMIN` is **not** auto-expanded from `SUPER_ADMIN` — it must appear explicitly in the route’s role array.
- `DB_ADMIN` does **not** imply `ACCOUNT_ADMIN` or vice versa.

Always copy the **exact** role array from the route file into docs.

---

## 7) Anti-patterns (do not do this)

- Shipping a new admin endpoint without documenting it in the topic doc.
- Leaving docs that contradict the code (e.g. “soft delete only” after archive+hard-delete shipped).
- Creating duplicate docs for the same feature in multiple files without cross-links.
- Documenting planned features as if they already exist.
- Skipping doc updates because “the user didn’t ask for docs” — **this guide is the user’s standing instruction.**

---

## 8) Suggested doc touchpoints by code location

| Code area | Doc |
|---|---|
| `src/controllers/registrationController.js` | `03-registration-system.md` |
| `src/controllers/adminController.js` (registration admin) | `03-registration-system.md` |
| `src/routes/adminRoutes.js` | Topic doc + `02-authentication-and-roles.md` for roles |
| `src/controllers/cashflowController.js` | `04-cashflow-and-transactions.md` |
| `prisma/schema.prisma` | `06-database-and-prisma.md` |
| `sdm-frontend/src/components/registrations-*.tsx` | `03-registration-system.md` (Admin UI section) |

---

## 9) For human reviewers

If a PR changes behavior in `src/` or admin-facing `sdm-frontend/` components and **no** doc update is present, request doc updates before merge — unless the change is a pure refactor with zero behavioral difference.