@chessceo/mcp 0.39.1 → 0.40.0

package/dist/index.js

@@ -16,8 +16,8 @@ import { Chess } from "chess.js";
 import { parsePGN } from "./pgn/parser.js";
 import { exportPGN } from "./pgn/exporter.js";
 import { describePosition } from "./pgn/describe.js";
-import { addLine, addMove, deleteSubtree, MutationError, promoteVariation, setAnnotations, setCeoEval, setComment, setNags, setTag, } from "./pgn/mutations.js";
-import { buildIdIndex, NodeIdError, PathError, resolveNodeId, ROOT_ID } from "./pgn/paths.js";
+import { addLine, addMove, deleteSubtree, MutationError, promoteVariation, setAnnotations, setCeoEval, setCeoEvalMany, setComment, setNags, setTag, } from "./pgn/mutations.js";
+import { buildFenIndex, buildIdIndex, NodeIdError, PathError, positionKey, resolveNodeId, ROOT_ID } from "./pgn/paths.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -77,6 +77,7 @@ const AUTHED_TOOLS = new Set([
     "search_prep_files",
     "read_prep_file",
     "list_nodes",
+    "list_transpositions",
     "create_prep_file",
     "delete_prep_file",
     "add_move",
@@ -573,19 +574,34 @@ const TOOLS = [
             "  • `mainline` — the spine (children[0] recursively). Use for a compact 'what does the repertoire cover' view.\n" +
             "  • `novelties` — nodes carrying the `$146` NAG.\n" +
             "  • `leaves` — nodes with no children (variation endpoints). Useful for finding lines that need continuation.\n" +
+            "  • `transpositions` — nodes that share their position with at least one other node in the same file (piece placement + side to move + castling rights match). Response includes `transposes_to: [node_id, …]` per hit so you can see the partners without a second call. Use this BEFORE auto_evaluate on a large branch to see where analysis will double up, and BEFORE writing prose to know which nodes can share commentary via 'transposes to line X'.\n" +
             "  • `all` — every node id. Use only when you really need the whole list.\n\n" +
-            "Response: `{ file_id, filter, count, nodes: [{node_id, san, ply, ...}] }`. `...` is filter-specific — e.g. `has_comment` includes the first 80 chars of the comment; `missing_eval` includes nothing extra (just the addressing).",
+            "Response: `{ file_id, filter, count, nodes: [{node_id, san, ply, ...}] }`. `...` is filter-specific — e.g. `has_comment` includes the first 80 chars of the comment; `transpositions` includes `transposes_to`; `missing_eval` includes nothing extra (just the addressing).",
         inputSchema: {
             type: "object",
             properties: {
                 id: { type: "string", description: "Prep file id." },
-                filter: { type: "string", enum: ["missing_eval", "has_comment", "has_annotations", "mainline", "novelties", "leaves", "all"], description: "Which nodes to list." },
+                filter: { type: "string", enum: ["missing_eval", "has_comment", "has_annotations", "mainline", "novelties", "leaves", "transpositions", "all"], description: "Which nodes to list." },
                 node_id: { type: "string", description: "Subtree root (default `'r'` = whole file)." },
                 max_depth: { type: "integer", minimum: 0, description: "Cap the walk at this many plies below `node_id`. Omit for unlimited." },
             },
             required: ["id", "filter"],
         },
     },
+    {
+        name: "list_transpositions",
+        description: "Group every position in a prep file that appears more than once — the same piece placement + side-to-move + castling rights reached by different move orders. Chess move orders diverge and re-converge constantly (1.d4 Nf6 2.c4 e6 3.Nc3 vs 1.c4 e6 2.Nc3 Nf6 3.d4 land on the same position); if you analyse both branches independently or write the same commentary twice, you're wasting engine time and inviting inconsistency.\n\n" +
+            "Call this BEFORE `auto_evaluate` on a big subtree to see how much work will actually be new, and BEFORE writing prose to know which nodes can share a comment or should point at each other with 'transposes to line X'.\n\n" +
+            "Note: engine evals auto-propagate — 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 the response's `also_stored_on`). And `auto_evaluate({only_missing: true})` naturally skips the twin because it now has an eval. So detection is cheap AND propagation is automatic; this tool is for prose planning and one-shot audits, not for gating engine work.\n\n" +
+            "Response: `{ file_id, group_count, node_count, groups: [{ position_key, size, node_ids, sans }] }`. `position_key` is the 3-field FEN prefix used as the match key; `size` is how many nodes share it; `sans` are the moves that led to each occurrence (parallel with `node_ids`, DFS order — first entry is the earliest/mainline-preferred occurrence). Only groups with size ≥ 2 are returned; sorted by size descending.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Prep file id." },
+            },
+            required: ["id"],
+        },
+    },
     {
         name: "create_prep_file",
         description: "Create a new (empty) prep file. `name` becomes the Event PGN tag. You then extend it with mutation tools (add_move, set_comment, …).\n\n" +
@@ -862,12 +878,14 @@ const TOOLS = [
     {
         name: "find_position_in_courses",
         description: "Look up which of the USER's own Chessable / PGN courses cover a position. This is the LLM's window into what the user has personally studied — not a general database. Two-step: `find_position_in_courses` returns metadata (course, chapter, author, updated_at, notes_chars, `course_file_id`); `read_course_at_position` fetches the actual commentary + variations from a specific hit.\n\n" +
+            "**Read multiple hits, not just the top one.** A search commonly returns 3-10 courses covering the same position. Different authors recommend different moves, weight lines differently, and disagree about which sidelines matter — that disagreement is exactly the information you want. Default assumption: read the top 3-5 hits by recency, more if the position is critical (novelty candidate, main-line trunk, sharp tactical junction). Reading only the first hit gives you one author's opinion; reading five gives you the actual state of theory as your user's library sees it.\n\n" +
             "Use it as a reference library, not memory. Query patterns:\n" +
-            "  • 'Does my chosen line have coverage?' → search from the position, see which repertoires cover it.\n" +
-            "  • 'What do opposite-colour repertoires recommend against this move?' → search, filter by author/course to the other side.\n" +
-            "  • 'Has anyone tried my novelty before?' → search the position, if hits exist read the ones that reach it.\n\n" +
+            "  • 'Does my chosen line have coverage?' → search from the position, read multiple hits, see whether the field agrees on the main response.\n" +
+            "  • 'What do opposite-colour repertoires recommend against this move?' → search, then read every hit whose author/course maps to the other side.\n" +
+            "  • 'Has anyone tried my novelty before?' → search the position, if hits exist read all of them (a novelty that appears in ONE 2019 course is still a novelty to serious opponents; a novelty covered by three 2025 courses is not).\n" +
+            "  • 'What are the main disagreements between authors?' → read the top 3-5 hits, diff the recommended moves against each other; if two Chessable authors branch differently at move 8, that's a decision point worth annotating in your own file.\n\n" +
             "Default sort is `recency` (most-recently-updated file first — theory shifts, 10-year-old material is less trustworthy than 2-month-old). Switch to `notes` when you specifically want the deepest annotated chapter regardless of age.\n\n" +
-            "Returns: `{fen, found, total_occurrences, sort, excluded, hits: [{course_file_id, course, file, author, chapter, line, ply, notes_chars, subtree_moves, updated_at}], truncated}`. Pass `course_file_id` to `read_course_at_position` to actually see the material.\n\n" +
+            "Returns: `{fen, found, total_occurrences, sort, excluded, hits: [{course_file_id, course, file, author, chapter, line, ply, notes_chars, subtree_moves, updated_at}], truncated}`. Pass `course_file_id` to `read_course_at_position` to actually see the material — and pass it more than once, on the top few hits, not just the first one.\n\n" +
             "Not available if the fenfind index isn't installed on the server — response includes a clear note in that case.",
         inputSchema: {
             type: "object",
@@ -888,11 +906,12 @@ const TOOLS = [
         name: "read_course_at_position",
         description: "Read the actual commentary + variations from a course file at a specific position. Second half of the find→read pair — `find_position_in_courses` returns metadata; this returns the material itself.\n\n" +
             "Response includes the subtree as PGN (comments, NAGs, `[%cal]`/`[%csl]` arrows all preserved), plus the moves-to-position and chapter metadata. Depth-capped by `max_plies_below` (default 20) to keep responses small — widen when you want to see deeper analysis, or call with a different `fen` to jump to another position in the same file.\n\n" +
+            "**Called once per search is a smell.** When `find_position_in_courses` returned 5 hits and you only read the first, you have 1 author's view of the position, not a survey. Read the top 3-5 hits by default; compare their recommendations and disagreements — that comparison is the value the user's library provides over your training data.\n\n" +
             "Usage patterns:\n" +
             "  • Read what an author says about a specific position → pass `course_file_id` from a find hit + the FEN.\n" +
             "  • Explore a chapter from move 1 → pass `course_file_id` + `chapter`, no FEN.\n" +
             "  • Skim deeper into a branch you're interested in → same file/chapter, wider `max_plies_below`.\n" +
-            "  • Compare how two authors annotate the same position → two calls with different `course_file_id`s.",
+            "  • **Compare how multiple authors annotate the same position → several calls with different `course_file_id`s (this is the common case, not the exception).** If the top hits recommend different moves, that's a decision point worth annotating with the disagreement itself.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1221,6 +1240,29 @@ 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);
+    // Dedup transpositions: if two candidate targets share the same
+    // 3-field FEN key, they're the same position reached by different
+    // move orders. Analyse ONE of them — cloud_analyse auto-propagates
+    // the resulting ceoEval to every other node with a matching key
+    // (see storeEvalOnNode), so the twin ends up with the same eval
+    // without a second engine call. Keep DFS-first (mainline-preferred)
+    // occurrence.
+    let skippedTranspositions = 0;
+    {
+        const seen = new Set();
+        const deduped = [];
+        for (const t of targets) {
+            const key = positionKey(t.fen);
+            if (seen.has(key)) {
+                skippedTranspositions++;
+                continue;
+            }
+            seen.add(key);
+            deduped.push(t);
+        }
+        targets.length = 0;
+        targets.push(...deduped);
+    }
     // Nothing to do → return a done job synthetically so the caller doesn't
     // need to special-case the empty response.
     if (targets.length === 0) {
@@ -1264,6 +1306,9 @@ async function autoEvaluate(args) {
     return {
         job_id: jobId,
         target_count: targets.length,
+        // Transpositions inside the walk that we skipped because they'll
+        // pick up the eval via auto-propagation. Zero when there are none.
+        skipped_transpositions: skippedTranspositions,
         status: "running",
         // Rough time estimate at the current default movetime. Serialization
         // on the per-combo semaphore means walltime ≈ target_count × movetime.
@@ -1829,7 +1874,13 @@ async function loadPrepFile(id) {
 }
 // Recursively project a PrepNode into the requested view. `depthLeft`
 // null → unlimited; 0 → just the node without children.
-function projectNode(node, view, depthLeft) {
+//
+// `fenIndex` (optional) enables the `transposes_to` field — for each
+// node whose position also appears elsewhere in the SAME file, we
+// annotate it with the OTHER occurrences' ids. Pass null (the default)
+// to skip the annotation entirely; passing the map costs one lookup
+// per node projected.
+function projectNode(node, view, depthLeft, fenIndex = null) {
     const base = {
         id: node.id,
         san: node.san,
@@ -1846,16 +1897,24 @@ function projectNode(node, view, depthLeft) {
         if (node.annotations)
             base.annotations = node.annotations;
     }
+    if (fenIndex && node.id !== ROOT_ID) {
+        const group = fenIndex.get(positionKey(node.fen));
+        if (group && group.length > 1) {
+            const others = group.filter(n => n.id !== node.id).map(n => n.id);
+            if (others.length > 0)
+                base.transposes_to = others;
+        }
+    }
     // Children handling depends on view + depth budget.
     const showChildren = depthLeft === null || depthLeft > 0;
     const childDepth = depthLeft === null ? null : depthLeft - 1;
     if (showChildren && node.children.length > 0) {
         if (view === "spine") {
             // Only follow children[0] — collapses the tree to the mainline.
-            base.children = [projectNode(node.children[0], view, childDepth)];
+            base.children = [projectNode(node.children[0], view, childDepth, fenIndex)];
         }
         else {
-            base.children = node.children.map(c => projectNode(c, view, childDepth));
+            base.children = node.children.map(c => projectNode(c, view, childDepth, fenIndex));
         }
     }
     else {
@@ -1874,6 +1933,19 @@ async function readPrepFile(args) {
     const idIndex = buildIdIndex(file.root);
     const path = resolveNodeId(idIndex, startNodeId);
     const anchor = getNodeByPath(file.root, path);
+    const fenIndex = buildFenIndex(file.root);
+    // How many DISTINCT positions in the file appear more than once,
+    // and how many nodes are involved. Shown in the header so the LLM
+    // sees at a glance whether transpositions matter here before diving
+    // into the tree.
+    let transGroups = 0;
+    let transNodes = 0;
+    for (const arr of fenIndex.values()) {
+        if (arr.length > 1) {
+            transGroups++;
+            transNodes += arr.length;
+        }
+    }
     const header = {
         id: fileIdEcho ?? id,
         version,
@@ -1881,6 +1953,8 @@ async function readPrepFile(args) {
         view,
         node_id: startNodeId,
         max_depth: maxDepth,
+        transposition_groups: transGroups,
+        transposition_nodes: transNodes,
     };
     if (view === "pgn") {
         // For the root, just return the file's actual PGN as-is. For a
@@ -1894,7 +1968,7 @@ async function readPrepFile(args) {
         const subtreePgn = exportSubtreePgn(file, anchor, maxDepth);
         return { ...header, pgn: subtreePgn };
     }
-    return { ...header, tree: projectNode(anchor, view, maxDepth) };
+    return { ...header, tree: projectNode(anchor, view, maxDepth, fenIndex) };
 }
 // Produce a PGN string for a subtree rooted at `anchor`, truncated
 // at `maxDepth` plies below (null = unlimited). Reuses the exporter
@@ -1933,6 +2007,7 @@ async function listNodes(args) {
     const idIndex = buildIdIndex(file.root);
     const path = resolveNodeId(idIndex, startNodeId);
     const anchor = getNodeByPath(file.root, path);
+    const fenIndex = filter === "transpositions" ? buildFenIndex(file.root) : null;
     const hits = [];
     const walk = (node, depthLeft, spineOnly) => {
         // Root has no san — never emit it as a match. Everything else is fair game.
@@ -1960,6 +2035,14 @@ async function listNodes(args) {
                 case "mainline":
                     include = spineOnly;
                     break;
+                case "transpositions": {
+                    const group = fenIndex.get(positionKey(node.fen));
+                    if (group && group.length > 1) {
+                        include = true;
+                        extra.transposes_to = group.filter(n => n.id !== node.id).map(n => n.id);
+                    }
+                    break;
+                }
                 case "all":
                     include = true;
                     break;
@@ -1988,6 +2071,27 @@ async function listNodes(args) {
     walk(anchor, maxDepth, rootIsSpineForFilter);
     return { file_id: id, filter, node_id: startNodeId, max_depth: maxDepth, count: hits.length, nodes: hits };
 }
+// list_transpositions — every position that occurs 2+ times in the
+// file, so the LLM knows where its analysis / prose will double up.
+async function listTranspositions(args) {
+    const id = String(args.id);
+    const { file } = await loadPrepFile(id);
+    const fenIndex = buildFenIndex(file.root);
+    const groups = [];
+    for (const [key, arr] of fenIndex.entries()) {
+        if (arr.length < 2)
+            continue;
+        groups.push({
+            position_key: key,
+            size: arr.length,
+            node_ids: arr.map(n => n.id),
+            sans: arr.map(n => n.san),
+        });
+    }
+    groups.sort((a, b) => b.size - a.size || a.position_key.localeCompare(b.position_key));
+    const nodeCount = groups.reduce((s, g) => s + g.size, 0);
+    return { file_id: id, group_count: groups.length, node_count: nodeCount, groups };
+}
 // 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
@@ -2260,22 +2364,41 @@ function getNodeByPath(root, path) {
     }
     return cur;
 }
-// Persist a fresh ceoEval on the node referenced by the file handle.
-// Best-effort — if the file version raced (another agent saved
-// between our GET and our PUT), we silently drop the store rather
-// than fail the analysis the LLM actually asked for. The eval is
-// still returned in the response either way.
+// Persist a fresh ceoEval on the node referenced by the file handle
+// AND on every other node in the same file that transposes to the
+// same position (matches on the frontend's 3-field FEN key: piece
+// placement + side to move + castling). Best-effort — if the file
+// version raced (another agent saved between our GET and our PUT),
+// we silently drop the store rather than fail the analysis the LLM
+// actually asked for. The eval is still returned in the response
+// either way.
+//
+// Return: ids of every node the eval was stamped on (empty on error).
+// The primary node's id is always first (if present).
 async function storeEvalOnNode(handle, ev) {
     try {
-        const step = setCeoEval(handle.parsedFile, handle.nodePath, ev);
-        const newPgn = exportPGN(step.file);
+        const anchor = getNodeByPath(handle.parsedFile.root, handle.nodePath);
+        const key = positionKey(anchor.fen);
+        const fenIndex = buildFenIndex(handle.parsedFile.root);
+        const group = fenIndex.get(key) ?? [anchor];
+        // Resolve every transposed node back to its path. cloneOnPath
+        // rebuilds the spine so we need paths, not references — the
+        // id index was built against the original tree and every id in
+        // `group` exists there.
+        const idIndex = handle.idIndex ?? buildIdIndex(handle.parsedFile.root);
+        const paths = group.map(n => resolveNodeId(idIndex, n.id));
+        const { file: newFile, ids } = setCeoEvalMany(handle.parsedFile, paths, ev);
+        const newPgn = exportPGN(newFile);
         await authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(handle.id)}`, {
             pgn: newPgn,
             expected_version: handle.version,
         });
+        // Ensure the primary node (the one the LLM addressed) comes first.
+        const anchorId = anchor.id;
+        return [anchorId, ...ids.filter(x => x !== anchorId)];
     }
     catch {
-        // Best-effort — the analysis result is what the LLM asked for.
+        return [];
     }
 }
 function stringifyForLog(v) {
@@ -2512,8 +2635,15 @@ async function callToolInner(name, args) {
             // was supplied and the eval survives via the [%ceo-eval] escape.
             if (resolved.file) {
                 const ev = analysisToStoredEval(converted);
-                if (ev)
-                    await storeEvalOnNode(resolved.file, ev);
+                if (ev) {
+                    const stamped = await storeEvalOnNode(resolved.file, ev);
+                    if (stamped.length > 1) {
+                        // Surface the propagation so the LLM sees exactly which
+                        // other nodes now carry this eval (and can skip them for
+                        // re-analysis).
+                        converted.also_stored_on = stamped.slice(1);
+                    }
+                }
             }
             return converted;
         }
@@ -2535,6 +2665,8 @@ async function callToolInner(name, args) {
             return readPrepFile(args);
         case "list_nodes":
             return listNodes(args);
+        case "list_transpositions":
+            return listTranspositions(args);
         case "create_prep_file":
             return authedRequest("POST", "/api/agent/prep-files", {
                 name: String(args.name),

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.

package/docs/pgn-authoring.md

@@ -164,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`.

package/docs/prep-strategy.md

@@ -91,16 +91,18 @@ Two-tool workflow:
 
 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 hit for background before writing prep.
-- **"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".
-- **"Has anyone tried my novelty before?"** — search the post-novelty position. Zero hits = genuine novelty (good). Hits = it's been tried; read what happened.
-- **"Compare how two authors annotate the same critical position"** — two `read_course_at_position` calls with different `course_file_id`s.
+- **"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 source when you use it: `{Ganguly (Reinventing the Ragozin, 2025) covers this exact position — recommends 12.Rd1.}` The reader can then go read the chapter themselves. Don't dump the course prose into your comment; point them at it.
+- 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.39.1",
+  "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": {