Add navigability signposts for agents

Spec-code mapping and non-obvious structural notes
inlined into AGENTS.md where agents auto-load them.
Module docs on persist.rs and ohttp.rs orient agents
hitting these files for the first time. Gitignore hides
generated/tooling dirs that waste exploration rounds.

Informed by arxiv.org/abs/2602.11988 which found verbose
context files hurt agent performance — these signposts
are kept minimal and focused on things LSP cannot surface.

Author: DanGould

.gitignore

@@ -8,3 +8,6 @@ mutants.out*
 *.ikm
 *payjoin.sqlite
 data
+.claude/
+.direnv/
+__pycache__/

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>`

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};
 

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.