docs(ev): correct kelly_percent units (0-100, not 0.0-1.0) + full-Kelly safety note (#207)

Issue 1 from #237: docs described kelly_percent as a fraction (0.0-1.0) but the
API actually emits a percentage (0-100). A consumer reading the docs literally
would interpret 34.43 as "3,443% of bankroll" or crash on values >1.0.

Fixes the schema in 6 doc pages:
- api-reference/opportunities-ev.mdx — schema row, 2 example values, Kelly
  Criterion section (formula + sizing guide rewritten in 0-100 units)
- quickstart.mdx — example value 0.0218 -> 2.18
- api-reference/websocket.mdx — 2 example values 0.038 -> 3.8
- api-reference/stream.mdx — example value 0.038 -> 3.8
- examples/value-betting.mdx — Discord embed + Telegram template now
  format as percentage with .toFixed(2)
- sdks/python.mdx — print formatters changed from {:.1%} (which
  multiplies by 100, wrong for already-percentage values) to {:.2f}%

Adds an explicit safety callout in the Kelly Criterion section explaining
that the field is full Kelly with no quality-of-signal adjustment, and
recommending fractional Kelly (1/4 or 1/2) plus 1-2% bankroll cap when
warnings is non-empty or confidence_score < 80. This addresses the
secondary concern in #237 with documentation rather than a wire change.

Issue 2 (publishing full Kelly without quality adjustment) requires a
product call on whether to:
  a) keep emitting full Kelly + add a kelly_percent_adjusted field, or
  b) change kelly_percent in place + add kelly_percent_raw

Both options affect the wire and need migration discussion. Documenting
the safety note now is the minimum correct action.

Closes #237 (Issue 1)
Refs #237 (Issue 2 — needs product decision)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Mlaz-code

content/en/api-reference/opportunities-ev.mdx

@@ -129,7 +129,7 @@ for opp in data['data']:
       "start_time": "2026-02-08T19:00:00Z",
       "is_live": false,
       "confidence_score": 87,
-      "kelly_percent": 0.021,
+      "kelly_percent": 2.1,
       "book_count": 5,
       "arb_available": false,
       "arb_profit": null,
@@ -164,7 +164,7 @@ for opp in data['data']:
       "start_time": "2026-02-08T19:00:00Z",
       "is_live": false,
       "confidence_score": 82,
-      "kelly_percent": 0.015,
+      "kelly_percent": 1.5,
       "book_count": 5,
       "arb_available": false,
       "arb_profit": null,
@@ -294,7 +294,7 @@ X-Request-Id: req_abc123def456
 | `start_time` | string\|null | ISO 8601 event start time |
 | `is_live` | boolean | Whether the event is currently live |
 | `confidence_score` | number | Multi-factor confidence score (0-100) |
-| `kelly_percent` | number\|null | Kelly criterion optimal bet fraction (0.0 to 1.0) |
+| `kelly_percent` | number\|null | Full-Kelly optimal bet **percentage** of bankroll (0–100, e.g. `2.1` = 2.1% of bankroll). Most practitioners apply a fractional Kelly multiplier (¼ or ½) before sizing — see [Kelly Criterion](#kelly-criterion) below. |
 | `book_count` | number | Number of sportsbooks offering this market |
 | `arb_available` | boolean | Whether an arbitrage exists on this market |
 | `arb_profit` | number\|null | Arbitrage profit percentage if available |
@@ -391,20 +391,26 @@ We recommend setting `min_ev=2` for most use cases. Marginal EV (below 2%) can b
 
 ## Kelly Criterion
 
-The `kelly_percent` field tells you the optimal fraction of your bankroll to wager according to the Kelly criterion (0.0 to 1.0, e.g. `0.021` = 2.1%):
+The `kelly_percent` field is the optimal **percentage** of your bankroll (0–100) to wager according to the full Kelly criterion. A value of `2.1` means full Kelly recommends 2.1% of bankroll; a value of `34.4` means 34.4%.
 
 ```
-Kelly% = (edge / odds_to_1) = (fair_prob x decimal_odds - 1) / (decimal_odds - 1)
+Kelly% = (fair_prob × decimal_odds - 1) / (decimal_odds - 1) × 100
 ```
 
+<Callout type="warning">
+**This is full Kelly, computed from the model's fair probability with no quality-of-signal adjustment.** Full Kelly is mathematically optimal only when the true probability is known exactly. In practice, sharp anchors carry uncertainty (single sharp reference, late-arriving live odds, low cross-validation), and full Kelly can produce dangerously large stake suggestions. See `confidence_score`, `cross_ref_count`, and `warnings` (e.g. `SINGLE_SHARP_REF`, `LIVE_STALE_ODDS`) before sizing.
+
+**Use a fractional Kelly multiplier**: most practitioners apply ¼ or ½ Kelly (`kelly_percent × 0.25` or `× 0.5`). Cap any single bet at 1–2% of bankroll regardless of what `kelly_percent` reports, especially when `warnings` is non-empty or `confidence_score < 80`.
+</Callout>
+
 ### Kelly Sizing Guide
 
-| Kelly % | Risk Level | Recommendation |
+| `kelly_percent` | Risk Level | Recommendation |
 |---------|------------|----------------|
-| < 1% | Low | Small edge, consider skipping |
-| 1 - 3% | Moderate | Standard bet size |
-| 3 - 5% | Aggressive | Strong edge, but size carefully |
-| 5%+ | Very aggressive | Excellent edge; consider fractional Kelly (half or quarter) |
+| < 1 | Low | Small edge, consider skipping |
+| 1 – 3 | Moderate | Standard bet size — quarter Kelly = 0.25–0.75% of bankroll |
+| 3 – 5 | Aggressive | Strong edge — quarter Kelly = 0.75–1.25% of bankroll |
+| 5+ | Very aggressive | Excellent edge or sharp-signal artifact; cap at 1–2% of bankroll regardless |
 
 <Callout type="warning">
 **Variance Warning:** +EV does not guarantee profit on every bet. Over 100 bets at 5% EV, actual results can range widely. The edge only materializes over hundreds or thousands of bets. Never bet more than you can afford to lose.
@@ -413,7 +419,7 @@ Kelly% = (edge / odds_to_1) = (fair_prob x decimal_odds - 1) / (decimal_odds - 1
 ## Best Practices
 
 1. **Set a minimum EV threshold** - Use `min_ev=2` or higher to focus on meaningful edges
-2. **Use Kelly sizing** - Use `kelly_percent` to determine bet size (multiply by bankroll)
+2. **Use Kelly sizing** - `kelly_percent` is a percentage (e.g. `2.1` = 2.1% of bankroll). Apply a fractional Kelly multiplier (¼ or ½) before sizing
 3. **Filter by confidence** - Use `confidence_score` to prioritize high-confidence opportunities
 4. **Monitor `market_width`** - Narrow markets (low width) indicate more efficient pricing and more reliable EV calculations
 5. **Act quickly** - +EV opportunities are fleeting; lines move fast

content/en/api-reference/stream.mdx

@@ -150,7 +150,7 @@ A new positive expected value opportunity has been found. Only sent on `opportun
 ```
 event: ev:detected
 id: evt_00043
-data: [{"id":"a1b2c3d4e5f6","game_id":"nba_phosuns_phi76ers_2026-02-08","ev_percentage":4.35,"odds_american":-105,"odds_decimal":1.952,"no_vig_odds":-101,"selection":"PHO Suns -3.5","market":"point_spread","line":-3.5,"sportsbook":"draftkings","game":"PHO Suns @ PHI 76ers","sport":"basketball","league":"nba","home_team":"PHI 76ers","away_team":"PHO Suns","start_time":"2026-02-08T19:00:00.000Z","is_live":false,"confidence_score":72,"kelly_percent":0.038,"book_count":4,"detected_at":"2026-02-08T18:47:20.000Z"}]
+data: [{"id":"a1b2c3d4e5f6","game_id":"nba_phosuns_phi76ers_2026-02-08","ev_percentage":4.35,"odds_american":-105,"odds_decimal":1.952,"no_vig_odds":-101,"selection":"PHO Suns -3.5","market":"point_spread","line":-3.5,"sportsbook":"draftkings","game":"PHO Suns @ PHI 76ers","sport":"basketball","league":"nba","home_team":"PHI 76ers","away_team":"PHO Suns","start_time":"2026-02-08T19:00:00.000Z","is_live":false,"confidence_score":72,"kelly_percent":3.8,"book_count":4,"detected_at":"2026-02-08T18:47:20.000Z"}]
 ```
 
 ### `ev:expired`

content/en/api-reference/websocket.mdx

@@ -213,7 +213,7 @@ Snapshot of opportunities for a single channel type. Sent once per subscribed op
       "start_time": "2026-02-08T19:00:00.000Z",
       "is_live": false,
       "confidence_score": 72,
-      "kelly_percent": 0.038,
+      "kelly_percent": 3.8,
       "book_count": 4,
       "detected_at": "2026-02-08T18:47:20.000Z"
     }
@@ -326,7 +326,7 @@ New +EV opportunity found. Pro tier or higher only.
       "start_time": "2026-02-08T19:00:00.000Z",
       "is_live": false,
       "confidence_score": 72,
-      "kelly_percent": 0.038,
+      "kelly_percent": 3.8,
       "book_count": 4,
       "detected_at": "2026-02-08T18:47:20.000Z"
     }

content/en/examples/value-betting.mdx

@@ -70,7 +70,7 @@ async function sendAlert(opp) {
       { name: 'Book', value: opp.sportsbook, inline: true },
       { name: 'Odds', value: String(opp.odds_american), inline: true },
       { name: 'EV', value: `+${opp.ev_percentage}%`, inline: true },
-      { name: 'Kelly', value: `${opp.kelly_percent}`, inline: true },
+      { name: 'Kelly', value: `${opp.kelly_percent.toFixed(2)}%`, inline: true },
       { name: 'Devig', value: `${opp.no_vig_odds} (${opp.sharp_book})`, inline: true },
     )
     .setTimestamp();
@@ -130,7 +130,7 @@ Selection: ${opp.selection}
 Book: ${opp.sportsbook}
 Odds: ${opp.odds_american}
 EV: +${opp.ev_percentage}%
-Kelly: ${opp.kelly_percent}
+Kelly: ${opp.kelly_percent.toFixed(2)}%
   `.trim();
 
   await bot.sendMessage(chatId, message, { parse_mode: 'Markdown' });

content/en/quickstart.mdx

@@ -157,7 +157,7 @@ Response:
         "odds_probability": 0.535
       },
       "ev_percentage": 4.35,
-      "kelly_percent": 0.0218
+      "kelly_percent": 2.18
     }
   ],
   "meta": {

content/en/sdks/python.mdx

@@ -41,7 +41,7 @@ evs = client.ev.get(min_ev=3.0, sport="basketball")
 for opp in evs.data:
     print(f"+{opp.ev_percentage:.1f}% EV on {opp.selection} @ {opp.sportsbook}")
     if opp.kelly_percent:
-        print(f"  Kelly: {opp.kelly_percent:.1%}, Confidence: {opp.confidence_score}")
+        print(f"  Kelly: {opp.kelly_percent:.2f}%, Confidence: {opp.confidence_score}")
 
 # Best odds across sportsbooks
 odds = client.odds.best(league="nba", market="moneyline")
@@ -83,7 +83,7 @@ for opp in evs.data:
     print(f"+{opp.ev_percentage:.1f}% on {opp.selection} @ {opp.sportsbook}")
     print(f"  Fair probability: {opp.fair_probability}")
     print(f"  Devig: {opp.devig_method} via {opp.sharp_book}")
-    print(f"  Kelly: {opp.kelly_percent:.1%}")
+    print(f"  Kelly: {opp.kelly_percent:.2f}%")
     print(f"  Confidence: {opp.confidence_score}/100")
 ```