Initial commit: add .gitignore and README

docs/TROUBLESHOOTING.md

@@ -0,0 +1,169 @@
+# Troubleshooting Guide
+
+## Common Issues and Solutions
+
+### Strategy Validation Errors
+
+**Error**: "Strategy validation failed"
+
+**Solutions**:
+- Check JSON syntax
+- Verify all required fields are present
+- Check action types are valid
+- Verify addresses are correct format
+- Run `strategic validate strategy.json` for details
+
+### Execution Failures
+
+**Error**: "Target not allowed"
+
+**Solutions**:
+- Verify protocol address is in allow-list
+- Check executor configuration
+- Verify address matches chain
+- Add address to allow-list if needed
+
+**Error**: "Insufficient gas"
+
+**Solutions**:
+- Increase gas limit in strategy
+- Optimize strategy (reduce steps)
+- Check gas price settings
+- Review gas estimation
+
+**Error**: "Guard failed"
+
+**Solutions**:
+- Review guard parameters
+- Check guard context (oracle, adapter availability)
+- Adjust guard thresholds if appropriate
+- Review guard failure action (revert/warn/skip)
+
+### Flash Loan Issues
+
+**Error**: "Unauthorized pool"
+
+**Solutions**:
+- Verify Aave Pool is in allowed pools
+- Check pool address is correct for chain
+- Add pool to allow-list
+
+**Error**: "Flash loan repayment failed"
+
+**Solutions**:
+- Verify sufficient funds for repayment + premium
+- Check swap execution in callback
+- Review flash loan amount
+- Ensure operations in callback are correct
+
+### Adapter Errors
+
+**Error**: "Adapter not available"
+
+**Solutions**:
+- Verify protocol is configured for chain
+- Check chain name matches
+- Verify RPC endpoint is working
+- Check protocol addresses in config
+
+**Error**: "Invalid asset address"
+
+**Solutions**:
+- Verify asset address format
+- Check address exists on chain
+- Verify asset is supported by protocol
+- Check address is not zero address
+
+### Price Oracle Issues
+
+**Error**: "Oracle not found"
+
+**Solutions**:
+- Verify Chainlink oracle address
+- Check oracle exists on chain
+- Verify token has price feed
+- Check RPC endpoint
+
+**Error**: "Stale price data"
+
+**Solutions**:
+- Check oracle update frequency
+- Verify RPC endpoint latency
+- Adjust maxAgeSeconds in guard
+- Use multiple price sources
+
+### Gas Estimation Issues
+
+**Error**: "Gas estimation failed"
+
+**Solutions**:
+- Check RPC endpoint
+- Verify strategy is valid
+- Check executor address
+- Review transaction complexity
+- Use fork simulation for accurate estimate
+
+### Cross-Chain Issues
+
+**Error**: "Bridge not configured"
+
+**Solutions**:
+- Verify bridge addresses
+- Check chain selectors
+- Verify bridge is supported
+- Configure bridge in orchestrator
+
+**Error**: "Message status unknown"
+
+**Solutions**:
+- Check bridge status endpoint
+- Verify message ID format
+- Check finality thresholds
+- Review bridge documentation
+
+## Debugging Tips
+
+### Enable Verbose Logging
+
+```bash
+DEBUG=* strategic run strategy.json
+```
+
+### Use Explain Mode
+
+```bash
+strategic run strategy.json --explain
+```
+
+### Fork Simulation
+
+```bash
+strategic run strategy.json --simulate --fork $RPC_URL
+```
+
+### Check Strategy
+
+```bash
+strategic validate strategy.json
+```
+
+## Getting Help
+
+1. Check logs for detailed error messages
+2. Review strategy JSON syntax
+3. Verify all addresses and configurations
+4. Test on fork first
+5. Start with simple strategies
+6. Review documentation
+7. Check GitHub issues
+
+## Prevention
+
+- Always validate strategies before execution
+- Test on fork before live execution
+- Use guards for safety checks
+- Start with small amounts
+- Monitor gas usage
+- Review transaction logs
+- Keep addresses updated
+