Add navigability signposts for agents

Minimal ARCHITECTURE.md maps BIP 77/78 spec sections to
code locations and documents non-obvious structural
decisions (pub(crate) core re-export, common/ wrapping,
mailroom routing split).

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
 

ARCHITECTURE.md

@@ -0,0 +1,26 @@
+# Architecture
+
+Implements [BIP 77](https://github.com/bitcoin/bips/blob/master/bip-0077.md) (v2)
+and [BIP 78](https://github.com/bitcoin/bips/blob/master/bip-0078.mediawiki) (v1).
+
+## 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()`).

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.