Survive Sunday — Wave 1

Private NFL survivor / elimination pool PWA for the 2026/27 season.
Locale: en-CA. Stack: Next.js App Router, Prisma + Neon Postgres (production), Auth.js (email/username + password).

Owner / keep-up

#1 cost rule: For specs, FILE-MAP lookups, QA critic scoring, copy, and checklists, use free tiers in order — free Grok, then free Claude, then free Gemini — before any paid Grok Bot / Cursor coding agents. Paid agents only for the actual code PR/merge. Aim to save ~30–50% usage by keeping planning and critic loops off paid runs. Details: docs/HANDOFF.md (top) and docs/FREE-GROK.md (free AI first).

Docs freshness: When any free or included usage allotment is near empty, refresh HANDOFF / FREE-GROK.md / FILE-MAP (Help only if a user/admin process changed) before starting more work — including Grok Bot / Cursor included weekly usage.

Not a coder? Start with docs/HANDOFF.md — what is live on main vs still in an open PR, where the app lives (GitHub + Vercel + Neon), login / AUTH_SECRET / AUTH_URL pitfalls, BM Boys roster names, official Week 1 picks, and copy-paste prompts for free Grok, then free Claude, then free Gemini. That is not paid Grok Bot, Cursor desktop agents, or other expensive coding bots. You merge GitHub PRs and click through Vercel yourself.

If a chat and the handoff disagree, trust the GitHub main branch.

Quick start

cd /workspace/survive-sunday/app
npm install
npx prisma db push
npm run seed
npm run dev

Open http://localhost:3000.

Or one-shot: npm run setup && npm run dev

Build check

npm install && npx prisma db push && npm run seed && npm run build

Live pool (no Demo vs Real toggle)

The pool is live-only. There is no Demo↔Real switch on Admin. Friends see Who are you? from the live roster, then Join (own email + password) or Sign in. Unclaimed seats still use practice @survivesunday.demo emails for Join claiming — that is seat claiming, not a Demo mode.

First real administrator login: Sign in as Gams (Player + Administrator). Switch Admin tools from Account.

Week 1 is the current board week. Week 2 stays on the schedule. Playbook: docs/REAL-MODE.md.

Legal names live in the database (Admin → Players), not in this repo. Sample files use placeholders such as Alex Player.

Join / claim a seat

• Invite code: SUNDAY26
• Landing → Who are you? from the Admin roster (nickname + real name). Friends then set their own email and password to claim that seat. Already-claimed seats point them to Sign in.
• Open seats keep a practice @survivesunday.demo address until claimed. That is not a Demo-mode picker.

Forgot password (email or text)

Friends stay signed in on their phone / Home Screen app. We do not ask for a code at every login.

If they forget the password: Sign in → Forgot password → 6-digit code by email (check inbox and spam/junk; optional SMS if a cell is saved) → new password → signed back in.

• Practice @survivesunday.demo addresses cannot use Forgot password. Claim the seat, or ask the administrator to set a password. There is no demo sign-in route.
• Production minimum: RESEND_API_KEY and RESEND_FROM_EMAIL (see DEPLOY.md §3b). Optional Twilio for texts.
• Locally, if those keys are missing, the code is printed in the server log and shown on the reset page.

Wave 1 features

• Invite code join + live-roster Who are you? claim (own email/password on an existing seat) + credentials login
• Forgot-password one-time code (email / SMS); sessions stay signed in (~90 days)
• Notification preferences (Account): each user chooses alert types. Core on, live scores / injury notes off. Email via Resend; missing-pick SMS follows the same switch. Password-reset codes are never gated.
• Nickname + optional real name; pool membership; admin/member roles
• Week 1 schedule from data/week1-slate.json (real 2026 slate + final scores where present)
• Lock at first kickoff; countdown; hide others’ picks until lock. Change an existing pick until that team’s kickoff if the new game has not started.
• One pick/week; no team reuse; bye teams disabled
• Mulligan auto-burn → one_loss; second loss → eliminated
• Participants list sorted undefeated, then one-loss, then eliminated; within each group same pick (no pick last), then same game (earlier kickoff first), then nickname A–Z
• Own pick always visible; after lock show matchup + choice; spreads on pick UI
• Live ESPN scores (poll ~45s while games are on) + auto-grade finals; admin simulate button
• Near-live ESPN injury report on team pages and pick-adjacent chips (Out / Doubtful / Questionable)
• Head coach on each team research page (ESPN name + ESPN / Wikipedia / team links)
• Light admin: lock override, remove player, force grade, audit log, mulligan / one-and-done from a week, Hand the pool
• Import Week picks (CSV / paste) for groups mid-season — counts for grading/mulligan/reuse
• Season-end tiebreak helpers (clean record / no ranked auto-pick 💩 → fewest losses → weeks survived → nickname A–Z)
• /help from HELP-COPY (+ importing prior picks); footer disclaimer
• Team research: tap a club from My pick / Schedule / Standings / Scores; helmet, record, this week, style (above coach), then Offence / Defence / Special teams, injuries, and news. Tap an NFL player for college, depth role, and any ESPN injury note
• Team logos are local files in public/helmets/. Every feed abbreviation (WSH, LA, JAC, …) maps to its file through src/lib/team-abbr.ts; see public/helmets/README.md
• Dark stadium UI (gold/green); installable PWA shell
• Seed via npm run seed

Import prior picks (administrator)

Week 1 may already be in progress. As [email protected]:

1. Open Admin → Import week picks
2. Upload or paste CSV (nickname,team)
3. Example: public/examples/week1-picks-import.csv
4. Picks are marked source: imported, audited, visible post-lock, and auto-graded if games are final

Fixed QA issues

Wave 1 Pool QA (critical):

1. Natural lock applies missed picks — ensureWeekLockedEffects(weekId) runs on pool, picks API, standings, scores, and import. When now >= lockAt (or week is locked/graded), it applies missed-pick losses once and auto-grades FINAL games.
2. Missed picks are idempotent — each no-pick member gets a source: missed pick (teamAbbr: MISS) + week.missedPicksAppliedAt. Lock now then Force grade will not double-loss. role === "admin" (Administrator) is skipped.
3. Re-import won’t re-burn — if an imported pick’s team is unchanged and already graded, membership status is left alone (no second mulligan / weeksSurvived bump). Team changes undo the prior grade effect once, then apply the new result.
4. usedTeamsJson on change-before-lock — rebuilt from prior-week picks + current pick only (frees KC when changing KC→BUF). Same rebuild on import updates.
5. Import preview — Preview matches resolves nickname→team (nickname first, then email) before Confirm import.
6. Auto-grade on load — scores/pool (and other ensure paths) grade pending picks whose games are FINAL.
7. App Router error boundaries — src/app/not-found.tsx, error.tsx, global-error.tsx, and (app)/error.tsx so a reload on /admin or /help no longer 404/500 with “missing required error components”.
8. Admin session on localhost — AUTH_URL=http://localhost:3000, AUTH_TRUST_HOST=true, trustHost: true, Secure cookies only on https. A practice administrator keeps admin membership for /admin and /admin/import until a real administrator login exists. There is no separate demo sign-in route. 8b. Tunnel login Host — middleware forwards a public Host (e.g. *.trycloudflare.com) as x-forwarded-host / x-forwarded-proto. Auth callbacks.redirect and the auth route rewrite any https://localhost:3000 Location to the request Host. Client afterAuthNavigate always uses a relative signed-in path (/pick).
9. Session identity drift — demo login signOuts first, await getSession() before navigate, then hard-loads /pick. Authenticated routes are force-dynamic + revalidate = 0; BottomNav prefetch is off; SW is network-only for HTML/RSC. remounts on user id (, ).

Server identity check: node scripts/verify-session-identity.mjs

Env

Copy .env.example → .env. Defaults use SQLite file:./dev.db.

AUTH_URL=http://localhost:3000
AUTH_TRUST_HOST=true

AUTH_TRUST_HOST=true + trustHost: true in src/lib/auth.ts make Auth.js use the incoming Host / x-forwarded-host / x-forwarded-proto instead of pinning AUTH_URL. Middleware copies a non-localhost Host onto x-forwarded-host so a Cloudflare quick tunnel (https://*.trycloudflare.com) and http://localhost:3000 share one npm run dev. Auth redirects that still resolve to localhost are rewritten to the request Host. Session cookies are Secure only on https; names stay authjs.* (no __Secure- / __Host- prefix) so a localhost login still works after a tunnel visit.

To pin a single origin (OAuth callback, tunnel-only):

AUTH_URL=https://great-sloths-fetch.loca.lt
AUTH_TRUST_HOST=false

Wave 2 later (deferred)

• H2H boxing gloves animation
• Weekly + season banter / mute
• Weekly digests (Resend), WhatsApp stub, close-game alerts
• PWA web push (preference flag exists; sender not wired)
• Team detail pages already show ESPN injury report (not demo stubs)
• Full visual polish / motion pass

Live scores & injuries

Scores (live): ESPN’s public NFL scoreboard JSON (site.web.api.espn.com, fallback site.api.espn.com). No API key. /scores, Home, Pick, and Schedule sync on load and poll about every 45s during a live kickoff window. Finals auto-grade picks.

Injuries (near-live): same ESPN public injury report JSON. Cached ~12 minutes. Team pages list Out / Doubtful / Questionable / IR / suspension. Pick / Home / Schedule show compact Out·Doubtful·Q chips. This is not the official NFL club report and has no SLA — ESPN’s undocumented endpoints can 403 or change. data/sample_injury_news.json is schema-only and is not shown in the UI.

Not live: spreads/odds stay seeded; no paid SportsDataIO / API-Sports key is required for Hobby.

See DEPLOY.md and data/data_sources.json.

Data

Seed JSON lives in /workspace/survive-sunday/data/ (symlinked as ./data).

Disclaimer

For entertainment among friends. Not a gambling service. Not affiliated with or endorsed by the NFL. Team names and logos are trademarks of their owners.