> **v5 upgrade:** the main UI and unified MT5_Intelligence_Observer supersede the separate Prediction Lab setup below. Follow ANALYTICS_SETUP.md. Legacy research endpoints remain available for compatibility.

# News and economic-event upgrade

This release adds scheduled-event protection and a headline reader. It does not infer trade direction from headlines, read full articles, perform fundamental valuation, or claim validated news sentiment. Existing EMA/structure analysis continues unchanged.

## Enable it

1. Keep live execution disabled while upgrading. Deploy the whole package, including `api/news.py` and `engine/news.py`.
2. Set server variables from `.env.example`: `NEWS_GATE_MODE=block`, `NEWS_BEFORE_MINUTES=30`, `NEWS_AFTER_MINUTES=15`. Redeploy. `warn` displays warnings without blocking; `off` disables the calendar execution gate. Unset mode defaults to off for compatibility, so **existing installations must explicitly set block**.
3. Recompile the updated `MT5_Prediction_Observer.mq5` (v1.10) and replace the observer on the second chart. Keep the main trade bridge on its original chart. Use matching account, bridge ID and token. Set `EnableNewsObserver=true`, `ObserverSeconds=15`, `NewsSeconds=60`, `NewsTimeoutMilliseconds=20000`. The existing HTTPS WebRequest allowlist entry is reused. No additional DLL is required.
4. Check that MT5's economic calendar is accessible. Compare several event timestamps against a trusted UTC schedule before enabling execution. Calendar failures or partial retrieval are reported as unhealthy, not an empty calendar.
5. Supply up to three HTTPS RSS/Atom feed URLs in `NEWS_RSS_URLS`, comma-separated. Choose feeds whose terms permit your intended use. No subscription, provider account or feed entitlement has been purchased/configured. Redirects are rejected; use the final feed URL. Only administrator-controlled public endpoints should be configured. URLs with embedded credentials are rejected; query-string secrets, if required by a provider, stay in server configuration. URL queries and raw provider errors are not returned to the client.
6. Connect the terminal. The news panel displays calendar freshness, gate mode, event times in UTC, feed status, source links, publication times and approximate affected assets. Live API snapshots carry per-symbol gate reasons; execution checks the gate again server-side.

## Behaviour

- Calendar collection approximately every 60 seconds on the VPS, even with browser closed. A slow research request can delay the observer; it runs separately from the trading EA. No new scheduler service is required.
- Reads events from the beginning of the server day minus three hours through the next 24 hours. Includes tentative/all-day events, conservatively covering their supplied server day.
- Blocks new entries for relevant **high-impact** releases from 30 minutes before through 15 minutes after (inclusive), by default. It does not close or modify existing positions.
- Calendar data older than 180 seconds, future timestamps or insufficient coverage block new entries in block mode. The original 15-second market telemetry watchdog remains separate.
- Checks occur at API enqueue and command dispatch. News arriving after dispatch cannot recall an in-flight broker request. No protection against all unscheduled geopolitical or corporate headlines is implied.
- Forex uses both currencies. US indices, metals, oil and Bitcoin use USD macro exposure; GER40 uses EUR and UK100 uses GBP. This is an explicit limited mapping, not a complete global event-impact model.
- The MT5 calendar uses **trade-server time**, not UTC. The observer estimates the current server offset from TimeTradeServer minus TimeGMT, rounded to 15 minutes, and rejects deviations greater than 10 seconds. Windows clock synchronization is essential. Current offset is applied across the query; future events across a broker DST change can be displaced until refresh after the change. Verify broker clock/DST behaviour in demo commissioning. Official reference: https://www.mql5.com/en/docs/calendar/calendarvaluehistory
- Calendar writes are monotonic and atomic; delayed older packets cannot overwrite a newer snapshot. Storage is isolated from the order ledger.
- RSS/Atom refresh is throttled to five minutes; up to 60 distinct links from the past 48 hours are retained, with the newest 20 shown. Undated, future-dated and unsafe-link entries are excluded. Feed failure does not disable the calendar gate. Partial feed success is labelled. Old successful headlines are not carried forward as fresh after a failed refresh.
- Headline asset tags use explicit keywords and a small macro mapping; they may miss relevant stories or over-associate assets. They do not produce positive/negative sentiment, score boosts or BUY/SELL orders. Full-text summarisation and licensed real-time news APIs remain future extensions.
- The Prediction Lab still evaluates its original **technical-only** paper policy. Its eligibility label does not include the new news gate; its results must not be interpreted as performance of the combined news-filtered strategy.

## Demo acceptance

Verify an actual scheduled event blocks the relevant symbol and leaves unrelated currencies eligible; test both window boundaries and warn/off modes. Stop the observer while leaving the main bridge running: after 180 seconds, block mode must reject new entries. Restart and verify recovery. Check duplicate packets, invalid timestamps, unavailable feeds and unsafe links. Compare timestamps around broker DST transitions. Verify news failures do not interfere with existing position management in MT5.

Automated Python and frontend tests use synthetic calendars/feeds. MetaEditor compilation, broker calendar availability, live feed ingestion, real Redis Lua execution and deployed cloud operation remain unverified. No actual trade was placed.