cleanup README, and project memory for claude

.gitignore

@@ -2,6 +2,9 @@
 build/
 orbit_sim
 
+# Session notes and conversation logs
+sessions/
+
 # Editor/IDE files
 .vscode/
 .idea/

CLAUDE.md

@@ -0,0 +1,17 @@
+# Orbital Mechanics Simulation - Project Memory
+
+## 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
+
+## Coding Rules
+- Use .cpp extensions (for future C++ features if needed)
+- Small, focused functions
+- Follow existing patterns in src/
+
+## Common Commands
+- Build: make
+- Run: ./orbit_sim [config_file]
+- See README.md for full build instructions
+

README.md

@@ -116,25 +116,6 @@ Fields:
 
 Velocities are calculated automatically for circular orbits.
 
-## Project Structure
-
-```
-claudes_game/
-├── src/
-│   ├── main.cpp           - Main program loop
-│   ├── physics.cpp/h      - Vector math and physics
-│   ├── bodies.cpp/h       - Celestial bodies and simulation
-│   ├── config_loader.cpp/h - Configuration file parser
-│   └── renderer.cpp/h     - 3D rendering with raylib
-├── configs/
-│   ├── solar_system.txt   - Solar system configuration
-│   └── example_binary_star.txt - Binary star example
-├── docs/
-│   └── implementation_plan.md - Detailed implementation plan
-├── Makefile
-└── README.md
-```
-
 ## Technical Details
 
 - **Physics**: 2-body gravitational model using Newton's law of gravitation
@@ -143,16 +124,6 @@ claudes_game/
 - **Rendering**: Logarithmic distance scaling and exponential size scaling for visualization
 - **Language**: C-style C++ (structs and functions, no classes or templates)
 
-## Future Enhancements
-
-- Quaternion-based rotations for realistic body orientation
-- Orbit trail rendering
-- N-body simulation mode
-- More accurate integration methods (RK4, Verlet)
-- Save/load simulation state
-- Interactive body selection and information display
-- Multiple reference frames
-
 ## License
 
 This project is provided as-is for educational and research purposes.

docs/verbose_project_overview.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+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
+This project uses **C-style C++**: structs and functions, no classes or templates. All headers use include guards. Memory management uses malloc/free.
+
+### Core Components
+
+**Physics Layer** (`physics.h/cpp`)
+- Vector math operations (Vec3 struct with add, sub, scale, normalize, magnitude, distance)
+- Gravitational force calculation using Newton's law: F = G * m1 * m2 / r^2
+- Euler integration for position/velocity updates
+- Defines gravitational constant G = 6.67430e-11
+
+**Simulation Layer** (`bodies.h/cpp`)
+- `CelestialBody` struct: stores name, mass, radius, position, velocity, SOI radius, parent index, color
+- `SimulationState` struct: manages array of bodies, body count, simulation time, time step (dt)
+- SOI (sphere of influence) calculations using Hill sphere approximation
+- Dynamic parent switching when bodies cross SOI boundaries
+- `find_dominant_body()` determines which body has gravitational dominance
+- `update_simulation()` runs one physics step: finds dominant parent, calculates gravity, applies Euler integration
+
+**Configuration Layer** (`config_loader.h/cpp`)
+- Parses text configuration files with format: `name mass radius x y z parent_index r g b`
+- Automatically calculates circular orbit velocities for all bodies
+- Calculates SOI radii for all bodies based on parent relationships
+- Comments start with `#`, parent_index -1 indicates root bodies (stars)
+
+**Rendering Layer** (`renderer.h/cpp`)
+- `RenderState` struct: manages Camera3D, distance_scale, size_scale, show_info flag
+- Uses logarithmic distance scaling for visualization (astronomical distances → screen coordinates)
+- Uses exponential size scaling for body rendering (realistic radii → visible spheres)
+- Implements 3D camera controls via arrow keys
+- Renders bodies as colored spheres using raylib
+
+**Main Program** (`main.cpp`)
+- Initializes simulation with MAX_BODIES=100, TIME_STEP=60 seconds
+- Runs 100 physics steps per frame for stability (adjustable with speed multiplier)
+- Game loop: input handling → camera update → physics update (if not paused) → rendering
+- Supports speed multiplier (2x/0.5x per keypress, min 0.125x)
+
+### Data Flow
+
+1. Configuration file → `load_system_config()` → populates `SimulationState`
+2. `calculate_initial_velocities()` → sets circular orbit velocities
+3. `calculate_soi_radii()` → computes sphere of influence for each body
+4. Main loop:
+   - `update_simulation()` → for each body:
+     - `find_dominant_body()` → determine gravitational parent
+     - `calculate_gravity_force()` → compute force from parent
+     - `euler_step()` → update position/velocity
+   - `render_simulation()` → for each body:
+     - `scale_position()` → convert to render coordinates
+     - `scale_radius()` → convert to render size
+     - `render_body()` → draw sphere with color
+
+### Key Implementation Details
+
+**SOI Transitions**: Bodies dynamically switch gravitational parents when crossing sphere of influence boundaries. The switch uses a 0.5x distance hysteresis to prevent oscillation.
+
+**Rendering Scales**: Astronomical scales are incompatible with graphics. The renderer applies:
+- Logarithmic distance scaling to fit solar system in viewport
+- Exponential size scaling to make small bodies visible
+- Both scales are configurable in `RenderState`
+
+**Physics Stability**: Multiple physics steps per frame (100x by default) provide smoother integration. The time step is 60 seconds, so each frame simulates 6000 seconds of time at 1x speed.
+
+**Velocity Calculation**: Initial velocities for circular orbits are calculated using v = sqrt(G * M / r) where M is parent mass and r is orbital radius.
+