update TODO, move doc generation to ./tmp/

- Output summaries to tmp/summaries/ instead of alongside source files
- Add per-module timestamp caching (skip up-to-date modules)
- Add combine_summaries() to merge all into all_summaries.md
- Extract LLM provider and model to config variables
- Reorganize script: config, discovery, utilities, worker, main loop

.gitignore

@@ -6,7 +6,7 @@ orbit_test
 tests/informational/test_time_step_stability
 
 # LLM summaries
-src/*.summary.md
+tmp/
 
 # Session notes and conversation logs
 docs/session_logs

Makefile

@@ -49,9 +49,6 @@ clean:
 	rm -rf $(BUILD_DIR) $(LIBRARY)
 	$(MAKE) -C example clean
 
-clean-all: clean
-	$(MAKE) -C example clean-all
-
 rebuild: clean all
 
-.PHONY: all lib test-build test example clean clean-all rebuild
+.PHONY: all lib test-build test example clean rebuild

docs/TODO

@@ -17,10 +17,8 @@ If you see modifications to this file in git status, IGNORE them and do not comm
     - add reset/load new config UI control
     - UI fixes
 
-    - add more documentation for the LLM to use 'make test-build' and run individual tests
     - write out/fix inline code docs with the documentation generation script, and review
         - can then work on a better method for commenting/detecting changes via script
-    - move summary docs to separate folder and combine into a big 'API reference' doc
 
 
 === Project Documentation ===

scripts/generate_interface_summaries.sh

@@ -1,72 +1,116 @@
 #!/bin/bash
 # Generate interface summaries for all modules in src/
-# Creates temporary markdown files alongside source files for quick reference
+# Outputs to tmp/summaries/ (per-module cache) and supports combining into one file
 
 set -e
 
 SRC_DIR="/home/agent/dev/claudes_game/src"
 TEMP_EXT=".summary.md"
+SUMMARY_DIR="tmp/"
 PROMPT_FILE="scripts/prompt.md"
+LLM_PROVIDER="llama.cpp"
+LLM_MODEL="Qwen3.6-35B"
 
-# Function to generate prompt for a specific module
+# Discover modules from src/ directory
+MODULES=()
+for h in src/*.h; do
+    mod=$(basename "$h" .h)
+    MODULES+=("$mod")
+done
+
+# Generate prompt for a specific module
 generate_prompt() {
     local module_name="$1"
-    sed "s|\${module_name}|$module_name|g" "$PROMPT_FILE" | sed "s|\${SRC_DIR}|$SRC_DIR|g"
+    sed "s|\${module_name}|$module_name|g" "$PROMPT_FILE" \
+        | sed "s|\${SRC_DIR}|$SRC_DIR|g" \
+        | sed "s|\${SUMMARY_DIR}|$SUMMARY_DIR|g"
+}
+
+# Check if summary needs regeneration based on file timestamps
+needs_update() {
+    local source_file="$1"
+    local summary_file="$2"
+
+    # Regenerate if summary doesn't exist
+    [ ! -f "$summary_file" ] && return 0
+
+    # Regenerate if .h file is newer
+    [ "$source_file" -nt "$summary_file" ] && return 0
+
+    # Regenerate if .cpp file is newer (if it exists)
+    local cpp_file="${SRC_DIR}/$(basename "$source_file" .h).cpp"
+    if [ -f "$cpp_file" ] && [ "$cpp_file" -nt "$summary_file" ]; then
+        return 0
+    fi
+
+    return 1
 }
 
-# Function to process a single module
+# Process a single module header/cpp pair
 process_module() {
     local module_name="$1"
     local header_file="${SRC_DIR}/${module_name}.h"
-    local output_file="${SRC_DIR}/${module_name}${TEMP_EXT}"
+    local output_file="${SUMMARY_DIR}/${module_name}${TEMP_EXT}"
 
     if [ ! -f "$header_file" ]; then
         echo "Warning: No header file found for ${module_name}, skipping"
         return
     fi
 
+    if ! needs_update "$header_file" "$output_file"; then
+        echo "----------"
+        echo "Skipping ${module_name} (up to date)"
+        return
+    fi
+
     echo "----------"
     echo "Processing ${module_name}..."
 
-    # Build command as array
-    CMD=()
-    CMD+=("pi" "--print" "--no-session" "--provider" "llama.cpp" "--model" "Qwen3.6-35B")
+    local CMD=()
+    CMD+=("pi" "--print" "--no-session" "--provider" "$LLM_PROVIDER" "--model" "$LLM_MODEL")
     CMD+=("$(generate_prompt "$module_name")")
 
-    #echo "CMD would execute: ${CMD[*]}"
     "${CMD[@]}"
     echo "Generated: ${output_file}"
 }
 
-# List of modules to process (based on src/ directory)
-# Modules to exclude from processing
-EXCLUDED=("renderer" "ui_renderer" "config_validator")
+# Combine all per-module summaries into a single file
+combine_summaries() {
+    local output_file="${SUMMARY_DIR}/all_summaries.md"
+    echo "Combining summaries into ${output_file}..."
+
+    echo "# Combined Interface Summaries" > "$output_file"
+    echo "" >> "$output_file"
+    echo "Generated: $(date '+%Y-%m-%d %H:%M:%S')" >> "$output_file"
+    echo "" >> "$output_file"
 
-# Filter function
-is_excluded() {
-    local mod="$1"
-    for exc in "${EXCLUDED[@]}"; do
-        [[ "$mod" == "$exc" ]] && return 0
+    for module in "${MODULES[@]}"; do
+        local summary_file="${SUMMARY_DIR}/${module}${TEMP_EXT}"
+        if [ -f "$summary_file" ]; then
+            echo "" >> "$output_file"
+            echo "---" >> "$output_file"
+            echo "" >> "$output_file"
+            cat "$summary_file" >> "$output_file"
+        fi
     done
-    return 1
-}
 
-# Build filtered list
-MODULES=()
-for h in src/*.h; do
-    mod=$(basename "$h" .h)
-    is_excluded "$mod" || MODULES+=("$mod")
-done
+    echo "Combined ${#MODULES[@]} summaries into ${output_file}"
+}
 
+# Main execution
 echo "=== Interface Summary Generator ==="
 echo "Processing ${#MODULES[@]} modules..."
 echo ""
 
+mkdir -p "$SUMMARY_DIR"
+
 for module in "${MODULES[@]}"; do
     process_module "$module"
 done
 
 echo ""
 echo "=== Complete ==="
-echo "Generated ${TEMP_EXT} files alongside source files in ${SRC_DIR}"
+echo "Generated ${TEMP_EXT} files in ${SUMMARY_DIR}"
 echo "These files are temporary and should be added to .gitignore"
+
+combine_summaries

scripts/prompt.md

@@ -35,4 +35,4 @@ static const <type> <CONSTANT_NAME> = <value>;  // or inline (if needed)
 Keep summaries concise but do not oversimplify complex algorithms - include enough detail
 to understand the logic and approach. Focus on public interfaces, not internal implementation details.
 
-IMPORTANT: write output to one file alongside the module location: ${SRC_DIR}/${module_name}.summary.md
+IMPORTANT: write output to one file: ${SUMMARY_DIR}/${module_name}.summary.md