@chessceo/mcp 0.36.6 → 0.40.0

package/dist/pgn/describe.js

@@ -10,9 +10,10 @@
 // cloud_analyse.
 import { parseFen } from "chessops/fen";
 import { Chess } from "chessops/chess";
-import { attacks } from "chessops/attacks";
-import { makeSquare, squareRank } from "chessops/util";
+import { attacks, pawnAttacks } from "chessops/attacks";
+import { makeSquare, squareRank, squareFile } from "chessops/util";
 import { makeSan } from "chessops/san";
+import { SquareSet } from "chessops/squareSet";
 const ROLE_LETTER = {
     pawn: "", knight: "N", bishop: "B", rook: "R", queen: "Q", king: "K",
 };
@@ -99,6 +100,7 @@ export function describePosition(fen) {
     for (const sq of ctx.checkers)
         checkers.push(pieceSANFromBoard(board, sq));
     const legalMoves = generateLegalMoves(pos);
+    const structural = computeStructural(pos);
     return {
         fen,
         sideToMove: pos.turn,
@@ -113,11 +115,275 @@ export function describePosition(fen) {
         pieces: { white: whitePieces, black: blackPieces },
         contested,
         hanging: { white: hangingWhite, black: hangingBlack },
+        pawnStructure: structural.pawnStructure,
+        weakSquares: structural.weakSquares,
+        outposts: structural.outposts,
+        bishops: structural.bishops,
+        space: structural.space,
         castling: { white: castlingW, black: castlingB },
         epSquare: typeof pos.epSquare === "number" ? makeSquare(pos.epSquare) : null,
         legalMoves,
     };
 }
+// ── Structural analysis ──────────────────────────────────────────────
+// Concepts a human sees at a glance but the LLM cannot derive from a
+// FEN. All chess-primitive computations on top of chessops bitboards;
+// no engine.
+const FILES = ["a", "b", "c", "d", "e", "f", "g", "h"];
+// Which files are occupied by pawns of each colour (bitmask, 8 bits).
+function pawnFilesMask(pos, color) {
+    let mask = 0;
+    for (const sq of pos.board.pawn.intersect(pos.board[color])) {
+        mask |= 1 << squareFile(sq);
+    }
+    return mask;
+}
+function computeStructural(pos) {
+    const whitePawns = pos.board.pawn.intersect(pos.board.white);
+    const blackPawns = pos.board.pawn.intersect(pos.board.black);
+    const wFileMask = pawnFilesMask(pos, "white");
+    const bFileMask = pawnFilesMask(pos, "black");
+    // File status per column.
+    const files = {};
+    for (let f = 0; f < 8; f++) {
+        const wHas = (wFileMask & (1 << f)) !== 0;
+        const bHas = (bFileMask & (1 << f)) !== 0;
+        if (!wHas && !bHas)
+            files[FILES[f]] = "open";
+        else if (!bHas && wHas)
+            files[FILES[f]] = "half_open_for_black"; // black has no pawn → open for black's rooks
+        else if (!wHas && bHas)
+            files[FILES[f]] = "half_open_for_white";
+        else
+            files[FILES[f]] = "closed";
+    }
+    // Islands: count runs of consecutive occupied files.
+    const countIslands = (mask) => {
+        let count = 0, prev = false;
+        for (let f = 0; f < 8; f++) {
+            const has = (mask & (1 << f)) !== 0;
+            if (has && !prev)
+                count++;
+            prev = has;
+        }
+        return count;
+    };
+    // Isolated pawns: own pawn with no friend on adjacent files.
+    const isolated = (color) => {
+        const mask = color === "white" ? wFileMask : bFileMask;
+        const own = color === "white" ? whitePawns : blackPawns;
+        const out = [];
+        for (const sq of own) {
+            const f = squareFile(sq);
+            const left = f > 0 && ((mask >> (f - 1)) & 1);
+            const right = f < 7 && ((mask >> (f + 1)) & 1);
+            if (!left && !right)
+                out.push(makeSquare(sq));
+        }
+        return out.sort();
+    };
+    // Doubled: files with >1 own pawn.
+    const doubled = (color) => {
+        const counts = {};
+        const own = color === "white" ? whitePawns : blackPawns;
+        for (const sq of own) {
+            const f = squareFile(sq);
+            counts[f] = (counts[f] || 0) + 1;
+        }
+        return Object.entries(counts).filter(([, c]) => c > 1).map(([f]) => FILES[Number(f)]).sort();
+    };
+    // Passed pawns: no enemy pawn on same or adjacent file ahead of it.
+    const passed = (color) => {
+        const own = color === "white" ? whitePawns : blackPawns;
+        const enemyMask = color === "white" ? bFileMask : wFileMask;
+        const enemyPawns = color === "white" ? blackPawns : whitePawns;
+        const out = [];
+        for (const sq of own) {
+            const f = squareFile(sq);
+            const r = squareRank(sq);
+            let blocked = false;
+            for (const ef of [f - 1, f, f + 1]) {
+                if (ef < 0 || ef > 7)
+                    continue;
+                if (((enemyMask >> ef) & 1) === 0)
+                    continue;
+                // any enemy pawn on this file ahead of us?
+                for (const esq of enemyPawns) {
+                    if (squareFile(esq) !== ef)
+                        continue;
+                    const er = squareRank(esq);
+                    if (color === "white" ? er > r : er < r) {
+                        blocked = true;
+                        break;
+                    }
+                }
+                if (blocked)
+                    break;
+            }
+            if (!blocked)
+                out.push(makeSquare(sq));
+        }
+        return out.sort();
+    };
+    // Backward: own pawn attacked by enemy pawn, unable to safely advance
+    // (advance square attacked by enemy pawn and undefended by own pawn).
+    const backward = (color) => {
+        const own = color === "white" ? whitePawns : blackPawns;
+        const dir = color === "white" ? 8 : -8;
+        const enemyColor = color === "white" ? "black" : "white";
+        const out = [];
+        for (const sq of own) {
+            const advanceSq = (sq + dir);
+            if (advanceSq < 0 || advanceSq > 63)
+                continue;
+            // Attacked by enemy pawn?
+            const enemyAttackers = pawnAttacks(enemyColor, advanceSq).intersect(pos.board.pawn).intersect(pos.board[enemyColor]);
+            if (enemyAttackers.isEmpty())
+                continue;
+            // Defended by own pawn?
+            const ownDefenders = pawnAttacks(color, advanceSq).intersect(pos.board.pawn).intersect(pos.board[color]);
+            if (ownDefenders.nonEmpty())
+                continue;
+            out.push(makeSquare(sq));
+        }
+        return out.sort();
+    };
+    // Weak squares (holes): squares in ranks 3-6 that no friendly pawn can
+    // ever attack. For White the "own attack" is a pawn on rank-1 diagonal
+    // behind (files ±1). We check every square in the middle four ranks.
+    const weakSquares = (color) => {
+        const own = color === "white" ? whitePawns : blackPawns;
+        const ownMask = color === "white" ? wFileMask : bFileMask;
+        const out = [];
+        const rankRange = color === "white" ? [3, 4, 5] : [2, 3, 4]; // 0-indexed 4,5,6 / 3,4,5 in real ranks
+        for (const r of rankRange) {
+            for (let f = 0; f < 8; f++) {
+                const sq = (r * 8 + f);
+                // Any friendly pawn on adjacent files that could ever attack this square?
+                // For White, an attack on square (f,r) comes from (f±1, r-1);
+                // any pawn on those adjacent files with rank < r could eventually reach.
+                let canBeAttacked = false;
+                for (const df of [-1, 1]) {
+                    const nf = f + df;
+                    if (nf < 0 || nf > 7)
+                        continue;
+                    if (((ownMask >> nf) & 1) === 0)
+                        continue;
+                    // Any pawn on this file at a rank behind the target?
+                    for (const psq of own) {
+                        if (squareFile(psq) !== nf)
+                            continue;
+                        const pr = squareRank(psq);
+                        if (color === "white" ? pr < r : pr > r) {
+                            canBeAttacked = true;
+                            break;
+                        }
+                    }
+                    if (canBeAttacked)
+                        break;
+                }
+                if (!canBeAttacked)
+                    out.push(makeSquare(sq));
+            }
+        }
+        return out.sort();
+    };
+    const wWeak = weakSquares("white");
+    const bWeak = weakSquares("black");
+    const wWeakSet = new Set(wWeak);
+    const bWeakSet = new Set(bWeak);
+    // Outposts: friendly N/B on a hole (WEAKNESS of the enemy) in enemy
+    // territory, defended by an own pawn.
+    const outposts = (color) => {
+        const enemyWeak = color === "white" ? bWeakSet : wWeakSet;
+        const own = pos.board[color];
+        const out = [];
+        for (const sq of own) {
+            const piece = pos.board.get(sq);
+            if (!piece || (piece.role !== "knight" && piece.role !== "bishop"))
+                continue;
+            const sqName = makeSquare(sq);
+            if (!enemyWeak.has(sqName))
+                continue;
+            // Defended by own pawn?
+            const enemyColor = color === "white" ? "black" : "white";
+            // A pawn defending sq for `color` = pawn one rank behind on adjacent file.
+            const defenders = pawnAttacks(enemyColor, sq).intersect(pos.board.pawn).intersect(pos.board[color]);
+            if (defenders.isEmpty())
+                continue;
+            out.push({ piece: ROLE_LETTER_INV[piece.role], square: sqName });
+        }
+        return out.sort((a, b) => a.square.localeCompare(b.square));
+    };
+    // Bishops: quality based on own pawns on the bishop's colour.
+    const bishopColor = (sq) => {
+        // a1 is dark, b1 is light. (file+rank) even = dark.
+        return (squareFile(sq) + squareRank(sq)) % 2 === 0 ? "dark" : "light";
+    };
+    const bishops = (color) => {
+        const own = pos.board.bishop.intersect(pos.board[color]);
+        const ownPawns = color === "white" ? whitePawns : blackPawns;
+        let pawnsLight = 0, pawnsDark = 0;
+        for (const p of ownPawns) {
+            if (bishopColor(p) === "light")
+                pawnsLight++;
+            else
+                pawnsDark++;
+        }
+        const out = [];
+        for (const sq of own) {
+            const c = bishopColor(sq);
+            const onColor = c === "light" ? pawnsLight : pawnsDark;
+            const q = onColor <= 3 ? "good" : onColor >= 5 ? "bad" : "mixed";
+            out.push({ square: makeSquare(sq), colorSquare: c, ownPawnsOnColor: onColor, quality: q });
+        }
+        return out;
+    };
+    // Space: squares in the enemy half controlled by side's pieces + pawns.
+    const space = (color) => {
+        const attackedByColor = SquareSet.empty();
+        let acc = attackedByColor;
+        for (const sq of pos.board[color]) {
+            const piece = pos.board.get(sq);
+            acc = acc.union(attacks(piece, sq, pos.board.occupied));
+        }
+        // Enemy half: white attacks ranks 5-8 (rank index 4-7); black attacks 1-4 (0-3).
+        let count = 0;
+        for (const sq of acc) {
+            const r = squareRank(sq);
+            if (color === "white" && r >= 4)
+                count++;
+            else if (color === "black" && r <= 3)
+                count++;
+        }
+        return count;
+    };
+    return {
+        pawnStructure: {
+            files,
+            islandsWhite: countIslands(wFileMask),
+            islandsBlack: countIslands(bFileMask),
+            isolated: { white: isolated("white"), black: isolated("black") },
+            doubled: { white: doubled("white"), black: doubled("black") },
+            passed: { white: passed("white"), black: passed("black") },
+            backward: { white: backward("white"), black: backward("black") },
+        },
+        weakSquares: { white: wWeak, black: bWeak },
+        outposts: { white: outposts("white"), black: outposts("black") },
+        bishops: {
+            white: bishops("white"),
+            black: bishops("black"),
+            pair: {
+                white: pos.board.bishop.intersect(pos.board.white).size() >= 2,
+                black: pos.board.bishop.intersect(pos.board.black).size() >= 2,
+            },
+        },
+        space: {
+            whiteSquaresInBlackHalf: space("white"),
+            blackSquaresInWhiteHalf: space("black"),
+        },
+    };
+}
 // 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).

package/dist/pgn/mutations.js

@@ -172,6 +172,28 @@ export function setCeoEval(file, path, ev) {
         target.ceoEval = ev;
     return { file: { tags: file.tags, root: newRoot }, id: target.id };
 }
+// Set the same ceoEval on every path in `paths`. One clone-and-return
+// rather than N sequential setCeoEval calls. Used by cloud_analyse to
+// propagate a single measurement to every transposition of the position
+// in the file — the LLM shouldn't have to re-analyse a position it
+// already measured under a different move order.
+export function setCeoEvalMany(file, paths, ev) {
+    if (paths.length === 0)
+        return { file, ids: [] };
+    // Sort deepest-first so cloning one target doesn't invalidate later
+    // ones' path references — cloneOnPath re-parents everything along
+    // the path, so mutating a shallower path after a deeper one is safe;
+    // sorting is defensive.
+    const sorted = [...paths].sort((a, b) => b.length - a.length);
+    let cur = file;
+    const ids = [];
+    for (const p of sorted) {
+        const step = setCeoEval(cur, p, ev);
+        cur = step.file;
+        ids.push(step.id);
+    }
+    return { file: cur, ids };
+}
 // Set or clear a tag. Passing null / empty removes.
 export function setTag(file, key, value) {
     const cleanedKey = key.trim();

package/dist/pgn/paths.js

@@ -101,6 +101,38 @@ export function getParent(root, path) {
     const index = path[path.length - 1];
     return { parent, index };
 }
+// Transposition key: the part of the FEN that decides whether two
+// positions are the same for opening/preparation purposes. Matches the
+// frontend's rule (frontend/src/game/gamestate/services/TreeService.ts
+// fenPositionMatch): piece placement + side to move + castling rights.
+// En-passant square, halfmove clock and fullmove number are excluded —
+// they diverge across move orders that reach the same position, and
+// treating them as significant would defeat the whole point of
+// transposition detection.
+export function positionKey(fen) {
+    return fen.split(" ").slice(0, 3).join(" ");
+}
+// Group every node in the tree by transposition key. Returned in DFS
+// order — the FIRST node in each list is the earliest (mainline-preferred)
+// occurrence, which is what the LLM should treat as the canonical anchor
+// for prose ("this transposes to line X"). Groups with only one member
+// are still included, so callers can check membership cheaply; filter
+// for size ≥ 2 to get actual transpositions.
+export function buildFenIndex(root) {
+    const index = new Map();
+    const walk = (node) => {
+        const key = positionKey(node.fen);
+        const arr = index.get(key);
+        if (arr)
+            arr.push(node);
+        else
+            index.set(key, [node]);
+        for (const c of node.children)
+            walk(c);
+    };
+    walk(root);
+    return index;
+}
 // Deep-clone nodes on the path from root to the mutation target,
 // leaving unrelated subtrees shared. Downstream code treats siblings
 // as immutable so this sharing is safe.

package/docs/engine-usage.md

@@ -16,6 +16,8 @@ When you call `cloud_analyse`, chess.ceo runs Stockfish and Lc0 in parallel on t
 
 Concrete failure this rule blocks: the LLM says *"9...Bb7: both engines 0.00"* after only calling `cloud_analyse` on the child positions (post-1.d4, post-castling). Both continuations really returned 0.00, but the Bb7 node was never analysed, and the claim reads to the user as a measurement. With this protocol, `quote_engine_eval(node_id=Bb7)` would return null and the LLM would either analyse it or reword to *"both continuations run to 0.00, so this position looks balanced"* (soft inference, honestly labelled).
 
+**Transposition propagation.** `cloud_analyse({file_id, node_id})` also stamps the resulting `ceoEval` on every OTHER node in the same file that reaches the same position by a different move order (3-field FEN match: pieces + side-to-move + castling). The response includes `also_stored_on: [id, id]` when this happens, and a follow-up `quote_engine_eval` on any of those twin nodes returns the same measurement — no second analysis needed. `auto_evaluate` also dedupes candidates by the same key and returns `skipped_transpositions` so you can see how much engine time it saved. See `list_transpositions` / `list_nodes({filter: "transpositions"})` for auditing where duplication exists before you start.
+
 **Concrete failure modes to avoid:**
 
 - Inventing an evaluation. If you say "this is +0.4 for White", that number must come from an engine call. Not a guess, not a vibe.
@@ -66,6 +68,27 @@ Trust Lc0 for:
   - Lc0 higher: probably a long-term positional factor beyond Stockfish's horizon
   - Never dismiss either engine — the disagreement itself is the signal
 
+## 0.00 is not "dead draw"
+
+The single most common misread of an engine number. **0.00 means "objectively balanced with optimal play from both sides".** It says nothing about how often the position actually draws over the board — a sharp middlegame with imbalances and only-moves can sit at 0.00 for 40 plies and be a lively fighting game.
+
+An eval quantifies WHO STANDS BETTER, not HOW LIKELY A DRAW IS. The two questions are independent.
+
+- **A wrong reasoning pattern** (documented failure): the LLM sees `SF 0.00, depth 58, 6.6B nodes` on a Bg5 sideline, concludes "actually a dead draw", and marks the line `?!` as a dead end. Wrong. All that eval says is neither side is objectively better with optimal play — the practical drawing chance is a separate question the SF number doesn't answer.
+
+Signals that actually correlate with high drawing chance:
+
+- **Forced repetition visible in the PV** (`Nf3 Nf6 Ng1 Ng8 …`) — that's a draw, not the eval.
+- **Reduced material + 0.00** — opposite-coloured bishops, queen + rook endgames with balanced pawns, king-and-pawn structures with no breakthrough. The material context makes the draw likely, not the eval.
+- **Symmetrical structures with no imbalances and no plan for either side** — engine says 0.00, humans agree by move 25.
+
+If you actually want to estimate PRACTICAL drawing chance, ask the tools that answer that question:
+
+- **`predict_human_move.wdlWhitePov`** — game-outcome prediction from the neural net, rating-conditioned. The `draw` component IS the answer to "how often does this position draw at this level".
+- **Lc0's practical eval** — often diverges from SF at 0.00 to say "still slightly better for White in a real game". That divergence is where the practical winning chance hides.
+
+**Never conflate the objective eval with the practical outcome.** A 0.00 middlegame with a piece imbalance, opposite-side attacks, or a rating gap is a fighting game; the number just told you nobody has a forced win.
+
 ## Lc0 contempt
 
 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.
@@ -103,6 +126,23 @@ 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.
 
+## Why the position is what it is: `describe_position.engineEvalTerms`
+
+`describe_position` returns Stockfish's classical eval decomposed into 13 named terms (Material, Imbalance, Pawns, Knights, Bishops, Rooks, Queens, Mobility, King safety, Threats, Passed, Space, Winnable) alongside the chess-primitive observations. Each term carries white / black / total values in middlegame + endgame. This is how you answer "WHY is Black better here" beyond pointing at `-0.35`.
+
+Primary pattern — **the delta**. Call `describe_position` on the position BEFORE and AFTER a candidate move, compare `engineEvalTerms`; the term with the biggest shift tells you what the move CHANGED. Kim et al. NAACL 2025 showed feeding these named deltas to an LLM roughly doubles chess-commentary correctness vs a bare eval number. Example:
+
+```
+before 12.Nd5:  king_safety = +0.10, mobility = -0.05, threats = 0.00
+after  12.Nd5:  king_safety = +0.40, mobility = +0.30, threats = +0.55
+→ the delta is dominated by threats + king safety
+→ commentary: "12.Nd5 lands an outpost that both eyes the kingside (threats) and improves piece coordination (mobility)"
+```
+
+Absolute values are useful on their own too — a large "King safety" term flags an exposed king regardless of what caused it.
+
+Complements `cloud_analyse` (best move + PV): different questions, two angles on the same position.
+
 ## 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`:

package/docs/pgn-authoring.md

@@ -40,7 +40,8 @@ All mutations **auto-save** with optimistic locking. Response includes the new `
 
 ## Typical build order
 
-1. `read_prep_file` — see what's there. Every node has an `id` you'll pass to the mutation and engine/DB tools.
+0. **`read_example_prep_files`** — do this once per session, before writing any prose. Not optional. Log analysis shows most sessions skip this and produce documented anti-patterns (long PVs in prose, restating what the app renders, verbose citations). Reading the two bundled reference files once inoculates the LLM against those.
+1. `read_prep_file` — see what's there. Every node has an `id` you'll pass to the mutation and engine/DB tools. Use `view: "compact"` (default) plus `node_id` + `max_depth` to scope; the full tree of a 500+-node file can blow the token limit.
 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)` — 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).
@@ -163,6 +164,16 @@ Prose is NEVER for:
 
   Test: if the reader can see it by looking at the position or clicking a branch, don't write it. Prose is only for plans, prep-signal, or WHY — the layer the app can't derive.
 
+## Transpositions: don't analyse (or comment on) the same position twice
+
+Move orders diverge and re-converge constantly. `1.d4 Nf6 2.c4 e6 3.Nc3` and `1.c4 e6 2.Nc3 Nf6 3.d4` land on the same position. The tree model doesn't merge those into one node — it stores both nodes with the same position — so if you're not careful you'll analyse both, quote engine numbers on both, and write two different comments for what is the same chess.
+
+**Detection.** `read_prep_file` shows `transposes_to: [id, id]` on every node whose position appears elsewhere in the file, and the header carries `transposition_groups` / `transposition_nodes` counts. `list_nodes({filter: "transpositions"})` lists just the affected nodes. `list_transpositions` groups every duplicated position with its member nodes. Match key is the frontend's rule: piece placement + side to move + castling rights (en-passant + clocks intentionally ignored).
+
+**Auto-propagation.** When `cloud_analyse({file_id, node_id})` stores `ceoEval` on a node, it also stamps every transposition of that position in the same file — see `also_stored_on: [id, id]` in the response. This means `auto_evaluate({only_missing: true})` naturally skips the twin. `auto_evaluate` also dedupes candidates before it starts and returns `skipped_transpositions` in the initial response so you can see how much engine time was saved.
+
+**Prose.** For commentary, pick a canonical node (usually the mainline-order occurrence — first in `transposes_to`) and write the plans / prep-signal / novelty there. On the twin, either point at it (`{transposes to 3.Nc3 in the mainline — see the note there}`) or leave the comment empty. Don't paste the same three sentences on both — they'll drift as you edit one and forget the other.
+
 ## Move-judgment symbols (NAGs)
 
 NAGs are the compact way to attach an evaluation to a move. Pass as `$N` strings to `set_nags`.
@@ -240,15 +251,22 @@ Contempt scale is signed 0-100 (same as the web UI's ContemptStrength slider). T
 
 ### 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:
+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)`. Pure computation (~1 ms, no engine), returns two layers:
+
+**Board state** — piece placements, material, contested pieces (attackers + defenders), hanging list, check state, castling, en passant, legal moves. Fixes the *"Black's queen on c7 is defended by the knight on d5"* failure when actually there's no knight on d5 and the queen is on c8.
+
+**Structural analysis** — the concepts a strong player reads at a glance but the LLM can't derive from a FEN:
+
+- `pawnStructure.files` — open / half-open / closed per column (rook targets).
+- `pawnStructure.isolated`, `doubled`, `passed`, `backward` — structural weaknesses (and strengths, for passed).
+- `weakSquares` — holes no friendly pawn can ever attack.
+- `outposts` — friendly N/B on an enemy hole defended by own pawn.
+- `bishops` — good / mixed / bad per bishop, based on own pawns on its colour. `bishops.pair` flags who has both.
+- `space` — squares in the enemy half controlled by each side.
 
-- 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 these instead of inventing structural claims. Commentary that says *"Black has the bad light-squared bishop"* should trace to `bishops.black[0].quality === "bad"`, not to a memory of similar Carlsbad positions.
 
-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.
+The same call also returns `engineEvalTerms` — Stockfish's classical-eval breakdown into 13 named terms per colour (mg/eg). Compare it before/after a candidate move: the term that shifts most tells you WHAT the move changed. See the engine-usage guide for the delta pattern.
 
 ### When prose ADDS to the NAG
 

package/docs/prep-files-guide.md

@@ -31,6 +31,10 @@ Every mutation call takes a `node_id` (or `parent_id` for add-style ops) and aut
 
 Duplicate files are the #1 way to lose your user's trust in this system.
 
+## Before writing any prose: read the examples
+
+**Call `read_example_prep_files` early in the session, before your first `set_comment` or comment-carrying `apply_mutations` batch.** Not once per project — once per LLM session. It returns two reference PGNs by a strong human coach and is the single biggest quality lift documented in this MCP; log analysis shows <5% of sessions call it and the ones that don't produce the exact anti-patterns the authoring guide warns against. Reading the two files takes one tool call and inoculates against most commentary failure modes.
+
 ## PGN authoring — separate concern
 
 Everything about **how to write good PGN** (structure, NAGs, arrows, coloured squares, variation discipline, common pitfalls) lives in `pgn-authoring.md` — call `read_pgn_authoring_guide` for the full doc. That guide is universal to any chess file you might write; this guide is about the prep-files *feature* on top.

package/docs/prep-strategy.md

@@ -80,6 +80,32 @@ For a rare position where the opponent has 0–2 games as their side, it's often
 
 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.
 
+## Using the user's course library (`find_position_in_courses` + `read_course_at_position`)
+
+The user has a private index of their own Chessable / PGN files (dozens of GB of prep material). This is a **reference library, not memory** — nobody remembers what's in it, but the LLM can query on demand and cite specific chapters.
+
+Two-tool workflow:
+
+1. **`find_position_in_courses(fen)`** → metadata: which courses cover this position, ranked most-recently-updated first (10-year-old material is less trustworthy than 2-month-old). Each hit has a `course_file_id`.
+2. **`read_course_at_position({course_file_id, fen})`** → the actual commentary, variations, arrows from that specific chapter. Depth-bounded (`max_plies_below`); widen or call again with a different `fen` to explore further.
+
+Query patterns worth reaching for:
+
+- **"Does my chosen line have coverage?"** — search from the target position. If several recent courses cover it, read the top 3-5 hits and see how much they agree; if they diverge, the position is a decision point worth annotating with the disagreement itself.
+- **"What do opposite-colour repertoires recommend against this move?"** — same position, look at hits authored for the OTHER side. That's the LLM's window into "what will opponents have been told to play here". Read every same-side hit — a repertoire that appears in one course may still be someone's line.
+- **"Has anyone tried my novelty before?"** — search the post-novelty position. Zero hits = genuine novelty (good). Hits = it's been tried; **read all of them**, not just the first — a novelty covered by three 2025 courses is not a novelty, but one that appears only in a single 2019 course probably still is.
+- **"Compare how multiple authors annotate the same critical position"** — several `read_course_at_position` calls with different `course_file_id`s from the same search. This is the common case, not a special one.
+
+**Read multiple hits, not just the top one.** The default action after `find_position_in_courses` returns 5 hits is FIVE `read_course_at_position` calls, not one. Different Chessable authors recommend different moves at critical junctions, and that disagreement is exactly the signal your user needs — it tells them where prep depth actually matters versus where the field is unanimous. Reading only the top hit gives the LLM one author's opinion presented as consensus; reading five gives the actual state of theory as the library sees it. The only excuse to stop after one is that the position is trivial (mainline endgame draw, hyper-quiet) and there's nothing to disagree about.
+
+Discipline:
+
+- Course material is a signal, not truth. A course written 2019 may be objectively refuted by current engine analysis; cross-check with `cloud_analyse` before adopting a course's recommendation wholesale.
+- Recency ranking matters most in fast-moving lines (Najdorf, KID, Grünfeld) and less in stable structures (Caro-Kann, Slav mainlines). Weight accordingly.
+- Cite the sources when you use them: `{Ganguly (Reinventing the Ragozin, 2025) recommends 12.Rd1; Aagaard (Attacking Manual II) prefers 12.a3 — decide based on what you're comfortable with.}` Naming multiple authors when they disagree gives the reader something to act on; naming one when others also cover the position understates the picture.
+
+Not available if fenfind isn't installed on the server; both tools respond with `status: "not_available"` in that case.
+
 ## 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:
@@ -174,6 +200,7 @@ Depth calibrates to the *character* of the position, not to whether the DB has g
 - **Forcing → keep going.** Concrete tactics, only-moves, sharp sequences — analyse until the position calms (real endgame, stable middlegame structure). No game data doesn't matter; the moves are forced, so there's nothing to look up anyway. `describe_position` + engine is enough.
 - **Quiet → stop early.** Once the position is strategic — many reasonable moves, no immediate threats — one sentence of plans is worth more than another 6 plies of tree. Stop and describe.
 - **Novelties still need coverage — but the position tells you HOW.** If you're introducing a move nobody's played, "the DB has no games" is not a reason to stop; the reader will reach this position over the board and needs an answer. The shape of that coverage follows the same forcing/quiet rule above: if the novelty forces a single reply, cover just that line; if it opens several plausible replies, branch on them. Predict the opponent with `predict_human_move` (rating-conditioned), sanity-check with Stockfish (objective) and Lc0 (practical alternatives). All three signals matter *most* here precisely because no game-database answer exists. See also "Novelty burns" — that's a separate rule about WHEN to spend a novelty.
+- **`predict_human_move.wdlWhitePov.draw` compares directly across positions.** When choosing between two lines for a specific practical goal (must-win, must-hold), call the tool on both and compare the draw share. Actual numbers only from actual calls — do not paste guessed percentages into prose without running the tool first.
 
 ## How to combine these
 

package/package.json

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

package/tools/fenfind/fenfind.py

@@ -49,6 +49,8 @@ def main():
     ap.add_argument('--games', action='store_true', help='include game-database hits')
     ap.add_argument('--min', type=float, default=400)
     ap.add_argument('-n', type=int, default=25)
+    ap.add_argument('--sort', choices=['recency', 'notes'], default='recency',
+                    help='ranking: recency (default, most recently updated file first) or notes (annotation depth, notes_chars desc)')
     ap.add_argument('--json', action='store_true', help='emit structured JSON on stdout instead of the text table (used by the MCP wrapper)')
     a = ap.parse_args()
 
@@ -60,7 +62,7 @@ def main():
 
     con = sqlite3.connect(DB); con.row_factory = sqlite3.Row
     rows = [dict(r) for r in con.execute(
-        """SELECT f.name,f.course,f.author,o.chapter,o.line,o.ply,o.subtree,o.chars
+        """SELECT f.id AS file_id,f.name,f.path,f.course,f.author,o.chapter,o.line,o.ply,o.subtree,o.chars
            FROM occ o JOIN files f ON f.id=o.file_id WHERE o.z=?""", (z,))]
     if not rows:
         if a.json:
@@ -70,6 +72,15 @@ def main():
         print("position not found in the collection"); return
     total = len(rows)
 
+    # Attach file mtime for recency ranking. Cheap — one stat() per row,
+    # done here rather than at index time so re-indexing isn't required
+    # for the recency signal to work.
+    for r in rows:
+        try:
+            r['mtime'] = os.path.getmtime(r['path'])
+        except OSError:
+            r['mtime'] = 0
+
     ngame = 0
     if not a.games:
         keep = [r for r in rows if not looks_like_gamedb(r['chapter'], r['line'])]
@@ -99,10 +110,24 @@ def main():
             if k not in groups or (r['chars'], r['subtree']) > (groups[k]['chars'], groups[k]['subtree']):
                 groups[k] = r
 
-    hits = sorted(groups.values(), key=lambda r: (-r['chars'], -r['subtree']))
+    # Ranking. `recency` (default) sorts by file mtime desc — 2-month-old
+    # material beats 10-year-old on the assumption that theory shifts. Ties
+    # broken by notes_chars so a deep chapter beats a thin one at the same
+    # mtime. `notes` sorts by annotation depth alone, useful when the
+    # question is "who explains this best regardless of age".
+    if a.sort == 'notes':
+        hits = sorted(groups.values(), key=lambda r: (-r['chars'], -r['subtree']))
+    else:  # recency
+        hits = sorted(groups.values(), key=lambda r: (-r['mtime'], -r['chars']))
     shown = hits if a.all else [h for h in hits if h['chars'] >= a.min]
     thin = len(hits) - len(shown)
 
+    import datetime as _dt
+    def _updated_at(ts):
+        if not ts:
+            return None
+        return _dt.date.fromtimestamp(ts).isoformat()
+
     if a.json:
         # Structured output for the MCP wrapper. Field names spelled out
         # so the LLM reader doesn't need to know the SQLite column names.
@@ -110,6 +135,7 @@ def main():
             "fen": b.fen(),
             "found": True,
             "total_occurrences": total,
+            "sort": a.sort,
             "excluded": {
                 "game_db_hits": ngame,
                 "unmapped_files": ncourse,
@@ -118,6 +144,7 @@ def main():
             },
             "hits": [
                 {
+                    "course_file_id": h['file_id'],  # opaque handle; pass to read_course_at_position
                     "course": h['course'] or None,
                     "file":   h['name'],
                     "author": h['author'] or None,
@@ -126,6 +153,7 @@ def main():
                     "ply":     h['ply'],
                     "notes_chars":   h['chars'],
                     "subtree_moves": h['subtree'],
+                    "updated_at":    _updated_at(h['mtime']),
                 }
                 for h in shown[:a.n]
             ],

package/tools/fenfind/readpgn

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Run readpgn.py with whichever interpreter has python-chess available.
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+for py in "$here/.venv/bin/python" "$HOME/chess/.venv/bin/python" "$HOME/.venv/bin/python" python3; do
+    if "$py" -c 'import chess' 2>/dev/null; then
+        exec "$py" "$here/readpgn.py" "$@"
+    fi
+done
+echo "readpgn: python-chess not found. Install it, e.g.:" >&2
+echo "  python3 -m venv \"$here/.venv\" && \"$here/.venv/bin/pip\" install python-chess" >&2
+exit 1