# Docs Maintenance Playbook

Use this checklist to keep the wiki accurate as features are added or changed.

---

## Definition of Done (Docs)

A feature PR is not done until docs are updated when any of these changed:

- DB schema (`backend/prisma/schema.prisma`)
- Backend routes/contracts (`backend/src/routes`, `backend/src/channels`)
- Agent behavior (`backend/src/agents`)
- Frontend flows/routes (`frontend/src/app`, `frontend/src/lib/api.ts`)
- Required env vars or deployment behavior

---

## Update Workflow

1. **Edit source docs first**
   - Update files in `docs/`:
     - `README.md` for architecture/overview changes
     - `API.md` for route/contract changes
     - `STATUS.md` for capability status changes
     - `ROADMAP.md` for execution-priority or timeline changes
     - add or update topic docs as needed

2. **Mirror docs for in-app wiki**
   - Copy changed files from `docs/` to `frontend/public/docs/`
   - Keep file names identical

3. **Register new docs page (if added)**
   - Update `frontend/src/app/docs/config.ts`
   - Add slug/title/description and path mapping

4. **Sanity check**
   - Open `/docs` in app
   - Confirm index entry, page rendering, and links

---

## Change-to-Doc Mapping

| Code change type | Required doc updates |
|---|---|
| New/changed API endpoint | `docs/API.md`, usually `docs/STATUS.md` |
| New Prisma model/field | `docs/README.md` architecture section, `docs/STATUS.md` |
| New agent or runner behavior | `docs/README.md`, `docs/STATUS.md`, maybe `reference-agents/README.md` |
| New frontend route/user flow | `docs/README.md` and `docs/FRONTEND_USAGE.md` |
| New env var/deploy step | `docs/QUICKSTART.md` and deployment docs |

---

## PR Template Snippet

Copy into PR description when feature touches product behavior:

```md
## Docs Update Checklist
- [ ] Updated source docs in `docs/`
- [ ] Mirrored changes to `frontend/public/docs/`
- [ ] Updated docs index/path in `frontend/src/app/docs/config.ts` (if needed)
- [ ] Verified pages render at `/docs`
```

---

## Recommended Ownership

- **Feature author** updates docs in the same PR.
- **Reviewer** verifies the checklist and spot-checks `/docs`.

This keeps the wiki continuously current rather than relying on periodic catch-up updates.