diff --git a/.gitignore b/.gitignore
index 1c5d75631..a87989b9f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,6 @@ mutants.out*
 *.ikm
 *payjoin.sqlite
 data
+.claude/
+.direnv/
+__pycache__/
diff --git a/AGENTS.md b/AGENTS.md
index 28491fcdc..ce5d99af6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -9,7 +9,8 @@ unstable options.
 
 Tools are provided by nix via direnv. Do not install tools globally.
 If you need a new tool, add it to the devshell in `flake.nix` so
-others can reproduce.
+others can reproduce. rust-analyzer LSP is available for navigation
+(go-to-definition, find-references, hover) — prefer it over grepping.
 
 ## Commit Rules
 
@@ -57,6 +58,28 @@ dependency change:
 bash contrib/update-lock-files.sh
 ```
 
+## Spec-code mapping
+
+| Spec section            | Code location                                                    |
+| ----------------------- | ---------------------------------------------------------------- |
+| BIP 77 sender flow      | `payjoin/src/core/send/v2/mod.rs`                                |
+| BIP 77 receiver flow    | `payjoin/src/core/receive/v2/mod.rs`                             |
+| BIP 77 directory        | `payjoin-directory/src/lib.rs` `handle_decapsulated_request()`   |
+| BIP 78 sender checklist | `payjoin/src/core/send/mod.rs` `PsbtContext::process_proposal()` |
+| BIP 78 receiver checks  | `payjoin/src/core/receive/mod.rs` `OriginalPayload` methods      |
+| OHTTP (RFC 9458)        | `payjoin/src/core/ohttp.rs`                                      |
+
+## Non-obvious things
+
+- `payjoin/src/lib.rs` re-exports all of `src/core/` — the `core`
+  module is the entire implementation but is `pub(crate)`.
+- `receive::v2` types wrap `receive::common` via `.inner`; all PSBT
+  logic lives in `common/`.
+- Relay vs directory routing lives in `payjoin-mailroom`, not in
+  either sub-crate.
+- V1 proposals through V2 directories MUST disable output substitution
+  (enforced in `receive::v2::unchecked_from_payload()`).
+
 ## AI Disclosure
 
 Add to PR body: `Disclosure: co-authored by <agent-name>`
diff --git a/payjoin/src/core/ohttp.rs b/payjoin/src/core/ohttp.rs
index 2036a9f5a..d92678ac8 100644
--- a/payjoin/src/core/ohttp.rs
+++ b/payjoin/src/core/ohttp.rs
@@ -1,3 +1,8 @@
+//! OHTTP encapsulation (RFC 9458) for v2 communication.
+//!
+//! The relay (ohttp-relay) sees client IPs but not content; the gateway
+//! (inside payjoin-directory) sees content but not IPs.
+
 use std::ops::{Deref, DerefMut};
 use std::{error, fmt};
 
diff --git a/payjoin/src/core/persist.rs b/payjoin/src/core/persist.rs
index bb5083e43..52d5def7c 100644
--- a/payjoin/src/core/persist.rs
+++ b/payjoin/src/core/persist.rs
@@ -1,3 +1,9 @@
+//! Session persistence for the typestate protocol.
+//!
+//! Protocol methods that advance state return a transition type from
+//! this module. Call `.save(&persister)` to persist the session event
+//! and extract the next state.
+
 use std::fmt;
 
 /// Representation of the actions that the persister should take, if any.