Documentation Maintenance

This documentation is part of the platform's contract surface. It must be updated with the changes it describes, not after them.

The rule

If a change alters behavior, architecture, permissions, data structures, deployment, or operational procedures, the relevant documentation must be updated with the change.

Concretely: a change is not "done" until the affected pages reflect it. Pull requests that change the system should include the documentation edits (or an explicit follow-up tracked as part of the change).

When documentation must be updated

Change	Pages to update
New/changed/removed API endpoint	API reference, API endpoints, Changelog
Schema change (table/column/constraint)	Schema, Database schema reference, Migrations, Changelog
New/changed RPC or trigger	RPC layer, RPCs reference, Migrations
Permission, clearance, rank, or allowlist change	Permissions, Authorization, Agents, Changelog
New event type or audit behavior	Event types, Events & audit, Audit integrity
Status set change	Statuses + the platform page that owns the domain
New frontend page/route/feature	Application structure, Adding a page
Deployment/operations procedure change	Deployment, Operations, Troubleshooting
Security control change	Security, Threat model — and the specific control's page
Identifier format change	Identifiers
Environment variable change	Environment variables, Environments

How API changes should be documented

1. Update the endpoint's entry in the API reference (method, path, auth, authorization, body/query, response, errors, side effects, audit/event behavior).
2. Add/remove the row in the API endpoints inventory.
3. If the change adds an event or RPC, update those references too.
4. Add a Changelog entry.

How schema changes should be documented

1. Write the migration (see Migrations) — the migration header comment is itself documentation.
2. Update the table's section in Schema and the reference.
3. Note retention/security implications (RLS, grants, triggers) on the database pages.
4. Add a Changelog entry referencing the migration number.

How security changes should be documented

Security controls are documented with the threat they address. A security change must update:

• the specific control page (authentication, authorization, input validation, media/URL safety, audit integrity);
• the threat model if the threat surface changes (new vector, removed control, residual risk change);
• the Changelog.

Never describe a security change as "hardening" without stating what it prevents.

How deployment changes should be documented

• Update the affected deployment page(s) (backend, frontend, database).
• Update Operations for runbook-affecting changes (backups, migrations, recovery, incident response).
• Update Troubleshooting when a failure mode or its resolution changes.
• Add a Changelog entry.

Accuracy obligations

• Derive from the code. Before documenting a feature, inspect the actual routes, services, migrations, RPCs, frontend usage, and tests. Do not invent endpoints, tables, functions, variables, permissions, or workflows.
• Mark uncertainty. If something cannot be confidently established from the codebase, say so explicitly (the Appeals page is the model: it documents the actual status-based model and flags what needs confirmation) rather than fabricating.
• No secrets, no sensitive data. Never document secret values, and never reproduce production data.
• No generation references. The site must read as the technical manual of a production system; do not add notes about how the software or its documentation was produced.

Verification checklist (run before publishing a change)

• [ ] Every documented endpoint exists in app.py
• [ ] Every documented table/column exists in the migrations
• [ ] Every documented RPC exists in the migrations
• [ ] Documented permissions/statuses match the implementation
• [ ] Migration instructions match the actual application tooling
• [ ] Repository paths and commands are real and valid
• [ ] Security claims are supported by the implementation
• [ ] No secrets or sensitive data present
• [ ] No broken internal links (the build warns on them)
• [ ] Site builds cleanly: npm run build in eccdps-docs/