docs: Comprehensive documentation update with multi-timeframe lessons

- Updated README.md with automation features and Docker troubleshooting
- Enhanced copilot-instructions.md with multi-timeframe patterns and Docker workflows
- Created DEVELOPMENT_GUIDE.md with comprehensive implementation patterns
- Added troubleshooting section for volume mount issues
- Documented fresh implementation approach vs file editing
- Included performance optimization tips and future roadmap
- Added testing strategies and common pitfall solutions

Key knowledge preserved:
- Multi-timeframe UI patterns and state management
- Docker Compose v2 syntax and volume mount troubleshooting
- Fresh file creation approach for problematic edits
- Complete automation page implementation examples

.github/copilot-instructions.instructions.md

@@ -55,6 +55,58 @@ npm run docker:exec       # Shell access for debugging inside container
 - **Development**: External port `9001` → Internal port `3000` (http://localhost:9001)
 - **Production**: External port `9000` → Internal port `3000` (http://localhost:9000)
 
+### Docker Volume Mount Troubleshooting
+**Common Issue**: File edits not reflecting in container due to volume mount sync issues.
+
+**Solutions:**
+1. **Fresh Implementation Approach**: When modifying existing files fails, create new files (e.g., `page-v2.js`) instead of editing corrupted files
+2. **Container Restart**: `docker compose -f docker-compose.dev.yml restart app`
+3. **Full Rebuild**: `docker compose -f docker-compose.dev.yml down && docker compose -f docker-compose.dev.yml up --build`
+4. **Manual Copy**: Use `docker cp` to copy files directly into container for immediate testing
+5. **Avoid sed/awk**: Direct text manipulation commands often corrupt JSX syntax - prefer file replacement
+
+**Volume Mount Verification:**
+```bash
+# Test volume mount sync
+echo "test-$(date)" > test-volume-mount.txt
+docker compose -f docker-compose.dev.yml exec app cat test-volume-mount.txt
+```
+
+### Multi-Timeframe Feature Copy Pattern
+When copying multi-timeframe functionality between pages:
+
+**Step 1: Identify Source Implementation**
+```bash
+# Search for existing timeframe patterns
+grep -r "timeframes.*=.*\[" app/ --include="*.js" --include="*.jsx"
+grep -r "selectedTimeframes" app/ --include="*.js" --include="*.jsx"
+```
+
+**Step 2: Copy Core State Management**
+```javascript
+// Always include these state hooks
+const [selectedTimeframes, setSelectedTimeframes] = useState(['1h', '4h']);
+const [balance, setBalance] = useState({ balance: 0, collateral: 0 });
+
+// Essential toggle function
+const toggleTimeframe = (tf) => {
+  setSelectedTimeframes(prev => 
+    prev.includes(tf) ? prev.filter(t => t !== tf) : [...prev, tf]
+  );
+};
+```
+
+**Step 3: Copy UI Components**
+- Timeframe checkbox grid
+- Preset buttons (Scalping, Day Trading, Swing Trading)
+- Auto-sizing position calculator
+- Formatted balance display
+
+**Step 4: Avoid Docker Issues**
+- Create new file instead of editing existing if volume mount issues persist
+- Use fresh filename like `page-v2.js` or `automation-v2/page.js`
+- Test in container before committing
+
 ### API Route Structure
 All core functionality exposed via Next.js API routes:
 ```typescript
@@ -105,6 +157,70 @@ const LAYOUT_URLS = {
 - `components/Dashboard.tsx` - Main trading dashboard with real Drift positions
 - `components/AdvancedTradingPanel.tsx` - Drift Protocol trading interface
 
+### Page Structure & Multi-Timeframe Implementation
+- `app/analysis/page.js` - Original analysis page with multi-timeframe functionality
+- `app/automation/page.js` - Original automation page (legacy, may have issues)
+- `app/automation-v2/page.js` - **NEW**: Clean automation page with full multi-timeframe support
+- `app/automation/page-v2.js` - Alternative implementation, same functionality as automation-v2
+
+**Multi-Timeframe Architecture Pattern:**
+```javascript
+// Standard timeframes array - use this exact format
+const timeframes = ['5m', '15m', '30m', '1h', '2h', '4h', '1d'];
+
+// State management for multi-timeframe selection
+const [selectedTimeframes, setSelectedTimeframes] = useState(['1h', '4h']);
+
+// Toggle function with proper array handling
+const toggleTimeframe = (tf) => {
+  setSelectedTimeframes(prev => 
+    prev.includes(tf) 
+      ? prev.filter(t => t !== tf)  // Remove if selected
+      : [...prev, tf]                // Add if not selected
+  );
+};
+
+// Preset configurations for trading styles
+const presets = {
+  scalping: ['5m', '15m', '1h'],
+  day: ['1h', '4h', '1d'],
+  swing: ['4h', '1d']
+};
+```
+
+**UI Pattern for Timeframe Selection:**
+```jsx
+// Checkbox grid layout with visual feedback
+<div className="grid grid-cols-4 gap-2 mb-4">
+  {timeframes.map(tf => (
+    <button
+      key={tf}
+      onClick={() => toggleTimeframe(tf)}
+      className={`p-2 rounded border transition-all ${
+        selectedTimeframes.includes(tf)
+          ? 'bg-blue-600 border-blue-500 text-white'
+          : 'bg-gray-700 border-gray-600 text-gray-300 hover:bg-gray-600'
+      }`}
+    >
+      {tf}
+    </button>
+  ))}
+</div>
+
+// Preset buttons for quick selection
+<div className="flex gap-2 mb-4">
+  {Object.entries(presets).map(([name, tfs]) => (
+    <button
+      key={name}
+      onClick={() => setSelectedTimeframes(tfs)}
+      className="px-3 py-1 bg-purple-600 hover:bg-purple-700 rounded text-sm"
+    >
+      {name.charAt(0).toUpperCase() + name.slice(1)}
+    </button>
+  ))}
+</div>
+```
+
 ## Environment Variables
 ```bash
 # AI Analysis (Required)

DEVELOPMENT_GUIDE.md

@@ -0,0 +1,348 @@
+# 🛠️ Development Guide: Multi-Timeframe Trading Bot
+
+## 🚀 Quick Reference for Future Development
+
+This guide contains lessons learned and best practices from implementing the multi-timeframe automation functionality. Use this to accelerate future development and avoid common pitfalls.
+
+## 🎯 Multi-Timeframe Implementation Pattern
+
+### Core Architecture
+```javascript
+// Standard timeframes configuration
+const timeframes = ['5m', '15m', '30m', '1h', '2h', '4h', '1d'];
+
+// State management
+const [selectedTimeframes, setSelectedTimeframes] = useState(['1h', '4h']);
+const [balance, setBalance] = useState({ balance: 0, collateral: 0 });
+
+// Toggle function - EXACT implementation required
+const toggleTimeframe = (tf) => {
+  setSelectedTimeframes(prev => 
+    prev.includes(tf) 
+      ? prev.filter(t => t !== tf)    // Remove if selected
+      : [...prev, tf]                  // Add if not selected
+  );
+};
+
+// Preset configurations
+const presets = {
+  scalping: ['5m', '15m', '1h'],
+  day: ['1h', '4h', '1d'], 
+  swing: ['4h', '1d']
+};
+```
+
+### UI Components Pattern
+```jsx
+// Timeframe checkbox grid
+<div className="grid grid-cols-4 gap-2 mb-4">
+  {timeframes.map(tf => (
+    <button
+      key={tf}
+      onClick={() => toggleTimeframe(tf)}
+      className={`p-2 rounded border transition-all ${
+        selectedTimeframes.includes(tf)
+          ? 'bg-blue-600 border-blue-500 text-white'
+          : 'bg-gray-700 border-gray-600 text-gray-300 hover:bg-gray-600'
+      }`}
+    >
+      {tf}
+    </button>
+  ))}
+</div>
+
+// Preset buttons
+<div className="flex gap-2 mb-4">
+  {Object.entries(presets).map(([name, tfs]) => (
+    <button
+      key={name}
+      onClick={() => setSelectedTimeframes(tfs)}
+      className="px-3 py-1 bg-purple-600 hover:bg-purple-700 rounded text-sm"
+    >
+      {name.charAt(0).toUpperCase() + name.slice(1)}
+    </button>
+  ))}
+</div>
+
+// Position sizing with balance integration
+<select 
+  value={positionPercentage} 
+  onChange={(e) => setPositionPercentage(parseFloat(e.target.value))}
+  className="bg-gray-700 border border-gray-600 rounded px-3 py-2"
+>
+  <option value={1}>1% (${(balance.balance * 0.01).toFixed(2)})</option>
+  <option value={5}>5% (${(balance.balance * 0.05).toFixed(2)})</option>
+  <option value={10}>10% (${(balance.balance * 0.10).toFixed(2)})</option>
+  <option value={25}>25% (${(balance.balance * 0.25).toFixed(2)})</option>
+  <option value={50}>50% (${(balance.balance * 0.50).toFixed(2)})</option>
+</select>
+```
+
+## 🐳 Docker Development Best Practices
+
+### Essential Commands (Docker Compose v2)
+```bash
+# Development environment (ALWAYS use for active development)
+npm run docker:dev                    # Port 9001:3000 with hot reload
+docker compose -f docker-compose.dev.yml up --build
+
+# Production environment
+npm run docker:up                     # Port 9000:3000 optimized
+docker compose -f docker-compose.prod.yml up --build
+
+# Debugging and maintenance
+npm run docker:logs                   # View container logs
+npm run docker:exec                   # Shell access to container
+docker compose -f docker-compose.dev.yml restart app  # Quick restart
+```
+
+### Volume Mount Troubleshooting
+
+**Problem**: File changes not reflecting in running container
+
+**Root Cause**: Docker volume mount synchronization issues, especially on Linux systems
+
+**Solutions (in order of preference)**:
+
+1. **Fresh Implementation Approach** (RECOMMENDED)
+   ```bash
+   # Instead of editing problematic files, create new ones
+   cp app/automation/page.js app/automation/page-v2.js
+   # OR create entirely new directory
+   mkdir app/automation-v2
+   # Edit the new file instead
+   ```
+
+2. **Container Restart**
+   ```bash
+   docker compose -f docker-compose.dev.yml restart app
+   ```
+
+3. **Full Rebuild** 
+   ```bash
+   docker compose -f docker-compose.dev.yml down
+   docker compose -f docker-compose.dev.yml up --build
+   ```
+
+4. **Volume Mount Verification**
+   ```bash
+   # Test if volume mount is working
+   echo "test-$(date)" > test-volume-mount.txt
+   docker compose -f docker-compose.dev.yml exec app cat test-volume-mount.txt
+   # Should show the same timestamp
+   ```
+
+5. **Manual File Copy** (for immediate testing)
+   ```bash
+   docker cp ./app/automation/page.js trader_dev:/app/app/automation/page.js
+   ```
+
+### Text Editing Pitfalls
+
+**NEVER use sed/awk for JSX files** - They often corrupt the syntax. Examples of problematic approaches:
+```bash
+# ❌ DON'T DO THIS - Often corrupts JSX
+sed -i 's/old_pattern/new_pattern/' app/automation/page.js
+
+# ❌ DON'T DO THIS - Breaks React syntax  
+awk 'pattern {action}' file.js > newfile.js
+```
+
+**✅ PREFERRED approaches**:
+1. Create new files instead of editing
+2. Use proper editing tools that understand JSX
+3. Manual copy/paste for small changes
+4. Use the `replace_string_in_file` tool with proper context
+
+## 📁 File Organization Strategy
+
+### Current Page Structure
+```
+app/
+├── analysis/page.js              # ✅ Original analysis with multi-timeframe
+├── automation/
+│   ├── page.js                   # ❌ Legacy, may have corruption issues
+│   └── page-v2.js               # ✅ Clean backup implementation
+├── automation-v2/
+│   └── page.js                   # ✅ NEW: Current working automation
+└── ...
+```
+
+### Naming Conventions for New Features
+- **Primary Implementation**: Use descriptive directory names (`automation-v2/`)
+- **Backup/Alternative**: Add `-v2`, `-clean`, `-working` suffixes
+- **Test Files**: Prefix with `test-` or put in `/test/` directory
+- **Backup Files**: Add `.backup`, `.working-backup` extensions
+
+## 🔍 Feature Copying Workflow
+
+When copying functionality between pages (like analysis → automation):
+
+### Step 1: Research Existing Implementation
+```bash
+# Find timeframe-related code
+grep -r "timeframes.*=.*\[" app/ --include="*.js" --include="*.jsx"
+grep -r "selectedTimeframes" app/ --include="*.js" --include="*.jsx"
+grep -r "toggleTimeframe" app/ --include="*.js" --include="*.jsx"
+```
+
+### Step 2: Create Clean Target File
+```bash
+# DON'T modify existing problematic files
+# CREATE new clean implementation
+cp app/analysis/page.js app/automation-v2/page.js
+# OR start completely fresh
+```
+
+### Step 3: Copy Core Components
+Required elements to copy:
+- [ ] `timeframes` array definition
+- [ ] `selectedTimeframes` state management
+- [ ] `toggleTimeframe` function
+- [ ] Timeframe checkbox grid UI
+- [ ] Preset buttons (Scalping, Day Trading, Swing)
+- [ ] Balance integration and formatting
+- [ ] Position sizing calculations
+
+### Step 4: Test in Container
+```bash
+# Ensure container sees changes
+npm run docker:dev
+# Access http://localhost:9001/automation-v2
+# Verify all functionality works
+```
+
+### Step 5: Commit Clean Implementation
+```bash
+git add .
+git commit -m "feat: Add automation V2 with multi-timeframe support"
+git push
+```
+
+## 🧪 Testing Strategy
+
+### Functional Testing Checklist
+- [ ] Timeframe checkboxes toggle correctly
+- [ ] Preset buttons select correct timeframes
+- [ ] Balance displays with proper formatting (2 decimal places)
+- [ ] Position sizing calculates correctly
+- [ ] Selected timeframes persist during page interaction
+- [ ] Visual feedback shows selected state
+- [ ] All 7 timeframes available (5m, 15m, 30m, 1h, 2h, 4h, 1d)
+
+### Docker Testing
+```bash
+# Test volume mount functionality
+echo "test-$(date)" > test-volume-mount.txt
+docker compose -f docker-compose.dev.yml exec app cat test-volume-mount.txt
+
+# Test hot reload
+# Make a small change to a file and verify it reflects in browser
+
+# Test container logs
+npm run docker:logs | grep -i error
+```
+
+## 🚨 Common Pitfalls & Solutions
+
+### Issue: "selectedTimeframes is not defined"
+**Cause**: State hook not properly imported or defined
+**Solution**: 
+```javascript
+import { useState } from 'react';
+const [selectedTimeframes, setSelectedTimeframes] = useState(['1h', '4h']);
+```
+
+### Issue: Checkboxes not showing selected state
+**Cause**: Missing `.includes()` check in className
+**Solution**:
+```javascript
+className={`... ${selectedTimeframes.includes(tf) ? 'selected-styles' : 'default-styles'}`}
+```
+
+### Issue: Balance showing as NaN or undefined
+**Cause**: Balance not properly fetched or formatted
+**Solution**:
+```javascript
+const [balance, setBalance] = useState({ balance: 0, collateral: 0 });
+// Format with: parseFloat(balance.balance).toFixed(2)
+```
+
+### Issue: File changes not reflecting in container
+**Cause**: Docker volume mount sync issues
+**Solution**: Use fresh implementation approach (create new files)
+
+### Issue: JSX syntax errors after text manipulation
+**Cause**: sed/awk corruption of JSX syntax
+**Solution**: Start with clean file, avoid text manipulation tools
+
+## 🎯 Performance Optimization
+
+### Multi-Timeframe Rendering
+```javascript
+// Efficient timeframe rendering with React.memo for large lists
+const TimeframeButton = React.memo(({ tf, isSelected, onToggle }) => (
+  <button
+    onClick={() => onToggle(tf)}
+    className={`... ${isSelected ? 'selected' : 'default'}`}
+  >
+    {tf}
+  </button>
+));
+
+// Use in parent component
+{timeframes.map(tf => (
+  <TimeframeButton
+    key={tf}
+    tf={tf}
+    isSelected={selectedTimeframes.includes(tf)}
+    onToggle={toggleTimeframe}
+  />
+))}
+```
+
+### Balance Updates
+```javascript
+// Throttle balance updates to avoid excessive API calls
+useEffect(() => {
+  const fetchBalance = async () => {
+    try {
+      const response = await fetch('/api/balance');
+      const data = await response.json();
+      setBalance(data);
+    } catch (error) {
+      console.error('Balance fetch failed:', error);
+    }
+  };
+
+  fetchBalance();
+  const interval = setInterval(fetchBalance, 30000); // Every 30 seconds
+  return () => clearInterval(interval);
+}, []);
+```
+
+## 📊 Future Development Roadmap
+
+### Immediate Improvements
+- [ ] Add timeframe-specific position sizing recommendations
+- [ ] Implement timeframe conflict detection (opposing signals)
+- [ ] Add saved timeframe combinations (custom presets)
+- [ ] Enhance balance integration with real-time updates
+
+### Advanced Features
+- [ ] Multi-symbol automation across timeframes
+- [ ] Automated position sizing based on volatility
+- [ ] Cross-timeframe correlation analysis
+- [ ] Risk management integration per timeframe
+
+### Code Quality
+- [ ] TypeScript migration for automation pages
+- [ ] Unit tests for timeframe logic
+- [ ] Integration tests for Docker workflows
+- [ ] Performance monitoring for multi-timeframe operations
+
+---
+
+**Key Takeaway**: When in doubt, create new files instead of editing problematic ones. Docker volume mount issues are easier to solve with fresh implementations than complex debugging.
+
+**Success Pattern**: Analysis page → Clean automation-v2 implementation → Working multi-timeframe functionality

README.md

@@ -30,6 +30,14 @@ A professional-grade Next.js trading dashboard with AI-powered chart analysis, d
 - **Risk/Reward Ratios** with specific R:R calculations
 - **Confirmation Triggers** - Exact signals to wait for before entry
 
+### 🤖 **Automated Trading Features**
+- **Multi-Timeframe Automation** - Select 1-8 timeframes for comprehensive strategy coverage
+- **Trading Style Presets** - Scalping (5m,15m,1h), Day Trading (1h,4h,1d), Swing (4h,1d)
+- **Automatic Position Sizing** - Balance-based calculations with leverage recommendations
+- **Real-Time Balance Integration** - Live wallet display with percentage-based position sizing
+- **Risk Management** - Timeframe-specific leverage and position size recommendations
+- **Clean UI/UX** - Checkbox-based timeframe selection with visual feedback
+
 ### 🖼️ **Enhanced Screenshot Service**
 - **Dual-Session Capture** - Parallel AI and DIY layout screenshots
 - **Docker Optimized** - Full CPU utilization for faster processing
@@ -120,6 +128,39 @@ The system includes optimized Docker configurations:
 
 3. **View Results** with consensus, divergences, and individual timeframe setups
 
+### Multi-Timeframe Automation (/automation-v2)
+
+1. **Access Automation**: Navigate to `/automation-v2` for the latest automation interface
+2. **Select Timeframes**: Use checkboxes to select 1-8 timeframes
+   - Individual selection: Click any timeframe checkbox
+   - Quick presets: Scalping, Day Trading, Swing Trading buttons
+3. **Position Sizing**: 
+   - View real-time wallet balance
+   - Select position percentage (1%, 5%, 10%, 25%, 50%)
+   - Automatic leverage calculations based on timeframe
+4. **Execute**: Run automation across all selected timeframes simultaneously
+
+### Docker Development Workflow
+
+```bash
+# Start development environment
+npm run docker:dev          # Runs on http://localhost:9001
+
+# View logs for debugging
+npm run docker:logs
+
+# Access container shell for troubleshooting  
+npm run docker:exec
+
+# Test volume mount sync (if files not updating)
+echo "test-$(date)" > test-volume-mount.txt
+docker compose -f docker-compose.dev.yml exec app cat test-volume-mount.txt
+
+# Full rebuild if issues persist
+docker compose -f docker-compose.dev.yml down
+docker compose -f docker-compose.dev.yml up --build
+```
+
 ### API Usage
 
 ```bash
@@ -180,7 +221,13 @@ node test-enhanced-screenshot.js
 ```
 trading_bot_v3/
 ├── app/                          # Next.js app router
-│   ├── api/enhanced-screenshot/  # Screenshot & AI analysis API
+│   ├── analysis/                 # Multi-timeframe analysis page
+│   ├── automation/               # Trading automation pages
+│   │   ├── page.js              # Original automation (legacy)
+│   │   └── page-v2.js           # Clean automation implementation
+│   ├── automation-v2/           # NEW: Multi-timeframe automation
+│   │   └── page.js              # Full automation with timeframe support
+│   ├── api/enhanced-screenshot/ # Screenshot & AI analysis API
 │   ├── globals.css              # Global styles
 │   ├── layout.tsx               # Root layout
 │   └── page.tsx                 # Main dashboard
@@ -212,6 +259,15 @@ node test-enhanced-screenshot.js
 
 # Test Docker setup
 docker compose up --build
+
+# Test automation features
+curl -X POST http://localhost:9001/api/automation \
+  -H "Content-Type: application/json" \
+  -d '{
+    "symbol": "BTCUSD",
+    "timeframes": ["1h", "4h", "1d"],
+    "positionSize": 10
+  }'
 ```
 
 ### Expected Test Output
@@ -221,6 +277,11 @@ docker compose up --build
 ✅ API endpoint available
 🎯 SUCCESS: Both AI and DIY layouts captured successfully!
 📊 Test Summary: 100% success rate
+
+🤖 Testing Multi-Timeframe Automation
+✅ Timeframe selection working
+✅ Position sizing calculations correct
+✅ Balance integration successful
 ```
 
 ## 🎯 Features in Detail