@chessceo/mcp 0.44.0 → 0.48.2

package/dist/prep/read.js

@@ -0,0 +1,242 @@
+// Prep-file reads and list-queries. Everything the LLM calls to inspect
+// a file WITHOUT mutating it:
+//   - readPrepFile (with four view modes: compact / full / spine / pgn)
+//   - listNodes (cheap filter-based node queries)
+//   - listTranspositions (positions occurring 2+ times in the file)
+//
+// Extracted from index.ts in v0.44 as part of the file split. Was
+// originally split off the read-case handler because both readPrepFile
+// and listNodes need the same load-parse pipeline and share the
+// compact / spine / pgn view logic.
+import { fetchGame } from "../http.js";
+import { parsePGN } from "../pgn/parser.js";
+import { exportPGN } from "../pgn/exporter.js";
+import { buildFenIndex, buildIdIndex, positionKey, resolveNodeId, ROOT_ID, } from "../pgn/paths.js";
+import { getNodeByPath } from "../analysis/file_handle.js";
+export async function loadPrepFile(id) {
+    const g = await fetchGame(id);
+    // Echo the composite id back so read_prep_file responses match the
+    // exact id the LLM passed in. The backend returns the raw game_id;
+    // recompose so the LLM never sees the split form.
+    return { file: parsePGN(g.pgnContent), version: g.version, fileIdEcho: id, pgn: g.pgnContent };
+}
+// Recursively project a PrepNode into the requested view. `depthLeft`
+// null → unlimited; 0 → just the node without children.
+//
+// `fenIndex` (optional) enables the `transposes_to` field — for each
+// node whose position also appears elsewhere in the SAME file, we
+// annotate it with the OTHER occurrences' ids. Pass null (the default)
+// to skip the annotation entirely; passing the map costs one lookup
+// per node projected.
+export function projectNode(node, view, depthLeft, fenIndex = null) {
+    const base = {
+        id: node.id,
+        san: node.san,
+        ply: node.ply,
+    };
+    if (node.nags && node.nags.length > 0)
+        base.nags = node.nags;
+    if (node.comment)
+        base.comment = node.comment;
+    if (node.ceoEval)
+        base.ceoEval = node.ceoEval;
+    if (view === "full") {
+        base.fen = node.fen;
+        if (node.annotations)
+            base.annotations = node.annotations;
+    }
+    if (fenIndex && node.id !== ROOT_ID) {
+        const group = fenIndex.get(positionKey(node.fen));
+        if (group && group.length > 1) {
+            const others = group.filter(n => n.id !== node.id).map(n => n.id);
+            if (others.length > 0)
+                base.transposes_to = others;
+        }
+    }
+    // Children handling depends on view + depth budget.
+    const showChildren = depthLeft === null || depthLeft > 0;
+    const childDepth = depthLeft === null ? null : depthLeft - 1;
+    if (showChildren && node.children.length > 0) {
+        if (view === "spine") {
+            // Only follow children[0] — collapses the tree to the mainline.
+            base.children = [projectNode(node.children[0], view, childDepth, fenIndex)];
+        }
+        else {
+            base.children = node.children.map(c => projectNode(c, view, childDepth, fenIndex));
+        }
+    }
+    else {
+        base.children = [];
+    }
+    return base;
+}
+export async function readPrepFile(args) {
+    const id = String(args.id);
+    const view = (typeof args.view === "string" && ["compact", "full", "spine", "pgn"].includes(args.view))
+        ? args.view
+        : "compact";
+    const startNodeId = typeof args.node_id === "string" && args.node_id.length > 0 ? args.node_id : ROOT_ID;
+    const maxDepth = typeof args.max_depth === "number" && args.max_depth >= 0 ? args.max_depth : null;
+    const { file, version, fileIdEcho, pgn } = await loadPrepFile(id);
+    const idIndex = buildIdIndex(file.root);
+    const path = resolveNodeId(idIndex, startNodeId);
+    const anchor = getNodeByPath(file.root, path);
+    const fenIndex = buildFenIndex(file.root);
+    // How many DISTINCT positions in the file appear more than once,
+    // and how many nodes are involved. Shown in the header so the LLM
+    // sees at a glance whether transpositions matter here before diving
+    // into the tree.
+    let transGroups = 0;
+    let transNodes = 0;
+    for (const arr of fenIndex.values()) {
+        if (arr.length > 1) {
+            transGroups++;
+            transNodes += arr.length;
+        }
+    }
+    const header = {
+        id: fileIdEcho ?? id,
+        version,
+        tags: file.tags,
+        view,
+        node_id: startNodeId,
+        max_depth: maxDepth,
+        transposition_groups: transGroups,
+        transposition_nodes: transNodes,
+    };
+    if (view === "pgn") {
+        // For the root, just return the file's actual PGN as-is. For a
+        // subtree, build a mini-Game from the anchor and export it. Keeps
+        // formatting identical to what the app renders.
+        if (startNodeId === ROOT_ID && (maxDepth === null || maxDepth >= 999)) {
+            return { ...header, pgn };
+        }
+        // Truncate to a subtree with max_depth. Simple: walk the anchor's
+        // subtree, produce a synthetic PGN starting from the anchor's FEN.
+        const subtreePgn = exportSubtreePgn(file, anchor, maxDepth);
+        return { ...header, pgn: subtreePgn };
+    }
+    return { ...header, tree: projectNode(anchor, view, maxDepth, fenIndex) };
+}
+// Produce a PGN string for a subtree rooted at `anchor`, truncated
+// at `maxDepth` plies below (null = unlimited). Reuses the exporter
+// by building a synthetic PrepFile whose root is a shallow clone of
+// the anchor with its children trimmed to depth.
+function exportSubtreePgn(file, anchor, maxDepth) {
+    const trim = (n, depthLeft) => {
+        if (depthLeft !== null && depthLeft <= 0)
+            return { ...n, children: [] };
+        const next = depthLeft === null ? null : depthLeft - 1;
+        return { ...n, children: n.children.map(c => trim(c, next)) };
+    };
+    const trimmedAnchor = trim(anchor, maxDepth);
+    // If the anchor IS the root, exporter handles it. If it's an inner
+    // node, we set the root's FEN to the anchor's position and hang the
+    // trimmed subtree off it. Tags carried over.
+    if (anchor.id === ROOT_ID) {
+        return exportPGN({ tags: file.tags, root: trimmedAnchor });
+    }
+    const syntheticRoot = {
+        id: ROOT_ID,
+        san: null,
+        fen: anchor.fen,
+        ply: 0,
+        children: trimmedAnchor.children,
+    };
+    const tags = { ...file.tags, FEN: anchor.fen, SetUp: "1" };
+    return exportPGN({ tags, root: syntheticRoot });
+}
+export async function listNodes(args) {
+    const id = String(args.id);
+    const filter = String(args.filter || "");
+    const startNodeId = typeof args.node_id === "string" && args.node_id.length > 0 ? args.node_id : ROOT_ID;
+    const maxDepth = typeof args.max_depth === "number" && args.max_depth >= 0 ? args.max_depth : null;
+    const { file } = await loadPrepFile(id);
+    const idIndex = buildIdIndex(file.root);
+    const path = resolveNodeId(idIndex, startNodeId);
+    const anchor = getNodeByPath(file.root, path);
+    const fenIndex = filter === "transpositions" ? buildFenIndex(file.root) : null;
+    const hits = [];
+    const walk = (node, depthLeft, spineOnly) => {
+        // Root has no san — never emit it as a match. Everything else is fair game.
+        if (node.id !== ROOT_ID) {
+            let include = false;
+            let extra = {};
+            switch (filter) {
+                case "missing_eval":
+                    include = !node.ceoEval;
+                    break;
+                case "has_comment":
+                    include = !!(node.comment && node.comment.length > 0);
+                    if (include)
+                        extra.comment_preview = (node.comment || "").slice(0, 80);
+                    break;
+                case "has_annotations":
+                    include = !!(node.annotations && (node.annotations.arrows.length > 0 || node.annotations.highlights.length > 0));
+                    break;
+                case "novelties":
+                    include = !!(node.nags && node.nags.includes("$146"));
+                    break;
+                case "leaves":
+                    include = node.children.length === 0;
+                    break;
+                case "mainline":
+                    include = spineOnly;
+                    break;
+                case "transpositions": {
+                    const group = fenIndex.get(positionKey(node.fen));
+                    if (group && group.length > 1) {
+                        include = true;
+                        extra.transposes_to = group.filter(n => n.id !== node.id).map(n => n.id);
+                    }
+                    break;
+                }
+                case "all":
+                    include = true;
+                    break;
+                default:
+                    throw new Error(`unknown filter: ${filter}`);
+            }
+            if (include) {
+                const hit = { node_id: node.id, san: node.san, ply: node.ply };
+                Object.assign(hit, extra);
+                hits.push(hit);
+            }
+        }
+        if (depthLeft !== null && depthLeft <= 0)
+            return;
+        const nextDepth = depthLeft === null ? null : depthLeft - 1;
+        if (filter === "mainline" && spineOnly) {
+            if (node.children.length > 0)
+                walk(node.children[0], nextDepth, true);
+        }
+        else {
+            for (const c of node.children)
+                walk(c, nextDepth, filter === "mainline");
+        }
+    };
+    const rootIsSpineForFilter = filter === "mainline";
+    walk(anchor, maxDepth, rootIsSpineForFilter);
+    return { file_id: id, filter, node_id: startNodeId, max_depth: maxDepth, count: hits.length, nodes: hits };
+}
+// list_transpositions — every position that occurs 2+ times in the
+// file, so the LLM knows where its analysis / prose will double up.
+export async function listTranspositions(args) {
+    const id = String(args.id);
+    const { file } = await loadPrepFile(id);
+    const fenIndex = buildFenIndex(file.root);
+    const groups = [];
+    for (const [key, arr] of fenIndex.entries()) {
+        if (arr.length < 2)
+            continue;
+        groups.push({
+            position_key: key,
+            size: arr.length,
+            node_ids: arr.map(n => n.id),
+            sans: arr.map(n => n.san),
+        });
+    }
+    groups.sort((a, b) => b.size - a.size || a.position_key.localeCompare(b.position_key));
+    const nodeCount = groups.reduce((s, g) => s + g.size, 0);
+    return { file_id: id, group_count: groups.length, node_count: nodeCount, groups };
+}

package/dist/response_transforms.js

@@ -0,0 +1,169 @@
+// Response shape transformations applied to backend payloads before
+// they reach the LLM. Two responsibilities:
+//   - Drop internal / debug-only fields the LLM doesn't need
+//     (`hash`, `plyNumber`, `relevance`, etc.).
+//   - Rewrite backend jargon into LLM-friendly names
+//     (`transpositions` → `reachedViaTransposition`, `hotness` →
+//     `fashionScore`, UCI moves → SAN).
+//
+// Plus a couple of tool-input adapters that also live here for lack of
+// a better home:
+//   - `trimMovesToPly` (used by trimGamesMovetext, exported for reuse).
+//   - `normalizeSourceForBackend` (prepare_opponent request adapter).
+//
+// Extracted from index.ts in v0.44 as part of the file split.
+import { uciMoveToSAN } from "./analysis/response.js";
+// Strip cruft the LLM doesn't need from the DB-position response.
+// Called AFTER trimGamesMovetext so plyNumber survives long enough to
+// slice each game's movetext. Also renames the `transpositions` field
+// to something the LLM can parse without knowing chess-DB jargon.
+export function stripPositionResponse(r) {
+    if (!r || typeof r !== "object")
+        return;
+    const t = r;
+    delete t.hash; // internal zobrist string
+    delete t.source; // internal "database" marker; we overwrite with our own .source
+    delete t.totalGames; // duplicates statistics.totalCount often; hasMore covers pagination
+    if (Array.isArray(t.moves)) {
+        for (const m of t.moves) {
+            if (typeof m.transpositions === "number") {
+                m.reachedViaTransposition = m.transpositions;
+                delete m.transpositions;
+            }
+            // Backend calls it "hotness" — a 0-100 time-decayed popularity score
+            // (recent + played often = high). Rename to something an LLM can read
+            // without guessing it means "on a winning streak".
+            if (typeof m.hotness === "number") {
+                m.fashionScore = m.hotness;
+                delete m.hotness;
+            }
+        }
+    }
+    if (Array.isArray(t.games)) {
+        for (const g of t.games) {
+            delete g.gameId;
+            delete g.whiteTitle;
+            delete g.blackTitle;
+            delete g.whiteTeam;
+            delete g.blackTeam;
+            delete g.round;
+            delete g.plyNumber;
+            delete g.relevance;
+            delete g.site;
+            delete g.ply;
+        }
+    }
+}
+// Trim every game's `moves` field to just the plies AFTER the queried
+// position, using each game's `plyNumber`. Massive token save — a game
+// 80 plies long queried at ply 12 drops to ~68 plies of movetext. Ports
+// the frontend's GamesTable.getMoveDisplay() trim logic.
+export function trimGamesMovetext(response) {
+    if (!response || typeof response !== "object")
+        return;
+    const r = response;
+    if (!Array.isArray(r.games))
+        return;
+    for (const g of r.games) {
+        if (typeof g.moves === "string" && typeof g.plyNumber === "number" && g.plyNumber > 0) {
+            g.moves = trimMovesToPly(g.moves, g.plyNumber);
+        }
+    }
+}
+export function trimMovesToPly(moves, plyNumber) {
+    // Split into plain SAN tokens, dropping standalone move-number tokens
+    // ("1.", "12...") and any glued number prefix on a SAN token ("1.e4").
+    // Result markers ("*", "1-0", "0-1", "1/2-1/2") are stripped so they
+    // don't get counted as plies.
+    const tokens = [];
+    for (const chunk of moves.split(/\s+/)) {
+        if (!chunk)
+            continue;
+        const cleaned = chunk.replace(/^\d+\.+/, "");
+        if (!cleaned)
+            continue;
+        if (/^(1-0|0-1|1\/2-1\/2|\*)$/.test(cleaned))
+            continue;
+        tokens.push(cleaned);
+    }
+    const remaining = tokens.slice(plyNumber);
+    if (remaining.length === 0)
+        return "";
+    // Reconstruct with move numbering. First move gets "N..." if it's
+    // Black's move (starting the slice mid-move-pair), so the reader knows
+    // moves were dropped.
+    const out = [];
+    let ply = plyNumber;
+    for (let i = 0; i < remaining.length; i++) {
+        const san = remaining[i];
+        const moveNumber = Math.floor(ply / 2) + 1;
+        if (ply % 2 === 0) {
+            out.push(`${moveNumber}. ${san}`);
+        }
+        else if (i === 0) {
+            out.push(`${moveNumber}... ${san}`);
+        }
+        else {
+            out.push(san);
+        }
+        ply++;
+    }
+    return out.join(" ");
+}
+// 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
+// response through unchanged if there's no availableMoves array.
+export function convertAvailableMovesToSAN(raw, fen) {
+    if (!raw || typeof raw !== "object")
+        return raw;
+    const r = raw;
+    if (!Array.isArray(r.availableMoves))
+        return raw;
+    for (const m of r.availableMoves) {
+        if (typeof m.move === "string" && m.move.length >= 4) {
+            m.move = uciMoveToSAN(fen, m.move);
+        }
+    }
+    return raw;
+}
+// Normalize one MCP `prepare_opponent` source into the shape the backend's
+// /api/chess/prep/prepare-multi expects. Handles two impedance mismatches:
+//   - snake_case → camelCase (fide_id → fideId, start_month → startMonth, etc.)
+//   - the unified `time_control` string → per-source-type filter:
+//       * fide / chesscom → timeFormats: ["Classical" | "Rapid" | "Blitz"]
+//       * lichess → perfType: "classical" | "rapid" | "blitz" | "bullet"
+// Backend validates required fields per source type, so we don't need to
+// pre-reject missing username/fideId here — it'll come back as a 400 the
+// LLM can act on.
+export function normalizeSourceForBackend(src, idx) {
+    const type = typeof src.type === "string" ? src.type : "";
+    if (type !== "fide" && type !== "chesscom" && type !== "lichess") {
+        throw new Error(`sources[${idx}].type must be one of fide|chesscom|lichess (got ${JSON.stringify(src.type)})`);
+    }
+    const out = { type };
+    if (typeof src.fide_id === "number")
+        out.fideId = src.fide_id;
+    if (typeof src.username === "string" && src.username.trim() !== "")
+        out.username = src.username.trim();
+    if (typeof src.color === "string" && (src.color === "white" || src.color === "black"))
+        out.color = src.color;
+    if (typeof src.start_month === "string" && src.start_month.trim() !== "")
+        out.startMonth = src.start_month.trim();
+    if (typeof src.end_month === "string" && src.end_month.trim() !== "")
+        out.endMonth = src.end_month.trim();
+    if (typeof src.exclude_online === "boolean")
+        out.excludeOnline = src.exclude_online;
+    const tc = typeof src.time_control === "string" ? src.time_control : "";
+    if (tc) {
+        if (type === "lichess") {
+            out.perfType = tc;
+        }
+        else {
+            // fide + chesscom take a titlecased timeFormats array.
+            const titled = tc.charAt(0).toUpperCase() + tc.slice(1);
+            out.timeFormats = [titled];
+        }
+    }
+    return out;
+}

package/dist/tools.js

@@ -837,34 +837,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.