@chessceo/mcp 0.26.0 → 0.30.2

package/dist/index.js

@@ -14,6 +14,7 @@ import { dirname, join } from "node:path";
 import { Chess } from "chess.js";
 import { parsePGN } from "./pgn/parser.js";
 import { exportPGN } from "./pgn/exporter.js";
+import { describePosition } from "./pgn/describe.js";
 import { addMove, deleteSubtree, MutationError, promoteVariation, setAnnotations, setCeoEval, setComment, setNags, setTag, } from "./pgn/mutations.js";
 import { PathError } from "./pgn/paths.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -192,7 +193,7 @@ const TOOLS = [
             "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 `hotness` — at the individual level it's trailing noise. The general DB endpoint keeps it (there it's fashion signal).\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.",
@@ -230,8 +231,12 @@ const TOOLS = [
     },
     {
         name: "get_position_stats",
-        description: "Move statistics from all 11.7M+ indexed games at a given position — game counts, win percentages, top continuations. Answers 'from position P, how often does White play 4. O-O vs 4. d3, and which scores better'.\n\n" +
-            "AUTO-EVAL: if a cloud combo instance is running, the response includes `.eval` with a compact Stockfish + Lc0 read (top move + score + PV) and the corresponding NAG. Do NOT fire a separate cloud_analyse for the same FEN — the eval is right there.",
+        description: "Move statistics + example games at a position. Answers 'how often is 4.O-O vs 4.d3 played here and which scores better'.\n\n" +
+            "SOURCE (default: `gm-classical`) selects a pre-aggregated database shard:\n" +
+            "- `gm-classical` — GM classical games (both players ≥2500, real thinking-time). BEST for opening prep — every move is signal, avgElo ~2600 across all listed moves.\n" +
+            "- `main` — the whole 11.7M-game DB. Widest coverage but noisiest (includes 1000-Elo blunder-fests in the move stats). Use as fallback when gm-classical's totalCount is too small to be informative.\n\n" +
+            "Game movetext is trimmed to the moves AFTER the queried position (using each game's plyNumber). Saves ~70% of the bytes vs full movetext.\n\n" +
+            "AUTO-EVAL: if a cloud combo instance is running, the response includes `.eval` with a compact Stockfish + Lc0 read and the corresponding NAG. Do NOT fire cloud_analyse separately for the same FEN.",
         inputSchema: {
             type: "object",
             properties: {
@@ -251,8 +256,27 @@ const TOOLS = [
                     type: "integer",
                     minimum: 1,
                     maximum: 50,
-                    description: "Number of top continuations to return.",
+                    description: "Number of example games to return (default 10).",
                 },
+                source: {
+                    type: "string",
+                    enum: ["gm-classical", "main"],
+                    description: "Which database shard to query. Default `gm-classical`. Switch to `main` only when gm-classical's totalCount is too low.",
+                },
+            },
+        },
+    },
+    {
+        name: "describe_position",
+        description: "Structured facts about a chess position: piece placements per colour (SAN-style letters), material balance in pawn units, list of every contested piece (attackers + defenders), hanging pieces, checkers if in check, castling rights, en passant square, side to move, and the full list of LEGAL MOVES for the side to move. Pure computation — no engine, ~1 ms per call.\n\n" +
+            "USE THIS BEFORE COMMENTING ON A POSITION. LLMs are not reliable at reading FEN strings — you'll misplace pieces or invent captures. This tool gives you the same board state a human sees.\n\n" +
+            "ALSO USE THIS if `add_move` rejects an illegal SAN — the `.legalMoves` array shows exactly what's playable from that position.\n\n" +
+            "Position input is flexible — pass `fen`, or `moves` from startpos, or `fen + moves` to walk from there.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fen: { type: "string", description: "Starting position as FEN (defaults to startpos)." },
+                moves: { type: "string", description: "Optional SAN moves to apply on top of `fen`." },
             },
         },
     },
@@ -620,15 +644,16 @@ const TOOLS = [
     },
     {
         name: "auto_evaluate",
-        description: "Walk the tree from `path` (default `[]` = whole file) and auto-assign NAGs to every node based on the Stockfish eval from cloud_analyse. Uses the standard eval → NAG thresholds (|eval|<0.25 → $10, <0.6 → $14/$15, <1.3 → $16/$17, ≥1.3 → $18/$19). Requires a running cloud combo instance.\n\n" +
-            "This is the automate-the-boring-part tool. Instead of hand-annotating each move with a NAG, you build the tree via apply_mutations (no NAGs needed), then call auto_evaluate once and every node gets the right glyph.\n\n" +
-            "Costs real money — hits cloud_analyse per node. A 200-node tree at 1.5s/node = ~5 min of engine time. Use `only_missing=true` (default) to skip nodes that already have a NAG on subsequent runs. Runs 4 evaluations in parallel to save wall time.",
+        description: "Walk the tree from `path` (default `[]` = whole file) and populate the persistent `ceoEval` (Stockfish + Lc0 numbers) on every node 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 (novelty, sharp choice, real mistake, decisive advantage).\n\n" +
+            "On re-read every node with a stored eval carries `ceoEval: { sf: {cp, depth}, lc0: {cp, depth} }` — the numbers travel with the file. 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.",
         inputSchema: {
             type: "object",
             properties: {
                 id: { type: "string" },
                 path: { type: "array", items: { type: "integer", minimum: 0 }, description: "Subtree root (default = whole file)." },
-                only_missing: { type: "boolean", description: "Skip nodes that already carry a NAG (default true)." },
+                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" },
             },
@@ -911,8 +936,6 @@ async function autoEvaluate(args) {
     const batchMutations = [];
     for (const s of stored) {
         batchMutations.push({ op: "set_ceo_eval", path: s.path, ceoEval: s.ev });
-        if (s.ev.nag)
-            batchMutations.push({ op: "set_nags", path: s.path, nags: [s.ev.nag] });
     }
     const saveResult = await applyBatchMutations({ id, mutations: batchMutations, expected_version: g.version });
     const sr = saveResult;
@@ -1038,6 +1061,103 @@ async function applyMutation(args, mutator) {
         version: savedRow.version,
     };
 }
+// Strip cruft the LLM doesn't need from the DB-position response.
+// Called AFTER trimGamesMovetext so plyNumber survives long enough to
+// slice each game's movetext. Also renames the `transpositions` field
+// to something the LLM can parse without knowing chess-DB jargon.
+function stripPositionResponse(r) {
+    if (!r || typeof r !== "object")
+        return;
+    const t = r;
+    delete t.hash; // internal zobrist string
+    delete t.source; // internal "database" marker; we overwrite with our own .source
+    delete t.totalGames; // duplicates statistics.totalCount often; hasMore covers pagination
+    if (Array.isArray(t.moves)) {
+        for (const m of t.moves) {
+            if (typeof m.transpositions === "number") {
+                m.reachedViaTransposition = m.transpositions;
+                delete m.transpositions;
+            }
+            // Backend calls it "hotness" — a 0-100 time-decayed popularity score
+            // (recent + played often = high). Rename to something an LLM can read
+            // without guessing it means "on a winning streak".
+            if (typeof m.hotness === "number") {
+                m.fashionScore = m.hotness;
+                delete m.hotness;
+            }
+        }
+    }
+    if (Array.isArray(t.games)) {
+        for (const g of t.games) {
+            delete g.gameId;
+            delete g.whiteTitle;
+            delete g.blackTitle;
+            delete g.whiteTeam;
+            delete g.blackTeam;
+            delete g.round;
+            delete g.plyNumber;
+            delete g.relevance;
+            delete g.site;
+            delete g.ply;
+        }
+    }
+}
+// Trim every game's `moves` field to just the plies AFTER the queried
+// position, using each game's `plyNumber`. Massive token save — a game
+// 80 plies long queried at ply 12 drops to ~68 plies of movetext. Ports
+// the frontend's GamesTable.getMoveDisplay() trim logic.
+function trimGamesMovetext(response) {
+    if (!response || typeof response !== "object")
+        return;
+    const r = response;
+    if (!Array.isArray(r.games))
+        return;
+    for (const g of r.games) {
+        if (typeof g.moves === "string" && typeof g.plyNumber === "number" && g.plyNumber > 0) {
+            g.moves = trimMovesToPly(g.moves, g.plyNumber);
+        }
+    }
+}
+function trimMovesToPly(moves, plyNumber) {
+    // Split into plain SAN tokens, dropping standalone move-number tokens
+    // ("1.", "12...") and any glued number prefix on a SAN token ("1.e4").
+    // Result markers ("*", "1-0", "0-1", "1/2-1/2") are stripped so they
+    // don't get counted as plies.
+    const tokens = [];
+    for (const chunk of moves.split(/\s+/)) {
+        if (!chunk)
+            continue;
+        const cleaned = chunk.replace(/^\d+\.+/, "");
+        if (!cleaned)
+            continue;
+        if (/^(1-0|0-1|1\/2-1\/2|\*)$/.test(cleaned))
+            continue;
+        tokens.push(cleaned);
+    }
+    const remaining = tokens.slice(plyNumber);
+    if (remaining.length === 0)
+        return "";
+    // Reconstruct with move numbering. First move gets "N..." if it's
+    // Black's move (starting the slice mid-move-pair), so the reader knows
+    // moves were dropped.
+    const out = [];
+    let ply = plyNumber;
+    for (let i = 0; i < remaining.length; i++) {
+        const san = remaining[i];
+        const moveNumber = Math.floor(ply / 2) + 1;
+        if (ply % 2 === 0) {
+            out.push(`${moveNumber}. ${san}`);
+        }
+        else if (i === 0) {
+            out.push(`${moveNumber}... ${san}`);
+        }
+        else {
+            out.push(san);
+        }
+        ply++;
+    }
+    return out.join(" ");
+}
 // Rewrite availableMoves[].move UCI → SAN. The prep + position-stats
 // endpoints return moves in UCI on the wire — same LLM-readability
 // concern as engine PVs, and the same wrapper-only fix. Passes the
@@ -1154,25 +1274,38 @@ async function callToolInner(name, args) {
                 fetchCompactEval(effectiveFen),
             ]);
             const converted = convertAvailableMovesToSAN(raw, effectiveFen);
-            if (ev && converted && typeof converted === "object")
-                converted.eval = ev;
+            if (converted && typeof converted === "object") {
+                trimGamesMovetext(converted);
+                stripPositionResponse(converted);
+                if (ev)
+                    converted.eval = ev;
+            }
             return converted;
         }
         case "get_position_stats": {
             const fen = resolveFenFromArgs(args);
+            const rawSource = typeof args.source === "string" ? args.source : "gm-classical";
+            const source = rawSource === "main" ? "main" : "gm-classical";
             const [raw, ev] = await Promise.all([
-                get("/api/chess/database/main", {
+                get(`/api/chess/database/${source}`, {
                     fen,
-                    limit: typeof args.limit === "number" ? args.limit : 20,
+                    limit: typeof args.limit === "number" ? args.limit : 10,
                     sort: "relevance",
                 }),
                 fetchCompactEval(fen),
             ]);
             const converted = convertAvailableMovesToSAN(raw, fen);
-            if (ev && converted && typeof converted === "object")
-                converted.eval = ev;
+            if (converted && typeof converted === "object") {
+                trimGamesMovetext(converted);
+                stripPositionResponse(converted);
+                converted.source = source;
+                if (ev)
+                    converted.eval = ev;
+            }
             return converted;
         }
+        case "describe_position":
+            return describePosition(resolveFenFromArgs(args));
         case "predict_human_move": {
             const fen = resolveFenFromArgs(args);
             const qs = new URLSearchParams();

package/dist/pgn/describe.js

@@ -0,0 +1,221 @@
+// describe_position — structured facts about a position that LLMs can't
+// reliably read out of a FEN string on their own. Pure computation
+// (chessops); no engine needed.
+//
+// Output covers piece placements, material balance in pawn units,
+// attackers/defenders on every piece that is currently contested, a
+// hanging list (attacked and undefended), checkers if in check, and
+// castling / ep state. NOT covered: pins, discovered attacks, tactical
+// patterns — those need the engine and are already available via
+// cloud_analyse.
+import { parseFen } from "chessops/fen";
+import { Chess } from "chessops/chess";
+import { attacks } from "chessops/attacks";
+import { makeSquare, squareRank } from "chessops/util";
+import { makeSan } from "chessops/san";
+const ROLE_LETTER = {
+    pawn: "", knight: "N", bishop: "B", rook: "R", queen: "Q", king: "K",
+};
+// SAN convention: pawn is empty prefix. For inventory listings we use "P"
+// so counts are readable.
+const ROLE_LETTER_INV = {
+    pawn: "P", knight: "N", bishop: "B", rook: "R", queen: "Q", king: "K",
+};
+const ROLE_VALUE = {
+    pawn: 1, knight: 3, bishop: 3, rook: 5, queen: 9, king: 0,
+};
+function pieceSAN(piece, sq) {
+    return `${ROLE_LETTER[piece.role]}${makeSquare(sq)}`;
+}
+export function describePosition(fen) {
+    const setup = parseFen(fen);
+    if (setup.isErr)
+        throw new Error(`bad fen: ${setup.error}`);
+    const posResult = Chess.fromSetup(setup.value);
+    if (posResult.isErr)
+        throw new Error(`bad position: ${posResult.error}`);
+    const pos = posResult.value;
+    const board = pos.board;
+    const whitePieces = [];
+    const blackPieces = [];
+    const materialW = { P: 0, N: 0, B: 0, R: 0, Q: 0, K: 0 };
+    const materialB = { P: 0, N: 0, B: 0, R: 0, Q: 0, K: 0 };
+    for (const [sq, piece] of board) {
+        const invLetter = ROLE_LETTER_INV[piece.role];
+        const entry = { piece: invLetter, square: makeSquare(sq) };
+        if (piece.color === "white") {
+            whitePieces.push(entry);
+            materialW[invLetter]++;
+        }
+        else {
+            blackPieces.push(entry);
+            materialB[invLetter]++;
+        }
+    }
+    whitePieces.sort(pieceSortKey);
+    blackPieces.sort(pieceSortKey);
+    const wValue = pieceValueSum(materialW);
+    const bValue = pieceValueSum(materialB);
+    const diff = wValue - bValue;
+    const summary = diff === 0 ? `even (both ${wValue})` :
+        diff > 0 ? `white +${diff} (${wValue} vs ${bValue})` :
+            `black +${-diff} (${wValue} vs ${bValue})`;
+    // Contested + hanging computation: for every piece, find who attacks
+    // it and who defends it. attacks() returns the squares a piece
+    // controls given the occupied board — we invert it into "attackers-of"
+    // by iterating all pieces once and testing membership.
+    const contested = [];
+    const hangingWhite = [];
+    const hangingBlack = [];
+    for (const [sq, piece] of board) {
+        const both = attackersOf(pos, sq);
+        const oppSide = piece.color === "white" ? "black" : "white";
+        const attackers = both[oppSide];
+        const defenders = both[piece.color];
+        if (attackers.length === 0)
+            continue;
+        const targetName = pieceSAN(piece, sq);
+        contested.push({
+            target: targetName,
+            color: piece.color,
+            attackers: attackers.map(a => pieceSANFromBoard(board, a)),
+            defenders: defenders.map(d => pieceSANFromBoard(board, d)),
+        });
+        if (defenders.length === 0) {
+            if (piece.color === "white")
+                hangingWhite.push(targetName);
+            else
+                hangingBlack.push(targetName);
+        }
+    }
+    // Order contested by target square for stable output the LLM can
+    // scan.
+    contested.sort((a, b) => a.target.slice(-2).localeCompare(b.target.slice(-2)));
+    // Castling rights encoded in the standard FEN letters (KQkq).
+    const castlingW = castlingLetters(pos, "white");
+    const castlingB = castlingLetters(pos, "black");
+    const checkers = [];
+    const ctx = pos.ctx();
+    for (const sq of ctx.checkers)
+        checkers.push(pieceSANFromBoard(board, sq));
+    const legalMoves = generateLegalMoves(pos);
+    return {
+        fen,
+        sideToMove: pos.turn,
+        inCheck: pos.isCheck(),
+        checkers,
+        material: {
+            white: materialW,
+            black: materialB,
+            diff,
+            summary,
+        },
+        pieces: { white: whitePieces, black: blackPieces },
+        contested,
+        hanging: { white: hangingWhite, black: hangingBlack },
+        castling: { white: castlingW, black: castlingB },
+        epSquare: typeof pos.epSquare === "number" ? makeSquare(pos.epSquare) : null,
+        legalMoves,
+    };
+}
+// All legal moves for the side to move, in SAN. Sorted for stable output.
+// Handles promotion by expanding each pawn-promotion destination into
+// the four promotion pieces (=Q, =R, =B, =N).
+function generateLegalMoves(pos) {
+    const out = [];
+    for (const [from, piece] of pos.board) {
+        if (piece.color !== pos.turn)
+            continue;
+        const dests = pos.dests(from);
+        for (const to of dests) {
+            const isPromotion = piece.role === "pawn" &&
+                ((piece.color === "white" && squareRank(to) === 7) ||
+                    (piece.color === "black" && squareRank(to) === 0));
+            if (isPromotion) {
+                for (const promo of ["queen", "rook", "bishop", "knight"]) {
+                    const san = makeSan(pos, { from, to, promotion: promo });
+                    if (san)
+                        out.push(san);
+                }
+            }
+            else {
+                const san = makeSan(pos, { from, to });
+                if (san)
+                    out.push(san);
+            }
+        }
+    }
+    return out.sort();
+}
+// Attackers-of a square, split by colour. A piece cannot attack its own
+// square, so we skip the target index. The `occupied` for sliding
+// pieces is the whole board minus nothing — chessops's `attacks()`
+// takes care of blockers.
+function attackersOf(pos, target) {
+    const white = [];
+    const black = [];
+    for (const [sq, piece] of pos.board) {
+        if (sq === target)
+            continue;
+        const set = attacks(piece, sq, pos.board.occupied);
+        if (set.has(target)) {
+            if (piece.color === "white")
+                white.push(sq);
+            else
+                black.push(sq);
+        }
+    }
+    return { white, black };
+}
+function pieceSANFromBoard(board, sq) {
+    const piece = board.get(sq);
+    if (!piece)
+        return makeSquare(sq);
+    return pieceSAN(piece, sq);
+}
+// Sort: kings first, then queens, rooks, bishops, knights, pawns; within
+// each type, by rank descending then file ascending. Matches the visual
+// scan a human does.
+const ROLE_ORDER = ["king", "queen", "rook", "bishop", "knight", "pawn"];
+function pieceSortKey(a, b) {
+    const roleA = roleOfEntry(a);
+    const roleB = roleOfEntry(b);
+    const orderA = ROLE_ORDER.indexOf(roleA);
+    const orderB = ROLE_ORDER.indexOf(roleB);
+    if (orderA !== orderB)
+        return orderA - orderB;
+    return a.square.localeCompare(b.square);
+}
+function roleOfEntry(e) {
+    switch (e.piece) {
+        case "K": return "king";
+        case "Q": return "queen";
+        case "R": return "rook";
+        case "B": return "bishop";
+        case "N": return "knight";
+        default: return "pawn";
+    }
+}
+function pieceValueSum(m) {
+    return m.P * ROLE_VALUE.pawn +
+        m.N * ROLE_VALUE.knight +
+        m.B * ROLE_VALUE.bishop +
+        m.R * ROLE_VALUE.rook +
+        m.Q * ROLE_VALUE.queen;
+}
+// Convert chessops castling representation to the standard FEN-letter
+// form for the given color: "K" (kingside), "Q" (queenside), "KQ",
+// or "" if none remain.
+function castlingLetters(pos, color) {
+    let out = "";
+    const castles = pos.castles;
+    // castles.rooksSideOf(color, 'a') and .rooksSideOf(color, 'h') return
+    // the rook square or undefined per side. Fall back to inspecting the
+    // stored castling squares — chessops's public API varies by version.
+    const rooks = castles.rook;
+    if (rooks?.[color]?.h !== undefined)
+        out += color === "white" ? "K" : "k";
+    if (rooks?.[color]?.a !== undefined)
+        out += color === "white" ? "Q" : "q";
+    return out;
+}

package/dist/pgn/mutations.js

@@ -144,7 +144,7 @@ function validateSan(fen, san) {
     const board = pos.value;
     const move = parseSan(board, san);
     if (!move) {
-        throw new MutationError(`illegal SAN "${san}" at fen "${fen}" — check the position (side to move, piece disambiguation, promotion piece) and re-check the path.`);
+        throw new MutationError(`illegal SAN "${san}" at fen "${fen}". Call describe_position on this fen to see the full list of legal moves.`);
     }
     return move;
 }

package/docs/pgn-authoring.md

@@ -23,7 +23,7 @@ Reading:
 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.
-- **`auto_evaluate(id, path?)`** — walk the tree from `path` and auto-assign the right NAG to every node by running cloud_analyse on each position. Standard threshold table (below). Costs real engine time but frees you from hand-annotating evals. Skip nodes that already have a NAG by default.
+- **`auto_evaluate(id, path?)`** — walk the tree from `path` and populate the persistent `ceoEval` (Stockfish + Lc0 numbers) on every node by running cloud_analyse on each position. **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, not an automatic mapping — see the section on NAG discipline below. Skip nodes that already have a stored eval by default.
 
 Per-op mutation tools (single-op calls, use for edits after the bulk build):
 
@@ -40,9 +40,9 @@ All mutations **auto-save** with optimistic locking. Response includes the new `
 ## Typical build order
 
 1. `read_prep_file` — see what's there.
-2. `apply_mutations([...])` — one call with your whole intended build (all `add_move` for the moves and variations, plus any `set_comment`/`set_annotations` you already know at author time). Skip `set_nags` — auto_evaluate handles that.
-3. `auto_evaluate(id)` — walk the tree, get engine evals, assign NAGs. One shot.
-4. Individual mutation tools ONLY for surgical follow-ups (fix one comment, add one arrow, promote a specific variation, prune a branch).
+2. `apply_mutations([...])` — one call with your whole intended build (all `add_move` for the moves and variations, 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).
 
 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.
 
@@ -122,7 +122,21 @@ 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` (∞)               |
 
-**Prefer auto_evaluate for the NAG.** Don't hand-write NAGs when building — call `auto_evaluate(id)` after your build and it assigns the right glyph to every node from actual engine analysis. Manual `set_nags` is for overrides (mark a novelty with $146, flag a `$5 !?` piece sac).
+**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.
+
+Where NAGs actually earn their place:
+
+- **`$146` (novelty)** — a move that hasn't appeared at this level. Only set if you actually know this (e.g. saw 0 games via `get_position_stats`).
+- **`$5 !?` (interesting/speculative)** — a committal move you're recommending anyway (a piece sac, a positional pawn concession).
+- **`$1 !` / `$3 !!`** — objectively good moves the reader might miss.
+- **`$2 ?` / `$4 ??` / `$6 ?!`** — mistakes in a sideline you're showing to reject.
+- **`$14/$15` (⩲/⩱)** and **`$16/$17` (±/∓)** — assessments on positions where the direction of pressure matters for the plan you're teaching. Skip these on 0.00 theory nodes.
+- **`$18/$19` (+−/−+)** — decisive advantages, use where the reader should recognise the position is winning.
+- **`$44` (compensation)** on a genuine gambit; **`$13` (∞)** on a genuinely sharp/unclear position that engines don't resolve.
+
+Where NAGs are noise: every `$10` "=" glyph on every equal position. If the whole tree is 0.00, that's the *default state* — leave it unmarked and the reader understands.
+
+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.
 
@@ -133,6 +147,27 @@ Engine numbers go into the NAG, not into prose. Convert the eval to the correct
 
 **Don't name the engine unless it adds signal.** "SF: +0.15" for a routine position is noise. Name it when there's a mismatch worth flagging: `{Human predictor gives Black 47% win despite the -0.35 objective eval — Elo gap does the work.}`
 
+**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:
+
+- `{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.}`
+
+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.
+
+### Before you write any commentary: describe_position
+
+LLMs are not reliable at reading FEN strings — you'll swap files/ranks, invent captures, miscount pieces. Before you write a comment describing what's happening in a position, call `describe_position(fen)`. It's pure computation (no engine, ~1ms) and returns the same board state a human sees:
+
+- All piece placements per colour (SAN-style: `Nf3`, `Bg7`, `e4`)
+- Material balance in pawn units (`"white +1 (39 vs 38)"`)
+- Every contested piece: attackers + defenders (e.g. `{target: "e5", color: "black", attackers: ["Nf3"], defenders: ["Nc6"]}`)
+- Hanging list — attacked and undefended
+- Check state + checkers, castling rights, en passant
+
+Use it whenever you're about to describe a position from memory or from your reading of a FEN. The failure mode this prevents: `{Black's queen on c7 is defended by the knight on d5.}` when actually there's no knight on d5 and the queen is on c8.
+
 ### When prose ADDS to the NAG
 
 Prose is worth writing when the NAG *understates* something the human should know:

package/docs/prep-strategy.md

@@ -21,7 +21,7 @@ The failure mode is *authoritative-sounding recipe = 30% real tool output + 70%
 
 ## Numbers are inputs, not verdicts
 
-The move statistics endpoints return win %, game counts, and (in the big DB) hotness. Treat every one of these as a *weight*, not a *rule*.
+The move statistics endpoints return win %, game counts, and (in the big DB) a `fashionScore` (0–100, how in-fashion the move is right now at the top level — recent + played often). Treat every one of these as a *weight*, not a *rule*.
 
 - **Sample size scales trust.** 3 games at 66% is noise; 300 at 55% is signal. A great score is nice — with volume. When the opponent has only 2-4 games in a variation, the "opponent-specific" score is basically the general-DB score anyway.
 - **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.
@@ -41,7 +41,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 `hotness` field. At the individual-player level, "hotness" is trailing noise — the opponent's opening trend is already captured in game dates. Hotness stays on the general-DB endpoint, where it's genuinely useful: it means fashion (what the whole top field is playing this month).
+**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.
 
 ## Prep is a tree, not a line
 
@@ -68,7 +68,7 @@ Deep prep is a weapon you spend, not one you own. A prepared novelty against a s
 
 ## Move-order tricks aren't visible in raw win rates
 
-The `trs` (transpositions) field on move statistics tells you how much a given position folds into related structures. Move-order tricks are legitimate prep and position stats alone can't recommend them.
+The `reachedViaTransposition` field on move statistics tells you how many of the games at that position arrived via a different move order — a hint at how much the line folds into related structures. Move-order tricks are legitimate prep and position stats alone can't recommend them.
 
 - Considering 1.Nf3 or 1.c4 as a duck around 1.d4? First check the opponent's repertoire *against 1.d4*. If they play the King's Indian, most 1.Nf3/1.c4 lines transpose anyway — the trick doesn't help.
 - Move orders are useful when the opponent plays something that specifically depends on the move order — e.g. a Nimzo player who never gets to play the Nimzo because you go 1.Nf3-2.g3.

package/package.json

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