diff --git a/CLAUDE.md b/CLAUDE.md
index fae1a598..e2548902 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -165,6 +165,9 @@ The docs below own the details — this section just points at them.
 
 - **Commit style, naming, identity, reconcile verb:** →
   [`docs/conventions.md`](docs/conventions.md).
+- **Never add `#[allow(clippy::…)]`** — fix the lint instead (extract a
+  helper, add backticks, etc.). Details + worked examples: →
+  [`docs/conventions.md`](docs/conventions.md#building--local-checks).
 - **NixOS / nspawn quirks** (bind mounts, conf flags, etc.): →
   [`docs/gotchas.md`](docs/gotchas.md).
 - **Turn loop, sentinels (rate-limit, auth-failed), context
diff --git a/docs/conventions.md b/docs/conventions.md
index c2918082..a837bfcb 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -472,6 +472,20 @@ nix fmt                       # treefmt — authoritative, NOT bare cargo fmt
 misses the non-rust files treefmt also covers, so always run `nix
 fmt` before pushing.
 
+**Clippy discipline — never add `#[allow(clippy::…)]`.** All lints are
+CI-fatal at `-D warnings` (pedantic included); every warning that fires
+must be *fixed*, not silenced. Common patterns:
+
+- `too_many_lines` — extract a helper function or a sub-struct
+  (the `TurnAccum` extraction in `stats.rs` is a worked example).
+- `doc_markdown` (brand name without backticks in a doc comment) — add
+  backticks: `` `DOMPurify` `` instead of `DOMPurify`.
+- `must_use` / `unused_results` — actually handle or explicitly discard
+  the return value (`let _ = …` is fine when intentional).
+
+If a lint seems wrong for a specific call site, file an issue and ask
+mara — don't add `#[allow]` speculatively. The gate is intentional.
+
 **The devshell checks are not the full `nix flake check`.** Clippy /
 fmt / `cargo test` cover most gates, but `nix flake check` runs extra
 check derivations they don't: