diff --git a/Server/docs/SOR.Ai-Architecture-Plan.md b/Server/docs/SOR.Ai-Architecture-Plan.md
new file mode 100644
index 0000000..38e116e
--- /dev/null
+++ b/Server/docs/SOR.Ai-Architecture-Plan.md
@@ -0,0 +1,1798 @@
+# SOR.Ai — AI Player Architecture Plan
+
+## Overview
+
+`SOR.Ai` is a new server-side project that provides AI-controlled players for free-play (custom lobby) games.
+Players can spin up a lobby, add 1–N AI opponents, choose difficulty, and play immediately — no wait queue needed.
+
+The AI integrates as **"just another player"** from the perspective of all existing infrastructure: it holds a
+virtual account, joins lobbies via the existing `CustomLobby` system, and submits game actions through the same
+`IMessageHandler` pipeline that human clients use. No changes to `GameEngine`, protocol contracts, or client code
+are required.
+
+---
+
+## Table of Contents
+
+1. [Project Structure](#1-project-structure)
+2. [Integration Points](#2-integration-points)
+3. [AI Account Model](#3-ai-account-model)
+4. [Game Flow — How AI Joins & Plays](#4-game-flow)
+5. [Decision Engine Architecture](#5-decision-engine-architecture)
+6. [Difficulty System](#6-difficulty-system)
+7. [Training & Improvement Strategy](#7-training--improvement-strategy)
+8. [Deck Composition for AI](#8-deck-composition-for-ai)
+9. [Multi-Player & Team AI](#9-multi-player--team-ai)
+10. [New Message Types](#10-new-message-types)
+11. [Database Schema Additions](#11-database-schema-additions)
+12. [Implementation Phases](#12-implementation-phases)
+
+---
+
+## 1. Project Structure
+
+```
+Server/src/SOR.Ai/
+├── SOR.Ai.csproj
+├── ServiceRegistration.cs — DI wiring, registers all AI services
+│
+├── Core/
+│ ├── AiPlayer.cs — Runtime state for one AI-controlled seat
+│ ├── AiPlayerSession.cs — Binds an AiPlayer to a GameSession
+│ ├── AiPlayerSessionManager.cs — Manages all active AI sessions (keyed by sessionId)
+│ └── AiTurnContext.cs — Snapshot of GameState from an AI's perspective
+│
+├── Engine/
+│ ├── IAiDecisionEngine.cs — Interface: next action given AiTurnContext
+│ ├── HeuristicDecisionEngine.cs — Rule-based engine (Difficulty 1–5)
+│ ├── MonteCarloEngine.cs — MCTS-based engine (Difficulty 6–8)
+│ ├── NeuralDecisionEngine.cs — ML model wrapper (Difficulty 9–10, future)
+│ └── RandomDecisionEngine.cs — Purely random (used for sanity testing / Novice)
+│
+├── Heuristics/
+│ ├── ScoringFunctions.cs — Board evaluation: material, position, affinity control
+│ ├── ActionCandidateGenerator.cs — Enumerate all legal moves from a GameState
+│ ├── ThreatDetector.cs — Identifies units threatening ArchSpirit
+│ ├── ResourceOptimizer.cs — SP/ST/MP expenditure strategies
+│ └── AffinityController.cs — Tile control and Terramorpha placement logic
+│
+├── MCTS/
+│ ├── MctsTree.cs — Monte Carlo Tree Search node + expansion
+│ ├── MctsSimulator.cs — Random playout from a given GameState
+│ └── MctsEvaluator.cs — Leaf-node evaluation function
+│
+├── Training/
+│ ├── SelfPlayOrchestrator.cs — Runs batches of AI-vs-AI games for data generation
+│ ├── GameReplayExporter.cs — Converts GameActionLog rows → training samples
+│ ├── FeatureExtractor.cs — Converts GameState → numeric feature vector
+│ └── TrainingDataWriter.cs — Writes JSONL / Parquet training files
+│
+├── Lobby/
+│ ├── AiLobbyService.cs — Handles "add AI to lobby" requests
+│ └── AiSlotAssigner.cs — Assigns AI accounts to open seats
+│
+└── Handlers/
+ ├── GameAddAiHandler.cs — Handles "game.ai.add" message from host
+ ├── GameRemoveAiHandler.cs — Handles "game.ai.remove" message from host
+ └── GameAiConfigureHandler.cs — Handles "game.ai.configure" (difficulty, strategy)
+```
+
+**Project file** (`SOR.Ai.csproj`):
+
+```xml
+
+
+ net8.0
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+---
+
+## 2. Integration Points
+
+### 2.1 How AI Submits Game Actions
+
+The AI does **not** open a WebSocket. Instead, `AiPlayerSessionManager` — a hosted background service —
+calls game handler methods **directly** (bypassing the transport layer):
+
+```csharp
+// Conceptual: AI calling GameDrawHandler directly
+var fakeConn = new AiAuthenticatedConnection(aiAccountId, sessionId);
+var fakeMsg = new AiClientMessage("game.draw", seq: 0, payload: Array.Empty());
+await drawHandler.HandleAsync(fakeMsg, fakeConn, ct);
+```
+
+`AiAuthenticatedConnection` implements `IAuthenticatedConnection` with the AI's virtual account ID.
+`AiClientMessage` implements `IClientMessage` with the given message type and payload.
+
+This means **the AI goes through the full handler pipeline** — transaction locking, state persistence,
+push to human players — with no special-casing anywhere in the existing code.
+
+### 2.2 Receiving State Updates
+
+Rather than subscribing to Redis push channels, `AiPlayerSessionManager` reacts to its own action
+completing. After the human player's turn ends (`game.end_turn` message is processed and the game's
+`ActivePlayerAccountId` flips to an AI account), the `GameEndTurnHandler` raises an internal
+`AiTurnStartedEvent` via NATS or an in-process `IEventBus`. `AiPlayerSessionManager` subscribes and
+schedules the AI's turn.
+
+```
+Human: game.end_turn
+ → GameEndTurnHandler runs, advances turn to AI seat
+ → Publishes AiTurnStartedEvent { SessionId, AiAccountId }
+ → AiPlayerSessionManager.OnAiTurnStarted fires
+ → Loads GameState from session
+ → AiDecisionEngine.ComputeTurn(state, difficulty, aiAccountId)
+ → Submits sequence of game actions with configurable delay
+ → Calls game.end_turn on behalf of AI
+```
+
+### 2.3 Turn Delay (Human Feel)
+
+Raw AI decisions are instant. A delay is introduced to make the AI feel natural:
+
+- **Simulated think time**: 800ms–3s before each discrete action (drawn from a configured range per difficulty)
+- **Action pacing**: individual actions (play card, move, attack) are submitted 400ms–1.2s apart
+- **These are configurable via `AiDifficultyProfile`** (see §6)
+
+---
+
+## 3. AI Account Model
+
+Each AI "player" is backed by a real `Account` row in the database. A seed migration creates a set of
+canonical AI accounts that are reused across games.
+
+### 3.1 AI Account DB Record
+
+| Field | Value |
+|---|---|
+| `Id` | deterministic GUID per difficulty tier (e.g. `ai-novice-001`) |
+| `Username` | "Novice AI", "Challenger AI", "Grandmaster AI", etc. |
+| `IsAi` | `true` (new boolean column on Account entity) |
+| `AiDifficulty` | 1–10 |
+| `AiStrategy` | "Aggressive", "Control", "Balanced", "Ramp" |
+| `AvatarUrl` | art asset per strategy archetype |
+
+`IsAi = true` accounts:
+- Cannot be ranked-matched against (MatchmakerService excludes them)
+- Are not shown in leaderboards
+- Have their own pre-built decks (see §8)
+- Have ELO tracked separately in `AiEloRecord` table (used for tuning, not displayed)
+
+### 3.2 Pre-Built AI Accounts
+
+A seed creates accounts for every combination of `(difficulty 1–10) × (strategy archetype)`:
+
+```
+ai-novice-aggressive Difficulty 1, Aggressive
+ai-novice-control Difficulty 1, Control
+ai-easy-balanced Difficulty 2, Balanced
+...
+ai-grandmaster-control Difficulty 10, Control
+```
+
+When a host adds an AI to a lobby, the client specifies `{ difficulty, strategy }`. The server
+looks up the matching pre-seeded account and inserts it into the `CustomLobby.AdditionalPlayersJson`
+(or `GuestAccountId` for the second seat in a 1v1).
+
+---
+
+## 4. Game Flow
+
+### 4.1 Host Adds AI to a Custom Lobby
+
+```
+Host (client)
+ → sends: game.ai.add { lobbyId, difficulty: 3, strategy: "Balanced" }
+
+GameAddAiHandler
+ → Validates: only host can add AI
+ → Validates: lobby must be Open or not Full
+ → AiSlotAssigner.Assign(lobbyId, difficulty, strategy)
+ → Looks up matching AI account (e.g. ai-easy-balanced)
+ → Inserts AI account into AdditionalPlayersJson or GuestAccountId
+ → AI seat is marked IsAiControlled = true in lobby data
+ → Pushes CustomLobbyUpdatedPush to all lobby members
+ → AI seat appears in lobby as a named player with AI badge
+```
+
+Multiple AIs are supported by calling `game.ai.add` repeatedly (up to `MaxPlayers - 1`).
+
+### 4.2 Lobby Ready → Game Start
+
+When the host marks ready and the game starts (existing `GameLobbyReadyHandler`):
+
+1. `GameSession` is created with AI accounts in their seats (no change to existing code).
+2. `AiPlayerSessionManager.OnGameSessionCreated` is called.
+3. Manager creates an `AiPlayerSession` for each AI seat in that session.
+4. AI seats automatically send `game.ready` after a short delay so the game can begin even if AI is the only non-human.
+
+### 4.3 AI Turn Execution
+
+```
+AiPlayerSession.ExecuteTurnAsync(state, difficulty, strategy, ct):
+
+ 1. AiTurnContext ctx = BuildContext(state, aiAccountId)
+ 2. AiAction[] actions = decisionEngine.ComputeTurn(ctx)
+ // actions is an ordered list of: draw, play_card, move, attack, end_turn, etc.
+ 3. For each action in actions:
+ a. await Task.Delay(ThinkTime(difficulty)) // simulated delay
+ b. Serialize action to IClientMessage payload
+ c. Call appropriate handler directly
+ d. If handler returns error (e.g. game state changed mid-turn), re-evaluate
+ 4. Finally: call GameEndTurnHandler
+```
+
+### 4.4 AI in Multi-Player / FFA
+
+Each AI account is managed as a separate `AiPlayerSession`. Sessions are independent.
+When it is AI-seat-3's turn, only AI-seat-3's session fires. Team play AIs do not coordinate
+(in Phase 1); coordinated team AI is a future enhancement.
+
+---
+
+## 5. Decision Engine Architecture
+
+### 5.1 Interface
+
+```csharp
+public interface IAiDecisionEngine
+{
+ ///
+ /// Compute the full sequence of actions the AI will take this turn.
+ /// Returns actions in submission order; the caller is responsible for delays and submission.
+ ///
+ IReadOnlyList ComputeTurn(AiTurnContext ctx);
+}
+
+public abstract record AiAction;
+public record AiDrawAction : AiAction;
+public record AiPlayCardAction(string CardInstanceId, Coord TargetTile,
+ IReadOnlyList CardTargets) : AiAction;
+public record AiMoveAction(string UnitInstanceId, Coord TargetPosition) : AiAction;
+public record AiAttackAction(string AttackerInstanceId, string TargetInstanceId) : AiAction;
+public record AiActivateAbilityAction(string SourceId, int AbilityIndex,
+ IReadOnlyList Targets) : AiAction;
+public record AiSacrificeAction(string UnitInstanceId) : AiAction;
+public record AiAscendAction(string IncomingArchSpiritInstanceId) : AiAction;
+public record AiEndTurnAction : AiAction;
+```
+
+### 5.2 HeuristicDecisionEngine (Difficulty 1–5)
+
+Pure rule-based. Fast (< 50ms per turn). No lookahead.
+
+**Turn planning algorithm:**
+
+```
+1. Draw Phase
+ → Always draw (nothing to decide)
+
+2. Main Phase — Iterative Greedy Loop:
+ a. Score current board state (ScoringFunctions.Evaluate)
+ b. Generate all candidate actions (ActionCandidateGenerator.All)
+ c. Score each candidate: simulate action → score new state
+ d. Pick highest-scoring candidate above threshold
+ e. Repeat until no candidate improves score OR SP/ST exhausted
+ f. Apply DifficultyFilter: randomly skip/replace N% of optimal moves
+
+3. End Turn
+```
+
+**Board Evaluation (ScoringFunctions.Evaluate):**
+
+```
+Score = Σ weights × features
+
+Material:
+ + (unit Damage × 2 + unit MaxHealth) per own unit on field
+ - (unit Damage × 2 + unit MaxHealth) per opponent unit on field
+ + ArchSpirit HP ratio × 500
+
+Affinity Control:
+ + tiles of own ArchSpirit affinity within channeling range × 3
+
+Threat:
+ - units that can reach own ArchSpirit next turn × 30
+
+Resource Efficiency:
+ + (SP remaining / SpCap) × -10 // penalize hoarding too much SP
+ + SacrificeTokens × 5
+
+Positional:
+ + units adjacent to opponent ArchSpirit × 15
+ + units in center board zone × 2
+```
+
+Weights are stored in `AiDifficultyProfile` and tuned per difficulty tier (see §6).
+
+**ActionCandidateGenerator.All(ctx) → List:**
+
+```
+Channeling candidates:
+ foreach card in hand where player.CurrentSp >= card.SpCost:
+ foreach tile where ChannelingRange.Contains(tile) && affinity matches:
+ yield PlayCardAction(card, tile)
+
+Movement candidates:
+ foreach unit on field where unit.CanMove && unit.CurrentMp > 0:
+ foreach reachable tile (pathfinding):
+ yield MoveAction(unit, tile)
+
+Attack candidates:
+ foreach unit on field where unit.CanAttack:
+ foreach enemy in attack range:
+ yield AttackAction(unit, enemy)
+
+Ability candidates:
+ foreach unit on field where unit.CanUseAbility:
+ foreach ability where conditions met:
+ foreach valid target combination:
+ yield ActivateAbilityAction(unit, abilityIdx, targets)
+
+Sacrifice candidates:
+ foreach unit on field where unit can be sacrificed:
+ yield SacrificeAction(unit)
+
+Ascend candidates:
+ if player has next-tier ArchSpirit in hand && can ascend:
+ yield AscendAction(archSpirit)
+```
+
+### 5.3 MonteCarloEngine (Difficulty 6–8)
+
+Uses **Monte Carlo Tree Search (MCTS)** with random playouts. Can look N turns ahead.
+
+```
+Root = current GameState for this AI
+Iterations = f(difficulty, remainingBudgetMs)
+
+repeat Iterations:
+ 1. Selection: traverse tree using UCB1 formula
+ UCB1 = (wins/visits) + C × sqrt(ln(parent.visits) / node.visits)
+ 2. Expansion: if node not fully expanded, add one new child (one candidate action)
+ 3. Simulation: random playout from child state until game over or N turns deep
+ (uses RandomDecisionEngine for all players including opponents)
+ 4. Backpropagation: update win/loss counts up the tree
+
+Best action = child of root with highest visit count (most-explored = most-trusted)
+```
+
+**Time budgets per difficulty:**
+- Difficulty 6: 500ms think budget, 3-turn depth
+- Difficulty 7: 1.5s think budget, 5-turn depth
+- Difficulty 8: 4s think budget, 7-turn depth
+
+For multi-action turns (play card + move + attack), MCTS treats the full sequence as a plan and
+builds the tree over **turn sequences** (not individual actions). This is done by treating
+"all actions until end_turn" as one composite node.
+
+### 5.4 NeuralDecisionEngine (Difficulty 9–10, Phase 3)
+
+Wraps a trained neural network model. Architecture TBD (likely a feedforward net or lightweight
+transformer on flattened board + hand state). The model predicts:
+
+- **Policy head**: probability distribution over candidate actions
+- **Value head**: estimated win probability from current state
+
+The engine selects the highest-policy action that doesn't reduce value below a threshold.
+
+Model inference is performed via **ONNX Runtime** (`Microsoft.ML.OnnxRuntime`), allowing models
+trained in Python (PyTorch / TensorFlow) to run in-process in the .NET server.
+
+---
+
+## 6. Difficulty System
+
+### 6.1 Difficulty Tiers
+
+| Tier | Name | Engine | Mistake Rate | Think Budget |
+|---|---|---|---|---|
+| 1 | Novice | Random | 100% random | none |
+| 2 | Apprentice | Heuristic | 60% mistakes | 50ms |
+| 3 | Journeyman | Heuristic | 40% mistakes | 50ms |
+| 4 | Adept | Heuristic | 25% mistakes | 50ms |
+| 5 | Expert | Heuristic | 10% mistakes | 50ms |
+| 6 | Master | MCTS | 5% mistakes | 500ms |
+| 7 | Grandmaster | MCTS | 2% mistakes | 1.5s |
+| 8 | Champion | MCTS | 0% | 4s |
+| 9 | Legend | Neural | 0% | 200ms inference |
+| 10 | Mythic | Neural | 0%, beam search | 500ms inference |
+
+### 6.2 AiDifficultyProfile
+
+```csharp
+public record AiDifficultyProfile
+{
+ public int Difficulty { get; init; } // 1–10
+ public string DisplayName { get; init; }
+ public string EngineType { get; init; } // "Random" | "Heuristic" | "MCTS" | "Neural"
+
+ // Mistake injection
+ public float MistakeRate { get; init; } // 0.0–1.0: probability of replacing optimal with random action
+ public float SuboptimalRate { get; init; } // 0.0–1.0: probability of picking 2nd-best instead of best
+
+ // MCTS params (if applicable)
+ public int MctsTimeBudgetMs { get; init; }
+ public int MctsMaxDepth { get; init; }
+
+ // Simulated delays (humanization)
+ public int MinThinkTimeMs { get; init; } // before first action each turn
+ public int MaxThinkTimeMs { get; init; }
+ public int MinActionDelayMs { get; init; } // between subsequent actions
+ public int MaxActionDelayMs { get; init; }
+
+ // Scoring weight overrides (heuristic engine)
+ public float MaterialWeight { get; init; }
+ public float AffinityControlWeight { get; init; }
+ public float ThreatWeight { get; init; }
+ public float PositionalWeight { get; init; }
+ public float ResourceWeight { get; init; }
+}
+```
+
+Profiles are defined as a static table in `AiDifficultyProfiles.cs` (in-code constants, not DB-stored),
+making them easy to tune without migrations.
+
+### 6.3 Strategy Archetypes
+
+Strategy affects **which actions the AI prioritizes**, not how good it is:
+
+| Strategy | Description | Playstyle |
+|---|---|---|
+| `Aggressive` | Rush opponent ArchSpirit; maximize attack pressure | Front-row units, direct damage |
+| `Control` | Protect own ArchSpirit; build affinity control | Back-row units, Terramorpha spam |
+| `Balanced` | Mix of attack and defense | General-purpose |
+| `Ramp` | Maximize SP/ST accumulation for high-cost plays | Sacrifice-heavy, late-game cards |
+| `Swarm` | Channel many low-cost Spirits; overwhelm by count | Cheap spirits, wide field |
+
+Strategy is encoded as **scoring function weight adjustments** layered on top of the difficulty
+profile. An `Aggressive` AI at difficulty 5 and a `Control` AI at difficulty 5 make equally
+"good" moves — but in different directions.
+
+```csharp
+// Example: Aggressive adjusts weights
+profile = profile with {
+ MaterialWeight = profile.MaterialWeight * 1.3f,
+ ThreatWeight = profile.ThreatWeight * 0.5f, // less concerned about own ArchSpirit
+};
+```
+
+---
+
+## 7. Training & Improvement Strategy
+
+### 7.1 Training Data Sources
+
+Training data is generated from three sources, in order of quality:
+
+**Source 1: Human Game Replays**
+- All completed `GameSession` rows have a full `ActionLog` (sequence of actions + states)
+- `GameReplayExporter` converts each log to a sequence of `(state, action, outcome)` triples
+- Outcome = did this player win? (1 = win, 0 = loss)
+- Only high-quality games are used: both players above rank 1200, game went > 10 turns
+
+**Source 2: AI Self-Play**
+- `SelfPlayOrchestrator` runs `AiVsAiGameSession` batches (no network, no DB needed — pure `GameEngine` calls)
+- MCTS AI (difficulty 7+) plays against itself 10,000+ games per training run
+- Self-play generates diverse board states including rare positions humans rarely reach
+- Runs as a background job, controlled by admin API: `POST /admin/ai/self-play/start { numGames, difficulty }`
+
+**Source 3: Bootstrapped Heuristic Rollouts**
+- For cold-start (before any data exists), heuristic AI at difficulty 5 generates initial training set
+- Lower quality but quick to generate; replaced by better sources over time
+
+### 7.2 Feature Extraction
+
+`FeatureExtractor.Extract(GameState state, string aiAccountId) → float[]`
+
+The feature vector is a fixed-size array encoding the full game state:
+
+```
+Board Features (9×9 grid):
+ [0..80] Tile affinity type (one-hot per tile, 6 values each → 486 floats)
+ [486..566] Tile occupant: own/enemy/empty (3 values per tile → 81×3 = 243)
+ [729..809] Occupant unit type index (normalized)
+ [810..890] Occupant HP ratio
+ [891..971] Occupant Damage (normalized)
+
+Own Player State:
+ [972] CurrentSp / SpCap
+ [973] CurrentSt / 10
+ [974] Hand size / HandSizeCap
+ [975] Deck size / MaxDeckSize
+ [976] Own ArchSpirit HP ratio
+ [977] Own ArchSpirit tier / 3
+ [978] Field unit count / 10
+ [979] TurnNumber / 30
+
+Opponent State (same fields, offset by constant):
+ [980..987] (same structure)
+
+Global:
+ [988] ActivePlayerIsAi (1.0 if AI is active player, 0.0 otherwise)
+ [989] GameMode FFA=0, Teams=0.5, MultiTeam=1.0
+
+Total: ~990 floats
+```
+
+### 7.3 Model Architecture (Phase 3)
+
+A lightweight **feedforward neural network**:
+
+```
+Input layer: 990 units
+Dense layer: 512 units, ReLU
+Dense layer: 256 units, ReLU
+Dense layer: 128 units, ReLU
+
+Split into two heads:
+ Policy head: 128 → num_actions (softmax over candidate action types)
+ Value head: 128 → 1 (sigmoid, win probability)
+```
+
+Training objective:
+- **Policy loss**: cross-entropy between predicted policy and action chosen in replay
+- **Value loss**: MSE between predicted win probability and actual game outcome
+
+Trained in Python using PyTorch, exported to ONNX, deployed to `/Server/models/sor-ai-v{N}.onnx`.
+`NeuralDecisionEngine` loads the ONNX model via `Microsoft.ML.OnnxRuntime` at service startup.
+
+### 7.4 Training Pipeline
+
+```
+1. Data Collection (continuous)
+ GameReplayExporter runs as background job nightly:
+ SELECT * FROM game_action_logs
+ JOIN game_sessions ON ...
+ WHERE sessions.status = 'Completed'
+ AND sessions.ended_at > last_export_timestamp
+ → Write JSONL to /data/training/raw/{date}.jsonl
+
+2. Feature Extraction (offline, Python)
+ python scripts/extract_features.py --input raw/ --output features/
+ Reads JSONL, calls FeatureExtractor equivalent in Python, writes Parquet
+
+3. Model Training (offline, Python)
+ python scripts/train.py --data features/ --epochs 50 --output models/
+ Trains PyTorch model, validates on held-out set
+
+4. Export & Validate
+ python scripts/export_onnx.py --model models/best.pt --output sor-ai-v{N}.onnx
+ Run benchmark: AiVsAiBenchmark plays 1000 games new vs old model; new must win > 55%
+
+5. Deploy
+ Copy sor-ai-v{N}.onnx to server/models/
+ Admin calls: POST /admin/ai/reload-model { version: N }
+ NeuralDecisionEngine.ReloadModel() hot-swaps without restart
+```
+
+### 7.5 Difficulty Calibration
+
+After each self-play / training cycle, run **calibration games** against human players:
+
+- Pull a random sample of 100 recent ranked games (human ELO distribution)
+- Run AI at each difficulty tier against a simulated human from a comparable rank
+- Measure AI win rate: target ~40–60% win rate for each difficulty tier against the matching rank band
+
+Calibration thresholds (target AI win rate vs human ELO band):
+
+| Difficulty | Target ELO range | Target AI win% |
+|---|---|---|
+| 1 | Unranked (any) | 10–25% |
+| 2 | 800–1000 | 30–45% |
+| 3 | 1000–1100 | 35–50% |
+| 4 | 1100–1200 | 40–55% |
+| 5 | 1200–1350 | 45–55% |
+| 6 | 1350–1500 | 45–55% |
+| 7 | 1500–1700 | 45–55% |
+| 8 | 1700–1900 | 45–55% |
+| 9 | 1900–2100 | 45–55% |
+| 10 | 2100+ | 45–55% |
+
+If win rate drifts outside target, adjust `MistakeRate` / MCTS budget / scoring weights accordingly.
+Calibration runs are automated via `AiCalibrationJob` (admin-triggered).
+
+---
+
+## 8. Deck Composition for AI
+
+### 8.1 AI Deck Creation
+
+AI players need pre-built decks. These are not in the player collection system; they are seeded
+directly in the `Deck` table with `AccountId` = the AI's virtual account.
+
+Each AI account gets **one deck per viable ArchSpirit + affinity combination**, covering major
+strategic archetypes:
+
+```
+ai-novice-balanced:
+ ArchSpirit: "Ignis Pup" (Fire, Tier 1)
+ Deck: 30-card fire-affinity mix of Spirits and Repentance cards
+ (Simple, no complex ability chains)
+
+ai-master-control:
+ ArchSpirit: "Hydra Sentinel" (Water, Tier 1)
+ Deck: 30-card water-control deck with Terramorpha + defensive Spirits
+ (Uses advanced affinity tile locking)
+
+ai-grandmaster-aggressive:
+ ArchSpirit: "Blazing Warchief" (Fire, Tier 1)
+ Deck: 30-card aggro deck, cheap Spirits, rush down opponent
+```
+
+Deck seeds are defined as code constants in `AiDeckDefinitions.cs` and applied via a DB seed
+migration. AI decks bypass normal deck validation requirements (IsValid flag forced true).
+
+### 8.2 Deck Matching to Strategy
+
+`AiSlotAssigner` picks the AI account whose strategy matches the host's request. For the first
+implementation, one deck per strategy tier is sufficient. Future iterations may allow AI to
+choose a deck based on opponent's ArchSpirit (counter-deck logic).
+
+---
+
+## 9. Multi-Player & Team AI
+
+### 9.1 FFA (Free-For-All)
+
+Each AI seat is independently managed by a separate `AiPlayerSession`. The AI evaluates all
+opponents as threats; scoring functions weight all enemy ArchSpirits equally (no preferred target
+in base version; future: target weakest).
+
+### 9.2 Team Mode
+
+In team games, AI evaluates friendly units as **protected** (does not attack them) and enemy
+units as **threats**. The AI is not aware of teammate's planned actions — it plays optimistically.
+
+Future Phase 2: implement `TeamAiCoordinator` that shares intention signals between team-AI
+sessions (e.g. "I will attack this unit, don't duplicate effort").
+
+---
+
+## 10. New Message Types
+
+Add to `GameMessages.cs`:
+
+```csharp
+// Host → Server: add an AI player to a custom lobby
+public record GameAddAiRequest(string LobbyId, int Difficulty, string Strategy);
+public record GameAddAiResponse(string AiAccountId, string AiDisplayName, int SeatIndex);
+
+// Host → Server: remove an AI player from a custom lobby
+public record GameRemoveAiRequest(string LobbyId, string AiAccountId);
+public record GameRemoveAiResponse(bool Success);
+
+// Host → Server: change AI difficulty or strategy before game starts
+public record GameConfigureAiRequest(string LobbyId, string AiAccountId,
+ int? Difficulty, string? Strategy);
+public record GameConfigureAiResponse(bool Success);
+
+// Push → all lobby members: lobby AI slots changed
+public record CustomLobbyAiSlotsChangedPush(string LobbyId,
+ IReadOnlyList CurrentAiSlots);
+
+public record AiSlotInfo(string AccountId, string DisplayName,
+ int Difficulty, string Strategy, int SeatIndex);
+```
+
+Message type strings:
+- `"game.ai.add"` → `GameAddAiHandler`
+- `"game.ai.remove"` → `GameRemoveAiHandler`
+- `"game.ai.configure"` → `GameAiConfigureHandler`
+
+---
+
+## 11. Database Schema Additions
+
+### 11.1 Account.IsAi Column
+
+```sql
+ALTER TABLE accounts ADD COLUMN is_ai BOOLEAN NOT NULL DEFAULT FALSE;
+ALTER TABLE accounts ADD COLUMN ai_difficulty INT NULL;
+ALTER TABLE accounts ADD COLUMN ai_strategy TEXT NULL;
+```
+
+`Account` entity:
+```csharp
+public bool IsAi { get; set; }
+public int? AiDifficulty { get; set; }
+public string? AiStrategy { get; set; }
+```
+
+### 11.2 AiEloRecord Table
+
+Tracks AI performance separately from ranked ELO (not shown to players):
+
+```sql
+CREATE TABLE ai_elo_records (
+ id UUID PRIMARY KEY,
+ ai_account_id UUID NOT NULL REFERENCES accounts(id),
+ elo_score INT NOT NULL DEFAULT 1200,
+ wins INT NOT NULL DEFAULT 0,
+ losses INT NOT NULL DEFAULT 0,
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+```
+
+### 11.3 CustomLobby AI Slot Tracking
+
+Add to `CustomLobby`:
+
+```sql
+ALTER TABLE custom_lobbies ADD COLUMN ai_slots_json JSONB NULL;
+```
+
+`AiSlotsJson` is an array of:
+```json
+[
+ { "accountId": "ai-easy-balanced", "seatIndex": 2, "difficulty": 3, "strategy": "Balanced" }
+]
+```
+
+---
+
+## 12. Implementation Phases
+
+Phases are deliberately narrow so each can be handed off as a single focused coding session.
+Each phase lists **exact files to create or modify**, the **DI wiring required**, and a
+**"done" definition** — a concrete test you can run to confirm the phase is complete before
+moving on.
+
+Phases are grouped into tracks:
+- **Track A (1.x)** — Project scaffold, database, and lobby plumbing. No AI logic yet.
+- **Track B (2.x)** — Turn execution pipeline. Random AI first, then heuristic.
+- **Track C (3.x)** — Competitive MCTS AI + training data collection.
+- **Track D (4.x)** — Neural AI + offline training pipeline.
+- **Track E (5.x)** — Polish, adaptive difficulty, ecosystem features.
+
+---
+
+### Phase 1.1 — Project Scaffold
+
+**Goal**: `SOR.Ai` compiles, is wired into `SOR.Host`, and registers its own empty
+`ServiceRegistration`. Nothing runs yet — this is pure plumbing.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+├── SOR.Ai.csproj
+└── ServiceRegistration.cs
+```
+
+**`SOR.Ai.csproj`** — follow the same pattern as all other class libraries:
+- `Sdk="Microsoft.NET.Sdk"`, `net8.0`
+- ``
+- Project references: `SOR.Database`, `SOR.Game`, `SOR.Networking.Abstractions`, `SOR.Shared`
+
+**`ServiceRegistration.cs`:**
+```csharp
+namespace SOR.Ai;
+
+public static class ServiceRegistration
+{
+ public static IServiceCollection AddAiService(
+ this IServiceCollection services,
+ IConfiguration configuration)
+ {
+ // phases will add registrations here
+ return services;
+ }
+}
+```
+
+**Files to modify:**
+
+- `Server/SOR.slnx` — add `SOR.Ai` project entry
+- `Server/src/SOR.Host/SOR.Host.csproj` — add `` to `SOR.Ai`
+- `Server/src/SOR.Host/Program.cs` — call `builder.Services.AddAiService(builder.Configuration)`
+ immediately after `AddGameService`, guarded by the same `ENABLED_SERVICES` check pattern
+
+**Done when**: `dotnet build Server/SOR.slnx` produces zero errors and zero warnings.
+
+---
+
+### Phase 1.2 — AI Transport Abstractions
+
+**Goal**: Define `AiAuthenticatedConnection` and `AiClientMessage` — the two types that let AI
+code call game handlers directly without a WebSocket. These are the foundation everything else
+builds on.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Transport/
+ ├── AiAuthenticatedConnection.cs
+ └── AiClientMessage.cs
+```
+
+**`AiAuthenticatedConnection`** implements `IAuthenticatedConnection` (from
+`SOR.Networking.Abstractions`). It holds:
+- `string UserId` — the AI's virtual account ID (passed in constructor)
+- `Guid SessionId` — the game session it belongs to
+- All other members of the interface no-op or throw `NotSupportedException`
+
+**`AiClientMessage`** implements `IClientMessage`. It holds:
+- `string Type` — the message type string (e.g. `"game.draw"`)
+- `int Seq` — always 0 (no reply routing needed for AI)
+- `ReadOnlyMemory Payload` — pre-serialized JSON payload bytes
+
+The payload is serialized by the caller using `JsonSerializer.SerializeToUtf8Bytes(request)`,
+matching exactly how `SOR.Gateway` deserializes incoming WebSocket frames.
+
+**No DI registration needed** — these are `new`-able value types, instantiated per action.
+
+**Done when**: Both types compile and the `IAuthenticatedConnection` / `IClientMessage` contracts
+are fully satisfied (no NotImplementedExceptions that handlers would hit during normal turn flow).
+
+---
+
+### Phase 1.3 — Database: AI Account Schema
+
+**Goal**: Add the `IsAi`, `AiDifficulty`, and `AiStrategy` columns to the `Account` entity and
+produce a migration. No seed data yet — that comes in 1.4.
+
+**Files to modify:**
+
+- `Server/src/SOR.Database/Entities/Identity/Account.cs`
+ — add three properties:
+ ```csharp
+ public bool IsAi { get; set; }
+ public int? AiDifficulty { get; set; }
+ public string? AiStrategy { get; set; }
+ ```
+
+- `Server/src/SOR.Database/Contexts/SorIdentityDbContext.cs`
+ — add `.HasDefaultValue(false)` config for `IsAi` in `OnModelCreating`
+
+- `Server/src/SOR.Database/Entities/Game/CustomLobby.cs`
+ — add `public string? AiSlotsJson { get; set; }` (JSONB column, nullable)
+
+- `Server/src/SOR.Matchmaking/MatchmakerService.cs`
+ — add `.Where(e => !e.Account.IsAi)` (or equivalent join filter) so AI accounts
+ are never entered into the ranked queue
+
+**Migration**: run `dotnet ef migrations add AddAiAccountFields` targeting
+`SorIdentityDbContext` and a separate migration targeting `GameDbContext` for
+`CustomLobby.AiSlotsJson`. Follow the existing migration project structure.
+
+**Done when**: migrations apply cleanly against a local dev DB and the Matchmaking
+service query is confirmed to exclude `IsAi = true` accounts via a unit or integration test.
+
+---
+
+### Phase 1.4 — AI Account Seeds
+
+**Goal**: Seed one AI `Account` row per `(difficulty, strategy)` combination into the DB.
+These accounts are the "virtual players" that will join lobbies. Decks come in Phase 1.5.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Seeding/
+ └── AiAccountSeeder.cs
+```
+
+**`AiAccountSeeder`** is a static helper called from `ServiceRegistration.AddAiService`:
+```csharp
+// Called at startup: ensures AI accounts exist, idempotent (upsert by deterministic ID)
+internal static async Task SeedAsync(SorIdentityDbContext identityDb, CancellationToken ct)
+```
+
+It uses a deterministic GUID-from-name strategy for each account ID so re-running is safe.
+For each combination of difficulties 1–10 and strategies `["Aggressive", "Control",
+"Balanced", "Ramp", "Swarm"]`, it upserts an Account row with:
+- `IsAi = true`
+- `AiDifficulty` / `AiStrategy` set
+- `Username` = e.g. `"Balanced AI (Adept)"` (human-readable display name)
+- `RankScore = 0`, `OriginPoints = 0` (AI accounts don't earn currency)
+- `IsEmailVerified = true`, `PasswordHash = ""` (never logs in)
+
+**DI wiring** (in `ServiceRegistration.cs`):
+```csharp
+// Register as IHostedService so it runs once at startup before traffic is accepted
+services.AddHostedService();
+```
+
+`AiSeedStartupService` is a one-shot `IHostedService` that calls `AiAccountSeeder.SeedAsync`
+then exits — same pattern as the existing `GameStartupCleanupService`.
+
+**Done when**: after server start, a DB query for `WHERE is_ai = true` returns exactly
+`10 difficulties × 5 strategies = 50` rows.
+
+---
+
+### Phase 1.5 — AI Deck Seeds
+
+**Goal**: Create one pre-built `Deck` (with `DeckCard` rows) for each AI account. Decks are
+seeded from code-defined constants; they do not go through normal collection ownership.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Seeding/
+ ├── AiDeckDefinitions.cs — static list of deck blueprints (by strategy archetype)
+ └── AiDeckSeeder.cs — upserts Deck + DeckCard rows for each AI account
+```
+
+**`AiDeckDefinitions.cs`** defines a `record AiDeckBlueprint(string Strategy, string ArchSpiritName, string[] CardNames)`.
+One blueprint per strategy archetype:
+- `Balanced` — one ArchSpirit, mixed Spirit/Repentance cards
+- `Aggressive` — cheap Spirits, attack-range units, Repentance damage spells
+- `Control` — Terramorpha + high-defense Spirits, few attacks
+- `Ramp` — Sacrifice-heavy Spirits, high-cost powerful late-game cards
+- `Swarm` — max-count low-SP Spirits, wide board presence
+
+Blueprints reference cards by name. `AiDeckSeeder` resolves names to `CardDefinitionId` at
+seed time (query `CardDefinitions WHERE Name = ?`). If a card doesn't exist in the catalog
+(environment without full card data), the seeder logs a warning and skips, allowing partial
+decks to still work.
+
+**`AiDeckSeeder`** upserts one `Deck` row per AI account with:
+- `AccountId` = AI account ID
+- `IsValid = true` (forced — bypasses deck-construction validation)
+- Cards from matching blueprint
+
+**DI wiring**: called inside `AiSeedStartupService` after `AiAccountSeeder.SeedAsync` completes,
+so both run atomically at startup.
+
+**Done when**: after server start, each AI account has at least one `Deck` row with at least
+one `DeckCard` child row; querying `decks WHERE account_id IN (ai account IDs)` returns 50 rows.
+
+---
+
+### Phase 1.6 — Lobby Handlers: Add / Remove / Configure AI
+
+**Goal**: Expose the three message handlers that let a host manage AI seats in a custom lobby.
+After this phase, a host can add/remove AI players from a lobby via the client — though the AI
+won't actually play yet (turn execution comes later).
+
+**New message types** — add to `SOR.Game/GameMessages.cs`:
+```csharp
+public record GameAddAiRequest(Guid LobbyId, int Difficulty, string Strategy);
+public record GameAddAiResponse(Guid AiAccountId, string AiDisplayName, int SeatIndex);
+
+public record GameRemoveAiRequest(Guid LobbyId, Guid AiAccountId);
+public record GameRemoveAiResponse(bool Success);
+
+public record GameConfigureAiRequest(Guid LobbyId, Guid AiAccountId,
+ int? Difficulty, string? Strategy);
+public record GameConfigureAiResponse(bool Success);
+
+public record CustomLobbyAiSlotsChangedPush(Guid LobbyId,
+ IReadOnlyList CurrentAiSlots);
+
+public record AiSlotInfo(Guid AccountId, string DisplayName,
+ int Difficulty, string Strategy, int SeatIndex);
+```
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+├── Lobby/
+│ ├── AiSlotAssigner.cs — resolves (difficulty, strategy) → AI Account + seat index
+│ └── AiLobbyService.cs — shared read/write helpers for CustomLobby.AiSlotsJson
+└── Handlers/
+ ├── GameAddAiHandler.cs
+ ├── GameRemoveAiHandler.cs
+ └── GameConfigureAiHandler.cs
+```
+
+**Handler pattern**: each handler extends `GameHandlerBase` (from `SOR.Game.Handlers`),
+taking a `GameDbContext` and `IClientPush` via constructor (injected as transient, same as all
+existing game handlers). Each validates:
+- `conn.UserId == lobby.HostAccountId` (only host can manage AI slots)
+- Lobby status is `Open` or `Full` (not `Started` or `Completed`)
+- For Add: seat count after add does not exceed `lobby.MaxPlayers`
+- For Remove: the given AI account is actually in `AiSlotsJson`
+
+`AiSlotAssigner.Assign(difficulty, strategy)` queries `identityDb.Users WHERE IsAi = true
+AND AiDifficulty = difficulty AND AiStrategy = strategy LIMIT 1` and returns the account.
+
+After any mutation, all handlers push `CustomLobbyAiSlotsChangedPush` to all lobby members
+(using the same `clientPush.PushAsync` pattern as existing lobby handlers).
+
+**DI wiring** in `SOR.Ai/ServiceRegistration.cs`:
+```csharp
+services.AddTransient();
+services.AddTransient();
+services.AddTransient();
+services.AddScoped();
+services.AddScoped();
+```
+
+**Done when**: a client can call `game.ai.add` on an open lobby and receive a valid
+`GameAddAiResponse`; calling `game.ai.remove` removes it; both changes are persisted to
+`CustomLobby.AiSlotsJson` and pushed to all lobby members.
+
+---
+
+### Phase 1.7 — AI Session Manager (Hosted Service Skeleton)
+
+**Goal**: Create `AiPlayerSessionManager` — the singleton hosted service that will orchestrate
+AI turns. In this phase it only handles the game-start event and registers active AI sessions.
+Turn execution is wired in Phase 2.1.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Core/
+ ├── AiPlayerSession.cs — per-session state for one AI seat
+ ├── AiPlayerSessionManager.cs — singleton hosted service, manages all active AI sessions
+ └── AiTurnContext.cs — snapshot of GameState from one AI's perspective
+```
+
+**`AiPlayerSession`** holds:
+- `Guid SessionId`
+- `Guid AiAccountId`
+- `int Difficulty`, `string Strategy`
+- `int SeatIndex`
+- `CancellationTokenSource SessionCts` — cancelled when game ends
+
+**`AiPlayerSessionManager`** is a `BackgroundService` that:
+1. Subscribes to NATS subject `NatsSubjects.GameStarted` (the same event `SOR.Matchmaking`
+ already publishes when any game starts — including custom lobby games)
+2. On `GameStartedEvent`, loads the `GameSession` from DB and inspects `AdditionalPlayersJson`
+ plus `GuestAccountId` / `PlayerOneAccountId` to identify any seats whose account has `IsAi = true`
+3. Creates one `AiPlayerSession` per AI seat and stores it in a `ConcurrentDictionary>`
+4. Subscribes to NATS subject `NatsSubjects.GameEnded` and disposes sessions for that game
+
+At this stage, the sessions are created but no turn logic fires yet.
+
+**Auto-ready**: when the game session is first created and an AI is in a seat, the manager
+sends `game.ready` (via a direct handler call using `AiAuthenticatedConnection` + `AiClientMessage`)
+with a short random delay (200–800ms). This allows a 1-human-vs-1-AI lobby to start without
+the human waiting for a fake "opponent connect" event.
+
+**DI wiring** in `ServiceRegistration.cs`:
+```csharp
+services.AddSingleton();
+services.AddHostedService(sp => sp.GetRequiredService());
+```
+
+**Done when**: starting a custom lobby game that has one AI seat causes `AiPlayerSessionManager`
+to log "AI session registered: {sessionId} seat {seatIndex}" and the game transitions past the
+ready phase automatically (the AI submits `game.ready`).
+
+---
+
+### Phase 2.1 — Turn Event + Action Submission Pipeline
+
+**Goal**: Wire up the `AiTurnStartedEvent` from `GameEndTurnHandler` and implement the action
+submission loop in `AiPlayerSession`. After this phase, the AI will take turns — even if it
+does nothing useful on them (end turn immediately). This proves the end-to-end pipeline works.
+
+**Files to modify:**
+
+- `SOR.Shared/Nats/NatsSubjects.cs` — add `public const string AiTurnStarted = "sor.game.ai_turn_started";`
+- `SOR.Game/Handlers/GameEndTurnHandler.cs` — after advancing the turn, if the new
+ `state.ActivePlayerAccountId` is an AI account (check via `IEventBus` — publish
+ `AiTurnStartedEvent { SessionId, AiAccountId, TurnNumber }`). The check is done by looking up
+ whether `activePlayerId` appears in a locally-injected `IAiAccountRegistry` (see below).
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Core/
+ └── AiAccountRegistry.cs — singleton: set of all known AI account IDs (loaded at startup)
+```
+
+`AiAccountRegistry` is a singleton loaded by `AiSeedStartupService` after seeding — it reads
+all `IsAi = true` account IDs into a `HashSet` for O(1) lookups. Injected into
+`GameEndTurnHandler` via `IAiAccountRegistry` interface (defined in `SOR.Networking.Abstractions`
+or `SOR.Shared` to avoid a circular dependency from `SOR.Game` → `SOR.Ai`).
+
+**`AiPlayerSession.ExecuteTurnAsync`** (Phase 2.1 stub):
+```csharp
+internal async Task ExecuteTurnAsync(GameState state, CancellationToken ct)
+{
+ // Phase 2.1: immediately end turn (no decision logic yet)
+ await SubmitActionAsync("game.end_turn", new GameEndTurnRequest(SessionId), ct);
+}
+```
+
+`SubmitActionAsync` constructs `AiAuthenticatedConnection` + `AiClientMessage`, resolves the
+matching `IMessageHandler` from `IServiceProvider` (keyed by `msg.Type`), and calls
+`handler.HandleAsync`. Handler resolution follows the same `MessageDispatcher` pattern already
+used in `SOR.Gateway`.
+
+**`AiPlayerSessionManager`** subscribes to `AiTurnStartedEvent` via NATS and calls
+`session.ExecuteTurnAsync` after a configurable base delay.
+
+**Done when**: in a human-vs-AI custom game, after the human ends their turn, the AI's turn
+starts and immediately ends (AI passes). The human sees the state update and their turn resumes.
+The game can reach game-over naturally when the human attacks the AI ArchSpirit to zero health.
+
+---
+
+### Phase 2.2 — Placement Phase Handling
+
+**Goal**: Teach the AI to handle the `Placement` phase — specifically `game.place_arch_spirit`.
+Without this the AI will never leave Placement and the game cannot begin.
+
+This is a discrete phase because placement has its own logic: the AI must pick a valid starting
+coordinate in its placement zone, which is determined by `SeatIndex` and `GameRules`.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Engine/
+ └── PlacementStrategy.cs — picks a valid arch-spirit placement coordinate
+```
+
+**`PlacementStrategy.SelectCoord(AiTurnContext ctx) → Coord`**:
+- Reads `ctx.State.Board.StartingZones[aiSeatIndex]`
+- For Phase 2.2 (novice behaviour): picks a random coordinate from the starting zone
+- Later phases will have `HeuristicDecisionEngine` call this too, potentially picking
+ a coordinate that maximises affinity push toward the board center
+
+**`AiPlayerSession.ExecuteTurnAsync`** gains a phase check:
+```csharp
+if (state.Phase == GamePhase.Placement)
+{
+ var coord = PlacementStrategy.SelectCoord(ctx);
+ await SubmitActionAsync("game.place_arch_spirit", new GamePlaceArchSpiritRequest(SessionId, coord), ct);
+ return;
+}
+```
+
+**Done when**: an AI seat progresses through Placement automatically and the board reaches
+the Draw phase, at which point both human and AI have ArchSpirits on the board.
+
+---
+
+### Phase 2.3 — Random Decision Engine (Difficulty 1)
+
+**Goal**: Implement `IAiDecisionEngine`, the `AiAction` discriminated union, `AiDifficultyProfile`,
+and `RandomDecisionEngine`. After this phase Difficulty 1 AI plays a legal (but random) game.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Engine/
+ ├── IAiDecisionEngine.cs — interface + AiAction hierarchy (records)
+ ├── AiDifficultyProfile.cs — record definition
+ ├── AiDifficultyProfiles.cs — static table of all 10 profiles
+ └── RandomDecisionEngine.cs — picks random legal action each step
+```
+
+**`IAiDecisionEngine`**:
+```csharp
+public interface IAiDecisionEngine
+{
+ IReadOnlyList ComputeTurn(AiTurnContext ctx);
+}
+```
+
+`AiAction` discriminated union: `AiDrawAction`, `AiPlayCardAction`, `AiMoveAction`,
+`AiAttackAction`, `AiActivateAbilityAction`, `AiSacrificeAction`, `AiAscendAction`,
+`AiEndTurnAction`.
+
+**`RandomDecisionEngine`** loops:
+1. Generate one random legal action (from any category) — or `AiEndTurnAction` if none exist
+2. Append to plan
+3. If action was `AiEndTurnAction` or SP/MP exhausted, stop
+
+**`AiPlayerSession`** selects engine based on `AiDifficultyProfiles.Get(difficulty).EngineType`.
+For this phase only `"Random"` works; other engine types fall back to `RandomDecisionEngine`.
+
+**DI wiring**:
+```csharp
+services.AddTransient();
+```
+
+Engines are resolved by `AiPlayerSession` directly from `IServiceProvider` (keyed by engine type
+string from the profile). This avoids a factory abstraction we don't need yet.
+
+**Done when**: an AI on Difficulty 1 plays a full game from Placement to game-over (either the
+human kills the AI ArchSpirit, the AI accidentally kills the human's, or turn limit is reached).
+All actions are valid (no `GameException` thrown).
+
+---
+
+### Phase 2.4 — Action Candidate Generator
+
+**Goal**: Build `ActionCandidateGenerator` — the component that enumerates every legal move
+the AI can make from a given `GameState`. This is a pure function (no side effects, no DB),
+reused by both the heuristic and MCTS engines.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Heuristics/
+ └── ActionCandidateGenerator.cs
+```
+
+**Method signatures:**
+```csharp
+public static class ActionCandidateGenerator
+{
+ // All legal actions for the active player in the given state.
+ public static IReadOnlyList All(AiTurnContext ctx);
+
+ // Channeling candidates only (play card to tile)
+ public static IReadOnlyList Channelings(AiTurnContext ctx);
+
+ // Movement candidates for a specific unit
+ public static IReadOnlyList Movements(AiTurnContext ctx, string unitInstanceId);
+
+ // Attack candidates for a specific unit
+ public static IReadOnlyList Attacks(AiTurnContext ctx, string unitInstanceId);
+
+ // Ability candidates for a specific unit
+ public static IReadOnlyList Abilities(AiTurnContext ctx, string unitInstanceId);
+}
+```
+
+Implementation delegates range/path/affinity logic back to `SOR.Game` modules directly —
+`ChannelingRange`, `Pathfinding`, `AffinitySystem` — so no game rules are duplicated in `SOR.Ai`.
+
+**`AiTurnContext`** (from Phase 1.7) stores:
+- `GameState State`
+- `string AiAccountId`
+- `PlayerState AiPlayer` (convenience: `State.Players[AiAccountId]`)
+- `IReadOnlyList OpponentIds`
+- `GameRules Rules`
+
+**Done when**: unit tests (xUnit, same test project pattern as existing `SOR.Game.Tests`) cover:
+- Channeling with sufficient SP and matching affinity → produces candidates
+- Channeling with insufficient SP → no candidates
+- Movement with zero MP remaining → no candidates
+- Attack out of range → not in candidates
+- Ascend when next-tier ArchSpirit is in hand → ascend candidate present
+
+---
+
+### Phase 2.5 — Heuristic Scoring & Decision Engine (Difficulties 2–5)
+
+**Goal**: Implement board evaluation and the greedy heuristic engine. After this phase,
+Difficulties 2–5 play purposefully — they attack weak targets, defend the ArchSpirit, and
+spend SP on cards that improve their board position.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Heuristics/
+ ├── ScoringFunctions.cs — board evaluation: material, position, affinity, threat
+ ├── ThreatDetector.cs — which enemy units can reach own ArchSpirit next turn
+ └── HeuristicDecisionEngine.cs — greedy loop with mistake injection
+```
+
+**`ScoringFunctions.Evaluate(GameState state, string aiAccountId, AiDifficultyProfile profile) → float`**
+uses the weighted formula defined in §5.2. Weights come from `profile`, allowing different
+difficulties and strategies to push the AI toward different behaviours without changing code.
+
+**`HeuristicDecisionEngine.ComputeTurn(AiTurnContext ctx) → IReadOnlyList`**:
+```
+1. Draw (always)
+2. Greedy loop:
+ a. candidates = ActionCandidateGenerator.All(ctx)
+ b. for each candidate: score = ScoringFunctions.Evaluate(Simulate(state, candidate))
+ c. best = argmax(score)
+ d. if best.score <= current score AND no mandatory actions remain: break
+ e. apply MistakeRate: with probability MistakeRate, replace best with random candidate
+ f. append best to plan; update ctx with simulated state
+3. AiEndTurnAction
+```
+
+`Simulate(state, action)` calls `GameEngine.Draw / MoveUnit / Attack / ChannelCard` etc.
+directly (same pure static methods — no DB, no side effects) to get the post-action state for
+scoring. This is cheap: `GameEngine` is designed to be called this way.
+
+**`AiDifficultyProfiles`** now defines full profiles for 1–5:
+- Difficulty 1: `EngineType = "Random"`, `MistakeRate = 1.0`
+- Difficulty 2: `EngineType = "Heuristic"`, `MistakeRate = 0.60`
+- Difficulty 3: `EngineType = "Heuristic"`, `MistakeRate = 0.40`
+- Difficulty 4: `EngineType = "Heuristic"`, `MistakeRate = 0.25`
+- Difficulty 5: `EngineType = "Heuristic"`, `MistakeRate = 0.10`
+
+Strategy weight overlays (Aggressive, Control, etc.) are applied on top of the difficulty profile
+via `AiDifficultyProfile.WithStrategy(strategy)` — a `with`-expression that adjusts weights.
+
+**DI wiring**:
+```csharp
+services.AddTransient();
+```
+
+**Done when**: manual playtesting confirms:
+- Difficulty 2 AI makes obviously suboptimal moves ~half the time
+- Difficulty 5 AI consistently attacks low-HP units first, channels Spirits to relevant affinity
+ tiles, and does not leave its ArchSpirit adjacent to enemy attackers without blocking
+- Difficulty 5 AI wins > 60% of games against Difficulty 1 AI in a 100-game self-play run
+ (run via a temporary test harness calling `GameEngine` directly in a console test)
+
+---
+
+### Phase 3.1 — AI Internal ELO Tracking
+
+**Goal**: Record win/loss outcomes for AI accounts in a separate `AiEloRecord` table.
+This data is used for calibration in later phases and is never surfaced to players.
+
+**Migration**: create `AiEloRecord` table (see §11.2).
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Tracking/
+ └── AiEloService.cs — records outcome, updates AiEloRecord after each AI game ends
+```
+
+**`AiEloService`** is called from `AiPlayerSessionManager` when it receives `GameEndedEvent`.
+It identifies which participants were AI accounts, loads their `AiEloRecord`, applies the same
+`GameEngine.ComputeEloDelta` formula used by `FinalizeGameAsync`, and saves.
+
+Note: AI accounts also go through `FinalizeGameAsync` for their human-facing `Account.RankScore`
+(since the session uses their real account ID). The `AiEloRecord` is an **additional** private
+tracker, not a replacement. AI `RankScore` on the `Account` table should be frozen at `0`
+post-game — add a guard in `FinalizeGameAsync`: if `winner.IsAi || loser.IsAi`, skip the
+`identityDb.SaveChangesAsync` ELO adjustment (human's ELO still updates normally).
+
+**DI wiring**:
+```csharp
+services.AddScoped();
+```
+
+**Done when**: after an AI game completes, the `ai_elo_records` table has updated win/loss
+counts and an adjusted internal ELO score for the AI account.
+
+---
+
+### Phase 3.2 — Self-Play Runner
+
+**Goal**: Build an in-memory AI-vs-AI game runner for data generation and engine benchmarking.
+Runs entirely via `GameEngine` static methods — no DB writes, no network, no handlers. Pure
+computation. Used by Phase 3.3 (data export) and for validating engine improvements.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Training/
+ └── SelfPlayRunner.cs — runs one in-memory AI-vs-AI game, returns outcome
+```
+
+**`SelfPlayRunner.RunGameAsync(AiDifficultyProfile p1, AiDifficultyProfile p2, GameRules rules) → SelfPlayResult`**:
+1. Build two `AiTurnContext` instances with a shared `GameState` (initialized via `GameEngine.Initialize`)
+2. Alternate turns: `decisionEngine.ComputeTurn(ctx)` → apply each action via `GameEngine.*`
+3. After `GameEngine.EndTurn` returns `(state, gameOver: true)`, return `SelfPlayResult { WinnerSeat, TurnCount, FinalState }`
+4. No delays, no DB, no NATS — pure CPU
+
+**`SelfPlayOrchestrator`** wraps this in a batch loop:
+```csharp
+public async Task RunBatchAsync(int numGames, int difficulty, CancellationToken ct)
+```
+Runs games in parallel via `Task.WhenAll` (configurable concurrency limit). Reports
+win counts, average turn counts, and game records for export.
+
+**Admin API** in `SOR.Admin`:
+- `POST /admin/ai/self-play/start { numGames, difficulty }` — kicks off a background batch
+- `GET /admin/ai/self-play/status` — returns progress (games completed / total, win rates)
+
+**Done when**: a 100-game self-play batch completes between two Difficulty 5 heuristic AIs
+in under 30 seconds, with a win rate between 45–55% (roughly equal opponents), confirming
+the runner produces valid complete games.
+
+---
+
+### Phase 3.3 — Training Data Export
+
+**Goal**: Export human game replays and self-play results as structured JSONL, ready for
+offline feature extraction and model training.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Training/
+ ├── GameReplayExporter.cs — reads GameActionLog rows, emits training samples
+ ├── FeatureExtractor.cs — GameState → float[] feature vector
+ └── TrainingDataWriter.cs — writes JSONL to disk, one record per action taken
+```
+
+**`TrainingRecord`** (serialized to JSONL):
+```csharp
+public record TrainingRecord(
+ string SessionId,
+ string ActorId,
+ int TurnNumber,
+ string ActionType,
+ string ActionPayloadJson,
+ string StateFeaturesBase64, // FeatureExtractor output, base64-encoded float[]
+ int Outcome); // 1 = this actor won, 0 = lost
+```
+
+**`GameReplayExporter`** queries:
+```sql
+SELECT al.*, gs.winner_account_id
+FROM game_action_logs al
+JOIN game_sessions gs ON gs.id = al.game_session_id
+WHERE gs.status = 'Completed'
+ AND gs.ended_at > @lastExportedAt
+ AND al.action_type NOT IN ('game.ready', 'game.concede')
+ORDER BY al.game_session_id, al.sequence_number
+```
+
+For each row, it deserializes the state from `StateJson` (at that point in the log), calls
+`FeatureExtractor.Extract`, and writes a `TrainingRecord`.
+
+**Admin API**:
+- `POST /admin/ai/export-replays { sinceDate }` — triggers an export job
+- Output path: configurable via `appsettings.json`, e.g. `"Ai:TrainingDataPath": "/data/training/"`
+
+**Done when**: calling the export API on a DB with at least 10 completed games produces a
+valid `.jsonl` file where each line deserializes to a `TrainingRecord` and `StateFeaturesBase64`
+decodes to a float array of length ~990.
+
+---
+
+### Phase 3.4 — MCTS Engine (Difficulties 6–8)
+
+**Goal**: Implement Monte Carlo Tree Search and wire it as the engine for Difficulties 6–8.
+This engine does lookahead — it should noticeably outperform the heuristic engine.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── MCTS/
+ ├── MctsNode.cs — tree node (state, action, visits, wins)
+ ├── MctsTree.cs — UCB1 selection + expansion + backpropagation
+ ├── MctsSimulator.cs — random playout from a node using RandomDecisionEngine
+ ├── MctsEvaluator.cs — leaf-node board score (delegates to ScoringFunctions)
+ └── MonteCarloEngine.cs — IAiDecisionEngine implementation wrapping MctsTree
+```
+
+**`MonteCarloEngine.ComputeTurn(AiTurnContext ctx)`**:
+```
+Given timeBudgetMs (from profile):
+ 1. Root = MctsNode(currentState)
+ 2. While elapsed < timeBudgetMs AND iterations < maxIterations:
+ a. node = Selection(root) — UCB1 traversal
+ b. child = Expansion(node) — pick unexplored candidate action
+ c. result = MctsSimulator.Playout(child.state, maxDepth)
+ d. BackPropagate(child, result) — increment visits and wins up to root
+ 3. bestChild = root.children.MaxBy(c => c.Visits)
+ 4. Return bestChild.Action + recurse into bestChild for multi-step plans
+```
+
+Simulation uses `SelfPlayRunner` internally (configured for max-speed random play). Because
+`SelfPlayRunner` calls `GameEngine` directly, the playout is very fast — expect 100–500
+simulations per second per thread.
+
+**`AiDifficultyProfiles`** entries for 6–8:
+- Difficulty 6: `EngineType = "MCTS"`, `MctsTimeBudgetMs = 500`, `MctsMaxDepth = 3`
+- Difficulty 7: `EngineType = "MCTS"`, `MctsTimeBudgetMs = 1500`, `MctsMaxDepth = 5`
+- Difficulty 8: `EngineType = "MCTS"`, `MctsTimeBudgetMs = 4000`, `MctsMaxDepth = 7`
+
+**DI wiring**:
+```csharp
+services.AddTransient();
+```
+
+**Done when**:
+- A 100-game self-play batch of MCTS-Difficulty-7 vs Heuristic-Difficulty-5 shows MCTS winning
+ > 70% of games, confirming meaningful lookahead improvement
+- Per-turn latency for Difficulty 6 is < 600ms measured wall-clock (budget + overhead)
+
+---
+
+### Phase 3.5 — AI Calibration Job
+
+**Goal**: Automated measurement of AI win rates across difficulty tiers to confirm the
+calibration targets from §7.5 are being met. Admin-triggered; results stored for review.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Calibration/
+ └── AiCalibrationJob.cs — runs cross-difficulty self-play batches, records results
+```
+
+**`AiCalibrationJob.RunAsync(CancellationToken ct)`**:
+- Runs 50-game batches for each adjacent difficulty matchup (1v2, 2v3, ..., 7v8)
+- Records win rates in a new `ai_calibration_runs` table (id, run_at, difficulty_a, difficulty_b, win_rate_a, game_count)
+- Also runs the full heuristic difficulty ladder (1v5, 2v5, 3v5, 4v5) to confirm relative strength
+
+**Admin API**:
+- `POST /admin/ai/calibrate` — triggers calibration job
+- `GET /admin/ai/calibrate/history` — returns last N calibration run results
+
+**Done when**: calibration completes and the output shows monotonically increasing win rates
+across the difficulty ladder (Difficulty 3 beats Difficulty 2 > 60% of games, etc.).
+
+---
+
+### Phase 4.1 — Feature Extractor & Training Pipeline Validation
+
+**Goal**: Finalize `FeatureExtractor` (already stubbed in Phase 3.3) to produce a stable,
+documented feature vector. Validate it against known game states before the Python training
+pipeline is built against it.
+
+**Files to modify:**
+
+- `SOR.Ai/Training/FeatureExtractor.cs` — finalize all feature groups per §7.2, ensure
+ output length is constant regardless of board size variation (pad or truncate to fixed dims)
+
+**Files to create:**
+
+```
+Server/scripts/ai_training/
+├── requirements.txt — numpy, torch, pyarrow, onnx, onnxruntime
+├── extract_features.py — reads JSONL from Phase 3.3, converts to Parquet
+├── train.py — PyTorch training loop (policy + value heads)
+├── export_onnx.py — exports best checkpoint to ONNX
+└── benchmark.py — runs AiVsAi in ONNX mode, reports win rates
+```
+
+These are Python scripts committed to the repo under `Server/scripts/`. They are not part of
+the .NET build. Documentation in `Server/scripts/ai_training/README.md` covers:
+- Environment setup
+- How to point scripts at exported JSONL data
+- Expected training time per epoch
+- How to validate the ONNX output shape matches what `NeuralDecisionEngine` expects
+
+**Done when**: `extract_features.py` reads a `.jsonl` file from Phase 3.3 and writes a
+`.parquet` file; `train.py` runs at least 1 epoch without error and outputs a `.pt` checkpoint;
+`export_onnx.py` produces an `.onnx` file with the expected input/output shape.
+
+---
+
+### Phase 4.2 — Neural Decision Engine (Difficulties 9–10)
+
+**Goal**: Wire ONNX model inference into the server as `NeuralDecisionEngine`. This phase
+requires a trained model from Phase 4.1 to be useful, but the code can be written and tested
+with a randomly-initialized model first.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Engine/
+ └── NeuralDecisionEngine.cs — IAiDecisionEngine wrapping OnnxRuntime inference
+```
+
+**`NeuralDecisionEngine`**:
+- Loads `{AiTrainingDataPath}/models/sor-ai-v{N}.onnx` at construction
+- `ComputeTurn(ctx)`:
+ 1. `float[] features = FeatureExtractor.Extract(ctx.State, ctx.AiAccountId)`
+ 2. Run ONNX session inference → `policyLogits[]`, `valueScore`
+ 3. Generate `ActionCandidateGenerator.All(ctx)`
+ 4. Map candidates to policy indices; take softmax
+ 5. Pick action with highest policy score where value doesn't drop below threshold
+ 6. Repeat until `AiEndTurnAction`
+
+**Hot-reload API**:
+- `POST /admin/ai/reload-model { version: N }` — `NeuralDecisionEngine.ReloadModel(version)`
+ swaps the ONNX session without restart. Uses a read-write lock so in-flight turns complete
+ before the swap.
+
+**`AiDifficultyProfiles`** for 9–10:
+- Difficulty 9: `EngineType = "Neural"`, inference timeout 200ms, fallback to MCTS-7 if model not loaded
+- Difficulty 10: `EngineType = "Neural"`, beam search (top-3 policy candidates, pick highest value), 500ms
+
+**Package**: add `Microsoft.ML.OnnxRuntime` to `SOR.Ai.csproj` via `Directory.Packages.props`
+(using the existing central package version management pattern).
+
+**DI wiring**:
+```csharp
+services.AddSingleton(); // singleton: ONNX session is expensive to load
+```
+
+**Done when**: `NeuralDecisionEngine` runs inference without exception (even with a
+randomly-initialized model) and produces a legal sequence of `AiAction`s. The hot-reload API
+swaps the model file and subsequent turns use the new model.
+
+---
+
+### Phase 5.1 — Game-Over Handling & ELO Guard
+
+**Goal**: Ensure that when an AI is eliminated or the game ends, AI sessions are properly
+cleaned up and AI ELO adjustments are skipped on the human-facing `Account.RankScore`.
+Also handle the edge case where an AI is eliminated mid-game (FFA/team games).
+
+**Files to modify:**
+
+- `SOR.Game/Handlers/GameHandlerBase.cs` `FinalizeGameAsync` — add guard:
+ ```csharp
+ if (!winner.IsAi) { winner.RankScore += winnerDelta; }
+ if (!loser.IsAi) { loser.RankScore = Math.Max(0, loser.RankScore - loserDelta); }
+ ```
+ Same guard for `FinalizeMultiPlayerGameAsync`.
+ OP rewards (`OriginPoints`) are also withheld for AI accounts (they never show a balance).
+
+- `SOR.Ai/Core/AiPlayerSessionManager.cs` — on `GameEndedEvent`, cancel all `AiPlayerSession`
+ CancellationTokens for that session and remove from the dictionary
+
+- `SOR.Game/Handlers/GameHandlerBase.cs` `PushStateToPlayersAsync` — AI player IDs should
+ **not** receive Redis push (they have no WebSocket subscriber). Add filter:
+ `allIds.Where(pid => !aiRegistry.IsAi(pid))` before pushing. This avoids wasted Redis
+ publishes to queues nobody reads.
+
+**Done when**: completing a human-vs-AI game does not change the AI account's `RankScore`
+and does not trigger ELO/OP changes for the AI in the identity DB; the human's stats update
+correctly; Redis push is not sent to the AI account ID.
+
+---
+
+### Phase 5.2 — Triggered Ability Handling for AI
+
+**Goal**: Handle `game.ability.triggered_target_request` pushes for AI accounts. When an
+ability fires that needs manual target selection, the push currently goes to the triggering
+player's Redis channel — if that player is AI, nobody reads it and the game stalls.
+
+**Files to modify:**
+
+- `SOR.Game/Handlers/GameHandlerBase.cs` `PushStateToPlayersAsync` — after pushing the
+ `triggered_target_request`, check if `pending.ActorId` is an AI account. If so, instead
+ of pushing to Redis, call `AiTriggeredTargetResolver.ResolveAsync(pending, state, ct)` directly.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Engine/
+ └── AiTriggeredTargetResolver.cs — picks targets for triggered abilities
+```
+
+**`AiTriggeredTargetResolver.ResolveAsync`** reads the pending action's target requirements
+(from `PendingTriggeredTarget.ActionsJson`) and picks targets using the same heuristic scoring
+as the main decision engine — prefer targets that maximize board score. Falls back to a random
+valid target if scoring is too expensive.
+
+Submits the selection via `AiAuthenticatedConnection` + `game.triggered_target` message,
+identical to how a human client would respond.
+
+**Done when**: a game where the AI has a card with a triggered target-selection ability
+completes without stalling. Verify with a specific card/ability known to trigger this path.
+
+---
+
+### Phase 5.3 — Adaptive Difficulty
+
+**Goal**: Allow the system to auto-suggest (or auto-adjust) AI difficulty based on a player's
+recent win rate against AI, so new players aren't stuck on a difficulty that's too hard, and
+veteran players aren't bored on one that's too easy.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Adaptive/
+ └── AiDifficultyAdvisor.cs — computes recommended difficulty from recent game history
+```
+
+**`AiDifficultyAdvisor.GetRecommendedDifficultyAsync(Guid humanAccountId, CancellationToken ct) → int`**:
+- Queries last 20 completed AI games for `humanAccountId` from `game_sessions` where any
+ participant `IsAi = true`
+- Computes human win rate
+- If win rate > 70%: recommend current + 1 (up to 10)
+- If win rate < 30%: recommend current - 1 (down to 1)
+- Otherwise: return current difficulty
+
+**Client API**: `GET /game/ai/recommended-difficulty` — returns `{ recommendedDifficulty: N }`.
+Called by the client when the custom lobby AI configuration panel opens.
+
+**Done when**: a player who has won their last 15 AI games gets a `recommendedDifficulty`
+higher than their last used difficulty; a player on a losing streak gets a lower recommendation.
+
+---
+
+### Phase 5.4 — AI Personality & Lobby Display Polish
+
+**Goal**: Add display metadata (personality label, flavor text, avatar) to AI slots in the
+custom lobby. This is purely presentational — no game logic changes.
+
+**Files to create:**
+
+```
+Server/src/SOR.Ai/
+└── Metadata/
+ └── AiPersonalityMetadata.cs — static display data per strategy archetype
+```
+
+**`AiPersonalityMetadata`** is a static dictionary keyed by strategy name, providing:
+- `string PersonalityLabel` — e.g. "The Relentless" (Aggressive), "The Architect" (Control)
+- `string FlavorText` — 1-sentence description shown in lobby
+- `string AvatarSlug` — key into asset server for an AI avatar image
+
+**New response field**: `GameAddAiResponse` gains `string PersonalityLabel`, `string FlavorText`,
+`string AvatarSlug`. The client shows these in the AI slot card.
+
+**Done when**: adding an AI to a lobby returns personality metadata in the response; the custom
+lobby screen (client-side, separate ticket) can display the AI's avatar and personality label.
+
+---
+
+### Phase 5.5 — Counter-Deck Logic
+
+**Goal**: Allow the AI to pick a deck archetype that counters the human opponent's observed
+ArchSpirit, rather than always using its static default deck.
+
+**Files to modify / create:**
+
+- `SOR.Ai/Lobby/AiSlotAssigner.cs` — when the human's deck is known (lobby `HostDeckId`),
+ load the human's ArchSpirit affinity. Apply counter-affinity logic:
+ - Fire ArchSpirit → prefer Water-control AI deck
+ - Water ArchSpirit → prefer Nature-ramp AI deck
+ - etc. (full matrix defined in `CounterAffinityMatrix.cs`)
+
+- `SOR.Ai/Lobby/CounterAffinityMatrix.cs` — static `Affinity → Affinity[]` mapping (preferred
+ counter affinities in priority order)
+
+`AiSlotAssigner.Assign` now takes an optional `Affinity? opponentAffinity` parameter. When
+provided, it queries for AI accounts whose deck's ArchSpirit affinity appears in the counter list
+for that opponent affinity.
+
+**Done when**: adding an AI to a lobby where the host has a Fire-affinity ArchSpirit deck
+causes the AI account selected to have a Water-affinity deck (or the closest available match).
+
+---
+
+## Phase Summary
+
+| Phase | Track | Goal | Key Deliverable |
+|---|---|---|---|
+| 1.1 | A | Scaffold | `SOR.Ai.csproj` builds, wired into Host |
+| 1.2 | A | Transport | `AiAuthenticatedConnection`, `AiClientMessage` |
+| 1.3 | A | DB Schema | Migrations for `IsAi`, `AiSlotsJson` |
+| 1.4 | A | AI Accounts | 50 seeded AI accounts at startup |
+| 1.5 | A | AI Decks | Pre-built decks for every AI account |
+| 1.6 | A | Lobby Handlers | Host can add/remove/configure AI in lobby |
+| 1.7 | A | Session Manager | AI auto-sends `game.ready`, sessions tracked |
+| 2.1 | B | Turn Pipeline | AI takes turns (immediately end-turns) |
+| 2.2 | B | Placement | AI places ArchSpirit in Placement phase |
+| 2.3 | B | Random Engine | Difficulty 1 plays legal random game end-to-end |
+| 2.4 | B | Candidate Gen | All legal moves enumerated, unit tested |
+| 2.5 | B | Heuristic Engine | Difficulties 2–5 play purposeful games |
+| 3.1 | C | AI ELO | Internal ELO tracked for AI accounts |
+| 3.2 | C | Self-Play | In-memory AI-vs-AI runner, admin API |
+| 3.3 | C | Data Export | Replay JSONL export for training pipeline |
+| 3.4 | C | MCTS Engine | Difficulties 6–8 with lookahead |
+| 3.5 | C | Calibration | Automated win-rate calibration across difficulty tiers |
+| 4.1 | D | Feature Extractor | Python training scripts, validated feature vector |
+| 4.2 | D | Neural Engine | ONNX inference for Difficulties 9–10 |
+| 5.1 | E | ELO Guard | AI ELO/OP excluded from human-facing records |
+| 5.2 | E | Triggered Targets | AI resolves ability target-selection without stalling |
+| 5.3 | E | Adaptive Difficulty | Recommended difficulty API |
+| 5.4 | E | Personality | Display metadata, avatars, flavor text |
+| 5.5 | E | Counter-Deck | AI selects counter-affinity deck vs human |
+
+---
+
+## Key Design Decisions & Rationale
+
+| Decision | Rationale |
+|---|---|
+| AI goes through full handler pipeline | Ensures AI actions are fully validated, logged, and pushed to humans exactly as human actions are. No code duplication, no drift. |
+| AI accounts are real DB rows | Allows lobby, session, and replay systems to work unmodified. AI is a player, not a special case. |
+| Heuristic engine first | Fastest path to a playable feature. Gives training data. MCTS and Neural can replace it later with no API changes. |
+| ONNX Runtime for inference | Train in Python (PyTorch ecosystem, mature ML tooling), run in .NET (production server). Standard interop pattern. |
+| Self-play for training data | Human game data is sparse and biased toward popular strategies. Self-play explores the full strategy space faster. |
+| In-process action submission | No network hop, no extra infra. AI turn latency is controlled purely by think-time delay, not transport. |
+| Per-strategy deck seeding | Strategy is only meaningful if the AI's deck supports it. A control AI with an aggro deck would play incoherently. |
+| Mistake injection for difficulty | Easier to implement and tune than reducing search depth for Heuristic AI. More realistic too — low-skill AIs play wrong, not just slowly. |