update documentation

Author: TexasCoding

.cursorrules

@@ -2,29 +2,51 @@
 
 This file provides guidance to Cursor AI when working with code in this repository.
 
-## Project Status: v3.0.1 - Production-Ready Async Architecture
+## Project Status: v3.1.1 - Stable Production Release
 
 **IMPORTANT**: This project uses a fully asynchronous architecture. All APIs are async-only, optimized for high-performance futures trading.
 
 ## Development Phase Guidelines
 
-**IMPORTANT**: This project is in active development. When making changes:
+**IMPORTANT**: This project has reached stable production status. When making changes:
 
-1. **No Backward Compatibility**: Do not maintain old implementations for compatibility
-2. **Clean Code Priority**: Always refactor to the cleanest, most modern approach
-3. **Remove Legacy Code**: Delete old logic when implementing improvements
-4. **Breaking Changes Allowed**: Make breaking changes freely to improve architecture
-5. **Modern Patterns**: Use the latest Python patterns and best practices
-6. **Simplify Aggressively**: Remove complexity rather than adding compatibility layers
+1. **Maintain Backward Compatibility**: Keep existing APIs functional with deprecation warnings
+2. **Deprecation Policy**: Mark deprecated features with warnings, remove after 2 minor versions
+3. **Semantic Versioning**: Follow semver strictly (MAJOR.MINOR.PATCH)
+4. **Migration Paths**: Provide clear migration guides for breaking changes
+5. **Modern Patterns**: Use the latest Python patterns while maintaining compatibility
+6. **Gradual Refactoring**: Improve code quality without breaking existing interfaces
 7. **Async-First**: All new code must use async/await patterns
 
 Example approach:
-- ❌ DON'T: Keep old method signatures with deprecation warnings
-- ✅ DO: Replace methods entirely with better implementations
-- ❌ DON'T: Add compatibility shims or adapters
-- ✅ DO: Update all callers to use new patterns
-- ❌ DON'T: Create synchronous wrappers for async methods
-- ✅ DO: Use async/await throughout the entire call stack
+- ✅ DO: Keep old method signatures with deprecation warnings
+- ✅ DO: Provide new improved APIs alongside old ones
+- ✅ DO: Add compatibility shims when necessary
+- ✅ DO: Document migration paths clearly
+- ❌ DON'T: Break existing APIs without major version bump
+- ❌ DON'T: Remove deprecated features without proper notice period
+
+### Deprecation Process
+1. Mark as deprecated with `warnings.warn()` and `@deprecated` decorator
+2. Document replacement in deprecation message
+3. Keep deprecated feature for at least 2 minor versions
+4. Remove only in major version releases (4.0.0, 5.0.0, etc.)
+
+Example:
+```python
+import warnings
+from typing import deprecated
+
+@deprecated("Use new_method() instead. Will be removed in v4.0.0")
+def old_method(self):
+    warnings.warn(
+        "old_method() is deprecated, use new_method() instead. "
+        "Will be removed in v4.0.0",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    return self.new_method()
+```
 
 ## Development Commands
 

AGENTS.md

@@ -1,5 +1,39 @@
 # Repository Guidelines
 
+## Project Status: v3.1.1 - Stable Production Release
+
+**IMPORTANT**: This project has reached stable production status. When making changes:
+
+1. **Maintain Backward Compatibility**: Keep existing APIs functional with deprecation warnings
+2. **Deprecation Policy**: Mark deprecated features with warnings, remove after 2 minor versions  
+3. **Semantic Versioning**: Follow semver strictly (MAJOR.MINOR.PATCH)
+4. **Migration Paths**: Provide clear migration guides for breaking changes
+5. **Modern Patterns**: Use the latest Python patterns while maintaining compatibility
+6. **Gradual Refactoring**: Improve code quality without breaking existing interfaces
+7. **Async-First**: All new code must use async/await patterns
+
+### Deprecation Process
+- Mark as deprecated with `warnings.warn()` and `@deprecated` decorator
+- Document replacement in deprecation message
+- Keep deprecated feature for at least 2 minor versions
+- Remove only in major version releases (4.0.0, 5.0.0, etc.)
+
+Example:
+```python
+import warnings
+from typing import deprecated
+
+@deprecated("Use new_method() instead. Will be removed in v4.0.0")
+def old_method(self):
+    warnings.warn(
+        "old_method() is deprecated, use new_method() instead. "
+        "Will be removed in v4.0.0",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    return self.new_method()
+```
+
 ## Project Structure & Module Organization
 - Source: `src/project_x_py/` (core SDK: client, realtime, orderbook, indicators, utils, etc.).
 - Tests: `tests/` (pytest; async tests supported).

CHANGELOG.md

@@ -5,16 +5,25 @@ All notable changes to the ProjectX Python client will be documented in this fil
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## ⚠️ Development Phase Notice
+## 📦 Stable Production Release Notice
 
-**IMPORTANT**: This project is under active development. During this phase:
-- Breaking changes may be introduced without deprecation warnings
-- Backward compatibility is not maintained
-- Old implementations are removed when improved
-- Clean, modern code architecture is prioritized
+**IMPORTANT**: As of v3.1.1, this project has reached stable production status:
+- Backward compatibility is now maintained between minor versions
+- Deprecation warnings will be provided for at least 2 minor versions before removal
+- Breaking changes will only occur in major version releases (4.0.0, 5.0.0, etc.)
+- Migration guides will be provided for all breaking changes
+- Semantic versioning (MAJOR.MINOR.PATCH) is strictly followed
 
 ## [3.1.1] - 2025-08-10
 
+### Changed
+- **📦 MAJOR POLICY CHANGE**: Project has reached stable production status
+  - Now maintaining backward compatibility between minor versions
+  - Deprecation warnings will be provided for at least 2 minor versions
+  - Breaking changes only in major releases (4.0.0+)
+  - Updated all AI assistant documentation files (CLAUDE.md, GROK.md, GEMINI.md, AGENTS.md, .cursorrules)
+  - Updated CONTRIBUTING.md with backward compatibility guidelines
+
 ### Fixed
 - **🐛 Test Suite Compatibility**: Fixed all failing tests for optimized cache implementation
   - Updated test references from old cache variables (`_instrument_cache`) to new optimized ones (`_opt_instrument_cache`)

CLAUDE.md

@@ -2,29 +2,51 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Project Status: v3.0.2 - Production-Ready Async Architecture
+## Project Status: v3.1.1 - Stable Production Release
 
 **IMPORTANT**: This project uses a fully asynchronous architecture. All APIs are async-only, optimized for high-performance futures trading.
 
 ## Development Phase Guidelines
 
-**IMPORTANT**: This project is in active development. When making changes:
+**IMPORTANT**: This project has reached stable production status. When making changes:
 
-1. **No Backward Compatibility**: Do not maintain old implementations for compatibility
-2. **Clean Code Priority**: Always refactor to the cleanest, most modern approach
-3. **Remove Legacy Code**: Delete old logic when implementing improvements
-4. **Breaking Changes Allowed**: Make breaking changes freely to improve architecture
-5. **Modern Patterns**: Use the latest Python patterns and best practices
-6. **Simplify Aggressively**: Remove complexity rather than adding compatibility layers
+1. **Maintain Backward Compatibility**: Keep existing APIs functional with deprecation warnings
+2. **Deprecation Policy**: Mark deprecated features with warnings, remove after 2 minor versions
+3. **Semantic Versioning**: Follow semver strictly (MAJOR.MINOR.PATCH)
+4. **Migration Paths**: Provide clear migration guides for breaking changes
+5. **Modern Patterns**: Use the latest Python patterns while maintaining compatibility
+6. **Gradual Refactoring**: Improve code quality without breaking existing interfaces
 7. **Async-First**: All new code must use async/await patterns
 
 Example approach:
-- ❌ DON'T: Keep old method signatures with deprecation warnings
-- ✅ DO: Replace methods entirely with better implementations
-- ❌ DON'T: Add compatibility shims or adapters
-- ✅ DO: Update all callers to use new patterns
-- ❌ DON'T: Create synchronous wrappers for async methods
-- ✅ DO: Use async/await throughout the entire call stack
+- ✅ DO: Keep old method signatures with deprecation warnings
+- ✅ DO: Provide new improved APIs alongside old ones
+- ✅ DO: Add compatibility shims when necessary
+- ✅ DO: Document migration paths clearly
+- ❌ DON'T: Break existing APIs without major version bump
+- ❌ DON'T: Remove deprecated features without proper notice period
+
+### Deprecation Process
+1. Mark as deprecated with `warnings.warn()` and `@deprecated` decorator
+2. Document replacement in deprecation message
+3. Keep deprecated feature for at least 2 minor versions
+4. Remove only in major version releases (4.0.0, 5.0.0, etc.)
+
+Example:
+```python
+import warnings
+from typing import deprecated
+
+@deprecated("Use new_method() instead. Will be removed in v4.0.0")
+def old_method(self):
+    warnings.warn(
+        "old_method() is deprecated, use new_method() instead. "
+        "Will be removed in v4.0.0",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    return self.new_method()
+```
 
 ## Development Commands
 

CONTRIBUTING.md

@@ -207,6 +207,44 @@ Good documentation is essential for this project:
 
 ## Architecture Guidelines
 
+### Backward Compatibility Policy (v3.1.1+)
+
+**IMPORTANT**: This project maintains strict backward compatibility:
+
+1. **API Stability**: Public APIs must remain stable between minor versions
+2. **Deprecation Process**:
+   - Add deprecation warnings using `warnings.warn()` and `@deprecated` decorator
+   - Document the replacement in the deprecation message
+   - Keep deprecated features for at least 2 minor versions
+   - Only remove in major version releases (4.0.0, 5.0.0, etc.)
+
+3. **Adding Deprecation Warnings**:
+   ```python
+   import warnings
+   from typing import deprecated
+   
+   @deprecated("Use new_method() instead. Will be removed in v4.0.0")
+   def old_method(self):
+       warnings.warn(
+           "old_method() is deprecated, use new_method() instead. "
+           "Will be removed in v4.0.0",
+           DeprecationWarning,
+           stacklevel=2
+       )
+       return self.new_method()
+   ```
+
+4. **Introducing New Features**:
+   - Add new methods/classes alongside existing ones
+   - Provide migration guides in docstrings
+   - Update examples to use new patterns
+   - Keep old patterns working with deprecation warnings
+
+5. **Version Numbering** (Semantic Versioning):
+   - PATCH (x.x.N): Bug fixes only, no API changes
+   - MINOR (x.N.x): New features, deprecations allowed, no breaking changes
+   - MAJOR (N.x.x): Breaking changes allowed, remove deprecated features
+
 ### Project Structure
 
 The SDK uses a modular architecture where large components are split into multi-file packages:

GEMINI.md

@@ -2,29 +2,51 @@
 
 This file provides guidance to Google's Gemini models when working with code in this repository.
 
-## Project Status: v3.0.1 - Production-Ready Async Architecture
+## Project Status: v3.1.1 - Stable Production Release
 
 **IMPORTANT**: This project uses a fully asynchronous architecture. All APIs are async-only, optimized for high-performance futures trading.
 
 ## Development Phase Guidelines
 
-**IMPORTANT**: This project is in active development. When making changes:
+**IMPORTANT**: This project has reached stable production status. When making changes:
 
-1. **No Backward Compatibility**: Do not maintain old implementations for compatibility
-2. **Clean Code Priority**: Always refactor to the cleanest, most modern approach
-3. **Remove Legacy Code**: Delete old logic when implementing improvements
-4. **Breaking Changes Allowed**: Make breaking changes freely to improve architecture
-5. **Modern Patterns**: Use the latest Python patterns and best practices
-6. **Simplify Aggressively**: Remove complexity rather than adding compatibility layers
+1. **Maintain Backward Compatibility**: Keep existing APIs functional with deprecation warnings
+2. **Deprecation Policy**: Mark deprecated features with warnings, remove after 2 minor versions
+3. **Semantic Versioning**: Follow semver strictly (MAJOR.MINOR.PATCH)
+4. **Migration Paths**: Provide clear migration guides for breaking changes
+5. **Modern Patterns**: Use the latest Python patterns while maintaining compatibility
+6. **Gradual Refactoring**: Improve code quality without breaking existing interfaces
 7. **Async-First**: All new code must use async/await patterns
 
 Example approach:
-- ❌ DON'T: Keep old method signatures with deprecation warnings
-- ✅ DO: Replace methods entirely with better implementations
-- ❌ DON'T: Add compatibility shims or adapters
-- ✅ DO: Update all callers to use new patterns
-- ❌ DON'T: Create synchronous wrappers for async methods
-- ✅ DO: Use async/await throughout the entire call stack
+- ✅ DO: Keep old method signatures with deprecation warnings
+- ✅ DO: Provide new improved APIs alongside old ones
+- ✅ DO: Add compatibility shims when necessary
+- ✅ DO: Document migration paths clearly
+- ❌ DON'T: Break existing APIs without major version bump
+- ❌ DON'T: Remove deprecated features without proper notice period
+
+### Deprecation Process
+1. Mark as deprecated with `warnings.warn()` and `@deprecated` decorator
+2. Document replacement in deprecation message
+3. Keep deprecated feature for at least 2 minor versions
+4. Remove only in major version releases (4.0.0, 5.0.0, etc.)
+
+Example:
+```python
+import warnings
+from typing import deprecated
+
+@deprecated("Use new_method() instead. Will be removed in v4.0.0")
+def old_method(self):
+    warnings.warn(
+        "old_method() is deprecated, use new_method() instead. "
+        "Will be removed in v4.0.0",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    return self.new_method()
+```
 
 ## Development Commands
 

.grok/GROK.md GROK.md.grok/GROK.md renamed to GROK.md

@@ -7,29 +7,51 @@ This is a Python SDK/client library for the ProjectX Trading Platform Gateway AP
 
 **Note**: Focus on toolkit development, not on creating trading strategies.
 
-## Project Status: v2.0.4 - Async Architecture
+## Project Status: v3.1.1 - Stable Production Release
 
-**IMPORTANT**: This project has migrated to a fully asynchronous architecture as of v2.0.0. All APIs are now async-only with no backward compatibility to synchronous versions.
+**IMPORTANT**: This project uses a fully asynchronous architecture. All APIs are async-only, optimized for high-performance futures trading.
 
 ## Development Phase Guidelines
 
-**IMPORTANT**: This project is in active development. When making changes:
+**IMPORTANT**: This project has reached stable production status. When making changes:
 
-1. **No Backward Compatibility**: Do not maintain old implementations for compatibility
-2. **Clean Code Priority**: Always refactor to the cleanest, most modern approach
-3. **Remove Legacy Code**: Delete old logic when implementing improvements
-4. **Breaking Changes Allowed**: Make breaking changes freely to improve architecture
-5. **Modern Patterns**: Use the latest Python patterns and best practices
-6. **Simplify Aggressively**: Remove complexity rather than adding compatibility layers
+1. **Maintain Backward Compatibility**: Keep existing APIs functional with deprecation warnings
+2. **Deprecation Policy**: Mark deprecated features with warnings, remove after 2 minor versions
+3. **Semantic Versioning**: Follow semver strictly (MAJOR.MINOR.PATCH)
+4. **Migration Paths**: Provide clear migration guides for breaking changes
+5. **Modern Patterns**: Use the latest Python patterns while maintaining compatibility
+6. **Gradual Refactoring**: Improve code quality without breaking existing interfaces
 7. **Async-First**: All new code must use async/await patterns
 
 Example approach:
-- ❌ DON'T: Keep old method signatures with deprecation warnings
-- ✅ DO: Replace methods entirely with better implementations
-- ❌ DON'T: Add compatibility shims or adapters
-- ✅ DO: Update all callers to use new patterns
-- ❌ DON'T: Create synchronous wrappers for async methods
-- ✅ DO: Use async/await throughout the entire call stack
+- ✅ DO: Keep old method signatures with deprecation warnings
+- ✅ DO: Provide new improved APIs alongside old ones
+- ✅ DO: Add compatibility shims when necessary
+- ✅ DO: Document migration paths clearly
+- ❌ DON'T: Break existing APIs without major version bump
+- ❌ DON'T: Remove deprecated features without proper notice period
+
+### Deprecation Process
+1. Mark as deprecated with `warnings.warn()` and `@deprecated` decorator
+2. Document replacement in deprecation message
+3. Keep deprecated feature for at least 2 minor versions
+4. Remove only in major version releases (4.0.0, 5.0.0, etc.)
+
+Example:
+```python
+import warnings
+from typing import deprecated
+
+@deprecated("Use new_method() instead. Will be removed in v4.0.0")
+def old_method(self):
+    warnings.warn(
+        "old_method() is deprecated, use new_method() instead. "
+        "Will be removed in v4.0.0",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    return self.new_method()
+```
 
 ## Tool Usage Guidelines
 As Grok CLI, you have access to tools like view_file, create_file, str_replace_editor, bash, search, and todo lists. Use them efficiently for tasks.