@chessceo/mcp 0.15.0 → 0.17.0

package/dist/index.js

@@ -35,6 +35,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");
 // ── HTTP ────────────────────────────────────────────────────────────
 //
 // Two auth flavours coexist:
@@ -58,6 +59,12 @@ const AUTHED_TOOLS = new Set([
     "list_cloud_engines",
     "stop_cloud_engine",
     "cloud_analyse",
+    "list_prep_files",
+    "search_prep_files",
+    "read_prep_file",
+    "create_prep_file",
+    "save_prep_file",
+    "delete_prep_file",
 ]);
 function isAuthedToolCall(body) {
     if (!body || typeof body !== "object")
@@ -185,11 +192,15 @@ const TOOLS = [
                 },
                 line: {
                     type: "string",
-                    description: "Move sequence in SAN, space-separated, no move numbers required. Example: 'e4 e5 Nf3'. Leave empty for the starting position.",
+                    description: "Move sequence in SAN from the starting position, space-separated, no move numbers required. Example: 'e4 e5 Nf3'. Leave empty for startpos. Alias: `moves` (same thing).",
+                },
+                moves: {
+                    type: "string",
+                    description: "SAN moves to apply on top of `fen` (or on top of startpos if no fen). Same shape as `line`. Use this when you have a starting FEN and want to walk from there — e.g. fen='<game tabiya>', moves='b4 a5 c3' to explore that continuation. Wins over `line` if both are set.",
                 },
                 fen: {
                     type: "string",
-                    description: "Alternative to `line` — raw FEN of the target position.",
+                    description: "Starting position as FEN. Combine with `moves` to walk from there, or use alone.",
                 },
                 limit: {
                     type: "integer",
@@ -210,7 +221,15 @@ const TOOLS = [
             properties: {
                 fen: {
                     type: "string",
-                    description: "FEN of the position to look up.",
+                    description: "Starting position as FEN. Combine with `moves` to walk from there.",
+                },
+                moves: {
+                    type: "string",
+                    description: "Optional SAN moves to apply on top of `fen` (or on top of startpos). Example: fen='<tabiya>', moves='b4 a5'.",
+                },
+                line: {
+                    type: "string",
+                    description: "Synonym for `moves` from the starting position; kept for compatibility.",
                 },
                 limit: {
                     type: "integer",
@@ -219,18 +238,22 @@ const TOOLS = [
                     description: "Number of top continuations to return.",
                 },
             },
-            required: ["fen"],
         },
     },
     {
         name: "analyse",
         description: "Short Stockfish evaluation at a position. Returns the top-N candidate moves with score (centipawns from side-to-move POV, positive = advantage; or mate distance) and the principal variation for each. Defaults: 2s think time, top-3 lines. PV moves come back in SAN (e4, Nf3, Bxc4 — not UCI). Free (no cloud instance needed) — use liberally.\n\n" +
             "GROUNDING: cite this tool's actual output when you claim things about positions. Don't invent evaluations from general principles or training data — if you don't have engine output for a FEN, call this. Compute is cheap.\n\n" +
+            "Position input is flexible — pass `fen`, or `moves` from startpos, or `fen + moves` to walk from an arbitrary position. Also see the flip-side-to-move threat check in read_engine_usage_guide.\n\n" +
             "Use this to sanity-check candidate lines from get_position_stats or get_player_preparation — human game frequency tells you what people play, engine evaluation tells you what's actually good.",
         inputSchema: {
             type: "object",
             properties: {
-                fen: { type: "string", description: "FEN of the position to analyse." },
+                fen: { type: "string", description: "Starting position as FEN (defaults to startpos)." },
+                moves: {
+                    type: "string",
+                    description: "Optional SAN moves to apply on top of `fen` (or on top of startpos). Example: fen='<tabiya>', moves='b4 a5'.",
+                },
                 movetime_ms: {
                     type: "integer",
                     minimum: 100,
@@ -244,7 +267,6 @@ const TOOLS = [
                     description: "Number of candidate lines to return (default 3).",
                 },
             },
-            required: ["fen"],
         },
     },
     {
@@ -338,12 +360,17 @@ const TOOLS = [
             "• Lc0 is practical eval — trust it for 'which side is easier?' 'which candidate is best when Stockfish shows several as equal?' Lc0 sees long-term positional factors Stockfish's fixed search can miss.\n" +
             "• When they agree → high confidence. When they disagree → look at both scores and reason WHY (Stockfish sharply higher = tactic Lc0 missed; Lc0 higher = long-term positional edge past Stockfish's horizon). Never dismiss either — the disagreement is the signal.\n\n" +
             "Contempt (`contempt`) skews Lc0 (only Lc0 — Stockfish always stays objective) toward White (positive) or Black (negative). Practical range -20..+20. Use it to find non-objective 'practical' ideas or when the user needs to steer toward fighting/solid lines with a specific colour. Do NOT quote a contempt-biased eval as objective — cross-check with Stockfish.\n\n" +
+            "Also useful: pass `moves` on top of `fen` to explore a variation without computing FENs yourself (e.g. fen='<tabiya>', moves='b4 a5 c3'). And the flip-side-to-move threat check documented in the guide is a great free trick.\n\n" +
             "For the full guide including worked examples, call the `read_engine_usage_guide` tool.\n\n" +
             "Not for casual questions — this costs real money per second. Use the free `analyse` tool (single Stockfish, 2s) or `get_position_stats` for anything that doesn't require deep prep.",
         inputSchema: {
             type: "object",
             properties: {
-                fen: { type: "string", description: "FEN of the position to analyse." },
+                fen: { type: "string", description: "Starting position as FEN. Combine with `moves` to walk from there." },
+                moves: {
+                    type: "string",
+                    description: "Optional SAN moves to apply on top of `fen` (or on top of startpos). Example: fen='<tabiya>', moves='b4 a5 c3' analyses the position after those three moves.",
+                },
                 movetime_ms: {
                     type: "integer",
                     minimum: 100,
@@ -366,6 +393,84 @@ const TOOLS = [
             required: ["fen"],
         },
     },
+    {
+        name: "list_prep_files",
+        description: "List every prep file the user has (all games inside their dedicated AI Prep collection). Returns id, PGN tags (Event, White, Black, Date, etc. — read the Event tag for the user-facing name), size, updated_at. ALWAYS call this before create_prep_file to check for existing coverage — creating a second 'Prep vs Firouzja' when one already exists is a common LLM failure. If the user has many, use search_prep_files with a query to narrow down.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "search_prep_files",
+        description: "Text search over the user's prep files (matches PGN headers, comments, and content). Use this instead of list_prep_files when you know a keyword — e.g. search_prep_files(query='Firouzja') or search_prep_files(query='Najdorf').",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Free-text query (opponent name, opening name, event keyword)." },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Prep file id, from list_prep_files or search_prep_files." },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        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.",
+        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.",
+                },
+            },
+            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.",
+        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"],
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Prep file id." },
+            },
+            required: ["id"],
+        },
+    },
     {
         name: "read_engine_usage_guide",
         description: "Returns the full chess.ceo engine-usage guide: when to trust Stockfish (objective truth) vs Lc0 (practical eval), how to read disagreements between them, and how to use Lc0 contempt to find non-objective 'practical' ideas. Call this ONCE per session before running expensive `cloud_analyse` calls or when the user asks WHY the engines gave certain scores. Same content is also available as the `engine_usage_primer` prompt (for clients that surface prompts as slash commands), but many clients do not expose prompts to the model — this tool works everywhere.",
@@ -376,6 +481,11 @@ const TOOLS = [
         description: "Returns the full chess.ceo prep-strategy guide: why win% is one weight not a verdict, why prep is a two-player game with symmetric information (opponent sees your history too), how sample size and recency change the reading, when 'revealed weaknesses' are actionable vs already patched, how to use move-order tricks with the `trs` field, and how to calibrate surprise (rare secondary lines inside the existing repertoire, not big first-move switches). Call this ONCE per session before recommending an opening plan, especially when the user is preparing for a specific real opponent.",
         inputSchema: { type: "object", properties: {} },
     },
+    {
+        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.",
+        inputSchema: { type: "object", properties: {} },
+    },
     {
         name: "prep_snapshot",
         description: "One call, three parallel fetches at the same position: opponent's stats on their side, your stats on your side, and the 11.7M-game general database at that position. Use this while walking the opening tree — one round trip instead of three separate calls, and you can compare the three views directly (e.g. opponent has 2 games here but the general DB has 8k → prep candidate).",
@@ -483,6 +593,24 @@ function convertCloudSnapshotResponse(raw, startFen) {
     }
     return raw;
 }
+function pgnToTree(pgn) {
+    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 }));
+    }
+    catch {
+        return null;
+    }
+}
 // Rewrite availableMoves[].move UCI → SAN. The prep + position-stats
 // endpoints return moves in UCI on the wire — same LLM-readability
 // concern as engine PVs, and the same wrapper-only fix. Passes the
@@ -500,18 +628,26 @@ function convertAvailableMovesToSAN(raw, fen) {
     }
     return raw;
 }
-// Resolve a starting FEN from either the `fen` or `line` argument the tool
-// received. Same logic prep_snapshot already had inline — extracted so we
-// can reuse it wherever we need to walk a SAN line to a concrete FEN
-// (e.g. for UCI→SAN conversion of availableMoves).
+// Resolve a starting FEN from any combination of `fen`, `line`, and
+// `moves` the tool received. Three modes, all valid:
+//
+//   fen alone                → use as-is
+//   line/moves alone         → walk from startpos
+//   fen + moves (or line)    → walk from that fen
+//
+// `line` is the historical field name from the backend's prep endpoint;
+// `moves` is the flexible-input name we now surface for LLM ergonomics
+// ("start from this FEN and play these moves next"). They're synonyms
+// here — same SAN sequence, same chess.js walker. `moves` wins if both
+// happen to be provided.
 function resolveFenFromArgs(args) {
     const fenArg = typeof args.fen === "string" ? args.fen.trim() : "";
-    if (fenArg)
-        return fenArg;
+    const movesArg = typeof args.moves === "string" ? args.moves.trim() : "";
     const lineArg = typeof args.line === "string" ? args.line.trim() : "";
-    const board = new Chess();
-    if (lineArg) {
-        for (const raw of lineArg.split(/\s+/)) {
+    const sequence = movesArg || lineArg;
+    const board = fenArg ? new Chess(fenArg) : new Chess();
+    if (sequence) {
+        for (const raw of sequence.split(/\s+/)) {
             const san = raw.replace(/^\d+\.+/, "");
             if (!san)
                 continue;
@@ -519,7 +655,7 @@ function resolveFenFromArgs(args) {
                 board.move(san);
             }
             catch {
-                throw new Error(`bad SAN token '${raw}' in line`);
+                throw new Error(`bad SAN token '${raw}' in moves`);
             }
         }
     }
@@ -561,15 +697,26 @@ async function callToolInner(name, args) {
         case "get_player_profile":
             return get("/api/chess/players/profile", { fideId: Number(args.fide_id) });
         case "get_player_preparation": {
+            // Prefer sending `line` to the backend when the caller specified moves
+            // WITHOUT a fen — the backend then attaches the cumulative-line SAN to
+            // each move in the response (nicer for the LLM's follow-up walks).
+            // When a fen was supplied, always resolve the effective position
+            // client-side and send just fen — the backend can't reconstruct
+            // history it didn't see anyway.
+            const fenArg = typeof args.fen === "string" ? args.fen.trim() : "";
+            const movesArg = typeof args.moves === "string" ? args.moves.trim() : "";
+            const lineArg = typeof args.line === "string" ? args.line.trim() : "";
             const params = {
                 fideId: Number(args.fide_id),
                 color: String(args.color),
                 compact: "true",
             };
-            if (typeof args.line === "string" && args.line.length > 0)
-                params.line = args.line;
-            if (typeof args.fen === "string" && args.fen.length > 0)
-                params.fen = args.fen;
+            if (fenArg || movesArg) {
+                params.fen = resolveFenFromArgs(args);
+            }
+            else if (lineArg) {
+                params.line = lineArg;
+            }
             if (typeof args.limit === "number")
                 params.limit = args.limit;
             if (typeof args.offset === "number")
@@ -578,7 +725,7 @@ async function callToolInner(name, args) {
             return convertAvailableMovesToSAN(raw, resolveFenFromArgs(args));
         }
         case "get_position_stats": {
-            const fen = String(args.fen);
+            const fen = resolveFenFromArgs(args);
             const raw = await get("/api/chess/database/main", {
                 fen,
                 limit: typeof args.limit === "number" ? args.limit : 20,
@@ -587,7 +734,7 @@ async function callToolInner(name, args) {
             return convertAvailableMovesToSAN(raw, fen);
         }
         case "analyse": {
-            const fen = String(args.fen);
+            const fen = resolveFenFromArgs(args);
             const params = { fen };
             if (typeof args.movetime_ms === "number")
                 params.movetime_ms = args.movetime_ms;
@@ -621,7 +768,7 @@ async function callToolInner(name, args) {
         case "stop_cloud_engine":
             return authedRequest("DELETE", `/api/agent/cloud-engines/${encodeURIComponent(String(args.contract_id))}`);
         case "cloud_analyse": {
-            const fen = String(args.fen);
+            const fen = resolveFenFromArgs(args);
             const body = { fen };
             if (typeof args.movetime_ms === "number")
                 body.movetime_ms = args.movetime_ms;
@@ -632,10 +779,41 @@ async function callToolInner(name, args) {
             const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
             return convertCloudSnapshotResponse(raw, fen);
         }
+        case "list_prep_files":
+            return authedRequest("GET", "/api/agent/prep-files");
+        case "search_prep_files":
+            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;
+        }
+        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 "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 "prep_snapshot": {
             const me = Number(args.fide_id_me);
             const opp = Number(args.fide_id_opponent);

package/docs/prep-files-guide.md

@@ -0,0 +1,125 @@
+# Prep files guide
+
+You can save chess prep to the user's chess.ceo account and read it back across sessions. This is the persistence layer that turns your analysis from ephemeral chat into a durable, viewable-in-app repertoire.
+
+## The mental model
+
+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:
+
+- `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
+- `delete_prep_file(id)` — soft delete (user can restore from app)
+
+## 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:
+
+1. `list_prep_files` (if the user has ≤20-30 files) or `search_prep_files(query=<opponent name>)` for their key term
+2. Read the ones that look relevant
+3. Decide: extend an existing one (save_prep_file) or genuinely start fresh (create_prep_file)
+
+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)}
+
+*
+```
+
+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`.
+
+## 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.
+
+Common LLM failure modes to catch yourself doing:
+
+- **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.
+
+## 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:
+
+1. Re-read the file to see what changed.
+2. Merge your edits with theirs.
+3. Retry the save 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).
+
+## Grounding
+
+Same rule as everywhere else in this MCP: **cite tool output in your PGN comments, don't invent chess prose**. A prep file that reads "White has practical chances" without a tool call to back it up is worse than a file that says "TODO: run cloud_analyse here". The user can view the file; if the commentary doesn't match the actual engine output, they see it.
+
+Concrete pattern:
+
+```
+7. Nb3 {Lc0 at movetime=2000 gives +0.14 for White in the resulting IQP structure.
+Stockfish scores 0.00 — the disagreement is the long-term positional weight Lc0
+sees on the c6 pawn. Verified by running cloud_analyse at move 12 and confirming
+Lc0's evaluation persists.}
+```
+
+vs
+
+```
+7. Nb3 {A strong positional move that gives White good chances.}
+```
+
+The first is what earns trust; the second is what makes the file worthless.
+
+## Naming conventions
+
+For the [Event] tag (which is the user-visible file name):
+
+- Opponent prep: `"Prep vs <Player> (<Color>) — <YYYY-MM-DD>"`
+- Opening study: `"<Opening> — <side>"` e.g. `"Najdorf 6.Bg5 — Black side"`
+- Position analysis: `"<Position description> — <date>"`
+
+Keep it short enough to fit in a picker (30-40 chars). Long titles get truncated in the app UI.
+
+## When to create vs extend
+
+- User asks "prep me against X" and no file matches → create.
+- User asks "check line Y for our Firouzja prep" and a file matches → extend that file with new variations, save with expected_version.
+- User asks "I found a novelty in the Najdorf" and a Najdorf file exists → extend.
+- Rule of thumb: if the user's request semantically overlaps with an existing file's [Event] name or main opening line, extend.
+
+## Icons and appearance
+
+The user sees your files in a collection called "AI Prep" with a 🤖 icon under folder `/mcp` in their chess.ceo app. This is intentional — they can tell at a glance which prep came from you, and they can browse / edit / delete from the app just like their manual work. Your files are first-class citizens on their account.

package/package.json

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