Upload folder using huggingface_hub

docs/dashboard.md

@@ -1,5 +1,185 @@
 ![OddsFlow Dashboard (Premier League example)](assets/dashboard-epl.jpg)
 
+---
+
+## Click Map (Jump to a section in 3 seconds)
+
+**Start here:**  
+- [30-second reading](#30-second-reading)  
+- [Key idea: Market vs Model](#key-idea-market-vs-model)
+
+**The 3 dashboard blocks:**  
+- [A) Probability Analysis (Left)](#a-probability-analysis-left)  
+- [B) Market Trends (Center)](#b-market-trends-center)  
+- [C) Value Detection (Right)](#c-value-detection-right)
+
+**Context + verification:**  
+- [Why league tabs matter](#why-league-tabs-matter)  
+- [Verification-first workflow](#verification-first-workflow-recommended)  
+- [Limitations](#limitations-read-this)
+
+---
+
+## 30-second reading
+
+1) Choose a league tab (EPL / LaLiga / Serie A / Bundesliga / Ligue 1 / UCL)  
+2) Read **Market Trends** first (league “weather”)  
+3) Check **Probability Analysis** (Market vs Model)  
+4) Open **Value Detection** only after context  
+5) Verify post-match (logs + timestamps)
+
+**Principle:** No hype. Just logs.
+
+---
+
+## Key idea: Market vs Model
+
+- **Market** = probability implied by bookmaker pricing (odds/lines)  
+- **Model** = AI-estimated probability  
+- **Edge** = meaningful disagreement between Model and Market (above threshold)
+
+If you want term definitions:
+- UI terms → [`dashboard-glossary.md`](./dashboard-glossary.md)  
+- Log/schema terms → [`signal-glossary.md`](./signal-glossary.md)
+
+---
+
+## A) Probability Analysis (Left)
+
+**Question it answers:**  
+“What does the AI estimate vs what does the market price?”
+
+**What you see:**  
+Semi-circular gauges for selected outcomes (e.g., Over 2.5, Draw) showing:
+- **Market** (implied probability)
+- **Model** (AI probability)
+
+**How to interpret:**  
+- Model > Market → AI thinks it’s more likely than priced  
+- Model < Market → AI thinks it’s less likely than priced
+
+---
+
+## B) Market Trends (Center)
+
+**Question it answers:**  
+“What is the league environment right now vs market expectations?”
+
+### B1) Market Volatility / Deviation
+A drift meter between:
+- **Implied** (market expected rate)
+- **Actual** (observed rate in sample window)
+- **Deviation** (Actual − Implied)
+
+Positive deviation → happening more than priced  
+Negative deviation → happening less than priced
+
+### B2) Home Advantage / awayLean
+Shows whether home teams are over/under performing vs market assumptions in the current window.
+awayLean indicates whether the league is leaning away relative to market assumptions.
+
+---
+
+## C) Value Detection (Right)
+
+**Question it answers:**  
+“Which matches show meaningful mispricing after filters?”
+
+Common elements:
+- **Edge Found** = number of candidates where Model vs Market exceeds threshold  
+- **Filtered** = candidates remaining after applying filters  
+- **Efficiency** = quality indicator for the current shortlist (implementation-specific)
+
+Use this as a **research shortlist**, then verify via logs.
+
+---
+
+## Why league tabs matter
+
+Leagues differ in:
+- scoring distribution / tempo  
+- home advantage strength  
+- market bias patterns  
+
+So a rule that feels true in one league can fail in another.
+OddsFlow makes league context explicit before interpreting edge.
+
+---
+
+## Verification-first workflow (recommended)
+
+1) Read league context (Market Trends)  
+2) Inspect shortlist (Value Detection)  
+3) Verify using:
+- [`verification.md`](./verification.md)
+- [`signal-glossary.md`](./signal-glossary.md)
+
+---
+
+## Limitations (read this)
+
+- Edge is a pricing disagreement, not certainty  
+- Markets reprice quickly (snapshots ≠ closing line)  
+- Sample window size affects drift indicators  
+- Injuries/rotation/news can change dynamics  
+
+---
+
+## FAQ (Common misunderstandings)
+
+### 1) Does “Edge Found 20” mean 20 guaranteed wins?
+No.  
+**Edge Found** only means: under the current league view, sample window, and filters, the system detected **20 candidates** where **Model vs Market** disagreement exceeds a threshold.  
+It is **not** a profit promise and **not** “sure wins.”  
+Correct use: treat it as a **research shortlist** → check league context → verify via logs and post-match audit.
+
+---
+
+### 2) If Model > Market, should I always follow the Model?
+Not always.  
+A Model–Market gap is a **mispricing hypothesis**, not certainty. Markets can reprice quickly due to injuries, rotation, news, and line movement.  
+Correct use: look for **consistency**, confirm it matches the league “weather” (Trends), and validate using **closing line / post-match audit**.
+
+---
+
+### 3) Does Market Volatility mean “more volatility = easier profit”?
+No.  
+On this dashboard, **Market Volatility / Deviation** is a **drift indicator**: how much recent outcomes differ from what the market implied.  
+A larger drift can reflect market adjustment, changing conditions, or sample effects. It does **not** automatically mean “more profit.”
+
+---
+
+### 4) Does awayLean mean “always back the away team”?
+No.  
+**awayLean** indicates a **league-level drift** in the current sample window (home outcomes under/over performing market assumptions).  
+It is **context**, not a fixed strategy. Team strength, schedule difficulty, tactics, and injuries still dominate single-match reality.
+
+---
+
+### 5) Is this dashboard a “score prediction” tool?
+No.  
+This dashboard is primarily about:
+1) estimating probabilities (Model)  
+2) comparing against market pricing (Market)  
+3) generating a verifiable shortlist of candidates (Value Detection)
+
+**Brand standard:** not tips, no guarantees — auditability first.  
+See: `verification.md` and `signal-glossary.md`.
+
+### 6) Does “Efficiency = 100%” mean “accuracy = 100%”?
+No.  
+**Efficiency** is a **dashboard quality indicator for the current filtered shortlist** (implementation-specific).  
+It typically reflects things like **filter consistency, data completeness, or rule pass-rate** for the candidates shown — not match outcomes.
+
+It does **not** mean:
+- 100% win rate
+- 100% prediction accuracy
+- guaranteed profit
+
+Correct use: treat Efficiency as “the shortlist is clean under current rules,” then rely on **verification logs** and **post-match audit** for actual performance evaluation.
+
+---
+
 
 # OddsFlow Football League Dashboard: AI vs Bookmakers