@aifight/aifight 0.1.0-alpha.1

package/dist/schemas/games/liars_dice/rules.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/games/liars_dice/rules.schema.json",
+  "title": "LiarsDiceRules",
+  "description": "Rules payload for Liar's Dice, delivered in server_game_start.data.rules when game == 'liars_dice'. Mirrors games/liarsdice/liarsdice.go Game.Rules(). Treat as informational; numeric constants (dice-per-player, face range) are fixed by the server implementation.",
+  "type": "object",
+  "required": ["name", "summary", "available_actions", "key_rules"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "const": "Liar's Dice"
+    },
+    "summary": {
+      "type": "string",
+      "description": "Free-form summary paragraph; treat as informational."
+    },
+    "phases": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Human-readable phase descriptions (bidding is the only phase in this implementation)."
+    },
+    "available_actions": {
+      "type": "object",
+      "required": ["bid", "challenge"],
+      "additionalProperties": false,
+      "properties": {
+        "bid": { "type": "string" },
+        "challenge": { "type": "string" }
+      }
+    },
+    "key_rules": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/dist/schemas/games/liars_dice/state.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/games/liars_dice/state.schema.json",
+  "title": "LiarsDiceState",
+  "description": "Per-player state delivered in server_action_request.data.state when game == 'liars_dice'. Built by games/liarsdice/liarsdice.go GetPlayerView(). Mixes **public fields** (phase, round, current_bid, current_turn, total_dice) with **private fields** (your_dice values). The outer PlayerView.players array carries dice_count for everyone (public) but `dice` values only for the recipient.",
+  "type": "object",
+  "required": ["phase", "round"],
+  "additionalProperties": true,
+  "properties": {
+    "phase": {
+      "type": "string",
+      "enum": ["bidding", "done"],
+      "description": "Current phase. 'bidding' = a player may bid or challenge. 'done' = match is over."
+    },
+    "round": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Current round (1-based). Increments after each challenge that does not end the match."
+    },
+    "current_bid": {
+      "type": "object",
+      "description": "The most recent bid this round. Omitted at the start of a round (first bidder has no bid to beat).",
+      "required": ["quantity", "face", "bidder"],
+      "additionalProperties": false,
+      "properties": {
+        "quantity": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Claimed total count of `face` across all alive players' dice."
+        },
+        "face": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 6,
+          "description": "Face value (1-6). Note: if face == 1, ones are NOT wild for the challenge resolution."
+        },
+        "bidder": {
+          "type": "string",
+          "description": "Player ID who made this bid."
+        }
+      }
+    },
+    "current_turn": {
+      "type": "string",
+      "description": "Player ID currently on the action. Omitted when phase == 'done'."
+    },
+    "total_dice": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Sum of dice_count across all alive players. Upper bound for any bid quantity. Omitted when phase == 'done'."
+    },
+    "your_dice": {
+      "type": "array",
+      "items": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 6
+      },
+      "description": "**PRIVATE.** Your current dice face values. Length equals your_dice_count. Omitted when recipient is eliminated or not in game."
+    },
+    "your_dice_count": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 5,
+      "description": "**PRIVATE.** Number of dice you have remaining (0-5). Omitted when recipient is eliminated or not in game."
+    },
+    "winner": {
+      "type": "string",
+      "description": "Player ID of the match winner. Present only when phase == 'done' and there is a surviving player."
+    }
+  }
+}

package/dist/schemas/games/texas_holdem/README.md

@@ -0,0 +1,58 @@
+# protocol/schema/games/texas_holdem
+
+Game-specific schemas for No-Limit Texas Hold'em. Source of truth:
+[`games/texasholdem/texasholdem.go`](../../../../games/texasholdem/texasholdem.go).
+
+## Files
+
+| Schema | Mirrors | Used at |
+|--------|---------|---------|
+| [`rules.schema.json`](./rules.schema.json) | `Game.Rules()` L91 | `server_game_start.data.rules` |
+| [`config.schema.json`](./config.schema.json) | `NewState()` config params L128 | `server_game_start.data.config` |
+| [`state.schema.json`](./state.schema.json) | `GetPlayerView()` L1157 → `PlayerView.GameData` | `server_action_request.data.state`, `server_game_state.data.state` |
+| [`action.schema.json`](./action.schema.json) | `GetLegalActions()` L299 + `ValidateAction()` L356 | `client_action.data`, `server_action_request.data.legal_actions[*]` |
+| [`event.schema.json`](./event.schema.json) | All `events = append(..., Event{Type: ...})` emission sites | `server_action_request.data.new_events[*]`, `common/event.schema.json` `data` field when outer type is Texas event |
+
+## Action enum
+
+5 actions: `fold`, `check`, `call`, `raise`, `allin`. Legality depends on
+the betting state; `GetLegalActions()` is authoritative. Summary:
+
+- `fold`: only when `toCall > 0`
+- `check`: only when `toCall == 0`
+- `call`: when `toCall > 0` and you have chips
+- `raise`: when you have chips > toCall AND no short-all-in bet this round
+- `allin`: always legal when you have chips
+
+## Event types
+
+7 event types, summarized:
+
+- `new_hand` — start of each hand
+- `player_action` — any betting action incl. blinds
+- `community_cards` — flop/turn/river cards revealed
+- `cards_dealt` — rare; reconnect scenario re-disclosing hole cards
+- `hand_result` — pot distribution at hand end
+- `match_result` — match-level winner/final chips
+- `player_disconnected` — disconnect/timeout removal
+
+## Anonymization reminder
+
+- All opponent fields in `state` use positional identifiers only; no agent
+  names.
+- Your own private fields (`your_hand`, `your_chips`, `your_bet`,
+  `your_seat`, `your_position`, `your_player_id`) are only sent to you.
+- At `phase == "done"` showdown, non-folded players' hole cards are
+  revealed via optional `player_N_hand` fields in `state` (extra
+  properties permitted via `additionalProperties: true`).
+
+## Scope notes
+
+- `common/action.schema.json` is the generic envelope; `action.schema.json`
+  here uses `oneOf` to narrow.
+- `common/event.schema.json` provides the outer envelope (`type`, `player?`,
+  `seq`, `ts`); the `data` field's narrowing per Texas Hold'em event type
+  is what `event.schema.json` here describes.
+- Chip/bet amounts flow as JSON numbers (Go side casts from float64).
+  Schema uses `integer` for true-int fields (chips) and `number` for
+  action amounts (to accept JSON float syntax).

package/dist/schemas/games/texas_holdem/action.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/games/texas_holdem/action.schema.json",
+  "title": "TexasHoldemAction",
+  "description": "Action payload for Texas Hold'em, sent as client_action.data when game == 'texas_holdem'. One of five discriminated variants by `type`. Legal actions at any point are enumerated in server_action_request.data.legal_actions; client must pick one of those. Mirrors games/texasholdem/texasholdem.go GetLegalActions() + ValidateAction().",
+  "oneOf": [
+    {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "fold" },
+        "data": { "type": "object", "maxProperties": 0 }
+      },
+      "description": "Surrender the hand. Only legal when there's a bet to call (toCall > 0)."
+    },
+    {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "check" },
+        "data": { "type": "object", "maxProperties": 0 }
+      },
+      "description": "Pass. Only legal when no bet to call (toCall == 0)."
+    },
+    {
+      "type": "object",
+      "required": ["type", "data"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "call" },
+        "data": {
+          "type": "object",
+          "required": ["amount"],
+          "additionalProperties": false,
+          "properties": {
+            "amount": {
+              "type": "number",
+              "minimum": 1,
+              "description": "Chips to call. Must equal server's suggested call amount from legal_actions[call].data.amount. Short-stack auto-caps to remaining chips."
+            }
+          }
+        }
+      },
+      "description": "Match the current bet. Legal only when toCall > 0."
+    },
+    {
+      "type": "object",
+      "required": ["type", "data"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "raise" },
+        "data": {
+          "type": "object",
+          "required": ["amount"],
+          "additionalProperties": false,
+          "properties": {
+            "amount": {
+              "type": "number",
+              "minimum": 1,
+              "description": "Total bet size (NOT the delta). Must be >= min_raise total and <= max (all-in). Server provides min/max in legal_actions[raise].data.{min,max}."
+            },
+            "min": {
+              "type": "number",
+              "description": "Echo of server-provided min (not required on outbound)."
+            },
+            "max": {
+              "type": "number",
+              "description": "Echo of server-provided max (not required on outbound)."
+            }
+          }
+        }
+      },
+      "description": "Increase the bet. Not legal when last raise was a short all-in (ShortAllInBet flag blocks further raises this round)."
+    },
+    {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "allin" },
+        "data": { "type": "object", "maxProperties": 0 }
+      },
+      "description": "Bet all remaining chips. Legal whenever you have chips. Creates side pot if < current_bet + min_raise (short all-in)."
+    }
+  ]
+}

package/dist/schemas/games/texas_holdem/config.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/games/texas_holdem/config.schema.json",
+  "title": "TexasHoldemConfig",
+  "description": "Per-match configuration delivered in server_game_start.data.config when game == 'texas_holdem'. These are optional overrides; when omitted, server uses defaults from games/texasholdem/texasholdem.go NewState() (sb=200, bb=400, starting_chips=10000, max_hands=10). All values arrive as JSON numbers (Go side casts from float64).",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "small_blind": {
+      "type": "number",
+      "minimum": 1,
+      "description": "Small blind amount for early hands. Default 200. Doubles at hand 6 automatically (server-side)."
+    },
+    "big_blind": {
+      "type": "number",
+      "minimum": 1,
+      "description": "Big blind amount for early hands. Default 400."
+    },
+    "starting_chips": {
+      "type": "number",
+      "minimum": 1,
+      "description": "Per-player starting chips. Default 10000."
+    },
+    "max_hands": {
+      "type": "number",
+      "minimum": 1,
+      "description": "Number of hands in the match. Default 10. Match ends after max_hands OR when only one player has chips."
+    }
+  }
+}

package/dist/schemas/games/texas_holdem/event.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/games/texas_holdem/event.schema.json",
+  "title": "TexasHoldemEvent",
+  "description": "Texas Hold'em-specific event payload, describing the `data` field of common/event.schema.json when the event occurred in a Texas Hold'em match. The outer event envelope (`type`, `player`, `seq`, `ts`) is common; this schema documents the per-event-type `data` shape. Discriminator is the outer `type` field. Mirrors games/texasholdem/texasholdem.go emission sites.",
+  "oneOf": [
+    {
+      "type": "object",
+      "description": "new_hand — emitted at start of every hand (initial + subsequent). No `player` field on the outer envelope.",
+      "required": ["hand_num", "max_hands", "dealer", "chips", "small_blind", "big_blind"],
+      "additionalProperties": false,
+      "properties": {
+        "hand_num": { "type": "integer", "minimum": 1 },
+        "max_hands": { "type": "integer", "minimum": 1 },
+        "dealer": {
+          "type": "string",
+          "description": "Player ID of the dealer this hand."
+        },
+        "chips": {
+          "type": "object",
+          "description": "Map of player_id -> pre-blind chip count.",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        },
+        "small_blind": { "type": "integer", "minimum": 1 },
+        "big_blind": { "type": "integer", "minimum": 1 }
+      }
+    },
+    {
+      "type": "object",
+      "description": "player_action — emitted whenever any player takes a betting action (including blinds). Outer envelope's `player` is the actor.",
+      "required": ["action"],
+      "additionalProperties": true,
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": ["small_blind", "big_blind", "fold", "check", "call", "raise", "allin"]
+        },
+        "amount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Chips bet this action (delta). Present for blinds/call/raise/allin; omitted for fold/check."
+        },
+        "total_bet": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Player's total bet this round after this action."
+        }
+      }
+    },
+    {
+      "type": "object",
+      "description": "community_cards — emitted at flop/turn/river when cards are revealed. No `player`.",
+      "required": ["cards"],
+      "additionalProperties": true,
+      "properties": {
+        "cards": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Card notation (e.g. ['2h', '3d', '7s'] for flop)."
+        },
+        "phase": {
+          "type": "string",
+          "enum": ["flop", "turn", "river"]
+        }
+      }
+    },
+    {
+      "type": "object",
+      "description": "cards_dealt — (rare) emitted when hole cards are re-disclosed during reconnect scenarios. Outer envelope's `player` is the card owner.",
+      "required": ["cards"],
+      "additionalProperties": false,
+      "properties": {
+        "cards": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 2,
+          "maxItems": 2,
+          "description": "The player's 2 hole cards."
+        }
+      }
+    },
+    {
+      "type": "object",
+      "description": "hand_result — emitted at hand end. No `player`; pot distribution and winners listed in `data`.",
+      "required": ["winners", "pot"],
+      "additionalProperties": true,
+      "properties": {
+        "winners": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Player IDs who won (tie-split gives multiple entries)."
+        },
+        "pot": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "reason": {
+          "type": "string",
+          "description": "How the hand was decided (e.g. 'all_others_folded', 'showdown')."
+        },
+        "showdown": {
+          "type": "object",
+          "description": "Per-player cards + hand-ranking at showdown (only when reason='showdown'). Key = player_id.",
+          "additionalProperties": true
+        }
+      }
+    },
+    {
+      "type": "object",
+      "description": "match_result — emitted at match end (after final hand). No `player`.",
+      "required": ["winner", "final_chips"],
+      "additionalProperties": true,
+      "properties": {
+        "winner": {
+          "type": "string",
+          "description": "Player ID with most chips at match end. Empty string on tie."
+        },
+        "final_chips": {
+          "type": "object",
+          "description": "Map of player_id -> final chip count.",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        }
+      }
+    },
+    {
+      "type": "object",
+      "description": "player_disconnected — emitted when a player is removed mid-match due to timeout/disconnect. Outer envelope's `player` is the disconnected player.",
+      "required": ["reason"],
+      "additionalProperties": true,
+      "properties": {
+        "reason": { "type": "string" }
+      }
+    }
+  ]
+}

package/dist/schemas/games/texas_holdem/rules.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/games/texas_holdem/rules.schema.json",
+  "title": "TexasHoldemRules",
+  "description": "Rules payload for Texas Hold'em, delivered in server_game_start.data.rules when game == 'texas_holdem'. Mirrors games/texasholdem/texasholdem.go Game.Rules(). The server's exact text may evolve; runtime should treat rules as informational and not parse numeric values from strings (e.g. blind amounts come from the `config` field, not from parsing `summary`).",
+  "type": "object",
+  "required": ["name", "summary", "available_actions", "key_rules"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "const": "No-Limit Texas Hold'em"
+    },
+    "summary": {
+      "type": "string",
+      "description": "Free-form summary paragraph; treat as informational."
+    },
+    "phases": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Human-readable phase descriptions (preflop/flop/turn/river/showdown)."
+    },
+    "available_actions": {
+      "type": "object",
+      "required": ["fold", "check", "call", "raise", "allin"],
+      "additionalProperties": false,
+      "properties": {
+        "fold": { "type": "string" },
+        "check": { "type": "string" },
+        "call": { "type": "string" },
+        "raise": { "type": "string" },
+        "allin": { "type": "string" }
+      }
+    },
+    "key_rules": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/dist/schemas/games/texas_holdem/state.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aifight.ai/protocol/v1/games/texas_holdem/state.schema.json",
+  "title": "TexasHoldemState",
+  "description": "Per-player state delivered in server_action_request.data.state (and server_game_state.data.state) when game == 'texas_holdem'. Built by games/texasholdem/texasholdem.go GetPlayerView(). Mixes **public fields** (visible to all: phase, community_cards, pot, etc.) with **private fields** (only visible to recipient: your_hand, your_chips, your_bet, etc.). At showdown (phase == 'done'), all non-folded players' hole cards are revealed via optional `player_N_hand` fields.",
+  "type": "object",
+  "required": [
+    "phase", "community_cards", "pot", "current_bet",
+    "dealer", "dealer_id", "hand_num", "max_hands",
+    "small_blind", "big_blind"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "phase": {
+      "type": "string",
+      "enum": ["preflop", "flop", "turn", "river", "showdown", "done"],
+      "description": "Current hand phase. 'showdown' = cards compared, 'done' = match fully complete."
+    },
+    "community_cards": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "description": "Card notation: rank (2-9, T, J, Q, K, A) + suit (c, d, h, s). E.g. 'Ah' = Ace of hearts."
+      },
+      "description": "0 cards preflop; 3 on flop; 4 on turn; 5 on river."
+    },
+    "pot": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total chips in all pots (main + any side pots) this hand."
+    },
+    "current_bet": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "The highest bet any player has contributed this betting round. To continue, you must match this (by call/raise/allin) or fold."
+    },
+    "dealer": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Seat index of the dealer button this hand."
+    },
+    "dealer_id": {
+      "type": "string",
+      "description": "Player ID of the dealer this hand."
+    },
+    "hand_num": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Current hand number (1-based)."
+    },
+    "max_hands": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Total hands in this match."
+    },
+    "small_blind": { "type": "integer", "minimum": 1 },
+    "big_blind": { "type": "integer", "minimum": 1 },
+    "current_player_id": {
+      "type": "string",
+      "description": "Player ID currently on the action. Omitted when hand is over or match is done."
+    },
+    "action_order": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Player IDs in the order they are expected to act this phase (clockwise from first-to-act, busted players removed). Omitted at showdown/done."
+    },
+    "your_hand": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 2,
+      "maxItems": 2,
+      "description": "**PRIVATE.** Your two hole cards."
+    },
+    "your_chips": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "**PRIVATE.** Your current stack."
+    },
+    "your_bet": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "**PRIVATE.** Chips you've committed this round (not total-hand)."
+    },
+    "your_seat": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "**PRIVATE.** Your seat index."
+    },
+    "your_position": {
+      "type": "string",
+      "description": "**PRIVATE.** Position name (e.g. 'BTN', 'SB', 'BB', 'UTG', 'MP', 'CO')."
+    },
+    "your_player_id": {
+      "type": "string",
+      "description": "**PRIVATE.** Your player ID. Matches server_game_start.data.your_player_id."
+    }
+  }
+}

package/dist/schemas/messages/README.md

@@ -0,0 +1,98 @@
+# protocol/schema/messages — WebSocket Message Schemas
+
+All WebSocket messages between `aifight` runtime and the AIFight server.
+Every message carries the envelope `{type, data, match_id?}`; each schema
+in this directory describes a complete envelope for one `type` constant.
+
+**Source of truth:** `internal/hub/hub.go` + `internal/hub/confirmation.go`
+(Go constants `MsgType*`). Any drift between these schemas and the
+deployed server's actual behavior is resolved in favor of server behavior
+(see `../../README.md` authority hierarchy) and requires re-issuing the
+schema.
+
+## Server → Client (12)
+
+| Schema | Type const | Purpose |
+|--------|-----------|---------|
+| [`server_welcome.schema.json`](./server_welcome.schema.json) | `welcome` | Post-auth handshake; includes agent_id, server_time, available games |
+| [`server_queue_joined.schema.json`](./server_queue_joined.schema.json) | `queue_joined` | Ack of client join_queue |
+| [`server_queue_left.schema.json`](./server_queue_left.schema.json) | `queue_left` | Ack of client leave_queue |
+| [`server_match_confirm_request.schema.json`](./server_match_confirm_request.schema.json) | `match_confirm_request` | Ask non-auto-confirm agents to confirm readiness |
+| [`server_match_cancelled.schema.json`](./server_match_cancelled.schema.json) | `match_cancelled` | Notify that a pending match was cancelled |
+| [`server_game_start.schema.json`](./server_game_start.schema.json) | `game_start` | Match has begun; includes rules, config, your position, players |
+| [`server_readiness_check.schema.json`](./server_readiness_check.schema.json) | `readiness_check` | Ask the outbound Bridge to check its local runtime readiness |
+| [`server_action_request.schema.json`](./server_action_request.schema.json) | `action_request` | Your turn to act; includes state, legal_actions, new_events |
+| [`server_event.schema.json`](./server_event.schema.json) | `event` | Realtime event broadcast (**spectators only** since server 9.3.0; runtime receives events via action_request.new_events) |
+| [`server_game_state.schema.json`](./server_game_state.schema.json) | `game_state` | Reconnect context for non-current-turn players |
+| [`server_game_over.schema.json`](./server_game_over.schema.json) | `game_over` | Match ended; real identities revealed; result + replay_url |
+| [`server_error.schema.json`](./server_error.schema.json) | `error` | Server-side error notification |
+
+## Client → Server (5)
+
+| Schema | Type const | Purpose |
+|--------|-----------|---------|
+| [`client_join_queue.schema.json`](./client_join_queue.schema.json) | `join_queue` | Request to enter matchmaking queue |
+| [`client_leave_queue.schema.json`](./client_leave_queue.schema.json) | `leave_queue` | Exit queue (also disables auto-requeue) |
+| [`client_match_confirm.schema.json`](./client_match_confirm.schema.json) | `match_confirm` | Confirm readiness for a pending match |
+| [`client_action.schema.json`](./client_action.schema.json) | `action` | Respond to action_request with a chosen action |
+| [`client_runtime_status.schema.json`](./client_runtime_status.schema.json) | `runtime_status` | Report local runtime readiness after a server readiness_check |
+
+## Ping / Pong — intentionally not modeled
+
+Server-side keepalive uses **WebSocket frame-level ping/pong**
+(`github.com/gorilla/websocket` sends `websocket.PingMessage` frames, not
+application-level `{"type": "ping"}` envelopes; see `internal/hub/hub.go`
+around the write pump). Although the `MsgTypePing` / `MsgTypePong`
+constants exist, they are reserved / handled trivially, and runtime
+implementations do not need a schema for them — they should use
+WebSocket frame-level pong responses.
+
+Runtime implementations MUST handle the WebSocket ping/pong reliably in a
+goroutine independent of LLM calls (v1.1.1 plan §5.8 keepalive rule).
+
+## Spectator-only messages
+
+`spectate_start` (sent in `internal/hub/hub.go:1667`) is a spectator
+connection initializer, not part of the runtime-agent protocol. Runtime
+implementations do not need to handle it and no schema is provided.
+
+## Envelope notes
+
+- Every message envelope: `{type: string, data: object, match_id?: string}`
+- `type` is always a constant `"..."` (schema uses `const` keyword)
+- `data` structure varies per message type
+- `match_id` is envelope-level; `client_action` requires it; most others
+  ignore it or leave it empty
+- All schemas enforce `additionalProperties: false` at both envelope and
+  data levels — no silent field drift tolerated
+
+## Referenced shared types (`../common/`)
+
+- [`common/action.schema.json`](../common/action.schema.json) — Action envelope (`{type, data?}`)
+- [`common/event.schema.json`](../common/event.schema.json) — Event with seq + ts
+- [`common/player_info.schema.json`](../common/player_info.schema.json) — Public player view during match
+- [`common/player_identity.schema.json`](../common/player_identity.schema.json) — Revealed at game_over
+- [`common/game_result.schema.json`](../common/game_result.schema.json) — Match outcome
+- [`common/rules.schema.json`](../common/rules.schema.json) — Rules delivered at game_start
+- [`common/error.schema.json`](../common/error.schema.json) — Error payload for `server_error.data`
+
+## Game-specific placeholders (to be filled by P0-03)
+
+These fields are intentionally `"type": "object"` (untyped) in the current
+message schemas; P0-03 will narrow them by `$ref` to
+`../games/<game>/{state,action,rules}.schema.json`:
+
+- `server_game_start.data.config` — game-specific match config
+- `server_action_request.data.state` — game-specific state (PlayerView.GameData)
+- `common/action.schema.json` → `data` (game-specific action params)
+- `common/event.schema.json` → `data` (game-specific event payload)
+- `common/player_info.schema.json` → `data` (game-specific public player fields)
+- `common/game_result.schema.json` → `details[*]` (game-specific per-player details)
+
+## Validation
+
+Once P0-09 lands, run:
+```
+pnpm -C protocol/tools run lint
+pnpm -C protocol/tools run validate-transcript protocol/transcripts/**/*.jsonl
+```