================================================================
AI GOLD ONI - SETUP GUIDE
================================================================


QUICK START (3 steps)

Step 1: Attach the EA to a XAUUSD M5 chart
Step 2: Set your risk (InpRiskPercent)
Step 3: Choose Strategy 1 or Strategy 2 and click OK

The EA handles everything else automatically.


================================================================
BROKER REQUIREMENTS
================================================================

- Symbol: XAUUSD (Gold)
- Chart timeframe: M5
- Account type: ECN or Raw Spread recommended
- Spread: ideally under 20-25 points raw on XAUUSD
- Server timezone: any (the EA auto-detects GMT on live accounts)


================================================================
FULL PARAMETER REFERENCE
================================================================


--- RISK MANAGEMENT ---

Use risk percent by balance (InpUseRiskPct)
  Default: true
  When ON, the EA calculates lot size automatically based on your
  account balance and the risk percent you set below.
  When OFF, it uses the fixed lot size instead.
  -> Recommended: leave ON for all accounts.

Balance risk for each trade (InpRiskPercent)
  Default: 2
  The percentage of your account balance risked per trade.
  Example: $10,000 account at 2% = $200 risk per trade.
  -> Prop firm: use 0.2 to 0.5
  -> Personal account: 1 to 2 is a reasonable range
  -> This value affects lot size, not stop loss distance.

Fixed lot size (InpFixedLot)
  Default: 0.01
  Only used when "Use risk percent" is OFF.
  If you turn off InpUseRiskPct, every trade will use this
  exact lot size regardless of balance or stop distance.
  -> Only use this if you know exactly what you are doing.


--- EXIT SETTINGS ---

Stop loss distance (InpAtrSlMult)
  Default: 3
  The stop loss is set at this multiple of the M15 ATR(61)
  away from the entry price.
  Example: ATR = 10 points, multiplier = 3 -> SL = 30 points.
  -> Larger value = wider stop = fewer stopped-out trades,
     but higher risk per trade (lot size adjusts automatically).
  -> Do not change this unless you have a specific reason.

Take profit distance (InpTpAtrMult)
  Default: 6
  The take profit is set at this multiple of the M15 ATR(61).
  Default gives a 1:2 risk-to-reward ratio (SL x3, TP x6).
  -> Set to 0 to disable fixed TP (use only trailing stop).
  -> Increasing this gives bigger wins but lower win rate.

Keep minimum safe distance (InpAutoProtectByPoints)
  Default: false
  When ON, the EA enforces a minimum SL distance in points
  to avoid orders being rejected by the broker for being
  too close to the market. Only enable if your broker
  frequently rejects orders for stop distance reasons.
  -> Leave OFF for most brokers.


--- TRAILING STOP ---

Turn on trailing stop (InpUseTrail)
  Default: true
  Enables the trailing stop feature. Once a trade moves
  into profit past the start threshold, the stop loss
  follows the price at a set distance.
  -> Recommended: leave ON.

Profit level to start trailing (InpTrailStartMult)
  Default: 0.3
  The trailing stop activates when the trade profit reaches
  this multiple of the M15 ATR. At default 0.3, if ATR = 10
  points, trailing begins when the trade is 3 points in profit.
  -> Lower value = trail starts earlier (more protection,
     but may close trades before they run).
  -> Higher value = trail starts later (lets trades breathe).

Space allowed after trailing starts (InpTrailDistMult)
  Default: 0.29
  Once trailing is active, the stop loss is placed this many
  ATR multiples behind the current price.
  Example: ATR = 10, multiplier = 0.29 -> trail distance = 2.9 pts.
  -> Smaller = tighter trail (locks profit sooner, exits earlier).
  -> Larger = more breathing room (fewer early exits).

Minimum move before updating stop (InpTrailStepMult)
  Default: 1.3
  The stop loss only moves when price has advanced by at least
  this ATR multiple since the last update. Prevents the stop
  from updating on every single tick.
  -> Leave at default unless you notice excessive updates in log.

Update once per minute (InpTrailOnlyOnNewM1)
  Default: false
  When ON, the trailing stop only checks and updates once per
  M1 bar instead of every tick. Reduces server load on slow VPS.
  -> Leave OFF for normal use.


--- PROP FIRM SAFETY SETTINGS ---

Maximum spread allowed (InpMaxSpreadPoints)
  Default: 350
  The EA will not place new pending orders if the current
  spread exceeds this value (in points).
  Example: 350 points = 3.5 pips on a 5-digit broker.
  -> This protects you from placing orders during wide-spread
     moments such as market open or news releases.
  -> Lower this if your broker normally has very tight spreads.

Close new trades if spread is too high (InpMaxSpreadAtFill)
  Default: 120
  If a pending order fills while the spread is above this level,
  the newly opened position is closed immediately.
  This handles cases where a spread spike triggers a pending order
  at an unfavorable price.
  Example: 120 points = 1.2 pips.
  -> Set to 0 to disable this feature.

Extra room before entry (InpBreakoutBufferAtr)
  Default: 0.08
  The entry price is placed slightly above (for buy) or below
  (for sell) the pivot level to confirm a real breakout.
  This buffer is calculated as a fraction of the ATR.
  -> Do not change this. It is calibrated to the strategy.

Add more room when spread is wide (InpBreakoutBufferSpreadMult)
  Default: 1.2
  When the spread is wide, the entry buffer is automatically
  increased by this multiplier to account for the wider spread.
  -> Do not change this.


--- CUSTOM SL TP TRAILING BY POINTS ---

These five settings let you override ATR-based calculations
with fixed point values. Set any value to 0 to use the ATR
method instead (default for all is 0 = use ATR).

Custom stop loss in points (InpCustomSlPoints)
  Default: 0 (use ATR)
  Set a fixed SL distance in points instead of ATR x multiplier.
  Example: 500 = SL of 500 points (50 pips on 5-digit broker).

Custom take profit in points (InpCustomTpPoints)
  Default: 0 (use ATR)
  Set a fixed TP distance in points instead of ATR x multiplier.

Custom trailing start in points (InpCustomTrailStartPoints)
  Default: 0 (use ATR)
  Fixed profit distance in points before trailing activates.

Custom trailing distance in points (InpCustomTrailDistPoints)
  Default: 0 (use ATR)
  Fixed distance in points that the trail keeps behind price.

Custom trailing step in points (InpCustomTrailStepPoints)
  Default: 0 (use ATR)
  Minimum price advance in points before the trail moves.

-> Leave all at 0 unless you want full manual control over
   exact point values. Mixing ATR and custom values (some 0,
   some not) is supported - each setting is independent.


--- NEWS FILTER ---

Enable News Filter (InpUseNewsFilter)
  Default: false
  When ON, the EA reads the MQL5 economic calendar and pauses
  all new order placement around high-impact news events.
  -> Recommended for prop firm accounts.
  -> Requires an active internet connection to the calendar.

Pause Before News - minutes (InpNewsMinutesBefore)
  Default: 30
  How many minutes before a news event the EA stops placing
  new orders and optionally closes existing ones.

Resume After News - minutes (InpNewsMinutesAfter)
  Default: 30
  How many minutes after a news event the EA resumes normal
  operation.

High impact only (InpNewsHighImpactOnly)
  Default: true
  When ON: only HIGH impact events trigger the filter.
  When OFF: both MEDIUM and HIGH impact events trigger it.
  -> Leave ON to avoid too many unnecessary pauses.

Calendar look-ahead window (InpNewsLookAheadHours)
  Default: 36
  How many hours ahead the EA scans the calendar for
  upcoming news events. Leave at default.

Calendar refresh interval (InpNewsRefreshSeconds)
  Default: 60
  How often (in seconds) the EA refreshes the news calendar.
  Leave at default.

Currencies to monitor (InpNewsCurrenciesOverride)
  Default: "USD"
  Which currency news to watch. For XAUUSD, USD is the
  most relevant. Leave as USD unless you want to add more.
  You can enter multiple currencies: "USD,XAU"

Block trading if calendar cannot be read (InpNewsBlockOnCalendarError)
  Default: false
  When ON, if the calendar fails to load, the EA stops trading
  entirely as a safety measure. Conservative option for prop firms.

Delete EA pending orders during news window (InpNewsClosePendingOrders)
  Default: false
  When ON, all pending orders placed by this EA are cancelled
  when a news blackout window begins. They will be re-placed
  after the window ends at the next scan.

Close EA open positions during news window (InpNewsClosePositions)
  Default: false
  When ON, any open positions are closed when a news blackout
  begins. Use with caution - this forces market exits.


--- SCHEDULE (GMT) ---

Daily scan hour (InpScanHourGMT)
  Default: 1
  The hour (GMT) at which the EA runs its daily scan to identify
  key levels and place pending orders for the session.
  At default 1 AM GMT, orders are placed before London open.
  -> On live accounts GMT is detected automatically.
  -> Do not change unless your broker session hours are unusual.

Hour to clear orders Mon-Thu (InpCleanHourWD)
  Default: 21
  At this hour (GMT), all remaining pending orders are cancelled
  for Monday through Thursday. Default 21:00 GMT = just before
  New York close on most standard brokers.

Minute to clear orders Mon-Thu (InpCleanMinWD)
  Default: 55
  Combined with the hour above: cleanup runs at 21:55 GMT.

Hour to clear orders on Friday (InpCleanHourFri)
  Default: 18
  On Friday, cleanup runs earlier to avoid weekend exposure.
  Default 18:00 GMT = well before market close.

Minute to clear orders on Friday (InpCleanMinFri)
  Default: 55
  Combined with the Friday hour: cleanup runs at 18:55 GMT Friday.

GMT offset in winter - Backtest Only (InpBacktestGmtOffsetWinter)
  Default: 2
  ONLY used during backtesting. Set this to match your broker's
  GMT offset in winter (non-DST period).
  Most standard brokers: GMT+2 in winter.
  -> Has NO effect on live accounts.

GMT offset in summer - Backtest Only (InpBacktestGmtOffsetSummer)
  Default: 3
  ONLY used during backtesting. Set this to match your broker's
  GMT offset in summer (DST period).
  Most standard brokers: GMT+3 in summer.
  -> Has NO effect on live accounts.


--- STRATEGY MODE ---

Choose how the EA enters trades (InpStrategyMode)
  Default: Strategy 1

  STRATEGY 1 - Trend Following (Recommended for live accounts)
  The EA only places Buy Stop orders when the H4 trend is up,
  and only Sell Stop orders when the H4 trend is down.
  Additionally, it refines each entry using the M5 timeframe
  for a more precise trigger point.
  Result: fewer trades, higher quality setups.

  STRATEGY 2 - High Frequency
  No trend filter. Trades both Buy and Sell stops regardless
  of H4 direction. No M5 refinement step.
  Result: more trades, wider range of market conditions covered.

  -> Start with Strategy 1 for any live or prop firm account.
  -> Strategy 2 is useful for backtesting and research.

Open second order at the same price (InpEnableTrade2)
  Default: false
  When ON, the EA places a second order at every pivot level
  alongside the main order. The second order uses a wider
  SL and TP defined by InpTrade2Scale.
  -> Use this to scale into winning trades.

Open third order at the same price (InpEnableTrade3)
  Default: false
  When ON, a third order is also placed at each level,
  using an even wider SL and TP from InpTrade3Scale.
  -> Only enable if you understand the increased risk exposure.

SL/TP scale for second order (InpTrade2Scale)
  Default: 1.3
  The second order's SL and TP are multiplied by this factor.
  At 1.3, the second order has 30% wider SL and TP than the main.
  -> Wider TP = this order targets a bigger move.
  -> Wider SL = this order is more tolerant of volatility.

SL/TP scale for third order (InpTrade3Scale)
  Default: 1.5
  Same as above but for the third order. At 1.5, the third
  order has 50% wider SL and TP than the main order.


--- AI SCORER ---

Use trade quality filter (InpUseScorer)
  Default: false
  When ON, the AI scoring engine filters pivot levels before
  placing orders. Each level is scored 0-100 based on multiple
  quality factors. Levels below 40 are skipped entirely.
  Levels scoring 40-60 are taken at half lot size.
  Levels scoring above 60 get the full calculated lot size.
  -> Enabling this reduces trade count but improves average
     quality. Recommended if you want fewer, higher-conviction trades.
  -> Leave OFF to trade all valid pivots found each scan.


--- GENERAL ---

Unique number for this EA (InpMagicNumber)
  Default: 202601
  A unique identifier attached to every order this EA places.
  This allows the EA to manage only its own orders and ignore
  orders placed manually or by other EAs on the same account.
  -> If you run multiple instances of this EA simultaneously,
     give each one a different magic number.
  -> Do not change this mid-session as the EA will lose track
     of existing orders.

Note added to each trade (InpTradeComment)
  Default: "AI Gold Oni"
  The comment text attached to every order in your trade history.
  -> You can change this to any label you prefer.
  -> Do not leave it blank.


================================================================
RECOMMENDED SETTINGS BY ACCOUNT TYPE
================================================================

Personal account (standard):
  InpUseRiskPct       = true
  InpRiskPercent      = 1.0 to 2.0
  InpStrategyMode     = Strategy 1
  InpUseScorer        = false
  InpUseNewsFilter    = false

Prop firm challenge:
  InpUseRiskPct       = true
  InpRiskPercent      = 0.2 to 0.5
  InpStrategyMode     = Strategy 1
  InpUseScorer        = true  (optional, reduces trade count)
  InpUseNewsFilter    = true
  InpNewsClosePendingOrders = true

High frequency / research:
  InpStrategyMode     = Strategy 2
  InpUseScorer        = false


================================================================
FREQUENTLY ASKED QUESTIONS
================================================================

Q: Which chart do I attach the EA to?
A: XAUUSD, M5 timeframe. Only one chart needed.

Q: Does it trade other pairs?
A: No. AI Gold Oni is built specifically for XAUUSD only.

Q: Do I need to configure the timezone?
A: No. On live accounts the EA reads GMT time automatically.
   Timezone settings (InpBacktestGmtOffsetWinter/Summer) only
   apply during backtesting.

Q: How many trades does it place per day?
A: Strategy 1 typically places 1 to 5 pending orders per day,
   of which only some will trigger. Strategy 2 places more.
   Actual fills depend on whether price reaches the levels.

Q: When are orders placed?
A: Once per day after 1 AM GMT (configurable via InpScanHourGMT).
   New levels can also be detected intraday on each M15 bar close.

Q: When are pending orders cancelled?
A: Mon-Thu at 21:55 GMT. Friday at 18:55 GMT.
   All unfilled orders from that day are removed automatically.

Q: Can I run it on a VPS?
A: Yes. Any standard Windows VPS with MetaTrader 5 will work.
   Recommended: 1GB RAM minimum, stable internet connection.

Q: Can I use it with multiple accounts at the same time?
A: Yes. Use a different InpMagicNumber for each instance to
   avoid conflicts.

Q: The EA is not placing orders. What is wrong?
A: Check the following in order:
   1. Is automated trading enabled in MetaTrader 5?
   2. Is the spread below InpMaxSpreadPoints?
   3. Has the daily scan already run today? (Check the log tab)
   4. Is the current time past InpScanHourGMT (1 AM GMT)?
   5. If using Strategy 1, is the H4 trend defined?
      (Both buy and sell stops will be filtered if trend is flat)

Q: Can I change settings while the EA is running?
A: Most settings can be changed live. However, changing
   InpMagicNumber mid-session will cause the EA to lose track
   of existing pending orders - avoid this.

================================================================