@chessceo/mcp 0.40.0 → 0.43.0

package/dist/index.js

@@ -73,8 +73,10 @@ const AUTHED_TOOLS = new Set([
     "list_cloud_engines",
     "stop_cloud_engine",
     "cloud_analyse",
+    "list_collections",
     "list_prep_files",
     "search_prep_files",
+    "find_position_in_files",
     "read_prep_file",
     "list_nodes",
     "list_transpositions",
@@ -174,6 +176,72 @@ async function authedRequest(method, path, body) {
     }
     return text.length ? JSON.parse(text) : null;
 }
+// ── Backend I/O layer ──────────────────────────────────────────────
+//
+// v0.43: MCP surface moved off the single-`/mcp`-folder model onto the
+// full user PGN library. LLM-facing tool ids are opaque composites of
+// the form `<collection_id>:<game_id>` so every existing tool that
+// takes `id` keeps taking `id` — the composite splits back into two
+// pieces at the HTTP layer. Backend routes live under
+// `/api/agent/pgns/*` (same handlers as `/me/pgns/*` browser routes;
+// a path-rewrite middleware in the server main.go maps the two).
+const PGN_BASE = "/api/agent/pgns";
+// Browser handlers wrap successful responses as
+//   { success: true, message: "...", data: <actual thing> }
+// via handlers.RespondSuccess. Peel that off; leave anything without
+// the envelope unchanged (some endpoints return raw bodies).
+function unwrap(raw) {
+    if (raw &&
+        typeof raw === "object" &&
+        "data" in raw &&
+        raw.success === true) {
+        return raw.data;
+    }
+    return raw;
+}
+// LLM-facing "prep file id" is always "<collection_id>:<game_id>" —
+// makeFileId to compose from a listing, splitFileId at the HTTP edge.
+function makeFileId(collectionId, gameId) {
+    return `${collectionId}:${gameId}`;
+}
+function splitFileId(id) {
+    const idx = id.indexOf(":");
+    if (idx <= 0 || idx === id.length - 1) {
+        throw new Error(`invalid prep file id "${id}" — expected "<collection_id>:<game_id>" ` +
+            `(get one from list_prep_files, search_prep_files, find_position_in_files, ` +
+            `or the create_prep_file return value)`);
+    }
+    return { collectionId: id.slice(0, idx), gameId: id.slice(idx + 1) };
+}
+// GET one game by composite id. Throws on 404.
+async function fetchGame(id) {
+    const { collectionId, gameId } = splitFileId(id);
+    const raw = await authedRequest("GET", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games/${encodeURIComponent(gameId)}`);
+    const g = unwrap(raw);
+    if (!g || typeof g.pgnContent !== "string") {
+        throw new Error("prep file missing pgnContent");
+    }
+    return g;
+}
+// PUT the game body. Returns the saved game (new version).
+async function saveGame(id, pgn, expectedVersion) {
+    const { collectionId, gameId } = splitFileId(id);
+    const body = { pgnContent: pgn };
+    if (typeof expectedVersion === "number")
+        body.baseVersion = expectedVersion;
+    const raw = await authedRequest("PUT", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games/${encodeURIComponent(gameId)}`, body);
+    return unwrap(raw);
+}
+// POST a new game into the given collection. Returns the created game.
+async function createGame(collectionId, pgn) {
+    const raw = await authedRequest("POST", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games`, { pgnContent: pgn });
+    return unwrap(raw);
+}
+// DELETE (soft) a game by composite id.
+async function deleteGame(id) {
+    const { collectionId, gameId } = splitFileId(id);
+    await authedRequest("DELETE", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games/${encodeURIComponent(gameId)}`);
+}
 // ── Tool definitions ───────────────────────────────────────────────
 //
 // Descriptions are written for the LLM, not humans — they should hint
@@ -332,7 +400,8 @@ const TOOLS = [
     },
     {
         name: "describe_position",
-        description: "Everything you need to understand a position in one call. USE BEFORE COMMENTING — pieces get misplaced when reading a FEN, hanging pieces missed, 'the knight on d5' turns out to not exist. ~50-100 ms per call (chess-primitive analysis is instant; the Stockfish leg dominates wall time).\n\n" +
+        description: "**CALL WHEN**: about to write ANY comment on a position that describes what's happening on the board — piece activity, structure, plans, weaknesses. This is the single biggest lever for prose quality in the whole system. Live audit: nodes where describe_position was called first produced comments grounded specifically in the position (correct piece squares, real pawn structure, actual weak squares); nodes where it wasn't produced generic pattern-matched prose that confidently named pieces on wrong squares. `set_comment` now emits a warning whenever a substantive comment lands on a node whose position was never grounded via describe_position this session — that warning is telling you to fix a class of hallucination that already showed up in your output. Cheap: chess-primitive analysis is instant, Stockfish leg is ~50-100 ms, no billing.\n\n" +
+            "Everything you need to understand a position in one call. Pieces get misplaced when reading a FEN, hanging pieces missed, 'the knight on d5' turns out to not exist.\n\n" +
             "Returns three layers:\n\n" +
             "**Board state** — piece placements per colour, material balance in pawn units, contested pieces (attackers + defenders), hanging pieces, checkers if in check, castling rights, en passant, side to move, full LEGAL MOVES list. Use `.legalMoves` when `add_move` rejects an illegal SAN.\n\n" +
             "**Structural analysis** — chess-concept observations a human sees at a glance:\n" +
@@ -480,6 +549,7 @@ const TOOLS = [
             "• 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). Signed 0-100 strength — same scale as the web UI's ContemptStrength slider (the server multiplies by 8 to produce Lc0's internal cp bias). Typical values: ±15 for a light nudge, ±30-60 for real fighting play, ±80-100 for maximum steer. Use it to find non-objective 'practical' ideas or when the user needs to lean 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" +
+            "**PVs are capped at 6 plies by default (3 full moves), and lines that got truncated are marked with `pv_truncated: true`.** This is deliberate: the tail of a PV is where the engine's confidence collapses, AND pasting a long PV into `add_line` as if it were prepared repertoire is the #1 documented anti-pattern of this MCP — a 15-move PV is one line of engine output through positions where both sides had real choices, not a repertoire. To see further, don't raise `pv_max_plies`; instead, walk the tree one branch at a time with a fresh `cloud_analyse` at each position where the opponent has real alternatives — that's what makes it prep instead of pasted output. Only raise the cap when you're verifying a forcing sequence (a mate, a forced tactical resolution), not to build lines.\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 `get_position_stats` for anything that doesn't require deep prep.\n\n" +
             "**When called with `file_id`+`node_id` (preferred inside a prep file), the resulting eval is auto-stored on that node's `ceoEval` — you can then quote it with quote_engine_eval on any later call.** This is what makes engine attribution trustworthy: prose that says 'engines say X on node Y' can only be true if a call was actually made against node_id=Y.",
@@ -522,17 +592,37 @@ const TOOLS = [
                     items: { type: "string", enum: ["stockfish", "lc0"] },
                     description: "Which engines to run. Default = both. Use `[\"lc0\"]` to skip Stockfish (e.g. while a deep_analyse job is holding the SF slot on the same combo). Use `[\"stockfish\"]` when only the objective read matters. The skipped engine's field is omitted from the response.",
                 },
+                pv_max_plies: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 40,
+                    description: "Cap each returned PV to this many plies (default 6 = 3 full moves). PVs beyond ~6 plies are speculative and are the anti-pattern behind pasted-engine-line 'prep' — don't raise unless you're specifically checking a forcing tactic or verifying a mate. When a line was truncated, the response marks it with `pv_truncated: true`.",
+                },
             },
         },
     },
     {
-        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.",
+        name: "list_collections",
+        description: "List the user's own PGN collections — every collection they've created, not just prep files. Response: `{collections: [{id, title, icon, folder_path, game_count, updated_at, position_search_enabled}]}`.\n\n" +
+            "**Call this before create_prep_file** — the LLM must pick a collection to write into (no default landing folder any more; the old hidden `/mcp` collection was retired in v0.43). Also useful when the user asks a position-shaped question — LLM can then run find_position_in_files to see which of these collections already covers the position.\n\n" +
+            "Encrypted collections (client-side-encrypted PGN) are excluded — the server can't read their contents, so they'd be dead weight on this surface.",
         inputSchema: { type: "object", properties: {} },
     },
+    {
+        name: "list_prep_files",
+        description: "List the games (prep files) inside one of the user's collections. **Requires `collection_id`** — call `list_collections` first if you don't have one. Returns id (composite `<collection_id>:<game_id>`, opaque to the LLM — pass as-is to read_prep_file / mutation tools), PGN header fields, updated_at.\n\n" +
+            "For cross-collection discovery use `search_prep_files` (text) or `find_position_in_files` (position); list_prep_files is the browse-one-collection tool.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection_id: { type: "string", description: "Collection id from list_collections. Required." },
+            },
+            required: ["collection_id"],
+        },
+    },
     {
         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').",
+        description: "Text search over the user's prep files ACROSS ALL their collections (matches PGN headers, comments, and content). Use when you know a keyword — e.g. search_prep_files(query='Firouzja') or search_prep_files(query='Najdorf'). Cheaper than paging list_collections + list_prep_files to find one file by name.",
         inputSchema: {
             type: "object",
             properties: {
@@ -541,6 +631,22 @@ const TOOLS = [
             required: ["query"],
         },
     },
+    {
+        name: "find_position_in_files",
+        description: "Position search across every one of the user's EDITABLE prep files (all their non-encrypted collections). Given a FEN, returns which of the user's files reach that exact position (or a transposition of it — matched by zobrist hash, so move-order variants are found automatically). Recency-sorted.\n\n" +
+            "Distinct from `find_position_in_courses`: courses are READ-ONLY reference material (Chessable PGNs, downloaded backups); this searches the user's OWN editable prep. Common workflow: user asks about a position → call this first to see if their existing prep covers it → if yes, extend that file; if no, consider whether to start new prep.\n\n" +
+            "Position input: `file_id`+`node_id` (from an already-open prep file), or `fen`, or `moves` from startpos, or `fen`+`moves`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file_id: { type: "string", description: "Prep file id. With `node_id`, derives FEN from the tree." },
+                node_id: { type: "string", description: "Node id inside `file_id`. Root is 'r'." },
+                fen: { type: "string", description: "Position as FEN. Only used if `file_id`/`node_id` not set." },
+                moves: { type: "string", description: "SAN moves from startpos (or on top of fen)." },
+                line: { type: "string", description: "Alias for moves." },
+            },
+        },
+    },
     {
         name: "read_prep_file",
         description: "Read one prep file. Response always includes `id`, `version`, `tags`. The tree/PGN part is controlled by `view` and `node_id`/`max_depth` — large files (500+ nodes) can otherwise blow the LLM's token limit.\n\n" +
@@ -604,17 +710,23 @@ const TOOLS = [
     },
     {
         name: "create_prep_file",
-        description: "Create a new (empty) prep file. `name` becomes the Event PGN tag. You then extend it with mutation tools (add_move, set_comment, …).\n\n" +
-            "ALWAYS call list_prep_files (or search_prep_files with the opponent / opening keyword) FIRST — creating a duplicate 'Prep vs Firouzja' when one exists is the #1 LLM failure mode. If a file already covers the topic, add moves to that one instead.",
+        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" +
+            "**collection_id is REQUIRED** — call `list_collections` first to pick where it lives. There is no default landing folder any more (v0.43: the old hidden `/mcp` collection was removed; prep files now live wherever the user organizes them).\n\n" +
+            "**Duplicate-check first.** Call `search_prep_files(query=<opponent / opening keyword>)` OR `find_position_in_files(fen=...)` before creating — a second 'Prep vs Firouzja' file when one already exists is a common LLM failure mode. If a file already covers the topic, extend that one instead.\n\n" +
+            "Response: `{ok, id, collection_id, version}` — `id` is a composite you pass to every other prep-file tool as `id` or `file_id`.",
         inputSchema: {
             type: "object",
             properties: {
+                collection_id: {
+                    type: "string",
+                    description: "Collection id from list_collections. Required — this is where the new file lands.",
+                },
                 name: {
                     type: "string",
                     description: "User-facing name — becomes the [Event] tag. Example: 'Prep vs Firouzja (Black) 2026-07-23'.",
                 },
             },
-            required: ["name"],
+            required: ["collection_id", "name"],
         },
     },
     {
@@ -646,7 +758,8 @@ const TOOLS = [
     {
         name: "add_line",
         description: "Append a linear sequence of moves under `parent_id`. Each SAN in the list becomes the mainline child of the previous — one call instead of N add_move calls for a straight variation. If the parent already has other children, this whole line is appended as a variation (promote_variation the first move if you want it as the mainline).\n\n" +
-            "Auto-saves. Returns `{node_id, line: [{node_id, san}, ...], version}` — `node_id` is the last (leaf) node's id, `line` is every node created in order so you can address any of them next.",
+            "**Anti-pattern: pasting an engine PV as a single long `add_line`.** Real prep is a tree, not a line. Almost every position along a variation has more than one plausible move — pasting a 12+-ply engine PV without branching at those points is the #1 documented failure mode of this MCP: it produces a page that reads as prep but ignores every decision the opponent actually gets to make. Long unbranched lines get a warning field in the response starting at ~9 plies and a strong warning at 14+ plies. Rule of thumb: if you added ≥8 plies in one call, at least half of them should have branched. Genuine exceptions exist (forced mates, obligated exchange sequences) — in those cases add a comment naming what makes the sequence forced (`{Every move here is forced by the mate threat.}`), so the reader knows it's forced by chess, not by LLM laziness.\n\n" +
+            "Auto-saves. Returns `{node_id, line: [{node_id, san}, ...], version}` — `node_id` is the last (leaf) node's id, `line` is every node created in order so you can address any of them next. When long-and-linear, also includes `warning: \"...\"`.",
         inputSchema: {
             type: "object",
             properties: {
@@ -660,7 +773,10 @@ const TOOLS = [
     },
     {
         name: "set_comment",
-        description: "Set (or clear, with empty string) the text comment on the node identified by `node_id`. Comments are for plans, prep-signal, and interpretation the app can't derive — NOT for describing moves that should be variations instead. Auto-saves.",
+        description: "Set (or clear, with empty string) the text comment on the node identified by `node_id`. Comments are for plans, prep-signal, and interpretation the app can't derive — NOT for describing moves that should be variations instead. Auto-saves.\n\n" +
+            "**Two guardrails fire in the response as `warnings: [...]`:**\n" +
+            "  1. **Content scan** — comments containing spread lists (`≈50, ≈42, …`), raw centipawn values (`≈−60`, `+0.35`, `at depth 24`), or roster restatement (`146 GM games — Nakamura, …`) are all restating what the app already renders. The warning names the fix (set the NAG and drop the number; label the character not the numbers; cite a specific game instead of a count).\n" +
+            "  2. **Ungrounded prose** — substantive comments (≥40 chars) on a node whose position was never passed to `describe_position` this session are prone to hallucinated structural claims (piece on wrong square, invented captures, misidentified pawn structure). Call `describe_position` with `file_id`+`node_id` BEFORE writing prose about the position; the same node's warning clears once the position is described.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1070,6 +1186,98 @@ async function fetchCompactEval(fen) {
 }
 // Rewrite the /api/agent/cloud-engines/analyse response (two engines,
 // each with lines[] and a bestMove) so PVs and bestMove come back in SAN.
+// Session-lifetime memory of which positions the LLM has actually asked
+// the DB about via `get_position_stats`. Keyed by the 3-field FEN
+// (piece placement + side to move + castling — same key used for
+// transposition detection). Used to warn on `add_move` / `add_line` under
+// a parent the LLM never DB-checked, which is the exact shape of the
+// bug where the LLM read course chapters and cargo-culted a "mainline"
+// that the actual games at the position don't play.
+//
+// One MCP server process per user, so this Set is effectively per-user
+// for the length of a session. Not persisted — a new session starts empty.
+const positionsStatsChecked = new Set();
+// Nodes we've ALREADY warned on for the "no stats check" pattern this
+// session, so repeated adds under the same parent don't spam the LLM.
+const noStatsWarned = new Set();
+// Session-lifetime memory of positions the LLM has called
+// `describe_position` on. Same 3-field FEN key. Live-log audit
+// (2026-07-27 Modern Defence session): 13 describe_position calls
+// vs 50+ set_comment ops — most comments were written blind. When
+// describe_position IS called before commentary, prose accuracy
+// jumps sharply (user's own observation). This tracks the same way
+// as positionsStatsChecked and drives the noDescribeWarning below.
+const positionsDescribed = new Set();
+// Once-per-node dedup for the describe warning.
+const noDescribeWarned = new Set();
+// Detect the anti-patterns the LLM keeps producing in comment prose.
+// All of these restate what the app already renders elsewhere:
+//   - spread lists ("5.O-O ≈50, 6.h3 ≈42, ...")
+//   - raw centipawn values in prose ("≈-60", "+0.35", "at depth 24")
+//   - long roster restatement ("146 GM games, Nakamura, Kramnik, MVL")
+// Return an array of warning strings — one per matched category — so the
+// LLM sees exactly which pattern to remove.
+function commentAntiPatterns(comment) {
+    if (!comment || typeof comment !== "string")
+        return [];
+    const warns = [];
+    // Spread list: ≈ followed by a 2-3-digit number, appearing 2+ times
+    // (one appearance is a stray, two+ is a comma-separated spread the LLM
+    // pasted from stats output).
+    const spreadMatches = comment.match(/≈\s*[+\-−]?\d{1,3}/g) ?? [];
+    if (spreadMatches.length >= 2) {
+        warns.push("comment contains a spread list (≈ + counts) — the DB viewer already shows sibling counts and fashion scores next to every move, so this is doubled noise. Name the character of the choice instead (\"solid vs sharp\", \"old vs fashionable\") or drop the numbers.");
+    }
+    // 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.
+    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.");
+    }
+    // Roster: "N GM games" pattern
+    if (/\b\d{2,4}\s+GM games\b/i.test(comment)) {
+        warns.push("comment restates game count — the app shows the count on hover. Either cite a specific game with signal (\"Caruana-Liang, Superbet 2026\") or drop the number.");
+    }
+    return warns;
+}
+// Return a warning string when an add_line is suspiciously long-and-linear
+// (the anti-pattern: LLM pastes a 15-ply engine PV into a single add_line
+// call as if it were prepared repertoire). Two thresholds so the message
+// escalates — a 10-ply Berlin mainline is fine, a 20-ply LLM extrapolation
+// almost never is. Threshold applies at the CALL level, not against
+// existing tree depth — the anti-pattern is a single tool call adding
+// many plies at once with no user thought about where the branching should
+// live.
+function longLineWarning(sansLength) {
+    if (sansLength >= 14) {
+        return `you added ${sansLength} plies in one call without branching — this is the shape of a pasted engine PV, not a repertoire. Real prep branches at every ply where the opponent has meaningful alternatives. Either (a) delete the tail and rebuild with add_move at each decision point, calling cloud_analyse + get_position_stats to see what actually gets played, or (b) if this really is one forcing sequence (mate combination, tactical winner), add a comment naming what makes it forced. Long unbranched lines with no comment default to "engine PV pasted as prep" in the reader's eyes.`;
+    }
+    if (sansLength >= 9) {
+        return `${sansLength}-ply linear line — check that every ply is a genuine only-move or a documented mainline. If the opponent has real alternatives at any ply (get_position_stats would show 2+ moves with meaningful frequency), that ply should branch instead. Prep is a tree, not a line.`;
+    }
+    return undefined;
+}
+// Trim every PV in a converted cloud-analyse response to `maxPlies`
+// and mark each trimmed line with `pv_truncated: true` so the LLM
+// sees what happened. Applied ONLY to cloud_analyse (short synchronous
+// snapshot); deep_analyse is the explicit "give me the deep line"
+// tool and keeps its full PV.
+function capPvsInResponse(converted, maxPlies) {
+    if (!converted || typeof converted !== "object")
+        return;
+    const r = converted;
+    for (const eng of [r.stockfish, r.lc0]) {
+        if (!eng || !Array.isArray(eng.lines))
+            continue;
+        for (const line of eng.lines) {
+            if (Array.isArray(line.pv) && line.pv.length > maxPlies) {
+                line.pv = line.pv.slice(0, maxPlies);
+                line.pv_truncated = true;
+            }
+        }
+    }
+    converted.pv_max_plies = maxPlies;
+}
 function convertCloudSnapshotResponse(raw, startFen) {
     if (!raw || typeof raw !== "object")
         return raw;
@@ -1115,17 +1323,37 @@ function dispatchMutation(file, idIndex, op) {
     };
     const resolve = (id) => resolveNodeId(idIndex, id);
     switch (kind) {
-        case "add_move":
-            return addMove(file, resolve(nodeIdField("parent_id")), String(op.san));
+        case "add_move": {
+            const parentPath = resolve(nodeIdField("parent_id"));
+            const parent = getNodeByPath(file.root, parentPath);
+            const noStatsWarn = noStatsCheckWarning(parent);
+            const step = addMove(file, parentPath, String(op.san));
+            return { ...step, ...(noStatsWarn ? { warning: noStatsWarn } : {}) };
+        }
         case "add_line": {
             const sans = Array.isArray(op.sans) ? op.sans.map(String) : [];
             const parentPath = resolve(nodeIdField("parent_id"));
+            const parent = getNodeByPath(file.root, parentPath);
             const step = addLine(file, parentPath, sans);
             const lastId = step.line.length > 0 ? step.line[step.line.length - 1].id : nodeIdField("parent_id");
-            return { file: step.file, id: lastId, results: step.line };
+            // Same anti-pattern warnings as the standalone add_line case —
+            // long unbranched line + no-stats-check parent are both bugs
+            // whether they land solo or inside a batch.
+            const longLineWarn = longLineWarning(sans.length);
+            const noStatsWarn = noStatsCheckWarning(parent);
+            const warnings = [longLineWarn, noStatsWarn].filter((s) => !!s);
+            return { file: step.file, id: lastId, results: step.line, ...(warnings.length > 0 ? { warnings } : {}) };
+        }
+        case "set_comment": {
+            const commentStr = typeof op.comment === "string" ? op.comment : "";
+            const commentWarns = commentAntiPatterns(commentStr);
+            const targetPath = resolve(nodeIdField("node_id"));
+            const targetNode = getNodeByPath(file.root, targetPath);
+            const describeWarn = noDescribeWarning(targetNode, commentStr);
+            const step = setComment(file, targetPath, commentStr);
+            const all = [...commentWarns, ...(describeWarn ? [describeWarn] : [])];
+            return { ...step, ...(all.length > 0 ? { warnings: all } : {}) };
         }
-        case "set_comment":
-            return setComment(file, resolve(nodeIdField("node_id")), typeof op.comment === "string" ? op.comment : "");
         case "set_nags":
             return setNags(file, resolve(nodeIdField("node_id")), Array.isArray(op.nags) ? op.nags.map(String) : []);
         case "set_annotations": {
@@ -1157,10 +1385,7 @@ async function applyBatchMutations(args) {
     const mutations = Array.isArray(args.mutations) ? args.mutations : [];
     if (mutations.length === 0)
         throw new Error("mutations array required");
-    const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
-    const g = raw;
-    if (typeof g.pgnContent !== "string")
-        throw new Error("prep file missing pgnContent");
+    const g = await fetchGame(id);
     let file = parsePGN(g.pgnContent);
     let idIndex = buildIdIndex(file.root);
     const results = [];
@@ -1170,7 +1395,12 @@ async function applyBatchMutations(args) {
             const step = dispatchMutation(file, idIndex, op);
             file = step.file;
             idIndex = buildIdIndex(file.root);
-            results.push({ node_id: step.id, ...(step.results !== undefined ? { line: step.results } : {}) });
+            results.push({
+                node_id: step.id,
+                ...(step.results !== undefined ? { line: step.results } : {}),
+                ...(step.warning ? { warning: step.warning } : {}),
+                ...(step.warnings && step.warnings.length > 0 ? { warnings: step.warnings } : {}),
+            });
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -1179,12 +1409,8 @@ async function applyBatchMutations(args) {
     }
     const newPgn = exportPGN(file);
     const expected = typeof args.expected_version === "number" ? args.expected_version : g.version;
-    const saved = await authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(id)}`, {
-        pgn: newPgn,
-        expected_version: expected,
-    });
-    const savedRow = saved;
-    return { ok: true, results, version: savedRow.version };
+    const saved = await saveGame(id, newPgn, expected);
+    return { ok: true, results, version: saved.version };
 }
 const evalJobs = new Map();
 // GC finished jobs after this long so status polling remains useful
@@ -1219,10 +1445,7 @@ async function autoEvaluate(args) {
         : ROOT_ID;
     const onlyMissing = args.only_missing !== false; // default true
     const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : 1500;
-    const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
-    const g = raw;
-    if (typeof g.pgnContent !== "string")
-        throw new Error("prep file missing pgnContent");
+    const g = await fetchGame(id);
     const file = parsePGN(g.pgnContent);
     const idIndex = buildIdIndex(file.root);
     const startPath = resolveNodeId(idIndex, startNodeId);
@@ -1835,10 +2058,7 @@ function storedEvalToCompact(ev, analysis) {
 // resolve node_ids without rebuilding the index itself.
 async function applyMutation(args, mutator) {
     const id = String(args.id);
-    const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
-    const g = raw;
-    if (typeof g.pgnContent !== "string")
-        throw new Error("prep file missing pgnContent");
+    const g = await fetchGame(id);
     const file = parsePGN(g.pgnContent);
     const idIndex = buildIdIndex(file.root);
     let result;
@@ -1853,24 +2073,60 @@ async function applyMutation(args, mutator) {
     }
     const newPgn = exportPGN(result.file);
     const expected = typeof args.expected_version === "number" ? args.expected_version : g.version;
-    const saved = await authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(id)}`, {
-        pgn: newPgn,
-        expected_version: expected,
-    });
-    const savedRow = saved;
+    const saved = await saveGame(id, newPgn, expected);
     return {
         ok: true,
         node_id: result.id,
         ...(result.results !== undefined ? { line: result.results } : {}),
-        version: savedRow.version,
+        ...(result.warning ? { warning: result.warning } : {}),
+        ...(result.warnings && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+        version: saved.version,
     };
 }
+// Compute the "you never called describe_position on this node" warning.
+// Fires from set_comment when the comment is substantive (>= 40 chars —
+// anything shorter is a label / pointer, doesn't need structural
+// grounding). LLMs are unreliable at reading FEN strings and confidently
+// describe positions that don't match the actual board; describe_position
+// is a pure-computation grounding pass that reliably fixes this. Warn
+// once per node.
+function noDescribeWarning(node, comment) {
+    if (node.id === ROOT_ID)
+        return undefined;
+    if (comment.length < 40)
+        return undefined;
+    const key = positionKey(node.fen);
+    if (positionsDescribed.has(key))
+        return undefined;
+    if (noDescribeWarned.has(node.id))
+        return undefined;
+    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.`;
+}
+// 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
+// starting position doesn't need a DB check), (b) we already warned on
+// this parent (dedup so building a big branching subtree isn't spammy),
+// or (c) the mutator is running against a parent whose position has a
+// stored ceoEval (implies the LLM has done SOME analytical work here).
+function noStatsCheckWarning(parent) {
+    if (parent.id === ROOT_ID)
+        return undefined;
+    const key = positionKey(parent.fen);
+    if (positionsStatsChecked.has(key))
+        return undefined;
+    if (noStatsWarned.has(parent.id))
+        return undefined;
+    noStatsWarned.add(parent.id);
+    return `no get_position_stats call for the parent (id=${parent.id}, ${parent.san}) this session. Course chapter titles describe what an author chose to cover, not what practical opponents play — treating "the So chapter says 6.O-O-O" as "the mainline is 6.O-O-O" is the exact pattern this warning exists to catch. Call get_position_stats at this position (via file_id+node_id=${parent.id}) BEFORE deciding which branches belong here; suppress this warning by making that call. Warned once per parent per session.`;
+}
 async function loadPrepFile(id) {
-    const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
-    const g = raw;
-    if (typeof g.pgnContent !== "string")
-        throw new Error("prep file missing pgnContent");
-    return { file: parsePGN(g.pgnContent), version: g.version, fileIdEcho: g.id, pgn: g.pgnContent };
+    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.
@@ -1922,6 +2178,91 @@ function projectNode(node, view, depthLeft, fenIndex = null) {
     }
     return base;
 }
+async function listCollections(_args) {
+    const raw = await authedRequest("GET", PGN_BASE);
+    const collections = unwrap(raw) ?? [];
+    return {
+        collections: collections.map(c => ({
+            id: c.id,
+            title: c.title,
+            icon: c.icon,
+            folder_path: c.folderPath,
+            game_count: c.gameCount,
+            position_search_enabled: c.positionSearchEnabled,
+            updated_at: c.updatedAt,
+        })),
+    };
+}
+// Convert a browser-returned game list row into the LLM shape (composite
+// id, cleaned field names).
+function projectGameRow(row) {
+    const collId = row.collectionId ?? "";
+    return {
+        id: collId ? makeFileId(collId, row.id) : row.id,
+        collection_id: collId,
+        collection_title: row.collectionTitle,
+        event: row.event,
+        white: row.white_player,
+        black: row.black_player,
+        eco: row.eco,
+        opening: row.opening,
+        updated_at: row.updated_at,
+        ply: row.ply,
+    };
+}
+async function listPrepFiles(args) {
+    const collectionId = typeof args.collection_id === "string" ? args.collection_id.trim() : "";
+    if (!collectionId) {
+        throw new Error("collection_id required — call list_collections to see your options, or search across collections with search_prep_files / find_position_in_files");
+    }
+    // Browser handler at GET /me/pgns/{id}/games returns a paginated list.
+    const raw = await authedRequest("GET", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games?page=1&limit=200`);
+    const data = unwrap(raw);
+    const games = data?.games ?? (Array.isArray(data) ? data : []);
+    return { collection_id: collectionId, prep_files: games.map(projectGameRow) };
+}
+async function searchPrepFiles(args) {
+    const q = typeof args.query === "string" ? args.query.trim() : "";
+    if (!q)
+        throw new Error("query required");
+    const raw = await authedRequest("GET", `${PGN_BASE}/games/search?q=${encodeURIComponent(q)}&limit=100`);
+    const data = unwrap(raw);
+    const games = data?.games ?? [];
+    return { query: q, prep_files: games.map(projectGameRow) };
+}
+async function findPositionInFiles(args) {
+    // FEN can come from a node handle OR a direct fen/moves/line. Reuse
+    // the same resolver everything else uses.
+    const resolved = await resolveFromNodeOrFen(args);
+    const fen = resolved.fen;
+    const raw = await authedRequest("GET", `${PGN_BASE}/games/search?position=${encodeURIComponent(fen)}&limit=100`);
+    const data = unwrap(raw);
+    const games = data?.games ?? [];
+    return {
+        fen,
+        match_count: games.length,
+        prep_files: games.map(projectGameRow),
+    };
+}
+async function createPrepFile(args) {
+    const collectionId = typeof args.collection_id === "string" ? args.collection_id.trim() : "";
+    if (!collectionId) {
+        throw new Error("collection_id required — call list_collections to pick where the new file lives. There is no default landing folder any more (v0.43: the old hidden /mcp collection was removed).");
+    }
+    const name = String(args.name || "").trim();
+    if (!name)
+        throw new Error("name is required");
+    // Seed with a PGN carrying the LLM-chosen name as the Event tag so
+    // subsequent list_prep_files calls display something useful.
+    const seedPgn = `[Event "${name.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"]\n\n*\n`;
+    const game = await createGame(collectionId, seedPgn);
+    return {
+        ok: true,
+        id: makeFileId(game.collectionId ?? collectionId, game.id),
+        collection_id: game.collectionId ?? collectionId,
+        version: game.version,
+    };
+}
 async function readPrepFile(args) {
     const id = String(args.id);
     const view = (typeof args.view === "string" && ["compact", "full", "spine", "pgn"].includes(args.view))
@@ -2298,10 +2639,7 @@ async function resolveFromNodeOrFen(args) {
     const fileId = typeof args.file_id === "string" ? args.file_id.trim() : "";
     const nodeId = typeof args.node_id === "string" ? args.node_id.trim() : "";
     if (fileId && nodeId) {
-        const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(fileId)}`);
-        const g = raw;
-        if (typeof g.pgnContent !== "string")
-            throw new Error("prep file missing pgnContent");
+        const g = await fetchGame(fileId);
         const parsedFile = parsePGN(g.pgnContent);
         const idIndex = buildIdIndex(parsedFile.root);
         const nodePath = resolveNodeId(idIndex, nodeId);
@@ -2317,18 +2655,15 @@ async function resolveFromNodeOrFen(args) {
         // node_id had been supplied (auto-persist on match).
         const fen = resolveFenFromArgs(args);
         try {
-            const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(fileId)}`);
-            const g = raw;
-            if (typeof g.pgnContent === "string") {
-                const parsedFile = parsePGN(g.pgnContent);
-                const match = findNodeByFen(parsedFile.root, fen);
-                if (match) {
-                    const idIndex = buildIdIndex(parsedFile.root);
-                    return {
-                        fen,
-                        file: { id: fileId, version: g.version ?? 0, parsedFile, idIndex, nodePath: match.path, fen },
-                    };
-                }
+            const g = await fetchGame(fileId);
+            const parsedFile = parsePGN(g.pgnContent);
+            const match = findNodeByFen(parsedFile.root, fen);
+            if (match) {
+                const idIndex = buildIdIndex(parsedFile.root);
+                return {
+                    fen,
+                    file: { id: fileId, version: g.version ?? 0, parsedFile, idIndex, nodePath: match.path, fen },
+                };
             }
         }
         catch {
@@ -2389,10 +2724,7 @@ async function storeEvalOnNode(handle, ev) {
         const paths = group.map(n => resolveNodeId(idIndex, n.id));
         const { file: newFile, ids } = setCeoEvalMany(handle.parsedFile, paths, ev);
         const newPgn = exportPGN(newFile);
-        await authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(handle.id)}`, {
-            pgn: newPgn,
-            expected_version: handle.version,
-        });
+        await saveGame(handle.id, newPgn, handle.version);
         // Ensure the primary node (the one the LLM addressed) comes first.
         const anchorId = anchor.id;
         return [anchorId, ...ids.filter(x => x !== anchorId)];
@@ -2529,6 +2861,10 @@ async function callToolInner(name, args) {
                 if (ev)
                     converted.eval = ev;
             }
+            // Record that this position was DB-checked this session. Downstream
+            // add_move / add_line under this parent won't fire the "no stats
+            // check" warning. Keyed by 3-field FEN so transpositions count.
+            positionsStatsChecked.add(positionKey(fen));
             return converted;
         }
         case "describe_position": {
@@ -2552,6 +2888,10 @@ async function callToolInner(name, args) {
             if (ev && ev.found === true) {
                 merged.engineEvalTerms = { terms: ev.terms, total: ev.total };
             }
+            // Record so set_comment on this node won't fire the "not described"
+            // warning. Keyed by 3-field FEN so a described position is
+            // credited across its transpositions too.
+            positionsDescribed.add(positionKey(resolved.fen));
             return merged;
         }
         case "predict_human_move": {
@@ -2627,6 +2967,21 @@ async function callToolInner(name, args) {
                 body.engines = args.engines;
             const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
             const converted = convertCloudSnapshotResponse(raw, fen);
+            // PV cap: engine PVs beyond ~6 plies are speculative (the tail is
+            // where the search's confidence collapses — SF at depth 24 has
+            // seen the first few plies solidly and hedged everything after).
+            // More importantly, LLMs paste long PVs into `add_line` as if
+            // they were prepared repertoire. A 15-move PV pasted as a
+            // variation is one line of engine output through positions
+            // where both sides had real choices — not a repertoire. Cap the
+            // affordance: return only what's load-bearing (3 full moves for
+            // understanding the point), let the caller re-analyse the
+            // resulting position if they want to see further. Override via
+            // `pv_max_plies` for the rare case (deep tactics verification).
+            const pvMaxPlies = typeof args.pv_max_plies === "number" && args.pv_max_plies > 0
+                ? Math.min(args.pv_max_plies, 40)
+                : 6;
+            capPvsInResponse(converted, pvMaxPlies);
             // Node-addressed calls: persist the result on the node's ceoEval
             // so a later quote_engine_eval can cite this measurement. This is
             // the anti-hallucination hinge — prose that says "engines say X
@@ -2657,10 +3012,14 @@ async function callToolInner(name, args) {
             return findPositionInCourses(args);
         case "read_course_at_position":
             return readCourseAtPosition(args);
+        case "list_collections":
+            return listCollections(args);
         case "list_prep_files":
-            return authedRequest("GET", "/api/agent/prep-files");
+            return listPrepFiles(args);
         case "search_prep_files":
-            return authedRequest("GET", `/api/agent/prep-files/search?q=${encodeURIComponent(String(args.query))}`);
+            return searchPrepFiles(args);
+        case "find_position_in_files":
+            return findPositionInFiles(args);
         case "read_prep_file":
             return readPrepFile(args);
         case "list_nodes":
@@ -2668,23 +3027,52 @@ async function callToolInner(name, args) {
         case "list_transpositions":
             return listTranspositions(args);
         case "create_prep_file":
-            return authedRequest("POST", "/api/agent/prep-files", {
-                name: String(args.name),
-            });
-        case "delete_prep_file":
-            return authedRequest("DELETE", `/api/agent/prep-files/${encodeURIComponent(String(args.id))}`);
+            return createPrepFile(args);
+        case "delete_prep_file": {
+            await deleteGame(String(args.id));
+            return { ok: true };
+        }
         case "add_move":
-            return applyMutation(args, (file, idIndex) => addMove(file, resolveNodeId(idIndex, argNodeId(args, "parent_id")), String(args.san)));
-        case "add_line":
             return applyMutation(args, (file, idIndex) => {
-                const sans = Array.isArray(args.sans) ? args.sans.map(String) : [];
                 const parentPath = resolveNodeId(idIndex, argNodeId(args, "parent_id"));
-                const step = addLine(file, parentPath, sans);
+                const parent = getNodeByPath(file.root, parentPath);
+                const noStatsWarn = noStatsCheckWarning(parent);
+                const step = addMove(file, parentPath, String(args.san));
+                return { ...step, ...(noStatsWarn ? { warning: noStatsWarn } : {}) };
+            });
+        case "add_line": {
+            const sansArg = Array.isArray(args.sans) ? args.sans.map(String) : [];
+            const longLineWarn = longLineWarning(sansArg.length);
+            return applyMutation(args, (file, idIndex) => {
+                const parentPath = resolveNodeId(idIndex, argNodeId(args, "parent_id"));
+                const parent = getNodeByPath(file.root, parentPath);
+                const noStatsWarn = noStatsCheckWarning(parent);
+                const step = addLine(file, parentPath, sansArg);
                 const lastId = step.line.length > 0 ? step.line[step.line.length - 1].id : argNodeId(args, "parent_id");
-                return { file: step.file, id: lastId, results: step.line };
+                const combined = [longLineWarn, noStatsWarn].filter((s) => !!s);
+                return {
+                    file: step.file,
+                    id: lastId,
+                    results: step.line,
+                    ...(combined.length > 0 ? { warnings: combined } : {}),
+                };
+            });
+        }
+        case "set_comment": {
+            const commentStr = typeof args.comment === "string" ? args.comment : "";
+            const commentWarns = commentAntiPatterns(commentStr);
+            return applyMutation(args, (file, idIndex) => {
+                const targetPath = resolveNodeId(idIndex, argNodeId(args));
+                const targetNode = getNodeByPath(file.root, targetPath);
+                const describeWarn = noDescribeWarning(targetNode, commentStr);
+                const step = setComment(file, targetPath, commentStr);
+                const all = [...commentWarns, ...(describeWarn ? [describeWarn] : [])];
+                return {
+                    ...step,
+                    ...(all.length > 0 ? { warnings: all } : {}),
+                };
             });
-        case "set_comment":
-            return applyMutation(args, (file, idIndex) => setComment(file, resolveNodeId(idIndex, argNodeId(args)), typeof args.comment === "string" ? args.comment : ""));
+        }
         case "set_nags":
             return applyMutation(args, (file, idIndex) => setNags(file, resolveNodeId(idIndex, argNodeId(args)), Array.isArray(args.nags) ? args.nags.map(String) : []));
         case "set_annotations": {
@@ -2715,10 +3103,7 @@ async function callToolInner(name, args) {
         case "quote_engine_eval": {
             const fileId = String(args.id);
             const nodeId = argNodeId(args);
-            const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(fileId)}`);
-            const g = raw;
-            if (typeof g.pgnContent !== "string")
-                throw new Error("prep file missing pgnContent");
+            const g = await fetchGame(fileId);
             const file = parsePGN(g.pgnContent);
             const idIndex = buildIdIndex(file.root);
             const path = resolveNodeId(idIndex, nodeId);

package/docs/engine-usage.md

@@ -191,8 +191,19 @@ Two calls:
 
 If the user is specifically preparing to *play* the black side in a must-win, add `contempt=-30` (or up to `-60` for a harder steer) on a follow-up call to see which lines Lc0 finds most fighting for Black. Compare against Stockfish's objective read to make sure the fighting choice isn't just losing.
 
+## The PV is not a line to paste
+
+`cloud_analyse` caps each PV at 6 plies (3 full moves) by default and marks longer ones `pv_truncated: true`. This is deliberate — the tail of a PV is where the engine's confidence collapses (SF at depth 24 has resolved the first few plies solidly and hedged everything after), and pasting long PVs into `add_line` as prep is the biggest documented anti-pattern of this whole system.
+
+**A PV tells you what the engine sees, not what will be played.** A 15-ply PV pasted as a variation is one line of engine output through positions where the opponent had 2-3 real alternatives at almost every ply. That's not prep — that's the engine's preferred game, and no opponent plays the engine's preferred game.
+
+**To see further into a line, walk the tree.** Take the position at the tail of your truncated PV, run a fresh `cloud_analyse` on it. That call gives you the multipv candidate set at THAT position — the opponent's actual options — which is what you need to decide whether to branch. Don't raise `pv_max_plies` unless you're verifying a forcing sequence (a mate, an obligated recapture chain).
+
+Practical: raise `lc0_multipv` (default 8) to see the candidate spread on the current position, NOT to see further down one PV. If Lc0 shows moves 1-3 within 0.15 of each other, that's a branching point — three responses need coverage, not one PV.
+
 ## What NOT to do
 
+- **Don't paste PVs as `add_line` variations.** See the section above and `pgn-authoring.md`'s "Prep is a TREE, not a line" section. This is not a stylistic preference — the tool warns you starting at 9 plies and warns hard at 14+, and the truncated `pv_truncated: true` marker is telling you the engine itself doesn't stand behind the tail.
 - **Don't quote Lc0's contempt-biased eval as objective.** If you tell the user "Lc0 gives Black +0.30 here" without disclosing you set contempt=-30, that's misleading.
 - **Don't run cloud analysis just for casual questions.** `cloud_analyse` costs the user real money per second. If the question is "is 1.e4 or 1.d4 better?", the free `analyse` (single Stockfish, 2s) or `get_position_stats` (11.7M-game database) is enough.
 - **Don't ignore the disagreement.** When Stockfish and Lc0 diverge sharply, that's exactly when you should explain *why* to the user — not paper over it.

package/docs/pgn-authoring.md

@@ -155,15 +155,80 @@ Prose is NEVER for:
 - Move recommendations ("here White should play h4") — add_move it.
 - Restating the eval a NAG already conveys.
 - **Describing a sibling variation you already added as a branch.** If move A has variation B added as `add_move(A, sibling)`, don't ALSO write `{if B then ...}` on A. The reader clicks B on the board — the branch is already there.
-- **Restating what the app already renders.** The reader opens the file in the app and sees: every sibling move (with count / avg rating / top players from the DB), each node's stored `ceoEval`, the NAG glyphs, the tree structure. Duplicating any of that in prose is pure noise.
+- **Restating what the app already renders.** The reader opens the file in the app and sees: every sibling move (with count / avg rating / top players from the DB), each node's stored `ceoEval`, the NAG glyphs, the tree structure. Duplicating any of that in prose is pure noise. Three specific patterns to never emit:
 
-  - ❌ `{5...Bb4 (180/247), 5...d6 (26), 5...Be7 (18), 5...d5 (7), 5...g6 (2)}` — those are the sibling variations, already visible.
-  - ❌ `{Main move, 180 of 247 games (So, Giri, Karjakin, Duda). Eval −0.20/−0.27.}` — count, top players, eval all shown by the app.
-  - ✅ `{Main move; the sharpest test is actually 5...d5 (only 7 games but avg 2526) — see the variation.}`
-  - ✅ `{Popular, but leads to the endgame Black draws — 6.Bd2 is where prep depth matters.}`
+  **1. Spread lists.** The database viewer already shows sibling counts and fashion scores next to every move. Pasting them into prose is doubled noise.
+
+  - ❌ `{Spread: 5.O-O ≈50, 6.h3 ≈42, 6.a4 ≈35, 6.Be3 ≈27, 6.Nbd2 ≈18 — the more White delays castling the less he gets.}` — every number here is one click away.
+  - ❌ `{Spread: 5.Nf3 ≈56, 5.Bd3 ≈55, 5.Be3 ≈47, 5.Rb1 ≈35, 5.h3 ≈32.}` — same problem.
+  - ✅ `{Two roads: quiet 5.Bd3 keeps position closed, sharp 5.e5 concedes the centre for tempo — cover both.}` — names the *character*, not the numbers.
+
+  **2. Raw centipawn values in prose.** The app shows `ceoEval` as `+0.20 / −0.27` next to every node and the NAG glyph next to that. If you write `≈−60` or `+0.35` in a comment, no reader knows whether that's a spread number, an eval, or a made-up decoration — and every one of them is visible without your prose.
+
+  - ❌ `{Best try, but ≈80 — a fifth of a pawn worse than the ...Nd7 move order.}` — cp number, opaque.
+  - ❌ `{0.00 at depth 31, 259M nodes.}` — engine metadata masquerading as insight; the eval is already visible.
+  - ❌ `{≈−60. White's f5 sacrifice does not work with the centre already liquidated.}` — the number tells the reader nothing; the *reason* is the whole comment.
+  - ✅ `{White's f5 sacrifice doesn't work with the centre already liquidated — no target for the pawn.}` — same content, no fake precision.
+  - ✅ Or better: set the NAG (`$17` for clear Black advantage) and drop the prose entirely; the glyph carries the judgment.
+
+  **3. Top-player rosters.** Count + names of the top players are shown on hover in the app. `146 GM games, Nakamura, Kramnik, MVL, So all play this` restates two visible facts.
+
+  - ❌ `{150 GM games and Caruana's choice against Liang in 2026.}` — count is visible; the specific-game citation is fine on its own if it carries prep signal.
+  - ✅ `{Caruana played this against Liang, Superbet 2026 — the current top-choice among elite Black players.}` — same specific-game citation, no restated count.
+
+  **Positive vocabulary for what the app can't render.** The reader wants labels the DB doesn't provide:
+
+  - `{The old main line — dominant through 2015, replaced by 6.Bd2 after Ding-Carlsen 2016.}` — historical context, not visible.
+  - `{The current fashion — 40+ games since 2024, mostly at 2700+.}` — recency signal condensed to a phrase, not a number list.
+  - `{Solid try (holds objectively) vs the sharper 6.Nd5 (small edge but requires memory) — choose based on style.}` — practical framing, uses labels the reader can act on.
+  - `{Prophylactic — every White plan is based on Bg5, this pre-empts it.}` — one word (prophylactic / restraint / clamp / breakthrough) does the work of a paragraph.
 
   Test: if the reader can see it by looking at the position or clicking a branch, don't write it. Prose is only for plans, prep-signal, or WHY — the layer the app can't derive.
 
+- **Prose "prevents Y" claims — always show Y as a `?`-tagged variation instead.** When you write `{6.f3 is necessary to prevent ...Bxh3.}` the reader has to trust you that the tactic exists. When you instead add a sibling variation `6.O-O? Bxh3 7.gxh3 …` marked with `?` in the NAG, the reader can play through the refutation themselves. Two benefits: (1) grounds the claim in an actual move sequence, so hallucinated tactics get exposed at authoring time when SAN validation runs; (2) the reader learns the tactic instead of taking your word for it. Rule: any prose of the shape "X because it prevents/avoids/deals with Y" should be either supplemented by or replaced with a `?`-marked variation showing Y.
+
+  - ❌ `{6.f3 is necessary — 6.O-O? runs into ...Bxh3 winning the exchange.}` — no way to check.
+  - ✅ Under 5.Nc3, add both `6.f3` (mainline) AND `6.O-O` as a sibling variation with `set_nags(["$2"])` and continuation `[Bxh3, gxh3, ...]` showing the refutation. The prose on 6.f3 shrinks to `{The 6.O-O branch shows why f3 must come first.}` — six words, refutation is playable.
+
+## Prep is a TREE, not a line — the pasted-engine-PV anti-pattern
+
+This is the single biggest quality problem in current LLM output on this system: after a `cloud_analyse` call the LLM sees a PV like `[Nf3, Nc6, Bb5, a6, Ba4, Nf6, O-O, Be7, Re1, b5, Bb3, O-O, ...]` and pastes it into a single `add_line`. 15 moves in one call, no branching, no reason to think the opponent will play any of those specific moves — one line of engine output through positions where both sides had real choices.
+
+**The reader can tell.** A pasted engine PV always looks the same: long, straight, no comments, no NAGs, ends in a position with no obvious relevance. It's the shape of the output, not the individual moves, that gives it away.
+
+**The fix is branching, not length.** Every ply along a variation is a decision point for whoever's turn it is. If the opponent has more than one plausible move at that ply (`get_position_stats` shows two or more moves with meaningful frequency; `predict_human_move` shows two or more moves with real WDL differences; `cloud_analyse.lc0.lines` shows several evals within 0.2 of each other), then that ply MUST branch — you're not preparing if you only cover one response.
+
+**Concrete rules:**
+
+- **`cloud_analyse` PVs are capped at 6 plies by default and marked `pv_truncated: true` when longer.** This is not a bug — it's telling you that the engine's confidence tail is not repertoire material. To see further into a line, don't raise `pv_max_plies` — pick the position at the end of the truncated PV and run a fresh `cloud_analyse` on it. That's what makes it prep instead of pasted output.
+
+- **`add_line` warns when you pass ≥9 plies** and warns hard at ≥14 plies. Long unbranched lines with no comment default to "engine PV pasted as prep" in the reader's eyes. Rule of thumb: if you added ≥8 plies in one call, at least half of them should have branched.
+
+- **Genuine forcing sequences ARE allowed** — a 12-ply mate combination, an obligated exchange sequence where both sides have exactly one reasonable move at every ply. In those cases: (a) write a comment naming what makes it forced (`{Every move here is forced by the mate threat on h7.}`), and (b) don't stop where the engine PV stops — stop where the position becomes evaluatable ("winning endgame, technique wins"; "mate in 3, easy calculation from here").
+
+**Correct pattern for building a variation.** At every ply:
+
+1. What are the plausible replies? `get_position_stats` (frequencies), `cloud_analyse` with `lc0_multipv: 8` (candidate spread), `predict_human_move` (what people actually play).
+2. If ≥2 are plausible → branch. `add_move` each, then recurse on each branch or `add_line` for each of the several straightforward continuations.
+3. If exactly 1 → continue linearly; note *why* it's the only move in a comment.
+
+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.
+
+## 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.
+
+**Course chapter titles tell you what the author decided to cover, not what practical opponents play.** A White repertoire author picks one continuation per branch and writes it up in depth — the chapter is named after what they cover. That is not the same as "this is the mainline in current practice", nor is it the same as "this is the most-played move against 5...Nd7". Five different courses can all pick different 6th moves for the same position; five different courses can all pick the SAME 6th move for coverage reasons (that's the sharpest / most-testing / easiest-to-teach) even though the DB shows practice is split five ways.
+
+**Rule:** before committing to a mainline branch — either `add_move` as the first child of a parent that's on the mainline, or `add_line` for a linear continuation you're calling THE way White/Black plays — you must have called `get_position_stats` at that parent position in this session. If you didn't, the mutation will warn (soft). Course reads are for what the authors *say about the move*, not what the mainline *is*.
+
+**How the two tools relate at a branching decision:**
+
+1. `get_position_stats(position)` — what moves are actually played, ranked by count / avg rating / fashion. This decides which moves need a branch (any move ≥5% frequency in reasonable practice; any move with unusually high avg rating even if less frequent).
+2. `find_position_in_courses(position)` → `read_course_at_position(...)` — for each branch you decided to include, what do the authors say about it, and where do they disagree. This decides the *content* of each branch (recommended reply, key concepts, historical context), not which branches exist.
+
+Getting these backwards is the failure this section exists to prevent.
+
 ## Transpositions: don't analyse (or comment on) the same position twice
 
 Move orders diverge and re-converge constantly. `1.d4 Nf6 2.c4 e6 3.Nc3` and `1.c4 e6 2.Nc3 Nf6 3.d4` land on the same position. The tree model doesn't merge those into one node — it stores both nodes with the same position — so if you're not careful you'll analyse both, quote engine numbers on both, and write two different comments for what is the same chess.
@@ -251,7 +316,9 @@ Contempt scale is signed 0-100 (same as the web UI's ContemptStrength slider). T
 
 ### Before you write any commentary: describe_position
 
-LLMs are not reliable at reading FEN strings — you'll swap files/ranks, invent captures, miscount pieces. Before you write a comment describing what's happening in a position, call `describe_position(fen)`. Pure computation (~1 ms, no engine), returns two layers:
+**This is the biggest lever for prose quality in the whole system.** Live audit of a recent session — 13 `describe_position` calls versus 50+ `set_comment` ops. The nodes where `describe_position` was called first produced comments that grounded specifically in the position (correct piece squares, real pawn structure, actual weak squares). The nodes where it wasn't produced generic prose that pattern-matched to similar-*looking* positions and confidently named pieces on wrong squares. This gap is why `set_comment` now emits a warning whenever a substantive comment (≥40 chars) lands on a node whose position was never grounded via `describe_position` this session.
+
+LLMs are not reliable at reading FEN strings — you'll swap files/ranks, invent captures, miscount pieces. Before you write a comment describing what's happening in a position, call `describe_position` (with `file_id`+`node_id` inside a prep file). Pure computation (~1 ms, no engine), returns two layers:
 
 **Board state** — piece placements, material, contested pieces (attackers + defenders), hanging list, check state, castling, en passant, legal moves. Fixes the *"Black's queen on c7 is defended by the knight on d5"* failure when actually there's no knight on d5 and the queen is on c8.
 

package/docs/prep-files-guide.md

@@ -4,16 +4,23 @@ You can save chess prep to the user's chess.ceo account and read it back across
 
 ## 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.
+The user has **any number of PGN collections** in their chess.ceo library — you have full access to every non-encrypted one. A **prep file** is one PGN game with variations, inside a collection. Every prep file id is a composite `<collection_id>:<game_id>` — opaque to you, pass it through unchanged to any tool that takes `id` or `file_id`.
 
-File-level tools:
+Discovery tools:
 
-- `list_prep_files` — show me all my prep files
-- `search_prep_files(query)` — find by opponent name / opening keyword
-- `read_prep_file(id)` — parsed tree (every node carries a stable `id`) + tags + `version`
-- `create_prep_file(name)` — new empty file, `name` becomes the [Event] tag
+- `list_collections` — show me all the user's collections (their organizational scheme is theirs; browse before creating)
+- `list_prep_files(collection_id)` — the games inside one collection
+- `search_prep_files(query)` — text search across ALL of the user's collections
+- `find_position_in_files(fen)` — position search across ALL of the user's collections (matched by zobrist hash so move-order variants are found automatically). Distinct from `find_position_in_courses` — that's the user's read-only reference library (Chessable etc.); this is their own editable prep
+
+Per-file tools:
+
+- `read_prep_file(id)` — parsed tree (every node carries a stable content-derived `id`) + tags + `version`
+- `create_prep_file(collection_id, name)` — new empty file inside the given collection, `name` becomes the [Event] tag
 - `delete_prep_file(id)` — soft delete (user can restore from app)
 
+**No default landing folder.** v0.43 removed the old hidden `/mcp` collection — prep files now live wherever the user organizes them. Every `create_prep_file` call REQUIRES `collection_id`; call `list_collections` first if you don't have one. Permanent delete is not exposed on this surface — the user does that from the app.
+
 Mutation tools (edit an existing file — you never touch raw PGN):
 
 - `apply_mutations(id, [...])` — batch: N ops in one save. **Primary build tool.**
@@ -25,11 +32,12 @@ Every mutation call takes a `node_id` (or `parent_id` for add-style ops) and aut
 
 **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)
+1. **Text search first**: `search_prep_files(query=<opponent name or opening keyword>)` — searches across every collection the user owns.
+2. **Position search when the request is position-shaped** ("prep me against 6.f3 in the Najdorf"): `find_position_in_files(fen=<the specific tabiya>)` — catches files that reach the position via a different move order too. This is often more accurate than text search because file names don't always mention every position they cover.
+3. Read the ones that look relevant.
+4. Decide: extend an existing one or genuinely start fresh (`create_prep_file(collection_id, name)`).
 
-Duplicate files are the #1 way to lose your user's trust in this system.
+Duplicate files are the #1 way to lose your user's trust in this system. Two searches (text + position) cost roughly nothing and catch nearly all overlap.
 
 ## Before writing any prose: read the examples
 
@@ -107,6 +115,8 @@ Keep it short enough to fit in a picker (30-40 chars). Long titles get truncated
 - 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
+## Appearance
+
+Prep files land in whichever collection the user picked (via `create_prep_file(collection_id, name)`). They're first-class citizens in that collection — the user can browse, edit, share, or delete them from the app exactly like manually-created games. Your only visibility signal is the [Event] tag; make it descriptive.
 
-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.
+The `/mcp` "AI Prep" hidden folder from earlier versions no longer exists. If the user has a collection literally named "AI Prep" it's one they created themselves.

package/package.json

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