@chessceo/mcp 0.30.2 → 0.31.2

package/docs/pgn-authoring.md

@@ -1,70 +1,142 @@
 # 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. Overlapping prefixes with an existing branch **join** (same SAN from the same position IS the same move) — see below.
+- **`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}, ...] }
+```
+
+**Mainline + variation at a branch 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]
+// 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"]}
 ```
 
+### add_move / add_line join on existing SAN
+
+`add_move` and `add_line` are **idempotent on SAN**: if a child with that SAN already exists under the parent, they return the existing child's id rather than creating a duplicate. In chess, same SAN from the same position IS the same move — two sibling children with SAN "d5" would be nonsensical.
+
+This means you can freely send `add_line` batches that share a prefix — they build a clean Y-shape at the divergence point, not duplicate spines.
+
+```
+// Two Ruy Lopez lines that share the first 5 plies, diverging at Black's 3rd move:
+{op: "add_line", parent_id: "r", sans: ["e4","e5","Nf3","Nc6","Bb5","Nf6","O-O"]}   // Berlin
+{op: "add_line", parent_id: "r", sans: ["e4","e5","Nf3","Nc6","Bb5","a6","Ba4"]}     // Steinitz
+
+// Result: single spine e4→e5→Nf3→Nc6→Bb5, then Bb5 has TWO children (Nf6, a6).
+// Both add_line responses report every id on the resulting line, including
+// the joined-prefix nodes, so you can address any of them next.
+```
+
+**Consequence for building repertoires**: you don't have to hand-decompose overlapping variations into a mainline + variation pair. Just send each variation as its own `add_line` from the same starting `parent_id`; the tree will de-dup the shared prefix automatically. Use `promote_variation` afterwards to pick which continuation is the mainline at the branch.
+
+## What good looks like
+
+Before writing your first substantial file, call `read_example_prep_files` — it returns two reference PGNs by a strong human coach. Read the full files; the rhythm and comment density are hard to convey in isolated snippets. What follows is a taste, not a substitute.
+
+**From an Italian Fried Liver overview (both sides, 1600+ audience):**
+
+```
+5. Nxf7 {Most principled. Interesting is that not long ago computers were saying this
+is winning for white. But modern strong engines almost immediately proclaim 0.00}
+  Bxf2+ 6. Kf1 Qe7 7. Nxh8 d5 8. exd5 Nd4
+9. d6 $1
+  (9. c3 {Most played, and weak engines still like this move, but fail to spot}
+    Bg4 10. Qa4+ Nd7 $1 {And black is winning} 11. Kxf2 Qh4+)
+9... Qxd6 (9... cxd6 $2 10. Kxf2 Ng4+ 11. Kg1 $18 {and the d6 pawn blocks Qc5})
+```
+
+Note the register: *"weak engines still like this move, but fail to spot"* — one sentence orients the reader and cites the failure mode. `$1` marks the resource, `$2` marks the trap, `$18` marks the resulting winning position — every glyph earns its place. No `{Stockfish gives 0.00 depth 22}` verbose engine chatter.
+
+**From a Najdorf 6.f4 White repertoire (2200+ audience):**
+
+```
+6... e6 {a common continuation, but usually in the Najdorf, e6 setups give white
+enough time to put their pieces in good positions, and here its no exception.}
+7. Qf3 {And black is already in danger. White just plans to finish development with
+Be3, long castle and g4.}
+  (7. g4 {is too early:} e5 $1 8. Nf5 Nc6 {[%cal Gg7g6]})
+7... Qc7
+8. g4 {White has easy play}
+  Nc6 9. Nxc6 bxc6 10. g5 Nd7 11. Bd2 $16 {[%cal Ge1c1,Gh2h4]}
+```
+
+Two `[%cal]` arrows on the last move show the whole plan (castle long, push h4). *"White has easy play"* is a five-word verdict that beats three sentences of hedged eval prose. The parenthesised sideline shows exactly WHY 7.g4 is premature — one variation, one point.
+
+**What both files share:**
+
+- Named citations: Karpov–Beliavsky, Nepomniachtchi, Mamedov–Volokitin, John Ludvig Hammer 2024. Concrete anchors the reader can look up.
+- Practical framing: *"objectively black has no compensation for the pawn, it does seem black still has some practical chances"* — separates objective from practical explicitly.
+- Move-order guidance in the reader's voice: *"Here it's easy for white to mess up the move order. If black wants to go exd4, you should be ready — d3 is a way to remember that white should castle first."*
+- Terse verdicts at line ends: *"White is a clean pawn up."* *"black is cooked"* *"All correspondence games here ended in a draw."* *"With a very unclear position."*
+- Zero decorative annotation: `[%csl Rf7]` on the Fried Liver f7 attack is one square, one colour, all signal.
+
+Study `read_example_prep_files` before writing at scale. The gap between "correct" prep and "prep worth reading" is entirely commentary discipline, and these two files are the target.
+
 ## 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.

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.2",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {