diff --git a/include/bitbishop/attacks/attackers_to.hpp b/include/bitbishop/attacks/attackers_to.hpp
new file mode 100644
index 0000000..e69de29
diff --git a/include/bitbishop/attacks/bishop_attacks.hpp b/include/bitbishop/attacks/bishop_attacks.hpp
new file mode 100644
index 0000000..e69de29
diff --git a/include/bitbishop/attacks/queen_attacks.hpp b/include/bitbishop/attacks/queen_attacks.hpp
new file mode 100644
index 0000000..e69de29
diff --git a/include/bitbishop/attacks/readme.md b/include/bitbishop/attacks/readme.md
new file mode 100644
index 0000000..6a36fba
--- /dev/null
+++ b/include/bitbishop/attacks/readme.md
@@ -0,0 +1,34 @@
+# About the `attacks/` directory
+
+## The core rule
+
+Lookups = immutable, compile-time geometry
+
+Attacks = runtime logic that depends on board state
+
+## What exactly goes into `attacks/`
+
+### Definition
+
+attacks/ contains functions that:
+
+- consume lookup tables
+- take runtime state (occupied)
+- compute attack bitboards dynamically
+
+### Examples (good)
+
+```cpp
+// attacks/bishop_attacks.cpp
+Bitboard bishop_attacks(Square from, Bitboard occupied);
+
+// attacks/attackers_to.cpp
+Bitboard attackers_to(Square sq, const Board&, Color);
+```
+
+### Examples (bad — belongs elsewhere)
+
+```cpp
+constexpr Bitboard KING_ATTACKS[64]; // ❌ data only
+generate_legal_moves(...) // ❌ rules layer
+```
diff --git a/include/bitbishop/attacks/rook_attacks.hpp b/include/bitbishop/attacks/rook_attacks.hpp
new file mode 100644
index 0000000..e69de29
diff --git a/include/bitbishop/engine/readme.md b/include/bitbishop/engine/readme.md
new file mode 100644
index 0000000..4c26dbf
--- /dev/null
+++ b/include/bitbishop/engine/readme.md
@@ -0,0 +1,58 @@
+# About the `engine/` directory
+
+## The core rule
+
+Engine = decision making
+
+This layer decides which move to play, not which moves are legal.
+
+## What exactly goes into `engine/`
+
+### Definition
+
+engine/ contains logic that:
+
+- searches the game tree
+- evaluates positions
+- selects the best move
+
+This layer may:
+
+- call generate_legal_moves()
+- make/unmake moves on the Board
+- maintain search state
+
+This layer must not:
+
+- implement chess rules
+- generate attacks directly
+- contain UI or protocol code
+
+Typical responsibilities
+
+- search algorithms:
+- Minimax
+- Alpha-Beta
+- MCTS
+- evaluation functions
+- move ordering
+- transposition tables
+- time management (search side)
+
+### Examples (good)
+
+```cpp
+// engine/search.cpp
+Move search_best_move(Board&, SearchLimits);
+
+// engine/eval.cpp
+int evaluate(const Board&);
+```
+
+### Examples (bad — belongs elsewhere)
+
+```cpp
+void generate_legal_rook_moves(...); // ❌ movegen
+constexpr Bitboard ROOK_RAYS[64][4]; // ❌ lookups
+void uci_loop(); // ❌ interface
+```
diff --git a/include/bitbishop/interface/readme.md b/include/bitbishop/interface/readme.md
new file mode 100644
index 0000000..5772032
--- /dev/null
+++ b/include/bitbishop/interface/readme.md
@@ -0,0 +1,55 @@
+# About the `interface/` directory
+
+## The core rule
+
+Interface = communication with the outside world
+
+This layer translates between the engine and humans or GUIs.
+
+## What exactly goes into interface/
+
+### Definition
+
+interface/ contains logic that:
+
+- parses input commands
+- formats output
+- manages clocks and sessions
+- interacts with GUIs or users
+
+This layer may:
+
+- call engine entry points
+- read/write text or UI events
+
+This layer must not:
+
+- implement search logic
+- implement chess rules
+- manipulate bitboards directly
+
+Typical responsibilities
+
+- UCI / CECP protocol handling
+- GUI hooks
+- command parsing
+- time control management
+- logging
+
+### Examples (good)
+
+```cpp
+// interface/uci.cpp
+void uci_loop();
+
+// interface/cli.cpp
+void run_cli();
+```
+
+### Examples (bad — belongs elsewhere)
+
+```cpp
+Bitboard attackers_to(...); // ❌ attacks
+int alpha_beta(...); // ❌ engine
+generate_legal_moves(...); // ❌ movegen
+```
diff --git a/include/bitbishop/lookups/bishop.hpp b/include/bitbishop/lookups/bishop_rays.hpp
similarity index 100%
rename from include/bitbishop/lookups/bishop.hpp
rename to include/bitbishop/lookups/bishop_rays.hpp
diff --git a/include/bitbishop/lookups/king.hpp b/include/bitbishop/lookups/king_attacks.hpp
similarity index 100%
rename from include/bitbishop/lookups/king.hpp
rename to include/bitbishop/lookups/king_attacks.hpp
diff --git a/include/bitbishop/lookups/knight.hpp b/include/bitbishop/lookups/knight_attacks.hpp
similarity index 100%
rename from include/bitbishop/lookups/knight.hpp
rename to include/bitbishop/lookups/knight_attacks.hpp
diff --git a/include/bitbishop/lookups/pawn.hpp b/include/bitbishop/lookups/pawn_attacks.hpp
similarity index 100%
rename from include/bitbishop/lookups/pawn.hpp
rename to include/bitbishop/lookups/pawn_attacks.hpp
diff --git a/include/bitbishop/lookups/queen.hpp b/include/bitbishop/lookups/queen_rays.hpp
similarity index 93%
rename from include/bitbishop/lookups/queen.hpp
rename to include/bitbishop/lookups/queen_rays.hpp
index 736f9d1..1eec3a3 100644
--- a/include/bitbishop/lookups/queen.hpp
+++ b/include/bitbishop/lookups/queen_rays.hpp
@@ -3,8 +3,8 @@
 #include <bitbishop/bitboard.hpp>
 #include <bitbishop/bitmasks.hpp>
 #include <bitbishop/constants.hpp>
-#include <bitbishop/lookups/bishop.hpp>
-#include <bitbishop/lookups/rook.hpp>
+#include <bitbishop/lookups/bishop_rays.hpp>
+#include <bitbishop/lookups/rook_rays.hpp>
 #include <cstdint>
 
 // NOTE: These queen lookups are not used in moves generation code.
diff --git a/include/bitbishop/lookups/readme.md b/include/bitbishop/lookups/readme.md
new file mode 100644
index 0000000..568f0e3
--- /dev/null
+++ b/include/bitbishop/lookups/readme.md
@@ -0,0 +1,38 @@
+# About the `lookups/` directory
+
+## The core rule
+
+Lookups = immutable, compile-time geometry
+
+Attacks = runtime logic that depends on board state
+
+## What exactly goes into `lookups/`
+
+### Definition
+
+lookups/ contains only data:
+
+- constexpr
+- no branching on board state
+- no Board, no occupied
+- no game rules
+
+### Examples (good)
+
+```cpp
+// lookups/king_attacks.hpp
+constexpr Bitboard KING_ATTACKS[64];
+
+// lookups/rook_rays.hpp
+constexpr Bitboard ROOK_RAYS[64][4];
+
+// lookups/between_squares.hpp
+constexpr Bitboard BETWEEN[64][64];
+```
+
+### Examples (bad — belongs elsewhere)
+
+```cpp
+Bitboard bishop_attacks(Square, Bitboard); // ❌ logic
+if (occupied & mask) { ... } // ❌ runtime state
+```
diff --git a/include/bitbishop/lookups/rook.hpp b/include/bitbishop/lookups/rook_rays.hpp
similarity index 100%
rename from include/bitbishop/lookups/rook.hpp
rename to include/bitbishop/lookups/rook_rays.hpp
diff --git a/include/bitbishop/movegen/readme.md b/include/bitbishop/movegen/readme.md
new file mode 100644
index 0000000..6ae036c
--- /dev/null
+++ b/include/bitbishop/movegen/readme.md
@@ -0,0 +1,71 @@
+# About the `movegen/` directory
+
+## The core rule
+
+Movegen = chess rules + king safety
+
+This layer is responsible for generating only legal moves, by construction.
+
+It sits above raw attack computation and below search/evaluation.
+
+## What exactly goes into `movegen/`
+
+### Definition
+
+movegen/ contains logic that:
+
+- generates legal moves only
+- enforces check, pins, and king safety
+- understands chess rules
+- emits Move objects
+
+This layer may:
+
+- depend on Board
+- depend on attacks/ and lookups/
+- branch on runtime board state
+
+This layer must not:
+
+- contain search logic
+- contain evaluation logic
+- contain UI / protocol logic
+
+Typical responsibilities
+
+- generate_legal_moves()
+- per-piece legal move generation:
+- generate_legal_bishop_moves
+- generate_legal_rook_moves
+- …
+- check detection (checkers, check_mask)
+- pin detection (pinned, pin_ray)
+- special rules:
+- castling
+- en passant
+- promotions
+
+### Examples (good)
+
+```cpp
+// movegen/generate_legal_moves.cpp
+void generate_legal_moves(MoveList&, const Board&, Color);
+
+// movegen/bishop_moves.cpp
+void generate_legal_bishop_moves(
+    MoveList&,
+    const Board&,
+    Color,
+    Bitboard check_mask,
+    Bitboard pinned,
+    const Bitboard pin_ray[64]
+);
+```
+
+### Examples (bad — belongs elsewhere)
+
+```cpp
+int evaluate_position(const Board&); // ❌ engine
+Bitboard bishop_attacks(Square, Bitboard); // ❌ attacks
+constexpr Bitboard KING_ATTACKS[64]; // ❌ lookups
+```
diff --git a/include/bitbishop/moves/king_move_gen.hpp b/include/bitbishop/moves/king_move_gen.hpp
index 65d4e7e..cb2cab3 100644
--- a/include/bitbishop/moves/king_move_gen.hpp
+++ b/include/bitbishop/moves/king_move_gen.hpp
@@ -1,7 +1,7 @@
 #pragma once
 #include <bitbishop/board.hpp>
 #include <bitbishop/color.hpp>
-#include <bitbishop/lookups/king.hpp>
+#include <bitbishop/lookups/king_attacks.hpp>
 #include <bitbishop/move.hpp>
 #include <utility>
 #include <vector>
diff --git a/include/bitbishop/moves/pawn_move_gen.hpp b/include/bitbishop/moves/pawn_move_gen.hpp
index d13a783..7f370b9 100644
--- a/include/bitbishop/moves/pawn_move_gen.hpp
+++ b/include/bitbishop/moves/pawn_move_gen.hpp
@@ -2,7 +2,7 @@
 #include <bitbishop/board.hpp>
 #include <bitbishop/color.hpp>
 #include <bitbishop/constants.hpp>
-#include <bitbishop/lookups/pawn.hpp>
+#include <bitbishop/lookups/pawn_attacks.hpp>
 #include <bitbishop/move.hpp>
 #include <utility>
 #include <vector>
diff --git a/include/bitbishop/moves/readme.md b/include/bitbishop/moves/readme.md
new file mode 100644
index 0000000..53a659d
--- /dev/null
+++ b/include/bitbishop/moves/readme.md
@@ -0,0 +1,70 @@
+# About the `moves/` directory (legacy / deprecated)
+
+## Status
+
+⚠️ Legacy code — kept intentionally
+
+This directory contains an older pseudo-legal move generation system, followed by post-filtering for legality.
+
+It is no longer the primary move generation path, but is preserved for:
+
+- correctness reference
+- debugging
+- performance comparison
+- educational purposes
+
+## What this folder represents
+
+`moves/` implements the classic two-step approach: 1. Generate pseudo-legal moves 2. Filter out illegal moves by:
+
+- making the move
+- checking king safety
+- undoing the move
+
+This approach is simple and correct, but:
+
+- slower
+- harder to optimize
+- less suitable for high-performance engines
+
+## Why this folder still exists
+
+This code is intentionally kept because it:
+
+- is known to work
+- provides a correctness baseline
+- allows perft and move comparison against the new generator
+- is useful for profiling and regression testing
+
+The new optimized legal move generator lives in `movegen/`.
+
+## What exactly goes into `moves/`
+
+### Definition
+
+This folder contains logic that:
+
+- generates pseudo-legal moves per piece
+- filters moves via make/unmake
+- does not use pins or check masks
+- prioritizes simplicity over performance
+
+It may:
+
+- use Board
+- generate Move objects
+- temporarily allow illegal states
+
+It must not:
+
+- be used in the main engine search loop
+- be mixed with the optimized movegen
+- grow with new features
+
+## Migration note
+
+All new development related to move generation must go into:
+
+`movegen/`
+
+This folder is frozen unless a bug fix or reference improvement is required.
diff --git a/src/bitbishop/moves/bishop_move_gen.cpp b/src/bitbishop/moves/bishop_move_gen.cpp
index 4463150..62975fd 100644
--- a/src/bitbishop/moves/bishop_move_gen.cpp
+++ b/src/bitbishop/moves/bishop_move_gen.cpp
@@ -1,4 +1,4 @@
-#include <bitbishop/lookups/bishop.hpp>
+#include <bitbishop/lookups/bishop_rays.hpp>
 #include <bitbishop/moves/bishop_move_gen.hpp>
 #include <optional>
 
diff --git a/src/bitbishop/moves/king_move_gen.cpp b/src/bitbishop/moves/king_move_gen.cpp
index 9e2bea5..2fb6c3f 100644
--- a/src/bitbishop/moves/king_move_gen.cpp
+++ b/src/bitbishop/moves/king_move_gen.cpp
@@ -1,4 +1,4 @@
-#include <bitbishop/lookups/king.hpp>
+#include <bitbishop/lookups/king_attacks.hpp>
 #include <bitbishop/moves/king_move_gen.hpp>
 #include <format>
 #include <optional>
diff --git a/src/bitbishop/moves/knight_move_gen.cpp b/src/bitbishop/moves/knight_move_gen.cpp
index 81c0130..925a180 100644
--- a/src/bitbishop/moves/knight_move_gen.cpp
+++ b/src/bitbishop/moves/knight_move_gen.cpp
@@ -1,4 +1,4 @@
-#include <bitbishop/lookups/knight.hpp>
+#include <bitbishop/lookups/knight_attacks.hpp>
 #include <bitbishop/moves/knight_move_gen.hpp>
 
 void KnightMoveGenerator::generate_pseudo_legal_moves(std::vector<Move>& moves, const Board& board, Color side) {
diff --git a/src/bitbishop/moves/pawn_move_gen.cpp b/src/bitbishop/moves/pawn_move_gen.cpp
index 8efc66f..001a066 100644
--- a/src/bitbishop/moves/pawn_move_gen.cpp
+++ b/src/bitbishop/moves/pawn_move_gen.cpp
@@ -1,7 +1,7 @@
 #include <bitbishop/bitboard.hpp>
 #include <bitbishop/board.hpp>
 #include <bitbishop/color.hpp>
-#include <bitbishop/lookups/pawn.hpp>
+#include <bitbishop/lookups/pawn_attacks.hpp>
 #include <bitbishop/moves/pawn_move_gen.hpp>
 #include <optional>
 
diff --git a/src/bitbishop/moves/queen_move_gen.cpp b/src/bitbishop/moves/queen_move_gen.cpp
index 596d47f..8d82865 100644
--- a/src/bitbishop/moves/queen_move_gen.cpp
+++ b/src/bitbishop/moves/queen_move_gen.cpp
@@ -1,4 +1,4 @@
-#include <bitbishop/lookups/queen.hpp>
+#include <bitbishop/lookups/queen_rays.hpp>
 #include <bitbishop/moves/bishop_move_gen.hpp>
 #include <bitbishop/moves/queen_move_gen.hpp>
 #include <bitbishop/moves/rook_move_gen.hpp>
diff --git a/src/bitbishop/moves/rook_move_gen.cpp b/src/bitbishop/moves/rook_move_gen.cpp
index d72ebd1..abf3245 100644
--- a/src/bitbishop/moves/rook_move_gen.cpp
+++ b/src/bitbishop/moves/rook_move_gen.cpp
@@ -1,4 +1,4 @@
-#include <bitbishop/lookups/rook.hpp>
+#include <bitbishop/lookups/rook_rays.hpp>
 #include <bitbishop/moves/king_move_gen.hpp>
 #include <bitbishop/moves/rook_move_gen.hpp>
 
diff --git a/tests/bitbishop/lookups/test_attacks_bishop.cpp b/tests/bitbishop/lookups/test_attacks_bishop.cpp
index f0e6f59..c44fcd6 100644
--- a/tests/bitbishop/lookups/test_attacks_bishop.cpp
+++ b/tests/bitbishop/lookups/test_attacks_bishop.cpp
@@ -1,7 +1,7 @@
 #include <gtest/gtest.h>
 
 #include <bitbishop/bitboard.hpp>
-#include <bitbishop/lookups/bishop.hpp>
+#include <bitbishop/lookups/bishop_rays.hpp>
 #include <bitbishop/square.hpp>
 
 TEST(BishopAttacksTest, CornerA1) {
diff --git a/tests/bitbishop/lookups/test_attacks_king.cpp b/tests/bitbishop/lookups/test_attacks_king.cpp
index 57feea2..75032a5 100644
--- a/tests/bitbishop/lookups/test_attacks_king.cpp
+++ b/tests/bitbishop/lookups/test_attacks_king.cpp
@@ -2,7 +2,7 @@
 
 #include <bitbishop/bitboard.hpp>
 #include <bitbishop/bitmasks.hpp>
-#include <bitbishop/lookups/king.hpp>
+#include <bitbishop/lookups/king_attacks.hpp>
 #include <bitbishop/square.hpp>
 
 using namespace Lookups;
diff --git a/tests/bitbishop/lookups/test_attacks_knight.cpp b/tests/bitbishop/lookups/test_attacks_knight.cpp
index c83282c..713f4ae 100644
--- a/tests/bitbishop/lookups/test_attacks_knight.cpp
+++ b/tests/bitbishop/lookups/test_attacks_knight.cpp
@@ -2,7 +2,7 @@
 
 #include <bitbishop/bitboard.hpp>
 #include <bitbishop/bitmasks.hpp>
-#include <bitbishop/lookups/knight.hpp>
+#include <bitbishop/lookups/knight_attacks.hpp>
 #include <bitbishop/square.hpp>
 
 using namespace Lookups;
diff --git a/tests/bitbishop/lookups/test_attacks_pawns.cpp b/tests/bitbishop/lookups/test_attacks_pawns.cpp
index 8f97ac0..b301a1a 100644
--- a/tests/bitbishop/lookups/test_attacks_pawns.cpp
+++ b/tests/bitbishop/lookups/test_attacks_pawns.cpp
@@ -1,7 +1,7 @@
 #include <gtest/gtest.h>
 
 #include <bitbishop/bitboard.hpp>
-#include <bitbishop/lookups/pawn.hpp>
+#include <bitbishop/lookups/pawn_attacks.hpp>
 #include <bitbishop/square.hpp>
 
 using namespace Lookups;
diff --git a/tests/bitbishop/lookups/test_attacks_queen.cpp b/tests/bitbishop/lookups/test_attacks_queen.cpp
index 0e441a5..49f4144 100644
--- a/tests/bitbishop/lookups/test_attacks_queen.cpp
+++ b/tests/bitbishop/lookups/test_attacks_queen.cpp
@@ -1,7 +1,7 @@
 #include <gtest/gtest.h>
 
 #include <bitbishop/bitboard.hpp>
-#include <bitbishop/lookups/queen.hpp>
+#include <bitbishop/lookups/queen_rays.hpp>
 #include <bitbishop/square.hpp>
 
 TEST(QueenAttacksTest, CornerA1) {
diff --git a/tests/bitbishop/lookups/test_attacks_rook.cpp b/tests/bitbishop/lookups/test_attacks_rook.cpp
index 06f623f..1cca594 100644
--- a/tests/bitbishop/lookups/test_attacks_rook.cpp
+++ b/tests/bitbishop/lookups/test_attacks_rook.cpp
@@ -1,7 +1,7 @@
 #include <gtest/gtest.h>
 
 #include <bitbishop/bitboard.hpp>
-#include <bitbishop/lookups/rook.hpp>
+#include <bitbishop/lookups/rook_rays.hpp>
 #include <bitbishop/square.hpp>
 
 TEST(RookAttacksTest, CornerA1) {
diff --git a/tests/bitbishop/test_knight.cpp b/tests/bitbishop/test_knight.cpp
index c83282c..713f4ae 100644
--- a/tests/bitbishop/test_knight.cpp
+++ b/tests/bitbishop/test_knight.cpp
@@ -2,7 +2,7 @@
 
 #include <bitbishop/bitboard.hpp>
 #include <bitbishop/bitmasks.hpp>
-#include <bitbishop/lookups/knight.hpp>
+#include <bitbishop/lookups/knight_attacks.hpp>
 #include <bitbishop/square.hpp>
 
 using namespace Lookups;