diff --git a/CLAUDE.md b/CLAUDE.md
index 6809dbb9..e13ac457 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -372,6 +372,12 @@ another session's roles work, swept up mid-`git add`. The other session was righ
 rewriting shared history to fix a message is the worse trade — so the record was corrected with a
 follow-up note instead. Cheap to avoid, awkward to undo.
 
+Two things about the form itself, both learned the same night. `-m`/`-F` goes BEFORE the `--`, or git
+reads the message as a pathspec. And it only works on **tracked** files — a new file must be `git add`ed
+first, so a commit introducing one is `git add <new>` then `git commit -- <paths>`, naming every path.
+Getting that wrong fails loudly, which is the good case: the release tag that followed it went onto the
+wrong commit, and only because the tag was checked afterwards did that surface at all.
+
 **An agent's commit names the session that made it.** A trailer, below `Co-Authored-By`:
 
 ```