diff --git a/README.md b/README.md
index 82fc764..d83d060 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,22 @@ docs/                  install, enroll-recipe, secrets, architecture, runbook, b
 - `docs/architecture.md`, `docs/runbook.md` — design + debugging failed runs
 - `docs/baseline.md` — bootstrap snapshot / rollback reference
 
+## Linting & formatting
+
+The codebase is kept formatted + lint-clean by a single entrypoint, run from the pinned `lint`
+devshell so local and CI use identical tool versions:
+
+```sh
+nix develop .#lint --command bash scripts/lint.sh         # check-only (what CI runs)
+nix develop .#lint --command bash scripts/lint.sh --fix   # auto-format + apply fixes
+```
+
+Covers Nix (`nixpkgs-fmt` · `statix` · `deadnix`), Python (`ruff` lint+format), Shell
+(`shellcheck` · `shfmt`), and YAML (`yamllint`). Config lives in `ruff.toml` / `.yamllint.yaml`;
+tool/strictness choices are in `DECISIONS.md`. **CI enforces it:** the `lint` step in the
+`.drone.yml` push pipeline runs the same command and **fails the build** on any unclean file, so
+keep commits clean (`--fix` before pushing).
+
 ## Loop state (autonomous build)
 
 `STATUS.md` (phase/blockers), `BACKLOG.md` (work + adversary findings), `REVIEW.md` (independent