diff --git a/friction.md b/friction.md
new file mode 100644
index 00000000..3cfa20d8
--- /dev/null
+++ b/friction.md
@@ -0,0 +1,46 @@
+# friction.md
+
+A running log of install / setup / environment friction — the papercuts that
+cost time getting clide (and its tooling) working on a machine. Newest first.
+
+Each entry: **symptom → root cause → fix**, with enough detail that the next
+person (or the next clone) can recognise and resolve it fast.
+
+---
+
+## 2026-06-06 — pql hooks disabled the repo's pre-push gate
+
+**Symptom**
+- "pql setup is broken." On the surface pql worked (`pql schema`,
+  `pql decisions sync`, `pql plan status` all fine), but the git hook wiring
+  was in a split-brain state.
+
+**Root cause**
+- The repo's intended setup is `git config core.hooksPath .githooks` (run via
+  `make hooks`). `.githooks/` is the committed, canonical hook set: it carries
+  **both** pql's planning delegators (pre-commit / post-merge / post-checkout /
+  post-rewrite, each sourcing `.pql/hooks/*`) **and** the repo's own `pre-push`
+  gate (`make push-check`).
+- `core.hooksPath` was **unset** in every scope, so git fell back to the
+  default `.git/hooks/`. `pql init` had populated *that* directory with only
+  the pql delegators — **no `pre-push`**.
+- Net effect: the pre-push gate (decisions + core + fast tests + a11y) was
+  silently **not running** on push, while pql's automation ran only by accident
+  from the default dir. CLAUDE.md requires the gate to always run and forbids
+  `--no-verify`, so this was a real (silent) regression, not cosmetic.
+
+**Fix**
+- `make hooks` → restores `core.hooksPath = .githooks` (now `pre-push` and the
+  pql delegators all fire from one canonical, git-tracked source).
+- Removed the stray pql-only delegators from `.git/hooks/`
+  (`pre-commit`, `post-merge`, `post-checkout`, `post-rewrite`). They became
+  inert once hooksPath pointed elsewhere, and leaving them created a dangerous
+  partial fallback — a hook set that runs pql but silently skips the pre-push
+  gate if `core.hooksPath` ever gets unset again. The real hook logic lives in
+  `.pql/hooks/` and was untouched.
+
+**Watch out for**
+- `pql init` installs into the default `.git/hooks/` and does **not** respect an
+  existing `core.hooksPath`. After running it, re-run `make hooks` and verify
+  with `git rev-parse --git-path hooks` (should print `.githooks`) and confirm
+  `.githooks/pre-push` is present & executable.