@chessceo/mcp 0.17.0 → 0.23.0

package/dist/index.js

@@ -12,6 +12,10 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { Chess } from "chess.js";
+import { parsePGN } from "./pgn/parser.js";
+import { exportPGN } from "./pgn/exporter.js";
+import { addMove, deleteSubtree, MutationError, promoteVariation, setAnnotations, setComment, setNags, setTag, } from "./pgn/mutations.js";
+import { PathError } 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";
@@ -36,6 +40,7 @@ function loadBundledDoc(filename, fallbackLabel) {
 const ENGINE_USAGE_DOC = loadBundledDoc("engine-usage.md", "Engine usage guide");
 const PREP_STRATEGY_DOC = loadBundledDoc("prep-strategy.md", "Prep strategy guide");
 const PREP_FILES_DOC = loadBundledDoc("prep-files-guide.md", "Prep files guide");
+const PGN_AUTHORING_DOC = loadBundledDoc("pgn-authoring.md", "PGN authoring guide");
 // ── HTTP ────────────────────────────────────────────────────────────
 //
 // Two auth flavours coexist:
@@ -63,8 +68,15 @@ const AUTHED_TOOLS = new Set([
     "search_prep_files",
     "read_prep_file",
     "create_prep_file",
-    "save_prep_file",
     "delete_prep_file",
+    "add_move",
+    "set_comment",
+    "set_nags",
+    "set_annotations",
+    "delete_subtree",
+    "promote_variation",
+    "set_tag",
+    "predict_human_move",
 ]);
 function isAuthedToolCall(body) {
     if (!body || typeof body !== "object")
@@ -269,6 +281,51 @@ const TOOLS = [
             },
         },
     },
+    {
+        name: "predict_human_move",
+        description: "Predicts what a HUMAN of the given rating will most likely play from a position. Rating-conditioned neural net (ResNet-20x256) — you get the top-N most likely moves with their probabilities and a WDL value head (White POV).\n\n" +
+            "This is a completely different question from the engine tools (analyse / cloud_analyse):\n" +
+            "• Engines answer: 'what is objectively best?'\n" +
+            "• predict_human_move answers: 'what will my 2200-rated opponent actually play here?'\n\n" +
+            "Prime use cases in prep:\n" +
+            "• After you've found what the opponent SHOULD do (with the engine), check what they'll ACTUALLY do at their rating. If the top human move is a mistake, you have a real practical advantage.\n" +
+            "• The WDL head is rating-aware — a 400-point gap will show up as a big win probability even in equal positions (the model has learned that human errors compound).\n" +
+            "• Pass `prev_fen` (most recent first) when analysing mid-trade positions — without history the model treats the position as quiet.\n\n" +
+            "Position input is flexible — pass `fen`, or `moves` from startpos, or `fen + moves`. Default rating 2400 both sides. ~1-2s per call. **Premium (or admin/moderator) only** — anonymous calls get 402.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fen: { type: "string", description: "Starting position as FEN." },
+                moves: {
+                    type: "string",
+                    description: "Optional SAN moves to apply on top of `fen` (or startpos).",
+                },
+                white_elo: {
+                    type: "integer",
+                    minimum: 100,
+                    maximum: 3400,
+                    description: "White's rating (default 2400).",
+                },
+                black_elo: {
+                    type: "integer",
+                    minimum: 100,
+                    maximum: 3400,
+                    description: "Black's rating (default 2400).",
+                },
+                top: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 20,
+                    description: "Number of top predicted moves to return (default 5).",
+                },
+                prev_fens: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Previous FEN(s), most recent first. Optional — omit for quiet-position analysis. Useful mid-trade so the model doesn't assume the position is stable.",
+                },
+            },
+        },
+    },
     {
         name: "get_head_to_head",
         description: "Complete head-to-head record between two players. Includes overall and per-colour W/D/L (from player A's perspective), splits by time control, most-played openings between them, first / last meeting, average game length, and the game list.",
@@ -411,7 +468,8 @@ const TOOLS = [
     },
     {
         name: "read_prep_file",
-        description: "Read one prep file. Returns the full PGN text and a compact tree JSON of the mainline (SAN + FEN per move) for programmatic reasoning. Also carries the `version` field you need to pass back to save_prep_file for the optimistic-lock check.",
+        description: "Read one prep file. Returns a compact tree (path-addressable, one node per move) plus tags and the `version` for optimistic locking on subsequent mutations. NO raw PGN — all edits go through the mutation tools (add_move / set_comment / set_nags / set_annotations / delete_subtree / promote_variation / set_tag), which validate SAN and structure for you.\n\n" +
+            "Path addressing: paths are arrays of child indices. `[]` = root position. `[0]` = the first mainline move. `[0, 1]` = the second variation branching after the first move. `[0, 0, 0]` = three plies deep on the mainline. Every mutation returns the effective path it landed at.",
         inputSchema: {
             type: "object",
             properties: {
@@ -422,53 +480,148 @@ const TOOLS = [
     },
     {
         name: "create_prep_file",
-        description: "Create a new prep file. `name` becomes the Event PGN tag (user-facing label). Optional `pgn` seeds the file — if omitted, a minimal empty PGN is written and you can save_prep_file into it later.\n\n" +
-            "ALWAYS run list_prep_files (or search_prep_files with the opponent / opening keyword) BEFORE creating, so you don't duplicate an existing file. If a file already exists that fits, extend it via save_prep_file instead.",
+        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" +
+            "ALWAYS call list_prep_files (or search_prep_files with the opponent / opening keyword) FIRST — creating a duplicate 'Prep vs Firouzja' when one exists is the #1 LLM failure mode. If a file already covers the topic, add moves to that one instead.",
         inputSchema: {
             type: "object",
             properties: {
                 name: {
                     type: "string",
-                    description: "User-facing name for the file — becomes the [Event] tag in the PGN. Example: 'Prep vs Firouzja (Black) 2026-07-23'.",
-                },
-                pgn: {
-                    type: "string",
-                    description: "Optional initial PGN content. Supports full PGN with headers and parenthesised variations. If omitted, an empty PGN is created.",
+                    description: "User-facing name — becomes the [Event] tag. Example: 'Prep vs Firouzja (Black) 2026-07-23'.",
                 },
             },
             required: ["name"],
         },
     },
     {
-        name: "save_prep_file",
-        description: "Save (replace) a prep file's PGN content. Optimistic-lock via `expected_version` — pass the `version` you got from read_prep_file. If someone else (user in the app, or another agent session) updated the file since you read it, save returns 409 with the current version — re-read and merge.\n\n" +
-            "PGN structure guidance:\n" +
-            "- Keep the mainline clean (your top recommendation).\n" +
-            "- Alternative candidates go in parenthesised variations at the branching move.\n" +
-            "- Attach one-sentence commentary at key branch points using PGN {curly-brace comments}. Cite the actual tool output ('Lc0 gives +0.15 in this line') — don't dress the file up with unsourced chess prose.\n" +
-            "- Use PGN NAGs for evaluations: $1 !, $2 ?, $3 !!, $4 ??, $6 =, $10 = (equal), $14 +/= (slight edge), etc. Optional but nice.",
+        name: "delete_prep_file",
+        description: "Soft-delete a prep file. User can restore from the app's recycle bin. Rare — usually you extend or edit instead.",
         inputSchema: {
             type: "object",
             properties: {
                 id: { type: "string", description: "Prep file id." },
-                pgn: { type: "string", description: "Full replacement PGN (headers + moves)." },
-                expected_version: {
-                    type: "integer",
-                    description: "The `version` you got from read_prep_file. If omitted, no optimistic check runs (last-write-wins — riskier).",
-                },
             },
-            required: ["id", "pgn"],
+            required: ["id"],
         },
     },
     {
-        name: "delete_prep_file",
-        description: "Soft-delete a prep file. The user can restore it from the chess.ceo app's recycle bin if you deleted something valuable. Rare — usually you extend or replace instead.",
+        name: "add_move",
+        description: "Append a move as a new child of the node at `path`. If the node already has children, the new move becomes a variation (appended at the end). Use promote_variation afterwards if you want it to be the mainline. SAN is validated against the position — illegal moves are rejected with a clear error.\n\n" +
+            "Auto-saves. Returns `{path, version}` — the effective path the new node landed at (which you pass to follow-up set_comment / set_nags / etc.) and the new file version for optimistic locking on your next mutation.",
         inputSchema: {
             type: "object",
             properties: {
                 id: { type: "string", description: "Prep file id." },
+                path: { type: "array", items: { type: "integer", minimum: 0 }, description: "Path to the parent node the move is played FROM." },
+                san: { type: "string", description: "The move in SAN notation (e.g. 'Nf3', 'exd5', 'O-O', 'Qxf7+')." },
+                expected_version: { type: "integer", description: "Optimistic-lock check; pass the `version` from your last read." },
             },
-            required: ["id"],
+            required: ["id", "path", "san"],
+        },
+    },
+    {
+        name: "set_comment",
+        description: "Set (or clear, with empty string) the text comment on the node at `path`. Comments are for plans, prep-signal, and interpretation the app can't derive — NOT for describing moves that should be variations instead. Auto-saves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Prep file id." },
+                path: { type: "array", items: { type: "integer", minimum: 0 } },
+                comment: { type: "string", description: "New comment text. Empty string clears." },
+                expected_version: { type: "integer" },
+            },
+            required: ["id", "path", "comment"],
+        },
+    },
+    {
+        name: "set_nags",
+        description: "Replace the list of NAGs on the node at `path`. Empty array clears them. See read_pgn_authoring_guide for the full NAG table and eval→NAG thresholds (|eval|<0.25 → $10; <0.6 → $14/$15; <1.3 → $16/$17; ≥1.3 → $18/$19). Auto-saves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                path: { type: "array", items: { type: "integer", minimum: 0 } },
+                nags: { type: "array", items: { type: "string", pattern: "^\\$\\d+$" }, description: "NAG list, e.g. ['$14'] or ['$146', '$44']." },
+                expected_version: { type: "integer" },
+            },
+            required: ["id", "path", "nags"],
+        },
+    },
+    {
+        name: "set_annotations",
+        description: "Replace the visual annotations (arrows + coloured squares) on the node at `path`. Passing empty arrays clears them.\n\n" +
+            "Colours: green, red, yellow, light-blue, dark-blue, orange. Keep it LIGHT: 1-3 arrows and 2-3 squares per move maximum. Twenty arrows is noise, not signal. Auto-saves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                path: { type: "array", items: { type: "integer", minimum: 0 } },
+                arrows: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            color: { type: "string", enum: ["green", "red", "yellow", "light-blue", "dark-blue", "orange"] },
+                            from: { type: "string", pattern: "^[a-h][1-8]$" },
+                            to: { type: "string", pattern: "^[a-h][1-8]$" },
+                        },
+                        required: ["color", "from", "to"],
+                    },
+                },
+                highlights: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            color: { type: "string", enum: ["green", "red", "yellow", "light-blue", "dark-blue", "orange"] },
+                            square: { type: "string", pattern: "^[a-h][1-8]$" },
+                        },
+                        required: ["color", "square"],
+                    },
+                },
+                expected_version: { type: "integer" },
+            },
+            required: ["id", "path"],
+        },
+    },
+    {
+        name: "delete_subtree",
+        description: "Delete the node at `path` and all its descendants. Refuses to delete the root. Auto-saves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                path: { type: "array", items: { type: "integer", minimum: 0 } },
+                expected_version: { type: "integer" },
+            },
+            required: ["id", "path"],
+        },
+    },
+    {
+        name: "promote_variation",
+        description: "Make the node at `path` its parent's mainline (children[0]), demoting the current mainline (and any other siblings) into variation order. Silently no-op if already the mainline. Auto-saves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                path: { type: "array", items: { type: "integer", minimum: 0 }, description: "Path to the node to promote. Length ≥ 1." },
+                expected_version: { type: "integer" },
+            },
+            required: ["id", "path"],
+        },
+    },
+    {
+        name: "set_tag",
+        description: "Set or clear a game-level PGN tag (Event, Site, Date, White, Black, Result, or any custom tag). Passing empty string removes the tag. Auto-saves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                key: { type: "string", description: "Tag key, e.g. 'Event', 'White', 'Date'." },
+                value: { type: "string", description: "Tag value. Empty string removes the tag." },
+                expected_version: { type: "integer" },
+            },
+            required: ["id", "key", "value"],
         },
     },
     {
@@ -483,7 +636,12 @@ const TOOLS = [
     },
     {
         name: "read_prep_files_guide",
-        description: "Returns the full guide on how to store prep in the user's chess.ceo account via list_prep_files / read_prep_file / create_prep_file / save_prep_file / delete_prep_file. Covers: how to structure a repertoire PGN (mainline + variations + comments + NAGs), the critical 'search-before-create' habit to avoid duplicates, optimistic-locking with `version`, and how to write comments that cite tool output instead of inventing chess prose. Call this ONCE per session before your first create_prep_file / save_prep_file call.",
+        description: "Returns the guide to the prep-files FEATURE — how the storage works, when to list vs search vs create, optimistic locking with `version`, and naming conventions for the [Event] tag. Call this ONCE per session before your first create_prep_file. For how to actually WRITE PGN (mainline, variations, NAGs, arrows, comments) call read_pgn_authoring_guide instead — separate concern.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "read_pgn_authoring_guide",
+        description: "Returns the guide on how to write correct, useful PGN — mainline discipline, variations as moves (never prose describing moves), NAG symbols including novelty ($146), unclear ($13), compensation ($44) and the standard set, ChessBase arrow/coloured-square syntax ([%cal] / [%csl]), and common pitfalls the parser will reject. Call this ONCE per session before any save_prep_file call, or any time you're producing PGN output for the user.",
         inputSchema: { type: "object", properties: {} },
     },
     {
@@ -593,23 +751,54 @@ function convertCloudSnapshotResponse(raw, startFen) {
     }
     return raw;
 }
-function pgnToTree(pgn) {
+// Path arg parsing for the mutation tools. Rejects malformed input
+// with a clear message the LLM can act on.
+function argPath(args) {
+    const raw = args.path;
+    if (!Array.isArray(raw))
+        throw new Error("`path` must be an array of non-negative integers");
+    const out = [];
+    for (let i = 0; i < raw.length; i++) {
+        const n = raw[i];
+        if (typeof n !== "number" || !Number.isInteger(n) || n < 0) {
+            throw new Error(`path[${i}] must be a non-negative integer (got ${JSON.stringify(n)})`);
+        }
+        out.push(n);
+    }
+    return out;
+}
+// Load-mutate-save: fetch current PGN, parse, apply mutation, re-export,
+// save with optimistic lock. Auto-saves so every tool call is atomic;
+// the LLM never sees intermediate state.
+async function applyMutation(args, mutator) {
+    const id = String(args.id);
+    const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
+    const g = raw;
+    if (typeof g.pgnContent !== "string")
+        throw new Error("prep file missing pgnContent");
+    const file = parsePGN(g.pgnContent);
+    let result;
     try {
-        const board = new Chess();
-        // chess.js loadPgn accepts full PGN incl. tags; loadPgn returns true on
-        // success or throws on newer versions. Wrap defensively.
-        board.loadPgn(pgn);
-        // history({verbose:true}) walks the mainline only; variations aren't
-        // exposed by chess.js's built-in PGN loader at time of writing. If the
-        // PGN carries parenthesised variations they get flattened.
-        const hist = board.history({ verbose: true });
-        if (hist.length === 0)
-            return [];
-        return hist.map(h => ({ san: h.san, fen: h.after }));
+        result = mutator(file);
     }
-    catch {
-        return null;
+    catch (err) {
+        if (err instanceof MutationError || err instanceof PathError) {
+            throw new Error(`mutation rejected: ${err.message}`);
+        }
+        throw err;
     }
+    const newPgn = exportPGN(result.file);
+    const expected = typeof args.expected_version === "number" ? args.expected_version : g.version;
+    const saved = await authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(id)}`, {
+        pgn: newPgn,
+        expected_version: expected,
+    });
+    const savedRow = saved;
+    return {
+        ok: true,
+        path: result.path,
+        version: savedRow.version,
+    };
 }
 // Rewrite availableMoves[].move UCI → SAN. The prep + position-stats
 // endpoints return moves in UCI on the wire — same LLM-readability
@@ -743,6 +932,24 @@ async function callToolInner(name, args) {
             const raw = await get("/api/chess/database/analyse", params);
             return convertAnalyseResponse(raw, fen);
         }
+        case "predict_human_move": {
+            const fen = resolveFenFromArgs(args);
+            const qs = new URLSearchParams();
+            qs.set("fen", fen);
+            if (typeof args.white_elo === "number")
+                qs.set("white_elo", String(args.white_elo));
+            if (typeof args.black_elo === "number")
+                qs.set("black_elo", String(args.black_elo));
+            if (typeof args.top === "number")
+                qs.set("top", String(args.top));
+            if (Array.isArray(args.prev_fens)) {
+                for (const p of args.prev_fens) {
+                    if (typeof p === "string" && p.length > 0)
+                        qs.append("prev_fen", p);
+                }
+            }
+            return authedRequest("GET", `/api/agent/predict-move?${qs.toString()}`);
+        }
         case "get_head_to_head":
             return get("/api/chess/players/h2h", {
                 a: Number(args.fide_id_a),
@@ -785,35 +992,54 @@ async function callToolInner(name, args) {
             return authedRequest("GET", `/api/agent/prep-files/search?q=${encodeURIComponent(String(args.query))}`);
         case "read_prep_file": {
             const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(String(args.id))}`);
-            // MCP layer adds the tree JSON view — backend stays pure PGN in/out.
-            // If parse fails the LLM still has the raw PGN text to work with.
-            if (raw && typeof raw === "object") {
-                const g = raw;
-                if (typeof g.pgnContent === "string") {
-                    const tree = pgnToTree(g.pgnContent);
-                    return { ...raw, tree };
-                }
-            }
-            return raw;
+            const g = raw;
+            if (typeof g.pgnContent !== "string")
+                throw new Error("prep file missing pgnContent");
+            const file = parsePGN(g.pgnContent);
+            return {
+                id: g.id,
+                version: g.version,
+                tags: file.tags,
+                tree: file.root,
+            };
         }
         case "create_prep_file":
             return authedRequest("POST", "/api/agent/prep-files", {
                 name: String(args.name),
-                pgn: typeof args.pgn === "string" ? args.pgn : undefined,
-            });
-        case "save_prep_file":
-            return authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(String(args.id))}`, {
-                pgn: String(args.pgn),
-                expected_version: typeof args.expected_version === "number" ? args.expected_version : undefined,
             });
         case "delete_prep_file":
             return authedRequest("DELETE", `/api/agent/prep-files/${encodeURIComponent(String(args.id))}`);
+        case "add_move":
+            return applyMutation(args, file => addMove(file, argPath(args), String(args.san)));
+        case "set_comment":
+            return applyMutation(args, file => setComment(file, argPath(args), typeof args.comment === "string" ? args.comment : ""));
+        case "set_nags":
+            return applyMutation(args, file => setNags(file, argPath(args), Array.isArray(args.nags) ? args.nags.map(String) : []));
+        case "set_annotations": {
+            const arrowsRaw = Array.isArray(args.arrows) ? args.arrows : [];
+            const highlightsRaw = Array.isArray(args.highlights) ? args.highlights : [];
+            const ann = (arrowsRaw.length === 0 && highlightsRaw.length === 0)
+                ? null
+                : { arrows: arrowsRaw, highlights: highlightsRaw };
+            return applyMutation(args, file => setAnnotations(file, argPath(args), ann));
+        }
+        case "delete_subtree":
+            return applyMutation(args, file => deleteSubtree(file, argPath(args)));
+        case "promote_variation":
+            return applyMutation(args, file => promoteVariation(file, argPath(args)));
+        case "set_tag":
+            return applyMutation(args, file => ({
+                file: setTag(file, String(args.key), String(args.value ?? "")),
+                path: [],
+            }));
         case "read_engine_usage_guide":
             return { guide: ENGINE_USAGE_DOC };
         case "read_prep_strategy_guide":
             return { guide: PREP_STRATEGY_DOC };
         case "read_prep_files_guide":
             return { guide: PREP_FILES_DOC };
+        case "read_pgn_authoring_guide":
+            return { guide: PGN_AUTHORING_DOC };
         case "prep_snapshot": {
             const me = Number(args.fide_id_me);
             const opp = Number(args.fide_id_opponent);

package/dist/pgn/exporter.js

@@ -0,0 +1,128 @@
+// PrepFile → PGN text. Deterministic — same tree always exports to the
+// same PGN modulo whitespace, so paths stay stable across
+// export→reparse cycles.
+import { codeFromColor } from "./types.js";
+// Standard PGN "seven tag roster" order. We emit these first (in the
+// order they appear in tags), then any extra tags in insertion order.
+const STR_ORDER = ["Event", "Site", "Date", "Round", "White", "Black", "Result"];
+export function exportPGN(file) {
+    const parts = [];
+    // Tag pairs. Ensure the seven-tag roster is present with sane
+    // defaults; other tags come after in whatever order the map yields.
+    const emittedTags = new Set();
+    const withDefaults = STR_ORDER.map(k => {
+        const value = file.tags[k];
+        emittedTags.add(k);
+        return [k, value ?? defaultTagValue(k)];
+    });
+    for (const [k, v] of Object.entries(file.tags)) {
+        if (emittedTags.has(k))
+            continue;
+        withDefaults.push([k, v]);
+        emittedTags.add(k);
+    }
+    for (const [k, v] of withDefaults) {
+        parts.push(`[${k} "${escapeTagValue(v)}"]`);
+    }
+    parts.push(""); // blank line between headers and movetext
+    // Movetext.
+    const rootAnnotation = renderNodeAnnotation(file.root);
+    const rootPrelude = rootAnnotation ? `${rootAnnotation} ` : "";
+    const movetext = rootPrelude + renderChildren(file.root.children, file.root.ply + 1, /* forceMoveNumber */ true);
+    const result = file.tags.Result ?? "*";
+    parts.push(`${movetext.trim()} ${result}`);
+    return parts.join("\n") + "\n";
+}
+function defaultTagValue(k) {
+    switch (k) {
+        case "Result": return "*";
+        case "Date": return "????.??.??";
+        default: return "?";
+    }
+}
+function escapeTagValue(v) {
+    return v.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+// Render a variation (a sequence of children starting at children[0] as
+// mainline and children[1..N] as parenthesised alternatives).
+function renderChildren(children, ply, forceMoveNumber) {
+    if (children.length === 0)
+        return "";
+    const mainline = children[0];
+    const alts = children.slice(1);
+    const bits = [];
+    // Emit the mainline node with move number as needed.
+    bits.push(renderMoveWithNumber(mainline, forceMoveNumber));
+    // Then, alternative variations that branch AT THIS POSITION —
+    // i.e. all siblings of the mainline child. They must fork from the
+    // same position (parent), so their move number matches the mainline's.
+    for (const alt of alts) {
+        bits.push(`(${renderMoveWithNumber(alt, /* forceMoveNumber */ true)}${renderVariationTail(alt)})`);
+    }
+    // Continue down the mainline. After emitting a variation, the next
+    // mainline move needs its own number rendered (Black's move after a
+    // variation should show "N... Nf6", etc.).
+    const forceNext = alts.length > 0;
+    bits.push(renderChildren(mainline.children, ply + 1, forceNext));
+    return bits.filter(Boolean).join(" ");
+}
+// Render the tail of a variation — everything after the variation's
+// first move (which is rendered by the parent). The recursion here
+// mirrors renderChildren but doesn't force a move number on the very
+// next move (unless a nested variation intervenes).
+function renderVariationTail(startNode) {
+    const suffix = renderChildren(startNode.children, startNode.ply + 1, /* forceMoveNumber */ false);
+    return suffix ? " " + suffix : "";
+}
+// Render a single move — number prefix + SAN + NAGs + comment.
+function renderMoveWithNumber(node, forceMoveNumber) {
+    if (!node.san)
+        return "";
+    const whiteToMove = (node.ply % 2) === 1;
+    let prefix = "";
+    if (whiteToMove) {
+        prefix = `${Math.ceil(node.ply / 2)}. `;
+    }
+    else if (forceMoveNumber) {
+        prefix = `${Math.ceil(node.ply / 2)}... `;
+    }
+    const suffix = renderNagsAndComment(node);
+    return `${prefix}${node.san}${suffix ? " " + suffix : ""}`.trimEnd();
+}
+function renderNagsAndComment(node) {
+    const bits = [];
+    if (node.nags && node.nags.length > 0) {
+        bits.push(node.nags.join(" "));
+    }
+    const commentBits = [];
+    if (node.comment && node.comment.trim().length > 0) {
+        commentBits.push(node.comment.trim());
+    }
+    const annotationCmd = renderNodeAnnotation(node);
+    if (annotationCmd)
+        commentBits.push(annotationCmd);
+    if (commentBits.length > 0) {
+        bits.push(`{${commentBits.join(" ")}}`);
+    }
+    return bits.join(" ");
+}
+// Build the [%cal ...] / [%csl ...] fragments if this node has arrows
+// or highlighted squares. Returns "" if none.
+function renderNodeAnnotation(node) {
+    if (!node.annotations)
+        return "";
+    const bits = [];
+    if (node.annotations.arrows.length > 0) {
+        const entries = node.annotations.arrows
+            .map(a => `${codeFromColor(a.color)}${a.from}${a.to}`)
+            .join(",");
+        bits.push(`[%cal ${entries}]`);
+    }
+    if (node.annotations.highlights.length > 0) {
+        const entries = node.annotations.highlights
+            .map(h => `${codeFromColor(h.color)}${h.square}`)
+            .join(",");
+        bits.push(`[%csl ${entries}]`);
+    }
+    return bits.join(" ");
+}

package/dist/pgn/mutations.js

@@ -0,0 +1,155 @@
+// Pure mutation functions on a PrepFile tree. Each returns a new
+// PrepFile (structural sharing where safe) plus the effective path of
+// the touched node, so tools can report where the LLM's request
+// actually landed after any rebalancing.
+//
+// All move-making mutations validate SAN against the current FEN via
+// chessops before touching the tree — a bad move surfaces as a thrown
+// error containing the FEN and rejected SAN, which the LLM can act on
+// (usually by re-checking the position it thought it was at).
+import { parseFen } from "chessops/fen";
+import { Chess } from "chessops/chess";
+import { parseSan } from "chessops/san";
+import { makeFen } from "chessops/fen";
+import { cloneOnPath, getNode, PathError } from "./paths.js";
+export class MutationError extends Error {
+}
+// Apply a SAN move as a new child at `path`. If the target already has
+// children, the new node is appended (becomes a variation, since
+// mainline is children[0]). Use promoteVariation to make the new node
+// the mainline afterwards if that's what you wanted.
+export function addMove(file, path, san) {
+    const parent = getNode(file.root, path);
+    const move = validateSan(parent.fen, san);
+    const posSetup = parseFen(parent.fen);
+    if (posSetup.isErr)
+        throw new MutationError(`bad parent FEN in tree: ${posSetup.error}`);
+    const pos = Chess.fromSetup(posSetup.value);
+    if (pos.isErr)
+        throw new MutationError(`bad parent position: ${pos.error}`);
+    const board = pos.value;
+    board.play(move);
+    const childFen = makeFen(board.toSetup());
+    const newNode = {
+        san,
+        fen: childFen,
+        ply: parent.ply + 1,
+        children: [],
+    };
+    const { root: newRoot, target } = cloneOnPath(file.root, path);
+    target.children = [...target.children, newNode];
+    return {
+        file: { tags: file.tags, root: newRoot },
+        path: [...path, target.children.length - 1],
+    };
+}
+// Replace the comment on the node at `path`. Passing empty string /
+// null clears it.
+export function setComment(file, path, comment) {
+    const { root: newRoot, target } = cloneOnPath(file.root, path);
+    const trimmed = (comment ?? "").trim();
+    if (trimmed)
+        target.comment = trimmed;
+    else
+        delete target.comment;
+    return { file: { tags: file.tags, root: newRoot }, path };
+}
+// Replace the NAG list. Empty array clears.
+export function setNags(file, path, nags) {
+    const cleaned = nags
+        .map(s => s.trim())
+        .filter(s => /^\$\d+$/.test(s));
+    const { root: newRoot, target } = cloneOnPath(file.root, path);
+    if (cleaned.length > 0)
+        target.nags = cleaned;
+    else
+        delete target.nags;
+    return { file: { tags: file.tags, root: newRoot }, path };
+}
+// Replace visual annotations (arrows + highlighted squares). Empty
+// arrows and highlights arrays clear the annotations entirely.
+export function setAnnotations(file, path, ann) {
+    const { root: newRoot, target } = cloneOnPath(file.root, path);
+    const isEmpty = !ann || (ann.arrows.length === 0 && ann.highlights.length === 0);
+    if (isEmpty)
+        delete target.annotations;
+    else
+        target.annotations = { arrows: ann.arrows, highlights: ann.highlights };
+    return { file: { tags: file.tags, root: newRoot }, path };
+}
+// Delete the node at `path` and all its descendants. Refuses to delete
+// the root. Returns the path of the deleted node's parent for the
+// caller's convenience.
+export function deleteSubtree(file, path) {
+    if (path.length === 0)
+        throw new MutationError("cannot delete root");
+    const parentPath = path.slice(0, -1);
+    const removeIdx = path[path.length - 1];
+    const { root: newRoot, target: parent } = cloneOnPath(file.root, parentPath);
+    if (removeIdx < 0 || removeIdx >= parent.children.length) {
+        throw new PathError(`delete index ${removeIdx} out of bounds`, path);
+    }
+    parent.children = parent.children.filter((_, i) => i !== removeIdx);
+    return { file: { tags: file.tags, root: newRoot }, path: parentPath };
+}
+// Promote the node at `path` to be its parent's first child (the
+// mainline). Silently no-ops if it's already the mainline. Refuses on
+// root (root has no parent to promote against).
+export function promoteVariation(file, path) {
+    if (path.length === 0)
+        throw new MutationError("cannot promote root");
+    const parentPath = path.slice(0, -1);
+    const idx = path[path.length - 1];
+    if (idx === 0)
+        return { file, path }; // already mainline
+    const { root: newRoot, target: parent } = cloneOnPath(file.root, parentPath);
+    const promoted = parent.children[idx];
+    const rest = parent.children.filter((_, i) => i !== idx);
+    parent.children = [promoted, ...rest];
+    return { file: { tags: file.tags, root: newRoot }, path: [...parentPath, 0] };
+}
+// Set or clear a tag. Passing null / empty removes.
+export function setTag(file, key, value) {
+    const cleanedKey = key.trim();
+    if (!cleanedKey)
+        throw new MutationError("tag key required");
+    const newTags = { ...file.tags };
+    if (value === null || value === "")
+        delete newTags[cleanedKey];
+    else
+        newTags[cleanedKey] = value;
+    return { tags: newTags, root: file.root };
+}
+// SAN validation: parses via chessops from the parent FEN. Throws a
+// MutationError with the FEN + rejected SAN so the LLM sees what
+// position it was actually attacking.
+function validateSan(fen, san) {
+    const setup = parseFen(fen);
+    if (setup.isErr)
+        throw new MutationError(`bad parent FEN: ${setup.error}`);
+    const pos = Chess.fromSetup(setup.value);
+    if (pos.isErr)
+        throw new MutationError(`bad parent position: ${pos.error}`);
+    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.`);
+    }
+    return move;
+}
+// Utility: report the path of a node reference. Used when a tool wants
+// to tell the LLM where the mutation landed after any rebalancing.
+export function pathOf(root, target) {
+    const stack = [{ node: root, path: [] }];
+    while (stack.length > 0) {
+        const { node, path } = stack.pop();
+        if (node === target)
+            return path;
+        for (let i = 0; i < node.children.length; i++) {
+            stack.push({ node: node.children[i], path: [...path, i] });
+        }
+    }
+    return null;
+}
+// Re-exports so index.ts only imports from mutations.
+export { getNode, getParent } from "./paths.js";

package/dist/pgn/parser.js

@@ -0,0 +1,117 @@
+// PGN → PrepFile. Uses chessops for the heavy lifting (SAN parsing,
+// legality, FEN generation) and walks the resulting parse tree into
+// our compact PrepNode shape.
+//
+// ChessBase annotations ([%cal ...], [%csl ...]) get stripped out of
+// the comment text and reified into the node's `annotations` field.
+// Unknown [%foo bar] blocks are dropped silently — the LLM won't be
+// writing arbitrary commands, and preserving unknown ones adds noise.
+import { parsePgn, startingPosition } from "chessops/pgn";
+import { parseSan } from "chessops/san";
+import { makeFen } from "chessops/fen";
+import { opposite } from "chessops/util";
+import { colorFromCode, } from "./types.js";
+const CAL_RE = /\[%cal\s+([^\]]+)\]/g;
+const CSL_RE = /\[%csl\s+([^\]]+)\]/g;
+const ANY_CMD_RE = /\[%[a-z]+\s+[^\]]+\]/g;
+// Parse a comment string, splitting out visual annotations from prose.
+export function parseCommentAnnotations(comment) {
+    const arrows = [];
+    const highlights = [];
+    for (const m of comment.matchAll(CAL_RE)) {
+        for (const entry of m[1].split(",")) {
+            const e = entry.trim().match(/^([GCRBOY])([a-h][1-8])([a-h][1-8])$/i);
+            if (e)
+                arrows.push({ color: colorFromCode(e[1]), from: e[2].toLowerCase(), to: e[3].toLowerCase() });
+        }
+    }
+    for (const m of comment.matchAll(CSL_RE)) {
+        for (const entry of m[1].split(",")) {
+            const e = entry.trim().match(/^([GCRBOY])([a-h][1-8])$/i);
+            if (e)
+                highlights.push({ color: colorFromCode(e[1]), square: e[2].toLowerCase() });
+        }
+    }
+    const text = comment.replace(ANY_CMD_RE, "").replace(/\s+/g, " ").trim();
+    const annotations = arrows.length || highlights.length ? { arrows, highlights } : undefined;
+    return { text, annotations };
+}
+// Parse full PGN → PrepFile. Throws on unrecoverable errors (no games,
+// invalid starting FEN). Illegal SAN moves in the movetext are skipped
+// silently — matches the frontend's tolerant behaviour so a game with
+// one typo doesn't nuke the whole tree.
+export function parsePGN(pgn) {
+    const games = parsePgn(pgn);
+    if (games.length === 0)
+        throw new Error("no games in PGN");
+    const game = games[0];
+    const tags = {};
+    game.headers.forEach((value, key) => { tags[key] = value; });
+    const startResult = startingPosition(game.headers);
+    if (startResult.isErr) {
+        throw new Error(`invalid starting position: ${startResult.error}`);
+    }
+    const startPos = startResult.value;
+    const rootFen = makeFen(startPos.toSetup());
+    const root = { san: null, fen: rootFen, ply: 0, children: [] };
+    // Root-level comment on the game (rare, but supported).
+    const gameComments = game.moves.comments;
+    if (gameComments && gameComments.length > 0) {
+        const parsed = parseCommentAnnotations(gameComments.join(" "));
+        if (parsed.text)
+            root.comment = parsed.text;
+        if (parsed.annotations)
+            root.annotations = parsed.annotations;
+    }
+    const build = (childNode, treeParent, pos, ply) => {
+        if (!childNode.data || typeof childNode.data.san !== "string")
+            return;
+        const san = childNode.data.san;
+        let nodeFen;
+        if (san === "--") {
+            // Null move — flip side, clear en-passant.
+            pos.turn = opposite(pos.turn);
+            pos.epSquare = undefined;
+            nodeFen = makeFen(pos.toSetup());
+        }
+        else {
+            const move = parseSan(pos, san);
+            if (!move)
+                return; // skip illegal — chessops tolerates the rest of the tree
+            pos.play(move);
+            nodeFen = makeFen(pos.toSetup());
+        }
+        const node = { san, fen: nodeFen, ply, children: [] };
+        // Comment on this move (both "starting comments" attached to
+        // variations and "after-move comments" — we fold both into the
+        // node's own comment; the LLM doesn't need the PGN's positional
+        // subtlety here).
+        const combined = [];
+        if (Array.isArray(childNode.data.startingComments))
+            combined.push(...childNode.data.startingComments);
+        if (Array.isArray(childNode.data.comments))
+            combined.push(...childNode.data.comments);
+        if (combined.length > 0) {
+            const parsed = parseCommentAnnotations(combined.join(" "));
+            if (parsed.text)
+                node.comment = parsed.text;
+            if (parsed.annotations)
+                node.annotations = parsed.annotations;
+        }
+        if (Array.isArray(childNode.data.nags) && childNode.data.nags.length > 0) {
+            node.nags = childNode.data.nags.map((n) => `$${n}`);
+        }
+        treeParent.children.push(node);
+        for (const grandchild of childNode.children) {
+            // chessops shares position state across siblings; we need a fresh
+            // clone per variation branch.
+            const forked = pos.clone();
+            build(grandchild, node, forked, ply + 1);
+        }
+    };
+    for (const child of game.moves.children) {
+        const forked = startPos.clone();
+        build(child, root, forked, 1);
+    }
+    return { tags, root };
+}

package/dist/pgn/paths.js

@@ -0,0 +1,55 @@
+// Path-based addressing for the LLM. The frontend uses UUIDs but they
+// regenerate every parse, so we can't use them across sessions. Paths
+// are child-index arrays — deterministic across parse/export cycles as
+// long as we don't reorder children on export.
+export class PathError extends Error {
+    path;
+    constructor(msg, path) {
+        super(`${msg} (path=${JSON.stringify(path)})`);
+        this.path = path;
+    }
+}
+// Resolve a path to a node reference. Throws PathError if the path
+// escapes the tree — that's ALWAYS the LLM's fault, and the message
+// tells it exactly where things fell apart.
+export function getNode(root, path) {
+    let cur = root;
+    for (let i = 0; i < path.length; i++) {
+        const idx = path[i];
+        if (!Number.isInteger(idx) || idx < 0 || idx >= cur.children.length) {
+            throw new PathError(`path segment ${i} = ${idx} is out of bounds; parent has ${cur.children.length} children`, path);
+        }
+        cur = cur.children[idx];
+    }
+    return cur;
+}
+// Get the parent of the node at `path` plus this node's index in its
+// parent's children array. Returns null if path refers to the root.
+export function getParent(root, path) {
+    if (path.length === 0)
+        return null;
+    const parentPath = path.slice(0, -1);
+    const parent = getNode(root, parentPath);
+    const index = path[path.length - 1];
+    return { parent, index };
+}
+// Read-only shallow clone helper the mutation functions use to avoid
+// hidden aliasing. Deep-clones nodes on the path from root to the
+// mutation target, leaving unrelated subtrees shared (they're
+// immutable-by-convention downstream, so this is safe and cheap).
+export function cloneOnPath(root, path) {
+    const newRoot = { ...root, children: [...root.children] };
+    const parentChain = [newRoot];
+    let cur = newRoot;
+    for (let i = 0; i < path.length; i++) {
+        const idx = path[i];
+        if (idx < 0 || idx >= cur.children.length) {
+            throw new PathError(`path segment ${i} = ${idx} out of bounds`, path);
+        }
+        const cloned = { ...cur.children[idx], children: [...cur.children[idx].children] };
+        cur.children[idx] = cloned;
+        cur = cloned;
+        parentChain.push(cur);
+    }
+    return { root: newRoot, target: cur, parentChain };
+}

package/dist/pgn/types.js

@@ -0,0 +1,21 @@
+// Compact tree types the LLM works with. No stable ids — chessops
+// regenerates them per parse — so we address nodes by PATH: the array
+// of child indices from the root. [] is the root, [0] is root's first
+// child, [0, 1] is the second child of the first child, etc.
+//
+// Paths ARE stable across parse/export/reparse cycles because move
+// order is deterministic and we don't rearrange children on export.
+// Named colours as they appear in the parsed tree. The wire format uses
+// single-letter codes (G, R, Y, C, B, O); the tree uses these longer
+// names to match how the frontend represents them.
+export const COLOR_NAMES = ["green", "red", "yellow", "light-blue", "dark-blue", "orange"];
+const COLOR_CODE_TO_NAME = {
+    G: "green", R: "red", Y: "yellow", C: "light-blue", B: "dark-blue", O: "orange",
+};
+const COLOR_NAME_TO_CODE = Object.fromEntries(Object.entries(COLOR_CODE_TO_NAME).map(([code, name]) => [name, code]));
+export function colorFromCode(code) {
+    return COLOR_CODE_TO_NAME[code.toUpperCase()] ?? "green";
+}
+export function codeFromColor(color) {
+    return COLOR_NAME_TO_CODE[color] ?? "G";
+}

package/docs/pgn-authoring.md

@@ -0,0 +1,163 @@
+# PGN authoring guide
+
+You author prep files by mutating a tree, not by writing PGN text. The MCP layer holds a parser+exporter (chessops-backed) so every mutation call load-mutates-saves atomically — you only ever address nodes, never raw text. No paren-counting, no move-numbering, no SAN typos surviving your edit.
+
+## Path addressing
+
+Nodes are addressed by **path**: an array of child indices from the root.
+
+- `[]` — the root position (empty board state, before any move).
+- `[0]` — the first mainline move (root's first child).
+- `[0, 0]` — the second ply on the mainline.
+- `[0, 1]` — a variation branching after the first move (sibling of `[0, 0]`).
+- `[0, 0, 0, 1]` — a variation branching at the third ply.
+
+`children[0]` is always the mainline; `children[1..N]` are alternative variations in declaration order. `promote_variation` swaps this order.
+
+## Workflow
+
+The mutation tool set is:
+
+- `read_prep_file(id)` → returns `{version, tags, tree}`. Every node in `tree` has `san`, `fen`, `ply`, optional `comment`, `nags`, `annotations`, and `children`.
+- `add_move(id, path, san)` — appends a new child of `path`. If `path` already has children, the new node becomes a variation. Returns the effective path of the new node.
+- `set_comment(id, path, comment)` — replace comment. Empty string clears.
+- `set_nags(id, path, nags)` — replace NAG list. Empty array clears.
+- `set_annotations(id, path, {arrows, highlights})` — replace visual annotations. Empty arrays clear.
+- `delete_subtree(id, path)` — remove node + descendants. Refuses to delete the root.
+- `promote_variation(id, path)` — make the node at `path` its parent's mainline.
+- `set_tag(id, key, value)` — set/clear a game-level tag.
+
+Every mutation **auto-saves** with optimistic locking. Response is `{ok: true, path, version}`. Pass the returned `version` as `expected_version` on your next mutation to catch concurrent edits.
+
+## Typical build order
+
+1. `read_prep_file` — see what's there.
+2. `add_move` to extend the mainline: `add_move(id, [], "e4")` then `add_move(id, [0], "c5")` etc.
+3. `add_move` for a variation at some node: `add_move(id, [0, 0], "Nc3")` adds Nc3 as a sibling of the current mainline's move 2.
+4. `set_comment` for plans / prep-signal, `set_nags` for evaluations, `set_annotations` for arrows and squares — always on the node the annotation belongs to.
+5. `promote_variation` if a variation is more important than the current mainline.
+6. `delete_subtree` to prune.
+
+Every step returns the new `version`; carry it forward.
+
+## Variations vs prose
+
+**Variations are moves, not sentences.** This was the biggest failure mode of raw-PGN authoring — LLMs writing "if Black plays Be6 White responds with f3" as prose. In the tree model there's no such temptation: variations are `add_move` calls at the branching node.
+
+Prose comments are for what MOVES cannot say:
+
+- **Plans**: `{Plan: exchange dark-square bishops, then break with f5.}`
+- **Prep-signal**: `{Firouzja plays this in 32 games since 2023, scores 41%.}`
+- **Interpretation the app can't derive**: `{IQP structure; Black's plan is …Nb4.}`
+- **Practical layer beyond the objective eval**: `{Objectively equal, but Black must remember 8 precise moves; White plays this blindfolded.}`
+
+Prose is NEVER for:
+
+- Move sequences ("then Nf3, then Bg5, ...") — use variations.
+- Move recommendations ("here White should play h4") — add_move it.
+- Restating the eval a NAG already conveys.
+
+## Move-judgment symbols (NAGs)
+
+NAGs are the compact way to attach an evaluation to a move. Pass as `$N` strings to `set_nags`.
+
+| NAG   | Symbol  | Meaning                                                        |
+|-------|---------|----------------------------------------------------------------|
+| `$1`  | `!`     | Good move                                                      |
+| `$2`  | `?`     | Mistake                                                        |
+| `$3`  | `!!`    | Brilliant move                                                 |
+| `$4`  | `??`    | Blunder                                                        |
+| `$5`  | `!?`    | Interesting / speculative                                      |
+| `$6`  | `?!`    | Dubious                                                        |
+| `$10` | `=`     | Equal                                                          |
+| `$13` | `∞`     | **Unclear** — position genuinely hard to evaluate              |
+| `$14` | `⩲`     | White slightly better                                          |
+| `$15` | `⩱`     | Black slightly better                                          |
+| `$16` | `±`     | White clearly better                                           |
+| `$17` | `∓`     | Black clearly better                                           |
+| `$18` | `+−`    | Winning for White                                              |
+| `$19` | `−+`    | Winning for Black                                              |
+| `$36` | `↑`     | With initiative                                                |
+| `$40` | `→`     | With attack                                                    |
+| `$44` | `=/∞`   | **Compensation** for the material                              |
+| `$132`| `⇆`     | With counterplay                                               |
+| `$140`| `∆`     | With the idea …                                                |
+| `$146`| `N`     | **Novelty** — this move has not been played before at this level |
+
+### Eval → NAG thresholds (the rule)
+
+Engine numbers go into the NAG, not into prose. Convert the eval to the correct NAG once and be done.
+
+| Engine eval (White POV) | NAG (White ahead)       | NAG (Black ahead)       |
+|-------------------------|-------------------------|-------------------------|
+| `\|eval\| < 0.25`         | `$10` (=)               | `$10` (=)               |
+| `0.25 ≤ \|eval\| < 0.6`   | `$14` (⩲)               | `$15` (⩱)               |
+| `0.6 ≤ \|eval\| < 1.3`    | `$16` (±)               | `$17` (∓)               |
+| `\|eval\| ≥ 1.3`          | `$18` (+−)              | `$19` (−+)              |
+| Sharp, hard to evaluate | `$13` (∞)               | `$13` (∞)               |
+
+**Don't paste raw engine numbers into comments.** `{Stockfish gives +0.35}` is noise — `$14` is the signal. Same for `{Lc0 says +0.15}`.
+
+**Don't name the engine unless it adds signal.** Naming Stockfish adds nothing to a `$14` on a routine position. Naming it makes sense when there's a mismatch worth flagging: `$14 {Human predictor gives 47% win at 2200 vs 2600 — the Elo gap does the practical work.}`
+
+### When prose ADDS to the NAG
+
+Prose is worth writing when the NAG *understates* something the human should know:
+
+Good (NAG says equal, prose adds the practical wrinkle):
+```
+set_comment(id, path, "Lc0 still gives Black a small pull — dark-square control is long-term, engine horizon can't quite reach it.")
+set_nags(id, path, ["$10"])
+```
+
+Good (NAG tells the truth, prose flags a mismatch worth noting):
+```
+set_comment(id, path, "Human predictor: 47% win at 2200 vs 2600 — the Elo gap does the practical work despite the small objective edge.")
+set_nags(id, path, ["$14"])
+```
+
+Bad (prose duplicates the NAG, adds nothing):
+```
+set_comment(id, path, "Stockfish gives +0.35 for White here.")
+set_nags(id, path, ["$14"])
+```
+
+## Visual annotations (arrows + coloured squares)
+
+`set_annotations(id, path, {arrows, highlights})` sets both together (an atomic replacement — pass both current and new). Passing empty arrays clears.
+
+Colours (both arrows and squares): `green`, `red`, `yellow`, `light-blue`, `dark-blue`, `orange`.
+
+Usage conventions:
+
+| Colour     | Typical use                                    |
+|------------|------------------------------------------------|
+| green      | Good move / plan / key square for you          |
+| red        | Threat / opponent's target / danger square     |
+| yellow     | Worth-noting / candidate                       |
+| light-blue | Neutral pointer / diagram note                 |
+| dark-blue  | Alternative / secondary idea                   |
+| orange     | Attention / warning                            |
+
+**Keep it light.** 1–3 arrows per node and 2–3 highlighted squares is plenty. Twenty arrows is noise, not signal — pick the most important ones. Highlights are labels, not decoration.
+
+Example:
+```
+set_annotations(id, path, {
+  arrows: [
+    { color: "green", from: "f2", to: "f4" },
+    { color: "green", from: "c1", to: "h6" },
+  ],
+  highlights: [
+    { color: "green", square: "g6" },
+    { color: "red",   square: "h6" },
+  ],
+})
+```
+Renders as a green f2→f4 arrow, a green c1→h6 arrow, a green square on g6, and a red square on h6 — attached to whichever node's path you specified.
+
+## Errors and how to recover
+
+- **Illegal SAN**: `add_move` validates against the position and rejects illegal moves with a message including the position's FEN. Re-check what position you thought you were at, then retry.
+- **Path out of bounds**: happens if you call a mutation with a path from an older read that's been changed since. Re-read the tree, recompute paths, retry.
+- **Version conflict (409)**: someone (the user in the app, or a parallel agent session) edited the file since your last read. Re-read, decide whether to merge or override, retry with the new version.

package/docs/prep-files-guide.md

@@ -25,40 +25,18 @@ Six tools:
 
 Duplicate files are the #1 way to lose your user's trust in this system.
 
-## PGN structure
-
-Real chess prep files are PGN with parenthesised variations. Learn the shape:
-
-```pgn
-[Event "Prep vs Firouzja (Black) — 2026-07-23"]
-[White "Firouzja, Alireza"]
-[Black "Van Foreest, Jorden"]
-[Date "2026.07.23"]
-
-1. e4 c5 2. Nf3 d6 3. d4 cxd4 4. Nxd4 Nf6 5. Nc3 a6 6. Be3 e5 7. Nb3
-{Main line. Firouzja plays this in 68% of his English Attacks (32 games, 2023-2025).}
-7... Be6 8. f3
-(8. Qd2 Nbd7 9. f3 h5 {Sideline he tried once and lost — probably patched.})
-8... Nbd7 9. Qd2 h5
-{Critical position for us. Lc0 at multipv=3 gives:
- - h5: +0.12 (main line, active)
- - Be7: +0.08 (calm, more classical)
- - Rc8: 0.00 (Stockfish preferred)}
-
-*
-```
+## 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.
+
+Minimum you should know before calling `save_prep_file`:
+
+- Mainline = your top recommendation. Alternative candidates go in parenthesised variations at the branching move.
+- **Variations are MOVES**, not prose describing moves. `7...Be6 (7...h5 8.Nd5)` — never `{if Black plays h5 White responds with Nd5}`.
+- **Plans, prep-signal, and interpretation** go in `{curly-brace comments}`. Cite tool output; don't invent chess prose.
+- `Event` tag is the file's user-facing name.
 
-The pieces:
-
-- **PGN tag pairs at the top** (`[Key "Value"]`) — `Event` is the name you show the user. `White` / `Black` set the game headers. `Date` is standard.
-- **Mainline** = your top recommendation. Numbered SAN moves separated by whitespace.
-- **Variations** in parentheses `(...)` at the branching move. Nesting is allowed but be conservative — three deep is a lot.
-- **Comments** in curly braces `{...}` between moves. This is where you cite tool output:
-  - `{Lc0 says +0.15 in this line vs 0.00 for the alternative}`
-  - `{Firouzja plays this in 32/47 games with Black. Scores 41%.}`
-  - `{Stockfish sees h4 as a tactical shot; Lc0 disagrees. Deep look needed.}`
-- **NAG glyphs** for evaluations at a move (optional): `$1` (!), `$2` (?), `$3` (!!), `$4` (??), `$6` (=), `$10` (=), `$14` (+/=). Placed right after the SAN: `7. Nb3 $1`.
-- **Result marker** at the end: `*` for unfinished (prep files are always unfinished), `1-0`, `0-1`, `1/2-1/2`.
+Full details, NAG table, arrow/highlight syntax, and worked example: `read_pgn_authoring_guide`.
 
 ## Editing without breaking the tree
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.17.0",
+  "version": "0.23.0",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {
@@ -43,6 +43,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "chess.js": "^1.4.0",
+    "chessops": "^0.15.1",
     "zod": "^3.23.0"
   },
   "devDependencies": {