HEATER_v1.0.0

Use when starting any task on HEATER's live product — the api/ FastAPI backend (Railway service "celebrated-respect") or web/ Next.js frontend (heater-v1-0-1.vercel.app) — or when unsure where code lives, how a request flows, which database owns what, why CORS/Yahoo-writes/billing seem "missing", or which app (Streamlit vs React) is the real one. Load this first on App B work.

Use when working on HEATER App B auth or billing — Clerk JWT verification, unexpected 401/402, HEATER_API_WRITE_TOKEN, Stripe checkout/webhooks/subscription tiers, require_pro gating, tier-based AI spend caps — or when auth "works locally but not live" (or vice versa), or a page bounces to /sign-in on hard load.

Use when working on Bubba, HEATER's AI assistant — /api/chat/* endpoints, provider streaming (src/ai/providers.py), token metering and spend caps, AI provider keys, attachments/page-context, saved prompts, or the chat composer in web/src/components/bubba/.

Use when proving a HEATER algorithm works — calibrating constants, backtesting projections or recommendations, validating win probabilities, adding uncertainty intervals, checking calibration drift — or before letting any new math drive user-facing recommendations. Also when asked "is this signal real?" or when a calibration run finds no clear winner.

Use when editing api/contracts/*, when api/openapi.json or web/src/lib/api/generated.ts drift (test_openapi_contract or the CI openapi-ts-sync job failing), when JSON responses 500 or render "nan"/"+nan" badges, or when adding/renaming fields on a response the live frontend already consumes.

Use when App B misbehaves and the cause isn't obvious — works locally but not on Railway/Vercel (or vice versa), a live page renders empty/zero/wrong data, an endpoint 500s or times out, or tests see different data than the app. Run this playbook before changing code.

Use when deploying HEATER App B, changing Railway or Vercel env vars/service config, diagnosing live 502s/timeouts/blank data after deploy, operating the Yahoo-token or Statcast relays, or driving Railway/Vercel headlessly from a terminal.

Use when adding or modifying an /api/* endpoint in HEATER App B — a new route, a new page contract, extending a response, wiring a service — or when tests/api/test_no_logic_in_routers.py or the OpenAPI snapshot test fail after touching api/ code.

Use when an App B feature needs Python engine behavior — composing src/ engines from api/services/*, changing scores/projections/valuations for the API, an engine returning empty/zero/wrong-looking data at the service seam — or when tempted to edit src/ engine code to serve an API need.

Use when implementing or reviewing any fantasy-baseball category math in HEATER — stat aggregation, SGP/VORP, win probability, Monte Carlo sims, projections, urgency/scarcity weighting — or when symptoms appear like 1-IP relievers dominating lineups, phantom pitchers ranked high, inverse categories (L/ERA/WHIP) moving the wrong way, or probabilities that don't behave.

Use when auditing HEATER App B, triaging a suspected bug, or about to "fix" one of these: FanGraphs 403, partial/skipped refresh_log statuses, season_stats coverage gaps, name-collision warnings, empty Yahoo tables locally, zero-value FA/lineup numbers on live, a thin Sell/Breakout lens, missing Stripe/CORS env, Yahoo writes 401, or known-flaky tests. Check here BEFORE filing or fixing.

Use when assessing whether a HEATER lineup recommendation is safe to enact — /api/lineup/optimize or /api/start-sit output, the Optimizer page's start/sit calls, daily swaps, streaming pickups — "does this lineup make sense?", "why is it benching X?", or before applying any roster moves it suggests.

Use when building or fixing any data-bearing App B surface — fallbacks, projections, empty/degraded states, "today"/week-window logic — or when live shows 0 / nan / 100% / wrong-date values that look like code bugs. Also before adding any fillna(0), default value, or synthetic placeholder to data a user will see as advice.

Use when assessing whether ANY HEATER recommendation output (lineup/start-sit, trades, free agents, streaming, draft) actually makes sense to enact as the manager of Team Hickey in the FourzynBurn league — "does this rec make sense?", "should I trust this?", "review the optimizer's answer", or before acting on any surface's advice. The harness the per-surface review skills plug into.

Use when designing or implementing a new scoring, valuation, probability, projection, or optimization algorithm for a HEATER decision feature (trade grades, win-prob, lineup value, FA/streaming scores, draft math) — before writing the code. Also when extending the value-engine / trade-math programs or unsure where new math should live.

Use when joining player data across tables, databases, machines, or services in HEATER — matching players by name, building PlayerRefs, syncing/relaying stats, headshots 404ing, a player showing another player's stats, or ids that don't line up between local and Railway. The "Muncy DNA" bug class.

Use when writing or fixing tests for HEATER's api/ or web/, when CI is red (ruff format skew, shard failures, coverage floor, openapi-ts-sync, bandit), when a test passes alone but fails in the full suite or on CI, or when a test needs "now", the DB, or the network.

Use when assessing whether a HEATER trade output is worth acting on — Trade Analyzer/Build evaluations (/api/trade/evaluate), Trade Finder suggestions, trade-targets (partner/acquire/category-fix/position-fix tabs) — "is this trade actually good?", "would they even accept?", "review what the finder suggested", or before proposing any trade it recommends.

Use when storing per-user state, resolving "my team" / viewer identity in HEATER App B, touching api/stores/* or api/tenancy.py, seeing HTTP 409 TEAM_NOT_LINKED or 401 "Login required.", adding admin endpoints, or tempted to write API/user data into data/draft_tool.db (or engine data into api_state.db).

Use when working in HEATER's web/ frontend — Next.js 16 / React 19 / Tailwind v4 pages, wiring a page to /api/* data, pnpm build/gen:api, page titles, PlayerLink/PlayerDialog, viewer team display, slot ordering, or hooking a page into Bubba. Also when a page refetches in a loop, shows the wrong tab title, or type errors appear after backend changes.

Use when starting any non-trivial HEATER change (feature, remediation program, refactor), when deciding how to plan/execute/review it, when finishing work (merge/push), or when another session or track has pushed to master mid-work (merge conflicts in openapi.json / generated.ts).