chesspal 0.0.1 → 0.2.0

package/README.md

@@ -1,5 +1,102 @@
 # Chesspal
 
-Play chess against an AI with a character, and learn with an AI coach that remembers your games and helps you improve.
+Play chess against an AI on a real board, or learn with one.
 
-In development: this is a placeholder for the first release.
+![The board page during a game: the AI's words on the left, the board in the middle, the opening's name and the moves on the right](https://raw.githubusercontent.com/stefanocaronia/chesspal/main/docs/screenshot.png)
+
+## Get started
+
+You need [Node.js](https://nodejs.org) 22.13 or newer and an AI agent on your computer, [Claude Code](https://code.claude.com/docs/en/setup) or [Codex](https://developers.openai.com/codex): see [what you need](#what-you-need). Open a new terminal, after installing Node.js (one opened before does not find `npm`), and type:
+
+```bash
+npm install -g chesspal
+chesspal init chess
+cd chess
+claude
+```
+
+- `npm install -g` installs the `chesspal` command for the whole computer, where your agent finds it.
+- `chesspal init chess` makes the folder `chess` to play in. Any name will do; your games are kept [elsewhere](#where-your-games-are).
+- `claude` opens Claude Code in that folder (in the Claude desktop app, choose the folder in the Code tab). With Codex, type `codex`, and when it asks about Chesspal's two hooks, choose **Trust all and continue**.
+- The first time, your agent asks whether you trust the folder: say yes.
+
+Then **say hello**. The AI answers with the link to the board page: open it in your browser, tell it who you are, and ask for a game. You choose your colour, the clock and the AI's level, and play on the board.
+
+On Windows, use Command Prompt (press Start, type `cmd`, press Enter). PowerShell, on a new computer, refuses npm's commands with "running scripts is disabled on this system"; there, type `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once and answer yes, or use Command Prompt. Codex on Windows also offers to set up its sandbox the first time: choose the first option, and answer yes when Windows asks for permission.
+
+## What it does
+
+An AI in a plain chat forgets the position, plays illegal moves and sees no board. Chesspal is what it lacks: it **keeps the rules, the board, the clock and your games**; the AI **plays, reasons and talks**. Every move is checked by Chesspal, and no chess engine plays for the AI: every judgment is its own, made from the facts Chesspal hands it, such as the legal moves, the pieces attacked and defended, the pins and the opening's name.
+
+- **Play on a board** in your browser, and talk with the AI there or in the chat.
+- **Choose its level**, from beginner to master: the higher, the more of the position the AI sees.
+- **Play with a clock**, against an AI that knows how much time it has left; offer a draw, resign, save the game as PGN.
+- **Go over a game** with the AI when it is over: its notes show on the board page, in Analyses. Games from other sites come in as PGN files.
+- **Keep a profile** for each player at the same computer, with their games.
+
+Coming later: an AI coach that helps you grow, exercises chosen on your weak points, a rating worked out from your games, an opponent with a character and moods of its own, and local models.
+
+## What you need
+
+- **Node.js 22.13** or newer: download the version marked LTS and install it like any program.
+- **An AI agent** with your own subscription: Claude Code, with a paid Claude plan, or Codex, with a ChatGPT account. Chesspal never uses an API key, which is paid by the call: sign your agent in with your account.
+- **A web browser**, for the board page.
+
+Chesspal works with any agent that supports MCP tools and can work with the files on your computer: we develop it with Claude Code, and Codex is connected too.
+
+## Good to know
+
+- **For the next game**, type `/clear` in the chat or start a new one: a long chat makes the AI slower and costs you more.
+- **A move written in the chat** counts too: `e4`, `Nf3`, in the international notation (K Q R B N in every language), or in words.
+- **To update**, close the chat, run `npm install -g chesspal` again, then `chesspal init` in your folder: it updates its own lines and keeps what you wrote there. In Codex, allow the hooks again when it says so.
+
+## Where your games are
+
+In one folder for every folder you play in:
+
+- Windows: `Documents › My Games › Chesspal`, inside OneDrive if you use it;
+- macOS: `Documents › Chesspal`; Linux: `Chesspal` in your Documents folder.
+
+The board page shows where, and its **Open the folder** button opens it. To back up your games, copy that whole folder; to move them to another computer, put the copy in the same place there. Do it with the chat and the board page closed.
+
+## Try it, and tell us
+
+Chesspal is in early development: the version on npm is a first one to try, and it may change from one release to the next. When something breaks, confuses you or could work better, open an [issue on GitHub](https://github.com/stefanocaronia/chesspal/issues): what you did, what you expected, what happened.
+
+## Development
+
+Chesspal is an MCP server, a command line and a board page, all made from the same commands, which check every move with [chess.js](https://github.com/jhlywa/chess.js) and write the games atomically.
+
+```bash
+git clone https://github.com/stefanocaronia/chesspal.git
+cd chesspal
+npm install
+npm run build
+npm test
+```
+
+[The guide for development](https://github.com/stefanocaronia/chesspal/blob/main/AGENTS.md), for people and AI coding agents alike, holds the other scripts, the layout, the architecture's rules and the coding guidelines.
+
+## Credits
+
+- The rules: [chess.js](https://github.com/jhlywa/chess.js), under the BSD 2-Clause license.
+- The openings' names: Lichess's [chess-openings](https://github.com/lichess-org/chess-openings), under CC0.
+- The pieces: Nitida, Torretta and Capablanca are Chesspal's own, the last after the diagrams of Capablanca's *Chess Fundamentals* (1921), in the public domain; they are free to use under CC BY 4.0, crediting "Stefano Caronia, Chesspal". [The piece sets' credits](https://github.com/stefanocaronia/chesspal/blob/main/src/page/pieces/CREDITS.md).
+
+Chesspal ships only original or open-licensed content, and no GPL dependency.
+
+## License
+
+[MIT](https://github.com/stefanocaronia/chesspal/blob/main/LICENSE).
+
+## Development notes
+
+Developed with the help of AI coding agents. Everything is designed, reviewed and tested by the project's human maintainer.
+
+**We encourage everyone to use AI for their own purposes.**\
+The means of production should belong to the people.\
+Fight corporate control of technology, not our right to use it.
+
+---
+
+© 2026 [Stefano Caronia](https://stefanocaronia.it) · [GitHub](https://github.com/stefanocaronia/chesspal) · [npm](https://www.npmjs.com/package/chesspal)

package/dist/cli/chat-hook.d.ts

@@ -0,0 +1,2 @@
+/** Reads the hook's input and writes how the chat started; a failure is told on stderr and never stops the chat. */
+export declare function recordChatStart(input?: NodeJS.ReadableStream, folder?: string, now?: Date): Promise<void>;

package/dist/cli/chat-hook.js

@@ -0,0 +1,33 @@
+// `chesspal chat`, the SessionStart hook of Claude Code and Codex (D-57): it writes how the chat started, new, cleared, resumed or compacted, for new_game to read.
+import { saveChatStart } from "../games/index.js";
+/** Reads the hook's input and writes how the chat started; a failure is told on stderr and never stops the chat. */
+export async function recordChatStart(input = process.stdin, folder = process.cwd(), now = new Date()) {
+    try {
+        const hook = parsed(await textOf(input));
+        saveChatStart(folder, {
+            source: typeof hook.source === "string" ? hook.source : "startup",
+            at: now.toISOString(),
+            ...(typeof hook.session_id === "string" ? { session: hook.session_id } : {}),
+            ...(typeof hook.transcript_path === "string" ? { transcript: hook.transcript_path } : {}),
+        });
+    }
+    catch (error) {
+        process.stderr.write(`Chesspal could not note how the chat started: ${error.message}\n`);
+    }
+}
+async function textOf(input) {
+    let text = "";
+    for await (const chunk of input) {
+        text += String(chunk);
+    }
+    return text;
+}
+function parsed(text) {
+    try {
+        const value = JSON.parse(text);
+        return typeof value === "object" && value !== null ? value : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/cli/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { runCommandLine } from "./command-line.js";
+const args = process.argv.slice(2);
+// "chesspal mcp" turns the process into a server for an AI host, "chesspal listen" into the doorbell of Claude Code, or of Codex with --codex,
+// "chesspal chat" notes how the chat started; everything else is a command.
+if (args.length === 1 && args[0] === "mcp") {
+    // The server and its SDK load only here: every other command starts faster without them.
+    const { startMcpServer } = await import("../server/mcp.js");
+    await startMcpServer();
+}
+else if (args[0] === "listen" && (args.length === 1 || (args.length === 2 && args[1] === "--codex"))) {
+    const { listen } = await import("../server/bell.js");
+    await listen(args[1] === "--codex");
+}
+else if (args.length === 1 && args[0] === "chat") {
+    const { recordChatStart } = await import("./chat-hook.js");
+    await recordChatStart();
+}
+else {
+    const { output, exitCode } = await runCommandLine(args);
+    if (exitCode === 0) {
+        console.log(output);
+    }
+    else {
+        console.error(output);
+    }
+    process.exitCode = exitCode;
+}

package/dist/cli/command-line.d.ts

@@ -0,0 +1,7 @@
+import { type AnyCommand, type Context } from "../commands/index.ts";
+export interface CommandLineResult {
+    output: string;
+    exitCode: number;
+}
+/** The `chesspal` command line: finds the command, validates its input, runs it and renders the result. */
+export declare function runCommandLine(argv: string[], context?: Context, list?: AnyCommand[]): Promise<CommandLineResult>;

package/dist/cli/command-line.js

@@ -0,0 +1,177 @@
+// The `chesspal` command line: a command's input read from the arguments, its result written for a person.
+import { parseArgs } from "node:util";
+import { baseType, commandLineFieldProblem, commands, defaultContext, inputProblems, isBoolean, isList, takesNumbers } from "../commands/index.js";
+import { version } from "../version.js";
+// The commands that exist only on the command line: cli.ts starts the server, the doorbell or the chat's note, when one comes alone.
+const mcpDescription = "Start the MCP server for an AI host. Through it the host uses these commands as tools; the host starts it, with no options.";
+const listenDescription = "Wait for the player's move on the board page and wake the chat. Claude Code starts it at the end of each turn, and Codex with --codex, as init sets them up.";
+const chatDescription = "Note how the chat started: new, cleared, resumed or compacted. Claude Code and Codex run it when a chat starts, as init sets them up.";
+/** The `chesspal` command line: finds the command, validates its input, runs it and renders the result. */
+export async function runCommandLine(argv, context = defaultContext(), list = commands) {
+    const [commandName, ...args] = argv;
+    if (commandName === undefined || commandName === "--help" || commandName === "-h") {
+        return success(generalHelp(list));
+    }
+    if (commandName === "--version" || commandName === "-v") {
+        return success(version);
+    }
+    if (commandName === "mcp") {
+        // A host that adds options to it would get this text instead of the protocol: it must see the failure.
+        const help = `chesspal mcp\n\n${mcpDescription}`;
+        return args.length === 0 || args.includes("--help") || args.includes("-h") ? success(help) : failure(`chesspal mcp takes no options: ${args.join(" ")}.\n\n${help}`);
+    }
+    if (commandName === "listen") {
+        const help = `chesspal listen [--codex]\n\n${listenDescription}`;
+        const known = args.every((arg) => ["--codex", "--help", "-h"].includes(arg));
+        return known ? success(help) : failure(`chesspal listen takes only --codex: ${args.join(" ")}.\n\n${help}`);
+    }
+    if (commandName === "chat") {
+        const help = `chesspal chat\n\n${chatDescription}`;
+        return args.length === 0 || args.includes("--help") || args.includes("-h") ? success(help) : failure(`chesspal chat takes no options: ${args.join(" ")}.\n\n${help}`);
+    }
+    const command = list.find((candidate) => candidate.name === commandName);
+    if (!command) {
+        return failure(`Unknown command "${commandName}".\n\n${generalHelp(list)}`);
+    }
+    if (args.includes("--help") || args.includes("-h")) {
+        return success(commandHelp(command));
+    }
+    try {
+        return success(await runCommand(command, args, context));
+    }
+    catch (error) {
+        return failure(error instanceof Error ? error.message : String(error));
+    }
+}
+async function runCommand(command, args, context) {
+    const { input, asJson } = readArguments(command, args);
+    const parsed = command.input.safeParse(input);
+    if (!parsed.success) {
+        const positionals = command.positionals ?? [];
+        const written = (name) => (positionals.includes(name) ? `<${name}>` : `--${name}`);
+        throw refused(command, inputProblems(command.name, parsed.error.issues, input, written));
+    }
+    const result = await command.run(parsed.data, context);
+    return asJson ? JSON.stringify(result, null, 2) : command.format(result, context);
+}
+/** An input refused, in the words the MCP server uses (inputProblems), with the command's usage. */
+function refused(command, problems) {
+    return new Error(`${problems} Nothing changed.\nUsage: ${usage(command)}\nRun \`chesspal ${command.name} --help\` for its options.`);
+}
+/** The command line's own refusals, from parseArgs, in the same words: an unknown option is a parameter the command does not have. */
+function parsedArguments(command, config) {
+    try {
+        return parseArgs(config);
+    }
+    catch (error) {
+        const { code, message } = error;
+        const option = /'(-[^' ]+)/.exec(message)?.[1] ?? "";
+        if (code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+            // A positional written as an option: the command has it, in another place.
+            const name = option.replace(/^-+/, "");
+            throw refused(command, command.positionals?.includes(name) === true
+                ? `Give ${name} as <${name}>, without ${option}.`
+                : inputProblems(command.name, [{ code: "unrecognized_keys", keys: [option], path: [], message }], {}, (key) => key));
+        }
+        throw refused(command, message.endsWith("argument missing") ? `${option} needs a value.` : `${message}${message.endsWith(".") ? "" : "."}`);
+    }
+}
+function readArguments(command, args) {
+    const positionals = command.positionals ?? [];
+    const options = { json: { type: "boolean" } };
+    for (const [name, field] of inputFields(command)) {
+        const problem = commandLineFieldProblem(command.name, name, positionals.includes(name));
+        if (problem !== undefined) {
+            throw new Error(problem);
+        }
+        if (!positionals.includes(name)) {
+            options[name] = { type: isBoolean(field) ? "boolean" : "string", multiple: isList(field) };
+        }
+    }
+    // A flag is turned off as --no-hidden, as the MCP server takes hidden: false.
+    const parsed = parsedArguments(command, { args, options, allowPositionals: true, allowNegative: true, strict: true, tokens: true });
+    const extra = parsed.positionals.slice(positionals.length);
+    if (extra.length > 0) {
+        // A text given in several words: quote it. A word from a list is not a text.
+        const last = positionals.at(-1);
+        const freeText = last !== undefined && baseType(command.input.shape[last]) === "string";
+        const quoted = parsed.positionals.slice(positionals.length - 1).join(" ");
+        throw refused(command, `Unexpected argument: ${extra.join(" ")}.${freeText ? ` Put a value with spaces in quotes, such as "${quoted}".` : ""}`);
+    }
+    checkRepeatedOptions(command, parsed.tokens, options);
+    const input = {};
+    for (const [name, value] of Object.entries(parsed.values)) {
+        if (name !== "json") {
+            input[name] = value;
+        }
+    }
+    positionals.forEach((name, index) => {
+        if (parsed.positionals[index] !== undefined) {
+            input[name] = parsed.positionals[index];
+        }
+    });
+    // The command line reads every value as text: a field that takes numbers gets them, and a text that is no number stays, for the schema to refuse.
+    for (const [name, field] of inputFields(command)) {
+        const value = input[name];
+        if (value !== undefined && takesNumbers(field)) {
+            input[name] = Array.isArray(value) ? value.map(number) : number(value);
+        }
+    }
+    return { input, asJson: parsed.values.json === true };
+}
+function number(value) {
+    return typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value)) ? Number(value) : value;
+}
+/** An option that takes one value must not be given twice: the first value would be lost without a word. */
+function checkRepeatedOptions(command, tokens, options) {
+    const given = [];
+    for (const token of tokens) {
+        if (token.kind !== "option" || token.name === undefined || options[token.name]?.multiple === true) {
+            continue;
+        }
+        if (given.includes(token.name)) {
+            throw refused(command, `Give --${token.name} only once.`);
+        }
+        given.push(token.name);
+    }
+}
+function inputFields(command) {
+    return Object.entries(command.input.shape);
+}
+/** The commands, each with the first sentence of its description. */
+function generalHelp(list) {
+    const width = Math.max("listen".length, ...list.map((command) => command.name.length));
+    const line = (name, description) => `  ${name.padEnd(width)} ${firstSentence(description)}`;
+    return [
+        `chesspal ${version}`,
+        "",
+        "Commands:",
+        ...list.map((command) => line(command.name, command.description)),
+        line("mcp", mcpDescription),
+        line("listen", listenDescription),
+        line("chat", chatDescription),
+        "",
+        "Run `chesspal <command> --help` for its options.",
+    ].join("\n");
+}
+function commandHelp(command) {
+    const positionals = command.positionals ?? [];
+    const optionLines = inputFields(command).map(([name, field]) => {
+        const flag = positionals.includes(name) ? `<${name}>` : `--${name}${isBoolean(field) ? "" : " <value>"}${isList(field) ? "..." : ""}`;
+        return `  ${flag.padEnd(20)} ${field.description ?? ""}`;
+    });
+    return [usage(command), "", command.description, "", ...optionLines, `  ${"--json".padEnd(20)} print the result as JSON`].join("\n");
+}
+function usage(command) {
+    return ["chesspal", command.name, ...(command.positionals ?? []).map((name) => `<${name}>`), "[options]"].join(" ");
+}
+function firstSentence(text) {
+    const end = text.search(/[.!?](\s|$)/);
+    return end === -1 ? text : text.slice(0, end + 1);
+}
+function success(output) {
+    return { output, exitCode: 0 };
+}
+function failure(output) {
+    return { output, exitCode: 1 };
+}

package/dist/commands/agents.d.ts

@@ -0,0 +1,26 @@
+import { type CurrentGame } from "../games/index.ts";
+import type { Context } from "./context.ts";
+import type { GameSummary } from "./game-summary.ts";
+/** Whether an analyst agent goes over a game over when the player wants: in Claude Code, with its agent in the player's folder (D-89). */
+export declare function analystRuns(context: Context): boolean;
+/**
+ * The game over, with the analyst agent that goes over it when the player wants, where it runs (D-89); over, the game from status and ai_say, which come after
+ * its end: once it is in analysis, by the agent or the chat, or reviewed, the chat goes over that review and never starts the agent again (Stefano).
+ */
+export declare function withAnalyst(summary: GameSummary, context: Context, over?: CurrentGame): GameSummary;
+/** How the chat has a game over gone over by the analyst agent, on the player's yes or for the game they brought (D-89). */
+export declare function analystLine(game?: string): string;
+/** How the chat goes over a game the analyst agent has reviewed, or is reviewing: from that review, never with another agent (Stefano). */
+export declare function reviewedLine(game?: string): string;
+/** Whether a coach judges the player's moves when the helps are on: in Claude Code, with its agent in the player's folder (D-80, D-88). */
+export declare function coachRuns(context: Context): boolean;
+/**
+ * Whether to start the coach after the player's own move has ended the game on the board, with the helps on: it judges that move too (D-88). Told again
+ * until it starts, since a chat woken by the page may lose the line on its way to its words (Priya).
+ */
+export declare function coachOnEnd(context: Context, folder: string, current: CurrentGame): boolean;
+/**
+ * How to start the agents, in one message, the one that thinks first, since it needs the time (Priya), and that the player sees nothing of
+ * them: their end needs no answer either. The end of the last move's agents, told just after, must not take their place (Priya).
+ */
+export declare function agentsLine(agents: readonly string[]): string;

package/dist/commands/agents.js

@@ -0,0 +1,72 @@
+// The agents that work beside the chat in Claude Code: the analyst that goes over a game over (D-89) and the coach that judges the player's moves (D-88).
+import { isReviewed } from "../core/index.js";
+import { archivedGame, archivedName, coachStarted, gameInAnalysis } from "../games/index.js";
+import { analystAgent, coachAgent, hasAgent } from "../host-files/index.js";
+import { gameFolder, helpsIn } from "../profiles/index.js";
+/** Whether an analyst agent goes over a game over when the player wants: in Claude Code, with its agent in the player's folder (D-89). */
+export function analystRuns(context) {
+    return context.host?.() === "claude-code" && hasAgent(context.folder, analystAgent);
+}
+/**
+ * The game over, with the analyst agent that goes over it when the player wants, where it runs (D-89); over, the game from status and ai_say, which come after
+ * its end: once it is in analysis, by the agent or the chat, or reviewed, the chat goes over that review and never starts the agent again (Stefano).
+ */
+export function withAnalyst(summary, context, over) {
+    const { end } = summary;
+    if (end === undefined || !analystRuns(context)) {
+        return summary;
+    }
+    return { ...summary, end: { ...end, analyst: over !== undefined && goneOver(context, over) ? "done" : "offer" } };
+}
+/** How the chat has a game over gone over by the analyst agent, on the player's yes or for the game they brought (D-89). */
+export function analystLine(game) {
+    return `start the chesspal-analyst agent in the background with the prompt "Analyse${game === undefined ? "" : ` ${game}`}. The player speaks <their language>.": it writes its review on the board `
+        + "page, which shows it at work; tell the player in a word, and when it ends go over the game with them from what it tells you.";
+}
+/** How the chat goes over a game the analyst agent has reviewed, or is reviewing: from that review, never with another agent (Stefano). */
+export function reviewedLine(game) {
+    return "The analyst agent has gone over this game, or is at it: never start it again. When the player wants it gone over, go over it with them from what "
+        + `it told you, or, in a chat without it, from its review on the board page, which analyse_game ${game === undefined ? "" : `{"game": "${game}"} `}gives.`;
+}
+/** Whether a coach judges the player's moves when the helps are on: in Claude Code, with its agent in the player's folder (D-80, D-88). */
+export function coachRuns(context) {
+    return context.host?.() === "claude-code" && hasAgent(context.folder, coachAgent);
+}
+/**
+ * Whether to start the coach after the player's own move has ended the game on the board, with the helps on: it judges that move too (D-88). Told again
+ * until it starts, since a chat woken by the page may lose the line on its way to its words (Priya).
+ */
+export function coachOnEnd(context, folder, current) {
+    const { game, ai } = current;
+    return game.outcome.over && game.position.turn === ai && helpsIn(folder) && coachRuns(context) && !coachStarted(folder, current);
+}
+/**
+ * How to start the agents, in one message, the one that thinks first, since it needs the time (Priya), and that the player sees nothing of
+ * them: their end needs no answer either. The end of the last move's agents, told just after, must not take their place (Priya).
+ */
+export function agentsLine(agents) {
+    const prompt = (agent) => `the prompt "${agent === coachAgent ? "Coach." : "Ponder."}"`;
+    const [first = "", second] = agents;
+    if (second === undefined) {
+        const why = first === coachAgent ? "Coach the player" : "Think on the player's time";
+        return `${why}: start the ${first} agent in the background with ${prompt(first)}; start it even when an agent of the move before has just ended, `
+            + "and write nothing about it in the chat, now or when it ends.";
+    }
+    return `Think on the player's time and coach them: in one message, start two agents in the background, ${first} with ${prompt(first)} and ${second} with `
+        + `${prompt(second)}; start them even when an agent of the move before has just ended, and write nothing about them in the chat, now or when they end.`;
+}
+/** Whether the game over is gone over already: in analysis now, by the analyst agent or the chat, or reviewed, whatever the page opened since (Federico). */
+function goneOver(context, over) {
+    const folder = gameFolder(context.home());
+    const archived = archivedName(folder, over);
+    if (archived === undefined || gameInAnalysis(folder)?.game === archived) {
+        return archived !== undefined;
+    }
+    try {
+        return isReviewed(archivedGame(folder, archived));
+    }
+    catch {
+        // A game the archive cannot read is offered as it would be: the analyst says what is wrong with it.
+        return false;
+    }
+}

package/dist/commands/ai-move.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { type MovePlayed } from "./game-summary.ts";
+/** The AI's move, with its plan, kept hidden (D-29), and its comment for the player when it has something to say (D-12, D-54). */
+export declare const aiMove: import("./registry.ts").Command<z.ZodObject<{
+    move: z.ZodString;
+    plan: z.ZodString;
+    comment: z.ZodOptional<z.ZodString>;
+    arrows: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    squares: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    offer_draw: z.ZodOptional<z.ZodBoolean>;
+    mood: z.ZodOptional<z.ZodEnum<{
+        neutral: "neutral";
+        happy: "happy";
+        surprised: "surprised";
+        worried: "worried";
+        thoughtful: "thoughtful";
+        sad: "sad";
+    }>>;
+}, z.core.$strip>, Played>;
+/**
+ * The AI's move, the agents to start on the player's time when the host runs them (D-72, D-88), and whether the player sees no board page, so the AI
+ * copies the board (D-85).
+ */
+type Played = MovePlayed & {
+    agents?: string[];
+    board?: true;
+};
+export {};

package/dist/commands/ai-move.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { boardText, drawingsText, moods, moodTag } from "../core/index.js";
+import { commentWithPlan, talkLimits } from "../games/index.js";
+import { coachAgent, hasAgent, ponderAgentFor } from "../host-files/index.js";
+import { gameFolder, helpsIn } from "../profiles/index.js";
+import { agentsLine, coachRuns, withAnalyst } from "./agents.js";
+import { closingLines, moveLines, shownMove } from "./answer-lines.js";
+import { arrowsInput, drawingsOf, squaresInput } from "./drawings.js";
+import {} from "./game-summary.js";
+import { playMove, refuseUnseenPosition } from "./play-move.js";
+import { defineCommand, sentence } from "./registry.js";
+import { give, waitingWords } from "./say.js";
+/** The AI's move, with its plan, kept hidden (D-29), and its comment for the player when it has something to say (D-12, D-54). */
+export const aiMove = defineCommand({
+    name: "ai_move",
+    description: "Plays your move, with your plan, hidden from the player, and a comment for them only when there is something to say: a capture, a move of theirs "
+        + "worth a word, words of theirs to answer; as a player at a tournament, never revealing your plans or threats unless the helps are on, and never the "
+        + "player's best move. When no board page is open, it answers with the board for your message. "
+        + 'Example: ai_move {move: "d5", plan: "After exd5 Na5, chase the bishop on c4.", comment: "An old favourite of mine."}.',
+    input: z.object({
+        move: z.string().min(1).describe("your move, in SAN (Nf3, exd5, O-O, e8=Q) or as squares (g1f3, e7e8q)"),
+        plan: sentence(200).describe("your plan, in one sentence: kept for you, hidden from the player"),
+        comment: sentence(talkLimits.aiHelps).optional().describe(`your words for the player, in one sentence of ${talkLimits.ai} characters at most, only when there is something to say: pieces and moves in words ("your `
+            + `knight takes on f6"), a move you write with the pieces' figurines, as the tools show it (♞xf6+ for Nxf6+); your plans and threats only with the helps on, and then as long as a note of ${talkLimits.aiHelps} `
+            + "characters, to teach; **two asterisks** put a word or two in bold on the page"),
+        arrows: arrowsInput.describe("only with the helps on: arrows on the board after your move, to show what your comment says, never your move itself: Rf2e1; G green: a good idea; "
+            + "R red: a threat or the mistake; Y yellow: another way; B blue: a plan"),
+        squares: squaresInput.describe("only with the helps on: squares to mark after your move, as PGN's %csl writes them: Rf2; colours as for arrows"),
+        offer_draw: z.boolean().optional().describe("true offers the player a draw with this move: it stands until their move"),
+        mood: z.enum(moods).optional().describe("how you feel, on a move where the game turns for you: your face on the board page shows it for three of your moves, this one included (a surprise for this one "
+            + "only), then turns neutral by itself"),
+    }),
+    alwaysLoad: true,
+    showsGame: true,
+    positionals: ["move"],
+    run: ({ move, plan, comment, offer_draw: offerDraw = false, mood, arrows, squares }, context) => {
+        const folder = gameFolder(context.home());
+        refuseUnseenPosition(context, folder);
+        refuseWithoutHelps(folder, { comment, arrows, squares });
+        const drawings = drawingsOf(arrows, squares);
+        // The player's words are read before the move, which would count as the answer to them; a move refused leaves them for the next call.
+        const waiting = waitingWords(context);
+        const words = [commentWithPlan(comment, plan), drawingsText(drawings), mood === undefined ? "" : moodTag(mood)].filter((part) => part !== "").join(" ");
+        const played = playMove(folder, context.now(), "ai", move, (message, legal) => `${message} Legal: ${legal.join(" ")}. Nothing changed.`, { comment: words, offerDraw });
+        const agents = agentsAfter(context, folder, played);
+        const board = context.pageOpen?.() === true ? {} : { board: true };
+        return { ...played, game: withAnalyst(played.game, context), words: give(context, waiting), ...(agents.length === 0 ? {} : { agents }), ...board };
+    },
+    format: (result) => {
+        // The mood the AI has just given is not told back: player_move and status tell it while it lasts (Priya).
+        const game = { ...result.game };
+        delete game.mood;
+        // The board goes before the player's words and the next step, which stays the last line.
+        return [
+            `Played ${shownMove(result.move)}.`,
+            ...moveLines({ ...result, game }),
+            ...(result.board === true ? ["No board page is open: copy this board into your message.", boardText(result.game.fen)] : []),
+            ...(result.agents === undefined ? [] : [agentsLine(result.agents)]),
+            ...closingLines(result.game, result.words),
+        ].join("\n");
+    },
+});
+/** A comment as long as a note, and drawings, only with the helps on (D-78): the player who has them off plays as at a tournament. */
+function refuseWithoutHelps(folder, { comment, arrows, squares }) {
+    const asked = [
+        arrows === undefined && squares === undefined ? "" : "without arrows and squares",
+        comment === undefined || comment.length <= talkLimits.ai ? "" : `with the comment in ${talkLimits.ai} characters at most`,
+    ].filter((part) => part !== "");
+    if (asked.length > 0 && !helpsIn(folder)) {
+        throw new Error(`The player has the helps off: play ${asked.join(", ")}. Nothing changed.`);
+    }
+}
+/**
+ * The agents to start after the move, in Claude Code, in a folder init set up with them: the one that thinks for the AI while the game goes on (D-72), then
+ * the coach with the helps on, which judges the player's move even when the AI's ends the game (D-88).
+ */
+function agentsAfter(context, folder, played) {
+    if (context.host?.() !== "claude-code") {
+        return [];
+    }
+    const ponder = ponderAgentFor(played.game.level);
+    const thinks = played.game.end === undefined && hasAgent(context.folder, ponder);
+    const coaches = helpsIn(folder) && coachRuns(context);
+    return [...(thinks ? [ponder] : []), ...(coaches ? [coachAgent] : [])];
+}

package/dist/commands/ai-say.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { type GameSummary } from "./game-summary.ts";
+interface Said {
+    /** The game, none when the AI spoke before the first (D-77). */
+    game?: GameSummary;
+    words: string[];
+    /** The coach yet to start on the player's move that ended the game (D-88). */
+    coach?: true;
+}
+/** The AI's words on the board page without a move, read only there, on the player's time: an answer, or a word it has to say (D-54, D-72). */
+export declare const aiSay: import("./registry.ts").Command<z.ZodObject<{
+    text: z.ZodString;
+    mood: z.ZodOptional<z.ZodEnum<{
+        neutral: "neutral";
+        happy: "happy";
+        surprised: "surprised";
+        worried: "worried";
+        thoughtful: "thoughtful";
+        sad: "sad";
+    }>>;
+}, z.core.$strip>, Said>;
+export {};