## DO NOT TOUCH
- docs/TODO - Manual file only. Never read, write, restore, or commit
- docs/session_logs/ - Manual logs only. Never read or write

# Orbital Mechanics Simulation - Project Memory

## Architecture
- C-style C++ (structs/functions, NO classes/templates)
- 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

## Coding Rules
- Use .cpp extensions (for future C++ features if needed)
- Small, focused functions
- Follow existing patterns in src/
- Minimal comments - code should be self-documenting
- No decorative comment blocks (===, ---, etc.)
- Only comment non-obvious logic
- No trailing whitespace in any files (including markdown)
  - Pre-commit hook automatically strips it
  - For markdown line breaks, use <br> tag instead of two trailing spaces
- ZII (Zero Is Initialization) pattern: Initialize structs using `= {0}` or `= {NULL}` instead of individual field assignments. This guarantees all fields (including padding) are zeroed out. Example: `MyStruct s = {0};`

## File Reading Policy
- Ask before reading files unless immediately necessary for current task
- Exception: Can read without asking if:
  - Single small file (<100 lines) clearly needed
  - File explicitly mentioned by user
- When reading multiple files or large files (>200 lines), always verify first

## Git Workflow
- Small commits with logical separation
- Concise commit messages

## Session Summaries
- When user requests session summary, create in docs/session_summaries/
- Format: YYYY-MM-DD-descriptive-name.md
- Keep concise: changes made, commits, results (net line count)
- Document any remaining issues not resolved in the current session
- If applicable, add a short list of next steps for the next session
- Always ask the user if we want to update the technical_reference after generating a summary

## Common Commands
- 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]'
- Test (with debug output): ./build/orbit_test -s '[tag_name]'
    - needed to display 'INFO' statements for successful tests with Catch2 framework
- See docs/technical_reference.md for full build target reference

## Simulation
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
- Do NOT use `Approx()` - it is deprecated in Catch2
- Required header: `<catch2/matchers/catch_matchers_floating_point.hpp>`
- Usage: `REQUIRE_THAT(value, WithinAbs(expected, absolute_margin))`

## Documentation
- Always read in docs/technical_reference.md when starting a new session
- Always read in src/*.summary.md when starting a new session