| name | docs-sync |
| description | When and how to update the whiteboard project's docs alongside a code change — the trigger→target map, Diátaxis quadrants, doc locations, the honesty rule, and doc-image regeneration. Use when a change has a user-visible effect, alters an API/contract/config, or when triaging a docs gap. |
Docs Sync
Docs, code, and tests stay in sync within the same change. A user-visible behavior, API, contract, or config change that ships without its docs is incomplete.
Audience split & language (project rules)
./docs/** = USER-facing only, Diátaxis (tutorials / how-to / reference / explanation).- Developer/contributor docs = OSS convention at repo root:
README.md, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, .github/ templates, etc. Never put contributor guides under ./docs.
- Language: English for everything under
docs/, README, SECURITY, CONTRIBUTING, .github (local tmp/ notes may differ).
Trigger → target
| Change | Update |
|---|
| User-visible behavior (UI, flow, MCP tool result that depends on state) | the how-to / tutorial that covers that flow; attach evidence per PR Visual Evidence rule |
| MCP tool added/changed (input/output schema) | tool reference docs + any skill that lists tools (keep tool lists in sync — a known drift source) |
| HTTP route / response shape | API reference; the typed-client docs if any |
| Persisted JSON / migration / data model | the relevant explanation/reference + migration notes |
| Config / env / deploy path | README + getting-started + self-host/docker docs + .env.example |
| New capability with no doc home | propose a new page in the right Diátaxis quadrant |
Diátaxis quadrants
- Tutorial — learning-oriented, "first X in 5 minutes" (the empty quadrant is a known gap).
- How-to — task-oriented recipes.
- Reference — dry, complete (tools, routes, config).
- Explanation — why/architecture/trade-offs.
Keep each doc in its quadrant; don't mix tutorial and reference.
Honesty rule
Document the shipped state, never the aspiration. Do not describe a feature/flag/route/path that doesn't exist yet. If the code is partial (e.g. apps/web mid-migration), document the real current behavior. Getting-started must be runnable as written.
Doc images
Images under docs/assets/** produced from the UI are regenerated by Vitest browser-mode tests, not hand-edited:
pnpm --filter @kamiazya/whiteboard-web docs:snapshots
Add a *.docs-snapshot.test.tsx, pin the clock, save via resolveDocAssetPath, run, and commit the PNG with the markdown that references it.
Discipline
Update only doc files in a docs pass; commit them separately with a docs: message. Fix broken links you touch. Surface any user-visible change you could not find a doc home for.
