diff --git a/README.md b/README.md
index 3342f86..49599b1 100644
--- a/README.md
+++ b/README.md
@@ -52,3 +52,19 @@ Connection (dev): host `localhost`, port `5432`, database `neon_sprawl`, user `n
 ### Run the client
 
 Open the [`client/`](client/) folder in **Godot 4.6** and run the main scene (see [`client/README.md`](client/README.md)).
+
+### Git hooks and GDScript lint (recommended)
+
+Once per clone, from the repo root:
+
+```bash
+./scripts/install-git-hooks.sh
+python3 -m venv .venv-gd
+.venv-gd/bin/pip install "gdtoolkit==4.5.0"
+```
+
+This sets **`core.hooksPath=scripts/git-hooks`**. On push, when **`client/scripts/*.gd`** or **`client/test/*.gd`** changed in the commits being pushed, **pre-push** runs **`gdlint`** and **`gdformat --check`** on those trees (same as [`.github/workflows/gdscript.yml`](.github/workflows/gdscript.yml)). Install **gdtoolkit** in **`.venv-gd`** (gitignored) or globally so the hook can run; otherwise pushes with GDScript changes are blocked.
+
+Windows (PowerShell): `pwsh -File scripts/install-git-hooks.ps1`, then create `.venv-gd` and `pip install "gdtoolkit==4.5.0"` the same way.
+
+More detail: [`client/README.md`](client/README.md) (Git hooks section).