@chessceo/mcp 0.46.0 → 0.49.0

package/README.md

@@ -1,23 +1,27 @@
 # @chessceo/mcp
 
-Model Context Protocol server for [chess.ceo](https://chess.ceo) — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts. Lets Claude, Cursor, and any other MCP host answer chess questions directly against real data instead of hallucinating.
+Model Context Protocol server for [chess.ceo](https://chess.ceo) — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts, cloud engine analysis, and (signed-in) a full read/write prep-file workflow. Lets Claude, Cursor, and any other MCP host answer chess questions directly against real data instead of hallucinating.
 
-No API key. No auth. No state. Free to use.
+Player/game lookups need no API key or auth. Cloud engines and prep-file tools need a `mcp_...` bearer token (see Auth below).
 
 ## What it can do
 
-The server exposes 8 tools that mirror the public GET API surface at `chess.ceo`:
+49 tools as of v0.49.0, mirroring the `chess.ceo` API surface. A few of the most-used:
 
 | Tool | What it answers |
 |---|---|
 | `search_player` | "Find FIDE ID for Magnus Carlsen" |
 | `get_player_profile` | "How strong is X, what do they play, who have they beaten" |
-| `get_player_preparation` | "What does X play against 1.e4? What's their win rate with the Najdorf?" |
+| `prepare_opponent` + `get_prep_position` | "What does X play against 1.e4? What's their win rate with the Najdorf?" |
 | `get_position_stats` | "From this position, which move scores best in the 11.7M-game database?" |
 | `get_head_to_head` | "What's the record between X and Y?" |
-| `list_live_tournaments` | "What's being broadcast live right now?" |
-| `list_tournament_players` | "Who's playing in tournament T?" |
-| `list_player_live_tournaments` | "Is X playing anywhere right now?" |
+| `list_live_tournaments` / `list_tournament_players` / `list_player_live_tournaments` | "What's being broadcast live right now? Who's playing? Is X in it?" |
+| `cloud_analyse` | "Run Stockfish + Lc0 on this position on my rented GPU instance" |
+| `read_prep_file` / `add_line` / `add_move` / `apply_mutations` | Read and edit your own repertoire/course PGNs stored server-side |
+| `auto_evaluate` / `deep_analyse` | Kick off a long-running engine-evaluation job over a whole prep file, poll it, cancel it |
+| `read_docs` | Bundled guides (engine usage, opening prep, prep-file conventions, PGN authoring, summary authoring) |
+
+Full tool inventory with categories lives in [`CLAUDE.md`](CLAUDE.md) under "Tools cheatsheet" — that's the maintained source of truth; this table is illustrative, not exhaustive.
 
 ## Install (Claude Desktop)
 
@@ -62,6 +66,25 @@ This repo is also a [Claude Code plugin marketplace](https://code.claude.com/doc
 
 Claude Code will pull the plugin from GitHub and wire the MCP server automatically. Enable "Sync automatically" in the marketplace UI if you want future updates fetched on push.
 
+## Auth (for cloud engines and prep files)
+
+Read-only chess data — player search, profiles, position stats, head-to-head, live tournaments — needs nothing. Cloud engine tools and your own prep-file tools (list/read/create/edit) need a `mcp_...` bearer token.
+
+- **Local (`npx`/Claude Desktop/Cursor):** set `CHESSCEO_TOKEN` in the server's `env` block:
+  ```json
+  {
+    "mcpServers": {
+      "chessceo": {
+        "command": "npx",
+        "args": ["-y", "@chessceo/mcp"],
+        "env": { "CHESSCEO_TOKEN": "mcp_..." }
+      }
+    }
+  }
+  ```
+  Get a token from your chess.ceo account settings.
+- **Remote (`mcp.chess.ceo/mcp`):** no config needed — calling an authed tool without a token triggers the host's normal OAuth flow (claude.ai, ChatGPT connectors) automatically.
+
 ## Try it
 
 Ask your model:
@@ -109,7 +132,7 @@ In Claude Desktop, edit `claude_desktop_config.json`:
 }
 ```
 
-Same 8 tools, same data, zero-install. Useful when the host can't spawn subprocesses (e.g. Claude.ai web, Claude mobile, ChatGPT connectors).
+Same tools, same data, zero-install. Bearer-authed tools (cloud engines, prep files) go through this host's OAuth flow instead of a config-file token. Useful when the host can't spawn subprocesses (e.g. Claude.ai web, Claude mobile, ChatGPT connectors).
 
 ## Self-host the HTTP transport
 

package/dist/index.js

@@ -20,7 +20,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { TOOLS } from "./tools.js";
 import { PROMPTS } from "./prompts.js";
-import { commentAntiPatterns, longLineWarning, noDescribeWarning, noStatsCheckWarning, positionsDescribed, positionsStatsChecked, } from "./warnings.js";
+import { commentAntiPatterns, longLineWarning, noDescribeWarning, noStatsCheckWarning, positionalNagOnIntermediateWarning, positionsDescribed, positionsStatsChecked, } from "./warnings.js";
 import { authContext, authedRequest, deleteGame, fetchGame, get, makeFileId, restoreGame, } from "./http.js";
 import { analysisToStoredEval, capPvsInResponse, convertCloudSnapshotResponse, fetchCompactEval, } from "./analysis/response.js";
 import { autoEvaluate, autoEvaluateCancel, autoEvaluateStatus, } from "./analysis/auto.js";
@@ -29,7 +29,7 @@ import { getNodeByPath, resolveFromNodeOrFen, storeEvalOnNode, } from "./analysi
 import { findPositionInCourses, readCourseAtPosition, runSfEval } from "./courses.js";
 import { applyBatchMutations, applyMutation, argNodeId, } from "./prep/mutations.js";
 import { listNodes, listTranspositions, readPrepFile, } from "./prep/read.js";
-import { createPrepFile, findPositionInFiles, listCollections, listPrepFiles, searchPrepFiles, } from "./prep/library.js";
+import { createCollection, createPrepFile, findPositionInFiles, listCollections, listPrepFiles, searchPrepFiles, } from "./prep/library.js";
 import { convertAvailableMovesToSAN, normalizeSourceForBackend, stripPositionResponse, trimGamesMovetext, } from "./response_transforms.js";
 // Tools that require an MCP token — cloud engine + prep-file tools
 // operate on the caller's own account so we can't service them
@@ -42,6 +42,7 @@ const AUTHED_TOOLS = new Set([
     "stop_cloud_engine",
     "cloud_analyse",
     "list_collections",
+    "create_collection",
     "list_prep_files",
     "search_prep_files",
     "find_position_in_files",
@@ -103,6 +104,7 @@ const ENGINE_USAGE_DOC = loadBundledDoc("engine-usage.md", "Engine usage guide")
 const PREP_STRATEGY_DOC = loadBundledDoc("prep-strategy.md", "Prep strategy guide");
 const PREP_FILES_DOC = loadBundledDoc("prep-files-guide.md", "Prep files guide");
 const PGN_AUTHORING_DOC = loadBundledDoc("pgn-authoring.md", "PGN authoring guide");
+const SUMMARY_AUTHORING_DOC = loadBundledDoc("summary-authoring.md", "Summary authoring guide");
 // Reference PGNs authored by a strong human coach. LLM pulls these when
 // it wants to see the commentary style, NAG discipline, and annotation
 // density we want it to hit. Kept as raw PGN so the LLM can parse them
@@ -110,6 +112,45 @@ const PGN_AUTHORING_DOC = loadBundledDoc("pgn-authoring.md", "PGN authoring guid
 // all intact) — not summarised into English.
 const EXAMPLE_OVERVIEW_PGN = loadBundledDoc("examples/italian-fried-liver.pgn", "Italian Fried Liver overview example");
 const EXAMPLE_REPERTOIRE_PGN = loadBundledDoc("examples/najdorf-6-f4-white.pgn", "Najdorf 6.f4 White repertoire example");
+// v0.48: consolidated the five `read_*_guide` / `read_example_prep_files`
+// tools into ONE `read_docs`. LLM lists what it wants; we return them
+// in a single response. Also cleaner: enumerating available docs in one
+// tool description (with per-doc "CALL WHEN" hints) beats surfacing
+// five almost-identical tools in the tool listing.
+const DOC_LIBRARY = {
+    "engine-usage": ENGINE_USAGE_DOC,
+    "opening-prep": PREP_STRATEGY_DOC,
+    "prep-files": PREP_FILES_DOC,
+    "pgn-authoring": PGN_AUTHORING_DOC,
+    "summary-authoring": SUMMARY_AUTHORING_DOC,
+    "examples/italian-fried-liver-overview": EXAMPLE_OVERVIEW_PGN,
+    "examples/najdorf-6-f4-repertoire": EXAMPLE_REPERTOIRE_PGN,
+};
+function readDocs(args) {
+    const raw = args.docs;
+    const requested = Array.isArray(raw)
+        ? raw.map(String).map(s => s.trim()).filter(s => s.length > 0)
+        : [];
+    if (requested.length === 0) {
+        throw new Error(`docs required — pass e.g. { docs: ["engine-usage", "pgn-authoring"] }. Available: ${Object.keys(DOC_LIBRARY).join(", ")}`);
+    }
+    const out = {};
+    const unknown = [];
+    for (const name of requested) {
+        if (name in DOC_LIBRARY) {
+            out[name] = DOC_LIBRARY[name];
+        }
+        else {
+            unknown.push(name);
+        }
+    }
+    const resp = { docs: out };
+    if (unknown.length > 0) {
+        resp.unknown = unknown;
+        resp.note = `unknown doc name(s): ${unknown.join(", ")}. Available: ${Object.keys(DOC_LIBRARY).join(", ")}`;
+    }
+    return resp;
+}
 // Log every tool call in and out. Keeps args + response payloads together
 // with a per-call duration so we can trace what the LLM asked for and what
 // it got back on the same journalctl line. Response is JSON-stringified and
@@ -397,6 +438,8 @@ async function callToolInner(name, args) {
             return readCourseAtPosition(args);
         case "list_collections":
             return listCollections(args);
+        case "create_collection":
+            return createCollection(args);
         case "list_prep_files":
             return listPrepFiles(args);
         case "search_prep_files":
@@ -461,7 +504,14 @@ async function callToolInner(name, args) {
             });
         }
         case "set_nags":
-            return applyMutation(args, (file, idIndex) => setNags(file, resolveNodeId(idIndex, argNodeId(args)), Array.isArray(args.nags) ? args.nags.map(String) : []));
+            return applyMutation(args, (file, idIndex) => {
+                const nagsArg = Array.isArray(args.nags) ? args.nags.map(String) : [];
+                const targetPath = resolveNodeId(idIndex, argNodeId(args));
+                const targetNode = getNodeByPath(file.root, targetPath);
+                const nagWarn = positionalNagOnIntermediateWarning(targetNode, nagsArg);
+                const step = setNags(file, targetPath, nagsArg);
+                return { ...step, ...(nagWarn ? { warning: nagWarn } : {}) };
+            });
         case "set_annotations": {
             const arrowsRaw = Array.isArray(args.arrows) ? args.arrows : [];
             const highlightsRaw = Array.isArray(args.highlights) ? args.highlights : [];
@@ -497,16 +547,8 @@ async function callToolInner(name, args) {
             const node = getNodeByPath(file.root, path);
             return { ceoEval: node.ceoEval ?? null };
         }
-        case "read_engine_usage_guide":
-            return { guide: ENGINE_USAGE_DOC };
-        case "read_opening_prep_guide":
-            return { guide: PREP_STRATEGY_DOC };
-        case "read_prep_files_guide":
-            return { guide: PREP_FILES_DOC };
-        case "read_pgn_authoring_guide":
-            return { guide: PGN_AUTHORING_DOC };
-        case "read_example_prep_files":
-            return { overview: EXAMPLE_OVERVIEW_PGN, repertoire: EXAMPLE_REPERTOIRE_PGN };
+        case "read_docs":
+            return readDocs(args);
         case "prep_snapshot": {
             const me = Number(args.fide_id_me);
             const opp = Number(args.fide_id_opponent);

package/dist/prep/library.js

@@ -71,6 +71,23 @@ export async function findPositionInFiles(args) {
         prep_files: games.map(projectGameRow),
     };
 }
+export async function createCollection(args) {
+    const title = String(args.title || "").trim();
+    if (!title)
+        throw new Error("title is required");
+    const folderPath = typeof args.folder_path === "string" ? args.folder_path.trim() : undefined;
+    const raw = await authedRequest("POST", PGN_BASE, {
+        title,
+        ...(folderPath ? { folderPath } : {}),
+    });
+    const collection = unwrap(raw);
+    return {
+        ok: true,
+        id: collection.id,
+        title: collection.title,
+        folder_path: collection.folderPath,
+    };
+}
 export async function createPrepFile(args) {
     const collectionId = typeof args.collection_id === "string" ? args.collection_id.trim() : "";
     if (!collectionId) {

package/dist/prep/mutations.js

@@ -19,7 +19,7 @@ import { exportPGN } from "../pgn/exporter.js";
 import { buildIdIndex, NodeIdError, PathError, resolveNodeId, ROOT_ID, } from "../pgn/paths.js";
 import { addLine, addMove, deleteSubtree, MutationError, promoteVariation, setAnnotations, setCeoEval, setComment, setNags, setTag, } from "../pgn/mutations.js";
 import { getNodeByPath } from "../analysis/file_handle.js";
-import { commentAntiPatterns, longLineWarning, noDescribeWarning, noStatsCheckWarning, } from "../warnings.js";
+import { commentAntiPatterns, longLineWarning, noDescribeWarning, noStatsCheckWarning, positionalNagOnIntermediateWarning, } from "../warnings.js";
 // Extract a node id from the args. Accepts either `node_id` or a
 // `parent_id` alias for the add-style tools. Throws with a helpful
 // message if malformed.
@@ -78,8 +78,14 @@ export function dispatchMutation(file, idIndex, op) {
             const all = [...commentWarns, ...(describeWarn ? [describeWarn] : [])];
             return { ...step, ...(all.length > 0 ? { warnings: all } : {}) };
         }
-        case "set_nags":
-            return setNags(file, resolve(nodeIdField("node_id")), Array.isArray(op.nags) ? op.nags.map(String) : []);
+        case "set_nags": {
+            const nagsArr = Array.isArray(op.nags) ? op.nags.map(String) : [];
+            const targetPath = resolve(nodeIdField("node_id"));
+            const targetNode = getNodeByPath(file.root, targetPath);
+            const nagWarn = positionalNagOnIntermediateWarning(targetNode, nagsArr);
+            const step = setNags(file, targetPath, nagsArr);
+            return { ...step, ...(nagWarn ? { warning: nagWarn } : {}) };
+        }
         case "set_annotations": {
             const arrows = Array.isArray(op.arrows) ? op.arrows : [];
             const highlights = Array.isArray(op.highlights) ? op.highlights : [];

package/dist/tools.js

@@ -466,6 +466,27 @@ export const TOOLS = [
             required: ["id"],
         },
     },
+    {
+        name: "create_collection",
+        description: "Create a new, empty PGN collection (a folder of prep files) — NOT a prep file itself. Use this when the user asks for a new file/course and `list_collections` shows nothing suitable to put it in; then call `create_prep_file` with the returned `id`.\n\n" +
+            "**Check `list_collections` first** — a duplicate folder with a slightly different name is the common failure mode here, same as `create_prep_file`.\n\n" +
+            "`folder_path` is optional (root if omitted) but should almost always be set — an ungrouped pile of top-level collections is exactly what this tool exists to avoid creating.\n\n" +
+            "Response: `{ok, id, title, folder_path}` — pass `id` to `create_prep_file` as `collection_id`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: {
+                    type: "string",
+                    description: "Collection name, shown in the user's file browser. Example: 'Sicilian Rauzer'.",
+                },
+                folder_path: {
+                    type: "string",
+                    description: "Virtual folder path, e.g. '/AI Organized/Sicilian Rauzer'. Omit for root.",
+                },
+            },
+            required: ["title"],
+        },
+    },
     {
         name: "create_prep_file",
         description: "Create a new (empty) prep file in the specified collection. `name` becomes the Event PGN tag. You then extend it with mutation tools (add_move, set_comment, …).\n\n" +
@@ -837,34 +858,41 @@ export const TOOLS = [
         },
     },
     {
-        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.",
-        inputSchema: { type: "object", properties: {} },
-    },
-    {
-        name: "read_opening_prep_guide",
-        description: "**CALL WHEN**: the user asks about OPENING PREPARATION — 'prep me against X', 'what should I play vs the Najdorf', 'help me build a repertoire against 1.e4', 'walk this opponent's Sveshnikov'. This guide is chess-and-analysis philosophy, not storage semantics.\n\n" +
-            "Covers: 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 choose between the GM-classical DB and the main DB, when to combine chesscom/lichess sources with FIDE, the three chess.com profile shapes (consistent / eclectic / split-personality), the reversed-colours scarcity trick, how to calibrate surprise (rare secondary lines inside the existing repertoire, not big first-move switches).\n\n" +
-            "Different tool: `read_prep_files_guide` covers the FILE STORAGE feature (how to list/create/save prep files) — call that only when about to manipulate files, not for opening questions.",
-        inputSchema: { type: "object", properties: {} },
-    },
-    {
-        name: "read_prep_files_guide",
-        description: "**CALL WHEN**: you're about to CREATE, LIST, SAVE, or DELETE a prep file — the persistent file storage feature. Not for opening prep philosophy (that's `read_opening_prep_guide`) and not for how to write PGN (that's `read_pgn_authoring_guide`).\n\n" +
-            "Covers: the AI Prep folder, when to list vs search vs create (avoid duplicate 'Prep vs Firouzja' files), optimistic locking with `version`, naming conventions for the [Event] tag, node-id addressing basics.",
-        inputSchema: { type: "object", properties: {} },
-    },
-    {
-        name: "read_pgn_authoring_guide",
-        description: "Returns the guide on how to write correct, useful PGN — mainline discipline, variations as moves (never prose describing moves), NAG symbols including novelty ($146), unclear ($13), compensation ($44) and the standard set, ChessBase arrow/coloured-square syntax ([%cal] / [%csl]), and common pitfalls the parser will reject. Call this ONCE per session before any save_prep_file call, or any time you're producing PGN output for the user.",
-        inputSchema: { type: "object", properties: {} },
-    },
-    {
-        name: "read_example_prep_files",
-        description: "**CALL WHEN**: about to write ANY prose commentary in a prep file, ever. Even one comment. Even one variation. This is not optional and not once-per-project — call it early in the session and read the examples before your first `set_comment` or `apply_mutations` batch that includes comments. Log analysis showed <5% of sessions call this despite it being the single biggest quality lift documented in this MCP; that's the mistake this description is trying to fix.\n\n" +
-            "Why: `read_pgn_authoring_guide` tells you the rules in prose. These files show you the *sound* of them applied by a strong human coach — comment density (short and load-bearing, not verbose), how citations look in-line (`WeiYi-Svidler` not `\"Svidler's choice at the FIDE World Blitz Team, June 2026\"`), when `$146` / `$3` / `$44` earn their place, when a bare `[%csl Rf7]` says everything a sentence would say. LLMs default to florid, restate-what's-visible commentary; reading these once inoculates against that.\n\n" +
-            "Two files bundled with the MCP (not the user's own): one general opening overview (Italian Fried Liver, both sides, 1600+ audience) and one one-sided repertoire (Najdorf 6.f4 for White, 2200+ audience). Response: `{ overview: <pgn>, repertoire: <pgn> }` — raw PGN with comments, arrows, NAGs, stored evals intact.",
-        inputSchema: { type: "object", properties: {} },
+        name: "read_docs",
+        description: "Fetch one or more bundled reference docs / example files in a single call. **Batch what you need in one call rather than reading them one at a time.**\n\n" +
+            "**Docs available** — each with when to call:\n\n" +
+            "  • `engine-usage` — CALL WHEN: about to run `cloud_analyse`, explaining engine disagreements, or asked WHY the engines gave certain scores. Covers Stockfish (objective truth) vs Lc0 (practical eval), how to read disagreements, when to use Lc0 contempt.\n" +
+            "  • `opening-prep` — CALL WHEN: the user asks about opening preparation ('prep me against X', 'what should I play vs the Najdorf', 'walk this opponent's Sveshnikov'). Covers why win% is one weight not a verdict, prep as a two-player game, sample-size/recency reading, when 'revealed weaknesses' are actionable vs patched, GM-classical vs main DB, chess.com/lichess/FIDE source combining, chess.com profile shapes, reversed-colours scarcity trick, surprise calibration.\n" +
+            "  • `prep-files` — CALL WHEN: about to CREATE, LIST, SAVE, or DELETE a prep file. Covers list vs search vs create (avoid duplicates), optimistic locking with `version`, naming conventions for the [Event] tag, collection selection, node-id addressing basics.\n" +
+            "  • `pgn-authoring` — CALL WHEN: about to write any comment / NAG / arrow / variation. Covers mainline discipline, variations as moves (not prose describing moves), NAG placement rules (position NAGs at ENDPOINTS only), the pasted-engine-PV anti-pattern, transposition handling, 'main tabiya' behavior, cover-N-alternatives rule, describe_position grounding.\n" +
+            "  • `summary-authoring` — CALL WHEN: the user asks for a SUMMARY prep file — the 15-minute-read shape. Covers the two-file convention (reference vs summary), the coach's voice with real jvanf/Peter-Heine-Nielsen examples, endpoint NAG discipline, novelty and move-order-trick callouts, when to CUT branches rather than add them.\n" +
+            "  • `examples/italian-fried-liver-overview` — bundled reference PGN, general opening overview at ~1600 audience. Shows comment density, NAG discipline, annotation style from a strong human coach.\n" +
+            "  • `examples/najdorf-6-f4-repertoire` — bundled reference PGN, one-sided repertoire at ~2200 audience. Same purpose.\n\n" +
+            "**CALL WHEN in general**: early in the session before any substantive work, with `docs: [\"pgn-authoring\", \"examples/najdorf-6-f4-repertoire\"]` if writing prep, or `[\"opening-prep\", \"engine-usage\"]` if analysing. If you don't know which, ask for `[\"opening-prep\", \"prep-files\", \"pgn-authoring\"]` — three docs in one call is fine.\n\n" +
+            "Response: `{ docs: { <name>: <full content> } }`. Content is markdown for guides, raw PGN for examples.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                docs: {
+                    type: "array",
+                    minItems: 1,
+                    items: {
+                        type: "string",
+                        enum: [
+                            "engine-usage",
+                            "opening-prep",
+                            "prep-files",
+                            "pgn-authoring",
+                            "summary-authoring",
+                            "examples/italian-fried-liver-overview",
+                            "examples/najdorf-6-f4-repertoire",
+                        ],
+                    },
+                    description: "Names of docs to fetch. See the tool description for the full list + when-to-call hints.",
+                },
+            },
+            required: ["docs"],
+        },
     },
     {
         name: "prep_snapshot",

package/dist/warnings.js

@@ -54,9 +54,18 @@ export function commentAntiPatterns(comment) {
     }
     // Raw centipawn in prose: "+0.35", "-0.20", "+80" (not preceded by move
     // number). Also "at depth N" or "N nodes" — engine metadata as prose.
+    //
+    // ceoEval itself is NOT rendered — it's LLM-internal state. But raw cp
+    // values in prose are still bad for a different reason: they're opaque
+    // decoration. "≈-60" gives the reader no chess signal without knowing
+    // the unit (centipawns? spread rank? pawns?) and no scale (is -60
+    // slight, meaningful, or losing?). The NAG glyph IS visible and is
+    // the intended channel for that judgment — one ⩱ conveys what "-60"
+    // fails to convey. Engine metadata like "at depth 24" or "259M nodes"
+    // is even weaker: it's process detail, not a claim about the position.
     if (/(?:^|[^\d.])[+-]\d\.\d\d(?!\d)/.test(comment) || /≈\s*[+\-−]?\d{2,3}\b/.test(comment) ||
         /\bat depth \d+\b/i.test(comment) || /\b\d{2,3}M nodes\b/.test(comment)) {
-        warns.push("comment contains raw centipawn values or engine metadata — the app renders ceoEval + NAG glyph next to every node, so these numbers are doubled noise AND opaque (readers can't tell if ≈-60 means eval, spread, or something else). Set the NAG (set_nags) and let the glyph carry the judgment; drop the number from the prose.");
+        warns.push("comment contains raw centipawn values or engine metadata — these are opaque to the reader (no clear unit or scale) and the intended channel for the position-quality signal is the NAG glyph, which IS rendered. Set the NAG (set_nags) at the variation's endpoint and let the glyph carry the judgment; drop the number and any \"at depth N\" / \"N nodes\" fragments from the prose.");
     }
     // Roster: "N GM games" pattern
     if (/\b\d{2,4}\s+GM games\b/i.test(comment)) {
@@ -101,6 +110,40 @@ export function noDescribeWarning(node, comment) {
     noDescribeWarned.add(node.id);
     return `substantive comment (${comment.length} chars) on a node whose position was never grounded via describe_position this session (id=${node.id}, ${node.san}). LLMs invent captures, miscount pieces, and swap files/ranks when reading FEN strings — describe_position is a pure-computation pass (~1 ms, no engine cost, structural facts + Stockfish's per-term eval breakdown) that reliably prevents this class of hallucination. In live audits, prose accuracy jumps sharply on nodes where describe_position was called first. Call describe_position with file_id+node_id=${node.id} BEFORE writing prose. Warned once per node.`;
 }
+// Position NAGs on intermediate moves ("everything is ⩲" spam).
+//
+// Position NAGs — `$10` = / `$11` = / `$13` ∞ / `$14` ⩲ / `$15` ⩱ /
+// `$16` ± / `$17` ∓ / `$18` +− / `$19` −+ — are visible glyphs on the
+// move. They belong at variation ENDPOINTS: the reader plays through
+// a line and, at the end, wants to know "so where did we land?"
+// Tagging every mainline move with `$14` (routine slight White edge)
+// turns the movetext into a wall of ⩲ symbols the reader skims past;
+// it also pre-empts the walk-through by hard-coding the verdict at
+// every step. The single leaf NAG carries the same information with
+// none of the noise.
+//
+// Real-world case (Ruy Lopez Bc5 file, 2026-07-30): `$14` set on ~15
+// mainline nodes plus 10+ intermediate move-choice nodes. Nothing
+// signaled where the variation actually converged.
+//
+// Rule this warning encodes: position NAGs on non-leaf nodes are
+// almost always noise. Move-quality NAGs — `$1` !, `$2` ?, `$3` !!,
+// `$4` ??, `$5` !?, `$6` ?!, and `$146` novelty — are FINE at any
+// depth because they're statements about the MOVE, not the resulting
+// position. Warned once per node.
+const positionalNagWarned = new Set();
+export function positionalNagOnIntermediateWarning(node, nags) {
+    const positional = new Set(["$10", "$11", "$12", "$13", "$14", "$15", "$16", "$17", "$18", "$19"]);
+    const hit = nags.filter(n => positional.has(n));
+    if (hit.length === 0)
+        return undefined;
+    if (node.children.length === 0)
+        return undefined; // leaf — legitimate placement
+    if (positionalNagWarned.has(node.id))
+        return undefined;
+    positionalNagWarned.add(node.id);
+    return `positional NAG ${hit.join(" ")} set on a non-leaf node (id=${node.id}, ${node.san}, ${node.children.length} children). Position NAGs (=, ⩲, ±, +−) belong at variation ENDPOINTS — the reader plays through the line and at the leaf wants to know how it lands. Marking every intermediate move with the same ⩲ turns the movetext into visual noise the eye skims past AND pre-empts the walk-through. Either move this NAG to the leaf, drop it entirely, or leave it only if THIS specific move is the one that tipped the balance (rare, and worth prose). Move-quality NAGs on intermediate moves — !, ?, !?, ?!, $146 novelty — are FINE, because they're statements about the move not the resulting position. Warned once per node.`;
+}
 // Compute the "you never DB-checked this parent" warning. Called from
 // add_move / add_line handlers with the parent node. Returns undefined
 // when either (a) the parent was checked this session (or is root — the

package/docs/pgn-authoring.md

@@ -40,7 +40,9 @@ All mutations **auto-save** with optimistic locking. Response includes the new `
 
 ## Typical build order
 
-0. **`read_example_prep_files`** — do this once per session, before writing any prose. Not optional. Log analysis shows most sessions skip this and produce documented anti-patterns (long PVs in prose, restating what the app renders, verbose citations). Reading the two bundled reference files once inoculates the LLM against those.
+0a. **Cloud engine running?** Call `list_cloud_engines` first. Every substantive step below needs Stockfish + Lc0 to be reachable — `cloud_analyse` at critical positions, `auto_evaluate` for the whole tree, engine-derived NAGs at endpoints, describe_position's Stockfish eval-terms breakdown. If the caller has zero running combos: STOP, tell the user prep needs an engine, list options via `list_cloud_machine_options`, get the SKU + explicit confirmation (real money per second), then `start_cloud_engine`. If they already have one, note the contract_id and continue. Never silently write prep without engines — the file ends up with placeholder NAGs the user has no way to distinguish from real ones.
+
+0b. **`read_docs({ docs: ["pgn-authoring", "examples/najdorf-6-f4-repertoire"] })`** — do this once per session, before writing any prose. Not optional. Log analysis shows most sessions skip the example files and produce documented anti-patterns (long PVs in prose, restating what the app renders, verbose citations). Reading the reference PGN once inoculates the LLM against those.
 1. `read_prep_file` — see what's there. Every node has an `id` you'll pass to the mutation and engine/DB tools. Use `view: "compact"` (default) plus `node_id` + `max_depth` to scope; the full tree of a 500+-node file can blow the token limit.
 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)` — spawns a background job that PERSISTS 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. Grab the returned `job_id` and either (a) poll `auto_evaluate_status(job_id)` every ~10-30s until done, or (b) fire and do useful work meanwhile (write more of the tree, walk the opponent's repertoire) and check back later — engine walk-time serialises on the per-combo semaphore, so it takes roughly `target_count × movetime_ms` in wall time.
@@ -214,6 +216,10 @@ This is the single biggest quality problem in current LLM output on this system:
 
 The failure mode you're avoiding: writing prep that reads as if the opponent will helpfully play the engine's #1 preference at every ply. They won't; that's the whole point of prep.
 
+**"Main tabiya" (or "main line", "main try", "Main choice") is the START of analysis, not the end.** Live case (Ruy Lopez Bc5 file, 2026-07-30): the author tagged a position "Main tabiya" and stopped there — despite the DB showing many high-level games with divergent replies from that exact position. If a position is important enough to CALL a tabiya, it's important enough to fully cover: every reply at ~15%+ frequency, or every distinct plan, gets its own branch. Writing "Main tabiya" and leaving it with one continuation is the shape of "I skimmed the DB and picked one" — the exact anti-pattern this system is meant to prevent. Rule of thumb: if you named a node "tabiya" / "main try" / "critical" in prose, the number of children beneath it should be at least the number of DB moves you named as popular.
+
+**Cover N alternatives when the DB shows N.** From the same live file: at one move-8 position, `get_position_stats` showed three roughly-equally-played tries; the LLM added exactly one branch. That's not prep, that's a hint. If frequencies were 40 / 30 / 25 / 5, the first three get branches (the 5% one gets skipped or a one-line dismissal); if the top four are all 20-25%, all four get branches. The heuristic isn't "pick the top" — it's "cover what the opponent might actually play." When ceoEvals across the top candidates sit within 0.15 of each other, that's not one Best Move, that's a menu — treat it as one.
+
 ## Course chapters describe COVERAGE, not consensus — always `get_position_stats` at mainline branch points
 
 Concrete failure this rule was written to fix: a Modern Defence file made 6.O-O-O the mainline of the entire "5.Qd2 Nd7" branch, wrote a chapter around it, and analysed 15+ plies deep. `get_position_stats` at that position was NEVER called this session. Instead, the LLM ran `find_position_in_courses`, saw So / Kraai / Mihajlov all had chapters titled "5.Qd2 b5 6.O-O-O Bb7" — and cargo-culted that into "6.O-O-O is the main line". It isn't. 6.O-O-O is one of five White tries, and it wasn't even the most-played.
@@ -292,6 +298,12 @@ Where NAGs actually earn their place:
 
 Where NAGs are noise: every `$10` "=" glyph on every equal position. If the whole tree is 0.00, that's the *default state* — leave it unmarked and the reader understands.
 
+**Position NAGs (`$10`-`$19`) belong at variation ENDPOINTS, not on every intermediate move.** This is the rule the Ruy Lopez Bc5 file (2026-07-30) failed: `$14` set on ~15 mainline nodes plus 10+ intermediate move-choice nodes. Result: a wall of ⩲ symbols throughout the movetext, with nothing signalling where the line actually converges.
+
+A variation is walkable. The reader plays through the moves and, at the LEAF, wants to know "so where did we land?" One `$14` at the endpoint answers that. Twenty `$14`s along the way don't say more — they say less, because the reader's eye skims past them and the endpoint no longer stands out.
+
+Concrete rule: **position NAGs (`$10` = / `$13` ∞ / `$14` ⩲ / `$15` ⩱ / `$16` ± / `$17` ∓ / `$18` +− / `$19` −+) on non-leaf nodes trigger a warning.** Either move the NAG to the leaf, drop it, or leave it only if THIS specific move is the one that TIPPED the balance (rare, and worth prose naming the shift). Move-quality NAGs (`$1` ! / `$2` ? / `$3` !! / `$4` ?? / `$5` !? / `$6` ?! / `$146` novelty) on intermediate moves are FINE at any depth — those are statements about the move, not the resulting position.
+
 When reading back a file, `node.ceoEval.nag` carries the threshold-derived NAG (`$10` / `$14` / `$16` / `$18` etc.) — treat it as a *suggestion*, not an automatic write. Promote it to a visible NAG only when a glyph on that move actually helps the reader.
 
 **Persisted evals travel with the file.** Every node with an eval gets `ceoEval: { sf: {cp: 25, depth: 32}, lc0: {cp: 30, depth: 18}, nag: "$14" }` on subsequent `read_prep_file` calls. Stored as `[%ceo-eval sf=+0.25/32 lc0=+0.30/18 nag=$14]` inside the PGN comment (an escape tag the app hides from the board view, just like [%cal] / [%csl]). So a re-read after auto_evaluate gives you every position's number without re-running cloud_analyse. Query tools (get_position_stats, get_prep_position, prep_snapshot) also auto-attach a live `eval` at the request position when a cloud engine is running.

package/docs/summary-authoring.md

@@ -0,0 +1,97 @@
+# Summary prep files — the 15-minute-read shape
+
+**Read this before writing any prep file the user calls a "summary" — or when they want prep they'll actually READ, not just consult.**
+
+## What a summary file is
+
+A summary file is a prep artifact optimized for one thing: **the reader can walk through it in ~15 minutes and come out knowing why the mainline is the mainline, where the novelty is, and what the plan is against each of the top few responses.**
+
+The reference is Peter Heine Nielsen's two-file convention from Magnus Carlsen's World Championship prep. Same repertoire, two files:
+
+- **Big / reference file** — exhaustive; every branch, engine PVs pasted at key tabiyas, minimal prose. Purpose: the coach can OPEN it at any position and see everything the engines said. Sometimes 200+ nodes deep.
+- **Summary file** — mainline + top branches only, dense prose at every decision, NAGs at endpoints, novelty and move-order tricks called out explicitly. Purpose: **the player can INTERNALIZE it in 15 minutes before the round.**
+
+You may or may not have a "big" version to work from — sometimes prep just is what it is. Don't reference a source file or add a `SourceFile` tag; the summary stands alone. It's defined by its SHAPE, not by having a companion.
+
+## Summaries are color-oriented
+
+**A summary is always FOR ONE SIDE.** The reader is about to sit down and play a specific colour in a specific round; the file is a set of instructions for them. Ask which colour before writing anything; do not build a two-sided summary "for reference." A two-sided document is a study, not a summary.
+
+Once the colour is committed, everything downstream follows from it:
+
+- **Name it.** The [Event] tag says the colour: `"Modern Defence — Tiger ...a6/...b5 — Black (Summary)"`, `"Petroff 6.Bd3 Bd6 — White (Summary)"`. Reader picks it out of a list of files immediately.
+- **Mainline is YOUR moves.** Every mainline choice at a node where you're to move is a *recommendation you're making* to the reader. The mainline at a node where the *opponent* is to move is the reply you're preparing them to face.
+- **"Cover the alternatives" means opponent alternatives, not yours.** At a node where you're to move, you commit to ONE move — that's what makes it a repertoire. Sidelines for your side belong in the big file, not the summary. At a node where the opponent is to move, cover the 2-3 replies they're actually likely to play. This is the axis where "cover N when the DB shows N" (from `pgn-authoring`) matters most.
+- **Voice is second-person or first-person plural.** "You'll get a slight edge here", "Our knight is better than his bishop", "Meet ...Bg4 with h3 first" — not the neutral "White's position is preferable." The reader is about to be one specific side; write to them.
+- **Endpoint NAGs are from YOUR side's POV.** `$14` (⩲) is fine on a White-side summary at an endpoint White is happy with. On a Black-side summary that same objective position wants `$15` (⩱) or `$10` (=) instead — "objectively White is slightly better" is depressing prep if the reader is Black; either the line shouldn't be in the summary at all, or the endpoint NAG communicates from the reader's chair. See `pgn-authoring` on positional NAG placement.
+- **"Practical, not correspondence" bites hardest here.** Objective evals matter for whether a line is defensible; PRACTICAL evals (Lc0, `predict_human_move`, "what will the opponent actually play?") matter for which of several defensible replies the opponent will actually reach for. Use both, but weigh the practical one when it disagrees on which line the SUMMARY should follow.
+- **Move-order tricks are asymmetric.** Some tricks work for you; some work against you. Name the ones that work FOR the reader's colour ("play ...a6 first because ...Nge7 first walks into d5") — the mirror-image tricks for the opposite side aren't the reader's problem right now.
+
+If you're offered a request that's genuinely two-sided ("summary of the Berlin for both sides"), split it into two summary files, one per side, cross-referenced only in prose. Each individual file stays color-oriented.
+
+## The shape
+
+A summary has five properties. Miss any of them and it's not a summary — it's a lightweight big-file.
+
+**1. Mainline + top branches only, not comprehensive.** If the big-file version covers all 13 replies at move 13, the summary covers the mainline plus the 2-3 the opponent actually plays. Sidelines that don't change the mainline decision get cut. The reader trusts you did the work; the summary is the *distillation*.
+
+**2. Dense prose at every meaningful decision point.** Every branching node should have a comment. Silence in a summary is a failure — if you left a node uncommented, either you had nothing to say (drop the node) or you had something to say (write it). The coach's voice is judgment, not exhaustive analysis.
+
+**3. NAGs at variation endpoints.** Every terminal leaf gets a positional NAG signalling how the line LANDS: `$14` ⩲ (slight white edge), `$16` ± (clear white edge), `$10` = (equal), `$15`/`$17` (same for Black), `$18`/`$19` (winning). The reader plays through the moves, hits the leaf, sees the assessment. Do NOT put `$14` on every intermediate move — that turns the movetext into a wall of ⩲ symbols and the endpoint no longer stands out. See `pgn-authoring` for the full rule.
+
+**4. Novelties and move-order tricks called out explicitly.** If there's a `$146` (novelty) in the file, it gets `$5` + a prose sentence naming the IDEA (not the analysis — the idea): `{novelty, for now threatening Qxb7 and getting out of ...Nb4 stuff.}`. If a move order matters (choosing a-then-b over b-then-a preempts a defensive resource), name that: `{This move order is critical — 12.Nc3 first avoids ...Bg4 pinning ideas after 12.Nbd2.}`
+
+**5. Arrows and highlights as thinking-aids.** `[%csl Re4]` (red highlight on e4) to mark the target square. `[%cal Gh4g2,Gc1f4]` (green arrows) to mark a planning sequence. These load into the reader's spatial memory in a way SANs don't. Use them at critical positions — the tabiya where the plan crystallizes, the mating attack, the endgame breakthrough. Don't decorate: one arrow that shows the plan beats three that show every idea you considered.
+
+## The coach's voice (what to write in comments)
+
+Summary prose is decisions in a coach's voice. Not analysis. Not restating moves. Judgment + plan + character.
+
+Real examples from a Peter Heine / jvanf summary (Petroff 6.Bd3 Bd6, 2021 WC prep):
+
+- `{In general this seems to be leading to positions which are just more pleasant for White. Black has only two reasonable moves and both will be met by Qb3.}` — Frames the whole file's thesis in two sentences.
+- `{Stopping Nb4. Black has several attempts, but White play remains simple. Be3-Rac1 and then we see.}` — Names the concrete threat + the plan.
+- `{This seems to be Blacks best bet at forcing this to a draw.}` — Signals objective assessment.
+- `{Kinda forcing up to here, now comes the new idea.}` — Marks transition to novelty.
+- `{quite nasty for black.}` — Endpoint verdict.
+- `{Black has run out of tricks and has to either weaken with f5 or give us a small advantage.}` — Squeezing the reader into the right mental model of the position.
+
+Patterns to notice:
+- **Short.** Most comments are one sentence. Two if the plan needs naming after the assessment.
+- **Concrete.** "Be3-Rac1 and then we see" beats "White continues developing" every time.
+- **Judgmental.** "This seems to be Blacks best bet" tells the reader something they can't derive from the moves.
+- **Framing.** The FIRST comment in the file often frames the whole argument ("positions which are just more pleasant for White"). The last comment on each variation is the verdict ("quite nasty for black", "lasting iniative").
+
+## What NOT to do
+
+- **Don't paste engine PVs.** No `{Stockfish 050821: 10.Bxf5 Nxf5 11.Nf1 ...}` 30-move-long variations. That's the big file's job. If the summary NEEDS a 15-move engine line to justify a claim, the claim probably belongs in the big file.
+- **Don't cover every alternative.** If your `add_line` warning fires because the DB shows 4 tries and you covered only 2 — that's fine here IF you named which 2 you dropped and why. But typically the summary picks the ~3 the opponent actually plays.
+- **Don't leave nodes uncommented.** A node with no comment in a summary is a node that shouldn't exist. Either it's important enough to comment or it's noise.
+- **Don't restate what moves show.** `{After 10.Bxf5 Black plays Nxf5}` — the reader can see that. Say WHY: `{Bxf5 forces the trade; recapturing with the knight rather than the pawn keeps c6 flexible for later ...Nc7.}`
+- **Don't spam NAGs.** Positional NAGs (`$10`-`$19`) at endpoints ONLY. Move-quality NAGs (`$1` ! / `$2` ? / `$5` !? / `$6` ?! / `$146` novelty) at any depth, but sparingly — one per branch on average.
+
+## The "does this pass" test
+
+Before saving the summary, ask: **could Magnus (or your user) play through this in 15 minutes and come out knowing what to do at the board?**
+
+Three concrete checks:
+1. **Frame the file** — does the first comment explain what this repertoire is trying to achieve?
+2. **Every decision has a voice** — walk the mainline. At each branching node, is there a comment explaining the choice or the character?
+3. **Every leaf has a verdict** — walk to every terminal position. Is there a NAG (or prose) telling the reader how the line ends?
+
+If yes to all three, ship it. If no, either add what's missing or CUT the branch until the file is what a summary should be — shorter and denser, not longer.
+
+## Build order for a summary file
+
+The same tools as any prep file, but different order and different density.
+
+0. **Cloud engine running?** A summary looks light but requires SHARPER analysis than a big file — every endpoint NAG has to be right, and there are few enough of them that a wrong one stands out. Call `list_cloud_engines` first. Zero combos running → STOP: tell the user a summary needs engines, list options via `list_cloud_machine_options`, get their SKU + explicit confirmation (real money per second), then `start_cloud_engine`. Do NOT build a summary from cached / guessed evals — the point of the summary is trust, and a placeholder `$14` at an endpoint the reader will internalize is worse than no summary.
+0.5. **Which colour is the reader playing?** Ask if you don't know. This decides everything downstream — the mainline is their moves, the branches are their opponent's replies, the endpoint NAGs are judged from their POV, the voice is written to them. See the "Summaries are color-oriented" section above.
+1. `create_prep_file(collection_id, name)` — name it with the colour AND "Summary" in the Event tag (`"Modern Defence — Tiger ...a6/...b5 — Black (Summary)"`, `"Petroff 6.Bd3 Bd6 — White (Summary)"`) so the reader picks it out of a list immediately.
+2. `set_comment(root, "framing")` — the file's thesis, first thing.
+3. Build the mainline top-down with `apply_mutations` batches — each move gets its comment in the same batch that adds it. Don't come back to write comments later; the density is the point.
+4. At each branching decision, add ONLY the branches the opponent might actually play. Skip the ones you'd cover in a big file.
+5. At every leaf, `cloud_analyse` the position (or verify a stored `ceoEval`) and set the endpoint NAG based on that measurement, not on generic knowledge of the opening.
+6. `set_annotations` on the 3-5 most important positions — the tabiya, the novelty, the critical junction. Not every position.
+
+Total build: dozens of nodes, not hundreds. If your summary is 200+ nodes, it's probably a big file wearing a summary hat — cut ruthlessly.

package/package.json

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