@chessceo/mcp 0.44.0 → 0.48.2

package/dist/index.js

@@ -7,24 +7,30 @@
 // endpoints — see the public contract at https://chess.ceo/llms.txt.
 // No API key, no auth, no state; the API's own rate limits apply.
 import { createServer as createHttpServer } from "node:http";
-import { spawn } from "node:child_process";
 import { readFileSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { Chess } from "chess.js";
 import { parsePGN } from "./pgn/parser.js";
-import { exportPGN } from "./pgn/exporter.js";
 import { describePosition } from "./pgn/describe.js";
-import { addLine, addMove, deleteSubtree, MutationError, promoteVariation, setAnnotations, setCeoEval, setCeoEvalMany, setComment, setNags, setTag, } from "./pgn/mutations.js";
-import { buildFenIndex, buildIdIndex, NodeIdError, PathError, positionKey, resolveNodeId, ROOT_ID } from "./pgn/paths.js";
+import { addLine, addMove, deleteSubtree, promoteVariation, setAnnotations, setComment, setNags, setTag, } from "./pgn/mutations.js";
+import { buildIdIndex, positionKey, resolveNodeId, ROOT_ID } from "./pgn/paths.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { TOOLS } from "./tools.js";
 import { PROMPTS } from "./prompts.js";
-import { commentAntiPatterns, longLineWarning, noDescribeWarning, noStatsCheckWarning, positionsDescribed, positionsStatsChecked, } from "./warnings.js";
-import { authContext, authedRequest, createGame, deleteGame, fetchGame, get, makeFileId, PGN_BASE, restoreGame, saveGame, unwrap, } from "./http.js";
+import { commentAntiPatterns, longLineWarning, noDescribeWarning, noStatsCheckWarning, positionalNagOnIntermediateWarning, positionsDescribed, positionsStatsChecked, } from "./warnings.js";
+import { authContext, authedRequest, deleteGame, fetchGame, get, makeFileId, restoreGame, } from "./http.js";
+import { analysisToStoredEval, capPvsInResponse, convertCloudSnapshotResponse, fetchCompactEval, } from "./analysis/response.js";
+import { autoEvaluate, autoEvaluateCancel, autoEvaluateStatus, } from "./analysis/auto.js";
+import { deepAnalyseCancel, deepAnalyseStart, deepAnalyseStatus, } from "./analysis/deep.js";
+import { getNodeByPath, resolveFromNodeOrFen, storeEvalOnNode, } from "./analysis/file_handle.js";
+import { findPositionInCourses, readCourseAtPosition, runSfEval } from "./courses.js";
+import { applyBatchMutations, applyMutation, argNodeId, } from "./prep/mutations.js";
+import { listNodes, listTranspositions, readPrepFile, } from "./prep/read.js";
+import { createPrepFile, findPositionInFiles, listCollections, listPrepFiles, searchPrepFiles, } from "./prep/library.js";
+import { convertAvailableMovesToSAN, normalizeSourceForBackend, stripPositionResponse, trimGamesMovetext, } from "./response_transforms.js";
 // Tools that require an MCP token — cloud engine + prep-file tools
 // operate on the caller's own account so we can't service them
 // anonymously. The streamable-http transport uses this list to decide
@@ -97,6 +103,7 @@ const ENGINE_USAGE_DOC = loadBundledDoc("engine-usage.md", "Engine usage guide")
 const PREP_STRATEGY_DOC = loadBundledDoc("prep-strategy.md", "Prep strategy guide");
 const PREP_FILES_DOC = loadBundledDoc("prep-files-guide.md", "Prep files guide");
 const PGN_AUTHORING_DOC = loadBundledDoc("pgn-authoring.md", "PGN authoring guide");
+const SUMMARY_AUTHORING_DOC = loadBundledDoc("summary-authoring.md", "Summary authoring guide");
 // Reference PGNs authored by a strong human coach. LLM pulls these when
 // it wants to see the commentary style, NAG discipline, and annotation
 // density we want it to hit. Kept as raw PGN so the LLM can parse them
@@ -104,1506 +111,51 @@ const PGN_AUTHORING_DOC = loadBundledDoc("pgn-authoring.md", "PGN authoring guid
 // all intact) — not summarised into English.
 const EXAMPLE_OVERVIEW_PGN = loadBundledDoc("examples/italian-fried-liver.pgn", "Italian Fried Liver overview example");
 const EXAMPLE_REPERTOIRE_PGN = loadBundledDoc("examples/najdorf-6-f4-white.pgn", "Najdorf 6.f4 White repertoire example");
-// Log every tool call in and out. Keeps args + response payloads together
-// with a per-call duration so we can trace what the LLM asked for and what
-// it got back on the same journalctl line. Response is JSON-stringified and
-// capped so the two doc-reading tools (~5-10 KB of static markdown each)
-// don't drown the log stream.
-const LOG_MAX_CHARS = 4096;
-// Convert a UCI move sequence into SAN by walking it move-by-move on
-// chess.js from the given starting FEN. LLMs reason far better in SAN
-// ("Nf3", "Bxc4") than UCI ("g1f3", "b5c4"), and matches how prep
-// discussion is written in the real world. If a move fails to parse
-// (illegal from the current position — bug or truncated PV), we
-// truncate cleanly rather than throwing so the response still carries
-// what we could convert.
-function uciLineToSAN(startFen, uciMoves) {
-    const board = new Chess(startFen);
-    const out = [];
-    for (const uci of uciMoves) {
-        if (uci.length < 4)
-            break;
-        try {
-            const move = board.move({
-                from: uci.slice(0, 2),
-                to: uci.slice(2, 4),
-                promotion: uci.length >= 5 ? uci[4] : undefined,
-            });
-            if (!move)
-                break;
-            out.push(move.san);
-        }
-        catch {
-            break;
-        }
-    }
-    return out;
-}
-function uciMoveToSAN(startFen, uci) {
-    if (!uci || uci.length < 4)
-        return uci;
-    const board = new Chess(startFen);
-    try {
-        const move = board.move({
-            from: uci.slice(0, 2),
-            to: uci.slice(2, 4),
-            promotion: uci.length >= 5 ? uci[4] : undefined,
-        });
-        return move ? move.san : uci;
-    }
-    catch {
-        return uci;
-    }
-}
-async function fetchCompactEval(fen) {
-    try {
-        const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen, movetime_ms: 1500, multipv: 1 });
-        const converted = convertCloudSnapshotResponse(raw, fen);
-        const stored = analysisToStoredEval(converted);
-        return storedEvalToCompact(stored, converted);
-    }
-    catch {
-        return null;
-    }
-}
-// 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;
-    const r = raw;
-    for (const eng of [r.stockfish, r.lc0]) {
-        if (!eng)
-            continue;
-        if (Array.isArray(eng.lines)) {
-            for (const line of eng.lines) {
-                if (Array.isArray(line.pv))
-                    line.pv = uciLineToSAN(startFen, line.pv);
-            }
-        }
-        if (typeof eng.bestMove === "string")
-            eng.bestMove = uciMoveToSAN(startFen, eng.bestMove);
-    }
-    return raw;
-}
-// Extract a node id from the args. Accepts either `node_id` or a
-// `parent_id` alias for the add-style tools. Throws with a helpful
-// message if malformed.
-function argNodeId(args, key = "node_id") {
-    const raw = args[key];
-    if (typeof raw !== "string" || raw.length === 0) {
-        throw new Error(`\`${key}\` is required (call read_prep_file to get valid node ids)`);
-    }
-    return raw.trim();
-}
-// Dispatch table for the batch tool: name → mutator that returns
-// { file, id } where id is the node the mutation touched. The batch
-// caller rebuilds the id → path index between ops so newly-created
-// nodes are addressable within the same batch.
-function dispatchMutation(file, idIndex, op) {
-    const kind = String(op.op);
-    // Small local helper — resolves a node_id (or parent_id) op field to
-    // a path against the CURRENT tree state.
-    const nodeIdField = (key) => {
-        const raw = op[key];
-        if (typeof raw !== "string" || raw.length === 0) {
-            throw new Error(`\`${key}\` required on op ${kind}`);
-        }
-        return raw.trim();
-    };
-    const resolve = (id) => resolveNodeId(idIndex, id);
-    switch (kind) {
-        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");
-            // 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_nags":
-            return setNags(file, resolve(nodeIdField("node_id")), Array.isArray(op.nags) ? op.nags.map(String) : []);
-        case "set_annotations": {
-            const arrows = Array.isArray(op.arrows) ? op.arrows : [];
-            const highlights = Array.isArray(op.highlights) ? op.highlights : [];
-            const ann = arrows.length === 0 && highlights.length === 0 ? null : { arrows, highlights };
-            return setAnnotations(file, resolve(nodeIdField("node_id")), ann);
-        }
-        case "set_ceo_eval": {
-            const ev = op.ceoEval;
-            return setCeoEval(file, resolve(nodeIdField("node_id")), ev ?? null);
-        }
-        case "delete_subtree":
-            return deleteSubtree(file, resolve(nodeIdField("node_id")));
-        case "promote_variation":
-            return promoteVariation(file, resolve(nodeIdField("node_id")));
-        case "set_tag":
-            return { file: setTag(file, String(op.key), String(op.value ?? "")), id: ROOT_ID };
-        default:
-            throw new Error(`unknown mutation op: ${kind}`);
-    }
-}
-// Batch: load, parse, apply N mutations in order, export, save.
-// All-or-nothing — any error aborts and nothing is saved. The id index
-// is rebuilt after each op so nodes created earlier in the batch can be
-// addressed by later ops via their newly-derived node_id.
-async function applyBatchMutations(args) {
-    const id = String(args.id);
-    const mutations = Array.isArray(args.mutations) ? args.mutations : [];
-    if (mutations.length === 0)
-        throw new Error("mutations array required");
-    const g = await fetchGame(id);
-    let file = parsePGN(g.pgnContent);
-    let idIndex = buildIdIndex(file.root);
-    const results = [];
-    for (let i = 0; i < mutations.length; i++) {
-        const op = mutations[i];
-        try {
-            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 } : {}),
-                ...(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);
-            throw new Error(`mutation #${i} (${String(op.op)}) failed: ${msg}`);
-        }
-    }
-    const newPgn = exportPGN(file);
-    const expected = typeof args.expected_version === "number" ? args.expected_version : g.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
-// for a while but the map doesn't grow unbounded across long uptimes.
-const EVAL_JOB_TTL_MS = 15 * 60 * 1000;
-// Checkpoint interval — save progress every N successfully-evaluated
-// nodes so a mid-run kill leaves the tree partially populated. Small
-// enough that <15s of work is at risk per checkpoint on a slow combo,
-// large enough that the save overhead stays a small fraction of the
-// per-node cost.
-const SAVE_EVERY_N = 8;
-function newEvalJobId() {
-    // 12 hex chars, low collision (same 32-bit width as node ids ×1.5).
-    const rand = Math.random().toString(16).slice(2, 8);
-    return `evj_${Date.now().toString(16)}${rand}`;
-}
-// Sweep expired jobs on every start/status call — cheap, doesn't need
-// a background timer, keeps the map bounded to active + recent jobs.
-function reapExpiredEvalJobs() {
-    const now = Date.now();
-    for (const [k, j] of evalJobs) {
-        if (j.finishedAt && now - j.finishedAt > EVAL_JOB_TTL_MS) {
-            evalJobs.delete(k);
-        }
-    }
-}
-async function autoEvaluate(args) {
-    reapExpiredEvalJobs();
-    const id = String(args.id);
-    const startNodeId = typeof args.node_id === "string" && args.node_id.length > 0
-        ? String(args.node_id)
-        : ROOT_ID;
-    const onlyMissing = args.only_missing !== false; // default true
-    const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : 1500;
-    const g = await fetchGame(id);
-    const file = parsePGN(g.pgnContent);
-    const idIndex = buildIdIndex(file.root);
-    const startPath = resolveNodeId(idIndex, startNodeId);
-    const targets = [];
-    const walk = (node, isStartAndRoot) => {
-        if (!isStartAndRoot) {
-            if (!onlyMissing || !node.ceoEval) {
-                targets.push({ nodeId: node.id, fen: node.fen });
-            }
-        }
-        for (const child of node.children)
-            walk(child, false);
-    };
-    const startNode = getNodeByPath(file.root, startPath);
-    // If the caller anchored at the root, skip evaluating the root itself
-    // (no move); otherwise the anchor node IS a real move and gets evaluated.
-    walk(startNode, startNode.id === ROOT_ID);
-    // Dedup transpositions: if two candidate targets share the same
-    // 3-field FEN key, they're the same position reached by different
-    // move orders. Analyse ONE of them — cloud_analyse auto-propagates
-    // the resulting ceoEval to every other node with a matching key
-    // (see storeEvalOnNode), so the twin ends up with the same eval
-    // without a second engine call. Keep DFS-first (mainline-preferred)
-    // occurrence.
-    let skippedTranspositions = 0;
-    {
-        const seen = new Set();
-        const deduped = [];
-        for (const t of targets) {
-            const key = positionKey(t.fen);
-            if (seen.has(key)) {
-                skippedTranspositions++;
-                continue;
-            }
-            seen.add(key);
-            deduped.push(t);
-        }
-        targets.length = 0;
-        targets.push(...deduped);
-    }
-    // Nothing to do → return a done job synthetically so the caller doesn't
-    // need to special-case the empty response.
-    if (targets.length === 0) {
-        const jobId = newEvalJobId();
-        evalJobs.set(jobId, {
-            id: jobId,
-            fileId: id,
-            status: "done",
-            targetCount: 0,
-            evaluated: 0,
-            errored: 0,
-            failedNodeIds: [],
-            finalVersion: g.version,
-            startedAt: Date.now(),
-            finishedAt: Date.now(),
-            cancelled: false,
-        });
-        return { job_id: jobId, target_count: 0, status: "done", version: g.version };
-    }
-    const jobId = newEvalJobId();
-    const job = {
-        id: jobId,
-        fileId: id,
-        status: "running",
-        targetCount: targets.length,
-        evaluated: 0,
-        errored: 0,
-        failedNodeIds: [],
-        startedAt: Date.now(),
-        cancelled: false,
-    };
-    evalJobs.set(jobId, job);
-    // Unawaited — runs concurrently with the tool response. Any thrown
-    // error gets recorded on the job so the LLM's status poll surfaces
-    // it instead of the process seeing an unhandled rejection.
-    void runEvalJob(job, id, targets, movetimeMs).catch(err => {
-        job.status = "error";
-        job.error = err instanceof Error ? err.message : String(err);
-        job.finishedAt = Date.now();
-    });
-    return {
-        job_id: jobId,
-        target_count: targets.length,
-        // Transpositions inside the walk that we skipped because they'll
-        // pick up the eval via auto-propagation. Zero when there are none.
-        skipped_transpositions: skippedTranspositions,
-        status: "running",
-        // Rough time estimate at the current default movetime. Serialization
-        // on the per-combo semaphore means walltime ≈ target_count × movetime.
-        estimated_seconds: Math.round((targets.length * movetimeMs) / 1000),
-    };
-}
-// Worker body — walks targets sequentially (concurrency > 1 is a lie
-// against the per-combo semaphore in the backend anyway), checkpoints
-// every SAVE_EVERY_N successfully-evaluated nodes so partial progress
-// is durable, and re-anchors the version after each save.
-async function runEvalJob(job, fileId, targets, movetimeMs) {
-    const pending = [];
-    const flush = async () => {
-        if (pending.length === 0)
-            return;
-        // No expected_version — auto_evaluate treats concurrent edits by
-        // the LLM as last-write-wins on the ceoEval field specifically.
-        // Safe because set_ceo_eval is idempotent per node and other
-        // mutations (add_move / set_comment / etc.) don't touch ceoEval.
-        const saved = await applyBatchMutations({
-            id: fileId,
-            mutations: pending,
-        });
-        const sr = saved;
-        if (typeof sr.version === "number")
-            job.finalVersion = sr.version;
-        pending.length = 0;
-    };
-    // Consecutive-failure abort. If N cloud_analyse calls in a row error,
-    // the engine is almost certainly dead (vanished contract, network to
-    // VastAI down) and burning through the rest of the tree just wastes
-    // time. Bail with an explicit reason so a targeted retry is possible.
-    const MAX_CONSECUTIVE_FAILURES = 3;
-    let consecutiveFailures = 0;
-    let aborted = false;
-    for (const t of targets) {
-        if (job.cancelled || aborted)
-            break;
-        try {
-            const analysis = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen: t.fen, movetime_ms: movetimeMs, multipv: 1 });
-            const ev = analysisToStoredEval(analysis);
-            if (ev) {
-                pending.push({ op: "set_ceo_eval", node_id: t.nodeId, ceoEval: ev });
-                job.evaluated++;
-                consecutiveFailures = 0;
-            }
-            else {
-                job.errored++;
-                job.failedNodeIds.push(t.nodeId);
-                consecutiveFailures++;
-            }
-        }
-        catch {
-            // Per-node failure — record the node_id so the caller can retry
-            // just those, and count consecutive failures for the abort check.
-            job.errored++;
-            job.failedNodeIds.push(t.nodeId);
-            consecutiveFailures++;
-        }
-        if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
-            aborted = true;
-            job.abortedReason = `aborted after ${MAX_CONSECUTIVE_FAILURES} consecutive cloud_analyse failures — check that the cloud combo is still running (list_cloud_engines)`;
-            break;
-        }
-        if (pending.length >= SAVE_EVERY_N) {
-            try {
-                await flush();
-            }
-            catch {
-                // Save failure is bad but not fatal — try again on the next
-                // checkpoint or at the end. Progress remains in `pending`
-                // so nothing is lost as long as the process stays alive.
-            }
-        }
-    }
-    // Final flush regardless of cancellation — durably persist whatever
-    // work was completed before the user asked to stop.
-    try {
-        await flush();
-    }
-    catch (err) {
-        job.error = err instanceof Error ? err.message : String(err);
-        job.status = "error";
-        job.finishedAt = Date.now();
-        return;
-    }
-    job.status = job.cancelled ? "cancelled" : "done";
-    job.finishedAt = Date.now();
-}
-function autoEvaluateStatus(args) {
-    reapExpiredEvalJobs();
-    const jobId = String(args.job_id || "").trim();
-    if (!jobId)
-        throw new Error("`job_id` is required");
-    const job = evalJobs.get(jobId);
-    if (!job) {
-        return {
-            status: "not_found",
-            note: "Job unknown — either expired (kept ~15 min after completion), never existed, or the MCP process restarted since it was created. Re-run auto_evaluate to start over; the `only_missing` default will skip nodes already evaluated in the prep file.",
-        };
-    }
-    return {
-        job_id: job.id,
-        status: job.status,
-        target_count: job.targetCount,
-        evaluated: job.evaluated,
-        errored: job.errored,
-        failed_node_ids: job.failedNodeIds, // exact ids for targeted retry — pass as node_id list or check with list_nodes
-        aborted_reason: job.abortedReason, // present when the job stopped early due to consecutive engine failures
-        remaining: Math.max(0, job.targetCount - job.evaluated - job.errored),
-        done: job.status !== "running",
-        error: job.error,
-        version: job.finalVersion,
-        started_at_ms: job.startedAt,
-        finished_at_ms: job.finishedAt,
-    };
-}
-function autoEvaluateCancel(args) {
-    const jobId = String(args.job_id || "").trim();
-    if (!jobId)
-        throw new Error("`job_id` is required");
-    const job = evalJobs.get(jobId);
-    if (!job)
-        return { status: "not_found" };
-    if (job.status !== "running") {
-        return { status: job.status, note: "Job already finished; nothing to cancel." };
-    }
-    job.cancelled = true;
-    // status transitions to "cancelled" on the next per-node iteration
-    // inside runEvalJob, after the final flush persists progress.
-    return { status: "cancelling", evaluated_so_far: job.evaluated };
-}
-const deepJobs = new Map();
-const DEEP_JOB_TTL_MS = 15 * 60 * 1000;
-function newDeepJobId() {
-    const rand = Math.random().toString(16).slice(2, 8);
-    return `deep_${Date.now().toString(16)}${rand}`;
-}
-function reapExpiredDeepJobs() {
-    const now = Date.now();
-    for (const [k, j] of deepJobs) {
-        if (j.finishedAt && now - j.finishedAt > DEEP_JOB_TTL_MS) {
-            deepJobs.delete(k);
-        }
-    }
-}
-async function deepAnalyseStart(args) {
-    reapExpiredDeepJobs();
-    const resolved = await resolveFromNodeOrFen(args);
-    const fen = resolved.fen;
-    const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : 60_000;
-    // Default 2 — SF loses meaningful strength at higher multipv, so a
-    // deep think is best spent on a tight candidate list. Matches the
-    // cloud_analyse stockfish_multipv default.
-    const multipv = typeof args.multipv === "number" ? args.multipv : 2;
-    const jobId = newDeepJobId();
-    const job = {
-        id: jobId,
-        status: "running",
-        fileHandle: resolved.file,
-        fen,
-        movetimeMs,
-        multipv,
-        startedAt: Date.now(),
-        cancelController: new AbortController(),
-    };
-    deepJobs.set(jobId, job);
-    // Kick off the long HTTP call unawaited — resolves when the backend
-    // returns the SF snapshot. authedRequest is a plain fetch under the
-    // hood; abort signal flows via cancelController.
-    void runDeepJob(job).catch(err => {
-        job.status = "error";
-        job.error = err instanceof Error ? err.message : String(err);
-        job.finishedAt = Date.now();
-    });
-    return {
-        job_id: jobId,
-        status: "running",
-        movetime_ms: movetimeMs,
-        fen,
-    };
-}
-async function runDeepJob(job) {
-    const body = {
-        fen: job.fen,
-        movetime_ms: job.movetimeMs,
-        stockfish_multipv: job.multipv,
-        engines: ["stockfish"],
-    };
-    let raw;
-    try {
-        // TODO(future): plumb an AbortSignal through authedRequest for
-        // real mid-flight cancellation. For now, cancel just marks the
-        // job so the caller stops polling; the backend still runs the
-        // engine to completion and the result is stored on the job
-        // record but flagged cancelled.
-        raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
-    }
-    catch (err) {
-        job.status = "error";
-        job.error = err instanceof Error ? err.message : String(err);
-        job.finishedAt = Date.now();
-        return;
-    }
-    const converted = convertCloudSnapshotResponse(raw, job.fen);
-    const sf = converted.stockfish;
-    if (job.cancelController.signal.aborted) {
-        job.status = "cancelled";
-    }
-    else {
-        job.status = "done";
-    }
-    job.result = sf ?? null;
-    job.finishedAt = Date.now();
-    // Same node-persistence as cloud_analyse: if the caller anchored on
-    // file_id+node_id, store the SF-only eval as the node's ceoEval so
-    // quote_engine_eval can cite it later. We build a StoredEval that has
-    // only the sf leg — no Lc0 was run.
-    if (job.fileHandle && sf) {
-        const ev = analysisToStoredEval({ stockfish: sf });
-        if (ev) {
-            try {
-                await storeEvalOnNode(job.fileHandle, ev);
-            }
-            catch {
-                // best-effort — the analysis result is what the LLM asked for
-            }
-        }
-    }
-}
-function deepAnalyseStatus(args) {
-    reapExpiredDeepJobs();
-    const jobId = String(args.job_id || "").trim();
-    if (!jobId)
-        throw new Error("`job_id` is required");
-    const job = deepJobs.get(jobId);
-    if (!job) {
-        return {
-            status: "not_found",
-            note: "Job unknown — expired (kept ~15 min after completion), never existed, or the MCP process restarted.",
-        };
-    }
-    return {
-        job_id: job.id,
-        status: job.status,
-        movetime_ms: job.movetimeMs,
-        elapsed_ms: (job.finishedAt ?? Date.now()) - job.startedAt,
-        fen: job.fen,
-        result: job.result,
-        error: job.error,
-        started_at_ms: job.startedAt,
-        finished_at_ms: job.finishedAt,
-    };
-}
-function deepAnalyseCancel(args) {
-    const jobId = String(args.job_id || "").trim();
-    if (!jobId)
-        throw new Error("`job_id` is required");
-    const job = deepJobs.get(jobId);
-    if (!job)
-        return { status: "not_found" };
-    if (job.status !== "running") {
-        return { status: job.status, note: "Job already finished; nothing to cancel." };
-    }
-    job.cancelController.abort();
-    // Status flips to "cancelled" when runDeepJob observes the abort on
-    // completion. Backend keeps churning until movetime elapses (mid-
-    // flight abort of the HTTP call is a follow-up).
-    return { status: "cancelling", elapsed_ms: Date.now() - job.startedAt };
-}
-// ── find_position_in_courses: fenfind subprocess wrapper ───────────
-//
-// fenfind is a small python tool that indexes chess PGN files by
-// polyglot Zobrist hash. Given a position it returns which of the
-// user's Chessable / PGN files cover it, ranked by how much annotated
-// material sits below that position in each course. Runs as a
-// subprocess of the MCP so we can reuse python-chess's polyglot
-// hashing (matching the pre-built positions.db) instead of porting
-// the hash function to TS.
-//
-// Path resolution order (`FENFIND_PATH` env var overrides):
-//   1. $FENFIND_PATH/fenfind
-//   2. <package-root>/tools/fenfind/fenfind (ships with the npm package)
-// The bash wrapper picks a python interpreter with python-chess
-// available (venv at $here/.venv/bin/python preferred, then falls back
-// to system python3). DB path is resolved inside fenfind.py itself
-// (FENFIND_DB env, then ~/positions.db).
-// Path resolution shared by both fenfind + readpgn. FENFIND_PATH env
-// overrides the bundled tools/fenfind/ directory.
-// Path to sf_eval helper (spawns local stockfish, parses its `eval`
-// verbose output). Uses the same resolution pattern as FENFIND_DIR.
-const SF_EVAL_SCRIPT = (() => {
-    const envPath = process.env.SF_EVAL_PATH?.trim();
-    if (envPath && existsSync(join(envPath, "sf_eval")))
-        return join(envPath, "sf_eval");
-    const here = dirname(fileURLToPath(import.meta.url));
-    const bundled = join(here, "..", "tools", "sf_eval", "sf_eval");
-    return existsSync(bundled) ? bundled : null;
-})();
-const SF_EVAL_TIMEOUT_MS = 12_000;
-async function runSfEval(fen) {
-    if (!SF_EVAL_SCRIPT) {
-        return {
-            found: false,
-            error: "sf_eval script not bundled; set SF_EVAL_PATH or install tools/sf_eval/",
-        };
-    }
-    const stdout = await new Promise((resolve, reject) => {
-        const p = spawn(SF_EVAL_SCRIPT, ["--fen", fen], { stdio: ["ignore", "pipe", "pipe"] });
-        let out = "";
-        let err = "";
-        p.stdout.on("data", d => { out += d.toString("utf8"); });
-        p.stderr.on("data", d => { err += d.toString("utf8"); });
-        const to = setTimeout(() => {
-            try {
-                p.kill("SIGTERM");
-            }
-            catch { /* already dead */ }
-            reject(new Error(`sf_eval timed out after ${SF_EVAL_TIMEOUT_MS}ms`));
-        }, SF_EVAL_TIMEOUT_MS);
-        p.on("error", e => { clearTimeout(to); reject(e); });
-        p.on("close", code => {
-            clearTimeout(to);
-            if (code !== 0)
-                reject(new Error(`sf_eval exited ${code}: ${err.slice(0, 500)}`));
-            else
-                resolve(out);
-        });
-    });
-    try {
-        return JSON.parse(stdout);
-    }
-    catch (e) {
-        throw new Error(`sf_eval returned non-JSON output (${e instanceof Error ? e.message : String(e)}): ${stdout.slice(0, 300)}`);
-    }
-}
-const FENFIND_DIR = (() => {
-    const envPath = process.env.FENFIND_PATH?.trim();
-    if (envPath && existsSync(join(envPath, "fenfind")))
-        return envPath;
-    const here = dirname(fileURLToPath(import.meta.url));
-    const bundled = join(here, "..", "tools", "fenfind");
-    return existsSync(join(bundled, "fenfind")) ? bundled : null;
-})();
-// Cap on how long we let the subprocess run. SQLite hash lookup returns
-// sub-second; PGN read from a course file is O(chapter size) and rarely
-// exceeds a second. 15s is a stuck-process backstop, not a real limit.
-const FENFIND_TIMEOUT_MS = 15_000;
-async function runFenfindScript(scriptName, args) {
-    if (!FENFIND_DIR) {
-        throw new Error("fenfind index not installed — set FENFIND_PATH or install the tools/fenfind bundle");
-    }
-    const script = join(FENFIND_DIR, scriptName);
-    return new Promise((resolve, reject) => {
-        const p = spawn(script, args, { stdio: ["ignore", "pipe", "pipe"] });
-        let out = "";
-        let err = "";
-        p.stdout.on("data", d => { out += d.toString("utf8"); });
-        p.stderr.on("data", d => { err += d.toString("utf8"); });
-        const to = setTimeout(() => {
-            try {
-                p.kill("SIGTERM");
-            }
-            catch { /* already dead */ }
-            reject(new Error(`${scriptName} timed out after ${FENFIND_TIMEOUT_MS}ms`));
-        }, FENFIND_TIMEOUT_MS);
-        p.on("error", e => { clearTimeout(to); reject(e); });
-        p.on("close", code => {
-            clearTimeout(to);
-            if (code !== 0)
-                reject(new Error(`${scriptName} exited ${code}: ${err.slice(0, 500)}`));
-            else
-                resolve(out);
-        });
-    });
-}
-function parseFenfindJson(scriptName, stdout) {
-    try {
-        return JSON.parse(stdout);
-    }
-    catch (e) {
-        throw new Error(`${scriptName} returned non-JSON output (${e instanceof Error ? e.message : String(e)}): ${stdout.slice(0, 300)}`);
-    }
-}
-async function findPositionInCourses(args) {
-    if (!FENFIND_DIR) {
-        return {
-            status: "not_available",
-            note: "fenfind index not installed on this server. Set FENFIND_PATH env var to the directory containing the `fenfind` script and positions.db, or install the tools/fenfind bundle shipped in the npm package.",
-        };
-    }
-    const resolved = await resolveFromNodeOrFen(args);
-    const cliArgs = [resolved.fen, "--json"];
-    if (typeof args.sort === "string" && (args.sort === "recency" || args.sort === "notes")) {
-        cliArgs.push("--sort", args.sort);
-    }
-    if (args.include_games)
-        cliArgs.push("--games");
-    if (args.chapters_mode)
-        cliArgs.push("--chapters");
-    if (typeof args.min_notes_chars === "number")
-        cliArgs.push("--min", String(args.min_notes_chars));
-    if (typeof args.limit === "number")
-        cliArgs.push("-n", String(args.limit));
-    const stdout = await runFenfindScript("fenfind", cliArgs);
-    return parseFenfindJson("fenfind", stdout);
-}
-async function readCourseAtPosition(args) {
-    if (!FENFIND_DIR) {
-        return {
-            status: "not_available",
-            note: "fenfind index not installed on this server. Set FENFIND_PATH env var to the directory containing the `fenfind`/`readpgn` scripts and positions.db.",
-        };
-    }
-    const fileId = typeof args.course_file_id === "number" ? args.course_file_id : Number(args.course_file_id);
-    if (!Number.isFinite(fileId) || fileId <= 0) {
-        throw new Error("`course_file_id` is required — pass the value from a find_position_in_courses hit");
-    }
-    const cliArgs = ["--file-id", String(fileId)];
-    if (typeof args.fen === "string" && args.fen.trim() !== "")
-        cliArgs.push("--fen", args.fen.trim());
-    if (typeof args.moves === "string" && args.moves.trim() !== "")
-        cliArgs.push("--moves", args.moves.trim());
-    if (typeof args.chapter === "string" && args.chapter.trim() !== "")
-        cliArgs.push("--chapter", args.chapter.trim());
-    if (typeof args.max_plies_below === "number")
-        cliArgs.push("--max-plies-below", String(args.max_plies_below));
-    const stdout = await runFenfindScript("readpgn", cliArgs);
-    return parseFenfindJson("readpgn", stdout);
-}
-// Walk chess.js-free: resolve a path against a tree, throw if invalid.
-function pathIntoTree(root, path) {
-    let cur = root;
-    for (let i = 0; i < path.length; i++) {
-        if (path[i] < 0 || path[i] >= cur.children.length) {
-            throw new Error(`path segment ${i}=${path[i]} out of bounds`);
-        }
-        cur = cur.children[path[i]];
-    }
-    return cur;
-}
-// Read the cloud analyse response and build a StoredEval (compact form —
-// no PVs, White-POV cp / mate, depth, and derived NAG). Returns null if
-// there's no usable Stockfish signal (SF is the source of truth for
-// the NAG per docs).
-function analysisToStoredEval(analysis) {
-    if (!analysis || typeof analysis !== "object")
-        return null;
-    const r = analysis;
-    // Backend returns White-POV cp/mate (engine-ws flips in ParseInfo
-    // based on side-to-move, cloud_snapshot passes through). Pure
-    // pass-through here — a previous sign-flip on black-to-move was
-    // wrong and silently inverted every Black-to-move stored eval.
-    const engineEval = (block) => {
-        const line = block?.lines?.[0];
-        if (!line)
-            return undefined;
-        const depth = line.depth ?? block?.depth;
-        if (typeof line.mate === "number")
-            return { mate: line.mate, depth };
-        if (typeof line.scoreCp === "number")
-            return { cp: line.scoreCp, depth };
-        return undefined;
-    };
-    const sf = engineEval(r.stockfish);
-    const lc0 = engineEval(r.lc0);
-    if (!sf && !lc0)
-        return null;
-    const ev = {};
-    if (sf)
-        ev.sf = sf;
-    if (lc0)
-        ev.lc0 = lc0;
-    ev.nag = nagFromCp(sf?.cp, sf?.mate) ?? nagFromCp(lc0?.cp, lc0?.mate) ?? undefined;
-    return ev;
-}
-function nagFromCp(cp, mate) {
-    let effective;
-    if (typeof mate === "number")
-        effective = mate > 0 ? 10000 : -10000;
-    else if (typeof cp === "number")
-        effective = cp;
-    else
-        return null;
-    const abs = Math.abs(effective);
-    if (abs < 25)
-        return "$10";
-    if (abs < 60)
-        return effective > 0 ? "$14" : "$15";
-    if (abs < 130)
-        return effective > 0 ? "$16" : "$17";
-    return effective > 0 ? "$18" : "$19";
-}
-// Adapter for the compact eval attached to live query responses. Same
-// derivation logic; different output shape (needs the .nag + summary
-// used by get_position_stats / prep_snapshot).
-function storedEvalToCompact(ev, analysis) {
-    if (!ev)
-        return null;
-    const a = analysis;
-    const compact = { nag: ev.nag ?? null };
-    if (ev.sf) {
-        compact.stockfish = {
-            cp: ev.sf.cp,
-            mate: ev.sf.mate,
-            bestMove: a.stockfish?.bestMove,
-            pv: a.stockfish?.lines?.[0]?.pv,
-        };
-    }
-    if (ev.lc0) {
-        compact.lc0 = {
-            cp: ev.lc0.cp,
-            mate: ev.lc0.mate,
-            bestMove: a.lc0?.bestMove,
-            pv: a.lc0?.lines?.[0]?.pv,
-        };
-    }
-    return compact;
-}
-// Load-mutate-save: fetch current PGN, parse, apply mutation, re-export,
-// save with optimistic lock. Auto-saves so every tool call is atomic;
-// the LLM never sees intermediate state. The mutator is called with
-// both the parsed file and its id → path index, so the mutation can
-// resolve node_ids without rebuilding the index itself.
-async function applyMutation(args, mutator) {
-    const id = String(args.id);
-    const g = await fetchGame(id);
-    const file = parsePGN(g.pgnContent);
-    const idIndex = buildIdIndex(file.root);
-    let result;
-    try {
-        result = mutator(file, idIndex);
-    }
-    catch (err) {
-        if (err instanceof MutationError || err instanceof PathError || err instanceof NodeIdError) {
-            throw new Error(`mutation rejected: ${err.message}`);
-        }
-        throw err;
-    }
-    const newPgn = exportPGN(result.file);
-    const expected = typeof args.expected_version === "number" ? args.expected_version : g.version;
-    const saved = await saveGame(id, newPgn, expected);
-    return {
-        ok: true,
-        node_id: result.id,
-        ...(result.results !== undefined ? { line: result.results } : {}),
-        ...(result.warning ? { warning: result.warning } : {}),
-        ...(result.warnings && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
-        version: saved.version,
-    };
-}
-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.
-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;
-}
-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))
-        ? 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 });
-}
-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.
-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 };
-}
-// 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.
-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.
-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);
-        }
-    }
-}
-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.
-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;
-}
-// Resolve a starting FEN from any combination of `fen`, `line`, and
-// `moves` the tool received. Three modes, all valid:
-//
-//   fen alone                → use as-is
-//   line/moves alone         → walk from startpos
-//   fen + moves (or line)    → walk from that fen
-//
-// `line` is the historical field name from the backend's prep endpoint;
-// `moves` is the flexible-input name we now surface for LLM ergonomics
-// ("start from this FEN and play these moves next"). They're synonyms
-// here — same SAN sequence, same chess.js walker. `moves` wins if both
-// happen to be provided.
-function resolveFenFromArgs(args) {
-    const fenArg = typeof args.fen === "string" ? args.fen.trim() : "";
-    const movesArg = typeof args.moves === "string" ? args.moves.trim() : "";
-    const lineArg = typeof args.line === "string" ? args.line.trim() : "";
-    const sequence = movesArg || lineArg;
-    const board = fenArg ? new Chess(fenArg) : new Chess();
-    if (sequence) {
-        for (const raw of sequence.split(/\s+/)) {
-            const san = raw.replace(/^\d+\.+/, "");
-            if (!san)
-                continue;
-            try {
-                board.move(san);
-            }
-            catch {
-                throw new Error(`bad SAN token '${raw}' in moves`);
-            }
-        }
-    }
-    return board.fen();
-}
-// 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.
-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;
+// v0.48: consolidated the five `read_*_guide` / `read_example_prep_files`
+// tools into ONE `read_docs`. LLM lists what it wants; we return them
+// in a single response. Also cleaner: enumerating available docs in one
+// tool description (with per-doc "CALL WHEN" hints) beats surfacing
+// five almost-identical tools in the tool listing.
+const DOC_LIBRARY = {
+    "engine-usage": ENGINE_USAGE_DOC,
+    "opening-prep": PREP_STRATEGY_DOC,
+    "prep-files": PREP_FILES_DOC,
+    "pgn-authoring": PGN_AUTHORING_DOC,
+    "summary-authoring": SUMMARY_AUTHORING_DOC,
+    "examples/italian-fried-liver-overview": EXAMPLE_OVERVIEW_PGN,
+    "examples/najdorf-6-f4-repertoire": EXAMPLE_REPERTOIRE_PGN,
+};
+function readDocs(args) {
+    const raw = args.docs;
+    const requested = Array.isArray(raw)
+        ? raw.map(String).map(s => s.trim()).filter(s => s.length > 0)
+        : [];
+    if (requested.length === 0) {
+        throw new Error(`docs required — pass e.g. { docs: ["engine-usage", "pgn-authoring"] }. Available: ${Object.keys(DOC_LIBRARY).join(", ")}`);
+    }
+    const out = {};
+    const unknown = [];
+    for (const name of requested) {
+        if (name in DOC_LIBRARY) {
+            out[name] = DOC_LIBRARY[name];
         }
         else {
-            // fide + chesscom take a titlecased timeFormats array.
-            const titled = tc.charAt(0).toUpperCase() + tc.slice(1);
-            out.timeFormats = [titled];
-        }
-    }
-    return out;
-}
-// Async resolver used by every engine / DB tool. Three paths:
-//
-//   1. file_id + node_id → load file, resolve node, return FEN + handle
-//      to persist ceoEval later. Cheapest, most explicit.
-//
-//   2. file_id + (fen | moves | line) → load file, resolve FEN
-//      client-side, then scan the file's nodes for one matching that
-//      FEN. If found, return the same handle as (1) so cloud_analyse
-//      auto-stores on the matching node. Fixes the previous footgun
-//      where `cloud_analyse({file_id, moves})` silently dropped the
-//      eval because the server didn't try to match the resulting FEN
-//      back to a node.
-//
-//   3. Just fen | moves | line, no file_id → scratch mode, no
-//      persistence. Same as before.
-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 g = await fetchGame(fileId);
-        const parsedFile = parsePGN(g.pgnContent);
-        const idIndex = buildIdIndex(parsedFile.root);
-        const nodePath = resolveNodeId(idIndex, nodeId);
-        const node = getNodeByPath(parsedFile.root, nodePath);
-        return {
-            fen: node.fen,
-            file: { id: fileId, version: g.version ?? 0, parsedFile, idIndex, nodePath, fen: node.fen },
-        };
-    }
-    if (fileId) {
-        // file_id only — resolve FEN from fen/moves/line, then look it up
-        // in the file's nodes. If a node has that FEN, treat this as if
-        // node_id had been supplied (auto-persist on match).
-        const fen = resolveFenFromArgs(args);
-        try {
-            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 {
-            // Best-effort: if the file load fails, fall through to scratch mode.
-        }
-        return { fen };
-    }
-    return { fen: resolveFenFromArgs(args) };
-}
-// Search the tree for a node whose FEN matches. Full-tree scan — trees
-// max out ~1000 nodes so this is fine. FEN comparison is exact string
-// match (both come from the same chessops normalisation).
-function findNodeByFen(root, targetFen) {
-    const stack = [{ node: root, path: [] }];
-    while (stack.length > 0) {
-        const { node, path } = stack.pop();
-        if (node.fen === targetFen)
-            return { node, path };
-        for (let i = 0; i < node.children.length; i++) {
-            stack.push({ node: node.children[i], path: [...path, i] });
+            unknown.push(name);
         }
     }
-    return null;
-}
-// Local wrapper — the mutation module re-exports paths.getNode so this
-// import stays consistent with the rest of the file's imports.
-function getNodeByPath(root, path) {
-    let cur = root;
-    for (const idx of path) {
-        if (idx < 0 || idx >= cur.children.length)
-            throw new Error(`invalid node path segment ${idx}`);
-        cur = cur.children[idx];
-    }
-    return cur;
-}
-// Persist a fresh ceoEval on the node referenced by the file handle
-// AND on every other node in the same file that transposes to the
-// same position (matches on the frontend's 3-field FEN key: piece
-// placement + side to move + castling). Best-effort — if the file
-// version raced (another agent saved between our GET and our PUT),
-// we silently drop the store rather than fail the analysis the LLM
-// actually asked for. The eval is still returned in the response
-// either way.
-//
-// Return: ids of every node the eval was stamped on (empty on error).
-// The primary node's id is always first (if present).
-async function storeEvalOnNode(handle, ev) {
-    try {
-        const anchor = getNodeByPath(handle.parsedFile.root, handle.nodePath);
-        const key = positionKey(anchor.fen);
-        const fenIndex = buildFenIndex(handle.parsedFile.root);
-        const group = fenIndex.get(key) ?? [anchor];
-        // Resolve every transposed node back to its path. cloneOnPath
-        // rebuilds the spine so we need paths, not references — the
-        // id index was built against the original tree and every id in
-        // `group` exists there.
-        const idIndex = handle.idIndex ?? buildIdIndex(handle.parsedFile.root);
-        const paths = group.map(n => resolveNodeId(idIndex, n.id));
-        const { file: newFile, ids } = setCeoEvalMany(handle.parsedFile, paths, ev);
-        const newPgn = exportPGN(newFile);
-        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)];
-    }
-    catch {
-        return [];
+    const resp = { docs: out };
+    if (unknown.length > 0) {
+        resp.unknown = unknown;
+        resp.note = `unknown doc name(s): ${unknown.join(", ")}. Available: ${Object.keys(DOC_LIBRARY).join(", ")}`;
     }
+    return resp;
 }
+// Log every tool call in and out. Keeps args + response payloads together
+// with a per-call duration so we can trace what the LLM asked for and what
+// it got back on the same journalctl line. Response is JSON-stringified and
+// capped so the two doc-reading tools (~5-10 KB of static markdown each)
+// don't drown the log stream.
+const LOG_MAX_CHARS = 4096;
 function stringifyForLog(v) {
     let s;
     try {
@@ -1949,7 +501,14 @@ async function callToolInner(name, args) {
             });
         }
         case "set_nags":
-            return applyMutation(args, (file, idIndex) => setNags(file, resolveNodeId(idIndex, argNodeId(args)), Array.isArray(args.nags) ? args.nags.map(String) : []));
+            return applyMutation(args, (file, idIndex) => {
+                const nagsArg = Array.isArray(args.nags) ? args.nags.map(String) : [];
+                const targetPath = resolveNodeId(idIndex, argNodeId(args));
+                const targetNode = getNodeByPath(file.root, targetPath);
+                const nagWarn = positionalNagOnIntermediateWarning(targetNode, nagsArg);
+                const step = setNags(file, targetPath, nagsArg);
+                return { ...step, ...(nagWarn ? { warning: nagWarn } : {}) };
+            });
         case "set_annotations": {
             const arrowsRaw = Array.isArray(args.arrows) ? args.arrows : [];
             const highlightsRaw = Array.isArray(args.highlights) ? args.highlights : [];
@@ -1970,7 +529,7 @@ async function callToolInner(name, args) {
         case "apply_mutations":
             return applyBatchMutations(args);
         case "auto_evaluate":
-            return autoEvaluate(args);
+            return autoEvaluate(args, applyBatchMutations);
         case "auto_evaluate_status":
             return autoEvaluateStatus(args);
         case "auto_evaluate_cancel":
@@ -1985,16 +544,8 @@ async function callToolInner(name, args) {
             const node = getNodeByPath(file.root, path);
             return { ceoEval: node.ceoEval ?? null };
         }
-        case "read_engine_usage_guide":
-            return { guide: ENGINE_USAGE_DOC };
-        case "read_opening_prep_guide":
-            return { guide: PREP_STRATEGY_DOC };
-        case "read_prep_files_guide":
-            return { guide: PREP_FILES_DOC };
-        case "read_pgn_authoring_guide":
-            return { guide: PGN_AUTHORING_DOC };
-        case "read_example_prep_files":
-            return { overview: EXAMPLE_OVERVIEW_PGN, repertoire: EXAMPLE_REPERTOIRE_PGN };
+        case "read_docs":
+            return readDocs(args);
         case "prep_snapshot": {
             const me = Number(args.fide_id_me);
             const opp = Number(args.fide_id_opponent);