Docs sync

Goal

Update documentation so it matches the current code and is easy for the target audience to follow.

Inputs to ask for (if missing)

• What changed (feature/bugfix/refactor) and who the docs are for.
• Which docs surfaces matter: README, /docs, wiki, runbooks, API spec, changelog, onboarding.
• Any required format/voice (company style guide, "keep it short", etc.).

Workflow (checklist)

1. Identify what changed
   • Use the diff to locate impacted areas:
     • git diff --name-only
     • git diff
2. Inventory docs surfaces in the repo
   • Common locations: README.md, docs/, CONTRIBUTING.md, CHANGELOG.md, openapi.*, schema.graphql, adr/, runbooks/.
   • For Spring: check for generated OpenAPI/Swagger docs or endpoint annotations.
   • For Next/TypeScript: check for docs pages, Storybook, or typed API clients.
   • If your repo uses docs/ as the primary doc root, see references/docs-structure.md for a suggested layout.
3. Decide what needs updating
   • Ensure docs cover:
     • setup and local dev commands
     • required env vars / config keys
     • API contract changes (request/response examples)
     • DB migrations and operational steps
     • behavior changes visible to users
   • If the change is an architectural/behavioral decision, add or update an ADR (use references/adr-template.md).
4. Apply edits with minimal churn
   • Prefer small, targeted edits over rewrites.
   • Add examples that are copy/paste runnable.
   • Keep headings stable to avoid breaking deep links.
   • Use templates in references/ when helpful.
5. Verify docs are consistent
   • Run the repo's existing doc checks if present (md lint, docs build, site build).
   • At minimum: ensure code fences match the actual commands and file paths, and env var names match the code.

Deliverable

Provide:

• The list of docs files updated and why.
• A short "How to verify" section (commands or manual checks).