diff --git a/AGENTS.md b/AGENTS.md
index 4bbd95f..9533086 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,7 +6,8 @@
 
 ## Architecture
 - C-style C++ (structs/functions, NO classes/templates)
-- Raylib (git submodule) for 3D - chose over SFML (no 3D support)
+- Core library (`liborbit.a`) in `src/` — simulation, physics, maneuvers, config
+- Visualizer in `example/src/` — Raylib/raygui rendering (moved from core)
 - See docs/technical_reference.md for data structures reference
 - See docs/rendering.md for rendering system reference
 
@@ -42,7 +43,9 @@
 - Always ask the user if we want to update the technical_reference after generating a summary
 
 ## Common Commands
-- Build: make
+- Build all (lib + tests + visualizer): make
+- Build library only: make lib
+- Build visualizer example: make example
 - Test (build + run all): make test
 - Test (rebuild only): make test-build
 - Test (specific tag): ./build/orbit_test '[tag_name]'
@@ -51,7 +54,7 @@
 - See docs/technical_reference.md for full build target reference
 
 ## Simulation
-The simulation binary is built at `./build/orbit_sim`. Agents should NOT attempt to run the graphical simulation. Focus on testing and code changes only.
+The core simulation library is built at `build/liborbit.a`. The visualizer binary is at `./build/orbit_sim`. Agents should NOT attempt to run the graphical simulation. Focus on testing and code changes only.
 
 ## Testing Guidelines
 - Always use `WithinAbs()` for floating-point comparisons
diff --git a/README.md b/README.md
index a346d1e..517126b 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,8 @@ cd claudes_game
 git submodule update --init --recursive  # If already cloned without --recursive
 ```
 
+This initializes submodules in both `ext/` (tomlc17) and `example/ext/` (raylib, raygui).
+
 ### Dependencies (Debian 13)
 
 ```bash
@@ -29,17 +31,23 @@ sudo apt install -y build-essential g++ make libx11-dev libxcursor-dev \
 ### Building
 
 ```bash
-make              # Build raylib (first time) and compile sources
-make rebuild      # Clean and rebuild
-make clean-all    # Clean everything including raylib
+make              # Build library (liborbit.a), tests, and visualizer example
+make lib          # Build library only
+make example      # Build visualizer only
+make rebuild      # Clean and rebuild all
+make clean-all    # Clean everything
 ```
 
+The visualizer (`./build/orbit_sim`) links against the core simulation library.
+
 ## Running
 
 ```bash
-./orbit_sim       # Run with the default solar system configuration
+./build/orbit_sim # Run visualizer with default config
 ```
 
+Pass a config file as argument: `./build/orbit_sim tests/test_moon_orbits.toml`
+
 ## Documentation
 
 - **[Technical Reference](docs/technical_reference.md)** - Data structures and module overview
diff --git a/docs/technical_reference.md b/docs/technical_reference.md
index ea2b277..8d074b8 100644
--- a/docs/technical_reference.md
+++ b/docs/technical_reference.md
@@ -2,20 +2,20 @@
 
 ## Overview
 
-2-body orbital mechanics simulator using **analytical propagation** for precise Keplerian trajectories. Supports elliptical, parabolic, and hyperbolic orbits with dynamic Sphere of Influence (SOI) transitions, impulsive burns, and 3D visualization via Raylib.
+2-body orbital mechanics simulator using **analytical propagation** for precise Keplerian trajectories. Supports elliptical, parabolic, and hyperbolic orbits with dynamic Sphere of Influence (SOI) transitions and impulsive burns. 3D visualization via Raylib is provided as a separate example project in `example/`.
 
 ## Architecture
 
 Modular C-style C++ (structs/functions, no classes). Module dependencies:
 
 ```
-Main → Simulation → Orbital Mechanics → Physics
-      → Maneuver
-      → Rendezvous
-      → Config Loader
+Core Library → Simulation → Orbital Mechanics → Physics
+             → Maneuver
+             → Rendezvous
+             → Config Loader
 ```
 
-Renderer and UI Renderer depend on Config Loader for display data. Test Utilities are standalone.
+The core library (`liborbit.a`) contains all simulation code. 3D rendering (Raylib/raygui) is in `example/src/`. Test Utilities are standalone.
 
 ## Coordinate Frame System
 
@@ -250,9 +250,22 @@ All satisfy vis-viva: v² = μ(2/r - 1/a).
 
 ## Build System
 
-**Targets**: make / make all (build + ctags), make raylib, make test, make test-build, make clean, make clean-all, make rebuild.
+The project is split into a core simulation library and a visualizer example.
 
-**Dependencies**: g++ (C++14), raylib (git submodule), raygui (header-only), tomlc17, Catch2 (tests only).
+**Root Makefile** (simulation library + tests):
+- `make all` — build library, tests, and example (default)
+- `make lib` — build `build/liborbit.a` static library
+- `make test` — build and run all tests
+- `make test-build` — rebuild test executable only
+- `make clean` — clean build artifacts
+- `make clean-all` — clean everything including example
+- `make rebuild` — clean and rebuild all
+
+**Example Makefile** (visualizer):
+- `make all` — build `build/orbit_sim` (recursive from root via `make example`)
+- `make clean` — clean example build artifacts
+
+**Dependencies**: g++ (C++14), tomlc17 (root submodule), Catch2 (tests only). Raylib/raygui are in `example/ext/` submodules.
 
 **Testing**:
 ```bash