diff --git a/CLAUDE.md b/CLAUDE.md
index 5438b43a..73323ea1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -111,13 +111,18 @@ bun dev          # the whole app — SPA + API + WebSockets, watched
 bun start        # production
 bunx tsgo        # typecheck (not tsc)
 bun test         # tests
-bun format       # prettier over changed files only
+bun format       # prettier over every dirty file — see the note below before running it
 bun db:push      # apply the schema to Postgres
 bun setup        # guided install (writes .env, incl. PUBLIC_BUILD_ENV=production)
 ```
 
 Sidecar control: `bun run start:sidecar` / `stop:sidecar` / `restart:sidecar` / `logs:sidecar`.
 
+**Format your own files, not the whole dirty tree.** `bun format` globs `git diff --name-only HEAD`,
+so it rewrites every uncommitted file — including work in progress that isn't yours, which then shows
+up as unexplained whitespace churn in someone else's diff. Run `bunx prettier --write <paths>` on the
+files you actually touched. `bun format` is only safe when the tree is otherwise clean.
+
 Note: `build:editor*` in `package.json` points at `scripts/build/editor.ts`, which does not exist.
 
 ## Code Style