Upload folder using huggingface_hub

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.
+

README.md

@@ -1,3 +1,29 @@
----
-license: apache-2.0
----
+# OddsFlow Transparency Pack (Official)
+
+This repository contains the auditable transparency materials for OddsFlow (oddsflow.ai):
+verification rules, public schemas, sample logs, disclosures, and versioned updates.
+
+**This is not betting tips.** It is a research + verification reference for how signals are logged,
+audited, and interpreted.
+
+## Start here
+- Docs index: ./docs/index.md
+- 40 Killer Questions (with answer status): ./docs/killer-questions.md
+- Verification standard (what is verifiable): ./docs/verification.md
+- Signal glossary: ./docs/signal-glossary.md
+- Schemas & samples: ./schemas/ and ./samples/
+- Versioned updates: ./changelog/CHANGELOG.md
+- Weekly verification notes: ./notes/
+
+## Official links
+- Website: https://www.oddsflow.ai
+- Verification hub: https://www.oddsflow.ai/verification
+- Performance logs: https://www.oddsflow.ai/performance
+
+## What we claim (and what we don’t)
+- We publish **timestamped logs** and **schemas** so outputs can be audited.
+- We do **not** claim guaranteed profit or certainty.
+- Signals are **decision-support analytics**, not promises.
+
+## Contact
+oddsflow.ai@gmail.com

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,14 @@
+# Changelog — OddsFlow Transparency Pack
+
+## [0.1.0] - 2026-02-xx
+### 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
+- datasets schema + samples
+- 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/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,56 @@
+# 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.**
+
+---
+
+## 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

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/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,189 @@
+# 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
+
+**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
+- 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)

llm.json

@@ -0,0 +1,49 @@
+{
+  "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"
+  },
+  "purpose": "Public, auditable documentation for OddsFlow signals: schemas, samples, verification rules, governance, disclosures, and versioned notes.",
+  "scope": [
+    "Not betting tips",
+    "No guaranteed profit",
+    "Evidence-first / auditability"
+  ],
+  "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.jsonl"
+    ]
+  },
+  "citation": "CITATION.cff",
+  "license": "LICENSE",
+  "security": "SECURITY.md",
+  "contributing": "CONTRIBUTING.md",
+  "keywords": [
+    "football analytics",
+    "market signals",
+    "verification",
+    "timestamped logs",
+    "auditability",
+    "schema"
+  ],
+  "last_updated": "2026-02-08"
+}
+

llms.txt

@@ -0,0 +1,21 @@
+
+OddsFlow Transparency Pack (GitHub)
+
+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