@chessceo/mcp 0.30.2 → 0.31.0

package/dist/pgn/mutations.js

@@ -1,7 +1,7 @@
 // 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.
+// PrepFile (structural sharing where safe) plus the node_id of the
+// touched node (the LLM addresses nodes by content-derived id — see
+// paths.ts — so tools return the id, not the path).
 //
 // All move-making mutations validate SAN against the current FEN via
 // chessops before touching the tree — a bad move surfaces as a thrown
@@ -11,15 +11,15 @@ 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";
+import { cloneOnPath, deriveNodeId, 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);
+// Add a SAN move as a new child under `parentPath`. Appends — becomes
+// a variation if the parent already has children (mainline is
+// children[0]). Use promoteVariation afterwards to switch mainline.
+// Returns the new node's stable id (derived from parent.id + san).
+export function addMove(file, parentPath, san) {
+    const parent = getNode(file.root, parentPath);
     const move = validateSan(parent.fen, san);
     const posSetup = parseFen(parent.fen);
     if (posSetup.isErr)
@@ -30,19 +30,44 @@ export function addMove(file, path, san) {
     const board = pos.value;
     board.play(move);
     const childFen = makeFen(board.toSetup());
+    const newId = deriveNodeId(parent.id, san);
     const newNode = {
+        id: newId,
         san,
         fen: childFen,
         ply: parent.ply + 1,
         children: [],
     };
-    const { root: newRoot, target } = cloneOnPath(file.root, path);
+    const { root: newRoot, target } = cloneOnPath(file.root, parentPath);
     target.children = [...target.children, newNode];
     return {
         file: { tags: file.tags, root: newRoot },
-        path: [...path, target.children.length - 1],
+        id: newId,
     };
 }
+// Add a linear sequence of moves under `parentPath` — one call for a
+// whole variation instead of N add_move calls. Each move becomes the
+// mainline child (children[0]) of the previous. Returns the ids and
+// SANs of every added node so the LLM can address any of them next.
+export function addLine(file, parentPath, sans) {
+    if (sans.length === 0)
+        throw new MutationError("add_line requires at least one san");
+    let cur = file;
+    let curPath = parentPath;
+    const line = [];
+    for (const san of sans) {
+        const step = addMove(cur, curPath, san);
+        cur = step.file;
+        // The move we just appended is the parent's last child — extend
+        // the walked path with that child index so the next move lands on
+        // top of it (extending the line, not creating a sibling).
+        const parent = getNode(cur.root, curPath);
+        const childIdx = parent.children.length - 1;
+        curPath = [...curPath, childIdx];
+        line.push({ id: step.id, san });
+    }
+    return { file: cur, line };
+}
 // Replace the comment on the node at `path`. Passing empty string /
 // null clears it.
 export function setComment(file, path, comment) {
@@ -52,7 +77,7 @@ export function setComment(file, path, comment) {
         target.comment = trimmed;
     else
         delete target.comment;
-    return { file: { tags: file.tags, root: newRoot }, path };
+    return { file: { tags: file.tags, root: newRoot }, id: target.id };
 }
 // Replace the NAG list. Empty array clears.
 export function setNags(file, path, nags) {
@@ -64,7 +89,7 @@ export function setNags(file, path, nags) {
         target.nags = cleaned;
     else
         delete target.nags;
-    return { file: { tags: file.tags, root: newRoot }, path };
+    return { file: { tags: file.tags, root: newRoot }, id: target.id };
 }
 // Replace visual annotations (arrows + highlighted squares). Empty
 // arrows and highlights arrays clear the annotations entirely.
@@ -75,11 +100,10 @@ export function setAnnotations(file, path, ann) {
         delete target.annotations;
     else
         target.annotations = { arrows: ann.arrows, highlights: ann.highlights };
-    return { file: { tags: file.tags, root: newRoot }, path };
+    return { file: { tags: file.tags, root: newRoot }, id: target.id };
 }
 // 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.
+// the root. Returns the id of the deleted node's parent.
 export function deleteSubtree(file, path) {
     if (path.length === 0)
         throw new MutationError("cannot delete root");
@@ -90,34 +114,38 @@ export function deleteSubtree(file, path) {
         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 };
+    return { file: { tags: file.tags, root: newRoot }, id: parent.id };
 }
 // 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).
+// root (root has no parent to promote against). Returns the promoted
+// node's id (unchanged by the reorder — IDs don't depend on sibling
+// position).
 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
+    if (idx === 0) {
+        // Already mainline — return the existing id without touching anything.
+        const target = getNode(file.root, path);
+        return { file, id: target.id };
+    }
     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] };
+    return { file: { tags: file.tags, root: newRoot }, id: promoted.id };
 }
 // Replace the stored ceoEval on the node at `path`. Passing null clears.
-// This is what auto_evaluate calls per-node; also exposed as an op the
-// LLM can invoke directly if it wants to overwrite a stale eval.
+// This is what auto_evaluate / cloud_analyse(node_id) calls per-node.
 export function setCeoEval(file, path, ev) {
     const { root: newRoot, target } = cloneOnPath(file.root, path);
     if (ev === null || (!ev.sf && !ev.lc0 && !ev.nag))
         delete target.ceoEval;
     else
         target.ceoEval = ev;
-    return { file: { tags: file.tags, root: newRoot }, path };
+    return { file: { tags: file.tags, root: newRoot }, id: target.id };
 }
 // Set or clear a tag. Passing null / empty removes.
 export function setTag(file, key, value) {
@@ -144,7 +172,7 @@ function validateSan(fen, san) {
     const board = pos.value;
     const move = parseSan(board, san);
     if (!move) {
-        throw new MutationError(`illegal SAN "${san}" at fen "${fen}". Call describe_position on this fen to see the full list of legal moves.`);
+        throw new MutationError(`illegal SAN "${san}" at fen "${fen}". Call describe_position on this node to see the full list of legal moves.`);
     }
     return move;
 }
@@ -163,4 +191,4 @@ export function pathOf(root, target) {
     return null;
 }
 // Re-exports so index.ts only imports from mutations.
-export { getNode, getParent } from "./paths.js";
+export { getNode, getParent, buildIdIndex, resolveNodeId, NodeIdError, ROOT_ID } from "./paths.js";

package/dist/pgn/parser.js

@@ -11,6 +11,7 @@ import { parseSan } from "chessops/san";
 import { makeFen } from "chessops/fen";
 import { opposite } from "chessops/util";
 import { colorFromCode, } from "./types.js";
+import { deriveNodeId, ROOT_ID } from "./paths.js";
 const CAL_RE = /\[%cal\s+([^\]]+)\]/g;
 const CSL_RE = /\[%csl\s+([^\]]+)\]/g;
 const CEO_EVAL_RE = /\[%ceo-eval\s+([^\]]+)\]/g;
@@ -105,7 +106,7 @@ export function parsePGN(pgn) {
     }
     const startPos = startResult.value;
     const rootFen = makeFen(startPos.toSetup());
-    const root = { san: null, fen: rootFen, ply: 0, children: [] };
+    const root = { id: ROOT_ID, 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) {
@@ -135,7 +136,13 @@ export function parsePGN(pgn) {
             pos.play(move);
             nodeFen = makeFen(pos.toSetup());
         }
-        const node = { san, fen: nodeFen, ply, children: [] };
+        const node = {
+            id: deriveNodeId(treeParent.id, san),
+            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

package/dist/pgn/paths.js

@@ -1,7 +1,40 @@
-// 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.
+// Node addressing for the LLM: stable content-derived IDs, resolved
+// internally to array-of-child-indices `Path` for the mutation
+// implementation. LLM-facing tools never accept a path — they take a
+// `node_id` (or `parent_id` for add_move) and this module turns it
+// into the path the mutation code walks.
+//
+// The ID → path index is built once per parse and read many times per
+// batch. Every mutation preserves IDs on unchanged nodes (IDs are pure
+// functions of parent.id + san, so adding/removing/promoting siblings
+// leaves every ID untouched), so callers don't need to rebuild the
+// index between ops in a batch — they just extend it with the newly
+// created node's id when applyMutations lands one.
+import { createHash } from "node:crypto";
+// Special ID for the root position (starting FEN, no move played).
+export const ROOT_ID = "r";
+// 8-hex-char content hash. Root is "r". Every other node's id is
+// derived from (parent.id, san). Two nodes with the same (parent, san)
+// can't co-exist as siblings in chess anyway, so within-parent
+// collisions are impossible. Cross-tree collisions in 32 bits at 1000
+// nodes are ~10^-4 — we throw on the rare hit rather than mask it.
+export function deriveNodeId(parentId, san) {
+    const h = createHash("sha256");
+    h.update(parentId);
+    h.update("|");
+    h.update(san);
+    return h.digest("hex").slice(0, 8);
+}
+// Bad-node-id errors so the LLM sees exactly what went wrong. Message
+// carries the offending id, which is often a copy-paste bug (missing
+// character, wrong file id, stale reference to a deleted node).
+export class NodeIdError extends Error {
+    nodeId;
+    constructor(msg, nodeId) {
+        super(`${msg} (node_id=${nodeId})`);
+        this.nodeId = nodeId;
+    }
+}
 export class PathError extends Error {
     path;
     constructor(msg, path) {
@@ -9,9 +42,40 @@ export class PathError extends Error {
         this.path = path;
     }
 }
+// Build the id → path index for a whole tree. Also detects the rare
+// collision (two nodes with the same 32-bit id) and throws so the
+// caller can surface a clear message.
+export function buildIdIndex(root) {
+    const index = new Map();
+    const walk = (node, path) => {
+        if (index.has(node.id)) {
+            throw new Error(`node id collision on "${node.id}" — two distinct nodes in the tree ` +
+                `hash to the same 32-bit id. This is statistically rare (~10^-4 at ` +
+                `1000 nodes); if you see this, please report the file so we can ` +
+                `widen the hash.`);
+        }
+        index.set(node.id, path);
+        for (let i = 0; i < node.children.length; i++) {
+            walk(node.children[i], [...path, i]);
+        }
+    };
+    walk(root, []);
+    return index;
+}
+// Resolve a node_id to a Path against a specific tree. Throws
+// NodeIdError with a message the LLM can act on.
+export function resolveNodeId(index, nodeId) {
+    const path = index.get(nodeId);
+    if (!path) {
+        throw new NodeIdError(`no node with this id in the tree. Either it was deleted since your ` +
+            `last read, you have a typo, or you're addressing a different file — ` +
+            `call read_prep_file to refresh`, nodeId);
+    }
+    return 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.
+// escapes the tree — used internally by the mutation code after
+// node_id → path resolution.
 export function getNode(root, path) {
     let cur = root;
     for (let i = 0; i < path.length; i++) {
@@ -33,10 +97,9 @@ export function getParent(root, path) {
     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).
+// Deep-clone nodes on the path from root to the mutation target,
+// leaving unrelated subtrees shared. Downstream code treats siblings
+// as immutable so this sharing is safe.
 export function cloneOnPath(root, path) {
     const newRoot = { ...root, children: [...root.children] };
     const parentChain = [newRoot];

package/dist/pgn/types.js

@@ -1,10 +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.
+// Compact tree types the LLM works with.
 //
-// Paths ARE stable across parse/export/reparse cycles because move
-// order is deterministic and we don't rearrange children on export.
+// Nodes are addressed by a stable, content-derived `id`:
+//   root.id = "r"
+//   node.id = first 8 hex chars of sha256(parent.id + "|" + san)
+//
+// The derivation is a pure function of the tree structure, so IDs
+// survive parse → mutate → export → reparse without needing to be
+// persisted in the PGN. Sibling insertions, deletions and variation
+// promotions all leave every other node's ID unchanged — the failure
+// mode of path-based addressing (later paths shifting when an earlier
+// op inserts a sibling) simply cannot happen. See src/pgn/paths.ts
+// for the id → path resolution used to power mutation calls.
+//
+// 32-bit width (8 hex chars) means birthday-collision probability
+// is ~10^-4 even at 1000 nodes — the largest prep files we see are
+// well under that. On the rare parse-time collision we throw a clear
+// error rather than persisting anything ambiguous.
 // 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.

package/docs/engine-usage.md

@@ -6,6 +6,16 @@ When you call `cloud_analyse`, chess.ceo runs Stockfish and Lc0 in parallel on t
 
 **Every claim you make about a position must trace back to actual engine output from this session.** Not from a book you were trained on, not from generic chess principles, not from a plausible-sounding pattern. If you don't have a Stockfish or Lc0 line for the exact FEN you're discussing, run one. Compute is cheap — `cloud_analyse` at ~2s each is fine to call 5-10 times while walking a tree; you can burn 20-30 seconds of billable time and it's still cents.
 
+### The node-id + quote_engine_eval protocol
+
+**When you're inside a prep file, call `cloud_analyse` with `file_id`+`node_id` — never with a hand-typed FEN.** The server derives the FEN from the tree node and, critically, **auto-stores the resulting eval on that node's `ceoEval`**. This is what makes engine attribution trustworthy end-to-end:
+
+1. `cloud_analyse({ id, node_id })` — runs analysis on the node's exact position, stores `{sf, lc0, nag}` on the node.
+2. Later, before you write "engines say X on this position" in a comment, call `quote_engine_eval({ id, node_id })` — it returns the stored eval or `null`.
+3. If `quote_engine_eval` returns `null`, you have no measurement to cite. **Do NOT infer an eval for a node from siblings, from children, or from a "position that looks similar."** Either analyse the node (`cloud_analyse`) or omit the number from your prose entirely.
+
+Concrete failure this rule blocks: the LLM says *"9...Bb7: both engines 0.00"* after only calling `cloud_analyse` on the child positions (post-1.d4, post-castling). Both continuations really returned 0.00, but the Bb7 node was never analysed, and the claim reads to the user as a measurement. With this protocol, `quote_engine_eval(node_id=Bb7)` would return null and the LLM would either analyse it or reword to *"both continuations run to 0.00, so this position looks balanced"* (soft inference, honestly labelled).
+
 **Concrete failure modes to avoid:**
 
 - Inventing an evaluation. If you say "this is +0.4 for White", that number must come from an engine call. Not a guess, not a vibe.

package/docs/pgn-authoring.md

@@ -1,68 +1,79 @@
 # 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.
+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 by id, never raw text or paths. No paren-counting, no move-numbering, no SAN typos surviving your edit, no index drift when a sibling is inserted.
 
-## Path addressing
+## Node id addressing
 
-Nodes are addressed by **path**: an array of child indices from the root.
+Every node has a stable **`id`** — the LLM's handle on that node across mutation calls.
 
-- `[]` — 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.
+- Root id is `"r"`.
+- Every other node id is an 8-hex-char content hash derived from `(parent.id, san)`.
+- **IDs never change when other nodes are added, deleted or promoted.** Sibling insertions do not shift ids. Variation promotion does not shift ids. A node's id is a pure function of its position in the tree's SAN structure.
+- **IDs are self-checking.** If you send a node_id the tree doesn't know, resolution fails immediately with a clear error — the LLM can't "make up" ids and have them silently work.
 
-`children[0]` is always the mainline; `children[1..N]` are alternative variations in declaration order. `promote_variation` swaps this order.
+Every read gives you the id on every node. Every mutation call takes `node_id` (or `parent_id` for add_move / add_line) and returns the id it landed on. You chain ids from one call to the next.
 
 ## Workflow
 
 Reading:
 
-- `read_prep_file(id)` → returns `{version, tags, tree}`. Every node in `tree` has `san`, `fen`, `ply`, optional `comment`, `nags`, `annotations`, and `children`.
+- `read_prep_file(id)` → returns `{version, tags, tree}`. Every node has `id`, `san`, `fen`, `ply`, optional `comment`, `nags`, `annotations`, `ceoEval`, 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 populate the persistent `ceoEval` (Stockfish + Lc0 numbers) on every node by running cloud_analyse on each position. **Does NOT set visible NAGs** — the numbers land in a hidden `[%ceo-eval]` tag so you can read them back later. NAG placement (`$1` `!`, `$14` `⩲`, `$16` `±`, `$18` `+−`, etc.) is your editorial call, not an automatic mapping — see the section on NAG discipline below. Skip nodes that already have a stored eval by default.
+- **`add_line(id, parent_id, sans[])`** — a whole linear variation in one op. Cleaner than N `add_move` ops for straight lines.
+- **`auto_evaluate(id, node_id?)`** — walk from a node and populate the persistent `ceoEval` (Stockfish + Lc0 numbers) on every descendant via cloud_analyse. **Does NOT set visible NAGs** — the numbers land in a hidden `[%ceo-eval]` tag so you can read them back later. NAG placement (`$1` `!`, `$14` `⩲`, `$16` `±`, `$18` `+−`, etc.) is your editorial call. Skip nodes that already have a stored eval 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.
+- `add_move(id, parent_id, san)` — appends a new child. If the parent has children, new node becomes a variation.
+- `add_line(id, parent_id, sans[])` — appends a whole linear continuation as a sequence of children.
+- `set_comment(id, node_id, comment)` — replace comment (empty string clears).
+- `set_nags(id, node_id, nags)` — replace NAGs (empty array clears).
+- `set_annotations(id, node_id, {arrows, highlights})` — replace visual annotations.
+- `delete_subtree(id, node_id)` — remove node + descendants.
+- `promote_variation(id, node_id)` — make the referenced node 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, plus any `set_nags` where you already have a clear judgment — novelty `$146`, `!?` speculative sac, obvious `?` blunder in a sideline you're rejecting).
+1. `read_prep_file` — see what's there. Every node has an `id` you'll pass to the mutation and engine/DB tools.
+2. `apply_mutations([...])` — one call with your whole intended build (a mix of `add_move` / `add_line` for structure, plus any `set_comment`/`set_annotations` you already know at author time, plus any `set_nags` where you already have a clear judgment — novelty `$146`, `!?` speculative sac, obvious `?` blunder in a sideline you're rejecting).
 3. `auto_evaluate(id)` — walk the tree and PERSIST engine numbers on every node. Does not touch visible NAGs. Cheap way to get every position's Stockfish + Lc0 read baked into the file for later reference.
 4. Re-read the file and add NAGs where they carry real signal (see NAG discipline below). Use individual mutation tools for surgical follow-ups (fix one comment, add one arrow, promote a specific variation, prune a branch).
 
 The build-cost math: a 200-move file via individual `add_move` calls is 200 saves ≈ 100+ seconds of tool overhead. The same file via one `apply_mutations` call is one save ≈ 500ms. Use batch by default.
 
-### Path math in a batch
+### Chaining node_ids across 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.
+Node ids are content-derived, so when you `add_move` inside a batch, the id of the new node is a deterministic function of the parent's id + the SAN. In practice: **use the id the previous op returned as the `parent_id` of the next op** (the batch response gives you each `node_id` in order, and `add_line` gives you the full `line: [{node_id, san}, …]`).
 
-For a linear mainline build from an empty file:
+Concretely, the response to a batch is:
 ```
-{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]
-...
+{ ok: true, results: [{node_id: "3c7f592e"}, {node_id: "22012be0"}, ...], version: 42 }
 ```
 
-For a variation at some point:
+If you know the tree ahead of time (writing from scratch), the deterministic recipe means you don't have to guess. But by far the easiest pattern is **`add_line` for straight lines, `add_move` for branch points** — you don't need to compute ids yourself.
+
+### Two clean batch patterns
+
+**Straight mainline:**
+```
+{op: "add_line", parent_id: "r", sans: ["e4","c5","Nf3","Nc6","Bb5"]}
+// → returns { node_id: "<id-of-Bb5>", line: [{node_id, san}, ...] }
 ```
-{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]
+
+**Mainline + variation at a branch point:**
+```
+// First, the mainline:
+{op: "add_line", parent_id: "r", sans: ["e4","c5","Nf3","d6"]}
+// → line[2] is the Nf3 node — grab its node_id, call it NF3.
+
+// Then the variation branching after Nf3:
+{op: "add_line", parent_id: NF3, sans: ["Nc6","Bb5","Bd7"]}
 ```
 
 ## Variations vs prose

package/docs/prep-files-guide.md

@@ -6,15 +6,21 @@ You can save chess prep to the user's chess.ceo account and read it back across
 
 The user has **one** collection dedicated to your work — labelled "AI Prep" in their chess.ceo app with a 🤖 icon. Inside it, each **prep file** is one PGN game with variations. You never see the collection itself; the tools operate directly on the files inside it.
 
-Six tools:
+File-level tools:
 
 - `list_prep_files` — show me all my prep files
 - `search_prep_files(query)` — find by opponent name / opening keyword
-- `read_prep_file(id)` — full PGN + parsed mainline tree + `version`
-- `create_prep_file(name, pgn?)` — new file, `name` becomes the [Event] tag
-- `save_prep_file(id, pgn, expected_version)` — replace the whole PGN
+- `read_prep_file(id)` — parsed tree (every node carries a stable `id`) + tags + `version`
+- `create_prep_file(name)` — new empty file, `name` becomes the [Event] tag
 - `delete_prep_file(id)` — soft delete (user can restore from app)
 
+Mutation tools (edit an existing file — you never touch raw PGN):
+
+- `apply_mutations(id, [...])` — batch: N ops in one save. **Primary build tool.**
+- `add_move`, `add_line`, `set_comment`, `set_nags`, `set_annotations`, `delete_subtree`, `promote_variation`, `set_tag` — individual ops for surgical follow-ups. See `read_pgn_authoring_guide` for the full mutation vocabulary.
+
+Every mutation call takes a `node_id` (or `parent_id` for add-style ops) and auto-saves. Nodes are addressed by stable content-derived id, not by path — sibling insertions / deletions / promotions never shift ids. Root id is `"r"`.
+
 ## The single most important habit
 
 **Before creating a new file, search for an existing one.** LLMs make three "Prep vs Firouzja" files in a row all the time. Always:
@@ -40,23 +46,22 @@ Full details, NAG table, arrow/highlight syntax, and worked example: `read_pgn_a
 
 ## Editing without breaking the tree
 
-You get the whole PGN back from `read_prep_file`, edit it in your head, send back via `save_prep_file`. There's no partial-patch API — small edits still resend the full text. The file is small (repertoire = maybe 5-20 KB), that's fine.
+You never send raw PGN. `read_prep_file` gives you the parsed tree with stable node ids; the mutation tools accept those ids and handle the parse/edit/serialize cycle for you. SAN is validated per mutation, move numbers are automatic, parenthesised variations are impossible to leave unbalanced.
 
-Common LLM failure modes to catch yourself doing:
+Failure modes the tool layer now blocks (that used to trip LLMs writing raw PGN):
 
-- **Unbalanced parentheses.** Every `(` needs a matching `)`. Count them if you added variations. The backend parses on save; if invalid, you get 400 with the parser error and have to retry.
-- **Bad SAN.** `Nfd7` where you meant `Nbd7`. Always trace the position in your head (or use the tree from read_prep_file's response) before writing a move.
-- **Forgotten move numbers.** `1. e4 c5 2. Nf3` — after each White move you need `<num>.`, after each Black move the number continues implicitly until the next full move. In variations at Black's move, PGN wants `2... Nc6`.
-- **Nested variations losing context.** `1.e4 e5 (1...c5 (2.Nf3 d6))` — the inner variation branches at `2.Nf3` off the c5 sideline, not off the mainline. This gets confusing fast; two levels is usually enough.
-- **Blank Event tag** — the user's list_prep_files response shows the Event tag as the name. Empty tag = "Untitled" everywhere.
+- **Unbalanced parentheses** — no longer possible; you address nodes, not text.
+- **Bad SAN** — every `add_move` / `add_line` validates against the parent's FEN. Illegal moves are rejected with the position's FEN in the error so you can call `describe_position` to see legal moves.
+- **Forgotten move numbers** — the exporter reconstructs them.
+- **Nested variations losing context** — `add_move(parent_id=X, san=…)` binds unambiguously to node X.
 
 ## Optimistic locking
 
-`read_prep_file` returns a `version` integer. Pass it back as `expected_version` on `save_prep_file`. If someone else (the user in the app, or a parallel agent session) updated the file since you read it, save returns `409 Conflict` with the current version. You should:
+`read_prep_file` returns a `version` integer. Pass it back as `expected_version` on any mutation. If someone else (the user in the app, or a parallel agent session) updated the file since you read it, the save returns `409 Conflict` with the current version. You should:
 
-1. Re-read the file to see what changed.
-2. Merge your edits with theirs.
-3. Retry the save with the new version.
+1. Re-read the file to see what changed (node ids are stable across the concurrent edit, so your local references may still work).
+2. Decide whether to merge or override.
+3. Retry with the new version.
 
 If you don't pass `expected_version`, it's last-write-wins — you might silently overwrite the user's manual edits. Only skip it when you know the file is untouched (e.g. you just created it).
 

package/package.json

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