diff --git a/AGENTS.md b/AGENTS.md
index 4224fc54ffaf..7deb7d1905c6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -62,6 +62,14 @@ All public methods should have a comment. So should most private ones!
 # Git Committing
 Always include a good description when creating a git commit.
 
+# Papercuts
+When you hit tooling/process friction, have to work around something, or learn something these
+docs should have told you — and now isn't the time to fix it — prepend a short entry to
+`PAPERCUTS.md` at the repo root (format in that file's header). Don't make a separate commit
+for it (it rides along in your next commit), don't derail your current task, and mention the
+logged cut in your final report. Cuts about the environment or team workflow (not this repo)
+go in your local bloom-team-skills clone's `PAPERCUTS.md` instead, if you have one.
+
 # Skills
 Reusable, task-specific procedures for this repo live in `.github/skills/<name>/SKILL.md`.
 When a request matches one of these, READ the matching `SKILL.md` and follow it as the
diff --git a/PAPERCUTS.md b/PAPERCUTS.md
new file mode 100644
index 000000000000..46744f6551c5
--- /dev/null
+++ b/PAPERCUTS.md
@@ -0,0 +1,31 @@
+# Papercuts
+
+Small dev/agent/tooling friction points and improvement ideas — captured in the moment,
+fixed later. This file holds cuts about **this repo** (its docs, scripts, build, tests,
+agent experience); cuts about the environment, machine, or team workflow go in
+bloom-team-skills' `PAPERCUTS.md`. The full procedure is the `papercut` skill in
+https://github.com/BloomBooks/bloom-team-skills.
+
+House rules:
+
+- Add new entries at the **top**, directly under this header block.
+- Entry format: `## YYYY-MM-DD — Title`, then `- **Cut:**` / `- **Idea:**` / optional
+  `- **Context:**` lines. 2–5 lines total.
+- Hit the same cut again? Add a dated `seen again: ...` line to the existing entry instead of
+  duplicating it.
+- On a merge conflict here, keep both sides' entries.
+- Product bugs/features go to YouTrack instead.
+- To work through the backlog, run the `papercut` skill in trim mode ("trim the papercuts").
+  Fixed, promoted, or stale entries get **deleted** — the log only contains open cuts.
+
+---
+
+## 2026-07-10 — Pre-commit hook fails confusingly when node_modules is empty
+
+- **Cut:** With `src/BloomBrowserUI/node_modules` empty (e.g. a fresh checkout/worktree after
+  the pnpm migration, before `pnpm install`), `git commit` fails with
+  `pretty-quick: command not found` — and since the hook runs mid-command, the failed commit
+  is easy to miss.
+- **Idea:** Have `.vite-hooks/pre-commit` check for `node_modules/.bin/pretty-quick` first and
+  fail with "front-end dependencies not installed — run `pnpm install` in src/BloomBrowserUI".
+- **Context:** Hit while committing this very file.