Update documentation for improved clarity and structure; add formatter CLI details and usage examples (#28)

Fixes #27

Author: popmonkey

DEVELOPMENT.md

@@ -18,13 +18,15 @@ It has been structured as a C-API library (`jres_solver`) and a simple CLI clien
 |   ├── jres_solver_utils.cpp       # Shared utilities and Base Class
 |   ├── jres_standard_solver.cpp    # Optimized Strict Solver
 |   ├── jres_diagnostic_solver.cpp  # Relaxed Diagnostic Solver
-|   └── jres_solver_types.cpp       # JSON serialization logic
+|   ├── jres_solver_types.cpp       # JSON serialization logic
+|   ├── formatter/                  # Formatter implementation
+|   └── utils/                      # Utility functions
 ├── lib/
 │   ├── cxxopts/                    # (Git Submodule) cxxopts header-only library
 │   └── json/                       # (Git Submodule) nlohmann/json header-only library
 ├── cmd/
-│   ├── /solver/                    # A CLI solver
-│   └── /formatter/                 # A CLI formatter
+│   ├── solver/                     # A CLI solver
+│   └── formatter/                  # A CLI formatter
 ├── test/                           # Google Test suite
 └── CMakeLists.txt                  # The main build script
 ```
@@ -112,25 +114,37 @@ We use a standard out-of-source CMake build.
     cmake --build .
     ```
 
-This will create two main products in the `build/` directory:
+This will create the main products in the `build/` directory:
 
-  * `libjres_solver.dylib` (or `.so` on Linux, `.dll` on Windows): The shared library.
-  * `jres_solver` (or `jres_solver.exe`): The CLI executable.
+  * `libjres_solver.a` (or `.lib` on Windows): The static library.
+  * `jres_solver` (or `jres_solver.exe`): The solver CLI executable.
+  * `jres_formatter` (or `jres_formatter.exe`): The formatter CLI executable.
 
-## Running the CLI Client
+## Running the CLI Clients
+
+### Solver
 
 The `jres_solver` executable is a client that uses the `jres_solver` library.
 
 ```
 # Run with a file
-./jres_solver -i ../data/race_data.json -s integrated
+./jres_solver -i ../data/short_race.json -s integrated
 
 # Pipe from stdin
-cat ../data/race_data.json | ./jres_solver -s sequential --allow-no-spotter
+cat ../data/24h_race.json | ./jres_solver -s sequential --allow-no-spotter
 
 # Run diagnostics on a failing schedule
 ./jres_solver -i ../data/infeasible.json --diagnose
 
 # Get help
 ./jres_solver --help
 ```
+
+### Formatter
+
+The `jres_formatter` executable formats solver output into various report formats.
+
+```
+# Get help
+./jres_formatter --help
+```

README.md

@@ -18,44 +18,56 @@ This library can be used to solve for optimal driver and spotter schedules for e
 
 The library exposes a C-compatible API and can be bound to languages like C, C++, Go, Python, or Rust.
 
-#### Header: `jres_solver.h`
+#### Basic Usage Example
 
 ```cpp
-// Structure defining solver configuration
-struct JresSolverOptions {
-    int timeLimit;               // Max runtime in seconds (e.g., 30)
-    JresSpotterMode spotterMode; // 0=None, 1=Integrated, 2=Sequential
-    bool allowNoSpotter;         // If true, stints can go without a spotter
-    double optimalityGap;        // Stop when solution is within this % of optimal (e.g., 0.05)
-    bool quiet;                  // If true, suppresses stdout logging
-};
-
-// Enum for spotter modes
-enum JresSpotterMode {
-    JRES_SPOTTER_MODE_NONE = 0,       // No Spotter schedule is solved for
-    JRES_SPOTTER_MODE_INTEGRATED = 1, // Driver and Spotter schedule is solved together
-    JRES_SPOTTER_MODE_SEQUENTIAL = 2  // Driver schedule is prioritized
-};
-
-// Main Solver Function
-// Returns 0 on success, -1 on failure.
-// outputJson is allocated by the library and must be freed by the caller.
-int solve_race_schedule(const char* raceDataJson,
-                        const JresSolverOptions& options,
-                        char** outputJson);
-
-// Diagnostic Solver Function
-// Runs a relaxed model to identify why a schedule is infeasible.
-// Returns 0 on success (diagnosis complete), -1 on internal failure.
-// outputJson will contain a "diagnosis" array with string explanations.
-int diagnose_race_schedule(const char* raceDataJson,
-                           const JresSolverOptions& options,
-                           char** outputJson);
-
-// Memory Cleanup
-void free_solver_result(char* resultJson);
+#include "jres_solver/jres_solver.hpp"
+
+// Configure solver options
+JresSolverOptions options;
+options.timeLimit = 5;
+options.spotterMode = JRES_SPOTTER_MODE_INTEGRATED;
+options.allowNoSpotter = false;
+options.optimalityGap = 0.2;
+options.quiet = false;
+
+// Solve with race data JSON string
+char* resultJson = nullptr;
+int status = solve_race_schedule(raceDataJson, options, &resultJson);
+
+// Always free the result
+free_solver_result(resultJson);
 ```
 
+For a complete working example, see [`cmd/solver/cli.cpp`](./cmd/solver/cli.cpp).
+
+#### Solver vs. Diagnostic Mode
+
+- **`solve_race_schedule()`**: Finds an optimal schedule satisfying all constraints. Returns an error if no feasible solution exists.
+
+- **`diagnose_race_schedule()`**: When the solver fails, this runs a relaxed model to identify which constraints are causing the infeasibility.
+
+#### Controlling Solve Time
+
+The solver can take a very long time (or never complete) for complex schedules if not properly constrained. Use `timeLimit` and `optimalityGap` to prevent excessive runtimes:
+
+**Recommended defaults:** `timeLimit = 5` seconds, `optimalityGap = 0.2` (20%)
+
+- **`timeLimit`**: Maximum seconds the solver will run before returning the best solution found. This is a hard stop.
+
+- **`optimalityGap`**: Allows the solver to stop early when it finds a "good enough" solution within this percentage of the theoretical optimum. For example, `0.2` means the solver stops once it finds a solution within 20% of optimal.
+
+**Why a small optimality gap is expensive and unnecessary:**
+
+Mixed Integer Programming problems like race scheduling are NP-hard. The solver may find a good feasible solution quickly (in seconds), but proving that solution is within 1% of optimal can take exponentially longer—hours or even days. For practical scheduling:
+
+- A 20% gap solution is typically excellent and solves in seconds
+- A 5% gap might take 10-100x longer with minimal practical benefit
+- A 1% gap can be prohibitively expensive, often timing out
+- The "optimal" schedule and a 20% suboptimal schedule are often nearly identical in practice—swapping equivalent drivers or spotters
+
+The solver prioritizes hard constraints (rest times, fuel, availability) first. The optimality gap only affects soft preferences like minimizing consecutive stints. A 20% gap on these preferences is imperceptible in real-world use.
+
 -----
 
 ### Input JSON Specification
@@ -183,6 +195,7 @@ The function returns a JSON string containing the solution or error details.
 }
 ```
 
+
 ---
 
 _Created by popmonkey, Gemini 2.5, Gemini 3.0, and ChatGPT 5.1_

TOOLS.md

@@ -18,20 +18,15 @@ brew tap popmonkey/jres_solver
 brew install jres_solver
 ```
 
-### Windows Specific Requirement
-
-On Windows, the `jres_solver` application is built as a thin executable that relies on a shared library. You must ensure the following DLL is present in the same directory as the executable (or in your system `%PATH%`):
-
-* **`jres_solver.dll`**
-
-The `jres_formatter` tool is statically linked and does not require this DLL.
-
 ---
 
 ## Solver (`jres_solver`)
 
 The **Solver** is the core engine. It accepts raw race data (track info, driver constraints, car specs) and calculates the optimal driver schedule.
 
+> [!TIP]
+> See the [README](./README.md#controlling-solve-time) for guidance on controlling solve time and understanding the difference between [Solver vs. Diagnostic Mode](./README.md#solver-vs-diagnostic-mode).
+
 ### Usage
 
 ```sh
@@ -101,11 +96,18 @@ If a schedule fails to solve, run with `-d` to get a plain English explanation o
 ./jres_solver -i race_config.json --diagnose
 ```
 
-**Advanced Optimization:**
-Run for up to 5 minutes (`300s`), use `integrated` spotter logic, and allow a 1% margin of error for faster results.
+**With Spotter Scheduling:**
+Use `integrated` spotter logic with a reasonable optimality gap for faster results.
 
 ```sh
-./jres_solver -i race_config.json -o solution.json -t 300 --spotter-mode integrated --optimality-gap 0.01
+./jres_solver -i race_config.json -o solution.json --spotter-mode integrated --optimality-gap 0.2
+```
+
+**Extended Solve Time:**
+For complex schedules, allow more time while maintaining a practical optimality gap.
+
+```sh
+./jres_solver -i race_config.json -o solution.json -t 30 --optimality-gap 0.2
 ```
 
 **Pipeline Usage:**
@@ -173,8 +175,8 @@ Here is how you would go from a raw configuration file to a final distributable
 ### Linux / macOS
 
 ```sh
-# Step 1: Solve the schedule (allowing 60 seconds for calculation)
-./jres_solver -i race_24h_config.json -o solved_schedule.json -t 60
+# Step 1: Solve the schedule (allowing 30 seconds with 20% optimality gap)
+./jres_solver -i race_24h_config.json -o solved_schedule.json -t 30 -g 0.2
 
 # Step 2: Format the solution into a ZIP file
 ./jres_formatter -i solved_schedule.json -o team_schedule.zip
@@ -183,10 +185,8 @@ Here is how you would go from a raw configuration file to a final distributable
 ### Windows (Command Prompt)
 
 ```cmd
-REM Ensure jres_solver.dll is in the current folder
-
 REM Step 1: Solve
-jres_solver.exe -i race_24h_config.json -o solved_schedule.json -t 60
+jres_solver.exe -i race_24h_config.json -o solved_schedule.json -t 30 -g 0.2
 
 REM Step 2: Format
 jres_formatter.exe -i solved_schedule.json -o team_schedule.zip