@chessceo/mcp 0.19.0 → 0.24.0

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,194 @@
+# 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
+
+Reading:
+
+- `read_prep_file(id)` → returns `{version, tags, tree}`. Every node in `tree` has `san`, `fen`, `ply`, optional `comment`, `nags`, `annotations`, and `children`.
+
+Building (use these — one call for many ops):
+
+- **`apply_mutations(id, mutations[])`** — batch. This is the primary build tool. Send 100 mutations in one call → one load-parse-mutate-save cycle instead of 100. When you're writing a repertoire from scratch, EVERYTHING should go through this. Individual mutation tools are for surgical follow-up edits, not for bulk work.
+- **`auto_evaluate(id, path?)`** — walk the tree from `path` and auto-assign the right NAG to every node by running cloud_analyse on each position. Standard threshold table (below). Costs real engine time but frees you from hand-annotating evals. Skip nodes that already have a NAG by default.
+
+Per-op mutation tools (single-op calls, use for edits after the bulk build):
+
+- `add_move(id, path, san)` — appends a new child. If `path` has children, new node becomes a variation.
+- `set_comment(id, path, comment)` — replace comment (empty string clears).
+- `set_nags(id, path, nags)` — replace NAGs (empty array clears).
+- `set_annotations(id, path, {arrows, highlights})` — replace visual annotations.
+- `delete_subtree(id, path)` — remove node + descendants.
+- `promote_variation(id, path)` — make the node at `path` its parent's mainline.
+- `set_tag(id, key, value)` — set/clear a game-level PGN tag.
+
+All mutations **auto-save** with optimistic locking. Response includes the new `version`; pass it as `expected_version` on your next call to catch concurrent edits.
+
+## Typical build order
+
+1. `read_prep_file` — see what's there.
+2. `apply_mutations([...])` — one call with your whole intended build (all `add_move` for the moves and variations, plus any `set_comment`/`set_annotations` you already know at author time). Skip `set_nags` — auto_evaluate handles that.
+3. `auto_evaluate(id)` — walk the tree, get engine evals, assign NAGs. One shot.
+4. Individual mutation tools ONLY for surgical follow-ups (fix one comment, add one arrow, promote a specific variation, prune a branch).
+
+The build-cost math: a 200-move file via individual `add_move` calls is 200 saves ≈ 100+ seconds of tool overhead. The same file via one `apply_mutations` call is one save ≈ 500ms. Use batch by default.
+
+### Path math in a batch
+
+Paths in each mutation resolve against the tree AFTER previous ops in the batch. When you `add_move(path=[0], san='c5')`, the new c5 lands at `[0, 0]` if [0] had no children, or `[0, N]` if it had N. Your next mutation in the batch can address the new node directly. The tree is deterministic — you can compute all paths ahead of time.
+
+For a linear mainline build from an empty file:
+```
+{op: "add_move", path: [],        san: "e4"}   // lands at [0]
+{op: "add_move", path: [0],       san: "c5"}   // lands at [0, 0]
+{op: "add_move", path: [0, 0],    san: "Nf3"}  // lands at [0, 0, 0]
+{op: "add_move", path: [0, 0, 0], san: "d6"}   // lands at [0, 0, 0, 0]
+...
+```
+
+For a variation at some point:
+```
+{op: "add_move", path: [0, 0], san: "Nc3"}   // variation branching after move 2; lands at [0, 0, 1]
+{op: "add_move", path: [0, 0, 1], san: "d5"} // continue the variation; lands at [0, 0, 1, 0]
+```
+
+## 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.
+- **Describing a sibling variation you already added as a branch.** If move A has variation B added as `add_move(A, sibling)`, don't ALSO write `{if B then ...}` on A. The reader clicks B on the board — the branch is already there.
+
+## 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` (∞)               |
+
+**Prefer auto_evaluate for the NAG.** Don't hand-write NAGs when building — call `auto_evaluate(id)` after your build and it assigns the right glyph to every node from actual engine analysis. Manual `set_nags` is for overrides (mark a novelty with $146, flag a `$5 !?` piece sac).
+
+**Engine numbers in prose: brief only.** If you must reference a number, keep it compact:
+
+- Good: `{... +0.2}` — bare number at the end of a note
+- Bad: `{Stockfish depth 22 shows +0.25, Lc0 depth 18 shows +0.4, both engines agree}` — verbose noise
+
+**Don't name the engine unless it adds signal.** "SF: +0.15" for a routine position is noise. Name it when there's a mismatch worth flagging: `{Human predictor gives Black 47% win despite the -0.35 objective eval — Elo gap does the work.}`
+
+### 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.