From d79bf572ef690d4e4d9245578bbf15c4cdedad14 Mon Sep 17 00:00:00 2001
From: Kunthawat Greethong <kunthawat@gmailcom>
Date: Sat, 3 Jan 2026 14:32:17 +0700
Subject: [PATCH] docs: add AGENTS.md

---
 AGENTS.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..598c717
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,147 @@
+# MeanRevisionEA - Agent Guide
+
+This repository contains a MetaTrader 5 Expert Advisor (EA) for XAUUSD trading using mean reversion strategies with Open Interest levels.
+
+## Build / Lint / Test Commands
+
+MQL5 files are compiled via MetaEditor IDE, not command line. Use MetaEditor (F4 in MT5) → Open OI_MeanReversion_Pro_XAUUSD_A.mq5 → Press F7 to compile.
+
+**File Encoding:** UTF-16LE with CRLF line endings. MetaEditor handles this automatically.
+
+**Testing:** Use MetaTrader 5 Strategy Tester. No automated test framework.
+
+## Code Style Guidelines
+
+### Naming Conventions
+
+**Input Parameters:** `Inp` prefix + PascalCase
+```mql5
+input double InpLotSize = 0.1;
+input bool InpUseStopLoss = true;
+input ENUM_OI_SOURCE InpOISource = OI_SOURCE_MANUAL;
+```
+
+**Global Variables:** PascalCase (no prefix)
+```mql5
+double DeltaPrice = 0.0;
+double SpotPrice = 0.0;
+int DailyTradeCount = 0;
+```
+
+**Functions:** PascalCase with descriptive names
+```mql5
+void InitializeOILevels()
+bool CheckGlobalConditions()
+double CalculateLotSize(ENUM_POSITION_TYPE tradeType)
+```
+
+**Local Variables:** camelCase
+```mql5
+double lotSize = NormalizeLot(ManualLotSize);
+double riskAmount = balance * (InpRiskPercent / 100.0);
+```
+
+**Object Names:** Descriptive names with prefixes (e.g., "CP_" for control panel)
+```mql5
+CreateButton("CP_Sell", x, y, width, height, "Sell Now", clrRed, clrWhite);
+```
+
+### Enums and Constants
+
+**Enums:** `ENUM_` prefix, uppercase values
+```mql5
+enum ENUM_MARKET_PHASE {
+   PHASE_BULLISH,
+   PHASE_BEARISH,
+   PHASE_SIDEWAYS,
+   PHASE_NEUTRAL
+};
+```
+
+### Imports and Includes
+
+Use angle brackets with backslashes:
+```mql5
+#include <Trade\Trade.mqh>
+#include <Trade\AccountInfo.mqh>
+```
+
+### Function Documentation
+
+Use MetaTrader's standard format:
+```mql5
+//+------------------------------------------------------------------+
+//| Calculate Lot Size                                               |
+//+------------------------------------------------------------------+
+double CalculateLotSize(ENUM_POSITION_TYPE tradeType) { }
+```
+
+### Error Handling
+
+Check return values and validate inputs:
+```mql5
+if(Trade.Buy(lotSize, _Symbol, SpotPrice, sl, tp, "BUY")) {
+   Print("BUY executed");
+} else {
+   Print("BUY failed. Error: ", Trade.ResultRetcodeDescription());
+}
+if(PendingPriceValue <= 0) {
+   Print("Invalid price");
+   return;
+}
+```
+
+### Conditionals and Loops
+
+No space after `if`/`for`, space after condition:
+```mql5
+if(DeltaDeviation <= threshold)
+   return false;
+for(int i = PositionsTotal() - 1; i >= 0; i--) { }
+```
+
+### Arrays and Strings
+
+Use MQL5 functions for arrays and strings:
+```mql5
+ArrayResize(result, count + 1);
+ArraySort(CallLevels);
+StringToDouble(), StringToInteger(), DoubleToString(value, _Digits)
+```
+
+### Color and Object Management
+
+Use MQL5 color constants and check object existence:
+```mql5
+color PanelColor = C'30,30,30';
+color TextColor = clrWhite;
+if(ObjectFind(chart_id, name) < 0)
+   ObjectCreate(chart_id, name, OBJ_LABEL, 0, 0, 0);
+ObjectSetInteger(chart_id, name, OBJPROP_ZORDER, 1001);
+```
+
+### Trade Operations
+
+Normalize values and use CTrade library:
+```mql5
+NormalizeDouble(price, _Digits)
+NormalizeLot(lotSize)
+CTrade Trade;
+Trade.SetExpertMagicNumber(InpMagicNumber);
+Trade.Buy(lotSize, _Symbol, price, sl, tp, comment);
+```
+
+### Event Handlers
+
+Implement required MQL5 handlers:
+```mql5
+int OnInit()        // Initialization
+void OnDeinit()     // Cleanup
+void OnTick()       // Price tick
+void OnTimer()      // Timer events
+void OnChartEvent() // UI interactions
+```
+
+### Comments
+
+Use `//` for single-line, `/* */` for multi-line. Thai comments acceptable for user messages.
\ No newline at end of file