@chessceo/mcp 0.31.2 → 0.34.0

package/dist/index.js

@@ -87,8 +87,17 @@ const AUTHED_TOOLS = new Set([
     "set_tag",
     "apply_mutations",
     "auto_evaluate",
+    "auto_evaluate_status",
+    "auto_evaluate_cancel",
+    "deep_analyse",
+    "deep_analyse_status",
+    "deep_analyse_cancel",
     "quote_engine_eval",
     "predict_human_move",
+    "prepare_opponent",
+    "get_prep_position",
+    "list_prep_sessions",
+    "delete_prep_session",
 ]);
 function isAuthedToolCall(body) {
     if (!body || typeof body !== "object")
@@ -195,55 +204,80 @@ const TOOLS = [
         },
     },
     {
-        name: "get_player_preparation",
-        description: "For a given player, colour and starting position, return both the moves the player actually chose (frequency + win rate) and the underlying games. Position is specified either as a move sequence in SAN (`line`) or a raw FEN. Use `line` iteratively to walk the opening tree: call once with empty `line`, pick a move, call again with `line` extended by that move, etc.\n\n" +
-            "GROUNDING: every claim about the opponent's repertoire must trace back to this tool's output. Don't assert 'they play sharply' or 'they hate isolated queen pawn' without pointing at the actual game counts / win rates in the response. Don't invent 'the opponent typically plays X' — check first. Compute is cheap: run this on more branches instead of pattern-matching from a chess book.\n\n" +
-            "AUTO-EVAL: if a cloud combo instance is running, the response includes `.eval` with a compact Stockfish + Lc0 read at the requested position (top move + score + PV) and the corresponding NAG. Do NOT fire a separate cloud_analyse for the same FEN — the eval is right there.\n\n" +
-            "Reading the response — CRITICAL:\n" +
-            "• Win % is one weight, not a verdict. Recommend 1.b3 over 1.d4 because 60% > 50% is wrong. Sample size matters (3 games at 66% is noise; 300 at 55% is signal); avgWhite / avgBlack per move show the rating context (a big score often means a rating gap, not repertoire truth).\n" +
-            "• Prep is symmetric information — both sides see the same history. Assume the opponent knows the weakness you spotted; a weak opponent won't patch it, a strong or improving one already has (but structural weaknesses like 'bad in Catalan structures' hold anyway).\n" +
-            "• Recency > career. The last 12-24 months dominate. This endpoint's compact/LLM view deliberately omits per-move `fashionScore` — at the individual level it's trailing noise. The general DB endpoint (`get_position_stats`) keeps it, where it's real fashion signal (what the top field is playing this month).\n" +
-            "• Opponent will deviate early. Prep is a tree, not a line — cover the 2 most likely replies at each real branching point, not one 20-move line.\n" +
-            "• Surprise is a scalpel. Don't tell a lifelong 1.e4 player to switch to 1.d4 — meta-signal screams prep. Rare secondary lines within the user's existing repertoire (e.g. 6.Bc4 instead of usual 6.Bg5 vs the Najdorf) are where surprise is real.\n\n" +
-            "For the full guide call the `read_prep_strategy_guide` tool.",
+        name: "prepare_opponent",
+        description: "Create a prep SESSION combining games from one or more sources — FIDE database, Chess.com account, Lichess account — with optional filters (colour, date range, time control). Returns a session `token` you pass to `get_prep_position` to query stats at any position within that filtered corpus.\n\n" +
+            "This is the main opponent-prep tool. Use it whenever a user asks 'prep me against X' — call once with the right sources+filters, then walk the tree with `get_prep_position(session_token, ...)`. Sessions are cached on the server (list existing ones with `list_prep_sessions` to avoid rebuilding).\n\n" +
+            "SOURCES (1-10 per call, combined into one gameset):\n" +
+            "- `fide` — needs `fideId`. Optional filters: `color`, `startMonth`/`endMonth`, `timeControl` (`classical`|`rapid`|`blitz`), `excludeOnline`.\n" +
+            "- `chesscom` — needs `username`. Filters: `color`, `startMonth`/`endMonth` (**required** for chesscom/lichess), `timeControl`.\n" +
+            "- `lichess` — needs `username`. Same filters as chesscom; `timeControl` also accepts `bullet` on Lichess.\n\n" +
+            "Multi-source example: one player with both a FIDE ID and a Lichess account → two sources in one call, all their games combined into one session.\n\n" +
+            "GROUNDING: every claim about the opponent's repertoire must trace back to a `get_prep_position` call on this session. Don't assert 'they play sharply' or 'they hate isolated queen pawn' without pointing at actual game counts / win rates in the response. Prep is a two-player game — see `read_prep_strategy_guide` before recommending an opening plan.",
         inputSchema: {
             type: "object",
             properties: {
-                fide_id: { type: "integer", description: "FIDE ID from search_player." },
-                color: {
-                    type: "string",
-                    enum: ["white", "black"],
-                    description: "Which colour the player is analysed with.",
-                },
-                file_id: {
-                    type: "string",
-                    description: "Prep file id to address the position from. Combine with `node_id` — the server derives the FEN from the tree, so you don't paste a FEN string. **Prefer this over `fen`/`line`/`moves` when a prep file is open.**",
-                },
-                node_id: {
-                    type: "string",
-                    description: "Node id inside `file_id` whose position to query. Root is 'r'. When set, overrides `fen`/`line`/`moves`.",
-                },
-                line: {
-                    type: "string",
-                    description: "Move sequence in SAN from the starting position, space-separated, no move numbers required. Example: 'e4 e5 Nf3'. Leave empty for startpos. Alias: `moves` (same thing). Only used if `node_id` is not set.",
-                },
-                moves: {
-                    type: "string",
-                    description: "SAN moves to apply on top of `fen` (or on top of startpos if no fen). Same shape as `line`. Wins over `line` if both are set. Only used if `node_id` is not set.",
-                },
-                fen: {
-                    type: "string",
-                    description: "Starting position as FEN. Combine with `moves` to walk from there, or use alone. Only used if `node_id` is not set.",
-                },
-                limit: {
-                    type: "integer",
-                    minimum: 1,
-                    maximum: 10,
-                    description: "Number of games to return (max 10 per request; page with offset).",
+                sources: {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: 10,
+                    description: "1-10 game sources, all combined into one filtered session.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            type: { type: "string", enum: ["fide", "chesscom", "lichess"], description: "Source type." },
+                            fide_id: { type: "integer", description: "FIDE ID (required for type='fide')." },
+                            username: { type: "string", description: "Platform username (required for type='chesscom'/'lichess')." },
+                            color: { type: "string", enum: ["white", "black"], description: "Filter: only games where this side is played by the source player. Omit for both colours." },
+                            start_month: { type: "string", pattern: "^\\d{4}/\\d{2}$", description: "Filter: games from this month onwards, format 'YYYY/MM'. **Required** for chesscom/lichess." },
+                            end_month: { type: "string", pattern: "^\\d{4}/\\d{2}$", description: "Filter: games up to this month, format 'YYYY/MM'. **Required** for chesscom/lichess." },
+                            time_control: { type: "string", enum: ["classical", "rapid", "blitz", "bullet"], description: "Filter: only this time control. `bullet` is Lichess-only." },
+                            exclude_online: { type: "boolean", description: "FIDE-only: exclude online-flagged games (default false)." },
+                        },
+                        required: ["type"],
+                    },
                 },
+            },
+            required: ["sources"],
+        },
+    },
+    {
+        name: "get_prep_position",
+        description: "Query one position within a prep session created by `prepare_opponent`. Returns move statistics (frequency + win rate + last-played date per move) plus the actual games played from that position, in one call.\n\n" +
+            "Position input: prefer `file_id`+`node_id` when inside a prep file (server derives FEN from the tree). Otherwise pass `fen`.\n\n" +
+            "AUTO-EVAL: if a cloud combo instance is running, the response includes `.eval` (Stockfish + Lc0 read at the position) so you don't need a separate cloud_analyse.\n\n" +
+            "Reading the response — CRITICAL:\n" +
+            "• Win % is one weight, not a verdict. Sample size matters (3 games at 66% is noise; 300 at 55% is signal).\n" +
+            "• Prep is symmetric information — both sides see the same history. Assume the opponent knows the weakness you spotted.\n" +
+            "• Recency > career. The last 12-24 months dominate — filter your session with `start_month` if the player's repertoire shifted.\n" +
+            "• Opponent will deviate early. Prep is a tree — cover the 2 most likely replies at each real branching point, not one 20-move line.\n\n" +
+            "For the full guide call `read_prep_strategy_guide`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_token: { type: "string", description: "Session token from `prepare_opponent`." },
+                file_id: { type: "string", description: "Prep file id — combine with `node_id` for tree-addressed position lookup." },
+                node_id: { type: "string", description: "Node id inside `file_id`. Root is 'r'. When set, overrides `fen`." },
+                fen: { type: "string", description: "Position as FEN. Only used if `node_id` is not set." },
+                limit: { type: "integer", minimum: 1, maximum: 50, description: "Games to return (default 10)." },
                 offset: { type: "integer", minimum: 0 },
             },
-            required: ["fide_id", "color"],
+            required: ["session_token"],
+        },
+    },
+    {
+        name: "list_prep_sessions",
+        description: "List the caller's active prep sessions with their tokens and metadata. Call this BEFORE `prepare_opponent` to reuse an existing session instead of rebuilding — sessions cost real backend work for chesscom/lichess (downloading months of games), so re-using saves time. Response includes source description, game count, and creation time per session.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "delete_prep_session",
+        description: "Delete one prep session by token. Free-form cleanup — sessions do expire automatically, but this is useful when you're done with one or when you want to force a rebuild after upstream data changed.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_token: { type: "string", description: "Token from `list_prep_sessions` or the response of `prepare_opponent`." },
+            },
+            required: ["session_token"],
         },
     },
     {
@@ -437,14 +471,14 @@ const TOOLS = [
     },
     {
         name: "cloud_analyse",
-        description: "Runs a synchronous ~2s analysis on the user's running combo instance and returns both Stockfish and Lc0's final read for the FEN — depth, top-N candidate moves with scores (centipawns from side-to-move POV, or mate distance), and each engine's principal variation.\n\n" +
+        description: "Runs a synchronous ~2s analysis on the user's running combo instance and returns both Stockfish and Lc0's final read for the FEN — depth, top-N candidate moves with scores (**scoreCp is White-POV centipawns**: +20 = White is +0.20 pawns better regardless of whose turn it is; matches the sign convention used everywhere else in this MCP, including the stored ceoEval). Mate is White-POV plies-to-mate (+5 = White mates in 5). Also returns each engine's principal variation.\n\n" +
             "GROUNDING: every claim you make about a position must trace back to actual engine output from a call in THIS session. Don't invent evaluations, don't name 'best moves' you haven't seen the engine list, don't fabricate variations that 'look plausible.' Compute is cheap — call this 5-10 times while walking a tree rather than pattern-matching from your training data. When you don't have data for the position, either run the tool or say so; don't fill the gap with chess prose the user can't distinguish from measured output.\n\n" +
             "Auto-picks the caller's only running combo instance; errors clearly if there are zero (start one first with start_cloud_engine) or more than one (destroy the extras first).\n\n" +
             "How to read the response:\n" +
             "• Stockfish is objective truth — trust it for 'does this line hold?' 'is there a tactic?' 'is this endgame drawn?' A Stockfish 0.00 means 'objectively equal', NOT 'trivial draw' — one side can still be much harder to play in practice.\n" +
             "• Lc0 is practical eval — trust it for 'which side is easier?' 'which candidate is best when Stockfish shows several as equal?' Lc0 sees long-term positional factors Stockfish's fixed search can miss.\n" +
             "• When they agree → high confidence. When they disagree → look at both scores and reason WHY (Stockfish sharply higher = tactic Lc0 missed; Lc0 higher = long-term positional edge past Stockfish's horizon). Never dismiss either — the disagreement is the signal.\n\n" +
-            "Contempt (`contempt`) skews Lc0 (only Lc0 — Stockfish always stays objective) toward White (positive) or Black (negative). Practical range -20..+20. Use it to find non-objective 'practical' ideas or when the user needs to steer toward fighting/solid lines with a specific colour. Do NOT quote a contempt-biased eval as objective — cross-check with Stockfish.\n\n" +
+            "Contempt (`contempt`) skews Lc0 (only Lc0 — Stockfish always stays objective) toward White (positive) or Black (negative). Signed 0-100 strength — same scale as the web UI's ContemptStrength slider (the server multiplies by 8 to produce Lc0's internal cp bias). Typical values: ±15 for a light nudge, ±30-60 for real fighting play, ±80-100 for maximum steer. Use it to find non-objective 'practical' ideas or when the user needs to lean toward fighting/solid lines with a specific colour. Do NOT quote a contempt-biased eval as objective — cross-check with Stockfish.\n\n" +
             "Also useful: pass `moves` on top of `fen` to explore a variation without computing FENs yourself (e.g. fen='<tabiya>', moves='b4 a5 c3'). And the flip-side-to-move threat check documented in the guide is a great free trick.\n\n" +
             "For the full guide including worked examples, call the `read_engine_usage_guide` tool.\n\n" +
             "Not for casual questions — this costs real money per second. Use `get_position_stats` for anything that doesn't require deep prep.\n\n" +
@@ -475,7 +509,12 @@ const TOOLS = [
                     type: "integer",
                     minimum: -100,
                     maximum: 100,
-                    description: "Lc0 contempt bias. 0 = objective (default). Positive favours White, negative favours Black; stay within -20..+20 in practice. Not applied to Stockfish. See engine_usage_primer prompt for when to use.",
+                    description: "Lc0 contempt bias. Signed 0-100 strength (same scale as the web UI's ContemptStrength slider — server multiplies by 8 to get the internal cp bias). 0 = objective (default). Positive favours White, negative favours Black. Typical: ±15 light nudge, ±30-60 real fighting play, ±80-100 maximum steer. Not applied to Stockfish. See engine_usage_primer for when to use.",
+                },
+                engines: {
+                    type: "array",
+                    items: { type: "string", enum: ["stockfish", "lc0"] },
+                    description: "Which engines to run. Default = both. Use `[\"lc0\"]` to skip Stockfish (e.g. while a deep_analyse job is holding the SF slot on the same combo). Use `[\"stockfish\"]` when only the objective read matters. The skipped engine's field is omitted from the response.",
                 },
             },
         },
@@ -500,7 +539,7 @@ const TOOLS = [
         name: "read_prep_file",
         description: "Read one prep file. Returns a compact tree (each node carries a stable `id`, `san`, `fen`, `ply`, optional `comment`/`nags`/`annotations`/`ceoEval`, and `children`) plus tags and the `version` for optimistic locking on subsequent mutations. NO raw PGN — all edits go through the mutation tools (add_move / add_line / set_comment / set_nags / set_annotations / delete_subtree / promote_variation / set_tag), which validate SAN and structure for you.\n\n" +
             "**Node addressing.** Every node has a stable `id` — root is `'r'`, every other node is an 8-hex-char content hash derived from its parent's id + its SAN. Sibling insertions, deletions and variation promotions do NOT change any other node's id. Pass this id as `node_id` (or `parent_id` for add_move / add_line) to every mutation and engine/DB tool.\n\n" +
-            "**Every engine/DB tool accepts `file_id`+`node_id`** (get_position_stats, cloud_analyse, describe_position, predict_human_move, prep_snapshot, get_player_preparation, quote_engine_eval). Use it whenever a file is open — the server derives the FEN from the tree, so you can't 'analyse the wrong position' by mis-typing a FEN.",
+            "**Every engine/DB tool accepts `file_id`+`node_id`** (get_position_stats, cloud_analyse, describe_position, predict_human_move, prep_snapshot, get_prep_position, quote_engine_eval). Use it whenever a file is open — the server derives the FEN from the tree, so you can't 'analyse the wrong position' by mis-typing a FEN.",
         inputSchema: {
             type: "object",
             properties: {
@@ -693,10 +732,11 @@ const TOOLS = [
     },
     {
         name: "auto_evaluate",
-        description: "Walk the tree from `node_id` (default `'r'` = whole file) and populate the persistent `ceoEval` (Stockfish + Lc0 numbers) on every descendant via cloud_analyse. Requires a running cloud combo instance.\n\n" +
-            "**Does NOT set visible NAGs.** NAG placement is your call, not the engine's — an opening tree full of 0.00 positions doesn't need a `$10` (=) glyph on every move (that's just noise on the board), and a `!` on a novelty or a `?!` on a risky committal is a judgment call the engine can't make. Use this tool to persist the raw numbers on every node, then re-read the file and hand-pick NAGs on the moves where a glyph carries real signal.\n\n" +
-            "On re-read every evaluated node carries `ceoEval: { sf: {cp, depth}, lc0: {cp, depth} }` — the numbers travel with the file. Read those back with quote_engine_eval before writing prose that references engine numbers. Use `only_missing=true` (default) to skip nodes already evaluated on repeat runs.\n\n" +
-            "Costs real money — hits cloud_analyse per node. A 200-node tree at 1.5s/node = ~5 min of engine time. Runs 4 evaluations in parallel to save wall time.",
+        description: "Walk the tree from `node_id` (default `'r'` = whole file) and populate the persistent `ceoEval` on every descendant via cloud_analyse. Requires a running cloud combo instance.\n\n" +
+            "**Async job — returns immediately.** Response: `{ job_id, target_count, status: 'running', estimated_seconds }`. Then poll `auto_evaluate_status(job_id)` until `done: true`. Cancel a run with `auto_evaluate_cancel(job_id)` — partial progress is preserved. Do useful other work between polls (write more of the tree, walk the opponent's repertoire) — the engine runs in the background.\n\n" +
+            "Progress is checkpointed to the prep file every 8 successfully-evaluated nodes, so a cancel / crash / MCP restart mid-run leaves the tree partially populated rather than losing everything. On MCP restart the job record disappears; re-run auto_evaluate and `only_missing=true` naturally skips what was already saved.\n\n" +
+            "**Does NOT set visible NAGs.** NAG placement is your call, not the engine's — an opening tree full of 0.00 positions doesn't need a `$10` (=) glyph on every move. Use quote_engine_eval on individual nodes before writing prose that references engine numbers.\n\n" +
+            "Costs real money — one cloud_analyse per node. A 200-node walk at default movetime is ~5 min of engine time (calls serialise on the per-combo semaphore in the backend).",
         inputSchema: {
             type: "object",
             properties: {
@@ -704,11 +744,83 @@ const TOOLS = [
                 node_id: { type: "string", description: "Subtree root (default 'r' = whole file)." },
                 only_missing: { type: "boolean", description: "Skip nodes that already carry a stored ceoEval (default true)." },
                 movetime_ms: { type: "integer", minimum: 500, maximum: 5000, description: "Per-node cloud_analyse think time (default 1500)." },
-                expected_version: { type: "integer" },
             },
             required: ["id"],
         },
     },
+    {
+        name: "auto_evaluate_status",
+        description: "Poll the status of an auto_evaluate job. Response: `{ status: 'running' | 'done' | 'cancelled' | 'error' | 'not_found', target_count, evaluated, errored, remaining, done, error?, version? }`. When `status: 'not_found'` the job either expired (kept ~15 min after completion), never existed, or the MCP restarted since it was created — re-run auto_evaluate.\n\n" +
+            "Typical poll cadence: every 3-5 s for small walks, every 10-30 s for large ones. Don't hammer — status is a pure in-memory read but polling doesn't speed the engine up.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                job_id: { type: "string", description: "Job id from the `auto_evaluate` response." },
+            },
+            required: ["job_id"],
+        },
+    },
+    {
+        name: "auto_evaluate_cancel",
+        description: "Ask a running auto_evaluate job to stop as soon as its current node finishes. Whatever progress was completed before cancellation is durably saved (checkpoint on cancel). Idempotent — cancelling an already-finished job is a no-op with a clear note in the response.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                job_id: { type: "string", description: "Job id from the `auto_evaluate` response." },
+            },
+            required: ["job_id"],
+        },
+    },
+    {
+        name: "deep_analyse",
+        description: "Start a long Stockfish think on a single position (up to 5 min movetime). Returns a `job_id` immediately; poll `deep_analyse_status(job_id)` for the result, cancel with `deep_analyse_cancel(job_id)`. Runs SF only — Lc0 doesn't benefit from long thinks past a handful of seconds — and **holds only the SF engine slot on the combo, so `cloud_analyse(..., engines: [\"lc0\"])` stays available for other work in parallel**.\n\n" +
+            "Use this when a specific critical position deserves depth — a novelty candidate, a hairy tactical shot, a difficult endgame — and you want Stockfish at depth 35+ rather than the ~depth 22 you get from a 2s cloud_analyse. Movetime is in ms; typical: 30_000-60_000 for 'careful check', 120_000-300_000 for 'find the truth'.\n\n" +
+            "Result shape when done matches cloud_analyse's Stockfish leg (depth, top-N candidates with scoreCp/mate, best move, PV). Auto-stores the eval on `file_id`+`node_id` when both are supplied, same as cloud_analyse.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file_id: { type: "string", description: "Prep file id. Combine with `node_id` to derive FEN from the tree AND persist the result on the node's ceoEval." },
+                node_id: { type: "string", description: "Node id inside `file_id`. Root is 'r'. When set, overrides `fen`/`moves`." },
+                fen: { type: "string", description: "Position as FEN. Only used if `node_id` is not set." },
+                moves: { type: "string", description: "Optional SAN moves on top of `fen`. Only used if `node_id` is not set." },
+                movetime_ms: {
+                    type: "integer",
+                    minimum: 5_000,
+                    maximum: 300_000,
+                    description: "Think time in ms. Default 60_000 (1 min). Max 300_000 (5 min).",
+                },
+                multipv: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 10,
+                    description: "Number of candidate lines (default 3).",
+                },
+            },
+        },
+    },
+    {
+        name: "deep_analyse_status",
+        description: "Poll a deep_analyse job. Response: `{ status: 'running' | 'done' | 'cancelled' | 'error' | 'not_found', elapsed_ms, movetime_ms, result?, error? }`. `result` shape when done: `{ engine, depth, timeMs, bestMove, lines: [{rank, depth, scoreCp?, mate?, pv, nodes?}] }` — the SF leg of a cloud_analyse response.\n\n" +
+            "Poll cadence: every ~15-30s for long thinks; there's no penalty for polling more often but the engine progresses at its own pace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                job_id: { type: "string", description: "Job id from `deep_analyse`." },
+            },
+            required: ["job_id"],
+        },
+    },
+    {
+        name: "deep_analyse_cancel",
+        description: "Ask a running deep_analyse job to stop early. The engine returns whatever it's found so far as the final result. Useful when a partial result at depth 25 is enough and you don't want to wait for depth 40. Idempotent for already-finished jobs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                job_id: { type: "string", description: "Job id from `deep_analyse`." },
+            },
+            required: ["job_id"],
+        },
+    },
     {
         name: "quote_engine_eval",
         description: "Return the stored engine eval for a node, or null if that node was never analysed. **Call this before writing prose or NAGs that quote engine numbers** — if it returns null, you have no measurement to cite. Do NOT infer an eval for the node from siblings or children; either analyse it (cloud_analyse with node_id) or omit the number from your prose.\n\n" +
@@ -968,12 +1080,33 @@ async function applyBatchMutations(args) {
     const savedRow = saved;
     return { ok: true, results, version: savedRow.version };
 }
-// Auto-evaluate: walk the tree from `path`, run cloud_analyse on each node,
-// stash the compact per-engine eval in the node's `ceoEval` field (which
-// survives across sessions and appears on every read_prep_file), and
-// derive the NAG from the SF score. Both writes go via a single batch
-// mutation at the end so a 200-node evaluate is one save.
+const evalJobs = new Map();
+// GC finished jobs after this long so status polling remains useful
+// for a while but the map doesn't grow unbounded across long uptimes.
+const EVAL_JOB_TTL_MS = 15 * 60 * 1000;
+// Checkpoint interval — save progress every N successfully-evaluated
+// nodes so a mid-run kill leaves the tree partially populated. Small
+// enough that <15s of work is at risk per checkpoint on a slow combo,
+// large enough that the save overhead stays a small fraction of the
+// per-node cost.
+const SAVE_EVERY_N = 8;
+function newEvalJobId() {
+    // 12 hex chars, low collision (same 32-bit width as node ids ×1.5).
+    const rand = Math.random().toString(16).slice(2, 8);
+    return `evj_${Date.now().toString(16)}${rand}`;
+}
+// Sweep expired jobs on every start/status call — cheap, doesn't need
+// a background timer, keeps the map bounded to active + recent jobs.
+function reapExpiredEvalJobs() {
+    const now = Date.now();
+    for (const [k, j] of evalJobs) {
+        if (j.finishedAt && now - j.finishedAt > EVAL_JOB_TTL_MS) {
+            evalJobs.delete(k);
+        }
+    }
+}
 async function autoEvaluate(args) {
+    reapExpiredEvalJobs();
     const id = String(args.id);
     const startNodeId = typeof args.node_id === "string" && args.node_id.length > 0
         ? String(args.node_id)
@@ -1001,45 +1134,294 @@ async function autoEvaluate(args) {
     // If the caller anchored at the root, skip evaluating the root itself
     // (no move); otherwise the anchor node IS a real move and gets evaluated.
     walk(startNode, startNode.id === ROOT_ID);
-    if (targets.length === 0)
-        return { ok: true, evaluated: 0, skipped: 0, version: g.version };
-    // Dispatch cloud_analyse in parallel with a 4-way cap so we don't
-    // over-saturate the engine-ws connection cap (single-client per port).
-    const stored = [];
-    const CONCURRENCY = 4;
-    let cursor = 0;
-    async function worker() {
-        while (cursor < targets.length) {
-            const idx = cursor++;
-            const t = targets[idx];
+    // Nothing to do → return a done job synthetically so the caller doesn't
+    // need to special-case the empty response.
+    if (targets.length === 0) {
+        const jobId = newEvalJobId();
+        evalJobs.set(jobId, {
+            id: jobId,
+            fileId: id,
+            status: "done",
+            targetCount: 0,
+            evaluated: 0,
+            errored: 0,
+            finalVersion: g.version,
+            startedAt: Date.now(),
+            finishedAt: Date.now(),
+            cancelled: false,
+        });
+        return { job_id: jobId, target_count: 0, status: "done", version: g.version };
+    }
+    const jobId = newEvalJobId();
+    const job = {
+        id: jobId,
+        fileId: id,
+        status: "running",
+        targetCount: targets.length,
+        evaluated: 0,
+        errored: 0,
+        startedAt: Date.now(),
+        cancelled: false,
+    };
+    evalJobs.set(jobId, job);
+    // Unawaited — runs concurrently with the tool response. Any thrown
+    // error gets recorded on the job so the LLM's status poll surfaces
+    // it instead of the process seeing an unhandled rejection.
+    void runEvalJob(job, id, targets, movetimeMs).catch(err => {
+        job.status = "error";
+        job.error = err instanceof Error ? err.message : String(err);
+        job.finishedAt = Date.now();
+    });
+    return {
+        job_id: jobId,
+        target_count: targets.length,
+        status: "running",
+        // Rough time estimate at the current default movetime. Serialization
+        // on the per-combo semaphore means walltime ≈ target_count × movetime.
+        estimated_seconds: Math.round((targets.length * movetimeMs) / 1000),
+    };
+}
+// Worker body — walks targets sequentially (concurrency > 1 is a lie
+// against the per-combo semaphore in the backend anyway), checkpoints
+// every SAVE_EVERY_N successfully-evaluated nodes so partial progress
+// is durable, and re-anchors the version after each save.
+async function runEvalJob(job, fileId, targets, movetimeMs) {
+    const pending = [];
+    const flush = async () => {
+        if (pending.length === 0)
+            return;
+        // No expected_version — auto_evaluate treats concurrent edits by
+        // the LLM as last-write-wins on the ceoEval field specifically.
+        // Safe because set_ceo_eval is idempotent per node and other
+        // mutations (add_move / set_comment / etc.) don't touch ceoEval.
+        const saved = await applyBatchMutations({
+            id: fileId,
+            mutations: pending,
+        });
+        const sr = saved;
+        if (typeof sr.version === "number")
+            job.finalVersion = sr.version;
+        pending.length = 0;
+    };
+    for (const t of targets) {
+        if (job.cancelled)
+            break;
+        try {
+            const analysis = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen: t.fen, movetime_ms: movetimeMs, multipv: 1 });
+            const ev = analysisToStoredEval(analysis, t.fen);
+            if (ev) {
+                pending.push({ op: "set_ceo_eval", node_id: t.nodeId, ceoEval: ev });
+                job.evaluated++;
+            }
+            else {
+                job.errored++;
+            }
+        }
+        catch {
+            // Per-node failure — record and continue; a bad FEN or a transient
+            // engine hiccup on one node shouldn't kill the whole walk.
+            job.errored++;
+        }
+        if (pending.length >= SAVE_EVERY_N) {
             try {
-                const analysis = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen: t.fen, movetime_ms: movetimeMs, multipv: 1 });
-                const ev = analysisToStoredEval(analysis, t.fen);
-                if (ev)
-                    stored.push({ nodeId: t.nodeId, ev });
+                await flush();
+            }
+            catch {
+                // Save failure is bad but not fatal — try again on the next
+                // checkpoint or at the end. Progress remains in `pending`
+                // so nothing is lost as long as the process stays alive.
+            }
+        }
+    }
+    // Final flush regardless of cancellation — durably persist whatever
+    // work was completed before the user asked to stop.
+    try {
+        await flush();
+    }
+    catch (err) {
+        job.error = err instanceof Error ? err.message : String(err);
+        job.status = "error";
+        job.finishedAt = Date.now();
+        return;
+    }
+    job.status = job.cancelled ? "cancelled" : "done";
+    job.finishedAt = Date.now();
+}
+function autoEvaluateStatus(args) {
+    reapExpiredEvalJobs();
+    const jobId = String(args.job_id || "").trim();
+    if (!jobId)
+        throw new Error("`job_id` is required");
+    const job = evalJobs.get(jobId);
+    if (!job) {
+        return {
+            status: "not_found",
+            note: "Job unknown — either expired (kept ~15 min after completion), never existed, or the MCP process restarted since it was created. Re-run auto_evaluate to start over; the `only_missing` default will skip nodes already evaluated in the prep file.",
+        };
+    }
+    return {
+        job_id: job.id,
+        status: job.status,
+        target_count: job.targetCount,
+        evaluated: job.evaluated,
+        errored: job.errored,
+        remaining: Math.max(0, job.targetCount - job.evaluated - job.errored),
+        done: job.status !== "running",
+        error: job.error,
+        version: job.finalVersion,
+        started_at_ms: job.startedAt,
+        finished_at_ms: job.finishedAt,
+    };
+}
+function autoEvaluateCancel(args) {
+    const jobId = String(args.job_id || "").trim();
+    if (!jobId)
+        throw new Error("`job_id` is required");
+    const job = evalJobs.get(jobId);
+    if (!job)
+        return { status: "not_found" };
+    if (job.status !== "running") {
+        return { status: job.status, note: "Job already finished; nothing to cancel." };
+    }
+    job.cancelled = true;
+    // status transitions to "cancelled" on the next per-node iteration
+    // inside runEvalJob, after the final flush persists progress.
+    return { status: "cancelling", evaluated_so_far: job.evaluated };
+}
+const deepJobs = new Map();
+const DEEP_JOB_TTL_MS = 15 * 60 * 1000;
+function newDeepJobId() {
+    const rand = Math.random().toString(16).slice(2, 8);
+    return `deep_${Date.now().toString(16)}${rand}`;
+}
+function reapExpiredDeepJobs() {
+    const now = Date.now();
+    for (const [k, j] of deepJobs) {
+        if (j.finishedAt && now - j.finishedAt > DEEP_JOB_TTL_MS) {
+            deepJobs.delete(k);
+        }
+    }
+}
+async function deepAnalyseStart(args) {
+    reapExpiredDeepJobs();
+    const resolved = await resolveFromNodeOrFen(args);
+    const fen = resolved.fen;
+    const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : 60_000;
+    const multipv = typeof args.multipv === "number" ? args.multipv : 3;
+    const jobId = newDeepJobId();
+    const job = {
+        id: jobId,
+        status: "running",
+        fileHandle: resolved.file,
+        fen,
+        movetimeMs,
+        multipv,
+        startedAt: Date.now(),
+        cancelController: new AbortController(),
+    };
+    deepJobs.set(jobId, job);
+    // Kick off the long HTTP call unawaited — resolves when the backend
+    // returns the SF snapshot. authedRequest is a plain fetch under the
+    // hood; abort signal flows via cancelController.
+    void runDeepJob(job).catch(err => {
+        job.status = "error";
+        job.error = err instanceof Error ? err.message : String(err);
+        job.finishedAt = Date.now();
+    });
+    return {
+        job_id: jobId,
+        status: "running",
+        movetime_ms: movetimeMs,
+        fen,
+    };
+}
+async function runDeepJob(job) {
+    const body = {
+        fen: job.fen,
+        movetime_ms: job.movetimeMs,
+        multipv: job.multipv,
+        engines: ["stockfish"],
+    };
+    let raw;
+    try {
+        // TODO(future): plumb an AbortSignal through authedRequest for
+        // real mid-flight cancellation. For now, cancel just marks the
+        // job so the caller stops polling; the backend still runs the
+        // engine to completion and the result is stored on the job
+        // record but flagged cancelled.
+        raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
+    }
+    catch (err) {
+        job.status = "error";
+        job.error = err instanceof Error ? err.message : String(err);
+        job.finishedAt = Date.now();
+        return;
+    }
+    const converted = convertCloudSnapshotResponse(raw, job.fen);
+    const sf = converted.stockfish;
+    if (job.cancelController.signal.aborted) {
+        job.status = "cancelled";
+    }
+    else {
+        job.status = "done";
+    }
+    job.result = sf ?? null;
+    job.finishedAt = Date.now();
+    // Same node-persistence as cloud_analyse: if the caller anchored on
+    // file_id+node_id, store the SF-only eval as the node's ceoEval so
+    // quote_engine_eval can cite it later. We build a StoredEval that has
+    // only the sf leg — no Lc0 was run.
+    if (job.fileHandle && sf) {
+        const ev = analysisToStoredEval({ stockfish: sf }, job.fen);
+        if (ev) {
+            try {
+                await storeEvalOnNode(job.fileHandle, ev);
             }
             catch {
-                // best-effort — a single failed node shouldn't kill the batch
+                // best-effort — the analysis result is what the LLM asked for
             }
         }
     }
-    await Promise.all(Array.from({ length: CONCURRENCY }, () => worker()));
-    if (stored.length === 0)
-        return { ok: true, evaluated: 0, skipped: targets.length, version: g.version };
-    // Persist the raw numbers only — never touch visible NAGs. NAG glyphs
-    // are the LLM's editorial call (novelty, sharp choice, real mistake),
-    // not an automatic mapping from the engine number. Stamping `$10` on
-    // every 0.00 position in an opening tree just clutters the board.
-    // The threshold-derived NAG still lives INSIDE `ceoEval.nag` so the
-    // LLM can read it back and decide whether to promote it to a visible
-    // NAG on a case-by-case basis.
-    const batchMutations = [];
-    for (const s of stored) {
-        batchMutations.push({ op: "set_ceo_eval", node_id: s.nodeId, ceoEval: s.ev });
+}
+function deepAnalyseStatus(args) {
+    reapExpiredDeepJobs();
+    const jobId = String(args.job_id || "").trim();
+    if (!jobId)
+        throw new Error("`job_id` is required");
+    const job = deepJobs.get(jobId);
+    if (!job) {
+        return {
+            status: "not_found",
+            note: "Job unknown — expired (kept ~15 min after completion), never existed, or the MCP process restarted.",
+        };
     }
-    const saveResult = await applyBatchMutations({ id, mutations: batchMutations, expected_version: g.version });
-    const sr = saveResult;
-    return { ok: true, evaluated: stored.length, skipped: targets.length - stored.length, version: sr.version };
+    return {
+        job_id: job.id,
+        status: job.status,
+        movetime_ms: job.movetimeMs,
+        elapsed_ms: (job.finishedAt ?? Date.now()) - job.startedAt,
+        fen: job.fen,
+        result: job.result,
+        error: job.error,
+        started_at_ms: job.startedAt,
+        finished_at_ms: job.finishedAt,
+    };
+}
+function deepAnalyseCancel(args) {
+    const jobId = String(args.job_id || "").trim();
+    if (!jobId)
+        throw new Error("`job_id` is required");
+    const job = deepJobs.get(jobId);
+    if (!job)
+        return { status: "not_found" };
+    if (job.status !== "running") {
+        return { status: job.status, note: "Job already finished; nothing to cancel." };
+    }
+    job.cancelController.abort();
+    // Status flips to "cancelled" when runDeepJob observes the abort on
+    // completion. Backend keeps churning until movetime elapses (mid-
+    // flight abort of the HTTP call is a follow-up).
+    return { status: "cancelling", elapsed_ms: Date.now() - job.startedAt };
 }
 // Walk chess.js-free: resolve a path against a tree, throw if invalid.
 function pathIntoTree(root, path) {
@@ -1312,6 +1694,46 @@ function resolveFenFromArgs(args) {
     }
     return board.fen();
 }
+// Normalize one MCP `prepare_opponent` source into the shape the backend's
+// /api/chess/prep/prepare-multi expects. Handles two impedance mismatches:
+//   - snake_case → camelCase (fide_id → fideId, start_month → startMonth, etc.)
+//   - the unified `time_control` string → per-source-type filter:
+//       * fide / chesscom → timeFormats: ["Classical" | "Rapid" | "Blitz"]
+//       * lichess → perfType: "classical" | "rapid" | "blitz" | "bullet"
+// Backend validates required fields per source type, so we don't need to
+// pre-reject missing username/fideId here — it'll come back as a 400 the
+// LLM can act on.
+function normalizeSourceForBackend(src, idx) {
+    const type = typeof src.type === "string" ? src.type : "";
+    if (type !== "fide" && type !== "chesscom" && type !== "lichess") {
+        throw new Error(`sources[${idx}].type must be one of fide|chesscom|lichess (got ${JSON.stringify(src.type)})`);
+    }
+    const out = { type };
+    if (typeof src.fide_id === "number")
+        out.fideId = src.fide_id;
+    if (typeof src.username === "string" && src.username.trim() !== "")
+        out.username = src.username.trim();
+    if (typeof src.color === "string" && (src.color === "white" || src.color === "black"))
+        out.color = src.color;
+    if (typeof src.start_month === "string" && src.start_month.trim() !== "")
+        out.startMonth = src.start_month.trim();
+    if (typeof src.end_month === "string" && src.end_month.trim() !== "")
+        out.endMonth = src.end_month.trim();
+    if (typeof src.exclude_online === "boolean")
+        out.excludeOnline = src.exclude_online;
+    const tc = typeof src.time_control === "string" ? src.time_control : "";
+    if (tc) {
+        if (type === "lichess") {
+            out.perfType = tc;
+        }
+        else {
+            // fide + chesscom take a titlecased timeFormats array.
+            const titled = tc.charAt(0).toUpperCase() + tc.slice(1);
+            out.timeFormats = [titled];
+        }
+    }
+    return out;
+}
 // Async resolver used by every engine / DB tool. If the caller supplied
 // file_id + node_id (preferred), load the file, resolve the node, and
 // return both the FEN and a handle we can use to persist ceoEval later.
@@ -1406,27 +1828,31 @@ async function callToolInner(name, args) {
             return get("/api/chess/players/search/simple", { q: String(args.name), view: "llm" });
         case "get_player_profile":
             return get("/api/chess/players/profile", { fideId: Number(args.fide_id) });
-        case "get_player_preparation": {
-            // Node-first: if file_id+node_id was given, derive the FEN from the
-            // tree (never trust an LLM-supplied FEN when a node reference is
-            // available). Otherwise fall back to fen/moves/line.
+        case "prepare_opponent": {
+            const rawSources = Array.isArray(args.sources) ? args.sources : [];
+            if (rawSources.length === 0)
+                throw new Error("`sources` array required");
+            const sources = rawSources.map((s, i) => normalizeSourceForBackend(s, i));
+            return authedRequest("POST", "/api/chess/prep/prepare-multi", { sources });
+        }
+        case "get_prep_position": {
+            const token = String(args.session_token || "").trim();
+            if (!token)
+                throw new Error("`session_token` required — create one with prepare_opponent");
             const resolved = await resolveFromNodeOrFen(args);
-            const effectiveFen = resolved.fen;
-            const params = {
-                fideId: Number(args.fide_id),
-                color: String(args.color),
-                compact: "true",
-                fen: effectiveFen,
+            const fen = resolved.fen;
+            const qs = {
+                token,
+                fen,
+                limit: typeof args.limit === "number" ? args.limit : 10,
             };
-            if (typeof args.limit === "number")
-                params.limit = args.limit;
             if (typeof args.offset === "number")
-                params.offset = args.offset;
+                qs.offset = args.offset;
             const [raw, ev] = await Promise.all([
-                get("/api/chess/prep/by-player", params),
-                fetchCompactEval(effectiveFen),
+                get("/api/chess/prep/unified", qs),
+                fetchCompactEval(fen),
             ]);
-            const converted = convertAvailableMovesToSAN(raw, effectiveFen);
+            const converted = convertAvailableMovesToSAN(raw, fen);
             if (converted && typeof converted === "object") {
                 trimGamesMovetext(converted);
                 stripPositionResponse(converted);
@@ -1435,6 +1861,14 @@ async function callToolInner(name, args) {
             }
             return converted;
         }
+        case "list_prep_sessions":
+            return authedRequest("GET", "/api/chess/prep/sessions");
+        case "delete_prep_session": {
+            const token = String(args.session_token || "").trim();
+            if (!token)
+                throw new Error("`session_token` required");
+            return authedRequest("DELETE", `/api/chess/prep/sessions/${encodeURIComponent(token)}`);
+        }
         case "get_position_stats": {
             const resolved = await resolveFromNodeOrFen(args);
             const fen = resolved.fen;
@@ -1515,6 +1949,8 @@ async function callToolInner(name, args) {
                 body.multipv = args.multipv;
             if (typeof args.contempt === "number")
                 body.contempt = args.contempt;
+            if (Array.isArray(args.engines))
+                body.engines = args.engines;
             const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
             const converted = convertCloudSnapshotResponse(raw, fen);
             // Node-addressed calls: persist the result on the node's ceoEval
@@ -1530,6 +1966,12 @@ async function callToolInner(name, args) {
             }
             return converted;
         }
+        case "deep_analyse":
+            return deepAnalyseStart(args);
+        case "deep_analyse_status":
+            return deepAnalyseStatus(args);
+        case "deep_analyse_cancel":
+            return deepAnalyseCancel(args);
         case "list_prep_files":
             return authedRequest("GET", "/api/agent/prep-files");
         case "search_prep_files":
@@ -1588,6 +2030,10 @@ async function callToolInner(name, args) {
             return applyBatchMutations(args);
         case "auto_evaluate":
             return autoEvaluate(args);
+        case "auto_evaluate_status":
+            return autoEvaluateStatus(args);
+        case "auto_evaluate_cancel":
+            return autoEvaluateCancel(args);
         case "quote_engine_eval": {
             const fileId = String(args.id);
             const nodeId = argNodeId(args);
@@ -1714,7 +2160,7 @@ Preparation workflow — follow the steps in order and be explicit about which t
    - Rapid and blitz reveal what they play under time pressure but may include experiments.
    - Online games are useful but noisier (blitz gambits, alt accounts).
 
-4. **Walk the opponent's repertoire against ${me}'s color.** Call \`get_player_preparation\` on the opponent for the color they'll have in this game. Iterate: start from move 1, pick the opponent's most-played reply, call again with \`line\` extended. Look for:
+4. **Walk the opponent's repertoire against ${me}'s color.** Call \`prepare_opponent\` once with the opponent's FIDE ID (add \`chesscom\` / \`lichess\` sources if you know their handles), filtered to the color they'll have in this game — plus \`start_month\` (last 12-24 months) and \`time_control: "classical"\` if you want the strongest signal. That returns a session \`token\`. Then walk the tree with \`get_prep_position(session_token=token, node_id="r")\`, pick the opponent's most-played reply, call again as you descend. Look for:
    - **Weak lines**: variations where the opponent scores below 40% as their side.
    - **Shallow lines**: openings the opponent has played only a few times — probably less deeply prepared.
    - **Abandoned lines**: openings they used to play but stopped. Something went wrong; may not want to revisit.
@@ -1756,7 +2202,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (req) => {
 1. \`search_player\` to get their FIDE ID.
 2. \`get_player_profile\` — pull rating history, career splits by color and time control, opening repertoire, opponent analysis, top events, notable wins and losses.
 3. Weight the data: recent (last 12-24 months) > older, classical OTB > rapid/blitz > online.
-4. \`get_player_preparation\` for both colors from the starting position to summarise their opening choices with actual frequencies and win rates.
+4. \`prepare_opponent\` twice (once per colour, or once with two sources), then \`get_prep_position(session_token, node_id="r")\` to summarise their opening choices with actual frequencies and win rates. Filter with \`start_month\` if you only care about their current repertoire.
 5. Deliver: current strength, characteristic openings, one-sentence style read, biggest wins, biggest losses / recurring weakness. Cite the numbers.`;
             break;
         }

package/docs/engine-usage.md

@@ -70,19 +70,24 @@ Trust Lc0 for:
 
 Contempt is an Lc0 option that skews its evaluation and move choice toward one side. Passing `contempt` to `cloud_analyse` sets it on the Lc0 leg only; Stockfish always analyzes objectively.
 
-**Range:** -100 to +100 accepted; **practical range: -20 to +20**. Beyond ±20 Lc0 starts picking objectively bad moves that only look good under an extreme bias.
+**Scale:** signed 0-100 strength — the same value the user's web UI shows on its ContemptStrength slider. The server multiplies by 8 to produce Lc0's internal centipawn bias, so `contempt=25` sends 200 cp, `contempt=50` sends 400 cp, `contempt=100` sends 800 cp. Positive favours White, negative favours Black, zero is objective.
 
-- **Positive contempt** (e.g. `+15`): Lc0 assumes it's playing *from White's side* against equal or slightly weaker opposition. It picks more ambitious, complicated moves and avoids quick simplifications. The eval reads higher than pure objective. Concrete effect: with White, Lc0 will less often steer into the Exchange Slav or a symmetrical Berlin.
-- **Negative contempt** (e.g. `-15`): Same but from Black's side. Lc0 will play sharper, more provocative lines with Black — more likely to pick a Sveshnikov over a Petroff, or a Grünfeld over a Slav.
+**Practical magnitudes:**
+- `±10-20` — a light nudge. Small preference shift, mostly for tie-breaking between candidates Lc0 already sees as near-equal.
+- `±30-60` — real fighting play. Lc0 avoids simplifications, prefers keeping tension, favours the more ambitious side of a choice.
+- `±80-100` — maximum steer. Use when the user needs Lc0 to surface *only* fighting ideas for a must-win, at the cost of ignoring objectively safer choices.
 - **Zero** (default): pure objective Lc0.
 
+- **Positive contempt** (e.g. `+30`): Lc0 assumes it's playing *from White's side* against equal or slightly weaker opposition. It picks more ambitious, complicated moves and avoids quick simplifications. The eval reads higher than pure objective. Concrete effect: with White, Lc0 will less often steer into the Exchange Slav or a symmetrical Berlin.
+- **Negative contempt** (e.g. `-30`): Same but from Black's side. Lc0 will play sharper, more provocative lines with Black — more likely to pick a Sveshnikov over a Petroff, or a Grünfeld over a Slav.
+
 The eval Lc0 returns when contempt is set is **not** the objective eval — it's Lc0's assessment under the contempt bias. If you also want the objective read, look at the Stockfish leg of the same response.
 
 ### When to set contempt
 
-- **Finding new ideas** — set contempt in the direction you're preparing to see moves the objective engine wouldn't consider "safe enough." Lines Lc0 rejects at contempt=0 but likes at contempt=±15 are candidate surprises.
-- **Building a solid repertoire** — small positive contempt for your color if the user wants to take positions seriously (real, competitive games) without gambling on unclear complications.
-- **Playing for a win with the "worse" side** — negative contempt if the user needs to avoid drawing lines with Black in a must-win situation.
+- **Finding new ideas** — set contempt in the direction you're preparing to see moves the objective engine wouldn't consider "safe enough." Lines Lc0 rejects at contempt=0 but likes at contempt=±30 are candidate surprises.
+- **Building a solid repertoire** — small positive contempt (`+10` to `+20`) for your color if the user wants to take positions seriously (real, competitive games) without gambling on unclear complications.
+- **Playing for a win with the "worse" side** — negative contempt (`-30` to `-60`) if the user needs to avoid drawing lines with Black in a must-win situation.
 - **Never with zero direction** — always know *why* you're skewing before you set contempt. It's a specific tool for a specific question, not a default knob.
 
 ## Tricks worth knowing
@@ -98,6 +103,31 @@ The gap (1.4 - 0.2 = 1.2) is roughly the value of the tempo Black has to spend d
 
 **Gotcha:** flipping side-to-move invalidates the en passant target field (if the last move was a two-square pawn push, the ep square is now stale). Also, both sides are counted as still having whichever castling rights are in the FEN — don't do this in the middle of a castling sequence. For opening / middlegame threat-checking it's a very useful idiom.
 
+## Deep Stockfish thinks: `deep_analyse`
+
+`cloud_analyse` runs both engines with a movetime cap of 10 s — deliberately fast because most opening-tree questions are answered in 2–3 s. For **one specific critical position** where you want depth 35+ instead of the usual depth 22, use `deep_analyse`:
+
+- SF-only (Lc0 saturates in a handful of seconds — no benefit past ~5 s of movetime).
+- Movetime up to 5 min.
+- Async: returns a `job_id` immediately, poll `deep_analyse_status(job_id)`, cancel with `deep_analyse_cancel(job_id)` if you decide partial depth is enough.
+- **Holds only the Stockfish slot on the combo.** Lc0 remains callable for other positions via `cloud_analyse({ engines: ["lc0"], … })` while the deep think runs. Use that during the wait — walk other branches, sanity-check candidates.
+
+Typical movetimes:
+- `30_000 – 60_000` (30–60 s) — careful check on a candidate move
+- `120_000 – 300_000` (2–5 min) — "find the truth" on a novelty, tactical shot, or difficult endgame
+
+Only use it when you actually need the depth. Regular `cloud_analyse` handles the ~5–10 branches of a typical prep walk perfectly well.
+
+## Splitting engines on `cloud_analyse`
+
+`cloud_analyse` accepts an `engines` list to run only one leg:
+
+- `engines: ["lc0"]` — Lc0 only, useful while a `deep_analyse` is holding the Stockfish slot.
+- `engines: ["stockfish"]` — SF only, when only the objective read matters and you want to skip the Lc0 latency.
+- Default (omitted) — both engines. This is what you want for real prep decisions.
+
+The skipped engine's field is omitted from the response (not present as an empty object).
+
 ## Worked example
 
 User is preparing Black against a 2600 opponent who plays 1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Be3 e5. You want to know if 7.Nb3 or 7.Nf3 is more testing.
@@ -106,10 +136,10 @@ Two calls:
 1. `cloud_analyse(fen=<position after 6...e5>, multipv=2)` — get both engines' top choices with movetime=2000.
 2. If Stockfish scores them equal but Lc0 prefers one by 0.10-0.20, that's your practical answer. The user will find that line harder to face.
 
-If the user is specifically preparing to *play* the black side in a must-win, add `contempt=-15` on a follow-up call to see which lines Lc0 finds most fighting for Black. Compare against Stockfish's objective read to make sure the fighting choice isn't just losing.
+If the user is specifically preparing to *play* the black side in a must-win, add `contempt=-30` (or up to `-60` for a harder steer) on a follow-up call to see which lines Lc0 finds most fighting for Black. Compare against Stockfish's objective read to make sure the fighting choice isn't just losing.
 
 ## What NOT to do
 
-- **Don't quote Lc0's contempt-biased eval as objective.** If you tell the user "Lc0 gives Black +0.30 here" without disclosing you set contempt=-15, that's misleading.
+- **Don't quote Lc0's contempt-biased eval as objective.** If you tell the user "Lc0 gives Black +0.30 here" without disclosing you set contempt=-30, that's misleading.
 - **Don't run cloud analysis just for casual questions.** `cloud_analyse` costs the user real money per second. If the question is "is 1.e4 or 1.d4 better?", the free `analyse` (single Stockfish, 2s) or `get_position_stats` (11.7M-game database) is enough.
 - **Don't ignore the disagreement.** When Stockfish and Lc0 diverge sharply, that's exactly when you should explain *why* to the user — not paper over it.

package/docs/pgn-authoring.md

@@ -23,7 +23,7 @@ Building (use these — one call for many ops):
 
 - **`apply_mutations(id, mutations[])`** — batch. This is the primary build tool. Send 100 mutations in one call → one load-parse-mutate-save cycle instead of 100. When you're writing a repertoire from scratch, EVERYTHING should go through this. Individual mutation tools are for surgical follow-up edits, not for bulk work.
 - **`add_line(id, parent_id, sans[])`** — a whole linear variation in one op. Cleaner than N `add_move` ops for straight lines. Overlapping prefixes with an existing branch **join** (same SAN from the same position IS the same move) — see below.
-- **`auto_evaluate(id, node_id?)`** — walk from a node and populate the persistent `ceoEval` (Stockfish + Lc0 numbers) on every descendant via cloud_analyse. **Does NOT set visible NAGs** — the numbers land in a hidden `[%ceo-eval]` tag so you can read them back later. NAG placement (`$1` `!`, `$14` `⩲`, `$16` `±`, `$18` `+−`, etc.) is your editorial call. Skip nodes that already have a stored eval by default.
+- **`auto_evaluate(id, node_id?)`** — walk from a node and populate the persistent `ceoEval` (Stockfish + Lc0 numbers) on every descendant via cloud_analyse. **Async job**: returns `{job_id, target_count, estimated_seconds}` immediately, does the work in the background. Poll with `auto_evaluate_status(job_id)` until `done:true`; cancel with `auto_evaluate_cancel(job_id)` if you change your mind (partial progress is checkpointed every 8 nodes so a cancel never loses more than a handful of evaluations). **Does NOT set visible NAGs** — the numbers land in a hidden `[%ceo-eval]` tag so you can read them back later. NAG placement (`$1` `!`, `$14` `⩲`, `$16` `±`, `$18` `+−`, etc.) is your editorial call. Skip nodes that already have a stored eval by default.
 
 Per-op mutation tools (single-op calls, use for edits after the bulk build):
 
@@ -42,8 +42,8 @@ All mutations **auto-save** with optimistic locking. Response includes the new `
 
 1. `read_prep_file` — see what's there. Every node has an `id` you'll pass to the mutation and engine/DB tools.
 2. `apply_mutations([...])` — one call with your whole intended build (a mix of `add_move` / `add_line` for structure, plus any `set_comment`/`set_annotations` you already know at author time, plus any `set_nags` where you already have a clear judgment — novelty `$146`, `!?` speculative sac, obvious `?` blunder in a sideline you're rejecting).
-3. `auto_evaluate(id)` — walk the tree and PERSIST engine numbers on every node. Does not touch visible NAGs. Cheap way to get every position's Stockfish + Lc0 read baked into the file for later reference.
-4. Re-read the file and add NAGs where they carry real signal (see NAG discipline below). Use individual mutation tools for surgical follow-ups (fix one comment, add one arrow, promote a specific variation, prune a branch).
+3. `auto_evaluate(id)` — spawns a background job that PERSISTS engine numbers on every node. Does not touch visible NAGs. Cheap way to get every position's Stockfish + Lc0 read baked into the file for later reference. Grab the returned `job_id` and either (a) poll `auto_evaluate_status(job_id)` every ~10-30s until done, or (b) fire and do useful work meanwhile (write more of the tree, walk the opponent's repertoire) and check back later — engine walk-time serialises on the per-combo semaphore, so it takes roughly `target_count × movetime_ms` in wall time.
+4. Once the job reports `done:true`, re-read the file and add NAGs where they carry real signal (see NAG discipline below). Use individual mutation tools for surgical follow-ups (fix one comment, add one arrow, promote a specific variation, prune a branch).
 
 The build-cost math: a 200-move file via individual `add_move` calls is 200 saves ≈ 100+ seconds of tool overhead. The same file via one `apply_mutations` call is one save ≈ 500ms. Use batch by default.
 
@@ -194,7 +194,7 @@ Engine numbers go into the NAG, not into prose. Convert the eval to the correct
 | `\|eval\| ≥ 1.3`          | `$18` (+−)              | `$19` (−+)              |
 | Sharp, hard to evaluate | `$13` (∞)               | `$13` (∞)               |
 
-**NAGs are editorial, not automatic.** `auto_evaluate` persists engine numbers on every node but does NOT set visible NAGs — because a repertoire full of 0.00 opening theory does not want a `$10` (=) glyph plastered on every move. That's noise, not signal. NAGs are your call: mark moves that carry a judgment a reader can't derive by looking at the board.
+**NAGs are editorial, not automatic.** `auto_evaluate` (and its `auto_evaluate_status` poll) persists engine numbers on every node but does NOT set visible NAGs — because a repertoire full of 0.00 opening theory does not want a `$10` (=) glyph plastered on every move. That's noise, not signal. NAGs are your call: mark moves that carry a judgment a reader can't derive by looking at the board.
 
 Where NAGs actually earn their place:
 
@@ -210,7 +210,7 @@ Where NAGs are noise: every `$10` "=" glyph on every equal position. If the whol
 
 When reading back a file, `node.ceoEval.nag` carries the threshold-derived NAG (`$10` / `$14` / `$16` / `$18` etc.) — treat it as a *suggestion*, not an automatic write. Promote it to a visible NAG only when a glyph on that move actually helps the reader.
 
-**Persisted evals travel with the file.** Every node with an eval gets `ceoEval: { sf: {cp: 25, depth: 32}, lc0: {cp: 30, depth: 18}, nag: "$14" }` on subsequent `read_prep_file` calls. Stored as `[%ceo-eval sf=+0.25/32 lc0=+0.30/18 nag=$14]` inside the PGN comment (an escape tag the app hides from the board view, just like [%cal] / [%csl]). So a re-read after auto_evaluate gives you every position's number without re-running cloud_analyse. Query tools (get_position_stats, get_player_preparation, prep_snapshot) also auto-attach a live `eval` at the request position when a cloud engine is running.
+**Persisted evals travel with the file.** Every node with an eval gets `ceoEval: { sf: {cp: 25, depth: 32}, lc0: {cp: 30, depth: 18}, nag: "$14" }` on subsequent `read_prep_file` calls. Stored as `[%ceo-eval sf=+0.25/32 lc0=+0.30/18 nag=$14]` inside the PGN comment (an escape tag the app hides from the board view, just like [%cal] / [%csl]). So a re-read after auto_evaluate gives you every position's number without re-running cloud_analyse. Query tools (get_position_stats, get_prep_position, prep_snapshot) also auto-attach a live `eval` at the request position when a cloud engine is running.
 
 **Engine numbers in prose: brief only.** If you must reference a number, keep it compact:
 
@@ -221,12 +221,14 @@ When reading back a file, `node.ceoEval.nag` carries the threshold-derived NAG (
 
 **Only quote engine numbers for positions you actually called `cloud_analyse` on** (or that carry a `ceoEval` from an earlier auto_evaluate, or an auto-attached `.eval` from a query tool). Do NOT infer an eval for a parent position from its children and then write "both engines 0.00" on the parent — that reads as a measurement but is a guess. If the position wasn't analysed, either analyse it or omit the number: prose can say "both continuations run to 0.00, so this looks balanced" without claiming an eval that wasn't taken.
 
-**When you set `contempt`, attribute it to Lc0 only.** Contempt affects Lc0 exclusively — Stockfish always analyses objectively. So don't write "both engines at contempt −15" — that misleads the reader into thinking SF was biased too. Correct phrasings:
+**When you set `contempt`, attribute it to Lc0 only.** Contempt affects Lc0 exclusively — Stockfish always analyses objectively. So don't write "both engines at contempt −30" — that misleads the reader into thinking SF was biased too. Correct phrasings:
 
-- `{Lc0 (contempt −15): 0.00 — even biased toward Black, still balanced. SF objective: 0.00.}`
-- `{With Lc0 nudged toward Black (contempt −15) it still picks Qg6 at 0.00; SF's objective read also 0.00.}`
+- `{Lc0 (contempt −30): 0.00 — even biased toward Black, still balanced. SF objective: 0.00.}`
+- `{With Lc0 nudged toward Black (contempt −30) it still picks Qg6 at 0.00; SF's objective read also 0.00.}`
 
-If you only quote the Lc0 number, disclose the bias in the same sentence — `{Lc0 gives Black +0.30}` with an undisclosed `contempt=-15` is a false objectivity claim.
+If you only quote the Lc0 number, disclose the bias in the same sentence — `{Lc0 gives Black +0.30}` with an undisclosed `contempt=-30` is a false objectivity claim.
+
+Contempt scale is signed 0-100 (same as the web UI's ContemptStrength slider). Typical: `±10-20` a light nudge, `±30-60` real fighting play, `±80-100` maximum steer.
 
 ### Before you write any commentary: describe_position
 

package/docs/prep-strategy.md

@@ -4,20 +4,20 @@ Opening prep is not a monologue with the position-stats and player-prep endpoint
 
 ## Grounding: cite tools, don't fill gaps with chess prose
 
-Every recommendation you make must trace back to an actual tool call in this session — engine output from `cloud_analyse` / `analyse` for evaluations and lines, `get_player_preparation` / `get_position_stats` for statistics, `get_player_profile` / `get_head_to_head` for style and history. **Compute is cheap.** When you don't have the data to justify a claim, run the tool — do not paper over the gap with generic chess wisdom you didn't verify.
+Every recommendation you make must trace back to an actual tool call in this session — engine output from `cloud_analyse` for evaluations and lines, `prepare_opponent` + `get_prep_position` for opponent statistics, `get_position_stats` for the general database, `get_player_profile` / `get_head_to_head` for style and history. **Compute is cheap.** When you don't have the data to justify a claim, run the tool — do not paper over the gap with generic chess wisdom you didn't verify.
 
 **Concrete failure modes to catch yourself doing:**
 
 - "This is a good line because Black gets the two bishops." → Did Lc0 or Stockfish score it that way? If not, drop the claim.
-- "Your opponent hates isolated queen pawn positions." → Did you actually look at their IQP games in `get_player_preparation`? Or is this a training-data pattern?
+- "Your opponent hates isolated queen pawn positions." → Did you actually look at their IQP games via a `prepare_opponent` session? Or is this a training-data pattern?
 - "The Petroff is a solid choice here." → Did you check the opponent's score as White vs the Petroff, or against Black openings in general? If not, drop it.
 - "Aim for a Catalan setup, they historically struggle there." → Point at concrete games where they lost in Catalan structures. If you can't, don't say it.
-- Inventing move sequences that "look like typical prep" without walking the actual tree via `get_player_preparation` / `prep_snapshot`.
+- Inventing move sequences that "look like typical prep" without walking the actual tree via `get_prep_position` / `prep_snapshot`.
 - Asserting an opponent's style ("sharp tactician", "endgame grinder") without pointing at their profile data or specific games.
 
 The failure mode is *authoritative-sounding recipe = 30% real tool output + 70% chess-book filler*. The user cannot tell which is which; from their side it all looks like analysis. That's worse than saying "I don't have data on this yet — should I run X?"
 
-**Do this instead:** cite the specific numbers ("opponent scores 32% as White vs the Sveshnikov over 47 games, 2023-2025"), the tool that produced them ("via `get_player_preparation`"), and reason from there. If the reasoning wants to extend beyond what the data supports, either run more tools or flag it as your read, not the data's.
+**Do this instead:** cite the specific numbers ("opponent scores 32% as White vs the Sveshnikov over 47 games, 2023-2025"), the tool that produced them ("via a `prepare_opponent` session filtered to classical since 2024"), and reason from there. If the reasoning wants to extend beyond what the data supports, either run more tools or flag it as your read, not the data's.
 
 ## Numbers are inputs, not verdicts
 
@@ -27,6 +27,58 @@ The move statistics endpoints return win %, game counts, and (in the big DB) a `
 - **Score doesn't automatically indicate a level gap.** A 60% variation isn't necessarily "stronger players crushing weaker ones." Look at the per-move `avgWhite` / `avgBlack` fields (returned on every move statistic) before drawing conclusions about who is playing whom.
 - **Don't recommend the higher-percentage move just because it's higher.** If 1.b3 scores 60% and 1.d4 scores 50% against a given opponent, that is *not* on its own a case for playing 1.b3 — style, prep depth, transposition risk, and the practical questions below all matter more.
 
+## Which DB source: signal vs population
+
+Two shards on `get_position_stats`, answering different questions:
+
+- **`gm-classical`** (default): pre-aggregated GM classical games (both players ~2500+, real thinking time). Every move is signal, no noise. Sample sizes are smaller. Answers: *what do good players actually play here, and how well does each option score at that level?*
+- **`main`**: the full 11.7M-game database. Wider coverage, cheaper positions included (blitz, weak opponents, blunder-fests). Noisier. Answers: *has this position/move been reached at all, and by whom?*
+
+They're not either-or. Reasonable to hit both on the same position for different questions:
+
+- **What GMs play here** → `gm-classical`. Even a small count (5-10 games at avgRating 2600) is often the honest answer for a specific tabiya — that's just how many GMs have gone there. Don't dismiss small numbers if the rating context supports them.
+- **Does anyone play this at all** → `main`. Especially useful for a move you're considering that hasn't appeared in `gm-classical`. Zero in the GM DB doesn't automatically mean bad — it might just mean unfashionable. Check `main`: if it has some volume at reasonable avgRating (~2200+), the move has real support even without top-level play; if it's only 1400-rated games or bots, it doesn't.
+- **Sanity-checking a candidate** → both. If a move you're considering shows 3 games in `gm-classical` but 800 in `main` at avgRating 2100, that's a coherent picture (unfashionable at the very top but played by strong players); if `main` shows the same 3 games and nothing else, the move is genuinely rare and you're pioneering.
+
+When you do read a `main` result, always eyeball `avgRating` per move before quoting the win%. A 60% score across 200 games at avgRating 1400 is not a recommendation — it's a trap that catches beginners. The same 60% across 200 games at avgRating 2400 is a real finding.
+
+Cross-reference tip: if `main` shows a specific move dominating that `gm-classical` doesn't touch, look at *who* — correspondence engines, blitz-only players, and bot accounts skew the `main` totals. A move with 5000 games in `main` at avgRating 1900 and zero in `gm-classical` is probably not something to recommend as GM prep.
+
+## Which prep source: match data density to what you're preparing
+
+`prepare_opponent` accepts fide, chesscom, lichess sources — each with per-source colour, date-range, time-control filters. Which sources to combine depends on how much data the opponent actually has and what specific question you're answering:
+
+- **Well-known player, well-known question** ("what does Firouzja play against 1.e4?"): FIDE, `time_control: "classical"`, `start_month` = 12–24 months ago. Cleanest signal, big enough sample. Don't dilute with online.
+- **Well-known player, sideline question** ("what would he play in this obscure 20-ply position?"): FIDE all-time-controls first — classical is unlikely to have games in a rare position. If still nothing, add rapid; add online only if you must.
+- **Junior / sub-2400 / comeback player**: FIDE classical alone might give you 5 games. Add FIDE rapid + chesscom + lichess (all filtered to the last 12 months). Signal density improves, but recognize online games are a mixed signal — see next section.
+- **Multiple accounts / handles**: pass them all as sources in one call — `[{type:"fide",fide_id:X}, {type:"chesscom",username:"..."}, {type:"lichess",username:"..."}]`. Same session, more games, no rebuild, all combined into one filtered corpus.
+
+The trade-off is always the same: signal quality vs data density. When density is high, prefer quality; when density is low, take what you can get and lower your confidence in the read explicitly ("only 12 games at this branch — the 66% is noisier than the 55% we saw at move 2").
+
+## Reading a chess.com / lichess profile: three shapes
+
+Online games are a *mixed* signal. Before treating chesscom/lichess data the same weight as FIDE, spot which of these three profiles the opponent fits — misclassifying is worse than not using online data at all.
+
+1. **Consistent** — plays roughly the same repertoire online and OTB. Gold. Suddenly you have thousands of extra games to see reactions against sidelines and to see where he makes mistakes in the early middlegame under time pressure. Weight online data almost the same as classical FIDE.
+
+2. **Eclectic** — online they play everything under the sun; OTB they have a real narrow repertoire. Still usable, but for a *different* question. Online tells you: (a) which openings he has *seen* and roughly *knows*, (b) which moves he *actually recalls under pressure*, (c) where he makes early mistakes. Online does NOT reliably tell you what he'll play in the game.
+
+3. **Split personality** — online repertoire genuinely differs from OTB. Classic example: a 1.e4 Ruy Lopez player over the board who plays only the King's Gambit on lichess blitz because it's fun. Online is the playground; OTB is serious. **Recognize this and discount the online games entirely** for opening-choice prediction — he's not playing his lichess repertoire in a rated classical game. Online may still surface middlegame tendencies, but "what will he play" belongs to FIDE only.
+
+How to distinguish, quickly: compare the top openings from `get_player_profile` (FIDE-based) against the moves he plays from the starting position in an online-only `prepare_opponent` session. High overlap → shape 1. Modest overlap with FIDE openings as a subset of online → shape 2. Different openings entirely → shape 3.
+
+Write the profile-shape into the prep file's overview comment as soon as you decide it — future re-reads (and the user) benefit from knowing you already made the call.
+
+## Reversed colours as a scarcity trick
+
+For a rare position where the opponent has 0–2 games as their side, it's often worth also checking what they've done in the same position from the OTHER colour. This doesn't tell you what they'd play — it tells you what they've SEEN. Useful when you have no direct data:
+
+- **Surprise calculus**: "he's had this position from the White side against people playing it against him — so seeing it from the Black side isn't a real surprise, he knows the ideas."
+- **Structural familiarity**: "he's played this pawn structure before, just from the other colour — his over-the-board understanding will carry over."
+- **Cuts both ways**: if the opponent has played it a lot with the OTHER colour AND had good results, assume he knows both sides thoroughly.
+
+Do this by dropping the `color` filter on `prepare_opponent`, or making a second session with the opposite colour — then compare game counts. When density is scarce, information from the "wrong" colour is worth more than no information at all. Just be honest about what it is: knowledge, not prediction.
+
 ## Prep is symmetric — both sides know the same things
 
 The single biggest LLM error in prep is treating it like writing a book: "here's what you should play against this opponent's weakness." A real chess opponent:
@@ -41,7 +93,7 @@ Every recommendation should be filtered through: "does this survive the fact tha
 
 The opponent's last 12-24 months matter far more than a 10-year career average. Repertoires evolve — a lifelong Najdorf player might have quietly become a Petroff player last year, and their old career stats will lie to you if you skim.
 
-**Related product note (2026-07-23):** the `get_player_preparation` endpoint (compact / LLM view) deliberately strips the per-move `fashionScore` field. At the individual-player level, fashion is trailing noise — the opponent's opening trend is already captured in game dates. `fashionScore` stays on the general-DB endpoint (`get_position_stats`), where it's genuinely useful: it's what the whole top field is playing this month.
+**Related product note:** `get_prep_position` (from a `prepare_opponent` session) deliberately strips the per-move `fashionScore` field. At the individual-player level, fashion is trailing noise — the opponent's opening trend is already captured in game dates. `fashionScore` stays on the general-DB endpoint (`get_position_stats`), where it's genuinely useful: it's what the whole top field is playing this month.
 
 ## Prep is a tree, not a line
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.31.2",
+  "version": "0.34.0",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {