chesspal 0.1.0 → 0.2.0

package/dist/commands/coach.js

@@ -0,0 +1,344 @@
+import { z } from "zod";
+import { badges, Game, leadText, levelOf, materialOf, withSanLetters } from "../core/index.js";
+import { archiveCoached, coachWaitingSince, coachWords, endOf, keepHint, keepJudgment, keepLead, loadGame, startCoach } from "../games/index.js";
+import { coachAgent } from "../host-files/index.js";
+import { activeProfile, gameFolder, helpsIn } from "../profiles/index.js";
+import { clockLine, clockSummaryOf } from "./clock.js";
+import { arrowsInput, drawingsOf, noteInput, squaresInput } from "./drawings.js";
+import { lastMoves } from "./game-summary.js";
+import { aheadWords, leadFrom, leadInput } from "./lead-input.js";
+import { knownMoves, openingLine } from "./opening-book.js";
+import { waitForPlayer, wordsOf } from "./ponder.js";
+import { profileLines } from "./position.js";
+import { defineCommand } from "./registry.js";
+import { speechLine, speechOf } from "./speech.js";
+import { colourName, compactView, materialText, riskLine } from "./view.js";
+// The badges the coach gives: the book's is Chesspal's, never a judgment (D-69).
+const judgments = badges.filter((badge) => badge !== "book");
+/**
+ * The coach (D-80, D-88), for the agent that judges the player's moves and gives them hints with the helps on: every fact, never the opponent's plan; its
+ * words go to the board page alone, never to the opponent. Its calls are not the chat's, and the server refuses them from the chat. Offered to Claude Code alone.
+ */
+export const coach = defineCommand({
+    name: "coach",
+    description: "For the chesspal-coach agent only, never from the chat: Chesspal's answers say when to start it. coach {} gives the player's move to judge and the position "
+        + "they are to move in; coach {game, position, ahead, badge, note, hint, arrows, squares} keeps who is ahead there, while the game goes on, and your judgment and your hint, "
+        + "each only when there is something to say; coach {game, position, done: true} waits for their move, once who is ahead is kept. Whenever it says stop, stop. "
+        + 'Example: coach {game: "t3k9qa", position: 24, ahead: -0.8, badge: "mistake", note: "It leaves the d5 pawn without a defender.", hint: "Look at what defends their king now."}.',
+    input: z.object({
+        game: z.string().optional().describe("the game's key, as coach {} gives it"),
+        position: z.int().min(0).optional().describe("the position's number, as coach {} gives it"),
+        ahead: leadInput.optional().describe("who is ahead in the position the player is to move in, for the page's bar: pawns from White's side, 1.5 for White, -3 for Black, 0 for even, or a mate "
+            + 'you see in moves of the side that mates, "#3" for White\'s, "#-3" for Black\'s'),
+        badge: z.enum(judgments).optional().describe("your badge on the player's move, as chess.com names them, only on a move that stands out, never on a routine one"),
+        note: noteInput.optional().describe("why, on the player's move, in a sentence or two, in their language"),
+        hint: noteInput.optional().describe("a hint for their turn, in a sentence or two, in their language, only when there is something to find: what is on the board (a piece, a square, a file, a "
+            + "threat of the opponent's, a goal), never what to play"),
+        arrows: arrowsInput.describe("only with a hint: arrows on the board as it is now, never a move the player can play: Rf2e1; R red: a threat of the opponent's; B blue: a plan or a target; "
+            + "Y yellow: a line; G green: a good idea"),
+        squares: squaresInput.describe("only with a hint: squares to mark on the board as it is now: Rf2; colours as for arrows"),
+        done: z.boolean().optional().describe("true once you have kept your words, who is ahead always while the game goes on: it waits for the player's move"),
+    }),
+    byAgents: [coachAgent],
+    host: "claude-code",
+    run: async ({ game, position, ahead, badge, note, hint, arrows, squares, done = false }, context) => {
+        const folder = gameFolder(context.home());
+        const current = loadGame(folder);
+        const words = { ahead, badge, note, hint, arrows, squares };
+        const writes = Object.values(words).some((word) => word !== undefined);
+        if (!helpsIn(folder)) {
+            return { stop: "helps" };
+        }
+        if (game === undefined || position === undefined) {
+            if (writes || done || game !== undefined || position !== undefined) {
+                throw new Error("Give the game's key and the position's number with it: call coach {} first, which gives them. Nothing changed.");
+            }
+            const start = current === undefined ? undefined : startOf(current, folder, context);
+            if (start === undefined || current === undefined) {
+                return { stop: "moved" };
+            }
+            // The chat may start a second coach on the same position, told again before the first called: one judges it (Priya).
+            return startCoach(folder, current) ? { start } : { stop: "started" };
+        }
+        // A new game may have started while the coach thought on the last one: its words never go to another game (Federico).
+        if (current === undefined || gameKey(current) !== game || position > current.game.record.moves.length) {
+            return { stop: "moved" };
+        }
+        const place = { game, position };
+        if (!done) {
+            return keep(folder, current, place, words);
+        }
+        if (writes) {
+            throw new Error(`Keep your words first, then call ${call(place, "done: true")} alone. Nothing changed.`);
+        }
+        // The bar on the page needs who is ahead in every position the player is to move in while the game goes on (D-90, Stefano).
+        if (leadMissing(folder, current, position)) {
+            throw new Error(`Who is ahead is still missing here: first ${aheadCall(place)}, then ${call(place, "done: true")}. Nothing changed.`);
+        }
+        const since = coachWaitingSince(folder, current, position, context.now());
+        const waited = await waitForPlayer(context, since, () => !theirTurn(loadGame(folder), place));
+        return waited === "waiting" ? { waiting: place } : { stop: waited };
+    },
+    format: (coached) => {
+        if ("stop" in coached) {
+            return coached.stop === "helps"
+                ? "Stop now: the player has turned the helps off. End with one word."
+                : coached.stop === "started"
+                    ? "Stop now: another coach works on this position. End with one word."
+                    : coached.stop === "moved"
+                        ? "Stop now: the player has moved, or the game is over. End with one word."
+                        : "Stop now: you have waited long enough. End with one word.";
+        }
+        if ("start" in coached) {
+            return coached.start.join("\n");
+        }
+        if ("kept" in coached) {
+            return keptText(coached);
+        }
+        return `Still the player's move: call ${call(coached.waiting, "done: true")} again.`;
+    },
+});
+/**
+ * What a call kept, and what comes next: who is ahead when it is still missing, then wait for the player's move; or stop, as they have moved or the game is
+ * over, with the hint that came too late.
+ */
+function keptText({ kept, then, saved, hintLeft }) {
+    const what = saved.length === 0 ? "nothing" : saved.join(", ");
+    if (then === "lead") {
+        return `Kept on the board page: ${what}. Who is ahead is still missing: now ${aheadCall(kept)}, then ${call(kept, "done: true")} alone.`;
+    }
+    if (then === "wait") {
+        return `Kept on the board page: ${what}. Now call ${call(kept, "done: true")} alone.`;
+    }
+    const late = hintLeft ? ", so your hint is not kept" : "";
+    return then === "moved"
+        ? `Kept: ${what}; the player has moved${late}. Stop now: end with one word.`
+        : `Kept for the game's record: ${what}; the game is over${late}. Stop now: end with one word.`;
+}
+/** A call of coach on a game's position, with what else it gives. */
+function call({ game, position }, rest) {
+    return `coach {game: "${game}", position: ${position}, ${rest}}`;
+}
+/** The call that gives who is ahead, with how to write it. */
+function aheadCall(place) {
+    return `call ${call(place, "ahead")}, in pawns from White's side (1.5, -3, 0) or a mate you see ("#3" White's, "#-3" Black's)`;
+}
+/** Whether who is ahead is still to give in a position the player is to move in, while the game goes on. */
+function leadMissing(folder, current, position) {
+    const { leads = [] } = coachWords(folder, current);
+    return endOf(current.game) === undefined && sideToMoveAt(current, position) !== current.ai && !leads.some((lead) => lead.position === position);
+}
+/** The game's short key, from its start: the coach names the game it works on, so that its words never go to the next one. */
+function gameKey(current) {
+    return Math.floor(Date.parse(current.started) / 1000).toString(36);
+}
+/** How many plies of the game the coach shows: enough to follow it, few enough for its budget. */
+const pliesShown = 40;
+/**
+ * What the coach works on, from the position the player is to move in, or the game over: the game, the player's move the opponent answered, or their own
+ * that ended the game, with the position they played it in and the book there, and the position now with the hint it gave last; none while the opponent is
+ * to move.
+ */
+function startOf(current, folder, context) {
+    const { game, ai } = current;
+    const { record } = game;
+    const plies = record.moves.length;
+    const over = endOf(game);
+    const player = ai === "white" ? "black" : "white";
+    const judged = judgedPly(current, plies);
+    if ((game.position.turn === ai && over === undefined) || (over !== undefined && judged === undefined)) {
+        return undefined;
+    }
+    const place = { game: gameKey(current), position: plies };
+    const ender = game.position.turn === ai ? "the player's" : "the opponent's";
+    const head = over === undefined
+        ? `Game "${place.game}", position ${plies}: the player (${colourName(player)}) to move, move ${game.position.moveNumber}; the opponent plays ${colourName(ai)} at the `
+            + `${levelOf(record)} level.`
+        : `Game "${place.game}", position ${plies}: the game is over, ${over.result}${over.termination === undefined ? "" : `, ${over.termination}`}, with ${ender} move.`;
+    const speech = speechOf(folder, context.language);
+    const clock = clockSummaryOf(current, context.now());
+    const keepLine = over === undefined
+        ? `Keep your words: ${call(place, "ahead, badge, note, hint, arrows, squares")}, who is ahead always, the rest only when there is something to say; then `
+            + `${call(place, "done: true")}.`
+        : `No hint: the game is over. Keep your judgment, when their move stands out: ${call(place, "badge, note")}; then end with one word.`;
+    return [
+        head,
+        speech === undefined ? "The player speaks English." : speechLine(speech),
+        ...playerLines(context),
+        ...movesLines(record),
+        ...(clock === undefined ? [] : [clockLine(clock, ai)]),
+        ...(judged === undefined ? [] : judgedLines(current, judged, player)),
+        ...(over === undefined ? nowLines(current, folder, player) : []),
+        keepLine,
+    ];
+}
+/** The game's moves as the coach reads them, with the position a game set up began in, the last ones of a long game, and its opening by the book (Anatolij). */
+function movesLines(record) {
+    const opening = openingLine(record);
+    return [
+        ...(record.tags.FEN === undefined ? [] : [`The game began from a set position: ${record.tags.FEN}`]),
+        `${record.moves.length > pliesShown ? `Moves (the last ${pliesShown} plies)` : "Moves"}: ${lastMoves(record, pliesShown)}`,
+        ...(opening === undefined ? [] : [`Opening: ${opening}`]),
+    ];
+}
+/**
+ * The plies up to the player's move a judgment at `position` is for: the one the opponent answered, or the player's own when the opponent is to move, as
+ * after their move that ended the game (D-88); none before their first move.
+ */
+function judgedPly(current, position) {
+    const ply = sideToMoveAt(current, position) === current.ai ? position : position - 1;
+    return ply >= 1 ? ply : undefined;
+}
+/**
+ * The player's move to judge, the position they played it in with the book there, and, when the opponent answered it, what it left at risk and the checks
+ * it let the opponent give (Anatolij), and the answer with its words.
+ */
+function judgedLines({ game }, ply, player) {
+    const { record } = game;
+    const before = new Game({ tags: record.tags, moves: record.moves.slice(0, ply - 1) });
+    const played = { tags: record.tags, moves: record.moves.slice(0, ply) };
+    const book = knownMoves(before.position.fen);
+    const lines = [
+        `Their move to judge: ${lastMoves(played, 1)}. The position they played it in:`,
+        `FEN: ${before.position.fen}`,
+        `Material: ${materialText(materialOf(before.position.fen))}`,
+        ...compactView(before.facts, player),
+        ...(book.length === 0 ? [] : [`Book moves there, most named lines first: ${book.join(", ")}`]),
+    ];
+    if (ply === record.moves.length) {
+        return lines;
+    }
+    const after = new Game(played).facts;
+    const answer = lastMoves({ tags: record.tags, moves: record.moves.slice(0, ply + 1) }, 1);
+    const said = wordsOf(record.moves[ply]?.comment);
+    return [
+        ...lines,
+        `After their move: at risk ${riskLine(after) ?? "none"}; the opponent's checks: ${after.checks.join(" ") || "none"}.`,
+        said === undefined ? `The opponent answered ${answer} and said nothing.` : `The opponent answered ${answer} and said: «${said}»`,
+    ];
+}
+/**
+ * The position the player is to move in, for who is ahead and the hint, with its positional facts too (D-90), and what the coach said on their turn
+ * before.
+ */
+function nowLines(current, folder, player) {
+    const { game } = current;
+    const plies = game.record.moves.length;
+    const { hint, leads = [] } = coachWords(folder, current);
+    const lead = leads.find(({ position }) => position === plies - 2)?.lead;
+    return [
+        "Now, for who is ahead and your hint:",
+        `FEN: ${game.position.fen}`,
+        ...compactView(game.facts, player),
+        ...profileLines(game.profile),
+        ...(lead === undefined ? [] : [`Who you saw ahead on their turn before: ${leadText(lead)}, ${aheadWords(lead)}`]),
+        ...(hint === undefined || hint.position !== plies - 2 ? [] : [`Your hint on their turn before: «${hint.text}»`]),
+    ];
+}
+/** How the player says they play, and their rating, when their profile says so. */
+function playerLines(context) {
+    const { level, rating } = activeProfile(context.home());
+    const parts = [level === undefined ? undefined : `plays at the ${level} level`, rating === undefined ? undefined : `is rated ${rating.value} on ${rating.site}`];
+    const said = parts.filter((part) => part !== undefined);
+    return said.length === 0 ? [] : [`The player ${said.join(" and ")}.`];
+}
+/** Keeps the judgment of the player's move the opponent answered at `position`, or that ended the game, and the hint for their turn while it is still theirs. */
+function keep(folder, current, place, { ahead, badge, note, hint, arrows, squares }) {
+    const { position } = place;
+    const judging = badge !== undefined || note !== undefined;
+    const over = endOf(current.game) !== undefined;
+    const toMove = theirTurn(current, place);
+    if (hint === undefined && (arrows !== undefined || squares !== undefined)) {
+        throw new Error("Arrows and squares show your hint: give them with it. Nothing changed.");
+    }
+    if (!judging && hint === undefined && ahead === undefined) {
+        throw new Error(`Give who is ahead (ahead), your judgment (badge, note), your hint (hint, arrows, squares); or ${call(place, "done: true")}. Nothing changed.`);
+    }
+    // On the position the game ended in there is no turn to help and the result says who won; a position before it keeps who was ahead there, when the game
+    // ended while the coach thought (Federico).
+    const ended = over && position === current.game.record.moves.length;
+    if (ended && (hint !== undefined || ahead !== undefined)) {
+        throw new Error("The game is over: no hint and no ahead. Keep your judgment, when their move stands out, or end with one word. Nothing changed.");
+    }
+    if (ahead !== undefined && sideToMoveAt(current, position) === current.ai) {
+        throw new Error("Who is ahead is for a position the player is to move in, as coach {} gives it: here the opponent is to move. Nothing changed.");
+    }
+    const lead = ahead === undefined ? undefined : leadFrom(ahead);
+    // The player's move to judge: the one the opponent answered, or their own that ended the game (D-88).
+    const ply = judgedPly(current, position);
+    if (judging && (ply === undefined || (ply === position && !ended))) {
+        throw new Error("There is no move of the player's to judge here: give only your hint. Nothing changed.");
+    }
+    const legal = toMove ? current.game.legalMoves() : [];
+    if (hint !== undefined && toMove) {
+        refuseMoves(hint, arrows ?? [], legal);
+    }
+    if (judging && ply !== undefined) {
+        // A note that names a move the player could play in the position it was given for waits until none of them is legal on their turn: until then it
+        // would play for them (Anatolij).
+        const then = toMove ? legal : new Game({ tags: current.game.record.tags, moves: current.game.record.moves.slice(0, position) }).legalMoves();
+        const held = note === undefined ? [] : [...new Set(namedMoves(note, then))];
+        keepJudgment(folder, current, { ply, ...(badge === undefined ? {} : { badge }), ...(note === undefined ? {} : { note }), ...(held.length === 0 ? {} : { held }) });
+    }
+    if (hint !== undefined && toMove) {
+        keepHint(folder, current, { position, text: hint, ...drawingsOf(arrows, squares) });
+    }
+    // Who is ahead in the position the player was to move in, kept even once they have moved: the bar and the chart show it on that position.
+    if (lead !== undefined) {
+        keepLead(folder, current, { position, lead });
+    }
+    const saved = [
+        judging ? "your judgment" : undefined,
+        lead === undefined ? undefined : `who is ahead, ${aheadWords(lead)}`,
+        hint !== undefined && toMove ? "your hint" : undefined,
+    ].filter((part) => part !== undefined);
+    const hintLeft = hint !== undefined && !toMove;
+    if (over) {
+        // The game went to the archive with the move that ended it: the judgment goes there too.
+        archiveCoached(folder, current);
+        return { kept: place, then: "over", saved, hintLeft };
+    }
+    if (!toMove) {
+        return { kept: place, then: "moved", saved, hintLeft };
+    }
+    return { kept: place, then: leadMissing(folder, current, position) ? "lead" : "wait", saved, hintLeft };
+}
+/** Whether the player is still to move in the position the coach works on, in the same game going on. */
+function theirTurn(current, { game, position }) {
+    return current !== undefined && gameKey(current) === game && endOf(current.game) === undefined && current.game.record.moves.length === position
+        && current.game.position.turn !== current.ai;
+}
+/** The side to move after `position` plies of the game. */
+function sideToMoveAt({ game }, position) {
+    const { turn } = game.position;
+    return (game.record.moves.length - position) % 2 === 0 ? turn : turn === "white" ? "black" : "white";
+}
+/** Refuses a hint that plays for the player: a move they may play now written in it, or drawn as an arrow (Anatolij). */
+function refuseMoves(hint, arrows, legal) {
+    const drawn = arrows.map((arrow) => legal.find((move) => move.from === arrow.slice(1, 3) && move.to === arrow.slice(3, 5))?.san).filter((san) => san !== undefined);
+    const named = [...namedMoves(hint, legal), ...drawn];
+    if (named.length > 0) {
+        throw new Error(`Your hint gives the player a move they may play now (${[...new Set(named)].join(", ")}): point at what is on the board, a piece, a square, a file, a threat, a goal, `
+            + "never what to play, and mark squares rather than draw their move. Nothing changed.");
+    }
+}
+/** The moves a text names that the player may play now: a piece's move, a capture, a promotion or a castling, in letters or figurines; a square alone is no move. */
+function namedMoves(text, legal) {
+    const sanOf = new Map(legal.map((move) => [moveKey(move.san), move.san]));
+    const written = withSanLetters(text).match(moveWords) ?? [];
+    return written.map((word) => sanOf.get(moveKey(word))).filter((san) => san !== undefined);
+}
+// A move as SAN writes it, but a pawn's move to a square, which reads as the square: Nf3, Nbxd2, exd5, e8=Q, O-O; never the opponent's, after "...".
+const moveWords = /(?<![\p{L}\d]|\.\.\.|…)(?:O-O(?:-O)?|0-0(?:-0)?|[KQRBN][a-h]?[1-8]?x?[a-h][1-8]|[a-h]x[a-h][1-8](?:=[QRBN])?|[a-h][18]=[QRBN])(?![\p{L}\d])/gu;
+/**
+ * A move as the coach may write it and Chesspal lists it, alike: its piece and capture, the square it goes to and its promotion; a castling as it is. A
+ * piece on a square without the capture names that piece, never a move taking it (Priya and Anatolij).
+ */
+function moveKey(san) {
+    const bare = san.replace(/[+#!?]+$/, "").replaceAll("0", "O");
+    if (bare.startsWith("O-O")) {
+        return bare;
+    }
+    const [, piece = "", capture = "", to = "", promotion = ""] = /^([KQRBN])?[a-h]?[1-8]?(x?)([a-h][1-8])(=[QRBN])?$/.exec(bare) ?? [];
+    return `${piece}${capture}${to}${promotion}`;
+}

package/dist/commands/context.d.ts

@@ -1,4 +1,3 @@
-import type { Position } from "./play-move.ts";
 /** What a command runs with, besides its input: given by the command line or the MCP server, and by the tests. */
 export interface Context {
     /** The folder Chesspal runs in: the player's, where the AI host started it, which keeps only the host's files (D-71). */
@@ -19,37 +18,49 @@ export interface Context {
     page?: string;
     /** Whether a browser has the board page open now, when the MCP server serves it. */
     pageOpen?: () => boolean;
-    /** Opens a folder in the system's file manager: the data folder, from the board page (T-119); whether it could; none in the tests. */
+    /** Opens a folder in the system's file manager: the data folder, from the board page; whether it could; none in the tests. */
     openFolder?: (folder: string) => Promise<boolean>;
     /** Opens the New game window on the board pages open now, where the player chooses the game: whether one was open. */
     askNewGame?: () => boolean;
     /** The AI host, as it names itself to the MCP server: claude-code, which notes how each chat starts (D-57); none on the command line. */
     host?: () => string | undefined;
-    /** The player's words on the board page given to the AI in this process, by line: each comes once (T-65). */
+    /** The player's words on the board page given to the AI in this process, by line: each comes once. */
     readonly given: Set<string>;
     /** Told when the board page has news that no file holds: words the AI was given, which it shows read (D-53), and the AI's model (D-82). */
     heard?: () => void;
     /** Told when the chat calls a tool, before it runs: the board page hears the chat listens, and the AI's clock, held while nobody did, starts. */
     calls?: () => void;
+    /** Told when the AI starts thinking on the player's time (D-72), with the position, and when it is done: the board page shows it. */
+    ponders?: (position: SeenPosition | undefined) => void;
     /** The game the chat saw when its last tool ended, its folder and its stamp: the doorbell wakes it only for a game changed since. */
     seen?: string | undefined;
     /**
      * The position the last tool that showed the game showed the chat: its moves are refused on a game changed since, by another chat or on the page
      * (D-71); null in a chat no tool has shown the game yet, none outside a chat.
      */
-    positionSeen?: Position | null | undefined;
+    positionSeen?: SeenPosition | null | undefined;
     /** The instructions the MCP server gave in this chat, by their name and the chat's start: each comes once a chat (D-68); none on the command line. */
     told?: Set<string>;
     /** Who makes this tool call, as far as the host ties it to the call (D-81); none on the command line. */
     caller?: () => Promise<Caller | undefined>;
+    /** The agent that makes this call of a tool it shares with the chat, as the analyst (D-89); none for the chat, or when it cannot be told. */
+    agent?: string;
 }
-/** Who made a tool call: the model, else the host's name, never what the AI says of itself; the effort only when the host gives it (T-113). */
+/** Who made a tool call: the model, else the host's name, never what the AI says of itself; the effort only when the host gives it. */
 export interface Caller {
     readonly annotator: string;
     readonly effort?: string;
     /** The annotator is the host's name: the model is not known. */
     readonly hostOnly?: boolean;
 }
+/**
+ * Where the game a chat sees stands: the game by its start, none when there is none, and how many plies it has. Not by its folder, which a profile
+ * completed renames (D-71); a game in another profile started at another time.
+ */
+export interface SeenPosition {
+    readonly started?: string;
+    readonly plies: number;
+}
 /** The context of a process started in the player's folder: the data folder is found at the first command that needs it, once. */
 export declare function defaultContext(): Context;
 /** A data folder with a profile in it, the first made when there is none, named after the system's account (D-71). */

package/dist/commands/context.js

@@ -1,3 +1,4 @@
+// What every command runs with besides its input, injected by the command line, the MCP server or the tests: the folders, the time, the randomness.
 import { userInfo } from "node:os";
 import { dataFolder, openFolder } from "../home/index.js";
 import { ensureProfile } from "../profiles/index.js";

package/dist/commands/delete-game.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+/** Deletes a game of the profile in use, by its name as past_games or study_games writes it. */
+export declare const deleteGame: import("./registry.ts").Command<z.ZodObject<{
+    game: z.ZodString;
+}, z.core.$strip>, {
+    deleted: string;
+}>;

package/dist/commands/delete-game.js

@@ -0,0 +1,30 @@
+// A game deleted from a profile (D-92): played here or kept to study, with its review. Only the command line and the page delete, never the AI.
+import { z } from "zod";
+import { deleteGame as deleteGameFile, endAnalysis, gameInAnalysis, isOverOnTable, listedName, removeGame } from "../games/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { defineCommand } from "./registry.js";
+/** Deletes a game of the profile in use, by its name as past_games or study_games writes it. */
+export const deleteGame = defineCommand({
+    name: "delete_game",
+    description: "Deletes a game of the profile in use, played here or kept to study, with its review: it cannot be undone. "
+        + "Example: chesspal delete_game games/2026-11-02-153012.pgn.",
+    input: z.object({ game: z.string().min(1).describe("the game, as past_games or study_games writes it") }),
+    cliOnly: true,
+    destructive: true,
+    positionals: ["game"],
+    run: ({ game }, context) => {
+        const folder = gameFolder(context.home());
+        const name = listedName(folder, game);
+        // Asked before deleting, so that nothing fails halfway: the game over still on the table would go back to the archive with the next game.
+        const onTable = isOverOnTable(folder, name);
+        deleteGameFile(folder, name);
+        if (gameInAnalysis(folder)?.game === name) {
+            endAnalysis(folder);
+        }
+        if (onTable) {
+            removeGame(folder);
+        }
+        return { deleted: name };
+    },
+    format: ({ deleted }) => `${deleted} deleted, with its review.`,
+});

package/dist/commands/delete-review.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+/** Deletes the review of a game of the profile in use, by its name as past_games or study_games writes it. */
+export declare const deleteReview: import("./registry.ts").Command<z.ZodObject<{
+    game: z.ZodString;
+}, z.core.$strip>, {
+    game: string;
+    reviewed: boolean;
+}>;

package/dist/commands/delete-review.js

@@ -0,0 +1,34 @@
+// A game's review deleted (D-92): the game stays, to analyse again, with another model or effort or after an update. Only the command line and the page
+// delete, never the AI.
+import { z } from "zod";
+import { isReviewed, unreviewed } from "../core/index.js";
+import { forgetCoach, gameInAnalysis, isOverOnTable, rewriteGame, startAnalysis } from "../games/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { defineCommand } from "./registry.js";
+import { namedGame } from "./study.js";
+/** Deletes the review of a game of the profile in use, by its name as past_games or study_games writes it. */
+export const deleteReview = defineCommand({
+    name: "delete_review",
+    description: "Deletes the review of a game of the profile in use: the badges, notes, drawings and estimates on its moves, the word on the game and who "
+        + "signed it, the coach's judgments too; the game stays, to analyse again. Example: chesspal delete_review games/2026-11-02-153012.pgn.",
+    input: z.object({ game: z.string().min(1).describe("the game, as past_games or study_games writes it") }),
+    cliOnly: true,
+    destructive: true,
+    idempotent: true,
+    positionals: ["game"],
+    run: ({ game }, context) => {
+        const folder = gameFolder(context.home());
+        const { record, name } = namedGame(context, game);
+        rewriteGame(folder, name, unreviewed(record));
+        // The coach's judgments on the game just over would go back into it.
+        if (isOverOnTable(folder, name)) {
+            forgetCoach(folder);
+        }
+        // The page showing the game hears of it, and shows it without its review.
+        if (gameInAnalysis(folder)?.game === name) {
+            startAnalysis(folder, name, context.now());
+        }
+        return { game: name, reviewed: isReviewed(record) };
+    },
+    format: ({ game, reviewed }) => `${game}: ${reviewed ? "review deleted" : "it had no review; the judgments on its moves are deleted"}. analyse_game goes over it again.`,
+});

package/dist/commands/drawings.d.ts

@@ -1,7 +1,5 @@
 import { z } from "zod";
 import { type DrawnArrow, type DrawnSquare } from "../core/index.ts";
-/** The most a note of the AI's on a move may hold: a few sentences. */
-export declare const noteLimit = 700;
 /** A note of the AI's on a move, as its input reads it: on one line of commands, so without brackets or braces. */
 export declare const noteInput: z.ZodString;
 /** The arrows the AI draws, as their input reads them. */

package/dist/commands/drawings.js

@@ -3,17 +3,19 @@
 import { z } from "zod";
 import { arrowOf, squareOf } from "../core/index.js";
 /** The most a note of the AI's on a move may hold: a few sentences. */
-export const noteLimit = 700;
+const noteLimit = 700;
 // The most arrows, and the most squares, on one move.
 const drawLimit = 6;
 /** A note of the AI's on a move, as its input reads it: on one line of commands, so without brackets or braces. */
 export const noteInput = z.string().trim().min(1).max(noteLimit).regex(/^[^[\]{}]*$/, "write it without [ ] { }");
+// A drawing as the AI may write it, spaced or with a dash, as PGN writes it: "R f2 e1" and "Rf2-e1" are Rf2e1 (Priya).
+const drawing = z.string().overwrite((text) => text.replace(/[\s-]+/g, ""));
 /** The arrows the AI draws, as their input reads them. */
-export const arrowsInput = z.array(z.string().regex(/^[GRYB][a-h][1-8][a-h][1-8]$/, "an arrow is a colour's letter and two squares: Gf6e4; a single square goes in squares")
+export const arrowsInput = z.array(drawing.regex(/^[GRYB][a-h][1-8][a-h][1-8]$/, "an arrow is a colour's letter and two squares: Gf6e4; a single square goes in squares")
     .refine((arrow) => arrow.slice(1, 3) !== arrow.slice(3, 5), "an arrow goes from a square to another: a single square goes in squares")).max(drawLimit).optional()
     .describe("arrows on the board, as PGN's %cal writes them: Rf2e1. G green: the better move or the good idea; R red: a threat or the mistake; Y yellow: another way; B blue: a plan.");
 /** The squares the AI marks, as their input reads them. */
-export const squaresInput = z.array(z.string().regex(/^[GRYB][a-h][1-8]$/, "a square is a colour's letter and the square: Rf2")).max(drawLimit).optional()
+export const squaresInput = z.array(drawing.regex(/^[GRYB][a-h][1-8]$/, "a square is a colour's letter and the square: Rf2")).max(drawLimit).optional()
     .describe("squares to mark, as PGN's %csl writes them: Rf2; colours as for arrows");
 /** The arrows and squares drawn, those that read; none of either left out. */
 export function drawingsOf(arrows = [], squares = []) {

package/dist/commands/end-game.js

@@ -2,7 +2,9 @@ import { z } from "zod";
 import { canMate, endWithMood, Game, moods, timeLeft } from "../core/index.js";
 import { archiveEnded, bothSidesMoved, drawOfferOf, saveGame } from "../games/index.js";
 import { gameFolder } from "../profiles/index.js";
-import { gameGoingOn, nextStep, positionLines, summaryOf } from "./game-summary.js";
+import { withAnalyst } from "./agents.js";
+import { nextStep, positionLines } from "./answer-lines.js";
+import { gameGoingOn, summaryOf } from "./game-summary.js";
 import { refuseUnseenPosition } from "./play-move.js";
 import { defineCommand } from "./registry.js";
 import { colourName } from "./view.js";
@@ -38,7 +40,8 @@ export const endGame = defineCommand({
             : { ...current, game, clock: { ...current.clock, left: timeLeft(current.clock, current.game.position.turn, now), since: now.toISOString() } };
         saveGame(folder, ended);
         const { archive, warning } = archiveEnded(folder, ended);
-        return warning === undefined ? { game: summaryOf(ended, now, archive) } : { game: summaryOf(ended, now, archive), warning };
+        const summary = withAnalyst(summaryOf(ended, now, archive), context);
+        return warning === undefined ? { game: summary } : { game: summary, warning };
     },
     format: ({ game, warning }) => [...positionLines(game), ...(warning === undefined ? [] : [warning]), nextStep(game)].join("\n"),
 });

package/dist/commands/export-game.d.ts

@@ -3,7 +3,7 @@ interface Exported {
     format: "pgn" | "moves" | "fen";
     text: string;
 }
-/** The game as PGN or its position as FEN, for the player to copy or keep: the plans stay hidden while it goes on (D-29); the moves alone for another site (T-59). */
+/** The game as PGN or its position as FEN, for the player to copy or keep: the plans stay hidden while it goes on (D-29); the moves alone for another site. */
 export declare const exportGame: import("./registry.ts").Command<z.ZodObject<{
     format: z.ZodEnum<{
         fen: "fen";

package/dist/commands/export-game.js

@@ -3,7 +3,7 @@ import { movesPgn, playerPgn } from "../games/index.js";
 import { gameFolder } from "../profiles/index.js";
 import { gameAt } from "./clock.js";
 import { defineCommand } from "./registry.js";
-/** The game as PGN or its position as FEN, for the player to copy or keep: the plans stay hidden while it goes on (D-29); the moves alone for another site (T-59). */
+/** The game as PGN or its position as FEN, for the player to copy or keep: the plans stay hidden while it goes on (D-29); the moves alone for another site. */
 export const exportGame = defineCommand({
     name: "export",
     description: "Gives the game as PGN, its moves alone as PGN for Lichess or chess.com, or its position as FEN, for the player to copy or keep. While the game goes on, "
@@ -15,11 +15,12 @@ export const exportGame = defineCommand({
     readOnly: true,
     positionals: ["format"],
     run: ({ format }, context) => {
-        const current = gameAt(gameFolder(context.home()), context.now());
+        const folder = gameFolder(context.home());
+        const current = gameAt(folder, context.now());
         if (current === undefined) {
             throw new Error("There is no game to export: start one with new_game.");
         }
-        const text = format === "fen" ? current.game.position.fen : format === "moves" ? movesPgn(current) : playerPgn(current);
+        const text = format === "fen" ? current.game.position.fen : format === "moves" ? movesPgn(current) : playerPgn(folder, current);
         return { format, text };
     },
     format: (result) => result.text,