cito-mcp 0.2.4 → 0.2.6

package/dist/tools/match.js

@@ -35,8 +35,55 @@ function matchCore(game, matchId, raw) {
         event: m.event,
         league: m.league,
         method: pickString(r.method, r.resultMethod) ?? null,
-        winner: pickString(r.winnerFighterSlug, r.winnerSlug, r.winner) ?? null,
+        winner: (() => {
+            // UFC rows carry an explicit winner slug/fighter ref.
+            const explicit = pickString(r.winnerFighterSlug, r.winnerSlug, r.winner);
+            if (explicit)
+                return explicit;
+            if (game === 'ufc')
+                return null;
+            // CS2 rows expose winnerTeamId instead; map it to a side, else fall back to scores.
+            const sideLabel = (side) => side ? pickString(side.slug, side.id, side.name) ?? null : null;
+            const winnerTeamId = pickString(r.winnerTeamId, r.winner_team_id);
+            if (winnerTeamId) {
+                const t1Ids = [m.team1?.id, m.team1?.slug, pickString(r.team1Id, r.team1_id)].filter(Boolean).map(String);
+                const t2Ids = [m.team2?.id, m.team2?.slug, pickString(r.team2Id, r.team2_id)].filter(Boolean).map(String);
+                if (t1Ids.includes(winnerTeamId))
+                    return sideLabel(m.team1);
+                if (t2Ids.includes(winnerTeamId))
+                    return sideLabel(m.team2);
+            }
+            if (s1 != null && s2 != null && s1 !== s2)
+                return sideLabel(s1 > s2 ? m.team1 : m.team2);
+            return null;
+        })(),
         weightClass: pickString(r.weightClass, r.division) ?? null,
+        referee: (() => {
+            const nested = asRecord(r.referee);
+            if (nested) {
+                const joined = [nested.firstName, nested.lastName].filter(Boolean).join(' ').trim();
+                const name = pickString(nested.name, joined || undefined) ?? null;
+                const id = pickString(nested.id, nested.refereeId) ?? null;
+                if (name || id) {
+                    return {
+                        id,
+                        name,
+                        firstName: pickString(nested.firstName) ?? null,
+                        lastName: pickString(nested.lastName) ?? null,
+                    };
+                }
+            }
+            const name = pickString(r.refereeName) ?? null;
+            const id = pickString(r.refereeId) ?? null;
+            if (!name && !id)
+                return null;
+            return {
+                id,
+                name,
+                firstName: pickString(r.refereeFirstName) ?? null,
+                lastName: pickString(r.refereeLastName) ?? null,
+            };
+        })(),
         rawStatus: pickString(r.status, r.state) ?? null,
     };
 }
@@ -56,18 +103,18 @@ function primaryPath(game, matchId) {
 }
 export const matchSummary = {
     name: 'match_summary',
-    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
-
-When to use:
-- Match recap / default match UI
-- After user selects a live or completed matchId
-
-Prefer over match_details for chat answers and default UIs.
-Prefer match_details for timelines, full map trees, live state, advanced packages.
-
-Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
-
-Parallel-safe: yes. Upstream cost: 2–5.
+    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
+
+When to use:
+- Match recap / default match UI
+- After user selects a live or completed matchId
+
+Prefer over match_details for chat answers and default UIs.
+Prefer match_details for timelines, full map trees, live state, advanced packages.
+
+Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
+
+Parallel-safe: yes. Upstream cost: 2–5.
 Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includePlayerStats": true }`,
     inputSchema: {
         type: 'object',
@@ -251,22 +298,22 @@ Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includ
 };
 export const matchDetails = {
     name: 'match_details',
-    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
-
-When to use:
-- Analyst deep dive
-- Live in-game window (LoL/CS2/UFC)
-- Full demo list
-
-Prefer over match_summary only when summary is insufficient.
-Prefer match_summary for short answers and default cards.
-
-Do not use when: first-pass live board (use live_matches + match_summary).
-
-Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
-If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
-
-Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
+    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
+
+When to use:
+- Analyst deep dive
+- Live in-game window (LoL/CS2/UFC)
+- Full demo list
+
+Prefer over match_summary only when summary is insufficient.
+Prefer match_summary for short answers and default cards.
+
+Do not use when: first-pass live board (use live_matches + match_summary).
+
+Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
+If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
+
+Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
 Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "includeLiveState": false }`,
     inputSchema: {
         type: 'object',

package/dist/tools/meta.js

@@ -4,7 +4,7 @@
 import { extractRows, fetchJson, gameNotIncludedHint, present } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
 import { boolSchema, gameSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
-const CATALOG_VERSION = '0.2.4';
+import { PACKAGE_VERSION as CATALOG_VERSION } from '../version.js';
 const TOOL_CATALOG = [
     {
         name: 'list_capabilities',
@@ -88,10 +88,10 @@ const TOOL_CATALOG = [
     },
     {
         name: 'player_profile',
-        outcome: 'Player/fighter identity + recent form',
+        outcome: 'Player/fighter identity + recent form, including images (headshot, body, CORS-safe proxied)',
         parallelSafe: true,
         games: [...PRIMARY_GAMES],
-        jobs: ['player_form'],
+        jobs: ['player_form', 'media'],
         exampleArgs: { game: 'cs2', playerId: 'cs2-player-1', recentLimit: 10 },
         preferOver: ['manual multi-call career/trends via call_api'],
         doNotUse: 'Full team roster → team_profile; unresolved name → resolve_entity',
@@ -138,14 +138,29 @@ const TOOL_CATALOG = [
     },
     {
         name: 'event_card',
-        outcome: 'Event / fight-night card: identity + bout/match list (+ optional standings)',
+        outcome: 'Event / fight-night card: identity + bout list, card-ordered (main event first), ' +
+            'each corner carrying photos, record, nickname, country and weight class (+ optional standings)',
         parallelSafe: true,
         games: [...PRIMARY_GAMES],
-        jobs: ['event_card', 'schedule', 'app_scaffold'],
+        jobs: ['event_card', 'schedule', 'media', 'app_scaffold'],
         exampleArgs: { game: 'ufc', eventIdOrSlug: 'ufc-300', includeBouts: true },
-        preferOver: ['call_api /ufc/events + bout expansion', 'N+1 match_summary for card list'],
+        preferOver: [
+            'call_api /ufc/events + bout expansion',
+            'N+1 match_summary for card list',
+            'N+1 call_api per fighter for headshots — corners already include images',
+        ],
         doNotUse: 'Live-only strip → live_matches; single match recap → match_summary',
     },
+    {
+        name: 'list_routes',
+        outcome: 'Index of raw REST routes from the live OpenAPI spec (method, path, summary)',
+        parallelSafe: true,
+        games: [...PRIMARY_GAMES, 'fortnite'],
+        jobs: ['app_scaffold'],
+        exampleArgs: { game: 'ufc', q: 'rankings' },
+        preferOver: ['guessing a REST path for call_api', 'fetching the full 90KB spec by hand'],
+        doNotUse: 'A curated tool covers the outcome → list_capabilities',
+    },
     {
         name: 'call_api',
         outcome: 'Allowlisted raw REST escape hatch (unshaped data.raw)',
@@ -167,6 +182,13 @@ const JOBS = [
     { id: 'schedule', description: 'Upcoming fixtures/events', recommendedTools: ['upcoming_schedule', 'event_card'] },
     { id: 'preview', description: 'Pre-match briefing', recommendedTools: ['match_preview'] },
     { id: 'event_card', description: 'Event / fight-night card page', recommendedTools: ['event_card', 'resolve_entity', 'match_preview'] },
+    // Agents asked "does this API have photos?" and, finding no job for it,
+    // assumed no. Photos ship on every UFC corner and profile; make that findable.
+    {
+        id: 'media',
+        description: 'Headshots, full-body shots and team logos for visual UIs. UFC fighters carry headshotUrl / bodyImageUrl / imageUrl plus a CORS-safe proxiedImageUrl; use the proxied URL in a browser. Available on event_card corners and player_profile without any extra call.',
+        recommendedTools: ['event_card', 'player_profile', 'resolve_entity'],
+    },
     { id: 'app_scaffold', description: 'Design-time multi-screen prototype', recommendedTools: ['list_capabilities', 'api_health', 'live_matches'] },
 ];
 const RECIPES = [
@@ -450,7 +472,18 @@ Example: { "includeGameProbes": true }`,
         });
     },
 };
-const ALLOWLIST_PREFIXES = ['/health', '/lol', '/cs2', '/dota2', '/cod', '/ufc', '/fortnite'];
+const ALLOWLIST_PREFIXES = [
+    '/health',
+    '/lol',
+    '/cs2',
+    '/dota2',
+    '/cod',
+    '/ufc',
+    '/fortnite',
+    // The spec describes the surface call_api is allowed to reach; refusing to
+    // serve it left route discovery impossible except by guessing.
+    '/openapi.json',
+];
 function pathAllowed(path) {
     if (!path.startsWith('/') || path.startsWith('//'))
         return false;
@@ -604,6 +637,147 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
         });
     },
 };
-export const metaTools = [listCapabilities, apiHealth, callApi];
+/**
+ * Games whose routes the published spec does not describe.
+ *
+ * The spec has 123 paths and zero under /lol, yet every LoL route works —
+ * api_health itself answers partly from /lol/leagues. An agent that treats the
+ * spec as the whole surface concludes LoL is unsupported and stops, so say so
+ * explicitly rather than returning an empty list that reads as a verdict.
+ */
+const SPEC_OMITS = {
+    lol: 'The published OpenAPI spec documents no /lol paths, but LoL routes exist and work. Use the curated LoL tools (live_matches, upcoming_schedule, team_profile, standings, player_profile); for raw access, /lol/* is allowlisted for call_api even though it is undocumented.',
+};
+export const listRoutes = {
+    name: 'list_routes',
+    description: `Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.
+
+When to use:
+- You need a long-tail path for call_api and do not want to guess
+- Checking whether an endpoint exists before building around it
+- Mapping what raw data backs a curated tool
+
+Prefer curated tools for standard jobs — this indexes the escape hatch, it is not a replacement for list_capabilities.
+
+Do not use when: a curated tool already covers the outcome (call list_capabilities instead).
+
+Note: the spec omits /lol entirely, though LoL routes work. Filtering by game=lol returns that caveat rather than an empty list.
+
+Parallel-safe: yes. Upstream cost: 1.
+Example: { "game": "ufc", "q": "rankings" }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            game: gameSchema({
+                allowAll: false,
+                description: 'Filter to one game prefix (also accepts fortnite). Omit for all routes.',
+            }),
+            q: stringSchema('Free-text filter over path and summary.', 'rankings'),
+            limit: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 200,
+                default: 60,
+                description: 'Max routes to return (default 60, max 200).',
+            },
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        // Accept fortnite here even though it is not a PRIMARY_GAME: it has 21
+        // documented paths and no curated tools, so it is exactly what call_api
+        // callers come looking for.
+        const gameRaw = typeof args.game === 'string' ? args.game.toLowerCase().trim() : '';
+        if (gameRaw && !gameRaw.match(/^(lol|cs2|dota2|cod|ufc|fortnite)$/)) {
+            return errorEnvelope({
+                code: 'UNSUPPORTED_GAME',
+                message: `unsupported game "${gameRaw}"; use lol|cs2|dota2|cod|ufc|fortnite`,
+                game: null,
+                source: 'list_routes',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const q = typeof args.q === 'string' ? args.q.toLowerCase().trim() : '';
+        const limit = Math.min(Math.max(Number(args.limit) || 60, 1), 200);
+        const res = await fetchJson(ctx, '/openapi.json');
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status),
+                message: `openapi.json HTTP ${res.status}`,
+                game: gameRaw || null,
+                source: 'list_routes',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                rateLimit: res.headers,
+                httpStatus: res.status,
+                recover: [
+                    'Call list_capabilities for curated tools that need no route knowledge',
+                    'call_api accepts /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite',
+                ],
+            });
+        }
+        const spec = (res.data ?? {});
+        const paths = (spec.paths ?? {});
+        const rows = [];
+        for (const [path, ops] of Object.entries(paths)) {
+            if (!ops || typeof ops !== 'object')
+                continue;
+            for (const [method, opRaw] of Object.entries(ops)) {
+                if (!/^(get|post|put|patch|delete)$/i.test(method))
+                    continue;
+                const op = (opRaw ?? {});
+                const tags = Array.isArray(op.tags) ? op.tags : [];
+                rows.push({
+                    method: method.toUpperCase(),
+                    path,
+                    summary: typeof op.summary === 'string' ? op.summary : null,
+                    tag: typeof tags[0] === 'string' ? tags[0] : null,
+                });
+            }
+        }
+        let filtered = rows;
+        if (gameRaw)
+            filtered = filtered.filter((r) => r.path.startsWith(`/${gameRaw}`));
+        if (q) {
+            filtered = filtered.filter((r) => r.path.toLowerCase().includes(q) || (r.summary ?? '').toLowerCase().includes(q));
+        }
+        filtered.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+        const notes = [];
+        if (gameRaw && filtered.length === 0 && SPEC_OMITS[gameRaw])
+            notes.push(SPEC_OMITS[gameRaw]);
+        if (!gameRaw)
+            notes.push(SPEC_OMITS.lol);
+        if (filtered.length > limit) {
+            notes.push(`${filtered.length} routes matched; showing ${limit}. Narrow with game or q.`);
+        }
+        return successEnvelope({
+            data: {
+                specVersion: typeof spec.info?.version === 'string'
+                    ? spec.info.version
+                    : null,
+                totalDocumented: rows.length,
+                matched: filtered.length,
+                routes: filtered.slice(0, limit),
+                allowlistedPrefixes: ALLOWLIST_PREFIXES,
+                notes,
+                nextSteps: [
+                    'Prefer a curated tool when one covers the outcome (list_capabilities)',
+                    'call_api { path } for a route with no curated equivalent',
+                ],
+            },
+            game: gameRaw || null,
+            source: 'list_routes',
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+        });
+    },
+};
+export const metaTools = [listCapabilities, apiHealth, listRoutes, callApi];
 // silence unused import in case extractRows needed later
 void extractRows;

package/dist/tools/normalize.js

@@ -1,8 +1,34 @@
 /**
  * Cross-game row normalization for live/schedule boards and entity cards.
  */
-import { asRecord, pickString, unwrapPayload } from '../client.js';
-function sideFrom(name, id, slug, score) {
+import { asRecord, pickString, unwrapPayload, DEFAULT_API_BASE } from '../client.js';
+const IMAGE_PROXY_BASE = (process.env.CITO_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
+/**
+ * Bout rows carry raw ufc.com URLs but no proxied variant (only the fighter
+ * detail endpoint includes one). ufc.com can hotlink-block and sends no CORS
+ * header, so a browser-side card built straight off those URLs shows broken
+ * images. The proxy token is base64url of the source URL — verified to
+ * round-trip and serve HTTP 200 — so derive it rather than making the caller
+ * N+1 the fighter endpoint just to get a loadable image.
+ *
+ * UFC only: /public/images/lol/<token> returns HTTP 400, so other games get
+ * their raw URL and a null proxy rather than a fabricated link.
+ */
+function deriveProxiedImageUrl(rawUrl, game) {
+    if (!rawUrl || game !== 'ufc')
+        return null;
+    let host;
+    try {
+        host = new URL(rawUrl).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+    if (host !== 'ufc.com' && !host.endsWith('.ufc.com'))
+        return null;
+    return `${IMAGE_PROXY_BASE}/public/images/ufc/${Buffer.from(rawUrl, 'utf8').toString('base64url')}`;
+}
+function sideFrom(name, id, slug, score, extra) {
     if (!name && !id && !slug)
         return null;
     return {
@@ -10,9 +36,96 @@ function sideFrom(name, id, slug, score) {
         ...(id ? { id } : {}),
         ...(slug ? { slug } : {}),
         ...(score !== undefined ? { score } : {}),
+        ...(extra ?? {}),
+    };
+}
+function numOrNull(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string' && v !== '' && Number.isFinite(Number(v)))
+        return Number(v);
+    return null;
+}
+/**
+ * Collect image URLs from a corner/team row and its nested profile. Returns
+ * undefined when the upstream carried none, so lean rows stay lean; when any
+ * image exists every key is present (null where absent) — a missing key would
+ * read as "this API has no images" rather than "no image for this one".
+ */
+function imagesFrom(game, ...sources) {
+    const pick = (...keys) => {
+        for (const src of sources) {
+            if (!src)
+                continue;
+            for (const k of keys) {
+                const v = pickString(src[k]);
+                if (v)
+                    return v;
+            }
+        }
+        return null;
+    };
+    const images = {
+        headshotUrl: pick('headshotUrl', 'headshot'),
+        bodyImageUrl: pick('bodyImageUrl', 'fullBodyImageUrl'),
+        imageUrl: pick('imageUrl', 'image', 'photoUrl', 'logoUrl', 'logo'),
+        proxiedImageUrl: pick('proxiedImageUrl', 'proxiedHeadshotUrl'),
     };
+    if (!images.proxiedImageUrl) {
+        // Prefer the headshot for the proxied variant — it is the crop a card UI wants.
+        images.proxiedImageUrl =
+            deriveProxiedImageUrl(images.headshotUrl, game) ??
+                deriveProxiedImageUrl(images.imageUrl, game);
+    }
+    return Object.values(images).some(Boolean) ? images : undefined;
+}
+function recordFrom(...sources) {
+    for (const src of sources) {
+        if (!src)
+            continue;
+        const rec = asRecord(src.record);
+        const text = pickString(src.recordText, rec?.text);
+        if (!rec && !text)
+            continue;
+        const out = {
+            wins: numOrNull(rec?.wins),
+            losses: numOrNull(rec?.losses),
+            draws: numOrNull(rec?.draws),
+            noContest: numOrNull(rec?.noContest),
+            text: text ?? null,
+        };
+        if (Object.values(out).some((v) => v !== null))
+            return out;
+    }
+    return undefined;
 }
-function nestedSide(raw) {
+/** Enrichment shared by UFC corners and (where upstream supplies it) team rows. */
+function sideExtras(o, game) {
+    const profile = asRecord(o.profile) ?? undefined;
+    const fighter = asRecord(o.fighter) ?? undefined;
+    const images = imagesFrom(game, o, profile, fighter);
+    const record = recordFrom(o, profile, fighter);
+    const nickname = pickString(profile?.nickname, fighter?.nickname, o.nickname);
+    const rank = pickString(o.rankText, o.rank, profile?.rankText);
+    const championStatus = pickString(o.championStatus, profile?.championStatus);
+    const division = pickString(profile?.division, o.division, o.weightClass);
+    const country = pickString(o.country, profile?.country);
+    const flag = pickString(o.flag, profile?.flag);
+    const outcome = pickString(o.outcome);
+    return {
+        ...(nickname ? { nickname } : {}),
+        ...(images ? { images } : {}),
+        ...(record ? { record } : {}),
+        ...(rank ? { rank } : {}),
+        // "none" carries no signal for a page; only surface an actual belt state.
+        ...(championStatus && championStatus.toLowerCase() !== 'none' ? { championStatus } : {}),
+        ...(division ? { division } : {}),
+        ...(country ? { country } : {}),
+        ...(flag ? { flag } : {}),
+        ...(outcome ? { outcome } : {}),
+    };
+}
+function nestedSide(raw, game) {
     const o = asRecord(raw);
     if (!o) {
         if (typeof raw === 'string')
@@ -29,7 +142,7 @@ function nestedSide(raw) {
         : typeof scoreRaw === 'string' && scoreRaw !== ''
             ? Number(scoreRaw)
             : null;
-    return sideFrom(name, id, slug, Number.isFinite(score) ? score : null);
+    return sideFrom(name, id, slug, Number.isFinite(score) ? score : null, sideExtras(o, game));
 }
 function scoreNum(v) {
     if (typeof v === 'number' && Number.isFinite(v))
@@ -42,10 +155,22 @@ export function normalizeMatch(game, row, forcedStatus) {
     // Always peel { success, data } so UFC bout fighters[] / status are visible.
     const r = asRecord(unwrapPayload(row)) ?? asRecord(row) ?? {};
     const matchId = pickString(r.matchId, r.boutId, r.id, r.gameId, r.match_id, r.dataId, r.fightMetricId, r.ufcFightId) ?? 'unknown';
-    let team1 = nestedSide(r.team1) ??
+    let team1 = nestedSide(r.team1, game) ??
         sideFrom(pickString(r.team1Name, r.team_a_name, r.redName, r.fighter1Name, r.homeName), pickString(r.team1Id, r.team1_id, r.redId, r.fighter1Id), pickString(r.team1Slug, r.redSlug, r.fighter1Slug), scoreNum(r.team1Score ?? r.score1 ?? r.team1Maps ?? r.redScore));
-    let team2 = nestedSide(r.team2) ??
+    let team2 = nestedSide(r.team2, game) ??
         sideFrom(pickString(r.team2Name, r.team_b_name, r.blueName, r.fighter2Name, r.awayName), pickString(r.team2Id, r.team2_id, r.blueId, r.fighter2Id), pickString(r.team2Slug, r.blueSlug, r.fighter2Slug), scoreNum(r.team2Score ?? r.score2 ?? r.team2Maps ?? r.blueScore));
+    // CS2 rows nest team1/team2 objects that lack a score; a nested side must not
+    // shadow the flat score fields (team1Score/score1/team1Maps) with score:null.
+    if (team1 && team1.score == null) {
+        const s = scoreNum(r.team1Score ?? r.score1 ?? r.team1Maps ?? r.redScore);
+        if (s != null)
+            team1 = { ...team1, score: s };
+    }
+    if (team2 && team2.score == null) {
+        const s = scoreNum(r.team2Score ?? r.score2 ?? r.team2Maps ?? r.blueScore);
+        if (s != null)
+            team2 = { ...team2, score: s };
+    }
     // UFC / live corners: red/blue objects, corner arrays, or fighters[] with corner field.
     // Public API serializeBout uses fighters:[{ corner, fighterName, fighterSlug, profile:{name,slug} }].
     // Live tracking uses red/blue + fighters[] (not team1/team2).
@@ -64,7 +189,7 @@ export function normalizeMatch(game, row, forcedStatus) {
             const id = pickString(o.id, o.fighterId, profile?.id, fighter?.id);
             const slug = pickString(o.slug, o.fighterSlug, profile?.slug, fighter?.slug);
             const score = scoreNum(o.score ?? o.points);
-            return sideFrom(name, id, slug, score);
+            return sideFrom(name, id, slug, score, sideExtras(o, game));
         };
         team1 =
             team1 ??
@@ -94,8 +219,8 @@ export function normalizeMatch(game, row, forcedStatus) {
     }
     // COD sometimes uses teams[]
     if ((!team1 || !team2) && Array.isArray(r.teams)) {
-        team1 = team1 ?? nestedSide(r.teams[0]);
-        team2 = team2 ?? nestedSide(r.teams[1]);
+        team1 = team1 ?? nestedSide(r.teams[0], game);
+        team2 = team2 ?? nestedSide(r.teams[1], game);
     }
     const startTime = pickString(r.startTime, r.scheduledAt, r.startsAt, r.date, r.startDate, r.beginAt, asRecord(r.event)?.startsAt, asRecord(r.event)?.startTime, asRecord(r.event)?.date) ?? null;
     const statusRaw = pickString(r.status, r.state, r.matchStatus, r.boutStatus)?.toLowerCase() ?? '';
@@ -151,9 +276,12 @@ export function normalizeMatch(game, row, forcedStatus) {
     const leagueSlug = pickString(asRecord(r.league)?.slug, r.leagueSlug);
     // Prefer explicit title/label when present, but never keep the placeholder
     // "? vs ?" once fighter/team names were resolved (UFC fighters[] / red-blue).
+    // When both sides lack names, prefer event / weight / bout id over opaque "? vs ?"
+    // so agent boards (live_matches, upcoming_schedule, event_card) stay legible.
     const vsLabel = `${team1?.name ?? '?'} vs ${team2?.name ?? '?'}`;
     const explicit = pickString(r.label, r.title, r.name);
     const explicitIsPlaceholder = explicit != null && /^\?\s*vs\s*\?$/i.test(explicit.trim());
+    const weightOrClass = pickString(r.weightClass, r.division, r.weight_class, r.boutClass);
     let label;
     if (explicit && !explicitIsPlaceholder) {
         label = explicit;
@@ -162,8 +290,28 @@ export function normalizeMatch(game, row, forcedStatus) {
         label = vsLabel;
     }
     else {
-        label = explicit ?? vsLabel;
+        // Identity fallbacks — never invent fighter names, but avoid bare "? vs ?"
+        label =
+            pickString(eventName, eventSlug, weightOrClass) ??
+                (matchId && matchId !== 'unknown' ? `Bout ${matchId}` : null) ??
+                vsLabel;
     }
+    // Bout metadata already present on the upstream row. Passing it through here
+    // is what stops an agent from N+1'ing call_api to rebuild a fight card.
+    const cardSection = pickString(r.cardSection, r.cardSegment, r.segment);
+    const cardPosition = pickString(r.cardPosition);
+    const cardSectionOrder = numOrNull(r.cardSectionOrder);
+    const boutOrder = numOrNull(r.boutOrder);
+    const hasCard = cardSection != null || cardPosition != null || cardSectionOrder != null || boutOrder != null;
+    const method = pickString(r.method);
+    const methodDetails = pickString(r.methodDetails);
+    const resultTime = pickString(r.resultTime);
+    // UFC sends referee as { id, name, firstName, lastName } — not a string.
+    const referee = pickString(r.referee, asRecord(r.referee)?.name);
+    const winnerSlug = pickString(r.winnerFighterSlug, r.winnerSlug, r.winner);
+    const resultRound = numOrNull(r.resultRound);
+    const hasResultDetail = method != null || resultRound != null || winnerSlug != null || resultTime != null;
+    const isCancelled = r.isCancelled === true;
     return {
         game,
         matchId,
@@ -174,8 +322,55 @@ export function normalizeMatch(game, row, forcedStatus) {
         team2,
         event: eventName || eventId || eventSlug ? { id: eventId, slug: eventSlug, name: eventName } : null,
         league: leagueName || leagueId || leagueSlug ? { id: leagueId, slug: leagueSlug, name: leagueName } : null,
+        ...(weightOrClass ? { weightClass: weightOrClass } : {}),
+        ...(r.titleBout != null ? { titleBout: Boolean(r.titleBout) } : {}),
+        ...(hasCard
+            ? {
+                card: {
+                    section: cardSection ?? null,
+                    sectionOrder: cardSectionOrder,
+                    position: cardPosition ?? null,
+                    order: boutOrder,
+                },
+            }
+            : {}),
+        ...(hasResultDetail
+            ? {
+                result: {
+                    method: method ?? null,
+                    methodDetails: methodDetails ?? null,
+                    round: resultRound,
+                    time: resultTime ?? null,
+                    referee: referee ?? null,
+                    winnerSlug: winnerSlug ?? null,
+                },
+            }
+            : {}),
+        ...(isCancelled
+            ? { cancelled: { isCancelled: true, reason: pickString(r.cancellationReason) ?? null } }
+            : {}),
     };
 }
+/**
+ * Sort a fight card the way it is presented: main card before prelims, and the
+ * main event at the top of its section. Rows without placement keep their
+ * upstream order behind those that have it.
+ */
+export function sortByCardOrder(rows) {
+    const rank = (x, i) => ({
+        section: x.card?.sectionOrder ?? Number.MAX_SAFE_INTEGER,
+        order: x.card?.order ?? Number.MAX_SAFE_INTEGER,
+        i,
+    });
+    return rows
+        .map((x, i) => ({ x, k: rank(x, i) }))
+        .sort((a, b) => a.k.section !== b.k.section
+        ? a.k.section - b.k.section
+        : a.k.order !== b.k.order
+            ? a.k.order - b.k.order
+            : a.k.i - b.k.i)
+        .map((e) => e.x);
+}
 export function entityRef(row, type, game) {
     const r = asRecord(row) ?? {};
     const id = pickString(r.id, r.teamId, r.playerId, r.lolPlayerId, r.codPlayerId, r.matchId, r.boutId, r.eventId, r.tournamentId, r.leagueId) ??