From 5b6cd13a597428ee53a918020f22d73a51fab312 Mon Sep 17 00:00:00 2001
From: Mayukha Vadari <mvadari@gmail.com>
Date: Fri, 4 Sep 2026 23:07:38 -0400
Subject: [PATCH 1/6] docs: Codify recurring PR review feedback into AGENTS.md

Mined 6 months of merged PR review comments (human reviewers only) for
conventions that recur across multiple PRs/reviewers but aren't already
documented in CONTRIBUTING.md/CodingStyle.md, and folded them in:

- Doxygen comments expected on new public functions/methods.
- API-CHANGELOG.md requirement is repo-wide, not RPC-directory-scoped.
- Shared test setup belongs in jtx/, not copy-pasted across test files.
- Amendment requirement test and a design-considerations checklist,
  sourced from the internal "Considerations for Future Amendments" doc.
- Amendment gating shape (single enabled/disabled block), per-amendment
  flag naming, and UNREACHABLE/LCOV_EXCL pairing, all recurring asks in
  tx/vault/invariant PR reviews.
---
 AGENTS.md                |  7 ++++++-
 src/libxrpl/tx/AGENTS.md | 18 +++++++++++++++++-
 src/xrpld/rpc/AGENTS.md  |  4 ++--
 3 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 85bf9befb2d..f7748a4600f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,6 +22,7 @@ Unit tests are a custom framework built into the `xrpld` binary itself (not Boos
 - `--unittest-arg` does nothing — don't use it.
 - Tests that run offline in under a minute should be automatic `--unittest` suites; anything else is a manual/integration test.
 - New tests should be written using `gtest` under `src/tests/` unless that isn't possible, in which case fall back to the legacy Beast framework under `src/test/`. `tests/` (top-level) holds integration tests exercised against `libxrpl`/`xrpld`.
+- Shared test setup/helper code used by more than one test file belongs in `jtx/` (`src/test/jtx/`), not copy-pasted across test files.
 
 ## Lint/Format
 
@@ -29,7 +30,11 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md#pre-commit-hooks) for `pre-commit` setup
 
 ## Code Style
 
-New file placement and header levelization: see [CONTRIBUTING.md](./CONTRIBUTING.md#before-making-a-pull-request). Braces, whitespace, member order, and other conventions: see [docs/CodingStyle.md](./docs/CodingStyle.md). `XRPL_ASSERT`/`UNREACHABLE` contracts: see [CONTRIBUTING.md](./CONTRIBUTING.md#contracts-and-instrumentation). Commit messages: see [CONTRIBUTING.md](./CONTRIBUTING.md#good-commit-messages).
+New file placement and header levelization: see [CONTRIBUTING.md](./CONTRIBUTING.md#before-making-a-pull-request). Braces, whitespace, member order, and other conventions: see [docs/CodingStyle.md](./docs/CodingStyle.md). `XRPL_ASSERT`/`UNREACHABLE` contracts: see [CONTRIBUTING.md](./CONTRIBUTING.md#contracts-and-instrumentation). Commit messages: see [CONTRIBUTING.md](./CONTRIBUTING.md#good-commit-messages). New public functions/methods need a Doxygen-style comment.
+
+## API Changelog
+
+Any change to publicly-visible API behavior — RPC/WebSocket fields, parameters, or error conditions, or transaction/signing behavior surfaced through the API — needs an entry in [API-CHANGELOG.md](./API-CHANGELOG.md) under `## Unreleased`, regardless of which directory the change lives in.
 
 ## Architecture
 
diff --git a/src/libxrpl/tx/AGENTS.md b/src/libxrpl/tx/AGENTS.md
index e2261fc1adf..de27c59d483 100644
--- a/src/libxrpl/tx/AGENTS.md
+++ b/src/libxrpl/tx/AGENTS.md
@@ -2,4 +2,20 @@
 
 See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance.
 
-Any change to transaction-processing behavior must be gated behind an amendment. New amendments (and fixes, i.e. `fix*` amendments) are added to [`include/xrpl/protocol/detail/features.macro`](../../../include/xrpl/protocol/detail/features.macro), as an `XRPL_FEATURE(...)` or `XRPL_FIX(...)` entry added to the top of the list (the list is kept in reverse chronological order). Once the pre-amendment code path for a retired amendment is removed, move its entry to `XRPL_RETIRE_FEATURE(...)`/`XRPL_RETIRE_FIX(...)` instead of deleting it.
+## When an amendment is required
+
+A change needs an amendment if it affects transaction processing, ledger objects, or anything else about the binary format or hash of the ledger. An amendment is optional if a change only affects what transactions get proposed for consensus (e.g. fee escalation). Otherwise, don't use one.
+
+New amendments (and fixes, i.e. `fix*` amendments) are added to [`include/xrpl/protocol/detail/features.macro`](../../../include/xrpl/protocol/detail/features.macro), as an `XRPL_FEATURE(...)` or `XRPL_FIX(...)` entry added to the top of the list (the list is kept in reverse chronological order). Once the pre-amendment code path for a retired amendment is removed, move its entry to `XRPL_RETIRE_FEATURE(...)`/`XRPL_RETIRE_FIX(...)` instead of deleting it.
+
+When adding a new amendment or transaction type, check its interaction with: invariants, fees, Deposit Auth, Batch transaction inclusion/exclusion, Permission Delegation inclusion/exclusion, Freeze/Deep Freeze (IOU) and Lock (MPT), Clawback, Credentials and Permissioned Domain, the case where the submitting account is the asset's issuer, and numeric over/underflow. Stick to existing paradigms rather than inventing new ones — consistency between features matters more than a locally "better" design.
+
+New (or deleted) invariant checks must be amendment-gated: they introduce (or remove) a way for a transaction to fail, and an un-gated change risks validators disagreeing on a transaction's result, i.e. a network fork.
+
+## Gating amendment-dependent code
+
+Prefer a single amendment-enabled block and a single disabled block over scattering `rules.enabled(...)` checks through a function, even if the two blocks are similar.
+
+When a file or function checks more than one amendment, name local enablement booleans per-amendment (e.g. `fix340Enabled` for `fixCleanup3_4_0`), not a generic `fixEnabled` — it becomes ambiguous once a second amendment is checked in the same scope.
+
+Only use `UNREACHABLE` for genuinely impossible paths, not to avoid writing a test for one that's reachable but rare. When a branch marked `UNREACHABLE` is excluded from coverage, wrap it in `LCOV_EXCL_START`/`LCOV_EXCL_STOP`.
diff --git a/src/xrpld/rpc/AGENTS.md b/src/xrpld/rpc/AGENTS.md
index 14fdd7a03ea..1dc26800d51 100644
--- a/src/xrpld/rpc/AGENTS.md
+++ b/src/xrpld/rpc/AGENTS.md
@@ -1,5 +1,5 @@
 # AGENTS.md — rpc
 
-See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance.
+See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance, including the [API Changelog](../../../AGENTS.md#api-changelog) rule.
 
-Any change to a public RPC method's behavior (new/changed/removed fields, parameters, or error conditions) needs a corresponding entry in [`API-CHANGELOG.md`](../../../API-CHANGELOG.md), under the `## Unreleased` section (`### Additions`, `### Deprecations`, etc. as appropriate).
+A change to a public RPC method's behavior (new/changed/removed fields, parameters, or error conditions) is exactly the kind of API-visible change that rule covers — use `### Additions`, `### Deprecations`, etc. under `## Unreleased` as appropriate.

From 0a1708dbfec5e00ef46bcfdbc4f5985f273738fc Mon Sep 17 00:00:00 2001
From: Mayukha Vadari <mvadari@gmail.com>
Date: Tue, 8 Sep 2026 17:05:08 -0400
Subject: [PATCH 2/6] docs: Add subsystem AGENTS.md files for transactors,
 ledger helpers, and READMEs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round 2 of PR-review mining: found two subsystem-specific, unrecorded
conventions (pseudo-account auth/freeze exemption in vault/lending
transactors; SLE-type assertion in ledger helpers) that warrant their
own nested AGENTS.md rather than more root-level bullets.

Also added thin AGENTS.md pointer files (with CLAUDE.md symlinks,
matching the existing convention) for subsystems that already have a
substantial README.md but no AGENTS.md — agent tooling auto-loads
AGENTS.md when working in a directory but not README.md, so those
conventions were otherwise invisible to an agent that didn't think to
look.
---
 include/xrpl/consensus/AGENTS.md     | 3 +++
 include/xrpl/consensus/CLAUDE.md     | 1 +
 include/xrpl/nodestore/AGENTS.md     | 3 +++
 include/xrpl/nodestore/CLAUDE.md     | 1 +
 include/xrpl/shamap/AGENTS.md        | 3 +++
 include/xrpl/shamap/CLAUDE.md        | 1 +
 src/libxrpl/ledger/helpers/AGENTS.md | 5 +++++
 src/libxrpl/ledger/helpers/CLAUDE.md | 1 +
 src/libxrpl/tx/transactors/AGENTS.md | 7 +++++++
 src/libxrpl/tx/transactors/CLAUDE.md | 1 +
 src/xrpld/app/consensus/AGENTS.md    | 3 +++
 src/xrpld/app/consensus/CLAUDE.md    | 1 +
 src/xrpld/app/ledger/AGENTS.md       | 3 +++
 src/xrpld/app/ledger/CLAUDE.md       | 1 +
 src/xrpld/overlay/AGENTS.md          | 3 +++
 src/xrpld/overlay/CLAUDE.md          | 1 +
 src/xrpld/peerfinder/AGENTS.md       | 3 +++
 src/xrpld/peerfinder/CLAUDE.md       | 1 +
 src/xrpld/rpc/AGENTS.md              | 2 +-
 19 files changed, 43 insertions(+), 1 deletion(-)
 create mode 100644 include/xrpl/consensus/AGENTS.md
 create mode 120000 include/xrpl/consensus/CLAUDE.md
 create mode 100644 include/xrpl/nodestore/AGENTS.md
 create mode 120000 include/xrpl/nodestore/CLAUDE.md
 create mode 100644 include/xrpl/shamap/AGENTS.md
 create mode 120000 include/xrpl/shamap/CLAUDE.md
 create mode 100644 src/libxrpl/ledger/helpers/AGENTS.md
 create mode 120000 src/libxrpl/ledger/helpers/CLAUDE.md
 create mode 100644 src/libxrpl/tx/transactors/AGENTS.md
 create mode 120000 src/libxrpl/tx/transactors/CLAUDE.md
 create mode 100644 src/xrpld/app/consensus/AGENTS.md
 create mode 120000 src/xrpld/app/consensus/CLAUDE.md
 create mode 100644 src/xrpld/app/ledger/AGENTS.md
 create mode 120000 src/xrpld/app/ledger/CLAUDE.md
 create mode 100644 src/xrpld/overlay/AGENTS.md
 create mode 120000 src/xrpld/overlay/CLAUDE.md
 create mode 100644 src/xrpld/peerfinder/AGENTS.md
 create mode 120000 src/xrpld/peerfinder/CLAUDE.md

diff --git a/include/xrpl/consensus/AGENTS.md b/include/xrpl/consensus/AGENTS.md
new file mode 100644
index 00000000000..bd7f082b184
--- /dev/null
+++ b/include/xrpl/consensus/AGENTS.md
@@ -0,0 +1,3 @@
+# AGENTS.md — consensus
+
+See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance. See [README.md](./README.md) for a short pointer, and [docs/consensus.md](../../../docs/consensus.md) for the full consensus design.
diff --git a/include/xrpl/consensus/CLAUDE.md b/include/xrpl/consensus/CLAUDE.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/include/xrpl/consensus/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/include/xrpl/nodestore/AGENTS.md b/include/xrpl/nodestore/AGENTS.md
new file mode 100644
index 00000000000..61e3818c345
--- /dev/null
+++ b/include/xrpl/nodestore/AGENTS.md
@@ -0,0 +1,3 @@
+# AGENTS.md — nodestore
+
+See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for backend and benchmark design.
diff --git a/include/xrpl/nodestore/CLAUDE.md b/include/xrpl/nodestore/CLAUDE.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/include/xrpl/nodestore/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/include/xrpl/shamap/AGENTS.md b/include/xrpl/shamap/AGENTS.md
new file mode 100644
index 00000000000..2acbb84fc16
--- /dev/null
+++ b/include/xrpl/shamap/AGENTS.md
@@ -0,0 +1,3 @@
+# AGENTS.md — shamap
+
+See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for the SHAMap design.
diff --git a/include/xrpl/shamap/CLAUDE.md b/include/xrpl/shamap/CLAUDE.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/include/xrpl/shamap/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/libxrpl/ledger/helpers/AGENTS.md b/src/libxrpl/ledger/helpers/AGENTS.md
new file mode 100644
index 00000000000..decdcd22aed
--- /dev/null
+++ b/src/libxrpl/ledger/helpers/AGENTS.md
@@ -0,0 +1,5 @@
+# AGENTS.md — ledger/helpers
+
+See the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance.
+
+A helper that takes an `SLE`/`std::shared_ptr<SLE const>` should `XRPL_ASSERT` that it's non-null and of the expected ledger-entry type at entry, and keep a real runtime check/error-return alongside the assert (asserts compile out in release builds). Don't invent a new error-handling idiom for this (e.g. `std::unexpected`) — return the existing `tec`/`ter`/`tef` code used elsewhere in the codebase.
diff --git a/src/libxrpl/ledger/helpers/CLAUDE.md b/src/libxrpl/ledger/helpers/CLAUDE.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/src/libxrpl/ledger/helpers/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/libxrpl/tx/transactors/AGENTS.md b/src/libxrpl/tx/transactors/AGENTS.md
new file mode 100644
index 00000000000..82d92a3f10c
--- /dev/null
+++ b/src/libxrpl/tx/transactors/AGENTS.md
@@ -0,0 +1,7 @@
+# AGENTS.md — transactors
+
+See [tx/AGENTS.md](../AGENTS.md) for amendment-gating conventions that apply to all transactors, and the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance.
+
+Pseudo-accounts (Vault, LoanBroker, AMM, ...) are exempt from `requireAuth` and freeze/deep-freeze checks as a class, not on a per-asset-type basis. Code that touches a pseudo-account (deposits, withdrawals, clawback, deletion, credential checks) must preserve that exemption rather than re-deriving it for each asset type.
+
+Prefer a single object-level invariant over duplicating the same delta/balance check in every transactor that touches an object — e.g. one invariant asserting a Vault's pseudo-account balance and `assetsAvailable` always move together, rather than repeating that check in `VaultDeposit`, `VaultWithdraw`, `VaultClawback`, `LoanSet`, etc.
diff --git a/src/libxrpl/tx/transactors/CLAUDE.md b/src/libxrpl/tx/transactors/CLAUDE.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/src/libxrpl/tx/transactors/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/xrpld/app/consensus/AGENTS.md b/src/xrpld/app/consensus/AGENTS.md
new file mode 100644
index 00000000000..98e7de4f677
--- /dev/null
+++ b/src/xrpld/app/consensus/AGENTS.md
@@ -0,0 +1,3 @@
+# AGENTS.md — consensus
+
+See the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance. See [README.md](./README.md) for a short pointer, and [docs/consensus.md](../../../../docs/consensus.md) for the full consensus design.
diff --git a/src/xrpld/app/consensus/CLAUDE.md b/src/xrpld/app/consensus/CLAUDE.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/src/xrpld/app/consensus/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/xrpld/app/ledger/AGENTS.md b/src/xrpld/app/ledger/AGENTS.md
new file mode 100644
index 00000000000..89d7e465730
--- /dev/null
+++ b/src/xrpld/app/ledger/AGENTS.md
@@ -0,0 +1,3 @@
+# AGENTS.md — ledger
+
+See the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance and [README.md](./README.md) for ledger lifecycle and fetch-pack design.
diff --git a/src/xrpld/app/ledger/CLAUDE.md b/src/xrpld/app/ledger/CLAUDE.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/src/xrpld/app/ledger/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/xrpld/overlay/AGENTS.md b/src/xrpld/overlay/AGENTS.md
new file mode 100644
index 00000000000..65df22cf863
--- /dev/null
+++ b/src/xrpld/overlay/AGENTS.md
@@ -0,0 +1,3 @@
+# AGENTS.md — overlay
+
+See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for the peer-protocol handshake, clustering, gossip, and monitoring design.
diff --git a/src/xrpld/overlay/CLAUDE.md b/src/xrpld/overlay/CLAUDE.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/src/xrpld/overlay/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/xrpld/peerfinder/AGENTS.md b/src/xrpld/peerfinder/AGENTS.md
new file mode 100644
index 00000000000..f7c5d443b0c
--- /dev/null
+++ b/src/xrpld/peerfinder/AGENTS.md
@@ -0,0 +1,3 @@
+# AGENTS.md — peerfinder
+
+See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for the peer-discovery design.
diff --git a/src/xrpld/peerfinder/CLAUDE.md b/src/xrpld/peerfinder/CLAUDE.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/src/xrpld/peerfinder/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/xrpld/rpc/AGENTS.md b/src/xrpld/rpc/AGENTS.md
index 1dc26800d51..01354ad2b6a 100644
--- a/src/xrpld/rpc/AGENTS.md
+++ b/src/xrpld/rpc/AGENTS.md
@@ -1,5 +1,5 @@
 # AGENTS.md — rpc
 
-See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance, including the [API Changelog](../../../AGENTS.md#api-changelog) rule.
+See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance, including the [API Changelog](../../../AGENTS.md#api-changelog) rule, and [README.md](./README.md) for the RPC subsystem design.
 
 A change to a public RPC method's behavior (new/changed/removed fields, parameters, or error conditions) is exactly the kind of API-visible change that rule covers — use `### Additions`, `### Deprecations`, etc. under `## Unreleased` as appropriate.

From 7c642cdf9e2755cf89b8b8e4009ee7378f8c2335 Mon Sep 17 00:00:00 2001
From: Mayukha Vadari <mvadari@gmail.com>
Date: Wed, 9 Sep 2026 13:38:42 -0400
Subject: [PATCH 3/6] docs: Scope AGENTS.md content to the smallest applicable
 folder

Team decided AGENTS.md content should live in the narrowest folder it
applies to, rather than the broadest, to keep context small for agents
working elsewhere in the repo. Restructure round 1/2's additions
accordingly, with no change in the rules themselves:

- Move the repo-wide API-CHANGELOG.md rule out of root AGENTS.md and
  into rpc/AGENTS.md (its natural home), with a one-line pointer left
  in tx/AGENTS.md for the signing-behavior case.
- Move the amendment-gating *code style* rules (single enabled/disabled
  block, per-amendment flag naming, UNREACHABLE/LCOV_EXCL pairing) from
  tx/AGENTS.md down into transactors/AGENTS.md, since all cited PR
  evidence was in transactor code, not tx/-level files.
- Move the "shared test setup belongs in jtx/" rule out of root
  AGENTS.md into a new src/test/AGENTS.md (+ CLAUDE.md symlink).
- Trim the now-duplicated amendment sentence out of root's Architecture
  bullet in favor of a pointer to tx/AGENTS.md.
---
 AGENTS.md                            | 9 ++-------
 src/libxrpl/tx/AGENTS.md             | 8 ++------
 src/libxrpl/tx/transactors/AGENTS.md | 8 ++++++++
 src/test/AGENTS.md                   | 5 +++++
 src/test/CLAUDE.md                   | 1 +
 src/xrpld/rpc/AGENTS.md              | 4 ++--
 6 files changed, 20 insertions(+), 15 deletions(-)
 create mode 100644 src/test/AGENTS.md
 create mode 120000 src/test/CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
index f7748a4600f..fa88b7ccd08 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,8 +21,7 @@ Unit tests are a custom framework built into the `xrpld` binary itself (not Boos
 - A suite's `--unittest` name is built from the arguments to its `BEAST_DEFINE_TESTSUITE`/`BEAST_DEFINE_TESTSUITE_PRIO` macro (usually at the bottom of the test file), in reverse order and joined with `.`: `BEAST_DEFINE_TESTSUITE(Credentials, app, xrpl)` → `xrpl.app.Credentials`.
 - `--unittest-arg` does nothing — don't use it.
 - Tests that run offline in under a minute should be automatic `--unittest` suites; anything else is a manual/integration test.
-- New tests should be written using `gtest` under `src/tests/` unless that isn't possible, in which case fall back to the legacy Beast framework under `src/test/`. `tests/` (top-level) holds integration tests exercised against `libxrpl`/`xrpld`.
-- Shared test setup/helper code used by more than one test file belongs in `jtx/` (`src/test/jtx/`), not copy-pasted across test files.
+- New tests should be written using `gtest` under `src/tests/` unless that isn't possible, in which case fall back to the legacy Beast framework under `src/test/` (see [src/test/AGENTS.md](./src/test/AGENTS.md) for conventions specific to that directory). `tests/` (top-level) holds integration tests exercised against `libxrpl`/`xrpld`.
 
 ## Lint/Format
 
@@ -32,15 +31,11 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md#pre-commit-hooks) for `pre-commit` setup
 
 New file placement and header levelization: see [CONTRIBUTING.md](./CONTRIBUTING.md#before-making-a-pull-request). Braces, whitespace, member order, and other conventions: see [docs/CodingStyle.md](./docs/CodingStyle.md). `XRPL_ASSERT`/`UNREACHABLE` contracts: see [CONTRIBUTING.md](./CONTRIBUTING.md#contracts-and-instrumentation). Commit messages: see [CONTRIBUTING.md](./CONTRIBUTING.md#good-commit-messages). New public functions/methods need a Doxygen-style comment.
 
-## API Changelog
-
-Any change to publicly-visible API behavior — RPC/WebSocket fields, parameters, or error conditions, or transaction/signing behavior surfaced through the API — needs an entry in [API-CHANGELOG.md](./API-CHANGELOG.md) under `## Unreleased`, regardless of which directory the change lives in.
-
 ## Architecture
 
 Paths below reflect the current layout; update this section if modularization moves a subsystem to a different directory.
 
-- `include/xrpl/` + `src/libxrpl/` — the core protocol library: ledger, shamap, consensus, crypto, json, resource, nodestore, rdb, peerfinder, and `tx/` (transaction application: `Transactor.cpp`, `applySteps.cpp`, invariants, payment paths). `tx/transactors/` has one file per transaction type, grouped by subsystem: `escrow/`, `vault/`, `lending/`, `sponsor/`, `nft/`, `token/` (MPT), `payment_channel/`, `permissioned_domain/`, `dex/`, `oracle/`, `did/`, `credentials/`, `bridge/`, `check/`, `delegate/`, `account/`, `system/`. Any change to transaction-processing behavior must be gated behind an Amendment.
+- `include/xrpl/` + `src/libxrpl/` — the core protocol library: ledger, shamap, consensus, crypto, json, resource, nodestore, rdb, peerfinder, and `tx/` (transaction application: `Transactor.cpp`, `applySteps.cpp`, invariants, payment paths — see [src/libxrpl/tx/AGENTS.md](./src/libxrpl/tx/AGENTS.md) for amendment-gating conventions). `tx/transactors/` has one file per transaction type, grouped by subsystem: `escrow/`, `vault/`, `lending/`, `sponsor/`, `nft/`, `token/` (MPT), `payment_channel/`, `permissioned_domain/`, `dex/`, `oracle/`, `did/`, `credentials/`, `bridge/`, `check/`, `delegate/`, `account/`, `system/`.
 - `src/xrpld/` — the server application built on top of `libxrpl`: `app`, `core`, `overlay` (P2P networking), `peerfinder`, `perflog`, `rpc`, `shamap`. `main` builds an `ApplicationImp` implementing `Application`; most components hold a reference to it (`app_`), giving broad cross-component access — expect to trace call chains through `Application&`.
 - `src/test/` — unit tests mirroring the subsystems above, plus `jtx/` (the transaction-building test DSL — e.g. `jtx/escrow.h`, `jtx/vault.h`, `jtx/sponsor.h`, `jtx/permissioned_dex.h`) and `unit_test/` (the custom test framework itself, derived from Beast).
 - `src/tests/` — unit tests for `libxrpl` written in `gtest`, gradually replacing the `src/test` equivalents.
diff --git a/src/libxrpl/tx/AGENTS.md b/src/libxrpl/tx/AGENTS.md
index de27c59d483..b3a55734c63 100644
--- a/src/libxrpl/tx/AGENTS.md
+++ b/src/libxrpl/tx/AGENTS.md
@@ -12,10 +12,6 @@ When adding a new amendment or transaction type, check its interaction with: inv
 
 New (or deleted) invariant checks must be amendment-gated: they introduce (or remove) a way for a transaction to fail, and an un-gated change risks validators disagreeing on a transaction's result, i.e. a network fork.
 
-## Gating amendment-dependent code
+See [transactors/AGENTS.md](./transactors/AGENTS.md) for conventions on writing the amendment-gated code itself.
 
-Prefer a single amendment-enabled block and a single disabled block over scattering `rules.enabled(...)` checks through a function, even if the two blocks are similar.
-
-When a file or function checks more than one amendment, name local enablement booleans per-amendment (e.g. `fix340Enabled` for `fixCleanup3_4_0`), not a generic `fixEnabled` — it becomes ambiguous once a second amendment is checked in the same scope.
-
-Only use `UNREACHABLE` for genuinely impossible paths, not to avoid writing a test for one that's reachable but rare. When a branch marked `UNREACHABLE` is excluded from coverage, wrap it in `LCOV_EXCL_START`/`LCOV_EXCL_STOP`.
+A change to transaction/signing behavior that's visible through the public API also needs an `API-CHANGELOG.md` entry — see [../../xrpld/rpc/AGENTS.md](../../xrpld/rpc/AGENTS.md) for the full rule.
diff --git a/src/libxrpl/tx/transactors/AGENTS.md b/src/libxrpl/tx/transactors/AGENTS.md
index 82d92a3f10c..9dbdc052c8c 100644
--- a/src/libxrpl/tx/transactors/AGENTS.md
+++ b/src/libxrpl/tx/transactors/AGENTS.md
@@ -5,3 +5,11 @@ See [tx/AGENTS.md](../AGENTS.md) for amendment-gating conventions that apply to
 Pseudo-accounts (Vault, LoanBroker, AMM, ...) are exempt from `requireAuth` and freeze/deep-freeze checks as a class, not on a per-asset-type basis. Code that touches a pseudo-account (deposits, withdrawals, clawback, deletion, credential checks) must preserve that exemption rather than re-deriving it for each asset type.
 
 Prefer a single object-level invariant over duplicating the same delta/balance check in every transactor that touches an object — e.g. one invariant asserting a Vault's pseudo-account balance and `assetsAvailable` always move together, rather than repeating that check in `VaultDeposit`, `VaultWithdraw`, `VaultClawback`, `LoanSet`, etc.
+
+## Gating amendment-dependent code
+
+Prefer a single amendment-enabled block and a single disabled block over scattering `rules.enabled(...)` checks through a function, even if the two blocks are similar.
+
+When a file or function checks more than one amendment, name local enablement booleans per-amendment (e.g. `fix340Enabled` for `fixCleanup3_4_0`), not a generic `fixEnabled` — it becomes ambiguous once a second amendment is checked in the same scope.
+
+Only use `UNREACHABLE` for genuinely impossible paths, not to avoid writing a test for one that's reachable but rare. When a branch marked `UNREACHABLE` is excluded from coverage, wrap it in `LCOV_EXCL_START`/`LCOV_EXCL_STOP`.
diff --git a/src/test/AGENTS.md b/src/test/AGENTS.md
new file mode 100644
index 00000000000..2aae286fc09
--- /dev/null
+++ b/src/test/AGENTS.md
@@ -0,0 +1,5 @@
+# AGENTS.md — test
+
+See the repo-level [AGENTS.md](../../AGENTS.md) for general build/test/style guidance, and [README.md](./README.md) for basic `--unittest` invocation.
+
+Shared test setup/helper code used by more than one test file belongs in `jtx/`, not copy-pasted across test files.
diff --git a/src/test/CLAUDE.md b/src/test/CLAUDE.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/src/test/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/xrpld/rpc/AGENTS.md b/src/xrpld/rpc/AGENTS.md
index 01354ad2b6a..177faffafaf 100644
--- a/src/xrpld/rpc/AGENTS.md
+++ b/src/xrpld/rpc/AGENTS.md
@@ -1,5 +1,5 @@
 # AGENTS.md — rpc
 
-See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance, including the [API Changelog](../../../AGENTS.md#api-changelog) rule, and [README.md](./README.md) for the RPC subsystem design.
+See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance, and [README.md](./README.md) for the RPC subsystem design.
 
-A change to a public RPC method's behavior (new/changed/removed fields, parameters, or error conditions) is exactly the kind of API-visible change that rule covers — use `### Additions`, `### Deprecations`, etc. under `## Unreleased` as appropriate.
+Any change to publicly-visible API behavior — RPC/WebSocket fields, parameters, or error conditions, or transaction/signing behavior surfaced through the API even from outside this directory — needs an entry in [`API-CHANGELOG.md`](../../../API-CHANGELOG.md) under `## Unreleased` (`### Additions`, `### Deprecations`, etc. as appropriate).

From 6b9db2460c91c27009c75d5ad379e288f1b6d62c Mon Sep 17 00:00:00 2001
From: Mayukha Vadari <mvadari@gmail.com>
Date: Wed, 9 Sep 2026 13:46:51 -0400
Subject: [PATCH 4/6] docs: Loosen Nix mandate, extract ARCHITECTURE.md, add
 docs-upkeep note
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Build section now recommends the Nix devshell rather than requiring
  it; contributors can use their own toolchain/build flow.
- Move the directory-by-directory architecture map out of AGENTS.md
  into a new top-level ARCHITECTURE.md, with a pointer left behind.
- Add a short note asking contributors to keep AGENTS.md/README/
  ARCHITECTURE.md files current when they change what those docs cover.
- ledger/helpers/AGENTS.md also needs the amendment-gating shape,
  per-amendment flag naming, and UNREACHABLE/LCOV_EXCL pairing notes
  (previously only in transactors/AGENTS.md) — the vault/lending
  helper files these were evidenced on live in ledger/helpers/, not
  tx/transactors/.
---
 AGENTS.md                            | 14 ++++++--------
 ARCHITECTURE.md                      |  9 +++++++++
 src/libxrpl/ledger/helpers/AGENTS.md |  4 ++++
 3 files changed, 19 insertions(+), 8 deletions(-)
 create mode 100644 ARCHITECTURE.md

diff --git a/AGENTS.md b/AGENTS.md
index fa88b7ccd08..789a3110016 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,13 +4,13 @@ This file provides guidance to AI coding agents (Claude Code, and other AGENTS.m
 
 ## Build
 
-Required on Linux/macOS: use the Nix devshell, which sets up the compiler, Conan, ccache, and (optionally) Rust automatically.
+Recommended on Linux/macOS: the Nix devshell sets up the compiler, Conan, ccache, and (optionally) Rust automatically.
 
 ```bash
 nix develop
 ```
 
-For alternate devshell variants (specific compiler, no-compiler, coverage), see [docs/build/nix.md](./docs/build/nix.md). For the manual build steps, CMake options, and protocol codegen commands, see [BUILD.md](./BUILD.md) (`## Steps`, `## Options`, `## Code generation`).
+Not required — contributors can use their own toolchain/build flow instead. For alternate devshell variants (specific compiler, no-compiler, coverage), see [docs/build/nix.md](./docs/build/nix.md). For manual (non-Nix) build steps, CMake options, and protocol codegen commands, see [BUILD.md](./BUILD.md) (`## Steps`, `## Options`, `## Code generation`).
 
 Rust crate tests (independent of the CMake build): `cargo test --manifest-path crates/Cargo.toml --workspace` (CI uses `cargo nextest`).
 
@@ -33,10 +33,8 @@ New file placement and header levelization: see [CONTRIBUTING.md](./CONTRIBUTING
 
 ## Architecture
 
-Paths below reflect the current layout; update this section if modularization moves a subsystem to a different directory.
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the directory-by-directory map of the codebase.
 
-- `include/xrpl/` + `src/libxrpl/` — the core protocol library: ledger, shamap, consensus, crypto, json, resource, nodestore, rdb, peerfinder, and `tx/` (transaction application: `Transactor.cpp`, `applySteps.cpp`, invariants, payment paths — see [src/libxrpl/tx/AGENTS.md](./src/libxrpl/tx/AGENTS.md) for amendment-gating conventions). `tx/transactors/` has one file per transaction type, grouped by subsystem: `escrow/`, `vault/`, `lending/`, `sponsor/`, `nft/`, `token/` (MPT), `payment_channel/`, `permissioned_domain/`, `dex/`, `oracle/`, `did/`, `credentials/`, `bridge/`, `check/`, `delegate/`, `account/`, `system/`.
-- `src/xrpld/` — the server application built on top of `libxrpl`: `app`, `core`, `overlay` (P2P networking), `peerfinder`, `perflog`, `rpc`, `shamap`. `main` builds an `ApplicationImp` implementing `Application`; most components hold a reference to it (`app_`), giving broad cross-component access — expect to trace call chains through `Application&`.
-- `src/test/` — unit tests mirroring the subsystems above, plus `jtx/` (the transaction-building test DSL — e.g. `jtx/escrow.h`, `jtx/vault.h`, `jtx/sponsor.h`, `jtx/permissioned_dex.h`) and `unit_test/` (the custom test framework itself, derived from Beast).
-- `src/tests/` — unit tests for `libxrpl` written in `gtest`, gradually replacing the `src/test` equivalents.
-- `crates/` — a Rust workspace (only built with `-Dxrpld -Drust=ON`) bridged into C++ via `cxxbridge`/the `cxx` crate; currently just a `hello_world` interop scaffold. Requires the Rust toolchain pinned in `rust-toolchain.toml` (the Nix devshell provides it automatically).
+## Keeping docs current
+
+When you add or change a convention, or touch a subsystem that has its own `AGENTS.md`, `README.md`, or `ARCHITECTURE.md`, update that documentation in the same change rather than leaving it stale.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 00000000000..c2e1d22c3bd
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,9 @@
+# Architecture
+
+Paths below reflect the current layout; update this doc if modularization moves a subsystem to a different directory.
+
+- `include/xrpl/` + `src/libxrpl/` — the core protocol library: ledger, shamap, consensus, crypto, json, resource, nodestore, rdb, peerfinder, and `tx/` (transaction application: `Transactor.cpp`, `applySteps.cpp`, invariants, payment paths — see [src/libxrpl/tx/AGENTS.md](./src/libxrpl/tx/AGENTS.md) for amendment-gating conventions). `tx/transactors/` has one file per transaction type, grouped by subsystem: `escrow/`, `vault/`, `lending/`, `sponsor/`, `nft/`, `token/` (MPT), `payment_channel/`, `permissioned_domain/`, `dex/`, `oracle/`, `did/`, `credentials/`, `bridge/`, `check/`, `delegate/`, `account/`, `system/`.
+- `src/xrpld/` — the server application built on top of `libxrpl`: `app`, `core`, `overlay` (P2P networking), `peerfinder`, `perflog`, `rpc`, `shamap`. `main` builds an `ApplicationImp` implementing `Application`; most components hold a reference to it (`app_`), giving broad cross-component access — expect to trace call chains through `Application&`.
+- `src/test/` — unit tests mirroring the subsystems above, plus `jtx/` (the transaction-building test DSL — e.g. `jtx/escrow.h`, `jtx/vault.h`, `jtx/sponsor.h`, `jtx/permissioned_dex.h`) and `unit_test/` (the custom test framework itself, derived from Beast).
+- `src/tests/` — unit tests for `libxrpl` written in `gtest`, gradually replacing the `src/test` equivalents.
+- `crates/` — a Rust workspace (only built with `-Dxrpld -Drust=ON`) bridged into C++ via `cxxbridge`/the `cxx` crate; currently just a `hello_world` interop scaffold. Requires the Rust toolchain pinned in `rust-toolchain.toml` (the Nix devshell provides it automatically).
diff --git a/src/libxrpl/ledger/helpers/AGENTS.md b/src/libxrpl/ledger/helpers/AGENTS.md
index decdcd22aed..615e24451bd 100644
--- a/src/libxrpl/ledger/helpers/AGENTS.md
+++ b/src/libxrpl/ledger/helpers/AGENTS.md
@@ -3,3 +3,7 @@
 See the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance.
 
 A helper that takes an `SLE`/`std::shared_ptr<SLE const>` should `XRPL_ASSERT` that it's non-null and of the expected ledger-entry type at entry, and keep a real runtime check/error-return alongside the assert (asserts compile out in release builds). Don't invent a new error-handling idiom for this (e.g. `std::unexpected`) — return the existing `tec`/`ter`/`tef` code used elsewhere in the codebase.
+
+Prefer a single amendment-enabled block and a single disabled block over scattering `rules.enabled(...)` checks through a function, even if the two blocks are similar. When a file or function checks more than one amendment, name local enablement booleans per-amendment (e.g. `fix340Enabled` for `fixCleanup3_4_0`), not a generic `fixEnabled`.
+
+Only use `UNREACHABLE` for genuinely impossible paths, not to avoid writing a test for one that's reachable but rare. When a branch marked `UNREACHABLE` is excluded from coverage, wrap it in `LCOV_EXCL_START`/`LCOV_EXCL_STOP`.

From 6dc958c136dd17ce960e0abb55a252e34e19d7ea Mon Sep 17 00:00:00 2001
From: Mayukha Vadari <mvadari@gmail.com>
Date: Wed, 9 Sep 2026 13:58:12 -0400
Subject: [PATCH 5/6] docs: Fix std::unexpected wording, split UNREACHABLE out
 of amendment section
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ledger/helpers/AGENTS.md: std::expected<..., TER>/std::unexpected(tec*)
  is already the established idiom here (confirmed in AMMHelpers.cpp,
  CredentialHelpers.cpp), not something to avoid; reword so the rule
  doesn't read as discouraging it.
- transactors/AGENTS.md: the UNREACHABLE/LCOV_EXCL coverage rule isn't
  amendment-specific, so give it its own heading instead of nesting it
  under "Gating amendment-dependent code".
- Root AGENTS.md: comments should explain why, not what/how, since the
  code already shows that.
- Drop the pseudo-account exemption rule from transactors/AGENTS.md —
  needs refining before it's codified.

Addresses PR review comments:
https://github.com/XRPLF/rippled/pull/8198#discussion_r3962352164
https://github.com/XRPLF/rippled/pull/8198#discussion_r3967566278
---
 AGENTS.md                            | 2 ++
 src/libxrpl/ledger/helpers/AGENTS.md | 2 +-
 src/libxrpl/tx/transactors/AGENTS.md | 4 ++--
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 789a3110016..668381828c4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,6 +31,8 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md#pre-commit-hooks) for `pre-commit` setup
 
 New file placement and header levelization: see [CONTRIBUTING.md](./CONTRIBUTING.md#before-making-a-pull-request). Braces, whitespace, member order, and other conventions: see [docs/CodingStyle.md](./docs/CodingStyle.md). `XRPL_ASSERT`/`UNREACHABLE` contracts: see [CONTRIBUTING.md](./CONTRIBUTING.md#contracts-and-instrumentation). Commit messages: see [CONTRIBUTING.md](./CONTRIBUTING.md#good-commit-messages). New public functions/methods need a Doxygen-style comment.
 
+Comments should explain _why_, not _what_/_how_ — the code already shows that. Only describe what/how when the code itself would otherwise be confusing (a non-obvious workaround, a subtle invariant, a surprising constraint).
+
 ## Architecture
 
 See [ARCHITECTURE.md](./ARCHITECTURE.md) for the directory-by-directory map of the codebase.
diff --git a/src/libxrpl/ledger/helpers/AGENTS.md b/src/libxrpl/ledger/helpers/AGENTS.md
index 615e24451bd..03bb46f752c 100644
--- a/src/libxrpl/ledger/helpers/AGENTS.md
+++ b/src/libxrpl/ledger/helpers/AGENTS.md
@@ -2,7 +2,7 @@
 
 See the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance.
 
-A helper that takes an `SLE`/`std::shared_ptr<SLE const>` should `XRPL_ASSERT` that it's non-null and of the expected ledger-entry type at entry, and keep a real runtime check/error-return alongside the assert (asserts compile out in release builds). Don't invent a new error-handling idiom for this (e.g. `std::unexpected`) — return the existing `tec`/`ter`/`tef` code used elsewhere in the codebase.
+A helper that takes an `SLE`/`std::shared_ptr<SLE const>` should `XRPL_ASSERT` that it's non-null and of the expected ledger-entry type at entry, and keep a real runtime check/error-return alongside the assert (asserts compile out in release builds) — the established idiom in this directory is `std::expected<..., TER>`, returning `std::unexpected(tec*)` on failure. Don't invent a new error-handling idiom for this.
 
 Prefer a single amendment-enabled block and a single disabled block over scattering `rules.enabled(...)` checks through a function, even if the two blocks are similar. When a file or function checks more than one amendment, name local enablement booleans per-amendment (e.g. `fix340Enabled` for `fixCleanup3_4_0`), not a generic `fixEnabled`.
 
diff --git a/src/libxrpl/tx/transactors/AGENTS.md b/src/libxrpl/tx/transactors/AGENTS.md
index 9dbdc052c8c..02a253c8ea9 100644
--- a/src/libxrpl/tx/transactors/AGENTS.md
+++ b/src/libxrpl/tx/transactors/AGENTS.md
@@ -2,8 +2,6 @@
 
 See [tx/AGENTS.md](../AGENTS.md) for amendment-gating conventions that apply to all transactors, and the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance.
 
-Pseudo-accounts (Vault, LoanBroker, AMM, ...) are exempt from `requireAuth` and freeze/deep-freeze checks as a class, not on a per-asset-type basis. Code that touches a pseudo-account (deposits, withdrawals, clawback, deletion, credential checks) must preserve that exemption rather than re-deriving it for each asset type.
-
 Prefer a single object-level invariant over duplicating the same delta/balance check in every transactor that touches an object — e.g. one invariant asserting a Vault's pseudo-account balance and `assetsAvailable` always move together, rather than repeating that check in `VaultDeposit`, `VaultWithdraw`, `VaultClawback`, `LoanSet`, etc.
 
 ## Gating amendment-dependent code
@@ -12,4 +10,6 @@ Prefer a single amendment-enabled block and a single disabled block over scatter
 
 When a file or function checks more than one amendment, name local enablement booleans per-amendment (e.g. `fix340Enabled` for `fixCleanup3_4_0`), not a generic `fixEnabled` — it becomes ambiguous once a second amendment is checked in the same scope.
 
+## `UNREACHABLE` and test coverage
+
 Only use `UNREACHABLE` for genuinely impossible paths, not to avoid writing a test for one that's reachable but rare. When a branch marked `UNREACHABLE` is excluded from coverage, wrap it in `LCOV_EXCL_START`/`LCOV_EXCL_STOP`.

From ef55ca97c82783a4519f17c7276864f42ccd2e7d Mon Sep 17 00:00:00 2001
From: Mayukha Vadari <mvadari@gmail.com>
Date: Thu, 10 Sep 2026 11:18:15 -0400
Subject: [PATCH 6/6] docs: Drop redundant repo-level AGENTS.md pointers,
 shorten Build section
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- The harness auto-loads every ancestor AGENTS.md (including root), so
  a nested file telling an agent to "see the repo-level AGENTS.md" is
  pure overhead — it can trigger a re-load/duplication-check/discard
  cycle, and some models just retain the duplicate content in context.
  Drop that pointer from every nested AGENTS.md; keep pointers to
  things that are NOT auto-loaded (README.md, docs/consensus.md,
  non-ancestor AGENTS.md like tx/ -> rpc/).
- Root AGENTS.md's Build section is now a short index pointer to
  BUILD.md and docs/build/nix.md instead of restating Nix setup steps,
  per review feedback that AGENTS.md should mostly index other docs
  rather than duplicate them.

Addresses PR review comments:
https://github.com/XRPLF/rippled/pull/8198#discussion_r3979325914
https://github.com/XRPLF/rippled/pull/8198#discussion_r3979424992
---
 AGENTS.md                            | 8 +-------
 include/xrpl/consensus/AGENTS.md     | 2 +-
 include/xrpl/nodestore/AGENTS.md     | 2 +-
 include/xrpl/shamap/AGENTS.md        | 2 +-
 src/libxrpl/ledger/helpers/AGENTS.md | 2 --
 src/libxrpl/tx/AGENTS.md             | 2 --
 src/libxrpl/tx/transactors/AGENTS.md | 2 --
 src/test/AGENTS.md                   | 2 +-
 src/xrpld/app/consensus/AGENTS.md    | 2 +-
 src/xrpld/app/ledger/AGENTS.md       | 2 +-
 src/xrpld/overlay/AGENTS.md          | 2 +-
 src/xrpld/peerfinder/AGENTS.md       | 2 +-
 src/xrpld/rpc/AGENTS.md              | 2 +-
 13 files changed, 10 insertions(+), 22 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 668381828c4..0839fd01a29 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,13 +4,7 @@ This file provides guidance to AI coding agents (Claude Code, and other AGENTS.m
 
 ## Build
 
-Recommended on Linux/macOS: the Nix devshell sets up the compiler, Conan, ccache, and (optionally) Rust automatically.
-
-```bash
-nix develop
-```
-
-Not required — contributors can use their own toolchain/build flow instead. For alternate devshell variants (specific compiler, no-compiler, coverage), see [docs/build/nix.md](./docs/build/nix.md). For manual (non-Nix) build steps, CMake options, and protocol codegen commands, see [BUILD.md](./BUILD.md) (`## Steps`, `## Options`, `## Code generation`).
+For the build steps, CMake options, and protocol codegen commands, see [BUILD.md](./BUILD.md) (`## Steps`, `## Options`, `## Code generation`). Nix development shells are available in the repo (not required) — see [docs/build/nix.md](./docs/build/nix.md) for setup and variants.
 
 Rust crate tests (independent of the CMake build): `cargo test --manifest-path crates/Cargo.toml --workspace` (CI uses `cargo nextest`).
 
diff --git a/include/xrpl/consensus/AGENTS.md b/include/xrpl/consensus/AGENTS.md
index bd7f082b184..553c7953bc5 100644
--- a/include/xrpl/consensus/AGENTS.md
+++ b/include/xrpl/consensus/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — consensus
 
-See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance. See [README.md](./README.md) for a short pointer, and [docs/consensus.md](../../../docs/consensus.md) for the full consensus design.
+See [README.md](./README.md) for a short pointer, and [docs/consensus.md](../../../docs/consensus.md) for the full consensus design.
diff --git a/include/xrpl/nodestore/AGENTS.md b/include/xrpl/nodestore/AGENTS.md
index 61e3818c345..f941557f831 100644
--- a/include/xrpl/nodestore/AGENTS.md
+++ b/include/xrpl/nodestore/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — nodestore
 
-See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for backend and benchmark design.
+See [README.md](./README.md) for backend and benchmark design.
diff --git a/include/xrpl/shamap/AGENTS.md b/include/xrpl/shamap/AGENTS.md
index 2acbb84fc16..355032f3faf 100644
--- a/include/xrpl/shamap/AGENTS.md
+++ b/include/xrpl/shamap/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — shamap
 
-See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for the SHAMap design.
+See [README.md](./README.md) for the SHAMap design.
diff --git a/src/libxrpl/ledger/helpers/AGENTS.md b/src/libxrpl/ledger/helpers/AGENTS.md
index 03bb46f752c..951b0975566 100644
--- a/src/libxrpl/ledger/helpers/AGENTS.md
+++ b/src/libxrpl/ledger/helpers/AGENTS.md
@@ -1,7 +1,5 @@
 # AGENTS.md — ledger/helpers
 
-See the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance.
-
 A helper that takes an `SLE`/`std::shared_ptr<SLE const>` should `XRPL_ASSERT` that it's non-null and of the expected ledger-entry type at entry, and keep a real runtime check/error-return alongside the assert (asserts compile out in release builds) — the established idiom in this directory is `std::expected<..., TER>`, returning `std::unexpected(tec*)` on failure. Don't invent a new error-handling idiom for this.
 
 Prefer a single amendment-enabled block and a single disabled block over scattering `rules.enabled(...)` checks through a function, even if the two blocks are similar. When a file or function checks more than one amendment, name local enablement booleans per-amendment (e.g. `fix340Enabled` for `fixCleanup3_4_0`), not a generic `fixEnabled`.
diff --git a/src/libxrpl/tx/AGENTS.md b/src/libxrpl/tx/AGENTS.md
index b3a55734c63..b95d34b1a80 100644
--- a/src/libxrpl/tx/AGENTS.md
+++ b/src/libxrpl/tx/AGENTS.md
@@ -1,7 +1,5 @@
 # AGENTS.md — tx
 
-See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance.
-
 ## When an amendment is required
 
 A change needs an amendment if it affects transaction processing, ledger objects, or anything else about the binary format or hash of the ledger. An amendment is optional if a change only affects what transactions get proposed for consensus (e.g. fee escalation). Otherwise, don't use one.
diff --git a/src/libxrpl/tx/transactors/AGENTS.md b/src/libxrpl/tx/transactors/AGENTS.md
index 02a253c8ea9..75218aceb06 100644
--- a/src/libxrpl/tx/transactors/AGENTS.md
+++ b/src/libxrpl/tx/transactors/AGENTS.md
@@ -1,7 +1,5 @@
 # AGENTS.md — transactors
 
-See [tx/AGENTS.md](../AGENTS.md) for amendment-gating conventions that apply to all transactors, and the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance.
-
 Prefer a single object-level invariant over duplicating the same delta/balance check in every transactor that touches an object — e.g. one invariant asserting a Vault's pseudo-account balance and `assetsAvailable` always move together, rather than repeating that check in `VaultDeposit`, `VaultWithdraw`, `VaultClawback`, `LoanSet`, etc.
 
 ## Gating amendment-dependent code
diff --git a/src/test/AGENTS.md b/src/test/AGENTS.md
index 2aae286fc09..2743e428aa5 100644
--- a/src/test/AGENTS.md
+++ b/src/test/AGENTS.md
@@ -1,5 +1,5 @@
 # AGENTS.md — test
 
-See the repo-level [AGENTS.md](../../AGENTS.md) for general build/test/style guidance, and [README.md](./README.md) for basic `--unittest` invocation.
+See [README.md](./README.md) for basic `--unittest` invocation.
 
 Shared test setup/helper code used by more than one test file belongs in `jtx/`, not copy-pasted across test files.
diff --git a/src/xrpld/app/consensus/AGENTS.md b/src/xrpld/app/consensus/AGENTS.md
index 98e7de4f677..292de6b67a7 100644
--- a/src/xrpld/app/consensus/AGENTS.md
+++ b/src/xrpld/app/consensus/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — consensus
 
-See the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance. See [README.md](./README.md) for a short pointer, and [docs/consensus.md](../../../../docs/consensus.md) for the full consensus design.
+See [README.md](./README.md) for a short pointer, and [docs/consensus.md](../../../../docs/consensus.md) for the full consensus design.
diff --git a/src/xrpld/app/ledger/AGENTS.md b/src/xrpld/app/ledger/AGENTS.md
index 89d7e465730..7f9125f61f9 100644
--- a/src/xrpld/app/ledger/AGENTS.md
+++ b/src/xrpld/app/ledger/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — ledger
 
-See the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance and [README.md](./README.md) for ledger lifecycle and fetch-pack design.
+See [README.md](./README.md) for ledger lifecycle and fetch-pack design.
diff --git a/src/xrpld/overlay/AGENTS.md b/src/xrpld/overlay/AGENTS.md
index 65df22cf863..c4566819be8 100644
--- a/src/xrpld/overlay/AGENTS.md
+++ b/src/xrpld/overlay/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — overlay
 
-See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for the peer-protocol handshake, clustering, gossip, and monitoring design.
+See [README.md](./README.md) for the peer-protocol handshake, clustering, gossip, and monitoring design.
diff --git a/src/xrpld/peerfinder/AGENTS.md b/src/xrpld/peerfinder/AGENTS.md
index f7c5d443b0c..d53d8f1e775 100644
--- a/src/xrpld/peerfinder/AGENTS.md
+++ b/src/xrpld/peerfinder/AGENTS.md
@@ -1,3 +1,3 @@
 # AGENTS.md — peerfinder
 
-See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for the peer-discovery design.
+See [README.md](./README.md) for the peer-discovery design.
diff --git a/src/xrpld/rpc/AGENTS.md b/src/xrpld/rpc/AGENTS.md
index 177faffafaf..5934e5ed423 100644
--- a/src/xrpld/rpc/AGENTS.md
+++ b/src/xrpld/rpc/AGENTS.md
@@ -1,5 +1,5 @@
 # AGENTS.md — rpc
 
-See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance, and [README.md](./README.md) for the RPC subsystem design.
+See [README.md](./README.md) for the RPC subsystem design.
 
 Any change to publicly-visible API behavior — RPC/WebSocket fields, parameters, or error conditions, or transaction/signing behavior surfaced through the API even from outside this directory — needs an entry in [`API-CHANGELOG.md`](../../../API-CHANGELOG.md) under `## Unreleased` (`### Additions`, `### Deprecations`, etc. as appropriate).