diff --git a/CLAUDE.md b/CLAUDE.md
index 5992889..07aab04 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -24,6 +24,16 @@ bun run lint         # eslint .
 bun run format       # prettier --write .
 ```
 
+If `bun` isn't on PATH (sandboxed/CI environments), use the `npx`/`bunx` equivalents:
+`npx tsc --noEmit -p tsconfig.json` (typecheck, no npm script exists for this),
+`npx eslint src` (not `npx eslint .` — a full-repo scan chokes on the root-owned
+`infra/supabase/docker/volumes/db/data` directory), `npx prettier --write <files>`.
+
+This repo is not fully `prettier`-clean — a fresh `eslint`/`prettier --check` run surfaces
+hundreds of pre-existing formatting errors unrelated to any given change. Filter with
+`grep -v "prettier/prettier"` to see real lint issues, and run `prettier --write` only on the
+files you touched, not the whole repo.
+
 There is no test runner configured in this repo.
 
 Adding a dependency: `bunfig.toml` enforces a 24h supply-chain guard (`minimumReleaseAge`) on new
@@ -107,6 +117,10 @@ load-bearing, not style preferences:
   content type via `/api/public/scout-finale` at match end, so it becomes visible cross-device in
   the admin panel — no retry if that POST fails, the local save already succeeded either way. The
   in-progress resume state still goes only to the `scout_live` Supabase table, unrelated to Strapi.
+- Local dev quirk: this machine's `infra/supabase/docker/.env` may customize `POSTGRES_PORT`
+  away from the documented default `5432` (e.g. to avoid colliding with another project's
+  Postgres) — check that file before assuming the template's port when wiring up a new service
+  to the same database.
 - Push notifications only for high-value events (convocations, training/match reminders, ball-duty
   turn, final result) — no chat/photo/video features.