Updating the Docs
Required update rule
Section titled “Required update rule”Any API-facing backend change should update this repo in the same task when feasible.
Examples:
- new endpoint
- request or response shape change
- auth change
- role or visibility rule change
- pagination/filtering behavior change
- realtime or AI integration change
Where to update
Section titled “Where to update”OpenAPI spec
Section titled “OpenAPI spec”Primary file:
public/openapi/openapi.yaml
Guide pages
Section titled “Guide pages”Use src/content/docs/ for:
- integration notes
- examples
- migration notes
- behavior that is awkward to express only in OpenAPI
Agent coordination
Section titled “Agent coordination”Backend-focused work should usually update:
- the OpenAPI spec
- relevant API pages
Frontend-focused work should usually update:
- usage guides
- examples
- dashboard integration notes
Avoid drift
Section titled “Avoid drift”Do not leave the OpenAPI file stale and try to compensate with prose.
If a conflict exists between prose and the spec, the spec should be fixed first.