From 8fb7bfe0c7610b90f2fd515a7a5b6b494571babe Mon Sep 17 00:00:00 2001
From: chrisnov-it <contact@chrisnov.com>
Date: Tue, 23 Jun 2026 15:51:25 +0800
Subject: [PATCH] Add CLAUDE.md with project context and critical fix notes

---
 CLAUDE.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..00e5336
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,42 @@
+# CLAUDE.md — QuantumBotX
+
+## Project Overview
+AI-powered modular trading bot for MetaTrader 5.
+Windows-first, Python + Flask + Tailwind CSS + Chart.js.
+Live demo validated on XM Global MT5.
+
+## Branches
+- **`main`** — MT5-only, stable, active. 4 bots running on XM demo.
+- **`refactor/universal-architecture`** — broker-agnostic (CCXT + MT5), paused.
+
+## Active Context (2026-06-23)
+- 4 bots running: EURUSD (MA), GBPUSD (RSI), AUDUSD (Bollinger), GOLD (Turtle)
+- 2 SELL positions executed, ~$1.80 floating profit
+- All risk management active: break-even, spread guard, ATR cap
+- Venv: Python 3.14.4, MetaTrader5 5.0.5735
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| `run.py` | App entry + MT5 init |
+| `core/bots/trading_bot.py` | Bot thread (main loop, risk mgmt) |
+| `core/mt5/trade.py` | Order execution (SL/TP calc, I/O) |
+| `core/utils/mt5.py` | MT5 helpers (symbol mapping, rates) |
+| `core/strategies/` | 14 strategies |
+| `templates/base.html` | Main layout + dark mode toggle |
+| `.env` | MT5 creds + broker config |
+
+## Critical Fixes (do not revert)
+- `find_mt5_symbol()`: broker priority MUST be guarded with `base_symbol_cleaned == 'XAUUSD'`
+- `ORDER_FILLING_FOK` → `ORDER_FILLING_IOC` for XM broker compat
+- `place_trade()`: ATR multiplier capped at max 5× SL / 10× TP
+
+## Commands
+```bash
+source venv/Scripts/activate && python run.py  # Start app
+curl http://127.0.0.1:5000/api/health           # Check status
+curl http://127.0.0.1:5000/api/bots/status       # Bot list
+```
+
+## Docs (excluded from git)
+TASKS.md, MEMORY.md, WALKTHROUGH.md, RETROSPECT.md