Condense and deduplicate project documentation

Reduced redundancy across documentation files:
- Condensed implementation_plan.md (236→112 lines)
- Condensed test_verification.md (143→62 lines), updated for 4-body test
- Condensed config_assumptions.md (115→44 lines), focused on active issues
- Removed architecture duplication from CLAUDE.md
- Removed common commands from verbose_project_overview.md
- Added 'make test' target to Makefile

Each file now has a clear, distinct purpose with minimal overlap.

🤖 Generated with Claude Code

CLAUDE.md

@@ -3,7 +3,8 @@
 ## Architecture
 - C-style C++ (structs/functions, NO classes/templates)
 - Raylib (git submodule) for 3D - chose over SFML (no 3D support)
-- See docs/implementation_plan.md for full technical design
+- See docs/verbose_project_overview.md for detailed technical architecture
+- See docs/implementation_plan.md for data structures reference
 
 ## Coding Rules
 - Use .cpp extensions (for future C++ features if needed)
@@ -31,5 +32,6 @@
 ## Common Commands
 - Build: make
 - Run: ./orbit_sim [config_file]
+- Test: make test
 - See README.md for full build instructions
 

Makefile

@@ -56,4 +56,8 @@ rebuild: clean all
 run: $(TARGET)
 	./$(TARGET)
 
-.PHONY: all clean clean-all rebuild run raylib
+# Run test configuration
+test: $(TARGET)
+	./$(TARGET) configs/test_simple.txt --headless --readable --days 365
+
+.PHONY: all clean clean-all rebuild run test raylib

docs/config_assumptions.md

@@ -1,114 +1,43 @@
-# Configuration File Assumptions and Issues
+# Configuration Issues & Known Bugs
 
-## Recent Updates:
+## Active TODOs:
-- ✅ **FIXED**: Eccentric orbit support added via eccentricity and semi_major_axis parameters
-- ✅ **FIXED**: Binary star barycenter calculation
-- ✅ **FIXED**: Refactored main.cpp into focused functions (parse args, run_headless, run_gui)
-- ✅ **FIXED**: Added initial state capture in headless mode for comparison with final state
 - ⚠️ **TODO**: Update configs/solar_system.txt to new 12-field format
 - ⚠️ **TODO**: Update configs/example_binary_star.txt to new 12-field format
 - ⚠️ **TODO**: Fix Moon and Jupiter's moons positions in solar_system.txt
 
-## Key Assumptions Found:
+## Fixed Issues:
+- ✅ Eccentric orbit support added
+- ✅ Binary star barycenter calculation
+- ✅ Refactored main.cpp into focused functions
+- ✅ Initial state capture in headless mode
 
-### **1. Format Assumptions (from config_loader.cpp)**
+## Known Issues:
-- Line buffer limited to 256 characters (config_loader.cpp:39)
-- Name limited to 64 characters (config_loader.cpp:40)
-- All 12 fields must be present: `name mass radius x y z parent_index r g b eccentricity semi_major_axis` (config_loader.cpp:16-20)
-- File format is space-delimited
 
-### **2. Solar System Configuration Issues:**
+### Solar System Configuration Issues:
 
-**Problem 1: Moon position is incorrect**
+**Moon position is incorrect (configs/solar_system.txt)**
-- Earth is at: `(1.496e11, 0, 0)` m
+- Earth at: `(1.496e11, 0, 0)` m
-- Moon is at: `(1.500e11, 0, 0)` m
+- Moon at: `(1.500e11, 0, 0)` m
-- Distance: ~4 million km, but Earth-Moon distance should be ~384,400 km (~3.844e8 m)
+- Distance: ~4M km, should be ~384,400 km (~3.844e8 m)
-- The Moon should be at approximately `(1.496e11 + 3.844e8, 0, 0)` or similar
+- Should be at: `(1.496e11 + 3.844e8, 0, 0)` approximately
 
-**Problem 2: Jupiter's moons positions**
+**Jupiter's moons positions (configs/solar_system.txt)**
-- Jupiter is at: `(7.785e11, 0, 0)` m
+- Io, Europa, Ganymede, Callisto all positioned incorrectly
-- Io is at: `(8.207e11, 0, 0)` m - **422 million km from Jupiter** (should be ~422,000 km = 4.22e8 m)
+- Currently use absolute coordinates, should be relative to Jupiter
-- Europa is at: `(8.456e11, 0, 0)` m - **671 million km from Jupiter** (should be ~671,000 km = 6.71e8 m)
+- Example: Io at `(8.207e11, 0, 0)` - 422M km from Jupiter (should be ~422,000 km)
-- Ganymede/Callisto have similar issues
 
-The moon positions appear to use **absolute coordinates** matching their orbital radii around the Sun, not relative positions around their parent bodies!
+### Implementation Notes:
 
-### **3. Binary Star Configuration Issues:**
+**Coordinate system**: All positions are absolute (heliocentric), not relative to parent
+**Velocity calculation**: Uses vis-viva equation: `v = sqrt(G*M*(2/r - 1/a))`
+**Orbit plane**: All orbits calculated in XY plane (Z-axis perpendicular)
 
-**~~Problem 1: Both stars have parent_index = -1~~ - FIXED**
+## Future Improvements:
-- StarA: `parent_index = -1`
-- StarB: `parent_index = -1`
-- ~~This means both are treated as root bodies with zero velocity (config_loader.cpp:69)~~
-- ~~They won't orbit each other!~~
-- **FIXED**: System now detects multiple root bodies, calculates barycenter, and sets appropriate orbital velocities (config_loader.cpp:64-146, bodies.cpp:101-124)
 
-**Problem 2: Planet positions**
+### Validation:
-- PlanetA1 is at `(3.5e11, 0, 0)` while StarA is at `(3.0e11, 0, 0)` - only 50 million km apart
+- Add config file validation to warn about incorrectly positioned child bodies
-- PlanetB1 is at `(-4.2e11, 0, 0)` while StarB is at `(-3.7e11, 0, 0)` - only 50 million km apart
+- Check for unrealistic orbital parameters
-- These seem reasonable as absolute positions (now supports both circular and eccentric orbits)
 
-### **4. Velocity Calculation Assumptions (config_loader.cpp:78-245):**
+### Features:
-- ~~All orbits are assumed to be **circular**~~ - **FIXED**: Now supports both circular (e=0) and eccentric (e>0) orbits
+- Consider relative coordinate option for child bodies
-- Velocities calculated using **vis-viva equation**: `v = sqrt(G*M*(2/r - 1/a))`
+- Add 3D orbit support (currently all orbits in XY plane)
-  - For circular orbits: e=0, a=orbital_radius
-  - For eccentric orbits: e>0, a=semi_major_axis
-- Orbits are calculated in the XY plane perpendicular to Z-axis (config_loader.cpp:219-226)
-- Root bodies (parent_index = -1) get zero velocity (or orbit barycenter if multiple roots)
-- Velocities are calculated relative to parent, then parent's velocity is added
-
-### **5. Critical Assumption:**
-The code assumes **positions are absolute (heliocentric)**, but for child bodies like moons, the **positions in the config should be relative to their parent**. This is not clearly documented and appears inconsistent!
-
-## Recommended Actions:
-
-### High Priority:
-1. **Update config files to new format** - All config files need to be updated to 12-field format
-   - ⚠️ `configs/solar_system.txt` - Still uses old 10-field format
-   - ⚠️ `configs/example_binary_star.txt` - Still uses old 10-field format
-   - ✅ `configs/test_simple.txt` - Already updated
-
-2. **Fix moon positions** - Moon and Jupiter's moons use incorrect absolute coordinates
-   - Moon should be at ~(1.496e11 + 3.844e8, 0, 0) not (1.500e11, 0, 0)
-   - Jupiter's moons should be relative to Jupiter's position
-
-### Medium Priority:
-3. **Add config file validation** - Warn when child bodies seem incorrectly positioned
-4. **Document coordinate system** - Clarify that positions are absolute (heliocentric)
-
-### Low Priority:
-5. **Consider relative coordinate option** - Allow specifying child positions relative to parent
-6. **Add 3D orbit support** - Currently all orbits are in XY plane
-
----
-
-## Session Notes (2026-01-03):
-
-### Changes Made:
-1. **Refactored main.cpp** - Broke 215-line main() into focused functions:
-   - `parse_command_line_args()` - Parse command line arguments into ProgramArgs struct
-   - `print_startup_info()` - Print simulation configuration
-   - `run_headless_simulation()` - Terminal-based simulation with initial/final state capture
-   - `run_gui_simulation()` - 3D visualization mode
-   - Main function now ~25 lines of setup and dispatch
-
-2. **Added eccentric orbit support**:
-   - Extended config format from 10 to 12 fields (added eccentricity, semi_major_axis)
-   - Implemented vis-viva equation: `v = sqrt(G*M*(2/r - 1/a))`
-   - Circular orbits: e=0, a=orbital_radius
-   - Elliptical orbits: e>0, a=semi_major_axis
-   - Renamed `calculate_initial_velocities_with_params()` → `calculate_velocities()`
-
-3. **Updated test_simple.txt**:
-   - Added Comet with highly eccentric orbit (e=0.7, a=2.5 AU)
-   - Perihelion: 0.75 AU, Aphelion: 4.25 AU
-   - Successfully tested - comet swings from 0.75 AU to ~3.8 AU
-
-4. **Documentation updates**:
-   - Updated README.md with new 12-field format and examples
-   - Updated this file with fixed issues and TODOs
-   - Added eccentric orbit feature to feature list
-
-### Known Issues:
-- **Old config files** still use 10-field format and need updating
-- **Moon positions** in solar_system.txt are physically incorrect
-- **No validation** for unrealistic body positions

docs/implementation_plan.md

@@ -1,36 +1,14 @@
-# Orbital Mechanics Simulation - Implementation Plan
+# Orbital Mechanics Simulation - Technical Reference
 
-## Project Overview
+## Overview
-A 3D orbital mechanics simulation using 2-body gravitational model with sphere of influence (SOI) transitions. Real-time visualization of the solar system (Sun, planets, moons) using raylib with C-style C++.
+3D orbital mechanics simulation using 2-body gravitational model with sphere of influence (SOI) transitions. Built with C-style C++ and raylib.
 
 ## Technical Constraints
 - C-style C++ only: structs and functions, no classes or templates
-- Small, focused functions
-- Simple rotations (Euler angles / axis-angle) - quaternions deferred for later
 - Euler integration for physics
+- Simple rotations (quaternions deferred)
 - raylib for 3D visualization
 
-## Project Structure
-
-```
-claudes_game/
-├── src/
-│   ├── main.cpp
-│   ├── physics.cpp
-│   ├── physics.h
-│   ├── bodies.cpp
-│   ├── bodies.h
-│   ├── renderer.cpp
-│   ├── renderer.h
-│   ├── config_loader.cpp
-│   └── config_loader.h
-├── configs/
-│   ├── solar_system.txt
-│   └── example_binary_star.txt
-├── Makefile
-└── README.md
-```
-
 ## Core Data Structures
 
 ### Vec3 (physics.h)
@@ -46,11 +24,13 @@ struct CelestialBody {
     char name[64];
     double mass;              // kg
     double radius;            // meters
-    Vec3 position;            // meters from solar system origin
+    Vec3 position;            // meters from origin
     Vec3 velocity;            // m/s
     double soi_radius;        // sphere of influence radius (meters)
-    int parent_index;         // index of gravitational parent (-1 for Sun)
+    int parent_index;         // index of gravitational parent (-1 for root)
     float color[3];           // RGB for rendering
+    double eccentricity;      // orbital eccentricity (0 = circular)
+    double semi_major_axis;   // meters
 };
 ```
 
@@ -59,177 +39,70 @@ struct CelestialBody {
 struct SimulationState {
     CelestialBody* bodies;
     int body_count;
+    int max_bodies;
     double time;              // simulation time (seconds)
     double dt;                // time step (seconds)
 };
 ```
 
-## Key Components
+### RenderState (renderer.h)
-
-### 1. Physics Module (physics.c/h)
-**Functions:**
-- `Vec3 vec3_add(Vec3 a, Vec3 b)` - vector addition
-- `Vec3 vec3_sub(Vec3 a, Vec3 b)` - vector subtraction
-- `Vec3 vec3_scale(Vec3 v, double s)` - scalar multiplication
-- `double vec3_magnitude(Vec3 v)` - vector length
-- `double vec3_distance(Vec3 a, Vec3 b)` - distance between points
-- `Vec3 vec3_normalize(Vec3 v)` - unit vector
-- `Vec3 calculate_gravity_force(CelestialBody* body, CelestialBody* parent)` - 2-body force
-- `Vec3 calculate_acceleration(Vec3 force, double mass)` - F = ma
-- `void euler_step(CelestialBody* body, Vec3 acceleration, double dt)` - Euler integration
-
-### 2. Bodies Module (bodies.c/h)
-**Functions:**
-- `SimulationState* create_simulation(int max_bodies)` - allocate simulation
-- `void destroy_simulation(SimulationState* sim)` - cleanup
-- `void add_body(SimulationState* sim, const char* name, double mass, double radius, Vec3 pos, Vec3 vel, float r, float g, float b)` - add celestial body
-- `int find_dominant_body(SimulationState* sim, int body_index)` - determine which body has gravitational dominance
-- `void update_soi(CelestialBody* body, CelestialBody* parent)` - calculate sphere of influence radius
-- `void update_simulation(SimulationState* sim)` - single time step update
-
-**SOI Calculation:**
-Using Hill sphere approximation: `r_soi = a * (m/M)^(2/5)`
-where a = semi-major axis, m = body mass, M = parent mass
-
-### 3. Config Loader Module (config_loader.cpp/h)
-**Functions:**
-- `bool load_system_config(SimulationState* sim, const char* filepath)` - load bodies from config file
-- `bool parse_body_line(const char* line, CelestialBody* body)` - parse single body definition
-- `void calculate_initial_velocities(SimulationState* sim)` - compute circular orbit velocities from positions
-
-**Config File Format (simple text):**
-```
-# Comment lines start with #
-# Format: name mass(kg) radius(m) x(m) y(m) z(m) parent_index r g b
-Sun 1.989e30 6.96e8 0 0 0 -1 1.0 1.0 0.0
-Earth 5.972e24 6.371e6 1.496e11 0 0 0 0.0 0.5 1.0
-Moon 7.342e22 1.737e6 1.4996e11 0 0 1 0.7 0.7 0.7
-# Velocity is calculated automatically for circular orbits
-```
-
-**Example configs to provide:**
-- `configs/solar_system.txt` - Our solar system with Sun, 8 planets, major moons
-- `configs/example_binary_star.txt` - Binary star system with planets
-
-### 4. Renderer Module (renderer.c/h)
-**Functions:**
-- `void init_renderer(int width, int height, const char* title)` - initialize raylib window
-- `void setup_camera(Camera3D* camera)` - configure 3D camera
-- `void render_body(CelestialBody* body, double scale)` - draw sphere for body
-- `void render_simulation(SimulationState* sim, Camera3D* camera)` - render all bodies
-- `void draw_orbit_trail(Vec3* positions, int count, Color color)` - draw orbit path (future enhancement)
-- `void close_renderer()` - cleanup raylib
-
-**Rendering approach:**
-- Use logarithmic scaling for distances (solar system is huge)
-- Use exponential scaling for body sizes (make small bodies visible)
-- Simple camera controls (rotate around Sun, zoom in/out)
-- Display FPS and simulation time
-
-### 5. Main Loop (main.cpp)
 ```cpp
-1. Parse command line arguments (config file path, default to configs/solar_system.txt)
+struct RenderState {
-2. Initialize raylib window and camera
+    Camera3D camera;
-3. Create simulation and load system from config file
+    double distance_scale;    // Scale factor for distances
-4. Main loop:
+    double size_scale;        // Scale factor for body sizes
-   a. Handle input (camera controls, pause/resume, speed adjustment)
+    bool show_info;           // Display simulation info
-   b. Update physics (multiple sub-steps per frame for stability)
+};
-   c. Check for SOI transitions
-   d. Render scene
-   e. Update camera
-5. Cleanup and exit
 ```
 
-## Implementation Steps
+## Module Overview
-
-### Phase 1: Foundation
-1. Create project structure and Makefile
-2. Implement Vec3 and basic vector math functions (physics.c/h)
-3. Define CelestialBody and SimulationState structs (bodies.h)
-4. Create basic simulation functions (create, destroy, add_body)
-
-### Phase 2: Physics Core
-5. Implement 2-body gravity calculation
-6. Implement Euler integration step
-7. Implement SOI detection and parent switching logic
-8. Create update_simulation() function
-
-### Phase 3: Config Loading System
-9. Implement config file parser (parse_body_line, skip comments/empty lines)
-10. Implement load_system_config() to read and populate simulation
-11. Create configs/solar_system.txt with our solar system data
-12. Implement calculate_initial_velocities() for circular orbits
-13. Calculate SOI radii for all bodies after loading
-
-### Phase 4: Visualization
-14. Initialize raylib window and 3D camera
-15. Implement render_body() with scaling
-16. Implement render_simulation() to draw all bodies
-17. Add basic camera controls (orbital rotation, zoom)
-
-### Phase 5: Integration and Refinement
-18. Integrate rendering with physics loop in main.cpp
-19. Add command line argument parsing for config file selection
-20. Add time scaling controls (speed up/slow down simulation)
-21. Add pause/resume functionality
-22. Display simulation info (time, FPS, body count, current config)
-23. Create example_binary_star.txt config for testing
-24. Test and tune time step for stability
-
-## Technical Notes
 
-### Config File System Benefits
+### Physics (physics.cpp/h)
-- **Flexibility**: Easily create any star system without recompiling
+Vector math and gravity calculations. Euler integration with `euler_step()`.
-- **Testing**: Quickly test different scenarios (binary stars, close encounters, etc.)
-- **Sharing**: Users can share interesting system configurations
-- **Debugging**: Simplified test cases with just 2-3 bodies
-- **Education**: Learn about different orbital configurations by experimenting
 
-### Scaling for Visualization
+### Bodies (bodies.cpp/h)
-- **Distance scale**: Use logarithmic or power-law scaling (e.g., `display_pos = sign(pos) * pow(abs(pos), 0.3)`)
+Simulation state management and updates. SOI detection using Hill sphere: `r_soi = a * (m/M)^(2/5)`
-- **Size scale**: Make minimum visible radius (e.g., max(actual_radius * scale, min_visible_radius))
-- Keep Sun at origin for simplicity
 
-### Time Step Considerations
+### Config Loader (config_loader.cpp/h)
-- Solar system scale requires small time steps (try dt = 60 seconds initially)
+Text-based config parser. Auto-calculates circular orbit velocities and SOI radii.
-- May need multiple physics updates per render frame
-- Allow user to adjust simulation speed multiplier
 
-### SOI Transition Logic
+**Config format:**
 ```
-For each body (except Sun):
+# name mass(kg) radius(m) x(m) y(m) z(m) parent_index r g b
-  1. Calculate distance to current parent
+Sun 1.989e30 6.96e8 0 0 0 -1 1.0 1.0 0.0
-  2. Calculate distance to all other potential parents
+Earth 5.972e24 6.371e6 1.496e11 0 0 0 0.0 0.5 1.0
-  3. Check if body is within SOI of a different parent
-  4. If yes, switch parent_index and recalculate relative state
 ```
 
-### Initial Conditions
+### Renderer (renderer.cpp/h)
-- Use Keplerian orbital elements or simplified circular orbits
+Raylib 3D visualization with logarithmic distance scaling and size scaling for visibility.
-- Ensure velocity is perpendicular to position vector for circular orbits
+
-- Circular orbit velocity: v = sqrt(G * M / r)
+## Implementation Status
-
+
-## Files to Create
+### ✅ Completed
-1. `src/physics.h` - Vector math and physics declarations
+- Phase 1-4: Core physics, simulation, config loading, and rendering
-2. `src/physics.cpp` - Vector math and physics implementations
+- Raylib integration with 3D camera
-3. `src/bodies.h` - Body and simulation data structures
+- Distance and size scaling for visualization
-4. `src/bodies.cpp` - Body management and simulation update
+- Config file system with solar_system.txt
-5. `src/config_loader.h` - Config file parsing declarations
+
-6. `src/config_loader.cpp` - Config file loading implementation
+### 🔨 Remaining/Future Work
-7. `src/renderer.h` - Rendering declarations
+- Time scaling controls (speed up/slow down)
-8. `src/renderer.cpp` - raylib rendering implementation
+- Pause/resume functionality
-9. `src/main.cpp` - Main loop and program entry
+- Additional config files (binary star, etc.)
-10. `configs/solar_system.txt` - Our solar system configuration
+- Time step tuning for stability
-11. `configs/example_binary_star.txt` - Example binary star system
+
-12. `Makefile` - Build configuration
+## Technical Notes
-13. `README.md` - Project documentation and config format docs
+
-
+### Scaling for Visualization
-## Future Enhancements (Not in Initial Implementation)
+- Distance: logarithmic/power-law scaling for solar system scale
-- Quaternion-based rotations
+- Size: minimum visible radius to prevent tiny bodies from disappearing
-- Orbit trail rendering
+- Origin at Sun for simplicity
-- N-body simulation mode
+
-- Patched conic approximation
+### Physics Considerations
-- More accurate integration (RK4, Verlet)
+- Timestep: ~60 seconds for solar system scale
-- Save/load simulation state
+- Circular orbit velocity: `v = sqrt(G * M / r)`
-- Interactive body selection and info display
+- May need multiple physics sub-steps per render frame
+
+## Future Enhancements
+- More accurate integration (RK4, Verlet), NOTE: try Newton-Raphson propagation method with testing first
+- Interactive body selection
 - Reference frame switching

docs/test_verification.md

@@ -1,142 +1,61 @@
-# Test Case Verification Guide
+# Test Verification Guide
 
-This document explains how to verify the orbital simulation using the `test_simple.txt` configuration.
+Quick reference for testing orbital mechanics using `configs/test_simple.txt`.
 
-## Running the Test
+## Test Command
 
 ```bash
-# Build the simulation
 make
-
-# Run the simple test case with human-readable output
 ./orbit_sim configs/test_simple.txt --headless --readable --days 365
 ```
 
-## Test Configuration
+## Test Bodies
-
-The `configs/test_simple.txt` file contains:
-- **Sun**: At the origin (0, 0, 0), mass 1.989e30 kg
-- **Earth**: Starts at 1.0 AU on the +X axis, mass 5.972e24 kg
-- **Mars**: Starts at 1.5 AU on the +X axis, mass 6.39e23 kg
-
-Both planets orbit in circular paths in the XY plane (counter-clockwise when viewed from +Z).
-
-## Expected Orbital Periods
-
-Using Kepler's third law: T² ∝ a³ (where T is period, a is semi-major axis)
-
-- **Earth**: T = 365.25 days (by definition)
-- **Mars**: T = 686.98 days (approximately 687 days)
-
-## Expected Velocities
-
-Circular orbit velocity: v = sqrt(G * M_sun / r)
-
-- **Earth**: v = 29.789 km/s
-- **Mars**: v = 24.323 km/s
-
-## Verification Points
-
-### Initial State (Day 0)
-```
-Earth:
-  Position: (1.0, 0.0, 0.0) AU
-  Velocity: (0.0, -29.789, 0.0) km/s
-
-Mars:
-  Position: (1.5, 0.0, 0.0) AU
-  Velocity: (0.0, -24.323, 0.0) km/s
-```
-
-### Quarter Orbit (Day ~91)
-After approximately 1/4 of Earth's year:
 
-```
+- **Sun**: Origin (0, 0, 0)
-Earth:
+- **Earth**: 1.0 AU, circular orbit (e=0), period ~365 days
-  Expected Position: (~0.0, -1.0, 0.0) AU
+- **Mars**: 1.5 AU, circular orbit (e=0), period ~687 days
-  Expected Velocity: (~-29.789, 0.0, 0.0) km/s
+- **Comet**: 2.5 AU semi-major axis, eccentric orbit (e=0.7), period ~1444 days
-  Distance: ~1.0 AU (circular orbit)
+  - Starts at perihelion (0.75 AU)
-
+  - Aphelion at 4.25 AU
-Mars:
-  Expected Position: (~0.987, -1.129, 0.0) AU (only traveled ~57 degrees)
-  Distance: ~1.5 AU (circular orbit)
-```
-
-### Half Orbit (Day ~183)
-After approximately 1/2 of Earth's year:
-
-```
-Earth:
-  Expected Position: (~-1.0, 0.0, 0.0) AU
-  Expected Velocity: (0.0, 29.789, 0.0) km/s
-  Distance: ~1.0 AU
-
-Mars:
-  Expected Position: (~0.72, -1.30, 0.0) AU (traveled ~114 degrees)
-  Distance: ~1.5 AU
-```
 
-### Full Orbit (Day ~365)
+All orbit counter-clockwise (viewed from +Z).
-After approximately 1 full Earth year:
 
-```
+## Expected Behavior
-Earth:
-  Expected Position: (~1.0, 0.0, 0.0) AU (back to start)
-  Expected Velocity: (0.0, -29.789, 0.0) km/s
-  Distance: ~1.0 AU
-
-Mars:
-  Expected Position: (~-0.87, -1.23, 0.0) AU (traveled ~228 degrees)
-  Distance: ~1.5 AU
-```
 
-## How to Verify
+**Circular orbits (Earth, Mars):**
+- Distance from Sun remains constant
+- Velocity magnitude remains constant
+  - Earth: ~29.8 km/s
+  - Mars: ~24.3 km/s
+- Return to starting position after full period
 
-1. **Check orbital stability**: The distance from the Sun should remain constant
+**Eccentric orbit (Comet):**
-   - Earth should stay at ~1.0 AU
+- Distance varies: 0.75 AU (perihelion) to 4.25 AU (aphelion)
-   - Mars should stay at ~1.5 AU
+- Velocity varies: faster at perihelion, slower at aphelion
+- Period ~1444 days
 
-2. **Check velocity magnitude**: Speed should remain constant in circular orbits
+## Quick Tests
-   - Earth: always ~29.789 km/s
-   - Mars: always ~24.323 km/s
-
-3. **Check orbital period**: Run for 365 days
-   - Earth should return to near its starting position
-   - Mars should complete about half its orbit (687 day period)
-
-4. **Check direction**: Both planets orbit counter-clockwise
-   - Starting at +X axis
-   - Moving in -Y direction
-   - Position angle increases over time
-
-## Quick Test Commands
 
 ```bash
-# Run for a quarter year (91 days)
+# Earth full orbit
-./orbit_sim configs/test_simple.txt --headless --readable --days 91
-
-# Run for a half year (183 days)
-./orbit_sim configs/test_simple.txt --headless --readable --days 183
-
-# Run for a full year (365 days)
 ./orbit_sim configs/test_simple.txt --headless --readable --days 365
 
-# Run for Mars' full orbit (687 days)
+# Mars full orbit
 ./orbit_sim configs/test_simple.txt --headless --readable --days 687
+
+# Comet full orbit (eccentric)
+./orbit_sim configs/test_simple.txt --headless --readable --days 1444
 ```
 
 ## Acceptable Tolerances
 
-Due to numerical integration with discrete time steps:
+Due to Euler integration with dt=60s:
-- Distance variation: ±0.001 AU (~150,000 km) is acceptable
+- Distance variation: ±0.001 AU
-- Velocity variation: ±0.1 km/s is acceptable
+- Velocity variation: ±0.1 km/s
-- Position after full orbit: Within 0.01 AU of starting position
+- Position after full orbit: Within 0.01 AU of start
-
-## Understanding the Output
 
-The `--readable` flag converts output to human-friendly units:
+## Output Flags
-- **Positions**: Shown in AU (Astronomical Units, ~150 million km)
-- **Velocities**: Shown in km/s
-- **Distances**: Shown in both AU and km
 
-Without `--readable`, all values are in SI units (meters, m/s) with scientific notation.
+- `--headless`: Terminal output only (no GUI)
+- `--readable`: Human-friendly units (AU, km/s) instead of SI (m, m/s)
+- `--days N`: Simulation duration in days

docs/verbose_project_overview.md

@@ -6,11 +6,6 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 A 3D orbital mechanics simulation using a 2-body gravitational model with sphere of influence (SOI) transitions. The simulation features real-time visualization using raylib and supports configurable star systems via text files.
 
-## Common Commands
-    - Build: make
-    - Run: ./orbit_sim [config_file]
-    - See README.md for full build instructions
-
 ## Architecture
 
 ### Code Style