World Cup Pool

Get current time

Return the current wall-clock time. Use this when reasoning about elapsed time (e.g. current minute of a live match, time until a deadline) or about what day it is — don't guess the time or the date. By default `now_iso` and `local_date` are in the user's own timezone (near midnight the UTC date is a day ahead of the user's local date). Pass `timezone` (an IANA name like 'Europe/Berlin') only to override that, e.g. to read the time in another location.

Create pool

Create a brand-new World Cup pool. Atomically: creates a platform group with the caller as owner, claims the caller as the pool's agent admin, and writes the initial pool/config blob. `name` becomes the group's display name; optional `config` patches the default settings (escalating_points, free, allow_late_entry, start_round). Returns the new group_id and the resolved pool config.

Get pool

Get an overview of the active pool: name, scoring config, the pinned manager note, members, all entries (across members), the pool manager, the caller's role (member / pool_admin / agent_admin), and the next kickoff deadline. Call this once at the start of a session to ground every downstream decision.

List matches

List World Cup fixtures with optional filters. Each match comes back with its status (scheduled | live | final) derived from kickoff time and whether a result has been recorded. Use this to ground pick submissions, look up upcoming deadlines, or surface 'what's on now'.

List groups

Return the tournament's group composition: each group letter with its 4 teams (code, name, flag, rank). Use this to answer 'which group is X in?', to seed bracket projections, or to compute group standings without crawling the full fixture list.

List results

List World Cup match results. Live matches (result row exists, no winner yet, kickoff has passed) come back with status=live and a live_minute field computed against the server clock. Use this for 'what's the score', 'who won', and 'who's still playing'.

Get my entry

Return the caller's pool entry / entries (entry id, name, emoji). If there are no entries, the caller hasn't created one yet — direct them to the SPA's Entries page to set up name + emoji.

Create my entry

Create a new entry in the pool for the caller. An entry is a lineup of picks — one member can hold multiple entries (e.g. their own pick set plus a hedge or a kid's set). Provide a display name and optional emoji. Returns the new entry's id.

Update my entry

Update the caller's own entry — display name or emoji. Pass only the fields you want to change; others are preserved. Refuses to touch entries owned by another member (managers go through set_picks_for_entry for pick overrides; member metadata edits stay self-only).

Delete my entry

Delete one of the caller's entries — removes the entry metadata AND every saved pick row for that entry. Irreversible. Refuses to touch entries owned by another member. Returns counts of what was removed.

Get my picks

Return the caller's submitted picks, optionally filtered to a specific round or to matches whose kickoff is still in the future (upcoming_only=true). Picks are grouped by round_id.

List picks

List picks across every entry in the pool, with the kickoff lockout enforced server-side: the caller's own picks are always included, but other entries' picks for a given match are only included once that match has kicked off. Filter to one round (`round_id`) and/or one match (`match_id`) to keep responses small. Returns a flat list — one row per (entry, match) pair that the caller is allowed to see.

Save my picks

Save or update the caller's picks for one round. Pass round_id and a picks map { match_id: choice } where choice is home / away / draw / np (explicit no-pick = 0 points) or null (delete the pick — only meaningful in merge mode against an existing pick on a still-open match). Any pick whose match has already kicked off is rejected — the agent should propose the next still-open match instead. By default the existing picks for that round are merged with the new ones (RFC 7396); pass replace=true to wholesale-replace.

Get my bonus picks

Return the caller's bonus picks (champion + golden_boot) for the active pool. Empty row if they haven't saved any picks yet — never errors on absence. Pass entry_id to disambiguate when the caller owns multiple entries.

List bonus picks

List bonus picks (champion + golden_boot) across every entry in the pool, with the first-kickoff lockout enforced server-side: the caller's own bonus picks are always included, but other entries' picks are sealed until the tournament's first match has kicked off. Sealed rows carry has_picks=true/false so the agent can answer 'who hasn't picked yet?' without leaking content.

Save my bonus picks

Save the caller's pre-tournament bonus picks: champion (ISO 3-letter team code, worth 2 points if correct) and golden_boot (player id from the seeded golden-boot-candidates roster, worth 3 points if correct). Both pick fields lock at the tournament-wide first kickoff. Pass either or both fields to update; pass null to clear an individual field. Partial updates merge with the existing row.

Get standings

Compute the pool's current standings using the canonical scoring rules (flat or escalating per pool/config.escalating_points). Optionally filter to a single round. Results for matches whose kickoff hasn't happened yet are silently dropped — pre-seeded or in-progress final scores for future matches do NOT move the displayed leaderboard. Pass ``as_of`` (ISO 8601 UTC) to project standings forward — e.g. the SPA threads its mock clock here so test-panel timelines line up with the server's gate. Each row carries ``avg_lead_seconds`` (average lead time of picks before kickoff); points-ties are broken by lead time descending so early-bird picks rank ahead. This is the same engine the SPA's Standings page consumes, so chat and SPA answers always agree.

Set pool config

Update pool configuration. Pass a patch object — only the fields you want to change. manager_user_id and created_at are silently ignored (they can't be changed through this surface). Always echo the resulting config back to the user for confirmation before considering the change done.

Set pool note

Set the pool's pinned manager note (HTML body). Stamps updated_at and updated_by automatically. Manager-only.

Set pool banner

Set or clear the pool's short banner pinned to the top of the home page. Distinct from the pinned note: the banner is one short urgent line with an optional safe-href link. Pass an empty `text` to clear the banner. Manager-only.

Set picks for entry

Manager override: write picks on behalf of any entry in the pool, even after kickoff. Use sparingly — for absent members or to fix data-entry mistakes. Always confirm the override with the user first, naming the affected entry and round.

Refresh standings

Force a fresh recomputation of the pool's standings, dropping any cached values first. Returns the recomputed leaderboard. Pool-manager only — the cache is normally kept fresh automatically on every pick / result / config / schedule change, so reach for this only when you suspect something is stale or you want to confirm a result write took effect.

Set schedule

Replace the tournament schedule wholesale for a given year. Use this for the initial seed and for full re-imports. For incremental edits (add R16 matches once teams qualify, fix one kickoff time, remove a stray match), use patch_schedule instead. Always show the parsed schedule to the maintainer for confirmation before calling this — never write directly from raw input.

Patch schedule

Incrementally edit the schedule's matches array. `add` appends new matches (e.g. R16 fixtures once group stage is decided). `update` merges fields into existing matches by id (rescheduled kickoff, venue correction, fill in TBD teams). `remove` drops matches by id (cleanup of a wrongly-added match). Always echo the resulting diff back to the maintainer for confirmation before calling.

Set match result

Write or update a single match result. For final scores, pass winner ('home'/'away'/'draw') plus the two scores. For an in-progress (live) match, leave winner=null and pass the current scores — the SPA shows status=live and the agent can compute the minute from kickoff + get_current_time. Always confirm with the maintainer (proposed diff vs current state) before calling.

Set match results

Batch-write multiple match results in one call — the workhorse for ingesting a screenshot, file, or bullet-point list. Each entry is validated independently; the response includes a per-match status so the maintainer can see which writes landed and which failed. Always show the parsed batch to the maintainer for confirmation before calling this.

Delete match result

Delete a match result row entirely. Use this to recover from a data-entry mistake — e.g. you wrote a result for the wrong match. Standings recompute from the remaining rows. Confirm with the maintainer before calling.

Set bonus results

Write the tournament's Golden Boot winner. Pass golden_boot (player id from the seeded roster, awards 3 points to matching picks). Champion is NOT set here — it's auto-derived from whichever team won the ``final`` round match, so once set_match_result has posted the final's winner, the +2 champion bonus lands automatically. Pass null to clear a previously-set golden boot. Confirm with the maintainer before calling.

Set golden boot candidates

Seed or replace the Golden Boot candidate roster for the given year. Pass the full players array — wholesale replace. Each player needs id (stable slug), name, team (ISO 3-letter code), and optional club. The SPA bundles a fallback so this is optional in dev.

Patch golden boot candidates

Incrementally edit the Golden Boot candidate roster: add new players, update existing ones by id, or remove ids. Use this instead of set_golden_boot_candidates when you only want to touch a few rows. Always echo the diff back to the maintainer for confirmation before calling.