diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6f8183433..8bff6030b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,14 +27,16 @@
 
 ## Adding New Subspecifications
 
-New subspecs belong in `src/lean_spec/subspecs/`. Follow the pattern of existing subspecs like `poseidon1`:
+Cryptographic subspecs live under `src/lean_spec/spec/crypto/`. Follow the pattern of an existing one like the `xmss` package:
 
 ```bash
-mkdir -p src/lean_spec/subspecs/my_new_subspec
-touch src/lean_spec/subspecs/my_new_subspec/__init__.py
-mkdir -p tests/subspecs/my_new_subspec
+mkdir -p src/lean_spec/spec/crypto/my_new_subspec
+touch src/lean_spec/spec/crypto/my_new_subspec/__init__.py
+mkdir -p tests/spec/crypto/my_new_subspec
 ```
 
+Tests mirror the source layout one-to-one (see `tests/spec/crypto/xmss/`).
+
 ## Testing
 
 - Write tests that mirror the source structure
diff --git a/README.md b/README.md
index 9e7a9e537..586fa8d7c 100644
--- a/README.md
+++ b/README.md
@@ -83,21 +83,18 @@ just test
 ```
 ├── src/
 │   └── lean_spec/                      # Main specifications
-│      ├── __init__.py
-│      └── subspecs/                       # Sub-specifications
-│          ├── poseidon1/
-│          │   ├── __init__.py
-│          │   ├── permutation.py
-│          │   └── constants.py
-│          ├── ...
-│          └── ...
+│       ├── cli/                        # Command-line entry points
+│       ├── node/                       # Node implementation (chain, networking, sync, validator, ...)
+│       └── spec/                       # Protocol specifications
+│           ├── crypto/                 # Cryptographic subspecs (poseidon, koalabear, xmss, ...)
+│           ├── forks/                  # Fork specifications (tested via consensus vectors)
+│           ├── ssz/                    # SSZ serialization
+│           └── observability/          # Observability spec
 ├── tests/                              # Test suite
-|   ├── consensus/                      # Tests for consensus
-|   |   └── devnet/                     # Tests for devnet
-|   |       ├── fc/                     # Tests for fork-choice
-|   |       └── state_transition/       # Tests for stf
-│   └── lean_spec/                      # Tests for main specs
-│       └── subspecs/                   # Tests for subspecs
+│   ├── consensus/                      # Consensus test vectors
+│   │   └── lstar/                      # e.g. fork_choice, state_transition, ssz, ...
+│   ├── spec/                           # Unit tests mirroring src/lean_spec/spec/
+│   └── node/                           # Unit tests mirroring src/lean_spec/node/
 ├── docs/                               # Documentation
 └── pyproject.toml                      # Project configuration
 ```