git:20260712.393de85 to git:20260831.7d13b8f

8 added, 0 removed. Audit A to A.

---

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.

+ The project is excluded from the ordinary `pnpm test` run because it writes into the repo, so

+ regenerate deliberately and commit the result. `docs:snapshots:check` generates TWICE before

+ `git diff --exit-code`: Vite's first run after a config change can re-optimise dependencies and

+ produce a one-off pixel drift, so the second run is the stable artifact. Diffs surviving a

+ double run are a real UI change, not jitter. Cross-platform font rendering means a Linux CI

+ capture is not byte-identical to a macOS one — this stays a developer-driven, regenerate-locally

+ workflow.

## 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.