Imported from youssefalw2001/Slipiq-Mini-App (
AGENTS.md). Install upstream withnpx skills add youssefalw2001/Slipiq-Mini-App. Copyright stays with the author.
SlipIQ Agent Instructions
These instructions are for Codex or any AI coding agent working in this repository.
Product
SlipIQ is a Telegram Mini App for first-set tennis probability intelligence and smarter betting slip construction.
Tagline: Don't guess. Calculate.
Main Brand Engine
The flagship feature is First Set Lab.
Tennis first-set score probability is the main engine of the brand. NBA and other sports are supporting slip legs only.
The product should feel like a Bloomberg terminal crossed with a sports betting app: serious, smart, dark, data-rich, and mobile-native.
Important Product Rule
SlipIQ is not a tipster service. Do not write copy that promises wins. It is a probability intelligence and decision-support tool.
Never use:
- guaranteed wins
- locks
- risk-free
- easy money
- guaranteed profit
- beat the book every time
Use:
- probability intelligence
- estimated hit rate
- model edge
- fair odds
- expected value
- high variance
- responsible betting
- no guaranteed outcomes
Stack
Use this stack unless the user explicitly changes it:
- React + Vite
- TypeScript
- Tailwind CSS
- Telegram Web App SDK / @twa-dev/sdk
- React Router
- Zustand
- Recharts
- Supabase/PostgreSQL later
- Telegram Stars payments later
Build Priority
Do not start with generic boilerplate. The math is the product.
Priority order:
- Probability engine
- Static seed data
- OpportunityCard component
- Home Feed screen
- First Set Lab / Match Detail screen
- Slip Builder
- Zustand slip store
- Telegram Mini App integration
- Supabase schema and persistence
- Alerts
- Premium / Telegram Stars
- Landing page
MVP Screens
Build these screens in this order:
- Home Feed — Today's Best Opportunities
- Match Detail / First Set Lab — Probability Deep Dive
- Slip Builder
- My Slips — Tracker & History
- Alerts — Don't Miss A Window
- Profile + Premium
- Onboarding — first launch only
Design System
Use the Terminal Intelligence design language.
CSS variables:
--bg-primary: #04040b;
--bg-card: #09091a;
--bg-elevated: #0f0f22;
--border: rgba(255,255,255,0.07);
--text-primary: #e8e4d8;
--text-muted: #4a4a6a;
--accent-gold: #FFD700;
--accent-orange: #FF6B35;
--accent-teal: #4ECDC4;
--accent-red: #FF4757;
--accent-green: #2ed573;
--positive: #2ed573;
--negative: #ff4757;
Typography:
- Display/data font: DM Mono or JetBrains Mono
- Body font: Sora or Plus Jakarta Sans
- All numbers should use monospace styling
UX requirements:
- Mobile-first, optimized for 375px width
- Dark mode only
- Telegram-style touch interactions
- Haptic feedback on important taps when Telegram SDK is available
- Native Telegram BackButton when inside Telegram
- Skeleton states for async operations
- Offline graceful fallback to cached/static data when possible
Probability Rules
All math should live in TypeScript utility files, primarily src/lib/probability.ts.
Separate these concepts clearly:
modelProbabilityfairOddsbookmakerOddsimpliedProbabilityedgeexpectedValue
Expected value must use actual bookmaker odds when available:
expectedValue = modelProbability * bookmakerOdds - 1
Do not calculate EV only from internally generated fair odds.
Fair odds:
fairOdds = 1 / modelProbability
Implied probability:
impliedProbability = 1 / bookmakerOdds
Edge:
edge = modelProbability - impliedProbability
Required Probability Engine Functions
Implement:
calcHoldProb(fs1, w1s, w2s, bpSave, surface)probWinGame(pointWinProbability)calcSetScoreDist(hold1, hold2)classifyScore(probability)fairOddsFromProbability(probability)impliedProbabilityFromOdds(decimalOdds)calculateEdge(modelProbability, bookmakerOdds)calculateExpectedValue(modelProbability, bookmakerOdds)calcSlip(legs)
First-set score classes:
- GREEN / ANCHOR: probability > 15%
- YELLOW / MID: probability > 8%
- ORANGE / PUSH: probability > 3%
- RED / LOTTO: otherwise
Slip tiers:
- S: combined odds >= 3000
- A: combined odds >= 500
- B: combined odds >= 100
- C: otherwise
S-tier means high-upside/high-variance, not guaranteed best.
Seed Data
Use static seed data for the first MVP:
src/data/tennisMatches.jsonsrc/data/nbaGames.json
The first tennis seed must include Rome 2026 Hurkacz vs Hanfmann.
Before Opening a PR
Always run:
npm run build
If tests exist, run:
npm run test
Each PR must include:
- summary of changes
- major files changed
- screenshots or preview notes for UI work
- known limitations
- whether
npm run buildpassed
What Not To Do
- Do not add real API keys or secrets.
- Do not implement payments before core app logic.
- Do not use misleading betting claims.
- Do not make NBA the main product.
- Do not let generated code hide the probability math in UI components.
- Do not ship without visible responsible-use copy.
