Documentation Maintenance

This project treats docs as a first-class artifact. Behavior changes are incomplete until docs are updated.

Rules

1. Any endpoint change requires updates in docs/api-reference.md.
2. Any webhook event or payload change requires updates in docs/webhooks.md.
3. Any CLI UX/keybinding change requires updates in docs/cli.md and cli/zmail/README.md.
4. Any deployment or DNS change requires updates in docs/deployment-operations.md.
5. Root README.md should always link to current docs index.

Required Update Triggers

• New route, removed route, status code change
• Request/response schema change
• Auth behavior change
• New folder/state semantics
• Tenant isolation behavior change
• New operational runbook steps

PR/Commit Checklist

• [ ] Code change complete
• [ ] Docs updated in same change
• [ ] Example payloads still valid
• [ ] Keybindings and CLI examples verified
• [ ] Smoke checklist re-run after deploy

Lightweight Drift Control

At least once per week (or before significant releases):

1. Run ./scripts/docs_audit.sh and fix any reported API doc gaps.
2. Compare webhook events in webhook_dispatcher.py to docs/webhooks.md.
3. Run CLI and verify docs/cli.md keymaps.
4. Update docs date stamp in release notes or deployment notes.

Ownership

• Feature owner updates docs for their area.
• Release owner confirms cross-doc consistency before deploy.

Suggested Automation (next step)

• Add CI script to diff documented endpoints vs discovered routes.
• Fail CI when route lists diverge.