diff --git a/LFS-IPFS.md b/LFS-IPFS.md
index 756162ba..4d0ab5bd 100644
--- a/LFS-IPFS.md
+++ b/LFS-IPFS.md
@@ -224,7 +224,8 @@ previously-committed LFS objects too, not just ones committed after they were ad
 | `private-repo LFS operations need to perform a key-agreement (ECDH) operation ...` | Your keystore is encrypted, ssh-agent can't do key agreement (protocol limitation), and no passphrase is available — normally you'd just be prompted interactively; this only happens in a non-interactive context (no TTY, e.g. CI). Set `RAD_PASSPHRASE`, or use an unencrypted keystore, or run it from a terminal. |
 | `you are not an authorized recipient of this object` | Either genuinely unauthorized (not a delegate/allow-listed DID for this private repo), or authorized *after* this specific object was committed and nobody has run `rad lfs rekey` since — ask an already-authorized collaborator to run it and push. |
 | `fatal: couldn't find remote ref refs/notes/rad-lfs` on `git fetch`/`git pull` (breaks *all* fetching, not just LFS) | Fixed — but if this repo had `rad lfs init` run against an older build, re-run `rad lfs init` once to replace the stale, now-invalid fetch refspec it configured (see `NOTES-lfs-notes-fetch-bug.md` for the full story). |
-| Plain `git push rad` (no branch name) doesn't push your commits, only the notes ref | Known, separate quirk: once any explicit push refspec is configured (which `rad lfs init` does), git stops falling back to pushing the current branch by default. Always push explicitly: `git push rad <branch>`. |
+| Plain `git push rad` (no branch name) doesn't push your commits, only the notes ref | Expected: `rad lfs init` only configures a push refspec for `refs/notes/rad-lfs`, not the branch — so `git push rad <branch>` and bare `git push rad` each push only what their own refspec covers. After committing an LFS-tracked file, run **both**: `git push rad <branch>` for the commit, then `git push rad` for the notes mapping. |
+| Collaborator gets `no CID recorded for oid ...; the peer that has this object needs to push its refs/notes/rad-lfs ref` even though they can see your commit | You (or whoever committed the LFS file) pushed the branch but forgot the follow-up bare `git push rad` — see the row above. Push it, then have them `git fetch rad` (or re-clone/re-pull). |
 
 ## Status
 
diff --git a/README.md b/README.md
index adefbf71..9f470005 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,57 @@
 > **Nothing above requires IPFS**; Git LFS support specifically needs a running `ipfs daemon`,
 > and `rad lfs init` will tell you plainly if one isn't reachable rather than failing confusingly
 > later.
+>
+> ### Quickstart cheatsheet
+>
+> One-time, per repository (with `ipfs daemon` already running in the background):
+>
+> ```sh
+> rad lfs init
+> git lfs track "*.psd"      # or whatever large-file patterns you need
+> git add .gitattributes
+> ```
+>
+> Day to day — same as plain Git LFS, just remember to push **both** the branch and the
+> `refs/notes/rad-lfs` mapping (see the push gotcha below):
+>
+> ```sh
+> git add my-large-file.psd
+> git commit -m "Add asset"  # pre-commit hook pins it to IPFS, records the CID as a git note
+> git push rad <branch>      # pushes your commit
+> git push rad               # pushes the refs/notes/rad-lfs mapping (separate step, see below)
+> ```
+>
+> Someone else, cloning the repository for the first time:
+>
+> ```sh
+> rad clone rad:<repo-id>
+> cd <repo>
+> rad lfs init                # one-time, needs their own ipfs daemon running
+> git lfs pull                 # fetches large files via IPFS instead of git
+> ```
+>
+> **Private repository?** You'll just be prompted for your keystore passphrase on `commit`/
+> `push`/`pull` when needed (ssh-agent alone can't do the key-agreement encryption requires —
+> see [`LFS-IPFS.md`](LFS-IPFS.md#encryption-for-private-repositories)). After granting a new
+> collaborator access, have an *already-authorized* collaborator run `rad lfs rekey` and push,
+> so the newcomer can decrypt files committed before they were added:
+>
+> ```sh
+> rad id update --allow <did>   # or add them as a delegate
+> rad lfs rekey                 # run by someone already authorized
+> git push rad                  # publish the updated wrapped keys
+> ```
+>
+> **The push gotcha, explained**: `rad lfs init` only configures a push refspec for the notes
+> ref, not the branch — so `git push rad <branch>` and bare `git push rad` each push only what
+> their own refspec covers, and you need *both* after committing an LFS-tracked file. Forgetting
+> the bare `git push rad` is the most common way to end up with "it works for me, but my
+> collaborator gets `no CID recorded for oid ...`" — their clone has your commit but not your
+> note yet.
+>
+> Full design, encryption details, and a longer troubleshooting table:
+> [`LFS-IPFS.md`](LFS-IPFS.md).
 
 ---