# Options Alert Bot — Client User Guide (Live System)

**Live URL:** https://garydsnakee.com  
**Client Guide (on site):** https://garydsnakee.com/client-guide  
**Status:** System is operational and ready for each U.S. trading day, provided you complete the **daily watchlist save** routine below.

---

## Short message you can send to your team (copy/paste)

> The trading dashboard is live at **garydsnakee.com**.  
> Every **trading morning (U.S. Eastern time)**, open **Watchlist**, enter today’s **Regular A+** tickers and **Fast News** tickers (they can be different), and click **Save today’s lists**. Without that save, the server uses old default tickers.  
> **Regular A+** = slower, high-quality setups — **Telegram alert only**; you enter the trade in your broker, then **confirm the fill on the Dashboard** so P/L and exits track correctly. **No A+ auto-orders.**  
> **Fast News** = breaking headlines — scans every ~30 seconds. When **Fast News Auto-Trading** is **ON** in **Settings** (with confirmation), the system may place **Tradier sandbox** option orders automatically after all guardrails pass; you still see the same trade on the **Dashboard Live Monitor** and **Telegram** at the same time.  
> Use **Dashboard** for live positions, P/L, and alerts; **Alerts Log** for full history; **Reports** for paper ledger and CSV export; **System Guide** on the site for full technical reference.

---

## 1. Two engines (never mix them)

| | **Regular A+** | **Fast News** |
|---|----------------|---------------|
| **Purpose** | Confirmed intraday setups (VWAP, opening range, volume, sector, options flow, AI score) | Speed on breaking news (geopolitical, macro, sector shocks, etc.) |
| **How you trade** | **Manual only** — Telegram alert → you trade in your broker → confirm fill on website | Optional **auto** via Tradier when enabled in Settings |
| **Scan frequency** | Every **3 minutes** (market hours) | Every **~30 seconds** (market hours) |
| **Typical hold** | Intraday (trim/target rules on paper-tracked position) | Minutes (time stop, trim, stop on premium) |
| **Max new entries/day (default)** | 2 ENTRY alerts | 1 auto entry (configurable on server) |

Fast News does **not** use A+ confirmation logic. A+ does **not** auto-submit broker orders.

---

## 2. Your daily morning routine (required)

**When:** Before or at the start of the U.S. session (all dates use **America/New_York / Eastern Time**).

**Steps:**

1. Go to **Watchlist** (sidebar).
2. In the orange card **“Today’s Watchlists”**:
   - **Regular A+ tickers** — comma- or space-separated symbols (e.g. `USO, XLE, SPY, QQQ`).
   - **Fast News tickers** — can be a **different** list (e.g. `USO, XLE, SMH, QQQ`).
3. Click **Save today’s lists**.
4. Confirm on screen:
   - Green success message.
   - **Source: Saved for today** (not “.env default”).
5. Optional: refresh the page — text boxes and chips below should match what you saved.

**Important rules:**

- Only **today’s** saved list is scanned. **Yesterday’s list is never used** after the ET calendar date changes.
- If you **do not** save, the server falls back to old default tickers from server config — not your intended day list.
- Ticker symbols must be **1–6 letters A–Z only** (e.g. `USO` works; test symbols with numbers are ignored).

**Example (current production save):**

- A+: USO, XLE, SPY, QQQ  
- Fast News: USO, XLE, SMH, QQQ  

---

## 3. Dashboard — what you see and what to do

Open **Dashboard** (home page after login).

### Top KPI row

| Card | Meaning |
|------|---------|
| **Regular A+ Alerts** | How many A+ alerts today; link to A+ Alerts Log |
| **Fast News** | Decisions today; executions count; **Auto ON/OFF** status |
| **Active Positions** | Open trades shown in Live Monitor below |
| **Kill Switch** | Manual or P/L-based stop for **new** entries; link to Settings |

### Second row — P/L today

- **A+ P/L Today** — closed A+ trades you confirmed on the site  
- **Fast News P/L Today** — closed auto/paper Fast News exits  
- **Combined P/L Today** — both engines  

### Paper Trading Ledger

- **$100,000** paper account model (sandbox tracking).  
- Shows **today net**, **open unrealized**, **week-to-date (WTD)**, and **50% protected / 50% reinvest** split.  
- Numbers come from **real logged trades** on the server — not a copy of an external ChatGPT report unless you import that separately.

### Confirm Manual A+ Fills (when visible)

When A+ sends you a Telegram entry and you **actually buy** in your broker:

1. This yellow panel appears on the Dashboard.  
2. Enter **fill premium** and **contracts**.  
3. Click **Confirm fill** — now the system monitors trim/exit for that position.  
4. Or **Skip — did not trade** if you ignored the alert.

**A+ never places broker orders for you.** Confirmation on the website is how the system tracks your manual trade.

### Live Monitor — Fast News + A+ Options

- Table of **open positions** with live **bid / ask / mid / spread / P/L**.  
- Refreshes every ~1–2 seconds via Tradier (option quotes).  
- Status chips: **Stream Cache Live** (faster underlying feed on server) or **Tradier Rest**.  
- **Premium Replay** button on rows — shows option premium snapshots around news/entry (for review and learning).

### Alert feed tabs (on Dashboard)

- Separate previews for **Regular A+** vs **Fast News**.  
- Paginated; click through pages without losing live quotes.  
- Telegram preview per row where applicable.

### Quick links

- **Reports & P/L** — deeper performance and CSV.  
- **Logic Manager** — view/edit scoring logic (advanced).

---

## 4. Regular A+ — how it works (step by step)

1. **Morning:** You save **Regular A+ tickers** on the Watchlist page.  
2. **During market hours (9:30 AM – 3:55 PM ET, weekdays):**  
   Server runs `options:scan-watchlist` every **3 minutes** on **only today’s A+ list**.  
3. For each ticker the engine checks (among others):  
   - Price vs VWAP  
   - Opening range break (default 15-minute range)  
   - Relative volume, options flow, sector alignment  
   - OpenAI score (minimum ~8 to proceed; “A+ ENTRY CONFIRMED” label at ~10)  
   - Weighted composite score (minimum ~85)  
   - Option spread within cap (~8%)  
4. If passed → **Telegram manual alert** with contract, suggested limits, trim/target/stop hints.  
5. **You** place the trade in **your broker** (not on this website).  
6. **You** return to **Dashboard → Confirm Manual A+ Fills** and enter actual fill price.  
7. **Monitor:** `options:monitor-positions` sends **TRIM / EXIT** Telegram alerts based on premium rules (e.g. trim ~+30%, target ~+50%, stop ~−20%).  
8. **Max A+ ENTRY alerts per day:** default **2**.

**There is no A+ auto-trade switch.** Settings will always show A+ as manual-only.

---

## 5. Fast News — how it works and what “Auto” means

### Always running (when market is open)

- Ingests headlines (e.g. Benzinga) for **today’s Fast News watchlist**.  
- Scores severity, checks duplicates, maps theme to tickers, checks underlying reaction, option liquidity, spread, latency.  
- Logs **ENTER** or **REJECT** decisions.  
- Sends **Telegram** for entries, reviews, and rejects (depending on outcome).  
- Good setups appear on **Dashboard Live Monitor** in line with Telegram timing.

### Fast News Auto-Trading (Settings)

Go to **Settings → Client Trading Controls:**

| Control | Effect |
|---------|--------|
| **Fast News Auto-Trading OFF** (default safe mode) | Full analysis + Telegram + dashboard logging; **no** Tradier orders |
| **Fast News Auto-Trading ON** | After AI + all code guardrails pass, system may submit **Tradier option orders** (sandbox or live per server config) |
| **Confirmation checkbox** | Required when turning auto ON — intentional safety |
| **Manual Kill Switch ON** | Blocks **all** new Fast News orders and new A+ entries, even if auto looks ON |
| **Daily P/L kill** | Auto-stops new risk if realized loss exceeds server limit (default ~$200) |

**When auto is ON and a trade is taken:**

1. Order goes to Tradier (sandbox unless admin enabled live).  
2. **Telegram: FAST NEWS AUTO ENTRY** (or review message if rejected).  
3. **Dashboard Live Monitor** shows the open option position with live quotes.  
4. **Exits:** `fast-news:monitor-exits` every minute — trim levels, stops, time stop (~5 min), etc.  
5. **Limits (defaults):** max **1** new auto entry per day; max **2** open Fast News positions; spread and **30-second** decision latency rules apply.

**Speed note:** Fast News runs every **30 seconds** on the server scheduler — fast for a rules+AI system, but not HFT microsecond trading.

---

## 6. Other pages (sidebar)

### System Guide

Complete in-app reference: engines, cron schedule, WebSocket stream, risk limits, troubleshooting. **Read this first** if you want technical depth without asking support.

### Alerts Log

- Full history for **both** engines.  
- Filter by engine (A+ / Fast News).  
- ENTRY / TRIM / EXIT / decisions.  
- Telegram message preview; Premium Replay where available.

### Watchlist

- **Daily save** (required routine above).  
- Sector map table (ticker → sector ETF).  
- **Stock Candles** chart — 1m/5m underlying OHLC for watchlist symbols (same data family as scanners).

### Tools (operator)

- **Telegram test** — ping your chat.  
- **Dry scan** — A+ watchlist scan with **no** DB writes / no Telegram.  
- **Fast News dry run** — pipeline test **no** orders.  
- **System health** — APIs, DB, Tradier, controls.  
- **ChatGPT import** — optional: import an external report snapshot for display/reference (does **not** auto-clone live market trades).  
- **Load client example** — **demo only**; do not use on production for real trading days.

### Reports & Integrations

- Same **Paper Trading Ledger** as dashboard.  
- **A+ / Fast News P/L** today and 30-day.  
- **Download client CSV** — end-of-day export (39 columns: premiums, latency, P/L, etc.).  
- Integration status (Tradier, news APIs, etc.).

### Logic Manager

- View and propose changes to scoring/logic JSON used by engines.  
- For advanced users; changes go through approval workflow on server.

### AI Lab

- Upload client logic JSON; test OpenAI Q&A.  
- Does not replace live engine runs.

### Settings

- **Fast News Auto** + kill switch (see section 5).  
- API key **presence** indicators (secrets stay in server `.env` only).

---

## 7. Telegram — what you should expect

Messages go to the chat ID configured on the server (your personal or group chat).

| Message type | When |
|--------------|------|
| **REGULAR A+ MANUAL ALERT** | A+ setup passed — you trade manually |
| **FAST NEWS AUTO ENTRY** | Auto ON and order placed |
| **FAST NEWS REVIEW** | Headline processed but rejected or not eligible |
| **TRIM / EXIT** | Open position hit monitor rules |
| **WAIT** | Optional choppy-market notice from scan |

**Test:** Tools → Send Test Telegram, or Diagnose Telegram.

When a Fast News trade is **good and auto-eligible**, you should see it on **Telegram and Dashboard Live Monitor together** (same decision cycle).

---

## 8. What runs automatically on the server (you do not click these)

Your host must run **every minute**:

```text
* * * * * cd /var/www/html/tradding_app && php artisan schedule:run
```

During **U.S. market hours (weekdays, Eastern Time)**, this triggers roughly:

| Job | Frequency | Role |
|-----|-----------|------|
| `fast-news:run` | Every 30 sec | Fast News scan + optional auto entry |
| `options:scan-watchlist` | Every 3 min | Regular A+ scan |
| `options:monitor-positions` | Every 1 min | A+ trim/exit alerts |
| `fast-news:monitor-exits` | Every 1 min | Fast News auto exits |
| `trading:collect-reactions` | Every 1 min | Price snapshots for learning |
| `trading:sync-executions` | Every 1 min | Tradier fill sync |
| `tracking:capture-positions` | Every 1 min | Position premium tracking |
| EOD jobs (~4:30–5:20 PM ET) | Daily | Learning retrain, missed review, CSV export |

A separate long-running process **`market:stream`** (Supervisor) feeds faster underlying prices into scans when enabled.

**Outside market hours:** cron may still run, but most trading jobs do nothing — normal.

---

## 9. What is ready vs what is not automatic

### Ready now

- Live website, two separate engines, daily watchlist UI + database save.  
- Dashboard live monitor, P/L split, paper ledger, alerts log, reports CSV.  
- Fast News pipeline with latency/premium guardrails.  
- A+ manual Telegram + website fill confirmation.  
- Premium replay on monitor/alerts.  
- Learning database and end-of-day export.

### Not automatic (by design)

- **Copying a ChatGPT P/L screenshot** line-for-line — use **Reports → ChatGPT import** or trade/log naturally.  
- **A+ broker execution** — always your broker + website fill confirm.  
- **Saving watchlist** — you must click Save each trading day.  
- **Sub-second HFT** — PHP scheduler limits; system targets disciplined speed, not exchange colocation.

---

## 10. Quick troubleshooting

| Problem | What to do |
|---------|------------|
| Wrong tickers scanned | Watchlist → **Save today’s lists** → confirm **Saved for today** |
| No Telegram | Tools → Diagnose Telegram; check kill switch OFF |
| Fast News 0 executions | Auto OFF is normal; decisions still log; turn auto ON only if you want sandbox orders |
| A+ alert but no P/L tracking | Dashboard → **Confirm fill** after broker trade |
| No alerts at all | Market hours ET? Kill switch? Server cron running? |
| Stale option quotes | Check Tradier token; refresh dashboard |
| **`pending_price_sync` on premarket/FN** | **Normal in sandbox** — delayed Tradier quotes vs news; system waits for aligned data (up to ~7 min skew). Not a VWAP reject. Check Dashboard **Sync pending** tab. |
| Misleading `reject_vwap` Telegram | Should not fire while status is `pending_price_sync` — update code if you still see this |
| “Stream Live” off | Server `market:stream` process — contact admin |

---

## 11. Recommended daily checklist

- [ ] **Watchlist** — update A+ and Fast News lists → **Save today’s lists**  
- [ ] **Settings** — Fast News Auto ON/OFF as you intend; kill switch OFF unless stopping day  
- [ ] **Dashboard** — Active positions and Auto status look correct  
- [ ] **Telegram** — test ping if you changed phones/chats  
- [ ] After A+ Telegram entry you took — **Confirm fill** on Dashboard  
- [ ] End of day — **Reports** for P/L; optional CSV download  

---

## 12. Support reference

- **Client Guide (recommended):** https://garydsnakee.com/client-guide — same content as this document, readable in the browser; use **Download .md** on that page for offline copy  
- **Technical reference:** System Guide on https://garydsnakee.com/system-guide  
- **Source file (developers):** `docs/CLIENT_USER_GUIDE.md` in the project repository  
- **Timezone:** All “today” and session windows = **U.S. Eastern (ET/EDT)**  

---

## 13. Sync guard statuses (sandbox)

When Tradier sandbox quotes or candles lag behind Benzinga news timestamps, the system uses **`pending_price_sync`** instead of an immediate **`reject_vwap`**. This prevents false rejects on setups like TSM/AVGO when data is delayed ~5–7 minutes.

| Status | Meaning |
|--------|---------|
| `pending_price_sync` | News/quote/candle timestamps not aligned yet — keep watching |
| `pending_vwap_confirmation` | Data synced; VWAP not confirmed yet (FN: up to 180s window) |
| `reject_vwap_confirmed` | Synced data + VWAP failed after confirmation window |
| `reject_stale_data` | Data too old after full sync tolerance |

**Morning paste:** Save the client **Premarket A+ Alert List** on **Watchlist** once — cron at **7:15** and **8:00 ET** auto-loads the stored paste for `premarket:start-day`.

---

*Document version: aligned with production deploy June 2026 — sync guard + daily watchlist via UI/DB.*