@claudinho/core 0.10.1 → 0.11.1

package/dist/index.d.ts

@@ -1,22 +1,154 @@
+/** One row of a group table. */
+interface StandingRow {
+    team: Team;
+    played: number;
+    won: number;
+    drawn: number;
+    lost: number;
+    goalsFor: number;
+    goalsAgainst: number;
+    goalDiff: number;
+    points: number;
+    /**
+     * The provider's own rank for this row. Present on every live row (the
+     * standings feed states it); absent on a computed or roster-at-zero table,
+     * which has no authority to rank anyone. Renderers print THIS, never the
+     * array position — on a partial table the two differ (audit A01).
+     */
+    rank?: number;
+}
+/**
+ * A table: its KEY and its rows in standings order.
+ *
+ * `group` is the key a surface selects the table by: a group letter (`A`), a
+ * numbered group (`A1`), a group under a league (`A-B`), or `LEAGUE` for a
+ * league's one table. `label` is the provider's name for the table, sanitized,
+ * present for every table EXCEPT a lettered group (which keeps its localized
+ * title, "Group A" / "Grupo A").
+ */
+interface GroupStandings {
+    group: string;
+    label?: string;
+    rows: StandingRow[];
+    /**
+     * Present when the provider's table could not be read in full: `omitted` rows
+     * were refused (malformed, duplicate, or beyond the row cap). The readable rows
+     * stay usable, but a partial table carries no authority to confirm or project
+     * qualification, and every surface says it is partial (audit A01).
+     */
+    partial?: {
+        omitted: number;
+    };
+}
+/** A table as every surface's structured output states it. */
+interface TableData {
+    group: string;
+    /** The provider's name for the table; absent for a lettered group. */
+    label?: string;
+    standings: StandingRow[];
+    partial?: {
+        omitted: number;
+    };
+}
+/**
+ * A table key as a surface accepts it as an ARGUMENT (`table`, `get_standings`,
+ * `standings://`, `share table`): 1 to 12 letters, digits or `-`, in any case.
+ * It says what may be ASKED FOR, and is wider than what a provider's table can
+ * be keyed as: an unknown key is answered "no such group", a string that is
+ * not a key at all is refused before anything is fetched.
+ */
+declare const TABLE_KEY_ARG: RegExp;
+/** The key an argument asks for, upper-cased; undefined when it is not a key. */
+declare function tableKeyArg(raw: unknown): string | undefined;
+/**
+ * A table's title on a surface that does not localize it (MCP text, the
+ * resource, a share card): `Group A` for a lettered group, and for any other
+ * table the provider's label followed by the key that selects it,
+ * `League A, Group B (A-B)`.
+ */
+declare function tableTitle(table: {
+    group: string;
+    label?: string;
+}): string;
+/**
+ * A table's structured form: `--json`, MCP `data` and both share cards. ONE
+ * mapping, because it carries a verdict (`partial`: rows were left out, so the
+ * table confirms nothing). It was written out at four emit sites, and the two
+ * share ones had already dropped `partial` once (review of #126).
+ */
+declare function tableData(table: GroupStandings): TableData;
+/**
+ * Compute a group table from a set of matches. Teams are seeded from every
+ * match (so a pre-tournament table still lists all four teams at 0), and only
+ * finished matches with a score contribute to the tally.
+ *
+ * Sort: points, then goal difference, then goals for, then name. (Real FIFA
+ * tiebreakers add head-to-head and fair-play; this is the standard simplified
+ * ordering used for display.)
+ */
+declare function computeStandings(matches: Match[]): StandingRow[];
+
 /**
  * Claudinho domain model — the canonical, provider-agnostic shapes.
  * Every data vendor maps INTO these types via a ProviderAdapter.
  */
-/** A national team. `flag` is an emoji (no image assets, no copyright). */
+/** A team. `flag` is an emoji (no image assets, no copyright), and a nation's only. */
 interface Team {
-    /** Short code, typically the FIFA/IOC 3-letter abbreviation (e.g. "MEX"). */
+    /**
+     * Short code as the provider abbreviates it (e.g. "MEX", "ARS", "O&M"). A
+     * DISPLAY LABEL, not an identity: two clubs in one competition can share one
+     * (`CAR` is both Carabobo and Always Ready in the Libertadores).
+     */
     code: string;
     /** Human-readable name (e.g. "Mexico"). */
     name: string;
-    /** Emoji flag (e.g. "🇲🇽"). */
-    flag: string;
+    /**
+     * Emoji flag (e.g. "🇲🇽"), GENERATED from a NATION's name (`sealTeam`); the
+     * neutral 🏳️ for a nation competition's side that is no nation yet (a
+     * bundle placeholder). A club has none: the key is ABSENT, never `''` and
+     * never 🏳️, and nothing is printed in its place. Which teams are nations is
+     * a written fact of the competition (`TEAM_KIND`).
+     */
+    flag?: string;
+    /**
+     * The provider's stable id for this team, namespaced by provider
+     * (`espn:359`). The same for a club in every competition it plays. Present
+     * on a team read from a live feed (and on that team read back from the
+     * cache); ABSENT on the bundled schedule's teams and on a feed record that
+     * carried none. Two teams with the same id are one team, whatever they are
+     * called; the id never makes two teams of one code AND name (see `sameTeam`).
+     */
+    id?: string;
 }
 /**
- * Tournament stage. "3P" is the third-place play-off. "FRIENDLY" is used for
- * non-tournament fixtures (e.g. international friendlies) surfaced when the
- * adapter points at a non-World-Cup competition.
+ * What a provider reported about the season ONE response belongs to. Metadata
+ * of that response, never an input: a request selects a competition, and the
+ * provider says which season it answered for.
  */
-type Stage = 'GROUP' | 'R32' | 'R16' | 'QF' | 'SF' | '3P' | 'F' | 'FRIENDLY';
+interface SeasonInfo {
+    /** The season's year as the provider keys it (2026 for "2026-27"). */
+    year: number;
+    /** Human label (e.g. "2026-27 English Premier League"); may be empty. */
+    label: string;
+    /** ISO 8601 UTC, when the provider states it. */
+    startDate?: string;
+    /** ISO 8601 UTC, when the provider states it. */
+    endDate?: string;
+}
+/**
+ * The stage of a fixture, from a written grammar over the provider's season
+ * slug and the competition's kind (`stageFromSlug` in the trust layer).
+ *   - `GROUP`, `R32`, `R16`, `QF`, `SF`, `3P` (the third-place play-off), `F`:
+ *     a tournament's group stage and knockout rounds;
+ *   - `REGULAR`: a league's regular season ("League");
+ *   - `LEAGUE`: a cup's league phase ("League phase");
+ *   - `PO`: play-offs ("Play-offs"), a knockout stage;
+ *   - `FRIENDLY`: a friendly, under the friendly competition only;
+ *   - `OTHER`: a phase the grammar does not know. It carries the provider's own
+ *     words in `Match.stageLabel` when there are any, and prints nothing when
+ *     there are none (an absent or unreadable slug asserts no phase).
+ */
+type Stage = 'GROUP' | 'R32' | 'R16' | 'QF' | 'SF' | '3P' | 'F' | 'FRIENDLY' | 'REGULAR' | 'LEAGUE' | 'PO' | 'OTHER';
 /** Normalized match status across all providers. */
 type Status = 'SCHEDULED' | 'LIVE' | 'HT' | 'FT' | 'POSTPONED' | 'CANCELLED';
 /** Match outcome from the home team's perspective. */
@@ -33,6 +165,13 @@ interface Match {
     /** Stable id (provider id for now; cross-provider keying comes later). */
     id: string;
     stage: Stage;
+    /**
+     * The provider's own words for a phase the grammar does not know (the slug
+     * humanized: `qualifying-final` → "Qualifying final"), a human label of at
+     * most 40 columns. Present only on an `OTHER` stage, and only when there are
+     * words; printed untranslated.
+     */
+    stageLabel?: string;
     /** Group letter "A".."L" for the group stage; undefined for knockouts. */
     group?: string;
     /** Kickoff time, ISO 8601 in UTC (always ends in "Z"). */
@@ -140,8 +279,15 @@ type Lang = 'en' | 'es' | 'pt' | 'fr';
 declare function normalizeLang(lang?: string): Lang;
 /** Translate a message key with optional `{placeholder}` interpolation. */
 declare function t(lang: string | undefined, key: string, vars?: Record<string, string>): string;
-/** Localized knockout/group stage label for bracket rendering. */
-declare function stageLabelI18n(lang: string | undefined, stage: string, group?: string): string;
+/**
+ * Localized stage label, from the match (its stage, its group letter under the
+ * group stage, and the words an OTHER stage carries). An `OTHER` stage prints
+ * the provider's own words untranslated, or NOTHING when it carries none: a
+ * caller that joins a stage into a line drops an empty one with its separator.
+ * A bare stage (a bracket round, a `bracket <stage>` filter) is passed as
+ * `{ stage }`.
+ */
+declare function stageLabelI18n(lang: string | undefined, m: Pick<Match, 'stage' | 'group' | 'stageLabel'>): string;
 
 /**
  * Resolve the effective timezone: explicit arg > CLAUDINHO_TZ env > system.
@@ -165,8 +311,18 @@ declare function formatKickoff(iso: string, opts?: FormatOpts): string;
 declare function formatDate(iso: string, opts?: FormatOpts): string;
 /** Time of day like "19:00" (24-hour) in the target timezone/locale. */
 declare function formatTime(iso: string, opts?: FormatOpts): string;
-/** Compact human countdown until kickoff: "3d4h", "2h10m", "45m", or "now". */
+/** What {@link countdown} says of a kickoff that has passed (the statusline prints it as it is: English, by its rule). */
+declare const COUNTDOWN_NOW = "now";
+/** Compact human countdown until kickoff: "3d4h", "2h10m", "45m", or {@link COUNTDOWN_NOW}. */
 declare function countdown(iso: string, from?: Date): string;
+/**
+ * The countdown as the reader's phrase, ONE rule for every localized line that
+ * says it (CLI `next`, the MCP match line): "in 3d4h" (`next.in`), or, for a
+ * kickoff that has passed (a stale record, the bundle's skeleton during an
+ * outage), the language's own word for now (`countdown.now`), never the
+ * English word inside a translated "in".
+ */
+declare function countdownPhrase(lang: string | undefined, iso: string, from?: Date): string;
 /**
  * The calendar date (YYYY-MM-DD) of a kickoff in the target timezone, or ''
  * when the input can't be parsed — an unfileable fixture matches no date rather
@@ -213,6 +369,15 @@ declare function truncateVisible(s: string, maxColumns: number, marker?: string)
  * too-long value overflows its column rather than being cut mid-name).
  */
 declare function padVisible(s: string, width: number): string;
+/**
+ * A team's text with its flag beside it, or the text alone: the one rule every
+ * renderer applies where a flag goes. The flag prints only when it is a
+ * non-empty string, with its one adjoining space (`🇲🇽 Mexico` on the home side,
+ * `Mexico 🇲🇽` on the away side); a side with no flag (a club, by the
+ * competition's written kind) prints its text alone. Nothing is put in the
+ * flag's place: no placeholder, no double space, no code.
+ */
+declare function withFlag(text: string, flag: string | undefined, side: 'home' | 'away'): string;
 
 /** Outcome (home perspective) from a final/looking scoreline. */
 declare function outcomeFromScore(home: number, away: number): Outcome;
@@ -236,17 +401,258 @@ declare function scoreline(match: Match): string;
 declare function matchLocation(match: Match): string;
 /** Sort comparator by kickoff time, ascending. */
 declare function byKickoff(a: Match, b: Match): number;
-/** Human-readable stage for display (group letter when applicable). */
-declare function stageLabel(m: Pick<Match, 'stage' | 'group'>): string;
+/**
+ * Human-readable stage for display, in English (the group letter under the
+ * group stage). An `OTHER` stage prints the provider's own words it carries,
+ * untranslated, or NOTHING when it carries none: a caller that joins a stage
+ * into a line drops an empty one with its separator.
+ */
+declare function stageLabel(m: Pick<Match, 'stage' | 'group' | 'stageLabel'>): string;
+/**
+ * The segments of a line that are joined with ` · ` (a stage, a location, a
+ * time), with the EMPTY ones dropped: an OTHER stage with no words, or a
+ * record with no venue, prints no segment and no separator, never a dangling
+ * ` ·` or a `· ·`.
+ */
+declare function joinSegments(segments: readonly (string | undefined)[]): string;
+
+/**
+ * The supported set, as ONE table: the sixteen competitions the product
+ * answers for, one row each, and every written fact about a competition that
+ * the rest of the code reads (its teams' kind, its own kind, a league's season
+ * name, its standings shape, what `bracket` and the market sidecar offer, how
+ * often it has an edition). Every other table derives from this one
+ * ({@link deriveTables}): `TEAM_KIND`, `COMPETITION_KIND`, `SEASON_SLUG`,
+ * `STANDINGS_SHAPE` (`kinds.ts`), `NO_BRACKET` (`competition.ts`),
+ * `MARKET_COMPETITIONS` (`markets/provider.ts`); `bracketCapability`, the
+ * canary's competitions and cadences and the README matrix read the rows.
+ * Adding a competition is one row here plus its fixtures; nothing else in the
+ * source changes.
+ *
+ * A LEAF module: it imports nothing. The trust layer reads the derived kinds
+ * at parse time (through `kinds.ts`), and `competition.ts` imports the adapter,
+ * which imports the trust layer; a table with imports of its own could be read
+ * uninitialized on one of those paths.
+ *
+ * Every lookup is by own property, or by equality on a row's slug: the
+ * competition reaches the code from a flag, an environment variable or a tool
+ * argument, and `constructor` is not one.
+ */
+/** Whether a competition fields nations (a flag is generated from the name) or clubs (no flag). */
+type TeamKind = 'nation' | 'club';
+/**
+ * What a surface does for a competition: `offered`; `not-offered-yet` (the
+ * competition may have it, the product does not read it yet); `not-applicable`
+ * (the competition has no such thing: a league season with no knockout tie
+ * has no bracket, a knockout-only cup has no table).
+ */
+type Capability = 'offered' | 'not-offered-yet' | 'not-applicable';
+/** One supported competition, as written down. */
+interface CompetitionEntry {
+    /** The provider's slug (`eng.1`): what a request asks for. */
+    readonly slug: string;
+    /** What a person types (`premier-league`): lower case, digits and hyphens, never a dot. */
+    readonly alias: string;
+    /** What a surface names it (`Premier League`): the provider's name, shortened where it says the country. */
+    readonly name: string;
+    /** The teams it fields. */
+    readonly teams: TeamKind;
+    /** A league (its season is the regular stage) or a cup (rounds and phases). */
+    readonly kind: 'league' | 'cup';
+    /**
+     * The season NAME a league's regular season is filed under, as measured on
+     * the real feed (`2026-27-english-premier-league`: the year in front varies,
+     * the name is this one, matched whole); absent where there is none.
+     */
+    readonly seasonSlug?: string;
+    /**
+     * How its standings are read: `league` (authorised to serve exactly ONE
+     * table: a fact of the competition, never inferred from a payload having one
+     * child), `groups` (lettered or numbered groups), `none` (no table at all:
+     * knockout from the first round).
+     */
+    readonly standings: 'league' | 'groups' | 'none';
+    /** What `bracket` is for it. */
+    readonly bracket: Capability;
+    /** What the market sidecar is for it (Claudinho's slug derivation, not the market provider's coverage). */
+    readonly markets: Capability;
+    /**
+     * How often it has an edition, in years: a season turn steps up by at most
+     * this (at most, not exactly: the Copa America went 2021, 2024, 2028).
+     */
+    readonly cadenceYears: 1 | 2 | 4;
+}
+/**
+ * The sixteen, in the order they are listed.
+ *   - Nations: the World Cup, the Euro, the Copa America (four-yearly), the
+ *     UEFA Nations League, the Concacaf Nations League (its next editions are
+ *     2026/27 and 2028/29, by Concacaf's published 2026 to 2030 calendar) and
+ *     the Gold Cup (two-yearly).
+ *   - The six leagues, yearly. A league's season name as measured on the real
+ *     feed (Oct 3, 2026); `mex.1` and `uru.1` have none (their slugs are
+ *     `torneo-apertura`, `torneo-clausura` and, for `mex.1`, its play-off
+ *     rounds).
+ *   - The four club cups. The Champions League's league phase reads as one
+ *     table; the Concacaf Champions Cup has none (knockout from the first
+ *     round); the Club World Cup is four-yearly.
+ * `bracket`: offered on the World Cup alone (its topology ships bundled);
+ * not applicable for the Premier League and LaLiga, 38-round leagues with no
+ * play-off; not offered yet elsewhere (`ita.1` has had championship and
+ * relegation play-offs since the FIGC's May 2026 decision, `ger.1` a
+ * relegation play-off, `mex.1` the Liguilla, `uefa.champions` a knockout after
+ * the league phase). A competition joins "not applicable" by a written fact.
+ * `markets`: offered on the World Cup alone: the sidecar derives its event
+ * slugs from the World Cup series only.
+ */
+declare const SUPPORTED: readonly CompetitionEntry[];
+/** Every written fact a consumer reads, as derived from one table. */
+interface DerivedTables {
+    /** The teams each competition fields. */
+    readonly teamKind: Readonly<Record<string, TeamKind>>;
+    /** Each competition's kind. */
+    readonly competitionKind: Readonly<Record<string, 'league' | 'cup'>>;
+    /** A league's season name, where it has one. */
+    readonly seasonSlug: Readonly<Record<string, string>>;
+    /** The standings shape where it is not groups (the default). */
+    readonly standingsShape: Readonly<Record<string, 'league' | 'none'>>;
+    /** The competitions with no bracket (`not-applicable`). */
+    readonly noBracket: ReadonlySet<string>;
+    /** The competitions the market sidecar reads (`offered`). */
+    readonly marketCompetitions: ReadonlySet<string>;
+}
+/**
+ * The views every consumer reads, derived from a table. A function of the
+ * table, so a test can run it on one with a row past the table's end and
+ * see every view carry it. Every view is frozen.
+ *
+ * A row that offers a bracket for any competition but the bundled one is
+ * REFUSED here, at load, naming it: an offered bracket needs a knockout
+ * topology the clients ship, and only the bundled competition has one (the
+ * same question as `bundleApplies(slug)` with no season, asked of the leaf's
+ * own constant), so a wrong row never reaches a user.
+ */
+declare function deriveTables(entries: readonly CompetitionEntry[]): DerivedTables;
+/** A competition's row, by its slug; undefined for a slug the table does not hold. */
+declare function entryOf(slug: string | undefined, table?: readonly CompetitionEntry[]): CompetitionEntry | undefined;
+/**
+ * What ONE value names, by the grammar every source of a selection shares
+ * (a flag, the environment, the saved choice): the row whose alias or slug it
+ * is; `raw` for a well-formed slug the table does not hold (experimental);
+ * undefined for anything else (`foo`, `ENG.1`, a space, an empty string). The
+ * resolver (`competition.ts`) and the config file's reader (`userConfig.ts`)
+ * ask this one question, so the file can never hold a value the resolver
+ * would refuse.
+ */
+declare function competitionValue(value: unknown, table?: readonly CompetitionEntry[]): {
+    row: CompetitionEntry;
+} | {
+    raw: string;
+} | undefined;
+/** What each surface is for a competition. */
+interface Capabilities {
+    readonly scores: Capability;
+    readonly next: Capability;
+    readonly standings: Capability;
+    readonly bracket: Capability;
+    readonly markets: Capability;
+}
+/**
+ * A competition's capability row. Scores and the next fixture are the generic
+ * reads, offered on every competition; standings are offered unless the
+ * competition has no table; bracket and markets are the row's. A slug the
+ * table does not hold (a raw slug) gets the generic reads and nothing else.
+ */
+declare function capabilitiesOf(slug: string, table?: readonly CompetitionEntry[]): Capabilities;
+/** What a surface names a competition: its row's name, or a raw slug as it is. */
+declare function competitionLabel(slug: string, table?: readonly CompetitionEntry[]): string;
+/** One competition as a listing states it. */
+interface ListedCompetition {
+    readonly slug: string;
+    readonly alias: string;
+    readonly name: string;
+    readonly teams: TeamKind;
+    readonly kind: 'league' | 'cup';
+    readonly capabilities: Capabilities;
+}
+/**
+ * The table as a listing: every row with its capabilities, in the table's
+ * order, and the current selection as the caller states it (`null` when
+ * there is none). No edition state: whether an edition is current is a fact
+ * of a READ (`betweenEditions`), never of the table.
+ */
+declare function listCompetitions<C>(table: readonly CompetitionEntry[], current: C | null): {
+    competitions: ListedCompetition[];
+    current: C | null;
+};
+
+/**
+ * The team rally cries: a team's own cry takes the flair slot of its match
+ * line instead of the moment's phrase, in every language (a fan's cry is not
+ * translated). Mexico's "¿Y si sí?" was the first, and was hard-coded; it is
+ * now one row of the table.
+ *
+ * A side carries a cry by IDENTITY, in a competition whose teams are of the
+ * entry's kind (a nation's cry in a nations competition, a club's in a club
+ * one): by the provider's id when the side carries one (the same id for a club
+ * in every competition; a present id that is not the entry's is never that
+ * team, whatever its labels say), or, for an id-less side in a nations
+ * competition (the bundle's nations), by its code AND its name. A club's side
+ * with no id carries none: a club's code is a label, not an identity. When
+ * both sides carry one, the pinned side's cry when the pin is one of them (the
+ * one pin predicate, `isPinnedSide`), else the home side's.
+ *
+ * The content is pinned to the approved fixture
+ * `test/fixtures/rally-cries.approved.json`: a cry is changed there, on
+ * purpose, and here to match (`flavor-bank.test.ts` compares them).
+ */
+
+/** One team's cry: the provider's id (the key), its code and name (labels), its kind, the cry. */
+interface RallyCry {
+    readonly id: string;
+    readonly code: string;
+    readonly name: string;
+    readonly kind: TeamKind;
+    readonly cry: string;
+}
+/** A pinned team, as far as the cries need it (core's `Pin` is one). */
+interface RallyPin {
+    readonly id?: string;
+    readonly code: string;
+    readonly name: string;
+}
+/** The approved cries, keyed by the provider's id. Frozen. */
+declare const RALLY_CRIES: readonly RallyCry[];
+/**
+ * The table's entry for this side, in a competition whose teams are of
+ * `kind`: by its id when it carries one, else (a nations competition only) by
+ * its code and its name; undefined when it is no team of the table.
+ */
+declare function rallyEntryFor(team: Team, kind: TeamKind): RallyCry | undefined;
+/**
+ * The rally cry a match's line carries, or undefined when neither side has
+ * one: the side's that has one; when both have one, the pinned side's when
+ * the pin is one of them, else the home side's.
+ */
+declare function rallyCryFor(m: Match, kind: TeamKind, pin?: RallyPin): string | undefined;
 
 /**
- * Commentary "flavor" — a small, localized layer of football-broadcast energy
- * that lets surfaces (and the model) narrate scores with some spice.
+ * Commentary "flavor": a small, localized layer of football-broadcast energy,
+ * one short exclamation for the moment a match is in, printed in the flair
+ * slot of a match line (CLI and MCP text; never in structured output).
  *
- * IMPORTANT (legal): these are GENERIC, unattributed exclamations that evoke the
- * *genre* of football commentary (with a Latin-American TV spirit for `es`).
- * They must NEVER quote, name, or impersonate a real commentator or reproduce a
- * person's signature catchphrase. Keep it that way when extending the banks.
+ * The rule for a phrase (Arturo, Oct 5, 2026): generic genre lines AND the
+ * popular catchphrases, song lines and slogans fans know are in. What stays
+ * out: a real person's NAME inside a phrase (nothing impersonates anyone by
+ * name), any betting word, and anything false for some score of its moment
+ * (a `draw` phrase is said of a level result only, a `late` one from the 80th
+ * minute, a `ht` one at the break whatever the score). The banks below are
+ * the approved content, pinned to the fixture
+ * `test/fixtures/flavor-bank.approved.json`: a phrase is changed there, on
+ * purpose, and here to match (`flavor-bank.test.ts` compares them).
+ *
+ * A team's rally cry is not a phrase of the bank: it takes the slot instead
+ * of the moment's phrase (`rally.ts`, through {@link matchFlairs} for a list
+ * and {@link matchFlair} for one line).
  */
 
 /** Commentary-flair intensity. */
@@ -258,13 +664,75 @@ declare function isFlavorLevel(s: string): s is FlavorLevel;
 /** Coerce arbitrary input (flag/env) to a level, defaulting to `full`. */
 declare function asFlavorLevel(s: string | undefined | null): FlavorLevel;
 /**
- * A short, localized exclamation for a match's moment — or '' when the level or
- * moment calls for restraint. Deterministic per match id. Never quotes a person.
+ * The moments a phrase is said of, in the banks' order: before kickoff, in
+ * play with no goal yet, in play with a goal on the board, at the break, from
+ * the 80th minute, a decided full time, a level one.
+ */
+declare const FLAVOR_MOMENTS: readonly ["scheduled", "live", "goal", "ht", "late", "ft", "draw"];
+type Moment = (typeof FLAVOR_MOMENTS)[number];
+/**
+ * One language's bank: a list of phrases per moment. Indexable by any string
+ * too (a moment read from elsewhere), which yields `undefined` for one that is
+ * not a moment.
  */
-declare function matchFlavor(m: Match, opts?: {
+type FlavorBank = Readonly<Record<Moment, readonly string[]>> & Readonly<Partial<Record<string, readonly string[]>>>;
+/** What a phrase is chosen with: the level (default `full`) and the language (default `en`, any unknown one `en`). */
+interface FlavorOpts {
     level?: FlavorLevel;
     locale?: string;
-}): string;
+}
+/**
+ * A short, localized exclamation for a match's moment, or '' when the level
+ * or moment calls for restraint. Deterministic per match id: the phrase its
+ * id hashes to. A match in a list may get another one ({@link flavorsFor}).
+ */
+declare function matchFlavor(m: Match, opts?: FlavorOpts): string;
+/**
+ * A phrase per match of a list, in order, none twice while the bank allows:
+ * each match takes its own phrase ({@link matchFlavor}) unless a previous row
+ * of THIS list already took it, and then the next phrase of its bank not yet
+ * taken, cyclically from its own; once every phrase of that bank is taken,
+ * its own phrase again (repeats resume). A match the level or its moment
+ * leaves silent gets ''. Deterministic for the same list; the first row's
+ * phrase is always its own, so a list of one is `matchFlavor`.
+ */
+declare function flavorsFor(matches: readonly Match[], opts?: FlavorOpts): string[];
+/** What a flair slot holds: the text (empty for none), and whether it is a team's rally cry (the CLI prints one green). */
+interface Flair {
+    text: string;
+    rally: boolean;
+}
+/**
+ * What a flair is chosen with: the level and the language, the competition's
+ * team kind (without it no side carries a cry: a kind nobody stated vouches
+ * for nothing), and the pinned team, which decides when both sides carry one.
+ */
+type FlairOpts = FlavorOpts & {
+    kind?: TeamKind;
+    pin?: RallyPin;
+};
+/**
+ * The flair slots of a list of match lines, in order: ONE rule for every list
+ * (CLI `today` and `live`, MCP `get_today` and `get_live`). A row whose side
+ * carries a cry ({@link cryOf}) prints the cry (`rally: true`, in every
+ * language: a fan's cry is not translated) and reserves no phrase; the other
+ * rows get the phrases {@link flavorsFor} gives them, as a list of their own,
+ * so they stay distinct while the bank allows whatever the cries around them.
+ * With no team kind the list is `flavorsFor`'s.
+ */
+declare function matchFlairs(matches: readonly Match[], opts?: FlairOpts): Flair[];
+/**
+ * What ONE match line's flair slot holds (CLI `next` and `match`, MCP
+ * `get_match` and `get_next_fixture`): the list of one ({@link matchFlairs}),
+ * so the match's cry, else the phrase the caller handed in, else the match's
+ * own phrase; `off` is silent whatever was handed in.
+ */
+declare function matchFlair(m: Match, opts: FlairOpts, phrase?: string): Flair;
+/**
+ * The approved banks, per language and moment, in the approved order. Frozen:
+ * the content is pinned to `test/fixtures/flavor-bank.approved.json`.
+ */
+declare const FLAVOR_BANKS: Readonly<Record<string, FlavorBank>>;
 
 /** A participant slot in the bundled bracket topology (pre-resolution). */
 type SlotRef = {
@@ -292,7 +760,7 @@ type SlotRef = {
 interface BracketMatchNode {
     matchId: string;
     stage: Stage;
-    /** 1-based index within the stage, ordered by kickoff. */
+    /** 1-based index within the stage, ordered by ascending numeric ESPN event id. */
     index: number;
     home: SlotRef;
     away: SlotRef;
@@ -308,7 +776,8 @@ type SlotStatus = 'confirmed' | 'projected' | 'tbd';
 /** A resolved bracket participant for display. */
 interface ResolvedParticipant {
     label: string;
-    flag: string;
+    /** A nation's flag, or the neutral 🏳️ of a slot not yet known; absent for a side with none. */
+    flag?: string;
     code?: string;
     status: SlotStatus;
 }
@@ -333,16 +802,43 @@ interface BracketView {
     source?: string;
     /** The bracket is a World Cup feature; off the bundle there is none (audit A03). */
     unsupported?: true;
+    /** This competition has no bracket at all (a league season with no knockout tie of its own). */
+    inapplicable?: true;
 }
 interface BracketResult {
     view: BracketView;
     /** Off the bundle there is no bracket (audit A03); `view.stages` is empty. */
     unsupported?: true;
+    /**
+     * This competition has no bracket at all (`bracketCapability`: a league
+     * season with no knockout tie of its own); `view.stages` is empty.
+     */
+    inapplicable?: true;
     degraded: boolean;
     standingsDegraded: boolean;
     source?: string;
+    /**
+     * The knockout window said its answer was not whole (see
+     * `VerdictSource.partial`): the view holds the ties that were read, and a
+     * tie whose record was left out shows its bundled slot. Absent when the
+     * window was whole, failed, or said nothing.
+     */
+    partial?: {
+        omitted?: number;
+    };
 }
 
+/**
+ * Is this a knockout stage: a tie that is played until it is decided (extra
+ * time, penalties)? The rounds (`R32` to `F`, the third-place play-off) and the
+ * play-offs (`PO`). Not a group, a league's season, a cup's league phase, a
+ * friendly, or a phase the grammar does not know (`OTHER`). ONE predicate for
+ * every reader that asks "is this a knockout tie" (the bundle's knockout
+ * readers, the live window's length); on the bundle, whose stages are GROUP and
+ * the rounds, it says what `stage !== 'GROUP' && stage !== 'FRIENDLY'` said.
+ * Not the shootout rule: `sealMatch` refuses penalties on GROUP only.
+ */
+declare function isKnockoutStage(stage: Stage): boolean;
 /**
  * Strip live/final state from a fixture for the bundled skeleton schedule.
  * The JSON ships kickoffs, teams, venues, and bracket structure only — never
@@ -397,7 +893,11 @@ declare const LIVE_WINDOW_MS: number;
  * Numerically matches the slack `marketFixtureForTeam` already applies (live.ts).
  */
 declare const KNOCKOUT_EXTRA_TIME_MS: number;
-/** Live-window length for a fixture — longer for knockout (extra time + penalties). */
+/**
+ * Live-window length for a fixture — longer for a knockout stage (extra time +
+ * penalties), the short one for every other (a group, a league's season, a
+ * cup's league phase, a friendly, a phase the grammar does not know).
+ */
 declare function liveWindowMsFor(m: Match): number;
 /**
  * True once EVERY bundled fixture's (stage-aware) live window has ELAPSED —
@@ -440,74 +940,6 @@ declare function currentOrNextFixtureForTeam(code: string, opts?: {
 /** Sorted list of distinct group letters present in the schedule. */
 declare function groups(fixtures?: Match[]): string[];
 
-/** A roster team plus its group letter (A–L). */
-interface TeamInfo extends Team {
-    group?: string;
-}
-/**
- * The 48-team roster from the bundled group-stage fixtures, sorted by name.
- * Placeholder/knockout slots (non-3-letter code or 🏳️) are skipped.
- */
-declare function allTeams(fixtures?: Match[]): TeamInfo[];
-interface TeamLookup {
-    query: string;
-    /** The single confident match, or null when the query is ambiguous or unknown. */
-    team: TeamInfo | null;
-    /** All candidate teams, best-first (1+ whenever anything matched). */
-    matches: TeamInfo[];
-}
-/**
- * Resolve a free-text team name or code to a roster team. Precedence: exact code,
- * exact name, alias, then prefix/substring fuzzy on the name (fuzzy only for
- * queries of 3+ letters, so a 1–2 char query can't substring-match noise). A
- * unique fuzzy hit resolves; multiple hits return as candidates with `team: null`.
- */
-declare function lookupTeam(query: string, fixtures?: Match[]): TeamLookup;
-
-/** One row of a group table. */
-interface StandingRow {
-    team: Team;
-    played: number;
-    won: number;
-    drawn: number;
-    lost: number;
-    goalsFor: number;
-    goalsAgainst: number;
-    goalDiff: number;
-    points: number;
-    /**
-     * The provider's own rank for this row. Present on every live row (the
-     * standings feed states it); absent on a computed or roster-at-zero table,
-     * which has no authority to rank anyone. Renderers print THIS, never the
-     * array position — on a partial table the two differ (audit A01).
-     */
-    rank?: number;
-}
-/** A group's table: the group letter ("A".."L") and its rows in standings order. */
-interface GroupStandings {
-    group: string;
-    rows: StandingRow[];
-    /**
-     * Present when the provider's table could not be read in full: `omitted` rows
-     * were refused (malformed, duplicate, or beyond the row cap). The readable rows
-     * stay usable, but a partial table carries no authority to confirm or project
-     * qualification, and every surface says it is partial (audit A01).
-     */
-    partial?: {
-        omitted: number;
-    };
-}
-/**
- * Compute a group table from a set of matches. Teams are seeded from every
- * match (so a pre-tournament table still lists all four teams at 0), and only
- * finished matches with a score contribute to the tally.
- *
- * Sort: points, then goal difference, then goals for, then name. (Real FIFA
- * tiebreakers add head-to-head and fair-play; this is the standard simplified
- * ordering used for display.)
- */
-declare function computeStandings(matches: Match[]): StandingRow[];
-
 /** Capabilities a provider advertises so callers can pick a strategy. */
 interface ProviderCapabilities {
     /** True if the provider can push events (websocket/SSE) vs poll-only. */
@@ -515,6 +947,14 @@ interface ProviderCapabilities {
     /** Rough event->feed latency hint, in seconds (for poll-cadence tuning). */
     latencyHintSec: number;
 }
+/** How a window is asked for (see {@link ProviderAdapter.fetchWindow}). */
+interface FetchWindowOptions {
+    /**
+     * Compose parts that state two seasons instead of refusing them. Only for a
+     * caller that applies no bundled schedule and publishes no cached slice.
+     */
+    readonly acrossSeasons?: boolean;
+}
 /**
  * The single swap-point for data vendors. Every provider (ESPN, API-Football,
  * Goalserve, …) implements this and maps INTO the canonical Match model, so the
@@ -522,6 +962,15 @@ interface ProviderCapabilities {
  */
 interface ProviderAdapter {
     readonly name: string;
+    /**
+     * The competition this adapter fetches (a provider slug, e.g. `fifa.world`,
+     * `eng.1`). An adapter serves exactly one, decided when it is built, and
+     * everything below the edge asks the ADAPTER — never the environment — which
+     * competition a request is for. That is what keeps a request from changing
+     * its mind halfway through, and what lets "does the bundled schedule apply?"
+     * be a question about a value.
+     */
+    readonly competition: string;
     readonly capabilities: ProviderCapabilities;
     /**
      * Expected group-table scope for omission checks. Omit when the competition's
@@ -534,12 +983,40 @@ interface ProviderAdapter {
      * can have known groups without sharing the bundled World Cup teams.
      */
     readonly standingsFallbackGroups?: readonly string[];
-    /** All fixtures/results for a single calendar date (provider's timezone semantics). */
+    /**
+     * All fixtures/results for a single calendar date (provider's timezone
+     * semantics). What a provider knows about a response — the season it
+     * belongs to, whether every record in it could be read — it attaches to the
+     * returned array (`attachFetchMeta`); callers read it with `fetchMeta`. The
+     * same holds for every fetch below.
+     */
     fetchByDate(dateISO: string): Promise<Match[]>;
     /** Currently in-progress matches (poll path). */
     fetchLive(): Promise<Match[]>;
-    /** Optional inclusive date-range fetch (used for schedule generation). */
-    fetchWindow?(startDate: string, endDate: string): Promise<Match[]>;
+    /**
+     * Optional inclusive date-range fetch. By default (strictly) a window whose
+     * parts state two seasons is refused: an absent season would let the bundled
+     * schedule apply and a cached slice stand. `acrossSeasons` asks it to compose
+     * them instead (the result then states no `season`, and `seasons` lists
+     * both): only for a caller that merges nothing and keeps no slice: the live
+     * read, and off the bundled competition the dated read and the match read.
+     * An adapter that ignores the option behaves as without it.
+     */
+    fetchWindow?(startDate: string, endDate: string, opts?: FetchWindowOptions): Promise<Match[]>;
+    /**
+     * Optional: the provider's calendar day (`YYYY-MM-DD`) for an instant, i.e.
+     * the day a fixture kicking off then is filed under (ESPN: US/Eastern). A
+     * caller that counts a span in days counts THESE days when the adapter states
+     * them, and UTC days otherwise.
+     */
+    bucketDay?(instant: Date): string;
+    /**
+     * Optional: the clock this adapter counts time by (epoch ms), the one its
+     * cooldown window is armed on. A read whose caller passed no clock asks this
+     * one, so the adapter and the reads it serves agree on "now" (and a test
+     * that injects the adapter's clock injects the read's).
+     */
+    now?(): number;
     /**
      * Optional authoritative group tables (cumulative across the group stage).
      * Returned in standings order per group. Providers that can't supply a real
@@ -577,36 +1054,885 @@ interface ProviderAdapter {
 }
 
 /**
- * Bounded collections — the type that carries its own honesty.
- *
- * Every round of review found a list that was capped without saying so, or that
- * reported a post-cap count as the total, or that said "none found" when it had
- * simply run out of budget. Those are the same bug three ways: the shape of the
- * data did not carry what the reader needed to interpret it. A `BoundedList`
- * cannot be constructed without stating all four facts.
+ * A pinned team, as `follow --team` resolved it: the provider's id (every
+ * club, and required for one: a pin is believed without an id on the bundled
+ * competition alone, whose nations the bundle names by code), and its code and
+ * name as labels.
  */
-interface BoundedList<T> {
-    /** What survived the cap. */
-    readonly items: readonly T[];
+interface Pin {
+    readonly id?: string;
+    readonly code: string;
+    readonly name: string;
+}
+/** The config file, as believed. */
+interface UserConfig {
+    readonly version: 1;
+    /** An alias, a slug in the table or a raw slug, AS WRITTEN: the resolver maps it. */
+    readonly competition: string;
+    readonly team?: Pin;
+}
+/** Why there is no saved choice. */
+type NoConfigReason = 'absent' | 'symlink' | 'unreadable' | 'malformed' | 'version' | 'competition';
+/** What one read of the config file found. */
+type UserConfigRead = {
+    kind: 'read';
+    config: UserConfig;
+} | {
+    kind: 'none';
+    reason: NoConfigReason;
+};
+/** The bound on the config file, in bytes: a real one is under 200. */
+declare const MAX_CONFIG_BYTES = 4096;
+/** The environment a path rule reads: only the variables named below. */
+type PathEnv = Readonly<Record<string, string | undefined>>;
+/**
+ * Where the config file lives: `$XDG_CONFIG_HOME/claudinho/config.json` when
+ * that is set to an absolute path (on every platform: tests and smokes set it;
+ * a relative value is invalid and ignored, see {@link baseDir}); else on
+ * Windows `%APPDATA%\claudinho\config.json` when `APPDATA` is set to an
+ * absolute path (a relative one is ignored the same way); else
+ * `<home>/.config/claudinho/config.json`. An empty variable is absent.
+ */
+declare function configPath(env: PathEnv, platform: string, home: string): string;
+/**
+ * Where the CLI's cache lives, by the same rule: `$XDG_CACHE_HOME/claudinho`
+ * when set to an absolute path (a relative value is invalid and ignored, see
+ * {@link baseDir}); else on Windows `%LOCALAPPDATA%\claudinho` when set to an
+ * absolute path (a relative one is ignored the same way); else
+ * `<home>/.cache/claudinho`. (A Windows install that used `~/.cache` moves
+ * once: it is a cache, refilled by one cold refresh, and the throttle note
+ * lives beside the snapshot, so it moves with it.)
+ */
+declare function cacheDirFor(env: PathEnv, platform: string, home: string): string;
+/**
+ * Read the config file at `path`, once: through the one bounded reader, NOT
+ * following a symbolic link (`lookAtOwnFile`: a link is `symlink`, whatever it
+ * points at), bounded at {@link MAX_CONFIG_BYTES} (a directory, a device, a
+ * file past the bound or one without permission is `unreadable`), never
+ * waiting. Then parsed: bytes that are not JSON, or a root that is not an
+ * object, are `malformed`; a `version` that is not 1 (or none) is `version`; a
+ * `competition` that is no alias, no slug in the table and no well-formed raw
+ * slug (the resolver's grammar) is `competition`. The `team` is believed only
+ * as a team (see {@link believedPin}: without an id only when the competition
+ * resolves to the bundled one, an alias through the table); otherwise it is
+ * dropped and the competition kept. Never throws.
+ */
+declare function readUserConfig(path: string): UserConfigRead;
+/**
+ * The slug a saved competition value names (`competitionValue`: an alias maps
+ * through the table, a slug is itself, a raw slug is itself), or undefined for
+ * a value the resolver's grammar refuses.
+ */
+declare function savedSlug(value: string): string | undefined;
+/**
+ * The saved pin that applies to a request for `selected` (the slug the edge
+ * resolved, undefined when nothing or a refused value was): the file's team
+ * when the file's competition IS that competition (an alias and its slug are
+ * one), whatever chose it: the flag, the environment or the file itself. A
+ * pin belongs to its competition, not to the source that chose it; another
+ * competition does not apply it (a club's id is the same in every
+ * competition, so a pin never carries over by accident). The ONE rule both
+ * edges ask.
+ */
+declare function pinUnder(selected: string | undefined, config: UserConfig | undefined): Pin | undefined;
+
+/** The edition a read's season says has ended (see `betweenEditions`). */
+interface BetweenEditions {
     /**
-     * How many were established before capping. Exact when `complete` is true;
-     * otherwise it may only be a lower bound over the records examined.
+     * The provider's calendar day (`YYYY-MM-DD`) of the season's STATED end:
+     * the day the rule decides on, printed as it is. An administrative date the
+     * provider states for its season, not the day of the last match.
      */
-    readonly total: number;
-    /** `items.length` — kept explicit so a serialized payload is self-describing. */
-    readonly shown: number;
-    /** Did the cap drop anything? */
-    readonly truncated: boolean;
+    readonly ended: string;
+    /** The season's label (e.g. "2026 Concacaf Champions Cup"); absent when the provider gave none. */
+    readonly label?: string;
+}
+/** Any result that may state a verdict. Results state more than this; these are the verdicts. */
+interface VerdictSource {
     /**
-     * Did we finish looking? False when a deadline, error, or partial fetch cut
-     * the work short — so a caller can tell "there are none" from "we don't know".
-     * An empty list with `complete: false` must NEVER render as "nothing found".
+     * No competition is chosen (no flag, no environment, no saved choice), so
+     * nothing was asked of any provider. Stated by a selection, never by a read
+     * (core `selectionVerdict`).
      */
-    readonly complete: boolean;
-}
-/**
- * Bound a list, recording what that cost.
- *
+    readonly noCompetition?: boolean;
+    /** The feature does not exist for this competition yet (off the bundled schedule). */
+    readonly unsupported?: boolean;
+    /**
+     * The competition has no such thing at all (a league season with no knockout
+     * tie of its own has no bracket). Not "not yet": a capability that does not
+     * apply.
+     */
+    readonly inapplicable?: boolean;
+    /**
+     * The competition's table, read WHOLE, and its fixtures over discovery's
+     * span hold no team by the name asked for. A claim about that evidence, not
+     * the competition (a club out in a qualifying round is in no table). Never
+     * stated from a roster that is not whole (a refused row, a missing table, a
+     * row with no id): that is not knowing (`rosterIncomplete`).
+     */
+    readonly unknownTeam?: boolean;
+    /**
+     * The evidence an `unknownTeam` rests on, which its sentence names: the
+     * competition's table read whole and its fixtures over discovery's span
+     * (`table`), or the bundled roster of the World Cup's nations (`bundle`).
+     * Forwarded with the key; not a verdict of its own.
+     */
+    readonly rosterEvidence?: 'table' | 'bundle';
+    /**
+     * The competition's roster was asked for and could not be read whole (a
+     * table missing or partial, a row with no id, no answer), and the name could
+     * not be answered without it: no club matched, or only by a code or a fuzzy
+     * name the unread rest may share. Not "no such team", and not an outage.
+     */
+    readonly rosterIncomplete?: boolean;
+    /**
+     * The name a team-scoped verdict names (`unknownTeam`, `rosterIncomplete`):
+     * the query as the reader typed it, bounded as a label. Not a verdict.
+     */
+    readonly query?: string;
+    /**
+     * The read's edition ended before the day asked and nothing in it is
+     * scheduled or in play (see `live.ts`, `betweenEditionsOf`).
+     */
+    readonly betweenEditions?: BetweenEditions;
+    /**
+     * The result holds what could be read and is not the whole answer: the
+     * provider sent a table that did not become one (an all-tables standings
+     * read). Unlike `unsupported`, the result is not empty: the sentence goes
+     * BESIDE what is shown, not instead of it.
+     */
+    readonly incomplete?: boolean;
+    /**
+     * The read behind the result said it was not whole: the provider sent
+     * records the result does not hold (unreadable, a second copy of one
+     * fixture, beyond a bound). `omitted` is how many, when that is known. The
+     * result holds what was read, and the sentence goes beside it. Stated only
+     * when the adapter SAID its answer was not whole; an adapter that says
+     * nothing about its answer states no verdict.
+     */
+    readonly partial?: {
+        readonly omitted?: number;
+    };
+}
+/** The structured keys of the verdicts a result states. Empty when it states none. */
+interface VerdictExtras {
+    noCompetition?: true;
+    unsupported?: true;
+    inapplicable?: true;
+    unknownTeam?: true;
+    rosterEvidence?: 'table' | 'bundle';
+    rosterIncomplete?: true;
+    betweenEditions?: {
+        ended: string;
+        label?: string;
+    };
+    incomplete?: true;
+    /** `omitted` present only when the count is known (a positive integer). */
+    partial?: {
+        omitted?: number;
+    };
+}
+/**
+ * Whether a result states `partial` (an object; anything else states nothing).
+ * The one test of it, for the sentences built beside the verdict's (an empty
+ * body after a read that was not whole says nothing was READ).
+ */
+declare function statesPartial<T extends VerdictSource>(result: T): result is T & {
+    readonly partial: {
+        readonly omitted?: number;
+    };
+};
+/**
+ * The verdict keys to spread into `--json` and MCP `data`, in a stable order.
+ * Only verdicts the result actually states: a healthy result adds no key.
+ */
+declare function verdictExtras(result: VerdictSource): VerdictExtras;
+/**
+ * `served` for a structured twin: the SHOWN fixtures whose record the read's
+ * window held, in the order shown (a shown fixture not among them is the
+ * bundled schedule's row, its live state unconfirmed). Bounded like the rows
+ * it interprets: `shown` is what the surface finally displays (the day's rows,
+ * the bounded list, the card's matches, the one match), never the window's
+ * every id, which can hold other dates. A plain field, not a verdict, carried
+ * only BESIDE the `partial` verdict it interprets: empty on a whole read,
+ * whose structured output keeps its shape, and when the result states none.
+ * The results state the window's ids on every successful read (the read's
+ * fact); this is the one rule for what a surface carries of them.
+ */
+declare function servedExtras(result: VerdictSource & {
+    readonly served?: readonly string[];
+}, shown: ReadonlyArray<{
+    readonly id: string;
+}>): {
+    served?: readonly string[];
+};
+/**
+ * The sentence that REPLACES the body, in the reader's language — or
+ * undefined when the result states none, and the surface prints its body (or
+ * says what it would have said anyway: "no fixture found", "couldn't reach the
+ * provider"). A qualifying verdict is never returned here: see
+ * {@link verdictQualifiers}.
+ */
+declare function verdictNotice(result: VerdictSource, lang?: string): string | undefined;
+/**
+ * The sentences that QUALIFY the body, printed beside it, in a fixed order
+ * (`incomplete`, then `partial`), in the reader's language. Empty when the
+ * result states none, and when it states a replacement (which stands alone).
+ *
+ * Any result object may be handed over, also one whose type declares none of
+ * the verdict fields (a degraded result: it simply states none); the fields it
+ * does declare are still checked against `VerdictSource`.
+ */
+declare function verdictQualifiers(result: VerdictSource & object, lang?: string): string[];
+
+/**
+ * Discovery's span, in the provider's calendar days around the day asked. Its
+ * own module because the read (`live.ts`) and the sentences that name it
+ * (`verdict.ts`: "no team called X in the table or in its fixtures over the
+ * next 14 days") both need the number, and the verdict module is below the
+ * read.
+ */
+/** Discovery looks this many provider days back (a match that kicked off late yesterday can still be in play). */
+declare const SCHEDULE_LOOKBACK_DAYS = 1;
+/** And this many ahead. */
+declare const SCHEDULE_AHEAD_DAYS = 14;
+
+/** Provider names {@link makeAdapter} can construct (the CLI validates against this). */
+declare const KNOWN_SOURCES: readonly ["espn"];
+/**
+ * Whether a source names a provider {@link makeAdapter} can construct: THE
+ * question for every caller that must not ask a provider it does not name (a
+ * command's precheck, the refresher, the trigger that starts one).
+ */
+declare function isKnownSource(source: string): boolean;
+interface AdapterOptions {
+    /**
+     * The competition the adapter will fetch. REQUIRED: the caller is the edge
+     * that resolved it (see `resolveCompetition`), and an adapter that picked a
+     * default here would be a second place where the competition is decided.
+     */
+    competition: string;
+    /**
+     * Enrich group-stage fixtures with their group letter (one extra standings
+     * request per poll). Default on; the statusline refresher turns it off because
+     * it never renders group letters.
+     */
+    enrichGroups?: boolean;
+    /** Clock, injectable for tests; drives the provider cooldown window. */
+    now?: () => number;
+}
+/**
+ * Construct a provider adapter for a `--source` name (default: espn). An
+ * unknown source FAILS LOUD instead of silently running ESPN — `--source foo`
+ * previously no-op'd, which lied about what the flag did (attribution stayed
+ * honest, but the advertised knob did nothing).
+ */
+declare function makeAdapter(source: string, opts: AdapterOptions): ProviderAdapter;
+/**
+ * Merge live matches over a base set by id. Live entries replace base entries
+ * with the same id; unknown ids are appended.
+ */
+declare function mergeLive(base: Match[], live: Match[]): Match[];
+interface LiveResult {
+    matches: Match[];
+    /** True when the provider call failed and we fell back to static data. */
+    degraded: boolean;
+    /**
+     * The live-data provider that served this result (e.g. "espn"), for
+     * attribution. Absent when `degraded` — the bundled static schedule, served
+     * by no live provider, must not be attributed to one.
+     */
+    source?: string;
+    /**
+     * The season the provider reported for the response behind this result.
+     * Absent when the provider stated none or the fetch failed, and for a live
+     * read at a season turn, whose days state two. A fact about THIS result:
+     * `today 2024-06-14` reports the season of that day.
+     */
+    season?: SeasonInfo;
+    /**
+     * The read says its competition is between editions (see
+     * {@link betweenEditionsOf}): a replacement verdict. The live read's
+     * `matches` is then empty (it keeps the matches in play); the dated read
+     * keeps the window's records, and states it only when the asked local date
+     * holds none of them. Never stated on the bundled competition.
+     */
+    betweenEditions?: BetweenEditions;
+    /**
+     * The read behind the result said it was not whole (see
+     * `VerdictSource.partial`): the provider sent records the result does not
+     * hold. `omitted` is how many, when the read knew it. Absent for a whole
+     * read, for an adapter that said nothing about its answer, and for a failed
+     * read (which is `degraded`).
+     */
+    partial?: {
+        omitted?: number;
+    };
+    /**
+     * The dated read only: the bundled skeleton was merged under the provider's
+     * records (the bundled competition, and no season stated or the bundle's
+     * own). The day's list is then the bundle's, whole, and a fixture whose
+     * record was left out shows without its live state; without it, a record
+     * left out is simply absent. Request-local: never written to a cache.
+     */
+    skeleton?: true;
+    /**
+     * The dated read only, when it succeeded: the ids of the records the
+     * provider's window held (what the overlay served). A surface compares it
+     * with the fixtures it displays (see `dayAttribution`). Request-local: never
+     * written to a cache.
+     */
+    served?: readonly string[];
+}
+/** Human label for a live-data provider name (attribution). Text only. */
+declare function liveSourceLabel(source: string): string;
+/**
+ * Matches for a date, preferring live provider data, falling back to the static
+ * schedule on any provider/network error (graceful degradation).
+ *
+ * Off the bundled competition there is no skeleton to merge, so the window is
+ * asked ACROSS a season turn, as the live read asks it: on a turn day its
+ * three days state two seasons, the records are served as they are, each on
+ * its own day, and the result states no season. On the bundle it is asked
+ * strictly: two seasons there would let the skeleton merge over another
+ * edition's day, and the refusal protects it. Off the bundle a read whose
+ * edition ended before the asked date, with nothing current in it and NOTHING
+ * on the asked local date, says "between editions" ({@link betweenEditionsOf});
+ * a date on or before the end day is a historical question, answered as asked.
+ * `matches` is the window's records in every case: the surface files them by
+ * the viewer's date.
+ *
+ * The result also says what it is made of: `partial` when the window said it
+ * was not whole (the count when it knew it), `skeleton` when the bundled
+ * schedule was merged under the records, and `served`, the ids the window
+ * held. The last two are request-local: a surface reads them to attribute the
+ * day it displays (`dayAttribution`) and to say what an empty day means.
+ *
+ * `tz` is the viewer's zone, the one the surface files the records by (pass
+ * the same effective zone: `resolveTz`). A caller that names none asks in the
+ * provider's zone, the days the window is counted in.
+ */
+declare function getMatchesForDate(adapter: ProviderAdapter, dateISO: string, tz?: string): Promise<LiveResult>;
+interface StandingsResult {
+    /** The tables, sorted by key (`A`, `A1`, `A-B`, `LEAGUE`); each table's rows in standings order. */
+    tables: GroupStandings[];
+    /** True when no authoritative table was available; tables may be a static roster or empty. */
+    degraded: boolean;
+    /** Provider that served the authoritative result, including an empty one (absent when degraded). */
+    source?: string;
+    /**
+     * The verdict of an ALL-TABLES read whose provider sent a table that could
+     * not be read: `tables` holds the ones that were, and is not the whole
+     * competition. Never set on a keyed read: a table that was found was read
+     * (it says `partial` itself if rows are missing), and one that was not found
+     * while a table may be missing is `degraded`, not "no such group".
+     */
+    incomplete?: true;
+}
+/**
+ * Authoritative group tables, preferring the provider's cumulative standings and
+ * FAILING CLOSED when none is available. An adapter with explicit bundled-
+ * roster compatibility may use the roster-at-zero; otherwise it returns an
+ * empty degraded result because expected group letters alone do not prove the
+ * bundle belongs to the same competition.
+ *
+ * Deliberately does NOT compute a table from a live-match window: that silently
+ * drops earlier matchdays and reports a wrong, partial table (e.g. all-zeros for
+ * a group not playing today) — the bug this replaced. A degraded roster is
+ * explicitly zeroed; a confidently-wrong table is the failure mode we refuse.
+ *
+ * An empty `tables` with `degraded: false` means either the fetch succeeded but
+ * the asked-for group wasn't in it, or the group is definitively outside the
+ * adapter's declared scope (caller renders "no such group"). A group declared
+ * in that expected scope but omitted from a partial
+ * provider result takes the degraded fallback instead of rendering as an
+ * authoritative empty table. An aggregate read also falls back when any group
+ * in that scope is absent; one result-level verdict cannot honestly describe a
+ * mix of live tables and static roster tables. Transport failure without
+ * explicit bundled-roster compatibility stays empty and degraded; it must
+ * never borrow the bundled World Cup roster.
+ *
+ * `group` is a table KEY (`A`, `A1`, `A-B`, `LEAGUE`), matched in any case.
+ *
+ * Two different things can be "not whole". A table whose rows were refused is
+ * `partial` (on the table). A provider result from which a whole TABLE is
+ * missing has an incomplete inventory (`fetchMeta`), and what that means
+ * depends on what was asked:
+ *   - with an expected scope, the scope decides, as above (and a table outside
+ *     it is not shown);
+ *   - without one, an all-tables read returns the tables that were read and
+ *     says `incomplete` (when NO table was read it is `degraded`: there is
+ *     nothing to qualify); a keyed read returns the table if it was read, and
+ *     is `degraded` if it was not: the missing table may be the one asked for.
+ */
+declare function getStandings(adapter: ProviderAdapter, group?: string): Promise<StandingsResult>;
+declare function knockoutWindow(): {
+    start: string;
+    end: string;
+} | null;
+/**
+ * Knockout bracket with hybrid slot resolution: confirmed FT winners/losers from
+ * the live overlay; group slots project from live standings once a group has started.
+ */
+declare function getBracket(adapter: ProviderAdapter, opts?: {
+    stage?: Stage;
+    lang?: string;
+}): Promise<BracketResult>;
+interface MatchByIdResult {
+    match?: Match;
+    degraded: boolean;
+    source?: string;
+    /** Off the bundle a fixture list to look an id up in does not exist yet (audit A03). */
+    unsupported?: true;
+    /**
+     * Off the bundle: the span searched for an id that a WHOLE read did not
+     * hold, in the provider's calendar days (`YYYY-MM-DD`, discovery's span:
+     * yesterday to 14 days ahead). "Not found in this window" is not "no such
+     * match": a plain field of the answer, not a verdict.
+     */
+    window?: {
+        from: string;
+        to: string;
+    };
+    /**
+     * The read behind the answer was not whole (see `VerdictSource.partial`):
+     * an absent id is then not known to be absent, and a found record's refresh
+     * left a record out.
+     */
+    partial?: {
+        omitted?: number;
+    };
+    /** The read's edition ended and nothing in it is current (a replacement verdict). */
+    betweenEditions?: BetweenEditions;
+    /**
+     * On the bundle, when the read succeeded: the ids of the records its window
+     * held (what the overlay served), as the dated read states them. A shown
+     * match not among them is the bundled schedule's row, its live state
+     * unconfirmed: the surfaces say so through the day's rule
+     * (`dayAttribution`). Request-local: never written to a cache. Not a verdict.
+     */
+    served?: readonly string[];
+    /**
+     * Off the bundle, with `degraded`: `match` is the provider's own EARLIER
+     * record (read by discovery in this command), whose state could not be
+     * refreshed: the refresh failed, or did not hold it. Not the bundled
+     * schedule, which is what a degraded match is on the bundle. Says which
+     * not-live sentence a surface prints; not a verdict.
+     */
+    earlierRecord?: true;
+}
+/**
+ * The not-live sentence for a match that is the provider's earlier record
+ * (`earlierRecord`), as the share card prints it: English (the card's copy),
+ * the catalog's sentence (`feed.earlierRecord`, which the CLI and the MCP text
+ * print in the reader's language) in parentheses.
+ */
+declare const EARLIER_RECORD_NOTE: string;
+/**
+ * The fixture a team-scoped MARKET query should be about, live-confirmed.
+ * Static window math alone fails twice at the edges: a match in extra time
+ * (now > kickoff + 140min, still LIVE) would be skipped for next week's
+ * fixture, and a just-finished match (inside the window, already FT) would be
+ * selected over the next one. So: pick the in-window candidate using a widened
+ * window, overlay live state, and fall through to the next fixture when the
+ * overlay says the candidate is finished. Degraded fetches keep the static
+ * candidate (fail-closed: the market-relevance gate then errs toward showing
+ * nothing rather than something wrong).
+ */
+declare function marketFixtureForTeam(adapter: ProviderAdapter, code: string, now?: Date): Promise<MatchByIdResult>;
+interface NextFixtureResult {
+    fixture?: Match;
+    /** True when the live overlay fetch failed and only the static skeleton was used. */
+    degraded: boolean;
+    /** The provider that served the live overlay (absent when degraded). */
+    source?: string;
+    /** Off the bundle "next" is built on a schedule we do not have yet (audit A03). */
+    unsupported?: true;
+    /**
+     * Off the bundle: the query as asked, bounded as a label. What the answer's
+     * sentences name when no team was resolved.
+     */
+    query?: string;
+    /** Off the bundle: the club the query resolved to (by its provider id). */
+    team?: Team;
+    /** Off the bundle: two or more clubs matched the query; no fixture is picked. */
+    candidates?: Team[];
+    /**
+     * The roster the competition has holds no team by that name (a replacement
+     * verdict): off the bundle the table read whole and a whole read of the
+     * span; on the World Cup the bundled nations (`nationArg`).
+     */
+    unknownTeam?: true;
+    /** What `unknownTeam` rests on, which its sentence names (see `VerdictSource.rosterEvidence`). */
+    rosterEvidence?: 'table' | 'bundle';
+    /**
+     * Off the bundle: the roster was asked for and could not be read whole (a
+     * table missing or partial, a row with no id, or no answer), and the query
+     * matched no club, or only by a code or a fuzzy name that the unread rest
+     * may share. A replacement verdict, not an outage: the provider answered.
+     */
+    rosterIncomplete?: true;
+    /**
+     * Off the bundle: a WHOLE read of the span held no fixture for the club. The
+     * span in provider days ahead (discovery's): a plain field of the answer,
+     * whose sentence is the empty body's own text, never a verdict.
+     */
+    horizon?: {
+        days: number;
+    };
+    /** Off the bundle: the read's edition ended and nothing in it is current (a replacement verdict). */
+    betweenEditions?: BetweenEditions;
+    /** Off the bundle: the season the discovery stated, when it stated one. */
+    season?: SeasonInfo;
+    /**
+     * The knockout window said its answer was not whole: a record it was sent
+     * is not in it (see `VerdictSource.partial`). `fixture` is still what was
+     * read; a team whose tie was the record left out has none, and that is not
+     * "eliminated". Absent when the window was whole, failed, or said nothing.
+     */
+    partial?: {
+        omitted?: number;
+    };
+}
+/**
+ * A team's next UPCOMING fixture, LIVE-RESOLVED across the knockout phase.
+ *
+ * The bundled schedule's knockout slots are resultless placeholders (home/away
+ * are slot refs like "Group A winner", never a nation — see
+ * {@link sanitizeBundledFixture}), so a purely static lookup goes blind the
+ * moment a team's last GROUP game passes: `next MEX` answers "no upcoming
+ * fixture" even after ESPN has confirmed Mexico's Round-of-32 tie. Overlay the
+ * live knockout window (the SAME window {@link getBracket} asks for) so the
+ * merged set carries the resolved nations, then pick the team's next fixture
+ * with kickoff ≥ now. (Strictly upcoming — the in-play match is `getLiveMatches`'
+ * job, preserving the pre-overlay `next` semantics.)
+ *
+ * Fails closed: on any provider error it falls back to the static result
+ * (`degraded: true`), so a feed outage degrades to "no fixture" rather than
+ * inventing one — advancement is never read from the static skeleton.
+ */
+declare function getNextFixtureForTeam(adapter: ProviderAdapter, code: string, now?: Date): Promise<NextFixtureResult>;
+/**
+ * The next fixture of a SAVED team (`claudinho follow <alias> --team <name>`):
+ * a team already resolved when it was saved, so it is never resolved again.
+ *
+ * Off the bundle: discovery's span as `next <club>` reads it (the same month
+ * requests, the same between-editions question first), and the fixture
+ * selected by `isTeam` with the pin (an id on both decides: a side carrying
+ * another club's id is never the pin's, whatever its labels). No roster is
+ * read: the pin is the identity. `team` is the pin, on every answer; the
+ * verdicts are `next`'s (`partial`, `betweenEditions`; never `unknownTeam` or
+ * `rosterIncomplete`, which are about resolving a name). The team is built by
+ * the one constructor (`sealTeam` with the competition's written kind). On the
+ * bundle the nations carry no id: by code, exactly as `next <code>` answers.
+ */
+declare function nextFixtureForPin(adapter: ProviderAdapter, pin: Pin, now?: Date): Promise<NextFixtureResult>;
+interface KnockoutFixturesResult {
+    /** Resolved (both nations known) upcoming knockout fixtures, sorted by kickoff. */
+    fixtures: Match[];
+    /** True when the overlay fetch failed — caller must NOT cache this as "none". */
+    degraded: boolean;
+    /** Off the bundle there is no knockout window to fetch (audit A03). */
+    unsupported?: true;
+    /**
+     * The season the provider reported for THIS response (absent when it stated
+     * none, or on failure). The fixtures belong to it — which need not be the
+     * season a live read made in the same breath answered for.
+     */
+    season?: SeasonInfo;
+    /**
+     * False when the provider sent records this result does not hold (one it
+     * could not read, or two that contradict each other). A fixture that is
+     * absent from such a result is not known to be gone: a caller that keeps a
+     * previous answer must not let this one erase it. Absent or true otherwise.
+     */
+    complete?: boolean;
+    /**
+     * Stated only with `complete: false`: the id of every fixture this answer
+     * DID read, whatever became of it. `fixtures` holds the ties that are
+     * resolved and still to be played; a tie the provider postponed, cancelled,
+     * started, un-resolved or moved outside the span was read and set aside (the
+     * last by the window itself: see `FetchMeta.mentioned`). A caller keeping a
+     * previous answer must ask "was it read?" of this list, not of `fixtures`,
+     * or it puts back what the provider just took away.
+     */
+    mentioned?: readonly string[];
+    /**
+     * The verdict a surface prints for `complete: false` (see
+     * `VerdictSource.partial`), with the count of records left out when the
+     * window knew it. Stated exactly when `complete` is false.
+     */
+    partial?: {
+        omitted?: number;
+    };
+}
+/**
+ * The RESOLVED upcoming knockout fixtures from the live overlay — the data the
+ * hot-path statusline can't fetch itself but needs to show a real next-match
+ * countdown (e.g. "🇲🇽 vs 🇪🇨 in 2d") instead of a 🏳️ placeholder. The cold-path
+ * refresher calls this and caches the result; the statusline reads the cache.
+ *
+ * Returns only fixtures where BOTH sides are resolved (neither is the 🏳️ placeholder) and kickoff
+ * ≥ now, so a slot ESPN hasn't filled yet is simply absent (the statusline then
+ * fails closed to "⚽ —", never a placeholder). **Fails closed with
+ * `degraded: true` on a provider error** — the caller must keep its prior cached
+ * fixtures rather than cache an empty list as a real "no knockouts" (a transient
+ * outage must never read as "your team is out").
+ */
+declare function getKnockoutFixtures(adapter: ProviderAdapter, now?: Date): Promise<KnockoutFixturesResult>;
+/**
+ * A single match by id, with live overlay. The provider's scoreboard buckets
+ * days in its own zone (ESPN: US/Eastern), so a fixture's UTC date can differ
+ * from the scoreboard day it's filed under — a 02:00Z kickoff belongs to the
+ * previous ET evening, and fetching only the UTC date silently misses its live
+ * state (the match then renders from the static schedule as if scheduled).
+ * Fetch the ±1-day window around the fixture's UTC date instead — the same
+ * trick `getMatchesForDate` uses — and fall back to the static fixture on any
+ * provider error.
+ */
+declare function getMatchById(adapter: ProviderAdapter, id: string, now?: Date): Promise<MatchByIdResult>;
+
+interface ScheduleAheadResult {
+    /** Every fixture read in the span, in ANY status, by kickoff. */
+    fixtures: Match[];
+    /** The schedule could not be had (a failed request, a refused window): the caller keeps what it has. */
+    degraded: boolean;
+    /**
+     * The season every month's response stated, when they all stated the SAME
+     * one (by year); absent when one stated none, when two stated different
+     * ones, or on failure. A month whose list held no readable record states what
+     * its response stated. Two months can state two seasons (the provider's
+     * season turns on June 1): the fixtures of both are returned, and the answer
+     * states none, because no one season describes all of them.
+     */
+    season?: SeasonInfo;
+    /**
+     * False when the provider sent records this result does not hold (one it
+     * could not read, a month whose list held no readable record, one fixture in
+     * both months), or when the adapter says nothing about its answer. A fixture
+     * absent from such a result is not known to be gone. Stated on every answer
+     * that is not `degraded`.
+     */
+    complete?: boolean;
+    /**
+     * Stated with `complete: false`: the id of every fixture either month's
+     * response held, BEFORE the months are narrowed to the span. A caller keeping
+     * a previous answer asks "was it read?" of this list, not of `fixtures` (a
+     * fixture moved beyond the span was read, and must not be put back).
+     */
+    mentioned?: readonly string[];
+    /**
+     * Stated with `complete: false` when the count is known: the provider
+     * records the answer left out (each month's own count, and each second copy
+     * across the months). Absent when a month's count is not known (a month that
+     * read nothing states none). What `partialOfRead` reads beside `complete`.
+     */
+    omitted?: number;
+}
+/**
+ * Discovery's span for a moment, in the PROVIDER's calendar days: from
+ * `SCHEDULE_LOOKBACK_DAYS` back to `SCHEDULE_AHEAD_DAYS` ahead, added as dates
+ * (a daylight-saving change does not move it). One computation, so the span
+ * discovery reads and the span `match <id>` says it searched are the same.
+ */
+declare function scheduleSpan(adapter: ProviderAdapter, now: Date): {
+    start: string;
+    end: string;
+};
+/**
+ * The schedule ahead: every fixture from `SCHEDULE_LOOKBACK_DAYS` back to
+ * `SCHEDULE_AHEAD_DAYS` ahead, counted in the PROVIDER's calendar days and
+ * added as dates (a daylight-saving change does not move the span). What the
+ * cold-path refresher reads, about once an hour, to know when a match can be
+ * in play in a competition the bundled schedule does not describe.
+ *
+ * Each calendar month the span touches is its OWN window, asked whole (first
+ * day to last), so it is exactly one month request whatever part of the month
+ * is in the span (a two- or three-day fragment passed as itself would be asked
+ * a day at a time). One request, or two, sent together and both settled before
+ * this answers (a throttle on one is retained by the adapter whatever the
+ * other did). Two windows, not one window of two months: a response states the
+ * season of the dates asked, and a composed window asked strictly (as these
+ * are) refuses two seasons. So the answer states a season only when every
+ * month stated the same one: discovery's own rule, not the window's (a window
+ * states the season its stating parts agree on).
+ *
+ * "A list that is not empty and holds no readable record is a failure" is
+ * asked of the WHOLE discovery, as a window asks it of all its parts: a month
+ * refused that way (`ProviderError.noReadableRecord`) read nothing, so the
+ * answer is not whole and nothing of that month is in `mentioned`, while the
+ * other month's fixtures are returned. If no month read a record, the
+ * discovery failed. Any other failure of either window fails it:
+ * `degraded`, nothing else.
+ */
+declare function getScheduleAhead(adapter: ProviderAdapter, now?: Date): Promise<ScheduleAheadResult>;
+/**
+ * Currently-live matches; empty + degraded on error.
+ *
+ * The provider buckets its scoreboard by its own day (ESPN: US/Eastern), so a
+ * late kickoff that crossed the day boundary lands in an ADJACENT bucket — a
+ * 04:00Z match still live at 76' while the provider's default "today" bucket
+ * already shows the prior, all-FT day. A bare `adapter.fetchLive()` reads only
+ * that single default bucket, so it silently MISSES such a match and `live` /
+ * the statusline / the hook show "nothing live" mid-match. Fetch the ±1-day UTC
+ * window around `now` instead — the same trick {@link getMatchesForDate} and
+ * {@link getMatchById} use — and filter to in-play, so no live match can hide in
+ * an adjacent bucket. Adapters without a window fetch fall back to `fetchLive()`.
+ */
+declare function getLiveMatches(adapter: ProviderAdapter, now?: Date): Promise<LiveResult>;
+/** A live read with the answer's own account of itself: what the refresher decides from. */
+interface LiveReadResult extends LiveResult {
+    /**
+     * True only when the provider's answer said every record in it was read.
+     * Absent is not true, and a failed read is not whole: a read that is not
+     * whole and holds no match in play does not prove none is.
+     */
+    complete: boolean;
+}
+/**
+ * {@link getLiveMatches}, keeping the window's `complete` verdict (read from
+ * the window's result BEFORE the in-play filter makes a new array). For the
+ * cold-path refresher, which keeps polling after a match was seen in play
+ * until a WHOLE read holds none.
+ */
+declare function getLiveRead(adapter: ProviderAdapter, now?: Date): Promise<LiveReadResult>;
+
+/** A roster team plus its group letter (A–L). */
+interface TeamInfo extends Team {
+    group?: string;
+}
+/**
+ * The 48-team roster from the bundled group-stage fixtures, sorted by name.
+ * Placeholder/knockout slots (non-3-letter code or 🏳️) are skipped.
+ */
+declare function allTeams(fixtures?: Match[]): TeamInfo[];
+interface TeamLookup {
+    query: string;
+    /** The single confident match, or null when the query is ambiguous or unknown. */
+    team: TeamInfo | null;
+    /** All candidate teams, best-first (1+ whenever anything matched). */
+    matches: TeamInfo[];
+}
+/**
+ * Resolve a free-text team name or code to a roster team. Precedence: exact code,
+ * exact name, alias, then prefix/substring fuzzy on the name (fuzzy only for
+ * queries of 3+ letters, so a 1–2 char query can't substring-match noise). A
+ * unique fuzzy hit resolves; multiple hits return as candidates with `team: null`.
+ */
+declare function lookupTeam(query: string, fixtures?: Match[]): TeamLookup;
+/**
+ * A competition's roster, read from its standings, and what that read can
+ * PROVE. Off the bundled competition there is no static roster: the clubs are
+ * whoever the provider's tables hold.
+ */
+interface Roster {
+    /** The tables' teams, one per id (a row with no id is kept, once per code and name). */
+    teams: Team[];
+    /**
+     * True only when the roster can prove a name is NOT in the competition: a
+     * table was asked for, the read was not degraded, no table is missing from
+     * it, none is partial, and every row's team carries an id. Anything less is
+     * "not known", never "no such team": the club behind a refused row cannot be
+     * ruled out, and a row with no id cannot be resolved by identity.
+     */
+    complete: boolean;
+    /**
+     * Whether a table exists to be asked for: false for a competition written
+     * down as having none (`STANDINGS_SHAPE` `none`), whose empty document is a
+     * complete inventory of nobody. The bundle's groups count as asked.
+     */
+    tableAsked: boolean;
+}
+/**
+ * The roster of the adapter's competition, from ONE standings read (all
+ * tables). Not asked at all for a competition with no table. The adapter
+ * shares its standings read for a short while, so a command whose fixture read
+ * already enriched from the standings asks once (a failed read is retried).
+ */
+declare function rosterFor(adapter: ProviderAdapter): Promise<Roster>;
+/** What a club query resolves to (see {@link resolveClub}). */
+type ClubResolution = {
+    outcome: 'resolved';
+    team: Team;
+} | {
+    outcome: 'ambiguous';
+    candidates: Team[];
+} | {
+    outcome: 'unknown';
+} | {
+    outcome: 'unresolved';
+    /**
+     * The teams the query DID match that carry no id (they cannot be
+     * resolved by identity). Empty when it matched nothing.
+     */
+    idless: Team[];
+};
+/**
+ * Resolve a club's name or code against a competition's roster, with the
+ * schedule ahead as POSITIVE evidence: a club found there is known, absence
+ * from fourteen days proves nothing. One function for the CLI and MCP.
+ *
+ * The candidates are `Team`s, never `allTeams` (which keeps three-letter codes
+ * only and one team per code: a real club is `O&M`, and two Libertadores clubs
+ * are both `CAR`). One per id; a team with no id is a candidate only while no
+ * team with an id has its code and name (`sameTeam` as written: the same code
+ * and name are the same team), and it can never be the answer: identity needs
+ * an id. Precedence as {@link lookupTeam}, with no alias table for clubs:
+ * exact code (any case), exact name (normalized), then the name by prefix or
+ * substring for a query of 3+ letters. One hit with an id resolves (one hit
+ * by CODE or by a FUZZY name only when the roster was read whole, or no table
+ * exists: it is not known to be unique otherwise; an exact name resolves
+ * anyway); two or more are `ambiguous` (never a silent pick); none is
+ * `unknown` only when the roster can prove it (`complete`), and `unresolved`
+ * otherwise.
+ */
+declare function resolveClub(query: string, roster: Roster, schedule: readonly Match[]): ClubResolution;
+/**
+ * The World Cup's team argument where a surface also takes club names (the MCP
+ * tools): a 3-letter token is a code, uppercased, as it always was (an unknown
+ * code still passes through: the escape hatch for other feeds); a NAME
+ * resolves against the bundled roster. A name that resolves to no single
+ * nation is answered here, with no request: two or more nations are the
+ * `candidates`, none is `unknownTeam` (the bundled roster is the competition's
+ * whole roster). The same answer for every tool that takes a team.
+ */
+declare function nationArg(query: string): {
+    code: string;
+} | {
+    answer: NextFixtureResult;
+};
+
+/**
+ * Bounded collections — the type that carries its own honesty.
+ *
+ * Every round of review found a list that was capped without saying so, or that
+ * reported a post-cap count as the total, or that said "none found" when it had
+ * simply run out of budget. Those are the same bug three ways: the shape of the
+ * data did not carry what the reader needed to interpret it. A `BoundedList`
+ * cannot be constructed without stating all four facts.
+ */
+interface BoundedList<T> {
+    /** What survived the cap. */
+    readonly items: readonly T[];
+    /**
+     * How many were established before capping. Exact when `complete` is true;
+     * otherwise it may only be a lower bound over the records examined.
+     */
+    readonly total: number;
+    /** `items.length` — kept explicit so a serialized payload is self-describing. */
+    readonly shown: number;
+    /** Did the cap drop anything? */
+    readonly truncated: boolean;
+    /**
+     * Did we finish looking? False when a deadline, error, or partial fetch cut
+     * the work short — so a caller can tell "there are none" from "we don't know".
+     * An empty list with `complete: false` must NEVER render as "nothing found".
+     */
+    readonly complete: boolean;
+}
+/**
+ * Bound a list, recording what that cost.
+ *
  * SLICE BEFORE MAP is the caller's job — this records the outcome, it does not
  * make an unbounded traversal safe. `takeBounded` is the one that bounds work.
  */
@@ -684,8 +2010,39 @@ declare function parsedValue<T>(r: ParseResult<T>): T | undefined;
  */
 declare function isCacheable<T>(r: ParseResult<T>): boolean;
 
+/**
+ * How a competition's standings payload is read. `groups`: every table is
+ * named by one of the group grammars. `league`: the competition is authorised
+ * to serve exactly ONE table, whatever its name (a season, a phase). `none`:
+ * the competition has no table (knockout from the first round), and the
+ * provider answers with its own document and no table list at all; that
+ * answer is then an empty one, not an unreadable one. If such a competition
+ * ever serves a child or a table, nothing is read: it is not what was written
+ * down.
+ */
+type StandingsShape = 'groups' | 'league' | 'none';
 interface MapContext {
+    /**
+     * Group letter by team CODE. Used for a team the feed gave NO id, and for
+     * every team when there is no id map at all (standings rows that carried
+     * none). Never for a team that has an id while an id map exists.
+     */
     groupByTeam?: Record<string, string>;
+    /**
+     * Group letter by team ID. When present it is the ONLY source for a team
+     * that has an id: two teams can share a code (`CAR` is two clubs in the
+     * Libertadores), so a code that happens to match is another team's row, and
+     * a missing row means "no group known", not "try the letters".
+     */
+    groupByTeamId?: Record<string, string>;
+    /**
+     * The competition the payload was asked for (the adapter states its own).
+     * Its WRITTEN kinds decide two things here: whether a team is a nation (a
+     * flag is generated from its name) or a club (none), and which slugs the
+     * stage grammar reads as a league's season (see `stageFromSlug`). Absent:
+     * clubs and a cup, the reading that asserts nothing.
+     */
+    competition?: string;
 }
 
 /**
@@ -700,8 +2057,17 @@ interface MapContext {
  * should be re-verified during an actual live match.
  */
 
-/** Default competition slug (the 2026 World Cup). */
+/** Default competition slug (the 2026 World Cup): the bundled one, written once in the supported table's module. */
 declare const DEFAULT_COMPETITION = "fifa.world";
+/**
+ * Reject declared response bodies past this before JSON.parse — a hijacked
+ * endpoint must not be able to balloon the refresher's memory every ~15s.
+ * (A day's scoreboard is tens of KB; a month's, the largest thing asked for,
+ * was 845 KB for the World Cup's June.) Shared by the Polymarket provider. The
+ * bytes actually read are counted too (`readJsonBounded`), so a body with no
+ * declared length is cut at the same cap.
+ */
+declare const MAX_RESPONSE_BYTES: number;
 /**
  * Provider cooldown after a 429/403 (audit A12): the window a throttled
  * adapter refuses to fetch in. `Retry-After` is honoured in both RFC 9110 forms
@@ -726,15 +2092,41 @@ declare class ProviderError extends Error {
     readonly status?: number;
     /** For a throttle: how long the adapter will refuse to fetch (bounded). */
     retryAfterMs?: number;
-    constructor(message: string, kind: ProviderErrorKind, status?: number);
+    /**
+     * Set on ONE refusal: a response whose envelope was read and whose list was
+     * not empty, but held no record that could be read. It is not a kind of its
+     * own: to every reader of `kind` it is the `parse` failure it always was (for
+     * a single read it is one). A caller that composes several answers into one
+     * (discovery: a window per month) asks this to tell such a list from an
+     * envelope nobody could read, which is refused with the same kind and
+     * without it. `season` is the one that response stated, if it stated one.
+     */
+    readonly noReadableRecord?: {
+        readonly season?: SeasonInfo;
+    };
+    constructor(message: string, kind: ProviderErrorKind, status?: number, detail?: {
+        noReadableRecord?: {
+            readonly season?: SeasonInfo;
+        };
+    });
     /** 429/403 — the upstream is refusing us; retrying at the live cadence makes it worse. */
     get throttled(): boolean;
 }
 /** Map a single ESPN event into the canonical Match model. Exported for tests. */
 declare function mapEspnEvent(ev: unknown, ctx?: MapContext): Match | undefined;
-/** Project an ESPN standings payload onto group tables. Exported for tests. */
-declare function parseStandings(data: unknown): GroupStandings[];
+/**
+ * Project an ESPN standings payload onto group tables. Exported for tests.
+ * `competition` states whose rows these are (its written kind decides whether
+ * a row's team is flagged); absent, the teams are clubs.
+ */
+declare function parseStandings(data: unknown, competition?: string): GroupStandings[];
 interface EspnAdapterOptions {
+    /**
+     * The competition to fetch (an ESPN slug). Default: the 2026 World Cup. The
+     * base URL is derived from it unless `baseUrl` overrides where to fetch.
+     */
+    competition?: string;
+    /** Override the base URL (tests, a custom host). Implies a non-default competition. */
     baseUrl?: string;
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
@@ -757,10 +2149,15 @@ interface EspnAdapterOptions {
 declare class EspnAdapter implements ProviderAdapter {
     private readonly opts;
     readonly name = "espn";
+    readonly competition: string;
+    /** Where this adapter fetches; fixed at construction, like the competition. */
+    private readonly base;
     readonly capabilities: ProviderCapabilities;
     readonly expectedStandingsGroups?: readonly string[];
     readonly standingsFallbackGroups?: readonly string[];
-    /** Short-lived team-code -> group-letter map (built lazily from standings). */
+    /** How this competition's standings payload is read (`standingsShapeOf`, from `STANDINGS_SHAPE`). */
+    private readonly standingsShape;
+    /** Short-lived group-letter maps, by team code and by team id (built lazily from standings). */
     private groupMap?;
     /**
      * One in-flight/recent standings fetch shared by fetchStandings and
@@ -787,6 +2184,8 @@ declare class EspnAdapter implements ProviderAdapter {
     private readonly cooldownListeners;
     private readonly clock;
     constructor(opts?: EspnAdapterOptions);
+    /** The clock this adapter counts by (see `ProviderAdapter.now`). */
+    now(): number;
     /** Epoch ms until which requests are refused, when a cooldown is armed. */
     get cooldownUntil(): number | undefined;
     /**
@@ -808,7 +2207,67 @@ declare class EspnAdapter implements ProviderAdapter {
      */
     private arm;
     fetchByDate(dateISO: string): Promise<Match[]>;
-    fetchWindow(startDate: string, endDate: string): Promise<Match[]>;
+    /**
+     * The provider's calendar day (`YYYY-MM-DD`) for an instant: the day a
+     * fixture kicking off then is filed under. See {@link PROVIDER_ZONE}. Used
+     * to keep, from a month's response, the fixtures a window asked for; the
+     * canary checks the rule against the real feed.
+     */
+    bucketDay(instant: Date): string;
+    /**
+     * Every fixture whose provider day is in `[startDate, endDate]`, composed
+     * from the request forms the provider accepts (see `WINDOW_DAY_REQUESTS`):
+     * never a range. The parts are sent together, so the wait is one timeout,
+     * not one per part, and EVERY part is settled before the window answers: a
+     * throttle that arrives after a sibling's quick failure has armed the
+     * cooldown by the time a caller looks at it.
+     *
+     * ONE result with ONE account, built in the order the parts were asked for
+     * (never the order they arrived in):
+     *   - any part's failure fails the window. A response whose envelope cannot
+     *     be read is a failed part (see `readScoreboard`), whatever its siblings
+     *     hold. If a part was throttled, the window's error is the throttle the
+     *     adapter retains (the one whose deadline is latest, counted from when
+     *     each was received); otherwise it is the first failed part's.
+     *   - a part that filled the request's limit fails the window: its tail is
+     *     unknown.
+     *   - the season. A response states the season of the DATE asked, and a
+     *     competition turns on its own date (June 1, July 1, January 1, ...), so
+     *     the parts of a window can state two. The window states the one its
+     *     stating parts agree on; a part that states none does not veto them.
+     *     Its start and end date are kept only when every stating part stated
+     *     the same one (`agreedSeason`): agreeing on the year is not agreeing on
+     *     when the edition ends. `seasons` lists every distinct season the parts
+     *     stated, in the order asked (empty: none stated). Two seasons are then
+     *     one of two answers:
+     *       strictly (the default): a failure. "Unknown" would be the wrong
+     *         account of a known disagreement: an absent season lets the bundled
+     *         schedule apply, and lets a cached slice from another season stand.
+     *         Every caller that merges the bundle or keeps a slice asks this way.
+     *       `acrossSeasons`: the window is composed, states no `season`, and
+     *         `seasons` names both. A window composes across seasons only when
+     *         its caller merges nothing and keeps no slice, where a refusal would
+     *         spend its requests on a verdict nobody can act on. Three callers
+     *         do: the live read (it keeps only the matches in play); the dated
+     *         read OFF the bundle (there is no skeleton to merge); and the match
+     *         read off the bundle (it refreshes one record it found itself).
+     *     (Discovery states a season by a different rule, every month the same;
+     *     see `getScheduleAhead`. The two stay two.)
+     *   - it is complete only if every part is. `omitted` is the parts' counts
+     *     summed (see `parseEspnEvents`), plus each second copy across parts;
+     *     0 exactly when the window is complete.
+     *   - a fixture is filed under exactly one day, so two parts cannot hold the
+     *     same one. If they ever do, it is the parser's rule for a duplicate:
+     *     the first copy, in the order asked, is the one that counts, the second
+     *     is counted as omitted, and the window says it is not complete. Copies
+     *     are compared BEFORE a month is narrowed to the window, so a second copy
+     *     that falls outside it (the same id, another kickoff) is still a
+     *     contradiction.
+     * Everything but the season is the same in both modes. It is a union of
+     * responses taken moments apart, not one snapshot: a fixture moved between
+     * two parts being answered can be in neither.
+     */
+    fetchWindow(startDate: string, endDate: string, opts?: FetchWindowOptions): Promise<Match[]>;
     /**
      * In-play matches from ESPN's DEFAULT scoreboard bucket only (no `dates`). This
      * single bucket misses a late kickoff ESPN files under an adjacent day, so it
@@ -821,10 +2280,12 @@ declare class EspnAdapter implements ProviderAdapter {
     /** The shared standings fetch (see {@link standingsShared}). */
     private sharedStandings;
     /**
-     * Authoritative, cumulative group tables from the standings endpoint. Throws
-     * on fetch failure. Group-stage only: non-group `children` are filtered out
-     * by {@link parseStandings}; malformed rows are omitted without hiding their
-     * readable siblings.
+     * Authoritative, cumulative tables from the standings endpoint, read for the
+     * shape this competition is written down as (`STANDINGS_SHAPE`). Throws on
+     * fetch failure, and when nothing in the payload could be read. A malformed
+     * row is omitted without hiding its readable siblings (its table says
+     * `partial`); a child that did not become a table is omitted too, and the
+     * result's metadata then says the inventory is not complete.
      */
     fetchStandings(): Promise<GroupStandings[]>;
     /**
@@ -837,229 +2298,43 @@ declare class EspnAdapter implements ProviderAdapter {
      * drift and one command never fetches standings twice.
      */
     fetchGroupMap(force?: boolean): Promise<Record<string, string>>;
-    private fetchScoreboard;
-    private get;
-}
-
-/**
- * The ONE bounded JSON reader for provider responses (audit A11).
- *
- * A declared Content-Length is the cheap early exit; an undeclared (chunked)
- * body used to be materialised in full before any cap applied, so a hijacked
- * or misbehaving upstream could balloon the refresher's memory every cycle.
- * Now the bytes actually consumed from the stream are counted, the read stops
- * and cancels at the cap, and parsing happens only after the whole body has
- * passed the bound. Test doubles without a body stream (`{ ok, json }`) still
- * work: they carry no bytes to bound.
- */
-declare class ResponseTooLargeError extends Error {
-    readonly bytes: number;
-    readonly limit: number;
-    constructor(bytes: number, limit: number);
-}
-/** Parse a JSON body of at most `maxBytes`, counting what is actually read. */
-declare function readJsonBounded(res: Response, maxBytes: number): Promise<unknown>;
-
-/**
- * The ESPN competition slug to fetch live state from. Defaults to the 2026
- * World Cup (`fifa.world`); override with CLAUDINHO_COMPETITION (e.g.
- * `eng.1`, `uefa.champions`, `fifa.friendly`). Only affects the *live* fetch —
- * the bundled static schedule is always the World Cup.
- *
- * Lives in its own module so that both the live layer and the market sidecar
- * read the ONE resolver without importing each other.
- */
-declare function resolveCompetition(explicit?: string): string;
-/** The competition whose schedule ships bundled in the clients: the 2026 World Cup. */
-declare const BUNDLE_COMPETITION = "fifa.world";
-/**
- * True when the bundled World Cup schedule applies to the active competition.
- * Off the bundle, every path built on the skeleton (date merge, `match <id>`,
- * `next`, the bracket, the knockout-fixture cache, the market fixture) must
- * not read it: an empty foreign day showed 104 World Cup fixtures with foreign
- * attribution (audit A03). Real per-competition support is 0.11 (2.1).
- */
-declare function bundleApplies(competition?: string): boolean;
-
-/** Provider names {@link makeAdapter} can construct (the CLI validates against this). */
-declare const KNOWN_SOURCES: readonly ["espn"];
-interface AdapterOptions {
-    /**
-     * Enrich group-stage fixtures with their group letter (one extra standings
-     * request per poll). Default on; the statusline refresher turns it off because
-     * it never renders group letters.
-     */
-    enrichGroups?: boolean;
-    /** Clock, injectable for tests; drives the provider cooldown window. */
-    now?: () => number;
-}
-/**
- * Construct a provider adapter for a `--source` name (default: espn). An
- * unknown source FAILS LOUD instead of silently running ESPN — `--source foo`
- * previously no-op'd, which lied about what the flag did (attribution stayed
- * honest, but the advertised knob did nothing).
- */
-declare function makeAdapter(source?: string, opts?: AdapterOptions): ProviderAdapter;
-/**
- * Merge live matches over a base set by id. Live entries replace base entries
- * with the same id; unknown ids are appended.
- */
-declare function mergeLive(base: Match[], live: Match[]): Match[];
-interface LiveResult {
-    matches: Match[];
-    /** True when the provider call failed and we fell back to static data. */
-    degraded: boolean;
     /**
-     * The live-data provider that served this result (e.g. "espn"), for
-     * attribution. Absent when `degraded` — the bundled static schedule, served
-     * by no live provider, must not be attributed to one.
+     * Both group maps from one standings read. A fixture's team that has an id
+     * is enriched from the id map alone; the code map serves a team with no id,
+     * and every team when the standings rows carried no ids (see `MapContext`).
      */
-    source?: string;
-}
-/** Human label for a live-data provider name (attribution). Text only. */
-declare function liveSourceLabel(source: string): string;
-/**
- * Matches for a date, preferring live provider data, falling back to the static
- * schedule on any provider/network error (graceful degradation).
- */
-declare function getMatchesForDate(adapter: ProviderAdapter, dateISO: string): Promise<LiveResult>;
-interface StandingsResult {
-    /** Group tables in group-letter order; each table's rows in standings order. */
-    tables: GroupStandings[];
-    /** True when no authoritative table was available; tables may be a static roster or empty. */
-    degraded: boolean;
-    /** Provider that served the authoritative result, including an empty one (absent when degraded). */
-    source?: string;
-}
-/**
- * Authoritative group tables, preferring the provider's cumulative standings and
- * FAILING CLOSED when none is available. An adapter with explicit bundled-
- * roster compatibility may use the roster-at-zero; otherwise it returns an
- * empty degraded result because expected group letters alone do not prove the
- * bundle belongs to the same competition.
- *
- * Deliberately does NOT compute a table from a live-match window: that silently
- * drops earlier matchdays and reports a wrong, partial table (e.g. all-zeros for
- * a group not playing today) — the bug this replaced. A degraded roster is
- * explicitly zeroed; a confidently-wrong table is the failure mode we refuse.
- *
- * An empty `tables` with `degraded: false` means either the fetch succeeded but
- * the asked-for group wasn't in it, or the group is definitively outside the
- * adapter's declared scope (caller renders "no such group"). A group declared
- * in that expected scope but omitted from a partial
- * provider result takes the degraded fallback instead of rendering as an
- * authoritative empty table. An aggregate read also falls back when any group
- * in that scope is absent; one result-level verdict cannot honestly describe a
- * mix of live tables and static roster tables. Transport failure without
- * explicit bundled-roster compatibility stays empty and degraded; it must
- * never borrow the bundled World Cup roster.
- */
-declare function getStandings(adapter: ProviderAdapter, group?: string): Promise<StandingsResult>;
-declare function knockoutWindow(): {
-    start: string;
-    end: string;
-} | null;
-/**
- * Knockout bracket with hybrid slot resolution: confirmed FT winners/losers from
- * the live overlay; group slots project from live standings once a group has started.
- */
-declare function getBracket(adapter: ProviderAdapter, opts?: {
-    stage?: Stage;
-    lang?: string;
-}): Promise<BracketResult>;
-interface MatchByIdResult {
-    match?: Match;
-    degraded: boolean;
-    source?: string;
-    /** Off the bundle a fixture list to look an id up in does not exist yet (audit A03). */
-    unsupported?: true;
-}
-/**
- * The fixture a team-scoped MARKET query should be about, live-confirmed.
- * Static window math alone fails twice at the edges: a match in extra time
- * (now > kickoff + 140min, still LIVE) would be skipped for next week's
- * fixture, and a just-finished match (inside the window, already FT) would be
- * selected over the next one. So: pick the in-window candidate using a widened
- * window, overlay live state, and fall through to the next fixture when the
- * overlay says the candidate is finished. Degraded fetches keep the static
- * candidate (fail-closed: the market-relevance gate then errs toward showing
- * nothing rather than something wrong).
- */
-declare function marketFixtureForTeam(adapter: ProviderAdapter, code: string, now?: Date): Promise<MatchByIdResult>;
-interface NextFixtureResult {
-    fixture?: Match;
-    /** True when the live overlay fetch failed and only the static skeleton was used. */
-    degraded: boolean;
-    /** The provider that served the live overlay (absent when degraded). */
-    source?: string;
-    /** Off the bundle "next" is built on a schedule we do not have yet (audit A03). */
-    unsupported?: true;
-}
-/**
- * A team's next UPCOMING fixture, LIVE-RESOLVED across the knockout phase.
- *
- * The bundled schedule's knockout slots are resultless placeholders (home/away
- * are slot refs like "Group A winner", never a nation — see
- * {@link sanitizeBundledFixture}), so a purely static lookup goes blind the
- * moment a team's last GROUP game passes: `next MEX` answers "no upcoming
- * fixture" even after ESPN has confirmed Mexico's Round-of-32 tie. Overlay the
- * live knockout window (the SAME single fetch {@link getBracket} uses) so the
- * merged set carries the resolved nations, then pick the team's next fixture
- * with kickoff ≥ now. (Strictly upcoming — the in-play match is `getLiveMatches`'
- * job, preserving the pre-overlay `next` semantics.)
- *
- * Fails closed: on any provider error it falls back to the static result
- * (`degraded: true`), so a feed outage degrades to "no fixture" rather than
- * inventing one — advancement is never read from the static skeleton.
- */
-declare function getNextFixtureForTeam(adapter: ProviderAdapter, code: string, now?: Date): Promise<NextFixtureResult>;
-interface KnockoutFixturesResult {
-    /** Resolved (both nations known) upcoming knockout fixtures, sorted by kickoff. */
-    fixtures: Match[];
-    /** True when the overlay fetch failed — caller must NOT cache this as "none". */
-    degraded: boolean;
-    /** Off the bundle there is no knockout window to fetch (audit A03). */
-    unsupported?: true;
-}
-/**
- * The RESOLVED upcoming knockout fixtures from the live overlay — the data the
- * hot-path statusline can't fetch itself but needs to show a real next-match
- * countdown (e.g. "🇲🇽 vs 🇪🇨 in 2d") instead of a 🏳️ placeholder. The cold-path
- * refresher calls this and caches the result; the statusline reads the cache.
- *
- * Returns only fixtures where BOTH nations are resolved (flag ≠ 🏳️) and kickoff
- * ≥ now, so a slot ESPN hasn't filled yet is simply absent (the statusline then
- * fails closed to "⚽ —", never a placeholder). **Fails closed with
- * `degraded: true` on a provider error** — the caller must keep its prior cached
- * fixtures rather than cache an empty list as a real "no knockouts" (a transient
- * outage must never read as "your team is out").
- */
-declare function getKnockoutFixtures(adapter: ProviderAdapter, now?: Date): Promise<KnockoutFixturesResult>;
-/**
- * A single match by id, with live overlay. The provider's scoreboard buckets
- * days in its own zone (ESPN: US/Eastern), so a fixture's UTC date can differ
- * from the scoreboard day it's filed under — a 02:00Z kickoff belongs to the
- * previous ET evening, and fetching only the UTC date silently misses its live
- * state (the match then renders from the static schedule as if scheduled).
- * Fetch the ±1-day window around the fixture's UTC date instead — the same
- * trick `getMatchesForDate` uses — and fall back to the static fixture on any
- * provider error.
- */
-declare function getMatchById(adapter: ProviderAdapter, id: string): Promise<MatchByIdResult>;
-/**
- * Currently-live matches; empty + degraded on error.
- *
- * The provider buckets its scoreboard by its own day (ESPN: US/Eastern), so a
- * late kickoff that crossed the day boundary lands in an ADJACENT bucket — a
- * 04:00Z match still live at 76' while the provider's default "today" bucket
- * already shows the prior, all-FT day. A bare `adapter.fetchLive()` reads only
- * that single default bucket, so it silently MISSES such a match and `live` /
- * the statusline / the hook show "nothing live" mid-match. Fetch the ±1-day UTC
- * window around `now` instead — the same trick {@link getMatchesForDate} and
- * {@link getMatchById} use — and filter to in-play, so no live match can hide in
- * an adjacent bucket. Adapters without a window fetch fall back to `fetchLive()`.
+    private groupMaps;
+    private fetchScoreboard;
+    /**
+     * One scoreboard response, parsed, with the parser's account of it. The
+     * "a non-empty payload with no readable record is a failure" rule is NOT
+     * applied here: it belongs to the whole answer, and a window is one answer
+     * made of several of these. An unreadable ENVELOPE is refused here, for
+     * every caller: it says nothing about its day, so no sibling can stand in
+     * for it (and a single read of one always was a failure).
+     */
+    private readScoreboard;
+    private get;
+}
+
+/**
+ * The ONE bounded JSON reader for provider responses (audit A11).
+ *
+ * A declared Content-Length is the cheap early exit; an undeclared (chunked)
+ * body used to be materialised in full before any cap applied, so a hijacked
+ * or misbehaving upstream could balloon the refresher's memory every cycle.
+ * Now the bytes actually consumed from the stream are counted, the read stops
+ * and cancels at the cap, and parsing happens only after the whole body has
+ * passed the bound. Test doubles without a body stream (`{ ok, json }`) still
+ * work: they carry no bytes to bound.
  */
-declare function getLiveMatches(adapter: ProviderAdapter, now?: Date): Promise<LiveResult>;
+declare class ResponseTooLargeError extends Error {
+    readonly bytes: number;
+    readonly limit: number;
+    constructor(bytes: number, limit: number);
+}
+/** Parse a JSON body of at most `maxBytes`, counting what is actually read. */
+declare function readJsonBounded(res: Response, maxBytes: number): Promise<unknown>;
 
 /**
  * Choosing one of several, and reporting on a batch.
@@ -1257,6 +2532,17 @@ declare function mapsCleanly(match: Match, outcomes: MarketOutcome[]): boolean;
 declare function marketSignalRendersFor(match: Match, signal: MarketSignal): boolean;
 /** Sanity check: ≥2 priced outcomes whose probabilities sum to ~1. */
 declare function hasSaneDistribution(outcomes: MarketOutcome[]): boolean;
+/**
+ * May this signal be SHOWN beside this fixture? Only if it still belongs to the
+ * fixture being rendered ({@link marketSignalRendersFor} — display labels come
+ * from the Match, so a signal cached for a pairing that has since degraded to
+ * a placeholder must not print), is not ambiguous, has a determinable
+ * favorite, and its distribution is sane.
+ *
+ * THE display rule, for every surface. The CLI and the MCP server each carried
+ * a copy of it; a rule that exists twice is a rule one copy will forget.
+ */
+declare function marketDisplayable(match: Match, signal: MarketSignal): boolean;
 /**
  * Is the signal outside the freshness window? Unparseable timestamps are stale.
  *
@@ -1302,6 +2588,21 @@ declare function buildMarketSignal(input: BuildSignalInput): MarketSignal;
  * percent on purpose, to avoid implying false precision.
  */
 
+/**
+ * What a market read says about a competition outside the sidecar's scope
+ * (see `MARKET_COMPETITIONS`): there the sidecar is a network-free no-op, and
+ * the copy says so instead of reporting a "no signal" it never looked for.
+ * One sentence, in the copy bank: the CLI and the MCP server each had it. Its
+ * structured twin is `marketScopeVerdict`.
+ */
+declare const MARKETS_SCOPE_NOTE = "Market signals cover the World Cup only; none are read for this competition.";
+/**
+ * The empty body of a dated market answer whose FIXTURE read was not whole:
+ * no signal among the fixtures that were read, which is not "none for the
+ * date". Market copy, so English on every locale like the rest of the bank;
+ * the card builder's `marketsNoneRead` says when it applies.
+ */
+declare function marketsNoneReadNote(date: string): string;
 /** Human label for the data source (text only — never a logo). */
 declare function marketSourceLabel(source: string): string;
 /** One-line favorite read, drawn only from the approved copy bank. */
@@ -1329,10 +2630,28 @@ declare function marketBlock(signal: MarketSignal, match: Match): string[];
  * slug that cannot exist, so the sidecar is switched off by construction
  * instead of issuing doomed requests. Supporting a league is slug-derivation,
  * mapping and validation work per competition — not widening this set.
+ * Derived from the supported table (`markets: 'offered'`), like every written
+ * fact of a competition.
  */
 declare const MARKET_COMPETITIONS: ReadonlySet<string>;
-/** Whether the market sidecar can say anything about the active competition. */
-declare function marketsCoverCompetition(competition?: string): boolean;
+/** Whether the market sidecar can say anything about a competition. */
+declare function marketsCoverCompetition(competition: string): boolean;
+/**
+ * The verdict a market read with NOTHING TO SHOW states about its competition:
+ * outside the sidecar's scope, "none" means "not read for this competition",
+ * which is not "none found". A surface passes this to `verdictExtras` so a
+ * day's read off scope says so in its structured output, as the by-team and
+ * by-id reads do through their fixture lookup.
+ *
+ * `shown` is how many signals the read is about to display. A read that shows
+ * some states no such verdict, whatever the competition: the demo source
+ * (`CLAUDINHO_MARKETS_SOURCE=fake`) synthesizes signals for any competition,
+ * and the text beside them says nothing about scope. Text and structured
+ * output decide on the same two facts.
+ */
+declare function marketScopeVerdict(competition: string, shown: number): {
+    unsupported?: true;
+};
 /**
  * Resolve the market-data source: explicit arg > CLAUDINHO_MARKETS_SOURCE env >
  * 'polymarket' (mirrors resolveCompetition). Set CLAUDINHO_MARKETS_SOURCE=fake
@@ -1340,11 +2659,15 @@ declare function marketsCoverCompetition(competition?: string): boolean;
  */
 declare function resolveMarketSource(explicit?: string): string;
 /**
- * Construct a market-signal provider. Defaults to the Polymarket public-data
- * adapter; honors CLAUDINHO_MARKETS_SOURCE ('fake' = network-free synthetic
- * demo data; 'none'/'off' = network-free no-op). Tests usually inject directly.
+ * Construct a market-signal provider for one competition. Defaults to the
+ * Polymarket public-data adapter; honors CLAUDINHO_MARKETS_SOURCE ('fake' =
+ * network-free synthetic demo data; 'none'/'off' = network-free no-op). Tests
+ * usually inject directly.
+ *
+ * The competition is the REQUEST'S (its adapter's), passed in — the sidecar
+ * never asks the environment which competition it is serving.
  */
-declare function makeMarketProvider(source?: string): MarketProvider;
+declare function makeMarketProvider(source: string | undefined, competition: string): MarketProvider;
 /** Fetch one match's signal; never throws — undefined on any error. */
 declare function getMarketSignal(provider: MarketProvider, match: Match, options?: MarketSignalOptions): Promise<MarketSignal | undefined>;
 /** Batch fetch; never throws — an empty, INCOMPLETE batch on any error. */
@@ -1387,6 +2710,19 @@ declare const MAX_LABEL_COLUMNS = 100;
  * Total: never throws, whatever the input.
  */
 declare function humanLabel(value: unknown, maxColumns?: number): string;
+/**
+ * Is this value ALREADY a human label, as a reader typed it: the role leaves
+ * it as it is, up to NFC and ordinary spaces at its ends (`' Arsenal '` is a
+ * label). For INPUT that must be refused rather than repaired (a tool
+ * argument): the same grammar `humanLabel` applies, asked as a question, of
+ * the RAW value. So a code point the role forbids is refused ANYWHERE, ends
+ * included (a control such as a tab or a newline, a format character such as
+ * a byte-order mark, a line or paragraph separator, anything invisible):
+ * comparing after a trim would hide one at an end, and a newline at the end
+ * of an argument splits the run cue it is pasted into. Then an emoji, or a
+ * tail past the column bound, which the role would drop, is refused too.
+ */
+declare function isHumanLabel(value: unknown, maxColumns?: number): boolean;
 /**
  * A flag, GENERATED from the bundled map — never accepted from anywhere.
  *
@@ -1399,6 +2735,69 @@ declare function humanLabel(value: unknown, maxColumns?: number): string;
  */
 declare function productFlag(nameOrCode: string | undefined): string;
 
+/** A league (its season is the regular stage), a cup (rounds and phases), or the friendly competition. */
+type CompetitionKind = 'league' | 'cup' | 'friendly';
+/**
+ * The teams each competition fields: the supported table's (`nation` for the
+ * World Cup, the Euro, the Copa America, both Nations Leagues and the Gold
+ * Cup; `club` for the six leagues and the four club cups), and the friendly
+ * competition's (`nation`). An unlisted competition fields clubs: a nations
+ * competition the set does not list renders its teams by name until it is
+ * written down.
+ */
+declare const TEAM_KIND: Readonly<Record<string, TeamKind>>;
+/** The teams a competition fields; an unlisted (or absent) competition fields clubs. */
+declare function teamKind(competition: string | undefined): TeamKind;
+/**
+ * Each competition's kind: the supported table's (`league`: the six leagues,
+ * whose regular season the stage grammar reads as `REGULAR`; `cup`: the other
+ * ten), and `friendly` for `fifa.friendly`, the one competition whose
+ * `friendly` slug is the `FRIENDLY` stage.
+ */
+declare const COMPETITION_KIND: Readonly<Record<string, CompetitionKind>>;
+/** A competition's kind; an unlisted (or absent) competition is a cup, the kind that asserts nothing. */
+declare function competitionKind(competition: string | undefined): CompetitionKind;
+/**
+ * The season NAME a league's regular season is filed under (the table's
+ * `seasonSlug`): `2026-27-english-premier-league`, `2026-27-laliga`,
+ * `2026-27-italian-serie-a`, `2026-27-german-bundesliga` on the real feed. The
+ * year in front varies; the name is this one, matched whole. `mex.1` has none.
+ */
+declare const SEASON_SLUG: Readonly<Record<string, string>>;
+/**
+ * What a competition's standings are, where it is not lettered or numbered
+ * GROUPS (the default, also for a competition that is not listed): the
+ * table's `standings`.
+ *   - `league`: the competition is authorised to serve exactly ONE table (a
+ *     season, a league phase). That is a fact about the competition, written
+ *     down; it is never inferred from a payload having one child, because a
+ *     grouped competition whose payload shrinks to one group is not a league.
+ *   - `none`: the competition has no table (knockout from the first round).
+ *     The provider then answers with no table list at all, and for such a
+ *     competition, and only for one, that is an empty answer rather than an
+ *     unreadable one. The canary checks the feed against it: the day it serves
+ *     a table, that is a changed shape.
+ * Read through {@link standingsShapeOf}, never by a bare index.
+ */
+declare const STANDINGS_SHAPE: Readonly<Record<string, 'league' | 'none'>>;
+/**
+ * How a competition's standings payload is read: its written shape, or
+ * `groups` for one not written down. By own property: a bare index on the
+ * table gave a competition named like a prototype key (`constructor`) the
+ * `Object` function as its shape.
+ */
+declare function standingsShapeOf(competition: string | undefined): StandingsShape;
+/**
+ * Is this side Mexico's national team: the team the rally cry ("¿Y si sí?")
+ * belongs to? The Mexico case of the rally table's rule (`rally.ts`): by
+ * IDENTITY, in a competition that fields nations: the provider's id when the
+ * side carries one (a present id that is not Mexico's is never Mexico,
+ * whatever its labels say), or, for the bundle's id-less Mexico, its code AND
+ * its name. A club abbreviated `MEX` never is; neither is Mexico's id read
+ * under a club competition.
+ */
+declare function isMexicoNationalTeam(team: Team, kind: TeamKind): boolean;
+
 /**
  * The single place a `Match` is sealed — whichever path it arrived by.
  *
@@ -1428,6 +2827,7 @@ declare function productFlag(nameOrCode: string | undefined): string;
 interface MatchParts {
     id?: unknown;
     stage?: unknown;
+    stageLabel?: unknown;
     group?: unknown;
     kickoff?: unknown;
     venue?: unknown;
@@ -1443,6 +2843,35 @@ interface MatchParts {
     updatedAt?: unknown;
     events?: unknown;
 }
+/**
+ * Is this side THE team a reader asked about — for SELECTING a team's fixture
+ * (`next`, the next card's label), never for the pairing question
+ * {@link sameTeam} answers.
+ *
+ * When both carry a provider id, the ids decide, alone: a side carrying
+ * another club's id is that other club, whatever its labels say (contradictory
+ * data is not this team's fixture). When either has none, the same code AND
+ * name (a side the provider sent without an id). `sameTeam` is the generous
+ * one, by design: for "can these two play each other" a shared label is
+ * already a refusal.
+ */
+declare function isTeam(side: Team, team: Team): boolean;
+/**
+ * Is this side the PINNED team (`claudinho follow --team`): the one rule for
+ * every line or list that prefers the pin (the statusline's and the hook's
+ * pick, the rally cry between two sides that both carry one). A pin with no
+ * id (the World Cup's nations, which the config reader believes on the
+ * bundled competition alone) by its CODE, the bundle's contract: a nation's
+ * FIFA code is unique there, and the feed's name need not be the bundle's
+ * ("United States of America" for the saved "United States"). A pin with an
+ * id by {@link isTeam}: equal ids decide when the side carries one too, the
+ * code and the name when it carries none.
+ */
+declare function isPinnedSide(side: Team, pin: {
+    readonly id?: string;
+    readonly code: string;
+    readonly name: string;
+}): boolean;
 /**
  * Validate candidate parts into a Match, or say why not.
  *
@@ -1464,6 +2893,14 @@ interface SealOptions {
      * needs ZERO. Cheapest work is work not done.
      */
     readonly events?: boolean;
+    /**
+     * The teams' kind, a written fact of the competition the record belongs to
+     * (`teamKind(competition)`): a `nation` side's flag is generated from its
+     * name, a `club` side has none. Default `club`: a kind nobody stated vouches
+     * for nothing, so no flag is generated from a name that merely looks like a
+     * region. Every reader of a cached match states its competition's kind.
+     */
+    readonly teamKind?: TeamKind;
 }
 declare function sealMatch(parts: MatchParts, opts?: SealOptions): ParseResult<Match>;
 /**
@@ -1478,6 +2915,66 @@ declare function parseCachedMatch(raw: unknown, opts?: SealOptions): ParseResult
 /** Cached fixtures, bounded BEFORE the per-record work. */
 declare function parseCachedMatches(raw: unknown, max: number, opts?: SealOptions): BoundedList<Match>;
 
+/**
+ * The season a provider reported for one response — sealed here, whether it
+ * arrived in a feed payload or was read back from our own cache file.
+ *
+ * A season is METADATA of a result. It is never part of what a request selects
+ * (a request selects a competition), and nothing may assume one before a
+ * provider has said it: the statusline, which reads only the cache, cannot know
+ * that a newer season exists and must not claim to.
+ */
+
+/**
+ * THE constructor of a `SeasonInfo`. The year is the fact; without a readable
+ * one there is no season to report. Label and dates are optional decorations:
+ * an unreadable one is dropped, never substituted.
+ */
+declare function sealSeason(raw: unknown): SeasonInfo | undefined;
+
+/**
+ * The schedule INDEX: one small record per fixture the refresher knows about,
+ * sealed here whether it was just read from a provider or read back from our
+ * own cache file. It is what decides, off the bundled competition, whether a
+ * match can be in play — so a record carries exactly what that decision needs
+ * and nothing a file could use to stretch it: a window is always the kickoff
+ * plus a fixed length, never a stored end.
+ */
+
+/** One fixture the schedule knows: its id, its kickoff, and whether it has a live window. */
+interface ScheduleEntry {
+    readonly id: string;
+    /** A canonical instant. */
+    readonly kickoff: string;
+    /** False for a postponed, cancelled or finished fixture: known, and opening no window. */
+    readonly on: boolean;
+}
+/**
+ * Whether a fixture in this status has a live window: not postponed, not
+ * cancelled, and not finished (nothing is left to poll for, and nothing to call
+ * live). THE rule, for the index (`scheduleEntryOf`) and for the statusline
+ * reading the slice's display records. A match seen IN PLAY is held by the
+ * refresher's continuation, not by its entry.
+ */
+declare function hasLiveWindow(status: Status): boolean;
+/**
+ * The most records an index holds. A 16-day span of the busiest competition
+ * measured holds about 80. An index is whole or it does not exist: a longer
+ * one is not cut somewhere, it is no schedule.
+ */
+declare const MAX_SCHEDULE_INDEX = 256;
+/** THE constructor of a schedule entry. */
+declare function sealScheduleEntry(raw: unknown): ScheduleEntry | undefined;
+/** A fixture's entry; none if the fixture has no id or no instant. */
+declare function scheduleEntryOf(m: Match): ScheduleEntry | undefined;
+/**
+ * A stored index, read back. Not a list, or longer than the bound: no schedule
+ * at all (decided before a record is looked at; never read as a prefix). A
+ * record that cannot be sealed does not count; an id held twice counts once,
+ * the first. In kickoff order.
+ */
+declare function parseCachedScheduleIndex(raw: unknown): ScheduleEntry[] | undefined;
+
 /**
  * Validate a market signal, or say why not.
  *
@@ -1539,6 +3036,24 @@ declare class PolymarketProvider implements MarketProvider {
     private toSignal;
 }
 
+/**
+ * The one non-affiliation sentence (0.11, ledger D5 option B). A leaf: every
+ * runtime surface imports it (the share card footer, the CLI's help footer and
+ * its English localized footer, the MCP server's footer), and the static copies
+ * that cannot import it (the listing JSON files, the public Markdown) are pinned
+ * to it by `test/disclaimer.test.ts`. A listing host is added by
+ * `disclaimerLine(host)`, the only composition: never a second spelling.
+ */
+/** Not affiliated with FIFA, any confederation, league or club, or Anthropic. */
+declare const DISCLAIMER = "Not affiliated with FIFA, any confederation, league or club, or Anthropic.";
+/** The fan line every footer pairs with the disclaimer. */
+declare const FAN_PROJECT = "Independent fan project";
+/**
+ * The disclaimer, with `, nor with <host>` before its final period when a host
+ * is given (a listing's own host: "Smithery", "Cursor").
+ */
+declare function disclaimerLine(host?: string): string;
+
 /** The two v1 snippet shapes. `social` is the rich card; `compact` is one terse line per match. */
 type ShareStyle = 'compact' | 'social';
 /** The project social tag — a distribution unit, default-on but removable. */
@@ -1547,7 +3062,7 @@ declare const SHARE_HASHTAG = "#VibingLaVidaLoca";
  * The non-affiliation line. Non-optional in every snippet: a shared artifact is
  * decontextualized, so the legal disclaimer must travel with every paste.
  */
-declare const SHARE_DISCLAIMER = "Independent fan project \u00B7 not affiliated with FIFA or Anthropic.";
+declare const SHARE_DISCLAIMER = "Independent fan project \u00B7 Not affiliated with FIFA, any confederation, league or club, or Anthropic.";
 interface ShareSnippetOptions {
     /** Snippet shape; defaults to `social`. */
     style?: ShareStyle;
@@ -1578,16 +3093,31 @@ interface ShareSnippetInput {
      * ZZZ."), so an unknown/empty target yields a clear card instead of a void.
      */
     emptyNote?: string;
+    /**
+     * A sentence that QUALIFIES the card (a verdict's, e.g. "Fixture data may
+     * be incomplete."): printed whenever it is set, right after the title and
+     * BEFORE the body, on a populated card and an empty one alike. A card is
+     * pasted where nobody can ask, so what it holds must not look like all
+     * there was. (A verdict that REPLACES the body is the `emptyNote`.)
+     */
+    note?: string;
     /** Exact run cue to advertise, e.g. "npx @claudinho/cli next MEX". */
     installLine?: string;
     /**
      * True when the live fetch failed and these are static fixtures (no live
      * scores). A pasted card must say so — otherwise a "no matches" / scheduled
      * card reads as authoritative when the feed is actually down. When set with
-     * matches present, a not-live notice is appended; for the empty case the
-     * caller picks a feed-down `emptyNote`.
+     * matches present, a not-live notice is printed before the matches (after
+     * the `note`); for the empty case the caller picks a feed-down `emptyNote`.
      */
     degraded?: boolean;
+    /**
+     * The not-live sentence a degraded card with records prints, when its
+     * builder knows better than the default (which says the records are the
+     * bundled schedule's): off the bundled competition a match card's record is
+     * the provider's own earlier one.
+     */
+    degradedNote?: string;
     /** Timezone for kickoff date/time (date/time only — copy stays English). */
     tz?: string;
     /** Locale for kickoff date/time. */
@@ -1600,9 +3130,17 @@ interface ShareSnippetInput {
  */
 declare function formatShareSnippet(input: ShareSnippetInput, options?: ShareSnippetOptions): string;
 interface ShareTableInput {
+    /**
+     * The card's first line, naming the competition (`Premier League ·
+     * standings`), before the tables (each keeps its own title); absent on a
+     * card built with no competition.
+     */
+    heading?: string;
     /** Group tables to render (1..n); each in standings order. */
     tables: readonly {
         group: string;
+        /** The provider's name for the table; absent for a lettered group. */
+        label?: string;
         rows: readonly StandingRow[];
         /** Rows the provider served that could not be read (see GroupStandings). */
         partial?: {
@@ -1615,6 +3153,12 @@ interface ShareTableInput {
     installLine?: string;
     /** Body line when there are no tables (e.g. "No group Z."). */
     emptyNote?: string;
+    /**
+     * Stated before the tables when they are not the whole competition (a table
+     * the provider sent could not be read). A card is pasted where nobody can
+     * ask: the tables that were read must not look like all of them.
+     */
+    incompleteNote?: string;
     /**
      * True when no authoritative table was available. Non-empty rows are a
      * static roster, not live results; an empty open-scope outage is described by
@@ -1631,33 +3175,6 @@ interface ShareTableInput {
  */
 declare function formatShareTable(input: ShareTableInput, options?: ShareSnippetOptions): string;
 
-declare function matchKey(stage: Stage, index: number): string;
-/**
- * Build and validate bracket topology from knockout fixtures.
- * Throws when ESPN introduces an unparsed placeholder or the graph is inconsistent.
- */
-declare function buildBracketTopology(matches: Match[], generatedAt: string): BracketTopology;
-
-/**
- * Parse an ESPN home/away label into a bracket slot reference (name patterns only).
- * Real nation flags are mapped to `seed` — never `team` — so the bundled schedule
- * cannot treat ESPN pre-draw labels as confirmed participants.
- */
-declare function parseTeamSlot(team: Team): SlotRef | null;
-
-/**
- * Resolve the bundled topology against merged knockout matches and standings.
- * Group slots project from live standings once a group has started; confirmed when
- * the group is fully played. Winner/loser slots require a confirmed FT result.
- */
-declare function buildBracketView(topology: BracketTopology, matches: Match[], tables: GroupStandings[], standingsDegraded: boolean, liveDegraded: boolean, filterStage?: string, lang?: string): BracketView;
-
-/** True when a team carries a real nation flag (not a bracket placeholder). */
-declare function isResolvedNation(team: Team): boolean;
-
-/** The bundled knockout bracket topology (generated by gen:schedule). */
-declare function loadBracketTopology(): BracketTopology;
-
 interface BracketFormatOpts {
     flags?: boolean;
     tz?: string;
@@ -1678,10 +3195,24 @@ declare function formatBracketTree(view: BracketView, opts?: BracketFormatOpts &
     footer?: boolean;
 }): string | null;
 interface ShareBracketInput {
+    /**
+     * The card's first line, as its builder states it in the reader's language
+     * (`Knockout bracket · World Cup`: the title, then the competition's name;
+     * no year, the ties carry their dates). Absent on an input built by hand,
+     * whose first line is the title in the options' locale.
+     */
+    title?: string;
     view: BracketView;
     source?: string;
     installLine?: string;
     emptyNote?: string;
+    /**
+     * A sentence that QUALIFIES the card (a verdict's, e.g. "Fixture data may
+     * be incomplete."): printed whenever it is set, after the title and BEFORE
+     * the tree, on a populated card and an empty one alike. (A verdict that
+     * REPLACES the tree is the `emptyNote`.)
+     */
+    note?: string;
 }
 interface ShareBracketOptions {
     includeHashtag?: boolean;
@@ -1696,4 +3227,688 @@ declare function formatShareBracket(input: ShareBracketInput, options?: ShareBra
 /** Compact one-line-per-match bracket for narrow share contexts. */
 declare function formatBracketCompactLine(mv: BracketMatchView, opts?: BracketFormatOpts): string;
 
-export { BRACKET_STAGE_ORDER, BUNDLE_COMPETITION, type BatchResolution, type BoundedList, type BracketFormatOpts, type BracketMatchNode, type BracketMatchView, type BracketResult, type BracketTopology, type BracketView, type BuildSignalInput, DEFAULT_COMPETITION, DEFAULT_COOLDOWN_MS, DEFAULT_FLAVOR, DEFAULT_MAX_AGE_MS, EspnAdapter, type EspnAdapterOptions, FLAVOR_LEVELS, FakeMarketProvider, type FakeMarketProviderOptions, type FavoriteStrength, type FlavorLevel, type FormatOpts, type GroupStandings, KNOCKOUT_EXTRA_TIME_MS, KNOWN_SOURCES, type KnockoutFixturesResult, LIVE_WINDOW_MS, type Lang, type LedgerRow, type LiveResult, MARKET_COMPETITIONS, MAX_COOLDOWN_MS, MAX_LABEL_COLUMNS, type MapContext, type MarketFavorite, type MarketMapping, type MarketMappingTable, type MarketOutcome, type MarketOutcomeKind, type MarketProvider, type MarketSignal, type MarketSignalOptions, type MarketSignalsResult, type Match, type MatchByIdResult, type MatchEvent, type NextFixtureResult, type Outcome, type ParseResult, PolymarketProvider, type PolymarketProviderOptions, type ProviderAdapter, type ProviderCapabilities, ProviderError, type ProviderErrorKind, type PunditPick, type ResolvedParticipant, ResponseTooLargeError, SHARE_DISCLAIMER, SHARE_HASHTAG, type Selection, type ShareBracketInput, type ShareBracketOptions, type ShareSnippetInput, type ShareSnippetOptions, type ShareStyle, type ShareTableInput, type SlotRef, type Stage, type StandingRow, type StandingsResult, type Status, type Team, type TeamInfo, type TeamLookup, allFixtures, allTeams, ambiguous, asFlavorLevel, bounded, buildBracketTopology, buildBracketView, buildMarketSignal, bundleApplies, byKickoff, cacheableKeys, competitionBase, computeStandings, countdown, currentOrNextFixtureForTeam, definitiveNone, deriveFavorite, displayWidth, emptyBatch, favoriteStrength, fixturesByDate, fixturesByGroup, fixturesByTeam, fixturesInLiveWindow, flagEmoji, formatBracketCompactLine, formatBracketList, formatBracketMatchLine, formatBracketTree, formatDate, formatKickoff, formatShareBracket, formatShareSnippet, formatShareTable, formatTime, getBracket, getKnockoutFixtures, getLiveMatches, getMarketSignal, getMarketSignals, getMatchById, getMatchesForDate, getNextFixtureForTeam, getStandings, groups, hasSaneDistribution, humanLabel, isCacheable, isFinished, isFlavorLevel, isLive, isReliableMarketSignal, isResolvedNation, isStaleSignal, isTournamentWindowOver, isUpcoming, isValidDate, isValidTimeZone, knockoutWindow, liveSourceLabel, liveWindowMsFor, loadBracketTopology, localDate, lookupTeam, makeAdapter, makeMarketProvider, malformed, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, marketSignalRendersFor, marketSourceLabel, marketsCoverCompetition, matchFlavor, matchKey, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, normalizeLang, normalizeOutcomes, outcomeFromScore, padVisible, parseCachedMarketSignal, parseCachedMatch, parseCachedMatches, parseStandings, parseTeamSlot, parsedValue, productFlag, readJsonBounded, resolveCompetition, resolveMarketSource, resolveTz, resolvedValues, retryAfterMs, sanitizeBundledFixture, scoreline, sealMarketSignal, sealMatch, selectOne, stageLabel, stageLabelI18n, t, truncateVisible, unresolved, valid };
+/**
+ * Share cards, assembled once.
+ *
+ * `claudinho share` and the MCP `get_share_snippet` tool hand out the same
+ * artifact, and each used to build it for itself: the title, the note an empty
+ * card shows, the run cue, which provider (if any) is attributed. Two copies of
+ * that assembly is two places for a verdict to be dropped and for the copy to
+ * drift. A surface now gets the card from here and only decides how to
+ * serialize it — and, for the MCP server, how many records it may hold: the
+ * builders take the caller's list, so a surface that bounds its payload passes
+ * the bounded one.
+ *
+ * Copy stays English (see AGENTS.md: share snippets are English-only in v1,
+ * except the localized bracket card); the sentences that ARE localized here
+ * are a verdict's, which are the same sentences on every surface. A verdict
+ * that replaces the body becomes the card's `emptyNote`; the ones that qualify
+ * it become its `note`, printed beside a populated body and an empty one.
+ *
+ * The empty bodies off the bundled competition say what was searched: `next`
+ * ("no fixture for X within the next 14 days") and `match <id>` ("not found
+ * between A and B") after a whole read, and "none read" after one that was not
+ * whole ("no fixture for X was read in this span", beside the partial
+ * sentence). They are the BODY's own text, not verdicts, and they are built
+ * here ({@link nextHorizonSentence}, {@link matchWindowSentence},
+ * {@link nextNoneReadSentence}, {@link matchNoneReadSentence}) for every
+ * surface: the CLI and the MCP tools print the same sentence, from this one
+ * place, and a card carries its span as a plain field (`span`).
+ *
+ * The same holds for the live and dated reads (0.11 2.1d): an empty body after
+ * a read that was not whole says nothing was READ ({@link liveNoneRead},
+ * {@link dateNoneRead}, {@link marketsNoneRead}), and a day's attribution on
+ * such a read is decided over the fixtures a surface displays
+ * ({@link dayAttribution}: the "Live data" line, and the sentence counting
+ * the bundled rows the read did not serve).
+ */
+
+/**
+ * The sentence for a `next` whose WHOLE read of the span held no fixture for
+ * the club (`horizon` stated), in the reader's language; undefined otherwise.
+ * It names the resolved club, else the query as asked, else `fallback`.
+ */
+declare function nextHorizonSentence(result: NextFixtureResult, fallback: string, lang: string | undefined): string | undefined;
+/**
+ * The sentence for a `match <id>` that a WHOLE read of the span did not hold
+ * (`window` stated), in the reader's language; undefined otherwise. Not "no
+ * such match": the id was not in the provider days searched.
+ */
+declare function matchWindowSentence(result: MatchByIdResult, id: string, lang: string | undefined): string | undefined;
+/**
+ * The sentence for an EMPTY `next` off the bundled competition whose read was
+ * not whole (`partial` stated, no fixture, not degraded): no fixture for the
+ * club was READ in the span, which is not "none exists". Undefined otherwise.
+ * (On the bundle the partial empty card keeps its own sentence.)
+ */
+declare function nextNoneReadSentence(result: NextFixtureResult, fallback: string, lang: string | undefined): string | undefined;
+/**
+ * The sentence for an EMPTY `match <id>` whose read was not whole (`partial`
+ * stated, no record, not degraded): no match with that id was READ in the
+ * span, which is not "no such match". Undefined otherwise.
+ */
+declare function matchNoneReadSentence(result: MatchByIdResult, id: string, lang: string | undefined): string | undefined;
+/**
+ * "No match in play was read", in the reader's language: an EMPTY live body
+ * after a read that was not whole, which is not "nothing is in play". (When
+ * it applies: {@link liveNoneRead}.)
+ */
+declare function liveNoneReadSentence(lang?: string): string;
+/**
+ * "No fixture was read for {date}", in the reader's language: an EMPTY day
+ * after a read that was not whole and merged no bundled schedule, which is not
+ * "no matches scheduled". `date` is printed as given: the card passes its
+ * human label, the CLI and MCP the date they print. (When it applies:
+ * {@link dateNoneRead}.)
+ */
+declare function dateNoneReadSentence(date: string, lang?: string): string;
+/**
+ * "Couldn't reach the data provider — no fixtures confirmed for {date}", in
+ * the reader's language: the EMPTY day of a read that FAILED and merged no
+ * bundled schedule (off the bundle), where nothing but the provider knows the
+ * fixtures, so an outage must not read as "no matches scheduled". `date` is
+ * printed as given: the card passes its human label, the CLI and MCP the date
+ * they print. (When it applies: {@link dateUnreached}.)
+ */
+declare function dateUnreachedSentence(date: string, lang?: string): string;
+/**
+ * The sentence beside a day's partial verdict that counts the displayed
+ * fixtures the read did not serve: they are the bundled schedule's rows, and
+ * their live state is unconfirmed. Singular and plural, in the reader's
+ * language. (When it applies: {@link dayAttribution}.)
+ */
+declare function unservedSentence(n: number, lang?: string): string;
+/**
+ * "No market signal among the fixtures read for {date}": an EMPTY dated
+ * market answer whose fixture read was not whole, which is not "none for the
+ * date". Market copy from the approved bank (`marketsNoneReadNote`), English
+ * on every locale. (When it applies: {@link marketsNoneRead}.)
+ */
+declare function marketsNoneReadSentence(date: string): string;
+/**
+ * What a live or dated read says about itself, as the empty bodies and the
+ * day's attribution read it: its verdicts, whether it failed, whether it
+ * merged the bundled schedule, and what the provider's window held.
+ */
+type ReadAccount = VerdictSource & {
+    readonly degraded?: boolean;
+    readonly skeleton?: true;
+    readonly served?: readonly string[];
+};
+/**
+ * The empty body of a live read that was not whole (`partial` stated, not
+ * degraded): {@link liveNoneReadSentence}. Undefined otherwise: a whole read
+ * with nothing in play says so in the surface's own words.
+ */
+declare function liveNoneRead(result: ReadAccount, lang?: string): string | undefined;
+/**
+ * The empty body of a dated read that was not whole and merged NO bundled
+ * schedule (off the bundle, or the bundle's slug answering for another
+ * edition): {@link dateNoneReadSentence}. Undefined otherwise: where the
+ * skeleton was merged the day's list is the bundle's, whole, and its empty
+ * body is the bundle's answer.
+ */
+declare function dateNoneRead(result: ReadAccount, date: string, lang?: string): string | undefined;
+/**
+ * The empty body of a dated read that FAILED and merged no bundled schedule:
+ * {@link dateUnreachedSentence}. Undefined otherwise: a failed read on the
+ * bundle shows the bundle's day (the schedule is known without the provider),
+ * and a read that answered says what it read.
+ */
+declare function dateUnreached(result: ReadAccount, date: string, lang?: string): string | undefined;
+/**
+ * The empty body of a dated MARKET answer whose fixture read was not whole:
+ * {@link marketsNoneReadSentence} (market copy, English). Undefined otherwise.
+ * Separate from the market requests' own completeness (`complete`), which
+ * says something else.
+ */
+declare function marketsNoneRead(result: ReadAccount, date: string): string | undefined;
+/** What a day's surface says about the provider, for the fixtures it displays. */
+interface DayAttribution {
+    /** Whether the "Live data" line is printed (the structured `source` keeps the provider either way). */
+    attributed: boolean;
+    /** The sentence counting the displayed fixtures the read did not serve, when there are any. */
+    unserved?: string;
+}
+/**
+ * The day's attribution, ONE rule for the CLI, the MCP tool and the date card,
+ * computed over the fixtures the surface finally DISPLAYS (after the date
+ * filter and any bound). A whole read, a degraded one, and a read that does not
+ * say what it served change nothing: the line is printed as it always was. On
+ * a read that was not whole:
+ *   - when some displayed fixtures are not among the ids the window held
+ *     (`served`), they are the bundled schedule's rows, whose live state is
+ *     unconfirmed: the sentence says how many;
+ *   - when NONE of the displayed fixtures was served, the "Live data" line is
+ *     not printed: a provider is never named for a day it served nothing of.
+ *     (An empty day attributes no fixture, and keeps the line.)
+ */
+declare function dayAttribution(read: ReadAccount, shown: readonly Match[], lang?: string): DayAttribution;
+/** Where and in which language a card's dates are rendered. */
+interface ShareCardContext {
+    tz?: string;
+    locale?: string;
+    /**
+     * The competition the card is about (its slug). Its title names it and its
+     * run cue selects it (`npx @claudinho/cli --competition premier-league next
+     * Arsenal`), the World Cup's too: a pasted card must answer the same thing
+     * whatever the recipient follows. A card built with none (a test) keeps the
+     * bare title and cue.
+     */
+    competition?: string;
+}
+/** Display-ready market signals for a card, and whether every fixture was checked. */
+interface ShareCardMarket {
+    signals: Map<string, MarketSignal>;
+    complete: boolean;
+}
+/** What a surface adds when it shows fewer records than exist. */
+interface ShareCardView {
+    /** The records the surface will show (default: all of the result's). */
+    matches?: readonly Match[];
+    /**
+     * The sentence a surface that bounds the list states, e.g. "(showing 20 of
+     * 31 — list truncated)". It QUALIFIES the body, so it is printed in the
+     * card's `note`, after the verdict's sentences and before the body, like a
+     * tool's; the title stays bare.
+     */
+    cap?: string;
+}
+/** A match card: what to format, what it is, and the verdict it carries. */
+interface MatchShareCard {
+    kind: 'today' | 'live' | 'next' | 'match';
+    target: string;
+    /**
+     * A next card's team: the club the query resolved to (its provider id,
+     * code and name) when one was, the query (a nation's code on the World Cup)
+     * otherwise.
+     */
+    team?: string | Team;
+    /** A next card for a name two or more teams match: them, and no fixture. */
+    candidates?: Team[];
+    input: ShareSnippetInput;
+    /** The structured verdict keys the card's note stands for (see `verdictExtras`). */
+    verdict: VerdictExtras;
+    /**
+     * The span an empty card says was searched, as plain fields for the
+     * structured twin (`horizon` for `next`, `window` for a match id); empty
+     * when the card states none. Not a verdict.
+     */
+    span: {
+        horizon?: {
+            days: number;
+        };
+        window?: {
+            from: string;
+            to: string;
+        };
+    };
+    /**
+     * Plain fields of the card's read for its structured twin, spread beside
+     * `source`: the card's shown fixtures whose record the window held, beside
+     * `partial` only (`servedExtras`); empty otherwise. Not a verdict.
+     */
+    readFields: {
+        served?: readonly string[];
+    };
+}
+/** Matches in play right now. No market lines: a live card stays lean. */
+declare function liveShareCard(result: LiveResult, ctx: ShareCardContext, view?: ShareCardView): MatchShareCard;
+/** A team's next fixture. */
+declare function nextShareCard(result: NextFixtureResult, code: string, market: ShareCardMarket, ctx: ShareCardContext): MatchShareCard;
+/** One match, by id. */
+declare function matchShareCard(result: MatchByIdResult, id: string, market: ShareCardMarket, ctx: ShareCardContext): MatchShareCard;
+/** A day's matches: today's, or an explicitly requested date's. */
+declare function dateShareCard(day: {
+    /** The calendar date shown (YYYY-MM-DD). */
+    date: string;
+    /** True when the caller named the date; false for "today". */
+    explicit: boolean;
+    /** The day's fixtures the surface will show. */
+    matches: readonly Match[];
+    degraded: boolean;
+    source?: string;
+    /** The list's cap when the surface bounded it (see `ShareCardView.cap`): in the note, not the title. */
+    cap?: string;
+    /**
+     * The dated read itself: the verdicts the card states (between editions,
+     * partial), whether it merged the bundled schedule (`skeleton`: the ONE
+     * input for what an empty day may say), and what it served (the card's
+     * attribution, over the fixtures it shows). A card handed no read is a
+     * whole read that merged no schedule.
+     */
+    read?: ReadAccount;
+}, market: ShareCardMarket, ctx: ShareCardContext): MatchShareCard;
+/** A standings card: facts only, never a market line. */
+interface TableShareCard {
+    group?: string;
+    input: ShareTableInput;
+    /** Null when degraded: a roster served by no provider is attributed to none. */
+    source: string | undefined;
+    degraded: boolean;
+    /** The card's tables in structured form, each with the verdict it carries. */
+    tables: TableData[];
+    /** The structured verdict keys of the READ (see `verdictExtras`): `incomplete` when tables are missing. */
+    verdict: VerdictExtras;
+}
+declare function tableShareCard(result: StandingsResult, group: string | undefined, 
+/** The tables the surface will show (default: all of the result's). */
+tables?: readonly GroupStandings[], 
+/** The reader's language, for the one localized sentence a card prints: a verdict's. */
+lang?: string, 
+/** The competition the card is about: its first line names it, its run cue selects it (see `ShareCardContext`). */
+competition?: string): TableShareCard;
+/** A knockout bracket card. Its empty note is localized, like the card itself. */
+interface BracketShareCard {
+    stage?: string;
+    input: ShareBracketInput;
+    source: string | undefined;
+    degraded: boolean;
+    verdict: VerdictExtras;
+}
+declare function bracketShareCard(result: BracketResult, stage: string | undefined, lang: string | undefined, 
+/** The competition the card is about: its first line names it, its run cue selects it (see `ShareCardContext`). */
+competition?: string): BracketShareCard;
+
+declare function matchKey(stage: Stage, index: number): string;
+/**
+ * Build and validate bracket topology from knockout fixtures.
+ * Throws when ESPN introduces an unparsed placeholder or the graph is inconsistent.
+ */
+declare function buildBracketTopology(matches: Match[], generatedAt: string): BracketTopology;
+
+/**
+ * Parse an ESPN home/away label into a bracket slot reference (name patterns only).
+ * Real nation flags are mapped to `seed` — never `team` — so the bundled schedule
+ * cannot treat ESPN pre-draw labels as confirmed participants.
+ */
+declare function parseTeamSlot(team: Team): SlotRef | null;
+
+/**
+ * Resolve the bundled topology against merged knockout matches and standings.
+ * Group slots project from live standings once a group has started; confirmed when
+ * the group is fully played. Winner/loser slots require a confirmed FT result.
+ */
+declare function buildBracketView(topology: BracketTopology, matches: Match[], tables: GroupStandings[], standingsDegraded: boolean, liveDegraded: boolean, filterStage?: string, lang?: string): BracketView;
+
+/**
+ * True exactly when a side is a placeholder: the neutral 🏳️ a nation
+ * competition's side carries when its name is no nation (the bundle's
+ * unresolved knockout slots, "Round of 32 1 Winner"). A side with NO flag is a
+ * club (a club has none, by the competition's written kind) and is RESOLVED: it
+ * is a real team, drawn by its name or code. "Not a placeholder" is not "has a
+ * nation's flag".
+ */
+declare function isPlaceholderSide(team: Pick<Team, 'flag'>): boolean;
+
+/** The bundled knockout bracket topology (generated by gen:schedule). */
+declare function loadBracketTopology(): BracketTopology;
+
+/**
+ * Where a selection came from: the command line's `--competition` or a tool's
+ * `competition` argument (`flag`), `CLAUDINHO_COMPETITION` (`env`), or the
+ * user's saved choice (`saved`: the config file `claudinho follow` writes).
+ * Nothing else chooses: with none of the three there is no competition
+ * (`{ kind: 'none' }`), never a default.
+ */
+type ChosenBy = 'flag' | 'env' | 'saved';
+/** A competition a request is for, and where that choice came from. */
+interface SelectedCompetition {
+    readonly kind: 'selected';
+    /** The provider's slug the request asks for. */
+    readonly slug: string;
+    /** The table's alias; absent for a raw slug. */
+    readonly alias?: string;
+    /** What a surface names it: the table's name, or a raw slug as it is. */
+    readonly name: string;
+    readonly chosenBy: ChosenBy;
+    /** A raw slug the table does not hold: the escape hatch, labelled. */
+    readonly experimental: boolean;
+}
+/**
+ * What the edge resolved: a competition; a value that is neither an alias nor
+ * a slug, REFUSED with the aliases (an unknown value is never a request); or
+ * `none`: nothing was chosen (no flag, no environment, no saved choice). The
+ * finished World Cup is not a default anyone falls into without choosing.
+ */
+type CompetitionSelection = SelectedCompetition | {
+    readonly kind: 'refused';
+    readonly value: string;
+    readonly aliases: string[];
+    /** The source that gave the refused value (a flag or the environment: the file's reader refuses its own). */
+    readonly chosenBy: ChosenBy;
+} | {
+    readonly kind: 'none';
+};
+/**
+ * The ONE constructor of a selected competition: a slug and where it was
+ * chosen, described by the table (its alias and name) or, for a slug the
+ * table does not hold, as itself and experimental. The resolver builds every
+ * selection through it; an edge that already holds a slug (a config built
+ * without the resolver) describes it through it too, never by hand.
+ */
+declare function selectedCompetition(slug: string, chosenBy: ChosenBy): SelectedCompetition;
+/**
+ * THE EDGE. The one function that decides which competition a request is for,
+ * from the values its edge hands in: the flag (`--competition`, a tool's
+ * `competition` argument), then the environment (`CLAUDINHO_COMPETITION`), then
+ * the saved choice (the config file's `competition`, read at the edge through
+ * core's one reader: `readUserConfig`). The FIRST present source decides (an
+ * empty string is absent): a present value that is refused is refused, even
+ * when a lower source holds a valid one (what was asked for is not answered
+ * with something else). With no source present, `none`: nothing is chosen,
+ * and every competition-answering surface says so instead of answering.
+ *
+ * Each value is an alias (`premier-league`), a slug in the table (`eng.1`), or
+ * a raw ESPN slug the table does not hold (`fifa.friendly`, `esp.copa_del_rey`:
+ * lower-case segments of letters, digits and underscores joined by dots, 64
+ * units at most; experimental);
+ * anything else (`foo`, `ENG.1`, a space) is refused with the aliases.
+ *
+ * Core reads NO environment and no file: the edges pass them. It is called
+ * where a request ENTERS (the CLI's option resolution, the MCP server's
+ * request) and nowhere else. From there the competition travels as a value
+ * (on the config, on the adapter), so nothing further down can answer for a
+ * different competition halfway through. `core/test/selection-identity.test.ts`
+ * fails if a call appears anywhere else.
+ */
+declare function resolveCompetition(explicit?: string, env?: string, saved?: string): CompetitionSelection;
+/**
+ * The line every competition-answering text answer prints after its header:
+ * the competition's name, then where the choice came from when it was the
+ * flag or the environment (`from the command line`; on MCP, `from the
+ * request`; `from the environment`), then `experimental` for a raw slug. A
+ * saved choice prints the name alone. The name is not localized; the rest is.
+ * Empty for a selection that is not a competition.
+ */
+declare function modeLine(selection: CompetitionSelection, lang?: string, 
+/** What a flag is on this surface: the command line's, or a tool request's argument. */
+flag?: 'command' | 'request'): string;
+/** The structured form of a selection: what `--json` and MCP `data` carry. */
+interface CompetitionKey {
+    readonly slug: string;
+    readonly alias?: string;
+    readonly name: string;
+    readonly chosenBy: ChosenBy;
+    readonly experimental?: true;
+}
+/**
+ * The selection as ONE structured key, `competition`, for every
+ * competition-answering structured answer (CLI `--json`, MCP `data`): the
+ * alias only when there is one, `experimental` only when true; `null` when
+ * nothing is chosen (beside the `noCompetition` verdict: see
+ * {@link selectionVerdict}). Nothing for a refused value (it is an error, never
+ * an answer). Every emit site spreads this; none builds the key by hand.
+ */
+declare function selectionExtras(selection: CompetitionSelection): {
+    competition?: CompetitionKey | null;
+};
+/**
+ * The verdict a selection states about every answer made under it: with
+ * nothing chosen, `noCompetition` (the first replacing verdict: its sentence
+ * stands instead of any answer, and its key goes beside `competition: null`);
+ * nothing otherwise. A surface hands THIS to `verdictNotice`/`verdictExtras`,
+ * never an object it builds itself.
+ */
+declare function selectionVerdict(selection: CompetitionSelection): VerdictSource;
+/**
+ * Why a selection is not a competition, in the reader's language; undefined
+ * for a competition. A refused value names the value (bounded) and the
+ * aliases; nothing chosen is the CLI's sentence (`claudinho follow <alias>`,
+ * `follow --list`): MCP answers nothing chosen with the `noCompetition`
+ * verdict's own sentence (`verdictNotice`), never this one. The CLI raises it
+ * as an input error, MCP a refused value as a tool error, before any request.
+ */
+declare function selectionRefusal(selection: CompetitionSelection, lang?: string): string | undefined;
+/** The competition whose schedule ships bundled in the clients: the World Cup. */
+declare const BUNDLE_COMPETITION = "fifa.world";
+/**
+ * The edition the bundled schedule describes, read from the schedule itself
+ * (the year of its first kickoff) rather than written down a second time.
+ */
+declare function bundleSeasonYear(): number;
+/**
+ * Does the bundled schedule describe what this request is about?
+ *
+ * The competition is an ARGUMENT — the caller's adapter states it — never a
+ * default. Off the bundle, every path built on the skeleton (date merge,
+ * `match <id>`, `next`, the bracket, the knockout-fixture cache, the market
+ * fixture) must not read it: an empty foreign day once showed 104 World Cup
+ * fixtures with foreign attribution (audit A03).
+ *
+ * The bundle is ONE EDITION of its competition. When the provider reported the
+ * season a response belongs to and it is a different one, the bundle does not
+ * describe that response. With no provider answer (offline, degraded) there is
+ * nothing to compare, and the bundle stays what it is: the 2026 edition.
+ */
+declare function bundleApplies(competition: string, season?: SeasonInfo): boolean;
+/**
+ * The competitions that HAVE NO BRACKET: league seasons with no knockout tie of
+ * their own, where "no bracket" is the answer, not a gap. Written down in the
+ * supported table (`bracket: 'not-applicable'`), one fact each, never inferred
+ * from the standings shape (`STANDINGS_SHAPE` says
+ * how a table is read, not whether a knockout follows it: `uefa.champions` and
+ * `mex.1` read as one league table and both have one).
+ *   - `eng.1`: the Premier League; a 38-round league, no play-off.
+ *   - `esp.1`: LaLiga; a 38-round league, no play-off.
+ * Deliberately NOT here: `ita.1` (championship and relegation play-offs since
+ * the FIGC's May 2026 decision), `ger.1` (the relegation play-off), `mex.1`
+ * (the Liguilla), `uefa.champions` (a knockout after the league phase). A
+ * competition joins by a written fact. A derived view, kept for its readers (it
+ * is exported); {@link bracketCapability} reads the row itself.
+ */
+declare const NO_BRACKET: ReadonlySet<string>;
+/**
+ * What `bracket` is for a competition, one of three values, read from its ROW
+ * (one row, one fact: a listing, the README matrix and the command cannot
+ * disagree):
+ *   - `offered`: the row offers it (only the bundled competition can:
+ *     `deriveTables` refuses any other row that does);
+ *   - `inapplicable`: the row says the competition has none (`not-applicable`);
+ *   - `unsupported`: it may have one, and it is not offered yet; also a slug
+ *     the table does not hold.
+ */
+declare function bracketCapability(competition: string, table?: readonly CompetitionEntry[]): 'offered' | 'inapplicable' | 'unsupported';
+
+/**
+ * Metadata that belongs to ONE fetch result.
+ *
+ * A provider says things about a response that are not fixtures: which season
+ * (or, for a window across a season turn, which seasons) it answered for and,
+ * from 0.11's bundle decoupling on, whether every record in it could be read
+ * and how many could not. Those facts decide what a caller may claim, so they
+ * must belong to the particular result they describe.
+ *
+ * They are NOT kept on the adapter. A field there is shared by every call in
+ * flight — `lastError` is, and documents itself as "best-effort under
+ * concurrency" for exactly that reason: with two overlapping calls, the second
+ * to finish overwrites what the first was told. Here the metadata is keyed on
+ * the returned array itself, so it cannot outlive, precede or cross to another
+ * result, and `ProviderAdapter` keeps its plain-array contract.
+ */
+
+interface FetchMeta {
+    /**
+     * The season the provider reported for this response, when it stated one.
+     * For a window, the one its stating parts agree on; absent when none stated
+     * one, or when a window asked across seasons held two (see `seasons`).
+     */
+    readonly season?: SeasonInfo;
+    /**
+     * Every distinct season the response(s) stated, by year, in the order the
+     * parts were asked: zero or one for a single response, and for a window
+     * asked strictly (two are refused there); two for a window asked across a
+     * season turn. Empty is "none stated", which a reader must tell from "two".
+     * Absent when the adapter does not say.
+     */
+    readonly seasons?: readonly SeasonInfo[];
+    /**
+     * Whether the result accounts for every record the provider sent. False when
+     * a record was left out: refused as unreadable, contradicting a sibling under
+     * the same id, or beyond the bound. A record the provider itself marks as not
+     * a fixture is not "left out". Absent when the adapter does not say.
+     */
+    readonly complete?: boolean;
+    /**
+     * How many provider records made the result not whole: refused as
+     * unreadable, a second record under an id already accepted (within a
+     * response or across the parts of a window), or beyond the bound. A record
+     * the provider marks as not a fixture is not counted. 0 exactly when
+     * `complete` is true. Absent when the count is not known: a response that
+     * filled the request's limit lost a tail nobody can count.
+     */
+    readonly omitted?: number;
+    /**
+     * The id of every fixture the response(s) held and the parser read, when the
+     * result can hold FEWER: a window narrowed from month responses sets aside
+     * what falls outside it, and the copy of a fixture held twice. A caller that
+     * keeps a previous answer asks "was this fixture read?" of this list, never
+     * of the result: a fixture the provider moved out of the window was read,
+     * and its old copy must not be put back. Absent when the result holds
+     * everything that was read.
+     */
+    readonly mentioned?: readonly string[];
+    /**
+     * Standings only: whether every table child the provider sent became a
+     * table. A different fact from `complete`, which is also false for a refused
+     * ROW of a table that was read. False means a table may be missing from the
+     * result, so a key it does not hold is not known to be absent.
+     */
+    readonly inventoryComplete?: boolean;
+}
+/** Attach metadata to a fetch result and return that same result. */
+declare function attachFetchMeta<T extends object>(result: T, meta: FetchMeta | undefined): T;
+/** The metadata of a fetch result, if the provider that produced it stated any. */
+declare function fetchMeta(result: object | undefined): FetchMeta | undefined;
+
+/**
+ * What one look at a small file found. Four answers, because the refresh lock
+ * must tell them apart (the other kept files only want `read` or nothing):
+ * - `read`: a regular file within the bound, its bytes and its mtime, both
+ *   from the one open file;
+ * - `absent`: no directory entry at the path. The lock's claimer must not
+ *   remove what is not there (a lock created a moment later is someone's);
+ * - `unreadable`: something is there that cannot be read as such a file (a
+ *   pipe, a device, a directory, a link to nothing, too large, no permission).
+ *   The lock's claimer takes it over: nobody can judge it;
+ * - `grown`: a regular file within the bound that grew while it was read: its
+ *   writer is writing it in place NOW (a lock's owner writes its token just
+ *   after creating it). No bytes, because nobody may parse a file caught
+ *   mid-write; its mtime, so a lock being written is judged by its date.
+ */
+type SmallFile = {
+    kind: 'read';
+    bytes: Buffer;
+    mtimeMs: number;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'unreadable';
+} | {
+    kind: 'grown';
+    mtimeMs: number;
+};
+/** What a NO-FOLLOW look found: the four answers, or a symbolic link at the path (never followed). */
+type OwnFile = SmallFile | {
+    kind: 'symlink';
+};
+/**
+ * Read a small regular file through ONE descriptor, never more than
+ * `maxBytes + 1` bytes of it, and say which of the four `SmallFile` answers it
+ * is. Never throws, never waits. The ONE implementation for every file kept on
+ * disk; `readSmallFile` is its bytes-or-nothing form, and {@link lookAtOwnFile}
+ * its no-follow form.
+ *
+ * A check by path followed by a read by path is two looks at what may be two
+ * files: between them the path can become a pipe (the read then blocks the
+ * statusline for ever) or a file far larger than the check allowed (read
+ * whole). Here the check and the read are of the same open file, and the read
+ * stops one byte past the size the check saw (at most the bound): a file that
+ * grew in place after it was checked is `grown`, and is not read further.
+ *
+ * `absent` means NO ENTRY. An open that follows a link to nothing also fails
+ * with ENOENT, so that failure is followed by one look at the entry itself
+ * (`lstat`, not followed): a link is there, so `unreadable`. Anything else that
+ * look finds (nothing, or a file created between the two looks) stays
+ * `absent`: answering `unreadable` for a file that appeared in between would
+ * have the lock's claimer remove a fresh lock (the vanished-lock tests in
+ * `cache-file-races.test.ts` pin it).
+ */
+declare function lookAtSmallFile(path: string, maxBytes: number): SmallFile;
+/**
+ * The contents of a small regular file (see `lookAtSmallFile`), or `undefined`
+ * for every other answer (absent, unreadable, grown while it was read: a file
+ * caught mid-write is not parsed). Never throws, never waits.
+ */
+declare function readSmallFile(path: string, maxBytes: number): Buffer | undefined;
+/** What a rename onto a path would do (see {@link lookAtEntry}). */
+type FileEntry = 'absent' | 'file' | 'replaceable' | 'unhealable';
+/**
+ * What a RENAME onto `path` would do, from one look at the entry (`lstat`,
+ * never following a link), one open for a regular file whose owner-read bit is
+ * set, and one probe where that bit is clear; nothing is read. The replacement
+ * (an atomic write: a temporary file made in the same directory and renamed
+ * over the path) is this process's own file and keeps the mode bits of
+ * whatever it replaces but a link, and nothing else of the entry (no
+ * access-control entry of its own, no other owner); what the DIRECTORY gives a
+ * new file (an inherited access-control entry) it gets too. So the owner-read
+ * bit decides nothing on its own where it is clear: there the look MEASURES
+ * whether a file made beside the path with those bits reads back, before any
+ * open of the entry (a probe, made with those bits, opened, and removed:
+ * nothing is left behind but where a crash interrupts it or the directory
+ * denies its deletion, at most one file per look). Where it is set the replacement is taken to read
+ * back (steps 5 and 6; a directory whose inherited entries deny a new file a
+ * read is not measured there). In this order:
+ * 1. the `lstat` fails: no entry → `absent` (a rename creates a fresh file);
+ *    anything else → `unhealable` (nobody can look at it: the directory above
+ *    cannot be searched);
+ * 2. a symbolic link to anything → `replaceable` (the rename replaces the link
+ *    itself and keeps nothing of it; its target is never followed, a link to
+ *    nothing included);
+ * 3. a directory → `unhealable` (a rename cannot replace it);
+ * 4. the owner-read bit clear (mode 000, 200, 044), whatever the kind (a
+ *    regular file refused, or one that opens through its other bits or an
+ *    access-control entry of its own; a pipe, a socket, a device): the
+ *    replacement keeps the bits and none of what let this process read the
+ *    entry, so whether it reads back is measured (`replacementReadsBack`): a
+ *    probe made there with those bits reads back (the directory's inherited
+ *    permissions let a new file be read) → `replaceable`; else → `unhealable`;
+ * 5. a regular file → opened (read-only, non-blocking where the platform has
+ *    it, on one descriptor, closed before returning, nothing read): it opens →
+ *    `file`, whatever its size or content; refused → `replaceable` (an
+ *    access-control list, another owner's 0600, a lock: the replacement is
+ *    ours with the owner-read bit set, so it reads back);
+ * 6. anything else with the bit set (a pipe, a socket, a device) →
+ *    `replaceable` (the rename replaces the entry with a regular file of ours
+ *    with those bits, which reads back).
+ *
+ * On Windows every mode reports the owner-read bit, so step 4 never runs there
+ * (no probe is made) and a file that cannot be opened is `replaceable`; if the
+ * rename itself then fails, the atomic write throws, and the publish that
+ * called it is one that did not happen, as before. The look cannot see a flag
+ * the system keeps beside the mode (an immutable or append-only flag: Node's
+ * `lstat` reports none); under one the rename is refused whatever it answers,
+ * with the same outcome.
+ *
+ * The bounded reader cannot answer this: `lookAtSmallFile` says `unreadable`
+ * for a file it cannot open, for a regular file larger than its bound, and for
+ * a link to nothing alike. For the CLI's refresher, which asks whether a
+ * publish can heal a snapshot it could not use. Never throws, never waits.
+ */
+declare function lookAtEntry(path: string): FileEntry;
+/**
+ * {@link lookAtSmallFile} for a file that must be the user's OWN regular file
+ * (the config file): a symbolic link at the path is `symlink`, never followed.
+ * Where the platform has `O_NOFOLLOW` (POSIX) the open itself refuses a link
+ * (`ELOOP`, or `EMLINK` on some BSDs), and one look at the entry tells a link
+ * from a path that loops elsewhere. Windows has no such flag: there the entry
+ * is looked at (`lstat`: a link is `symlink`) BEFORE the open, and the file
+ * the open gave must be THAT entry: the same device and inode by `fstat` as by
+ * the `lstat`. A link (or any other file) put in place between the two looks
+ * is then not what was inspected, and is answered `symlink`, its descriptor
+ * closed and nothing read; so is a file found at the open where the look found
+ * no entry. The two looks are kept apart by the check, not closed into one.
+ */
+declare function lookAtOwnFile(path: string, maxBytes: number): OwnFile;
+
+export { BRACKET_STAGE_ORDER, BUNDLE_COMPETITION, type BatchResolution, type BetweenEditions, type BoundedList, type BracketFormatOpts, type BracketMatchNode, type BracketMatchView, type BracketResult, type BracketShareCard, type BracketTopology, type BracketView, type BuildSignalInput, COMPETITION_KIND, COUNTDOWN_NOW, type Capabilities, type Capability, type ChosenBy, type ClubResolution, type CompetitionEntry, type CompetitionKey, type CompetitionKind, type CompetitionSelection, DEFAULT_COMPETITION, DEFAULT_COOLDOWN_MS, DEFAULT_FLAVOR, DEFAULT_MAX_AGE_MS, DISCLAIMER, type DayAttribution, type DerivedTables, EARLIER_RECORD_NOTE, EspnAdapter, type EspnAdapterOptions, FAN_PROJECT, FLAVOR_BANKS, FLAVOR_LEVELS, FLAVOR_MOMENTS, FakeMarketProvider, type FakeMarketProviderOptions, type FavoriteStrength, type FetchMeta, type FetchWindowOptions, type FileEntry, type Flair, type FlairOpts, type FlavorBank, type FlavorLevel, type Moment as FlavorMoment, type FlavorOpts, type FormatOpts, type GroupStandings, KNOCKOUT_EXTRA_TIME_MS, KNOWN_SOURCES, type KnockoutFixturesResult, LIVE_WINDOW_MS, type Lang, type LedgerRow, type ListedCompetition, type LiveReadResult, type LiveResult, MARKETS_SCOPE_NOTE, MARKET_COMPETITIONS, MAX_CONFIG_BYTES, MAX_COOLDOWN_MS, MAX_LABEL_COLUMNS, MAX_RESPONSE_BYTES, MAX_SCHEDULE_INDEX, type MapContext, type MarketFavorite, type MarketMapping, type MarketMappingTable, type MarketOutcome, type MarketOutcomeKind, type MarketProvider, type MarketSignal, type MarketSignalOptions, type MarketSignalsResult, type Match, type MatchByIdResult, type MatchEvent, type MatchShareCard, NO_BRACKET, type NextFixtureResult, type NoConfigReason, type Outcome, type OwnFile, type ParseResult, type Pin, PolymarketProvider, type PolymarketProviderOptions, type ProviderAdapter, type ProviderCapabilities, ProviderError, type ProviderErrorKind, type PunditPick, RALLY_CRIES, type RallyCry, type RallyPin, type ReadAccount, type ResolvedParticipant, ResponseTooLargeError, type Roster, SCHEDULE_AHEAD_DAYS, SCHEDULE_LOOKBACK_DAYS, SEASON_SLUG, SHARE_DISCLAIMER, SHARE_HASHTAG, STANDINGS_SHAPE, SUPPORTED, type ScheduleAheadResult, type ScheduleEntry, type SeasonInfo, type SelectedCompetition, type Selection, type ShareBracketInput, type ShareBracketOptions, type ShareCardContext, type ShareCardMarket, type ShareCardView, type ShareSnippetInput, type ShareSnippetOptions, type ShareStyle, type ShareTableInput, type SlotRef, type SmallFile, type Stage, type StandingRow, type StandingsResult, type Status, TABLE_KEY_ARG, TEAM_KIND, type TableData, type TableShareCard, type Team, type TeamInfo, type TeamKind, type TeamLookup, type UserConfig, type UserConfigRead, type VerdictExtras, type VerdictSource, allFixtures, allTeams, ambiguous, asFlavorLevel, attachFetchMeta, bounded, bracketCapability, bracketShareCard, buildBracketTopology, buildBracketView, buildMarketSignal, bundleApplies, bundleSeasonYear, byKickoff, cacheDirFor, cacheableKeys, capabilitiesOf, competitionBase, competitionKind, competitionLabel, competitionValue, computeStandings, configPath, countdown, countdownPhrase, currentOrNextFixtureForTeam, dateNoneRead, dateNoneReadSentence, dateShareCard, dateUnreached, dateUnreachedSentence, dayAttribution, definitiveNone, deriveFavorite, deriveTables, disclaimerLine, displayWidth, emptyBatch, entryOf, favoriteStrength, fetchMeta, fixturesByDate, fixturesByGroup, fixturesByTeam, fixturesInLiveWindow, flagEmoji, flavorsFor, formatBracketCompactLine, formatBracketList, formatBracketMatchLine, formatBracketTree, formatDate, formatKickoff, formatShareBracket, formatShareSnippet, formatShareTable, formatTime, getBracket, getKnockoutFixtures, getLiveMatches, getLiveRead, getMarketSignal, getMarketSignals, getMatchById, getMatchesForDate, getNextFixtureForTeam, getScheduleAhead, getStandings, groups, hasLiveWindow, hasSaneDistribution, humanLabel, isCacheable, isFinished, isFlavorLevel, isHumanLabel, isKnockoutStage, isKnownSource, isLive, isMexicoNationalTeam, isPinnedSide, isPlaceholderSide, isReliableMarketSignal, isStaleSignal, isTeam, isTournamentWindowOver, isUpcoming, isValidDate, isValidTimeZone, joinSegments, knockoutWindow, listCompetitions, liveNoneRead, liveNoneReadSentence, liveShareCard, liveSourceLabel, liveWindowMsFor, loadBracketTopology, localDate, lookAtEntry, lookAtOwnFile, lookAtSmallFile, lookupTeam, makeAdapter, makeMarketProvider, malformed, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketDisplayable, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, marketScopeVerdict, marketSignalRendersFor, marketSourceLabel, marketsCoverCompetition, marketsNoneRead, marketsNoneReadNote, marketsNoneReadSentence, matchFlair, matchFlairs, matchFlavor, matchKey, matchLocation, matchNoneReadSentence, matchShareCard, matchWindowSentence, mergeLive, modeLine, nationArg, nationToFlag, nationToRegion, nextFixtureForPin, nextFixtureForTeam, nextHorizonSentence, nextNoneReadSentence, nextShareCard, normalizeLang, normalizeOutcomes, outcomeFromScore, padVisible, parseCachedMarketSignal, parseCachedMatch, parseCachedMatches, parseCachedScheduleIndex, parseStandings, parseTeamSlot, parsedValue, pinUnder, productFlag, rallyCryFor, rallyEntryFor, readJsonBounded, readSmallFile, readUserConfig, resolveClub, resolveCompetition, resolveMarketSource, resolveTz, resolvedValues, retryAfterMs, rosterFor, sanitizeBundledFixture, savedSlug, scheduleEntryOf, scheduleSpan, scoreline, sealMarketSignal, sealMatch, sealScheduleEntry, sealSeason, selectOne, selectedCompetition, selectionExtras, selectionRefusal, selectionVerdict, servedExtras, stageLabel, stageLabelI18n, standingsShapeOf, statesPartial, t, tableData, tableKeyArg, tableShareCard, tableTitle, teamKind, truncateVisible, unresolved, unservedSentence, valid, verdictExtras, verdictNotice, verdictQualifiers, withFlag };