docs: Update documentation for TradingSuite features and recent fixes

- Added comprehensive Features section to README with available feature flags
- Documented RiskManager integration requirements and position_manager attribute fix
- Updated CLAUDE.md with v3.1.13 development changes and Features enum
- Added patching_v4 changes to CHANGELOG with all fixes and improvements
- Clarified that OrderManager and PositionManager are always included by default

Author: TexasCoding

CHANGELOG.md

@@ -14,6 +14,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migration guides will be provided for all breaking changes
 - Semantic versioning (MAJOR.MINOR.PATCH) is strictly followed
 
+## [Unreleased] - patching_v4 branch
+
+### Fixed
+- **🔧 Bracket Order Fill Detection**: OrderManager now properly detects entry order fills
+  - Fixed initialization of OrderManager with realtime client for WebSocket callbacks
+  - Bracket orders now correctly wait for entry fills before placing protective orders
+  - OCO (One-Cancels-Other) linking properly implemented for stop/target pairs
+
+- **🔄 Circular Dependencies**: Resolved circular dependency between PositionManager and RiskManager
+  - Made cross-references optional during initialization
+  - Proper initialization sequence in TradingSuite
+
+- **🎯 RiskManager Integration**: Fixed RiskManager position manager references
+  - Now correctly sets both `positions` and `position_manager` attributes
+  - Ensures all risk methods work properly with PositionManager
+
+### Improved
+- **✅ Type Safety**: Full mypy compliance with 0 errors
+  - Added comprehensive protocol definitions for all manager interfaces
+  - Fixed all async method return type annotations
+  - Proper type hints for event handlers
+
+- **🧪 Test Suite**: Enhanced test mocking for cross-component dependencies
+  - Bracket order tests now properly mock all required methods
+  - Fixed test isolation for mixin testing
+
+### Documentation
+- Added comprehensive Features documentation to README
+- Updated CLAUDE.md with architectural changes
+- Clarified RiskManager feature flag requirements
+- Documented available TradingSuite features and their usage
+
 ## [3.1.12] - 2025-08-15
 
 ### Added

CLAUDE.md

@@ -162,6 +162,18 @@ uv run python -m build       # Alternative build command
 - Async event handlers with priority support
 - Built-in event types for all trading events
 
+### Available TradingSuite Features
+
+The `Features` enum defines optional components that can be enabled:
+
+- `ORDERBOOK = "orderbook"` - Level 2 market depth and analysis
+- `RISK_MANAGER = "risk_manager"` - Position sizing and risk management
+- `TRADE_JOURNAL = "trade_journal"` - Trade logging (future)
+- `PERFORMANCE_ANALYTICS = "performance_analytics"` - Advanced metrics (future)
+- `AUTO_RECONNECT = "auto_reconnect"` - Automatic reconnection (future)
+
+**Note**: OrderManager and PositionManager are always included by default.
+
 ### Architecture Patterns
 
 **Async Factory Functions**: Use async `create_*` functions for component initialization:
@@ -288,6 +300,14 @@ async with ProjectX.from_env() as client:
 
 ## Recent Changes
 
+### v3.1.13 - Current Development (patching_v4)
+- **Fixed**: Bracket order fill detection through proper WebSocket callback initialization
+- **Fixed**: Circular dependencies between PositionManager and RiskManager
+- **Fixed**: RiskManager integration now properly sets both `positions` and `position_manager` attributes
+- **Enhanced**: Full mypy type checking compliance with 0 errors
+- **Added**: Comprehensive protocol definitions for all manager interfaces
+- **Updated**: Test suite to properly mock cross-component dependencies
+
 ### v3.1.12 - Latest Release
 - **Enhanced**: Significantly improved `01_events_with_on.py` real-time data example
   - Added CSV export functionality with interactive prompts
@@ -375,7 +395,7 @@ async def main():
     suite = await TradingSuite.create(
         "MNQ",
         timeframes=["1min", "5min"],
-        features=["orderbook", "risk_manager"],
+        features=["orderbook", "risk_manager"],  # Optional features
         initial_days=5
     )
 

README.md

@@ -251,6 +251,38 @@ Or use a config file (`~/.config/projectx/config.json`):
 }
 ```
 
+### Available Features
+
+TradingSuite supports optional features that can be enabled during initialization:
+
+| Feature | String Value | Description |
+|---------|-------------|-------------|
+| **OrderBook** | `"orderbook"` | Level 2 market depth, bid/ask analysis, iceberg detection |
+| **Risk Manager** | `"risk_manager"` | Position sizing, risk validation, managed trades |
+| **Trade Journal** | `"trade_journal"` | Trade logging and performance tracking (future) |
+| **Performance Analytics** | `"performance_analytics"` | Advanced metrics and analysis (future) |
+| **Auto Reconnect** | `"auto_reconnect"` | Automatic WebSocket reconnection (future) |
+
+**Note:** PositionManager and OrderManager are always included and don't require feature flags.
+
+```python
+# Enable specific features
+suite = await TradingSuite.create(
+    "MNQ",
+    features=["orderbook", "risk_manager"]
+)
+
+# Access feature-specific components
+if suite.orderbook:  # Only available when orderbook feature is enabled
+    spread = await suite.orderbook.get_bid_ask_spread()
+
+if suite.risk_manager:  # Only available when risk_manager feature is enabled
+    sizing = await suite.risk_manager.calculate_position_size(
+        entry_price=100.0,
+        stop_loss=99.0
+    )
+```
+
 ### Component Overview
 
 #### ProjectX Client
@@ -296,11 +328,19 @@ icebergs = await suite.orderbook.detect_iceberg_orders()
 ```
 
 #### RiskManager
-Risk management and managed trades (when enabled):
+Risk management and managed trades (requires feature flag):
 ```python
 # Enable risk manager in features
 suite = await TradingSuite.create("MNQ", features=["risk_manager"])
 
+# Risk manager integrates with PositionManager automatically
+# Use for position sizing and risk validation
+sizing = await suite.risk_manager.calculate_position_size(
+    entry_price=100.0,
+    stop_loss=99.0,
+    risk_percent=0.02  # Risk 2% of account
+)
+
 # Use managed trades for automatic risk management
 async with suite.managed_trade(max_risk_percent=0.01) as trade:
     # Market price fetched automatically (v3.1.11+)
@@ -310,6 +350,8 @@ async with suite.managed_trade(max_risk_percent=0.01) as trade:
     )
 ```
 
+**Note:** RiskManager requires the `"risk_manager"` feature flag and automatically integrates with PositionManager for comprehensive risk tracking.
+
 ### Technical Indicators
 
 All 58+ indicators work with async data pipelines: