docs(api): update API reference and overview documentation

- Added overview section to the API reference
- Improved clarity of next steps in strategy guide
- Consolidated strategy hierarchy and available combinations
- Enhanced links to related documentation for better navigation

Author: Jason Marechal

docs/api/benders-strategy-api.md

@@ -1,5 +1,7 @@
 # Benders Strategy Pattern - API Reference
 
+**Overview**: See [Architecture Overview](../architecture/benders-strategy-overview.md) for high-level design and diagrams.
+
 ## Table of Contents
 1. [Interfaces](#interfaces)
 2. [Concrete Strategies](#concrete-strategies)
@@ -645,41 +647,7 @@ All methods from `BendersBase` are available in `IBendersCore`, ensuring backwar
 
 ## Summary
 
-### Strategy Hierarchy
-
-```
-IBendersCore (main interface)
-    └── BendersCore (orchestrator)
-            ├── IExecutionStrategy
-            │   ├── SequentialExecutionStrategy
-            │   └── ParallelMpiExecutionStrategy
-            ├── IBatchingStrategy
-            │   ├── NoBatchingStrategy
-            │   └── ByBatchStrategy
-            └── IOuterLoopStrategy
-                ├── NoOuterLoopStrategy
-                └── OuterLoopAdapter
-```
-
-### Available Combinations
-
-All **8 combinations** are supported:
-
-| Execution | Batching | OuterLoop | When Used |
-|-----------|----------|-----------|-----------|
-| Sequential | NoBatching | NoOuterLoop | Single process, no options |
-| Sequential | NoBatching | OuterLoop | Single process, outer-loop on |
-| Sequential | ByBatch | NoOuterLoop | Single process, batching on |
-| Sequential | ByBatch | OuterLoop | Single process, batching + outer-loop |
-| MPI | NoBatching | NoOuterLoop | Multi-process, no options |
-| MPI | NoBatching | OuterLoop | Multi-process, outer-loop on |
-| MPI | ByBatch | NoOuterLoop | Multi-process, batching on |
-| MPI | ByBatch | OuterLoop | Multi-process, batching + outer-loop |
-
----
-
-## Next Steps
-
-- Read [Developer Guide](../developer-guide/benders-strategy-guide.md) for usage patterns
-- See [Architecture Overview](../architecture/benders-strategy-overview.md) for design details
-- Review [Code Navigation](../developer-guide/code-navigation.md) to find code
+See [Architecture Overview](../architecture/benders-strategy-overview.md) for:
+- Complete strategy hierarchy diagram
+- Design principles and benefits
+- Available strategy combinations table

docs/architecture/benders-strategy-overview.md

@@ -68,55 +68,16 @@ This architecture enables **8 different combinations** while maintaining clean s
 
 ### Key Abstractions
 
-#### IBendersCore Interface
-The main interface for Benders engine operations:
-```cpp
-class IBendersCore {
-public:
-    virtual void launch() = 0;
-    virtual void InitializeProblems() = 0;
-    virtual void set_input_map(const CouplingMap&) = 0;
-    virtual int MasterRowIndex(const std::string&) const = 0;
-    virtual LogData GetBestIterationData() const = 0;
-    virtual WorkerMasterDataVect AllCuts() const = 0;
-    // ... other methods
-};
-```
+#### Key Strategy Interfaces
 
-#### Strategy Interfaces
-
-**IExecutionStrategy**: Controls how subproblems are solved
-```cpp
-class IExecutionStrategy {
-public:
-    virtual void Run() = 0;
-    virtual void InitializeProblems() = 0;
-    virtual void set_input_map(const CouplingMap&) = 0;
-    virtual std::string BendersName() const = 0;
-    // ... other methods
-};
-```
+Three focused interfaces separate concerns:
 
-**IBatchingStrategy**: Controls problem batching
-```cpp
-class IBatchingStrategy {
-public:
-    virtual void InitializeProblems() = 0;
-    virtual void UpdateStoppingCriterion() = 0;
-    virtual bool ShouldRelaxationStop() const = 0;
-};
-```
+- **IBendersCore**: Main interface for Benders engine operations
+- **IExecutionStrategy**: Controls how subproblems are solved (Sequential vs. MPI)
+- **IBatchingStrategy**: Controls problem batching
+- **IOuterLoopStrategy**: Controls outer-loop optimization
 
-**IOuterLoopStrategy**: Controls outer-loop optimization
-```cpp
-class IOuterLoopStrategy {
-public:
-    virtual void Run(IBendersCore*) = 0;
-    virtual void init_data() = 0;
-    virtual bool UpdateMaster(WorkerMasterDataVect&) = 0;
-    // ... other methods
-};
-```
+For detailed interface signatures and methods, see [API Reference](../../api/benders-strategy-api.md)
 
 ## Component Details
 
@@ -130,135 +91,43 @@ public:
 - Delegates operations to appropriate strategy
 - Coordinates execution flow
 
-**Location**: `src/cpp/benders/strategy/include/antares-xpansion/benders/strategy/BendersCore.h`
-
-**Example**:
-```cpp
-class BendersCore : public IBendersCore {
-public:
-    BendersCore(
-        std::unique_ptr<IExecutionStrategy> exec,
-        std::unique_ptr<IBatchingStrategy> batch,
-        std::unique_ptr<IOuterLoopStrategy> outer
-    );
-    
-    void launch() override;
-    // ... other IBendersCore methods
-    
-private:
-    std::unique_ptr<IExecutionStrategy> execution_;
-    std::unique_ptr<IBatchingStrategy> batching_;
-    std::unique_ptr<IOuterLoopStrategy> outer_loop_;
-};
-```
+For implementation details and code examples, see [API Reference - BendersCore](../../api/benders-strategy-api.md#orchestrator)
 
 ### Execution Strategies
 
-#### SequentialExecutionStrategy
-**Wraps**: BendersSequential  
-**Use Case**: Single-process execution  
-**Selection**: Automatic when `world->size() == 1`  
-**Location**: `src/cpp/benders/strategy/include/.../SequentialExecutionStrategy.h`
+- **SequentialExecutionStrategy**: Single-process execution
+- **ParallelMpiExecutionStrategy**: Multi-process MPI execution
 
-#### ParallelMpiExecutionStrategy
-**Wraps**: BendersMPI  
-**Use Case**: Multi-process MPI execution  
-**Selection**: Automatic when `world->size() > 1`  
-**Location**: `src/cpp/benders/strategy/include/.../ParallelMpiExecutionStrategy.h`
+Automatically selected based on `world->size()`. Details in [API Reference](../../api/benders-strategy-api.md#concrete-strategies)
 
 ### Batching Strategies
 
-#### NoBatchingStrategy
-**Behavior**: Passthrough (no batching logic)  
-**Use Case**: Process all subproblems together  
-**Selection**: When BENDERSMETHOD doesn't include "BY_BATCH"  
-**Location**: `src/cpp/benders/strategy/include/.../NoBatchingStrategy.h`
+- **NoBatchingStrategy**: Process all subproblems together
+- **ByBatchStrategy**: Process subproblems in batches
 
-#### ByBatchStrategy
-**Wraps**: BendersByBatch  
-**Use Case**: Process subproblems in batches  
-**Selection**: When BENDERSMETHOD includes "BY_BATCH"  
-**Location**: `src/cpp/benders/strategy/include/.../ByBatchStrategy.h`
+Selected based on BENDERSMETHOD enum. See [Developer Guide](../../developer-guide/benders-strategy-guide.md) for usage.
 
 ### Outer-Loop Strategies
 
-#### NoOuterLoopStrategy
-**Behavior**: Passthrough (no outer-loop optimization)  
-**Use Case**: Standard Benders without outer loop  
-**Selection**: When BENDERSMETHOD doesn't include "OUTERLOOP"  
-**Location**: `src/cpp/benders/strategy/include/.../NoOuterLoopStrategy.h`
+- **NoOuterLoopStrategy**: Standard Benders without outer loop
+- **OuterLoopAdapter**: Benders with outer-loop optimization
 
-#### OuterLoopAdapter
-**Wraps**: Outerloop::OuterLoop  
-**Use Case**: Benders with outer-loop optimization  
-**Selection**: When BENDERSMETHOD includes "OUTERLOOP"  
-**Location**: `src/cpp/benders/strategy/include/.../OuterLoopAdapter.h`
+Selected based on BENDERSMETHOD enum. See [API Reference](../../api/benders-strategy-api.md) for details.
 
 ## Execution Flow
 
-### Initialization Flow
+### Overview
 
-```
-BendersFactory::PrepareForExecution()
-    │
-    ├─→ Determine BENDERSMETHOD (from options)
-    │
-    ├─→ ConfigureBenders()
-    │   │
-    │   ├─→ Create ExecutionStrategy
-    │   │   └─→ world->size() == 1 ? Sequential : MPI
-    │   │
-    │   ├─→ Create BatchingStrategy
-    │   │   └─→ method has BY_BATCH ? ByBatch : NoBatch
-    │   │
-    │   ├─→ Create OuterLoopStrategy
-    │   │   └─→ method has OUTERLOOP ? OuterLoop : None
-    │   │
-    │   └─→ Create BendersCore(exec, batch, outer)
-    │
-    └─→ Return BendersEnvironment { benders: IBendersCore* }
-```
-
-### Runtime Execution Flow
-
-```
-client->launch()  // Called on IBendersCore
-    │
-    ▼
-BendersCore::launch()
-    │
-    ├─→ 1. outer_loop_->init_data()
-    │
-    ├─→ 2. batching_->InitializeProblems()
-    │
-    ├─→ 3. execution_->InitializeProblems()
-    │
-    ├─→ 4. if (outer_loop_ != nullptr)
-    │   │     outer_loop_->Run(this)  // Outer loop controls execution
-    │   │
-    │   └─→ else
-    │         execution_->Run()        // Direct execution
-    │
-    └─→ 5. batching_->UpdateStoppingCriterion()
-```
+Execution follows this sequence:
+1. **Initialize outer-loop**: Set up data structures
+2. **Initialize batching**: Configure batch processing
+3. **Initialize execution**: Set up solver strategies
+4. **Run**: Execute outer-loop (if enabled) or direct execution
+5. **Update stopping criterion**: Check convergence
 
-### Delegation Examples
-
-**Example 1: Get master row index**
-```
-Client → BendersCore::MasterRowIndex()
-           │
-           └─→ execution_->MasterRowIndex()
-                  │
-                  └─→ wrapped_benders_->MasterRowIndex()
-```
-
-**Example 2: Check if should stop**
-```
-Client → BendersCore::ShouldRelaxationStop()
-           │
-           └─→ batching_->ShouldRelaxationStop()
-```
+For detailed flow diagrams and code examples, see:
+- [API Reference - Orchestrator](../../api/benders-strategy-api.md#orchestrator)
+- [Developer Guide - Using the Strategy Pattern](../../developer-guide/benders-strategy-guide.md#using-the-strategy-pattern)
 
 ## Design Principles
 
@@ -332,9 +201,12 @@ All **8 combinations** are supported:
 
 ## Next Steps
 
-For detailed information, see:
-- **Developer Guide**: `docs/developer-guide/benders-strategy-guide.md`
-- **Code Navigation**: `docs/developer-guide/code-navigation.md`
-- **Testing Guide**: `docs/developer-guide/testing-strategy-pattern.md`
-- **API Reference**: `docs/api/benders-strategy-api.md`
-- **ADR**: `docs/architecture/adr/0001-benders-strategy-pattern.md`
+**Start here**: This is a high-level architecture overview.
+
+**For detailed API information**: See [API Reference](../../api/benders-strategy-api.md)
+
+**For practical guidance**: See [Developer Guide](../../developer-guide/benders-strategy-guide.md)
+
+**For code location and navigation**: See [Code Navigation](../../developer-guide/code-navigation.md)
+
+**For architectural decision context**: See [ADR 0001](adr/0001-benders-strategy-pattern.md)

docs/developer-guide/benders-strategy-guide.md

@@ -7,6 +7,7 @@
 4. [Common Patterns](#common-patterns)
 5. [Best Practices](#best-practices)
 6. [Troubleshooting](#troubleshooting)
+7. [Next Steps](#next-steps)
 
 ## Quick Start
 
@@ -57,45 +58,13 @@ The interface is the same! `IBendersCore` provides all methods from `BendersBase
 
 The factory creates a `BendersCore` with three composed strategies:
 
-```cpp
-// Inside BendersFactory::ConfigureBenders()
-
-// 1. Select execution strategy based on MPI world size
-if (world_->size() == 1) {
-    // Single process → Sequential
-    auto sequential = std::make_unique<BendersSequential>(...);
-    execution = std::make_unique<SequentialExecutionStrategy>(
-        std::move(sequential)
-    );
-} else {
-    // Multiple processes → MPI
-    auto mpi = std::make_unique<BendersMpi>(...);
-    execution = std::make_unique<ParallelMpiExecutionStrategy>(
-        std::move(mpi)
-    );
-}
+For details on factory implementation, see [API Reference - Factory](../api/benders-strategy-api.md#factory)
 
-// 2. Select batching strategy based on method
-if (method == BENDERS_BY_BATCH || method == BENDERS_BY_BATCH_OUTERLOOP) {
-    batching = std::make_unique<ByBatchStrategy>(...);
-} else {
-    batching = std::make_unique<NoBatchingStrategy>();
-}
-
-// 3. Select outer-loop strategy based on method
-if (method == BENDERS_OUTERLOOP || method == BENDERS_BY_BATCH_OUTERLOOP) {
-    outer_loop = std::make_unique<OuterLoopAdapter>(...);
-} else {
-    outer_loop = std::make_unique<NoOuterLoopStrategy>();
-}
-
-// 4. Compose into BendersCore
-return std::make_unique<BendersCore>(
-    std::move(execution),
-    std::move(batching),
-    std::move(outer_loop)
-);
-```
+**Key points**:
+1. **Execution strategy** is automatically selected based on MPI world size
+2. **Batching strategy** is selected based on BENDERSMETHOD enum
+3. **Outer-loop strategy** is selected based on BENDERSMETHOD enum
+4. All three are composed into BendersCore which orchestrates their execution
 
 ### Accessing Strategy Components
 
@@ -114,6 +83,8 @@ benders->launch();
 
 **Note**: You shouldn't need to access individual strategies directly. `BendersCore` handles all orchestration.
 
+For detailed interface documentation, see [API Reference](../api/benders-strategy-api.md)
+
 ## Adding New Strategies
 
 ### Example: Adding a GPU Execution Strategy
@@ -530,6 +501,6 @@ Currently, strategies are set at construction. For runtime swapping:
 
 ## Next Steps
 
-- Read [Architecture Overview](../architecture/benders-strategy-overview.md)
-- Study [Code Navigation Guide](code-navigation.md)
-- Check [API Reference](../api/benders-strategy-api.md)
+- Read [Architecture Overview](../architecture/benders-strategy-overview.md) for design principles
+- Study [Code Navigation Guide](code-navigation.md) to find code in the repository
+- Review [API Reference](../api/benders-strategy-api.md) for interface details and method signatures