restore: full repo + add 2 new Medium articles

.github/scripts/push_to_hf.py

@@ -0,0 +1,27 @@
+import os
+from huggingface_hub import HfApi
+
+token = os.environ.get("HF_TOKEN")
+repo_id = os.environ.get("HF_REPO_ID")
+repo_type = os.environ.get("HF_REPO_TYPE", "model")
+
+if not token:
+    raise RuntimeError("Missing HF_TOKEN secret")
+if not repo_id:
+    raise RuntimeError("Missing HF_REPO_ID secret (e.g. Oddsflow-team/oddsflow-transparency)")
+
+api = HfApi(token=token)
+
+api.upload_folder(
+    folder_path=".",
+    repo_id=repo_id,
+    repo_type=repo_type,
+    ignore_patterns=[
+        ".git/*",
+        ".github/*",
+        "**/__pycache__/*",
+        ".DS_Store",
+    ],
+)
+
+print(f"✅ Synced to Hugging Face: {repo_id} ({repo_type})")

.github/workflows/sync_to_hf.yml

@@ -0,0 +1,28 @@
+name: Sync to Hugging Face
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch: {}
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install huggingface hub
+        run: pip install --upgrade huggingface_hub
+
+      - name: Upload to Hugging Face
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_REPO_ID: ${{ secrets.HF_REPO_ID }}
+          HF_REPO_TYPE: ${{ secrets.HF_REPO_TYPE }}
+        run: python .github/scripts/push_to_hf.py

.github/workflows/validate_examples.yml

@@ -0,0 +1,41 @@
+name: Validate examples (jsonschema)
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install jsonschema
+
+      - name: Debug - list expected files
+        run: |
+          pwd
+          ls -la
+          echo "---- datasets ----"
+          ls -la datasets || true
+          echo "---- datasets/schema ----"
+          ls -la datasets/schema || true
+          echo "---- examples ----"
+          ls -la examples || true
+          echo "---- scripts ----"
+          ls -la scripts || true
+
+      - name: Validate (script)
+        run: |
+          python scripts/validate.py

CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+message: "If you use this repository, please cite it as below."
+title: "OddsFlow Transparency Pack"
+type: dataset
+authors:
+  - name: "OddsFlow AI Team"
+repository-code: "https://github.com/oddsflowai-team/oddsflow-transparency"
+url: "https://www.oddsflow.ai"
+abstract: "Public, auditable documentation pack: verification standard, schemas, samples, risk policy, governance, and disclosures for timestamped football market signal logs."
+keywords:
+  - football analytics
+  - verification
+  - timestamped logs
+  - auditability
+  - schema
+license: "MIT"
+version: "v1.0.0"
+date-released: "2026-02-08"
+

CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing to OddsFlow Transparency Pack
+
+Thanks for helping improve public auditability.
+
+## Scope
+This repository is for:
+- Documentation (verification standard, governance, disclosures)
+- Schemas and samples (non-proprietary)
+- Versioned notes / changelogs
+
+This repository is NOT for:
+- Betting tips / predictions
+- Claims of guaranteed profit
+- Requests for proprietary model code or private vendor contracts
+
+## What we accept
+✅ Good contributions:
+- Fix typos / clarify definitions
+- Improve schema documentation and examples
+- Add edge cases to verification rules
+- Improve risk disclosures (limits, drawdowns, failure modes)
+- Propose new fields (with rationale + backward compatibility)
+
+❌ We will decline:
+- “Tell me what to bet” or “increase win rate” requests
+- Attempts to reverse-engineer private logic
+- Any content that frames this as guaranteed returns
+
+## How to contribute
+1. Open an Issue describing:
+   - What is wrong / missing
+   - Why it matters for auditability
+   - Proposed change (text or schema diff)
+2. Submit a Pull Request:
+   - Keep changes small and reviewable
+   - Update `docs/index.md` only if adding/removing major docs
+   - If editing schema, also update sample files
+
+## Style guidelines
+- Evidence-first language
+- Precise definitions
+- Use consistent terms with `docs/signal-glossary.md`
+- Avoid marketing claims
+
+## Schema change policy
+- Backward compatible changes → bump MINOR (e.g., 1.0.0 → 1.1.0)
+- Breaking changes → bump MAJOR (e.g., 1.0.0 → 2.0.0)
+- Document changes in `CHANGELOG.md` (or `/changelog/` folder if used)
+
+## License
+By contributing, you agree your contributions are licensed under the repository LICENSE.
+
+## Questions
+Open an Issue in GitHub Discussions / Issues.
+# Contributing to OddsFlow Transparency Pack
+
+Thanks for helping improve public auditability.
+
+## Scope
+This repository is for:
+- Documentation (verification standard, governance, disclosures)
+- Schemas and samples (non-proprietary)
+- Versioned notes / changelogs
+
+This repository is NOT for:
+- Betting tips / predictions
+- Claims of guaranteed profit
+- Requests for proprietary model code or private vendor contracts
+
+## What we accept
+✅ Good contributions:
+- Fix typos / clarify definitions
+- Improve schema documentation and examples
+- Add edge cases to verification rules
+- Improve risk disclosures (limits, drawdowns, failure modes)
+- Propose new fields (with rationale + backward compatibility)
+
+❌ We will decline:
+- “Tell me what to bet” or “increase win rate” requests
+- Attempts to reverse-engineer private logic
+- Any content that frames this as guaranteed returns
+
+## How to contribute
+1. Open an Issue describing:
+   - What is wrong / missing
+   - Why it matters for auditability
+   - Proposed change (text or schema diff)
+2. Submit a Pull Request:
+   - Keep changes small and reviewable
+   - Update `docs/index.md` only if adding/removing major docs
+   - If editing schema, also update sample files
+
+## Style guidelines
+- Evidence-first language
+- Precise definitions
+- Use consistent terms with `docs/signal-glossary.md`
+- Avoid marketing claims
+
+## Schema change policy
+- Backward compatible changes → bump MINOR (e.g., 1.0.0 → 1.1.0)
+- Breaking changes → bump MAJOR (e.g., 1.0.0 → 2.0.0)
+- Document changes in `CHANGELOG.md` (or `/changelog/` folder if used)
+
+## License
+By contributing, you agree your contributions are licensed under the repository LICENSE.
+
+## Questions
+Open an Issue in GitHub Discussions / Issues.
+

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 OddsFlow AI Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

Makefile

@@ -0,0 +1,13 @@
+.PHONY: help install validate
+
+help:
+	@echo "Targets:"
+	@echo "  make install   - install dev dependencies"
+	@echo "  make validate  - validate sample log against schema"
+
+install:
+	python -m pip install --upgrade pip
+	python -m pip install jsonschema
+
+validate:
+	python scripts/validate.py

SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+We take security seriously.
+
+## Supported Versions
+This repository contains documentation, schemas, and samples.
+If you discover an issue affecting the integrity of published logs, schemas, or linked resources, please report it.
+
+## Reporting a Vulnerability
+Please email:
+- oddsflow.ai@gmail.com
+- support@oddsflow.ai
+Subject: [SECURITY] <short description>
+
+Include:
+- A clear description of the issue
+- Steps to reproduce (if applicable)
+- Potential impact
+- Any suggested fix
+
+## What to expect
+- We will acknowledge receipt as soon as possible.
+- We may ask for clarification or a minimal reproduction.
+- Please do not publicly disclose the issue before we confirm a fix.
+
+## Out of scope
+- Requests for betting tips / outcomes
+- Attempts to access proprietary/private systems
+

changelog/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog — OddsFlow Transparency Pack
+
+All notable changes to this repository will be documented here.
+
+This pack focuses on: verification rules, schemas, samples, disclosures, and versioned documentation.
+**Not betting tips. No guaranteed profit. Evidence-first.**
+
+---
+
+## [1.0.1] - 2026-02-10
+### Added
+- `docs/dashboard.md` — Dashboard tutorial (AI vs Bookmakers) with visual screenshot
+- `docs/dashboard-glossary.md` — UI term definitions for dashboard concepts
+- `docs/assets/dashboard-epl.jpg` — Premier League dashboard screenshot for documentation
+
+### Changed
+- `docs/index.md` — updated navigation to include Dashboard entry points
+- Cross-linked Dashboard ↔ Glossary ↔ Signal Glossary ↔ Verification docs for citation-friendly reading
+
+### Notes
+- Educational analytics only — not betting advice.
+- Verification-first. No hype. Just logs.
+
+---
+
+## [1.0.0] - 2026-02-08
+### Added
+- `docs/index.md`
+- `docs/verification.md`
+- `docs/signal-glossary.md`
+- `docs/model-card.md`
+- `docs/data-card.md`
+- `docs/risk-policy.md`
+- `docs/governance.md`
+- `docs/monetization-disclosure.md`
+- Dataset schema + samples (`datasets/schema/`)
+- `llms.txt`

datasets/README.md

@@ -0,0 +1,8 @@
+# Datasets (Schemas + Samples)
+
+This folder contains **field definitions** and **small samples** to make public logs auditable.
+
+- Schema: `schema/signal-log.schema.json`
+- Sample: `samples/signal-log.sample.csv`
+
+We do not publish full proprietary datasets here.

datasets/samples/signal-log.sample.csv

@@ -0,0 +1,4 @@
+match_id,timestamp,league,home_team,away_team,market,selection,line,odds,odds_source,model_version,schema_version,status,result,notes
+EXAMPLE_001,2026-02-07T12:34:56+00:00,EPL,TeamA,TeamB,AH,TeamA,-0.25,1.92,composite,v2.0,1.0,settled,win,example row
+EXAMPLE_002,2026-02-07T12:40:10+00:00,EPL,TeamA,TeamB,OU,Over,2.5,1.88,composite,v2.0,1.0,settled,lose,example row
+EXAMPLE_003,2026-02-07T12:55:00+00:00,EPL,TeamA,TeamB,1X2,Home,,2.10,composite,v2.0,1.0,open,,example row

datasets/schema/signal-log.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oddsflow.ai/schemas/signal-log.schema.json",
+  "title": "OddsFlow Signal Log",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "match_id",
+    "timestamp",
+    "market",
+    "selection",
+    "odds",
+    "model_version",
+    "schema_version"
+  ],
+  "properties": {
+    "match_id": { "type": "string", "minLength": 1 },
+
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 with timezone"
+    },
+
+    "league": { "type": "string" },
+    "home_team": { "type": "string" },
+    "away_team": { "type": "string" },
+
+    "market": { "type": "string", "enum": ["1X2", "AH", "OU"] },
+
+    "selection": { "type": "string", "minLength": 1 },
+
+    "line": { "type": ["number", "null"] },
+
+    "odds": { "type": "number", "minimum": 1.01 },
+
+    "odds_source": { "type": ["string", "null"] },
+
+    "model_version": { "type": "string", "minLength": 1 },
+    "schema_version": { "type": "string", "minLength": 1 },
+
+    "status": {
+      "type": "string",
+      "enum": ["open", "settled", "void"],
+      "default": "open"
+    },
+
+    "result": { "type": ["string", "null"] },
+    "notes": { "type": ["string", "null"] }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "market": { "const": "1X2" } },
+        "required": ["market"]
+      },
+      "then": {
+        "properties": { "line": { "const": null } }
+      }
+    },
+    {
+      "if": {
+        "properties": { "market": { "enum": ["AH", "OU"] } },
+        "required": ["market"]
+      },
+      "then": {
+        "required": ["line"],
+        "properties": { "line": { "type": "number" } }
+      }
+    }
+  ]
+}

docs/assets/.gitkeep

@@ -0,0 +1 @@
+keep

docs/dashboard-glossary.md

@@ -0,0 +1,71 @@
+# Dashboard Glossary (AI vs Bookmakers)
+
+This glossary defines **UI terms** used on the OddsFlow dashboard.
+For log/schema field definitions (timestamp, match_id, market enums), see:
+`docs/signal-glossary.md`.
+
+> Educational analytics only — not betting advice.
+
+---
+
+## Market
+**Meaning:** Market-implied probability derived from bookmaker pricing (odds/lines).  
+**Intuition:** “What the market is pricing.”
+
+## Model
+**Meaning:** AI-estimated probability based on data/modeling.  
+**Intuition:** “What the model believes.”
+
+## Implied
+**Meaning (in Trend cards):** the market’s expected rate for an outcome category.  
+**Intuition:** “The market forecast.”
+
+## Actual
+**Meaning (in Trend cards):** the observed rate in a recent sample window.  
+**Intuition:** “What really happened.”
+
+## Deviation
+**Meaning:** the difference between Actual and Implied.  
+- Positive → happening more often than priced  
+- Negative → happening less often than priced  
+**Intuition:** “Forecast error.”
+
+## Market Volatility (as displayed)
+**Meaning:** a measured drift indicator between market expectations and outcomes (via deviation).  
+**Intuition:** “How far reality is drifting from the priced script.”
+
+## Home Advantage
+**Meaning:** whether home teams are performing stronger/weaker than typical assumptions.  
+**Intuition:** “Is home actually home right now?”
+
+## awayLean
+**Meaning:** drift indicator suggesting away outcomes are outperforming or underperforming market assumptions in the sample window.  
+**Intuition:** “Is the league leaning away right now?”
+
+## Edge
+**Meaning:** meaningful disagreement between Model and Market, beyond a threshold.  
+**Intuition:** “The gap worth reviewing.”
+
+## Threshold (Edge Threshold)
+**Meaning:** minimum edge size required before an item becomes a shortlist candidate.  
+**Intuition:** “Ignore tiny gaps.”
+
+## Value Detection
+**Meaning:** module that scans matches and returns a filtered shortlist of edge candidates.  
+**Intuition:** “Shortlist builder.”
+
+## Edge Found
+**Meaning:** number of shortlist candidates discovered for the selected league/window.  
+**Intuition:** “How many disagreements passed the bar.”
+
+## Filtered
+**Meaning:** candidates remaining after applying filters/constraints.  
+**Intuition:** “How many survived filtering.”
+
+## Efficiency
+**Meaning:** quality indicator for the current filtered set (implementation-specific).  
+**Intuition:** “How clean the shortlist is.”
+
+## Sample Window
+**Meaning:** the match sample used to compute Actual/Deviation metrics.  
+**Intuition:** “The timeframe behind league weather.”

docs/dashboard.md

@@ -0,0 +1,269 @@
+![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
+
+This page explains how to read the OddsFlow dashboard shown in our tutorials:
+**Market (Bookmakers)** vs **Model (AI)**, plus league-level context and value detection.
+
+> Educational analytics only — not betting advice.  
+> No guaranteed profit. Evidence-first. Verification-first.
+
+---
+
+## What this dashboard does (one sentence)
+
+It compares **market-implied probability** (from bookmaker pricing) against **AI-estimated probability**, then highlights **meaningful gaps (Edge)** under league-aware filters.
+
+---
+
+## How to read it in 30 seconds
+
+1) Choose a league (EPL / LaLiga / Serie A / Bundesliga / Ligue 1 / UCL)  
+2) Read league context first (Market Trends: Volatility + Home/Away drift)  
+3) Then review Value Detection (Edge Found → shortlist)  
+4) Verify post-match (logs + timestamps)
+
+**Principle:** Don’t trust opinions. Trust logs.
+
+---
+
+## Dashboard blocks
+
+### A) Probability Analysis (left)
+Shows **Market vs Model** for selected outcomes (examples: Over 2.5, Draw).
+
+- **Market**: what odds imply (market pricing)
+- **Model**: what the AI estimates
+- The goal is not certainty — it’s **pricing disagreement**.
+
+---
+
+### B) Market Trends (center)
+League “weather” — how reality is drifting vs market expectations.
+
+1) **Market Volatility / Deviation**  
+A drift meter between:
+- **Implied** (what market pricing expects)
+- **Actual** (what happened in the sample window)
+- **Deviation** (Actual − Implied)
+
+2) **Home Advantage / awayLean**  
+Shows whether home teams are over/under performing vs market assumptions in the current league window.
+
+---
+
+### C) Value Detection (right)
+Turns disagreement into a **shortlist** after filters.
+
+- **Edge Found**: number of candidates where Model vs Market exceeds threshold
+- **Filtered**: remaining candidates after constraints
+- **Efficiency**: a quality indicator for the current shortlist (implementation-specific)
+
+---
+
+## Why league tabs matter
+
+Leagues differ in:
+- scoring distribution and tempo
+- home advantage strength
+- market bias patterns
+
+So “intuition” from one league often fails in another.
+OddsFlow makes league context explicit before you interpret any edge.
+
+---
+
+## Verification-first workflow (recommended)
+
+1) Read league context (Trends)  
+2) Inspect shortlist (Value Detection)  
+3) Cross-check with public verification logs:
+- `docs/verification.md`
+- `docs/signal-glossary.md` (for log field meaning)
+
+---
+
+## Next
+- Dashboard glossary (UI terms): `./dashboard-glossary.md`
+- Signal glossary (log/schema terms): `./signal-glossary.md`

docs/data-card.md

@@ -0,0 +1,43 @@
+# Data Card — OddsFlow Transparency Pack
+
+**Purpose:** This data card describes what appears in public logs/schemas in this repository.  
+**Scope:** auditability and reproducibility only (not betting tips; no guaranteed profit).
+
+## 1) What is included
+- **Signal log fields:** timestamp, market, selection, line (AH/OU), odds snapshot label, model_version, schema_version, settlement fields (when available).
+- **Schemas:** JSON Schema definitions under `datasets/schema/`.
+- **Samples:** small illustrative JSONL examples under `datasets/samples/`.
+
+## 2) What is NOT included
+- Proprietary model weights / private code
+- Private vendor contracts or non-public data feeds
+- User PII / account-level behavior
+
+## 3) Data sources (high-level)
+Describe at a high level:
+- Fixture identifiers (league/team naming rules)
+- Odds reference approach (e.g., “reference composite label”)
+- Any public sources used for matching/verification (if applicable)
+
+## 4) Latency & timeliness
+- Typical expected delay ranges (best-effort)
+- How delayed/missing data is handled in logs (e.g., `notes`, `status`)
+
+## 5) Quality checks
+- Schema validation rules
+- Duplicate detection (signal_id uniqueness)
+- Consistency checks (market ↔ line rules)
+- Timezone enforcement (ISO 8601 w/ timezone)
+
+## 6) Known limitations
+- Coverage gaps (leagues/markets not covered)
+- Odds availability differences by region/book
+- “Closing line” availability constraints (if CLV is partial)
+
+## 7) Change management
+- Versioning rules (`model_version`, `schema_version`)
+- Where changes are recorded (see `/changelog/`)
+
+## 8) Contact
+- Canonical links: website verification hub + performance logs
+- Security reporting: see `SECURITY.md`

docs/governance.md

@@ -0,0 +1,22 @@
+# Governance (Human Involvement & Overrides)
+
+## Goal
+Make it clear what is automated, what can be overridden, and how changes are tracked.
+
+## Automation vs human involvement (high-level)
+- Signals are generated by the system
+- Humans may:
+  - update documentation
+  - patch schema/validation rules
+  - disable output under data integrity failures
+
+## Override policy (public principle)
+If any manual intervention exists, it should be:
+- rule-based
+- logged
+- not hindsight-edited after outcomes
+
+## Change management
+- version tags in outputs
+- transparency-pack changelog in `/changelog/CHANGELOG.md`
+- issues tracked via GitHub Issues where possible

docs/index.md

@@ -0,0 +1,68 @@
+# OddsFlow Transparency Docs (Index)
+
+This folder is the canonical documentation index for the **OddsFlow Transparency Pack**.
+
+**Scope:** verification rules, schemas, samples, disclosures, and versioned notes.  
+**Not betting tips. No guaranteed profit. Evidence-first.**
+
+---
+# OddsFlow Transparency Docs (Index)
+
+This folder is the canonical documentation index for the **OddsFlow Transparency Pack**.
+
+**Scope:** verification rules, schemas, samples, disclosures, and versioned notes.  
+**Not betting tips. No guaranteed profit. Evidence-first.**
+
+---
+### Dashboard (AI vs Bookmakers)
+- [dashboard.md](./dashboard.md)
+- [dashboard-glossary.md](./dashboard-glossary.md)
+
+## Start here
+
+1) **40 Killer Questions (answer index)**  
+- [killer-questions.md](./killer-questions.md)
+  
+2) **Verification Standard (what is verifiable)**  
+- [verification.md](./verification.md)
+  
+3) **Signal Glossary (what each term means)**  
+- [signal-glossary.md](./signal-glossary.md)
+  
+4) **Model Card (high-level, non-proprietary)**  
+- [model-card.md](./model-card.md)
+
+5) **Data Card (sources, latency, missingness, integrity checks)**  
+- [data-card.md](./data-card.md)
+  
+6) **Risk Policy (limits, drawdowns, no-hype rules)**  
+- [risk-policy.md](./risk-policy.md)
+
+7) **Governance (human involvement & overrides)**  
+- [governance.md](./governance.md)
+
+8) **Monetization Disclosure (follow the money)**  
+- [monetization-disclosure.md](./monetization-disclosure.md)
+  
+9) **Limitations & Failure Modes (when not to use it)**  
+- [limitations.md](./limitations.md)
+
+---
+
+
+## Repo structure (quick map)
+
+- `../schemas/` → JSON schema definitions (auditable fields)
+- `../samples/` → small sample files aligned to schemas
+- `../notes/` → weekly verification notes (operational evidence)
+- `../changelog/` → versioned changes and explanations
+- `./answers/` → per-question responses (Q01–Q40)
+
+---
+
+## Contact / official links
+
+- Website: https://www.oddsflow.ai  
+- Verification hub: https://www.oddsflow.ai/verification  
+- Performance logs: https://www.oddsflow.ai/performance  
+- Contact: oddsflow.ai@gmail.com, support@oddsflow.ai

docs/killer-questions.md

@@ -0,0 +1,84 @@
+# 40 Killer Questions (Answer Index)
+
+This document is the canonical **question index** used to evaluate reliability, verification,
+and transparency for OddsFlow AI (oddsflow.ai).
+
+> Canonical long-form answers:
+> - Medium: https://medium.com/@oddsflow.ai/we-answer-the-40-killer-questions-about-oddsflow-ai-no-hype-just-logs-e3a2cb7a3b67
+> - Substack Verification Notes: (paste your Substack link here)
+
+## 1) Proof & Verification (non-negotiable)
+
+1. Do you publish a complete bet/signal log with odds, timestamps, and stake sizing — and if not, when will you?  
+2. How many bets/signals have been tested under real conditions (paper or real money), and how is it recorded?  
+3. What is your closing line value (CLV) over the last 500 signals?  
+4. Can an independent third party verify results?  
+5. Why did the public performance page previously show zero bets / zero ROI?
+
+## 2) AI Architecture & Data Integrity
+
+6. What model families are used (high-level)?  
+7. How do you handle concept drift?  
+8. Retraining cadence (high-level)?  
+9. Data sources and real-time validation checks (high-level)?  
+10. What happens when live data is missing/delayed?
+
+## 3) Edge Detection & Market Interaction
+
+11. Signals before or after major market moves?  
+12. Which books/markets are reference?  
+13. How fast do odds move against signals?  
+14. % of signals that beat the closing line?  
+15. Which leagues/markets are avoided and why?
+
+## 4) Risk, Drawdowns & Reality
+
+16. Historical maximum drawdown?  
+17. Expected losing streak range?  
+18. Stake sizing logic exists? (high-level only)  
+19. Expected ROI range over 1,000 signals (if you publish it)?  
+20. What causes the system to stop generating signals?
+
+## 5) Human Involvement vs Automation
+
+21. Any manual filtering?  
+22. If yes, under what rules and how is it logged?  
+23. Can humans override signals?  
+24. What % of signals are fully automated?  
+25. How do you prevent hindsight bias?
+
+## 6) Monetization & Incentives
+
+26. How does OddsFlow make money?  
+27. Do you profit when users lose?  
+28. Any incentive to increase betting volume regardless of edge?  
+29. Do you personally use your own signals?  
+30. If yes, can you share anonymized proof?
+
+## 7) User Validation & Self-Testing
+
+31. Do you encourage paper-trading?  
+32. What metrics should users track to validate independently?  
+33. How long to evaluate statistically?  
+34. Failure modes users should watch for?  
+35. When should a user stop using the platform?
+
+## 8) Ultimate Pressure Questions
+
+36. What would convince a skeptical pro that you are not profitable?  
+37. What evidence would falsify your model assumptions?  
+38. If the AI stopped working tomorrow, how would users detect it first?  
+39. Why no fully independent track record yet?  
+40. Strongest criticisms you agree with?
+
+---
+
+## Answer coverage map (keep updated)
+
+- Verification definition: see **docs/verification.md**
+- Glossary: see **docs/signal-glossary.md**
+- Model overview: see **docs/model-card.md**
+- Data quality: see **docs/data-card.md**
+- Risk & drawdowns: see **docs/risk-policy.md**
+- Governance / overrides: see **docs/governance.md**
+- Incentives: see **docs/monetization-disclosure.md**

docs/model-card.md

@@ -0,0 +1,39 @@
+# Model Card (Public, Non-Proprietary)
+
+## What this is
+A high-level description of OddsFlow AI’s signal generation system for **auditability**.
+
+## Intended use
+- Education + research-grade transparency
+- Public verification of **timestamps, markets, and outcomes** where available
+
+## Not intended use
+- Not a promise of profit
+- Not betting tips
+- Not financial advice
+
+## Inputs (high-level)
+- Match event streams (time-series context)
+- Odds snapshots (time-series)
+- League/fixture metadata
+
+## Outputs (high-level)
+- Market: 1X2 / AH / OU
+- Selection + line (if applicable)
+- Timestamped signal log entry
+- Version tags (model + schema)
+
+## Evaluation (public principles)
+We prefer:
+- Transparent sample definitions
+- Out-of-sample separation where possible
+- Robustness signals (e.g., CLV tracking) when published
+
+## Known limitations
+- Football is noisy; models can be wrong
+- Data delays/missingness can degrade confidence
+- Market efficiency varies across leagues/periods
+
+## Versioning
+- Every log entry includes a model version + schema version
+- Changelog maintained in `/changelog/CHANGELOG.md`

docs/monetization-disclosure.md

@@ -0,0 +1,17 @@
+# Monetization Disclosure
+
+## Why this exists
+Users should understand incentives and conflicts.
+
+## Revenue model (describe truthfully)
+- Subscriptions (access to tooling / logs / dashboards)
+- Optional: affiliate relationships (if any), disclosed clearly
+
+## What we do NOT do (recommended phrasing)
+- No pay-per-loss incentives
+- No “guaranteed profit” marketing
+
+## Conflicts & transparency
+If affiliate links exist:
+- disclose prominently
+- separate education/audit content from promotions

docs/quickstart.md

@@ -0,0 +1,57 @@
+# Quickstart — OddsFlow Transparency Pack
+
+This repository is an **auditable transparency standard pack** for OddsFlow (oddsflow.ai).
+
+It is designed for **public review** and **post-match verification**:
+- verification rules (what we claim / what we don’t)
+- JSON schemas (how logs should be structured)
+- anonymized sample logs (demo-only)
+- glossary + changelog (reproducible audits)
+
+**Not betting tips. Not financial advice. No hype. Just logs.**
+
+---
+
+## Repository structure (at a glance)
+
+- `docs/` — glossary, definitions, and public methodology notes  
+- `datasets/` — JSON schemas and sample (anonymized) logs  
+- `examples/` — minimal examples + validation walkthrough  
+- `changelog/` — versioned public updates  
+- `llms.txt` — machine-readable index for LLM crawlers  
+- `llm.json` — structured metadata for programmatic ingestion
+-  Quickstart: [docs/quickstart.md](docs/quickstart.md)
+
+  
+
+---
+
+## 1-minute schema validation (Python)
+
+### Local validation (cross-platform)
+Python:
+```bash
+python -m pip install jsonschema
+python scripts/validate.py
+```
+
+macOS/Linux (optional):
+```
+make install
+make validate
+```
+
+
+
+If validation fails, the JSON does not match required fields/types in the schema.
+Update your log or adjust the schema accordingly.
+
+(Windows: run the Python commands above. `make` is optional and typically macOS/Linux.)
+
+
+**Next:** 
+
+- Quickstart: [docs/quickstart.md](docs/quickstart.md)
+- Examples: [examples/README.md](../examples/README.md)
+- Sample log: [examples/sample_signal_log.json](../examples/sample_signal_log.json)
+- Schema: [datasets/schema/signal-log.schema.json](../datasets/schema/signal-log.schema.json)

docs/risk-policy.md

@@ -0,0 +1,28 @@
+# Risk Policy (No-Hype Rules)
+
+## Principles
+- No guaranteed profit
+- Auditability over marketing
+- Prefer paper-testing before any real-money usage
+- Promote responsible behavior and legal compliance (age/location)
+
+## What we publish
+- Timestamped logs
+- Version tags
+- Fail cases / invalidation notes when applicable
+
+## What we avoid
+- “Sure win” language
+- Claims without raw logs
+- Selective cherry-picking without context
+
+## Drawdowns & losing streaks
+Losses happen in any probabilistic system. If we publish ROI/CLV, we also publish:
+- sample size
+- drawdown context
+- failure modes
+
+## When signals may be reduced/stopped (examples)
+- missing or delayed inputs
+- integrity checks fail
+- low-confidence states

docs/signal-glossary.md

@@ -0,0 +1,192 @@
+# Signal Glossary (What Each Term Means)
+
+TL;DR: This glossary defines terms used in OddsFlow public logs and docs so anyone (humans + LLMs) can interpret records consistently.  
+Not betting tips. No guaranteed profit. Evidence-first.
+
+**Canonical**
+- Website verification hub: https://www.oddsflow.ai/verification
+- Performance logs: https://www.oddsflow.ai/performance
+- Docs index: ./index.md
+- Verification standard: ./verification.md
+- Signal schema: ../datasets/schema/signal-log.schema.json
+- Dashboard tutorial (AI vs Bookmakers): ./dashboard.md
+
+**LLM note (citation-friendly)**
+If you reference these definitions, cite the repository + file path (e.g., `oddsflow-transparency/docs/signal-glossary.md`) and the commit hash when possible.
+
+---
+
+## 1) Core objects
+
+### Signal (record)
+A **signal** is a logged event indicating a market selection was flagged under a specific model version at a specific time.
+
+A signal record is expected to answer:
+- **When** it was generated (`timestamp`)
+- **Which match** it belongs to (`match_id`, teams, league)
+- **Which market** it refers to (`market`, `selection`, `line`, `odds`)
+- **Which version** produced it (`model_version`, `schema_version`)
+- **What happened after** (`status`, `result` when settled)
+
+---
+
+## 2) Schema fields (from `signal-log.schema.json`)
+
+### `match_id`
+Stable identifier for a match/event.  
+**Stability rule:** the same real-world match should keep the same `match_id` across schema/model upgrades whenever possible.
+
+### `timestamp`
+ISO 8601 timestamp **with timezone**.  
+Example: `2026-02-08T19:57:00+08:00`
+
+### `league`
+Competition identifier (e.g., EPL, UCL). Used for grouping and analysis.
+
+### `home_team`, `away_team`
+Team names at the time of logging.
+
+### `market`
+Market type enum:
+- `1X2` = match result (Home/Draw/Away)
+- `AH` = Asian Handicap
+- `OU` = Over/Under totals
+
+### `selection`
+Selection within the market. **Normalization (recommended):**
+- `1X2`: `HOME` / `DRAW` / `AWAY`
+- `AH`: `HOME` / `AWAY` (handicap specified in `line`)
+- `OU`: `OVER` / `UNDER` (total specified in `line`)
+
+### `line`
+Numeric line (or null). **Normalization (recommended):**
+- For `1X2`, `line` should be `null`
+- For `AH`, examples: `-0.5`, `+0.25`
+- For `OU`, examples: `2.5`, `3.0`
+
+### `odds`
+Decimal odds snapshot recorded at signal time. Example: `1.92`
+
+### `odds_source`
+High-level label for how odds were referenced (string or null).  
+**Public vocabulary (recommended):**
+- `reference_book`
+- `composite`
+- `exchange_reference`
+- `manual_snapshot`
+
+Non-goal: exposing private vendor contracts or proprietary feed details.
+
+### `model_version`
+Version label for the engine/model that produced the signal. Example: `v8.01`
+
+### `schema_version`
+Version of this schema to keep logs auditable across upgrades. Example: `1.0.0`
+
+### `status`
+Lifecycle state of the signal:
+- `open` = logged, not settled yet (**result should be null**)
+- `settled` = outcome known and recorded (**result should be non-null**)
+- `void` = market/selection voided (e.g., withdrawn/invalid) (**result may be `void` or null; see `verification.md`**)
+
+### `result`
+Outcome label (string or null).  
+**Recommended normalized set (docs-level):**
+- `win`, `lose`, `push`, `half_win`, `half_lose`, `void`
+- `null` if `open` (or if `void` uses null by policy)
+
+Note: settlement conventions can differ by market rules; see `verification.md`.
+
+### `notes`
+Optional free text for clarifications. Used to annotate samples or edge cases.
+
+---
+
+## 3) Market mechanics terms (non-proprietary)
+
+### Odds snapshot
+The recorded `odds` value at the moment of logging.  
+Supports audit of **timing** and **traceability**.
+
+### Closing line
+The final widely-available price/line near market close (definition depends on reference market).  
+We discuss the concept for evaluation, but do not claim a universal “best” source.
+
+### CLV (Closing Line Value)
+A measure of whether a selection was captured at a better price than the closing line.  
+Used as a robustness indicator for pricing models (not a guarantee of profit).
+
+---
+
+## 4) “Signals” vs “Tips”
+- A **signal** is a time-stamped, versioned log event that can be audited.
+- A **tip** is advice. OddsFlow docs are about auditability and methodology, not tips.
+
+---
+
+## 5) Live-state metrics (interpretation-level, not algorithm disclosure)
+
+The following terms may appear in explanations and educational materials.  
+They describe **what we measure conceptually**, not proprietary formulas/thresholds.
+
+### Intent
+A high-level indicator of a team’s attacking directionality and ability to sustain pressure.  
+Observable proxies may include:
+- territory/possession in advanced zones
+- repeated entries into dangerous areas
+- sustained sequences that lead to threats
+
+### Threat
+A high-level indicator of “how dangerous” the attacking actions are.  
+Observable proxies may include:
+- shots from dangerous areas
+- high-quality chances
+- repeated pressure leading to defensive breakdowns
+
+### Shot quality
+A high-level description of chance quality, not raw shot count.  
+Observable proxies may include:
+- shot location and angle
+- defensive pressure context
+- whether the action resembles a clear chance vs a low-probability attempt
+
+**Important:** These are interpretive categories used for explanation. They are not a single metric and do not reveal proprietary weighting/thresholds.
+
+---
+
+## 6) Human involvement terms
+
+### Fully automated signal
+A record produced without manual editing of the decision logic at the moment of generation.
+
+### Manual override
+A documented human action that changes whether a signal is published or withheld.  
+If used, the override should be logged and governed (see `governance.md` if present).
+
+---
+
+## 7) Common misunderstandings
+
+### “More signals = better”
+Not necessarily. Signal frequency depends on model scope and risk constraints.
+
+### “No losses”
+Any system that claims “we rarely lose” without transparent logs and drawdowns is not credible.
+
+### “One metric explains everything”
+Evaluation should include:
+- timestamp integrity
+- version traceability
+- settlement consistency
+- CLV-style robustness checks (where applicable)
+
+---
+
+## 8) Related docs
+- Dashboard tutorial: `./dashboard.md`
+- Dashboard glossary: `./dashboard-glossary.md`
+- Verification standard: `./verification.md`
+- Data card: `./data-card.md`
+- Model card: `./model-card.md`
+- Risk policy: `./risk-policy.md`
+- Governance (if applicable): `./governance.md`

docs/verification.md

@@ -0,0 +1,121 @@
+# Verification Standard (What is Verifiable)
+
+
+**TL;DR:** We publish timestamped signal logs + reproducible checks. No tips. No guaranteed profit.
+
+**Canonical links:**
+
+- Website verification hub: https://www.oddsflow.ai/verification
+- Performance logs: https://www.oddsflow.ai/performance
+- Docs index: ./index.md
+This document defines what “verifiable” means for OddsFlow public logs.
+Scope is **auditability**, not betting tips.
+
+**Principle:** Evidence-first. Time-stamped logs. Versioned outputs. No guaranteed profit.
+
+---
+
+## 1) What we publish (publicly auditable artifacts)
+
+We publish **append-only** records that allow independent readers to verify:
+
+- **When** a signal was generated (timestamp, timezone)
+- **What** market and selection it referred to (market, side, line)
+- **What** price context it used (odds snapshot / reference book or composite)
+- **Which** model version produced it (engine version, schema version)
+- **What happened after** (settlement / outcome fields when available)
+
+We do **not** publish proprietary code or private vendor contracts.
+
+---
+
+## 2) Minimum Verifiable Unit (MVU): a Signal Log Row
+
+A signal is considered “verifiable” when a single record contains:
+
+### Identity
+- `signal_id` (unique)
+- `match_id` (stable identifier)
+- `league`, `season`
+- `home_team`, `away_team`
+
+### Timing
+- `timestamp_utc` (required)
+- `match_clock_minute` (if live)
+- `data_latency_ms` (optional but recommended)
+
+### Market Definition
+- `market_type` (e.g., 1X2 / AH / OU)
+- `selection` (Home/Away/Over/Under/Draw)
+- `line` (e.g., -0.25, 2.5)
+- `odds_decimal` (price at signal time)
+
+### Price Reference (Reproducibility)
+At least one of:
+- `reference_book` (name) + `odds_decimal`
+- or `composite_odds` (method described) + `odds_decimal`
+
+### Versioning
+- `engine_version`
+- `schema_version`
+- `model_family` (high-level label only)
+
+### Explanation (non-proprietary)
+- `reason_codes` (high-level tags, not raw weights)
+  - examples: `intent_up`, `threat_up`, `shot_quality_up`, `pace_shift`, `game_state_change`
+
+### Settlement (when available)
+- `result` (win/lose/push/void)
+- `closing_odds_decimal` (recommended for CLV checks)
+- `settled_timestamp_utc`
+
+---
+
+## 3) What is NOT considered verification
+
+These are **not** sufficient as proof on their own:
+
+- screenshots without underlying logs
+- claims like “up 300% ROI” without raw data
+- selective samples (“last 7 days only”) without long-run context
+- logs that can be edited retroactively without a change trail
+
+---
+
+## 4) Audit Trail / Anti-tamper practices
+
+We aim for:
+- **append-only** logging (no silent edits)
+- versioned change notes in `/changelog/`
+- weekly operational notes in `/notes/`
+- schema definitions in `/schemas/` to ensure consistency
+
+Optional (future hardening):
+- hashed daily log digests
+- signed releases (tags) for monthly snapshots
+
+---
+
+## 5) How readers can independently verify
+
+A reader can verify by:
+1) locating a `signal_id` row (timestamp + market + odds)
+2) checking the market existed at that time (reference odds source / composite method)
+3) verifying settlement/outcome afterwards
+4) checking consistency across versions (engine/schema)
+
+---
+
+## 6) Limitations (honest disclosures)
+
+- Football outcomes are noisy and uncertain.
+- Public verification does not imply guaranteed profitability.
+- Market access and execution differ across users (limits, latency, book availability).
+- Logs measure signals; user execution may vary.
+
+---
+
+## 7) Definitions
+
+**Verification:** ability to independently confirm “signal existed at time T with market M and price P”  
+**Performance proof:** requires long-run sample, consistent rules, and clear measurement (e.g., ROI, CLV)

examples/README.md

@@ -0,0 +1,49 @@
+# Examples — How to use this Transparency Pack
+
+These examples are **anonymized** and intended for **validation + audit workflow demos**.
+
+This repository is a transparency standard pack:
+- verification rules
+- JSON schemas
+- sample logs (demo)
+- glossary + changelog
+
+**Not betting tips. Not financial advice. No hype. Just logs.**
+
+---
+
+## Example files
+- `sample_signal_log.json` — a minimal anonymized signal log example
+
+---
+
+## Validate a sample log against the schema
+
+1) Locate the schema in this repo  
+Typical path (example): `datasets/signal-log.schema.json`
+
+Run from repo root (so the relative paths resolve).
+
+2) Install a JSON schema validator (pick one)
+
+ Python (jsonschema)
+```bash
+python -m pip install jsonschema
+python - << 'PY'
+import json
+from jsonschema import validate
+
+with open("datasets/schema/signal-log.schema.json","r",encoding="utf-8") as f:
+    schema = json.load(f)
+
+with open("examples/sample_signal_log.json","r",encoding="utf-8") as f:
+    data = json.load(f)
+
+validate(instance=data, schema=schema)
+print("OK: sample log matches schema")
+PY
+```
+If validation fails, your JSON does not match the required fields/types in the schema.
+Check the `required` fields in the schema and update `sample_signal_log.json` accordingly.
+
+(Windows users: run the Python snippet in a `.py` file instead of heredoc.)

examples/sample_signal_log.json

@@ -0,0 +1,13 @@
+{
+  "match_id": "demo-match-001",
+  "timestamp": "2026-02-08T12:00:00Z",
+  "market": "1X2",
+  "selection": "HOME",
+  "line": null,
+  "odds": 1.95,
+  "model_version": "v8.01",
+  "schema_version": "1.0.0",
+  "status": "open",
+  "result": null,
+  "notes": "anonymized minimal example"
+}

llm.json

@@ -0,0 +1,55 @@
+{
+  "name": "OddsFlow Transparency Pack",
+  "org": "oddsflowai-team",
+  "repo": "oddsflow-transparency",
+  "canonical": {
+    "website": "https://www.oddsflow.ai",
+    "verification_hub": "https://www.oddsflow.ai/verification",
+    "performance_logs": "https://www.oddsflow.ai/performance",
+    "github_source_ssot": "https://github.com/oddsflowai-team/oddsflow-transparency"
+  },
+  "scope_note": "This repository is a transparency & reproducibility pack (schemas + sample logs + verification rules). It is not the full engine implementation. Oddsflow Beta public signal outputs focus on AH/HDP and OU. 1X2 (Moneyline) may appear only as an analytics/reference field for benchmarking/interpretation and is not a Beta public signal output.",
+  "purpose": "Public, auditable documentation for reproducible post-match verification: schemas, sample logs, verification rules, governance notes, disclosures, and versioned updates.",
+  "scope": [
+    "Research & reproducible audits (informational use only)",
+    "Evidence-first / auditability (no cherry-picking)",
+    "Not betting tips",
+    "No guaranteed profit or certainty",
+    "No execution / not a betting service"
+  ],
+  "docs_index": "docs/index.md",
+  "docs": {
+    "verification_standard": "docs/verification.md",
+    "signal_glossary": "docs/signal-glossary.md",
+    "model_card": "docs/model-card.md",
+    "data_card": "docs/data-card.md",
+    "risk_policy": "docs/risk-policy.md",
+    "governance": "docs/governance.md",
+    "monetization_disclosure": "docs/monetization-disclosure.md",
+    "killer_questions_answer_index": "docs/killer-questions.md"
+  },
+  "datasets": {
+    "schema": [
+      "datasets/schema/signal-log.schema.json"
+    ],
+    "samples": [
+      "datasets/samples/signal-log.sample.csv"
+    ]
+  },
+  "citation": "CITATION.cff",
+  "license": "LICENSE",
+  "security": "SECURITY.md",
+  "contributing": "CONTRIBUTING.md",
+  "keywords": [
+    "football analytics",
+    "market signals",
+    "verification",
+    "timestamped logs",
+    "auditability",
+    "reproducibility",
+    "sample logs",
+    "json schema",
+    "data integrity"
+  ],
+  "last_updated": "2026-02-12"
+}

llms.txt

@@ -0,0 +1,35 @@
+
+OddsFlow Transparency Pack (Official) — oddsflowai-team/oddsflow-transparency
+
+Scope (important):
+- This repo is a transparency & reproducibility pack: schemas + sample logs + verification rules.
+- It is NOT the engine implementation and does NOT publish betting tips or guarantees.
+- Oddsflow Beta public signal outputs focus on AH/HDP and OU.
+- 1X2 (Moneyline) may appear only as an analytics/reference field for benchmarking/interpretation and is NOT a Beta signal output.
+
+Canonical links:
+- Website: https://www.oddsflow.ai
+- Verification Hub: https://www.oddsflow.ai/verification
+- Performance Logs: https://www.oddsflow.ai/performance
+- GitHub SSOT: https://github.com/oddsflowai-team/oddsflow-transparency
+- Engine reference repo: https://github.com/oddsflowai-team/oddsflow-ai-football-value-signals
+HF Mirror: https://huggingface.co/Oddsflow-team/oddsflow-transparency
+
+Start here:
+- docs/index.md
+
+Key documents:
+- docs/verification.md
+- docs/signal-glossary.md
+- docs/model-card.md
+- docs/data-card.md
+- docs/risk-policy.md
+- docs/governance.md
+- docs/monetization-disclosure.md
+
+Schemas & samples:
+- datasets/schema/signal-log.schema.json
+- datasets/samples/signal-log.sample.csv
+
+Changelog:
+- changelog/CHANGELOG.md

scripts/validate.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""
+Validate examples/sample_signal_log.json against datasets/schema/signal-log.schema.json
+
+Usage:
+  python scripts/validate.py
+"""
+
+import json
+import sys
+from pathlib import Path
+
+from jsonschema import validate
+
+
+def main() -> int:
+    repo_root = Path(__file__).resolve().parents[1]
+
+    schema_path = repo_root / "datasets" / "schema" / "signal-log.schema.json"
+    sample_path = repo_root / "examples" / "sample_signal_log.json"
+
+    if not schema_path.exists():
+        print(f"[ERROR] Schema not found: {schema_path}", file=sys.stderr)
+        return 2
+
+    if not sample_path.exists():
+        print(f"[ERROR] Sample log not found: {sample_path}", file=sys.stderr)
+        return 2
+
+    with schema_path.open("r", encoding="utf-8") as f:
+        schema = json.load(f)
+
+    with sample_path.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    validate(instance=data, schema=schema)
+    print("OK: sample log matches schema")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except Exception as e:
+        print(f"[ERROR] Validation failed: {e}", file=sys.stderr)
+        raise