@orlan-maker/cli 0.1.0 → 0.2.0

package/dist/commands.js

@@ -6,11 +6,10 @@ import { createHash } from "node:crypto";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { hostname } from "node:os";
 import path from "node:path";
-import { addMcp, agentIds, agentLabels, CLAUDE_PLUGIN, detectAgent, installClaudePlugin, MCP_NAME, parseAgent, removeMcp, STOP_LOOP_LIMIT, setHooks, setOpencodePlugin, skillsDir, } from "./agents.js";
+import { agentIds, agentLabels, CLAUDE_PLUGIN, detectAgent, installClaudePlugin, orlanIntro, parseAgent, removeMcp, STOP_LOOP_LIMIT, sessionStartOutput, setHooks, setOpencodePlugin, skillsDir, uninstallClaudePlugin, } from "./agents.js";
 import { openBrowser } from "./browser.js";
-import { configDir, DEFAULT_SERVER, readConfig, serverOrigin, writeConfig } from "./config.js";
+import { configDir, readConfig, serverOrigin, writeConfig } from "./config.js";
 import { AgentApi, agentTokenRefused, apiCall, OrlanError, unreachable } from "./http.js";
-import { McpClient } from "./mcp.js";
 import { account, deleteSecret, getSecret, setSecret } from "./secrets.js";
 import { writeSkills } from "./skills.js";
 const agentOption = { agent: { type: "string" } };
@@ -36,6 +35,15 @@ function namedAgent(values) {
  * else the only connected agent.
  */
 async function agentSecret(config, values) {
+    const agent = pickAgent(config, values);
+    const secret = await getSecret(agentAccount(config, agent));
+    if (!secret) {
+        throw new OrlanError(`The token of ${agent} is missing.`, undefined, `orlan connect --agent ${agent}`);
+    }
+    return secret;
+}
+/** The connected agent a daily command works as: see agentSecret. */
+function pickAgent(config, values) {
     const connected = Object.keys(config.agents);
     let agent = typeof values.agent === "string" ? parseAgent(values.agent) : undefined;
     if (!agent) {
@@ -44,19 +52,15 @@ async function agentSecret(config, values) {
     }
     if (!agent) {
         throw connected.length === 0
-            ? new OrlanError("No agent is connected.", undefined, "orlan mcp connect --agent <id>")
+            ? new OrlanError("No agent is connected.", undefined, "orlan connect --agent <id>")
             : new OrlanError(`Several agents are connected (${connected.join(", ")}). Add --agent <id>.`, undefined, `run the command again with --agent ${connected[0]}`);
     }
     if (!config.agents[agent]) {
-        throw new OrlanError(`${agentLabels[agent]} is not connected.`, undefined, `orlan mcp connect --agent ${agent}`);
+        throw new OrlanError(`${agentLabels[agent]} is not connected.`, undefined, `orlan connect --agent ${agent}`);
     }
-    const secret = await getSecret(agentAccount(config, agent));
-    if (!secret) {
-        throw new OrlanError(`The token of ${agent} is missing.`, undefined, `orlan mcp connect --agent ${agent}`);
-    }
-    return secret;
+    return agent;
 }
-/** Runs the work with the stateless agent API of the agent token (F038): no MCP session. */
+/** Runs the work with the stateless agent API of the agent token (F038): one plain HTTP request a call. */
 async function withAgent(values, work) {
     const config = await readConfig();
     return work(new AgentApi(config.server, await agentSecret(config, values)), config);
@@ -77,6 +81,19 @@ function finish(io, values, data, lines, next) {
 }
 /** --topic as input: a topic id or a topic name. It also tells Orlan where to look up a name or #12. */
 const topicInput = (values) => (typeof values.topic === "string" ? { topicId: values.topic } : {});
+/**
+ * The topic of a command that needs one: --topic (an id or a name), else the topic the brief names (the
+ * one the agent used last, else its only topic).
+ */
+async function topicOrDefault(api, values) {
+    if (typeof values.topic === "string")
+        return values.topic;
+    const { topic } = await api.get("/api/agent/brief", {}, "the brief");
+    if (!topic) {
+        throw new OrlanError("The agent has several topics and used none yet. Add --topic <topic>.", "topic_missing");
+    }
+    return topic.id;
+}
 const WAIT_STEP = "orlan wait (the next request)";
 /**
  * A text people wrote, quoted on one line as `orlan wait` quotes it (B029): JSON quotes, with the line
@@ -106,6 +123,17 @@ function versionNumber(values, option) {
     }
     return number;
 }
+/** An option of numbers with commas: --at 300,200, --size 200,120, --region 0.1,0.2,0.3,0.1. */
+function numbersOption(values, option, count) {
+    const raw = values[option];
+    if (typeof raw !== "string")
+        return undefined;
+    const parts = raw.split(",").map((part) => Number(part.trim()));
+    if (parts.length !== count || parts.some((part) => !Number.isFinite(part))) {
+        throw new OrlanError(`--${option} takes ${count} numbers with commas.`, undefined, `run the command again with --${option} ${count === 2 ? "300,200" : "0.1,0.2,0.3,0.1"}`);
+    }
+    return parts;
+}
 const baseOption = (values) => {
     const number = versionNumber(values, "base");
     return number === undefined ? {} : { baseVersion: number };
@@ -299,20 +327,19 @@ async function* sseData(body) {
         }
     }
 }
-/** What `orlan mcp print` shows: the settings any MCP client takes. */
-function mcpSettings(server, secret) {
-    const url = new URL("/mcp", server).toString();
-    return [
-        `MCP server: ${url} (Streamable HTTP)`,
-        `Header:     Authorization: Bearer ${secret}`,
-        "",
-        "As JSON, for an mcp.json file:",
-        JSON.stringify({ mcpServers: { [MCP_NAME]: { url, headers: { Authorization: `Bearer ${secret}` } } } }, null, 2),
-    ];
-}
-/** Makes an agent token for the agent, keeps it, and writes the agent's MCP settings. */
-async function connect(config, agent, values, io) {
+/**
+ * Connects the agent to Orlan with the orlan command (D088): makes an agent token and keeps it, installs
+ * the skills and the agent's plugin or hooks, takes out the Orlan server entry that an older CLI wrote in
+ * the agent's settings, and tests the token with one plain HTTP call.
+ */
+async function connect(agent, values, io) {
+    const config = await readConfig();
     const token = await cliToken(config);
+    // First, before a token or a file is made: an old entry goes also when the plan refuses a new agent, and
+    // a settings file the CLI cannot edit stops the connect before it changes anything.
+    if (agent !== "other" && (await removeMcp(agent))) {
+        io.out("Removed the old Orlan server entry from the agent's settings. The agent uses the orlan command.");
+    }
     const topicIds = values.topic;
     const made = await apiCall(config.server, "/api/cli/agents", {
         token,
@@ -324,22 +351,19 @@ async function connect(config, agent, values, io) {
     const role = made.token.role[0]?.toUpperCase() + made.token.role.slice(1);
     io.out(`Made an agent token for ${agentLabels[agent]}: ${made.token.prefix}..., ${role} on ` +
         `${made.token.topics.map((topic) => quote(topic.name)).join(", ")}. It is in the ${where === "keychain" ? "keychain" : "credentials file"}.`);
+    // The Claude Code plugin carries the skills: a second copy would show each skill twice.
+    let plugin = false;
     if (agent === "claude-code" && !values["no-plugin"]) {
-        if (await installClaudePlugin()) {
-            io.out("Installed the Orlan plugin in Claude Code: the orlan command, a monitor that wakes the session on each " +
-                "request, the hooks that show its state on the board, the skills, and the MCP server.");
-            if (config.server === DEFAULT_SERVER) {
-                // The plugin's MCP server gets the token from the keychain: one entry, never a stale token.
-                await removeMcp(agent);
-                return made.secret;
-            }
-            io.out(`The plugin's MCP server goes to $ORLAN_SERVER, else ${DEFAULT_SERVER}. Set ORLAN_SERVER=${config.server} ` +
-                "where you start Claude Code. Until then, the MCP entry below stays.");
-        }
-        else {
-            io.out(`Claude Code did not install the Orlan plugin (${CLAUDE_PLUGIN}). The MCP server works without it, ` +
-                "but no monitor wakes the session. Run `claude plugin list` to see why.");
-        }
+        plugin = await installClaudePlugin();
+        io.out(plugin
+            ? "Installed the Orlan plugin in Claude Code: the orlan command, the hooks that show the session's state " +
+                "on the board, and the skills."
+            : `Claude Code did not install the Orlan plugin (${CLAUDE_PLUGIN}). The orlan command and the skills work ` +
+                "without it, but the board does not show the session's state. Run `claude plugin list` to see why.");
+    }
+    if (!plugin) {
+        await writeSkills(agent);
+        io.out(`Installed the Orlan skills orlan, orlan-review and orlan-versions in ${skillsDir(agent)}.`);
     }
     if (agent === "codex" || agent === "cursor") {
         io.out(`Added the Orlan hooks to ${await setHooks(agent, true)}: at the session start the brief goes into the ` +
@@ -357,10 +381,62 @@ async function connect(config, agent, values, io) {
         io.out("A request wakes a session only while OpenCode runs (the TUI or opencode serve). Restart a running " +
             "OpenCode to load the plugin.");
     }
-    if (agent !== "other")
-        io.out(`Added the Orlan MCP server to ${await addMcp(agent, new URL("/mcp", config.server).toString(), made.secret)}.`);
-    return made.secret;
+    const { topics } = await new AgentApi(config.server, made.secret).call("inbox", {
+        brief: true,
+    });
+    io.out(`Test: ok. The agent can reach ${topics.map((topic) => quote(topic.name)).join(", ")}.`);
+    io.out(agent === "other"
+        ? "next_step: tell your agent to read the orlan skill in .agents/skills, then run orlan brief"
+        : `next_step: start a new ${agentLabels[agent]} session, then run orlan brief`);
+    return 0;
 }
+/**
+ * Revokes the agent's token, and takes out what a connect installed: the plugin or the hooks, and an
+ * Orlan server entry that an older CLI wrote. The skills stay.
+ */
+async function disconnect(agent, io) {
+    const config = await readConfig();
+    const connected = config.agents[agent];
+    if (connected) {
+        await apiCall(config.server, `/api/cli/agents/${connected.tokenId}`, {
+            token: await cliToken(config),
+            method: "DELETE",
+        }).catch((error) => {
+            if (!(error instanceof OrlanError) || error.code !== "not_found")
+                throw error;
+        });
+    }
+    const removed = agent !== "other" && (await removeMcp(agent));
+    if (agent === "claude-code")
+        await uninstallClaudePlugin();
+    if (agent === "codex" || agent === "cursor")
+        await setHooks(agent, false);
+    if (agent === "opencode")
+        await setOpencodePlugin(false);
+    await deleteSecret(agentAccount(config, agent));
+    delete config.agents[agent];
+    await writeConfig(config);
+    const parts = { "claude-code": "plugin", codex: "hooks", cursor: "hooks", opencode: "plugin", other: "" }[agent];
+    io.out(`Disconnected ${agentLabels[agent]}: its token is revoked` +
+        `${parts ? `, and its Orlan ${parts} ${removed ? "and the old Orlan server entry are" : "is"} gone` : ""}. The skills stay.`);
+    io.out(`next_step: orlan connect --agent ${agent} (to connect it again)`);
+    return 0;
+}
+/** The agent that connect and disconnect are for: --agent, else the agent that runs the command. */
+function agentToConnect(values) {
+    const agent = namedAgent(values);
+    if (!agent)
+        throw new OrlanError(`Add --agent <id>: ${agentIds.join(", ")}.`);
+    return agent;
+}
+/** The notice of an old command name, on standard error: the output stays what the new name prints. */
+const oldName = (text) => process.stderr.write(`orlan: ${text}\n`);
+const CONNECT_OPTIONS = {
+    ...agentOption,
+    topic: { type: "string", multiple: true },
+    role: { type: "string" },
+    "no-plugin": { type: "boolean" },
+};
 // ---------- the commands ----------
 export const commands = {
     "auth login": {
@@ -402,7 +478,7 @@ export const commands = {
                     await writeConfig(next);
                     io.out(`Signed in to ${server} as ${quote(signed.user.name)} (${signed.user.email ?? "guest account"}), organisation ${quote(signed.org.name)}.`);
                     io.out(where === "keychain" ? "The CLI token is in the OS keychain." : "The CLI token is in the credentials file.");
-                    io.out("next_step: orlan mcp connect --agent <id>");
+                    io.out("next_step: orlan connect --agent <id>");
                     return 0;
                 }
                 catch (error) {
@@ -418,7 +494,7 @@ export const commands = {
         usage: "orlan auth logout",
         summary: "Revoke the CLI token and forget it.",
         details: [
-            "The agents you connected keep their own tokens. Revoke them with `orlan mcp disconnect`,",
+            "The agents you connected keep their own tokens. Revoke them with `orlan disconnect`,",
             "or in Agents and tokens in the web app.",
         ],
         options: {},
@@ -442,9 +518,9 @@ export const commands = {
     },
     status: {
         usage: "orlan status [--json]",
-        summary: "Show who you are, the server, and the connected agents, and test each agent's MCP connection.",
+        summary: "Show who you are, the server, and the connected agents, and test each agent's connection.",
         details: [
-            "Each connected agent makes one MCP call (inbox brief) with its own token, so a failed",
+            "Each connected agent makes one plain HTTP call (the inbox brief) with its own token, so a failed",
             "connection shows here with its reason. Ends with exit code 1 when a check fails.",
             "",
             JSON_HELP,
@@ -466,19 +542,16 @@ export const commands = {
                 const secret = await getSecret(agentAccount(config, agent));
                 let check;
                 if (!live || !secret) {
-                    check = { ok: false, error: "its token was revoked or replaced. Run `orlan mcp connect` again." };
+                    check = { ok: false, error: "its token was revoked or replaced. Run `orlan connect` again." };
                 }
                 else {
-                    const client = new McpClient(config.server, secret, io.version);
                     try {
-                        check = { ok: true, topics: (await client.call("inbox", { brief: true })).topics };
+                        const api = new AgentApi(config.server, secret);
+                        check = { ok: true, topics: (await api.call("inbox", { brief: true })).topics };
                     }
                     catch (error) {
                         check = { ok: false, error: error.message };
                     }
-                    finally {
-                        await client.close();
-                    }
                 }
                 if (!check.ok)
                     failed = true;
@@ -486,9 +559,9 @@ export const commands = {
             }
             const elsewhere = status.agents.filter((each) => !Object.values(config.agents).some((local) => local.tokenId === each.id));
             const next = agents.length === 0
-                ? "orlan mcp connect --agent <id>"
+                ? "orlan connect --agent <id>"
                 : failed
-                    ? "orlan mcp connect --agent <id> for each failed agent"
+                    ? "orlan connect --agent <id> for each failed agent"
                     : "orlan brief (where the work stands)";
             if (values.json) {
                 printJson(io, {
@@ -510,12 +583,12 @@ export const commands = {
             for (const { agent, token: local, role, check } of agents) {
                 io.out(`${agentLabels[agent]} (${agent}): token ${local?.prefix}..., ${role ?? "revoked"}`);
                 if (check.ok) {
-                    io.out("  MCP: ok. Topics it can reach:");
+                    io.out("  Connection: ok. Topics it can reach:");
                     for (const topic of check.topics)
                         io.out(`  - ${quote(topic.name)} (${topic.id})`);
                 }
                 else {
-                    io.out(`  MCP: failed - ${check.error}`);
+                    io.out(`  Connection: failed - ${check.error}`);
                 }
             }
             for (const each of elsewhere)
@@ -528,8 +601,9 @@ export const commands = {
         usage: "orlan skills add [--agent <id>]",
         summary: "Install the Orlan skills where the agent reads skills.",
         details: [
-            "Writes the skills orlan-review and orlan-versions. Without --agent, the CLI finds the agent that",
-            "runs it; when it finds none, it writes them in this project, in .agents/skills.",
+            "Writes the skills orlan, orlan-review and orlan-versions. Without --agent, the CLI finds the agent that",
+            "runs it; when it finds none, it writes them in this project, in .agents/skills. `orlan connect` does",
+            "this too.",
             "",
             `  claude-code  ${skillsDir("claude-code")}`,
             `  codex        ${skillsDir("codex")}`,
@@ -547,24 +621,22 @@ export const commands = {
             io.out(`Installed the Orlan skills for ${agentLabels[agent]}:`);
             for (const folder of written)
                 io.out(`  ${folder}`);
-            io.out(`next_step: orlan mcp connect --agent ${agent === "other" ? "<id>" : agent}`);
+            io.out(`next_step: orlan connect --agent ${agent === "other" ? "<id>" : agent}`);
             return 0;
         },
     },
-    "mcp connect": {
-        usage: "orlan mcp connect [--agent <id>] [--topic <topic id>]... [--role editor|commenter|viewer] [--no-plugin]",
-        summary: "Make an agent token and add the Orlan MCP server to the agent.",
+    connect: {
+        usage: "orlan connect [--agent <id>] [--topic <topic id>]... [--role editor|commenter|viewer] [--no-plugin]",
+        summary: "Connect an agent to Orlan: an agent token, the skills, and the plugin or the hooks.",
         details: [
-            "Makes an agent token with your CLI token, keeps it in the keychain, and writes the MCP entry:",
-            "Claude Code with `claude mcp add --scope user`, Codex in its config.toml, Cursor in",
-            "~/.cursor/mcp.json, OpenCode in its opencode.json. For --agent other it prints the settings.",
-            "A second connect for the same agent replaces its token. Then it makes one MCP call to test it.",
+            "Makes an agent token with your CLI token and keeps it in the keychain. The agent then works on",
+            "Orlan with the orlan command. It installs the skills (as `orlan skills add` does), and removes the",
+            "Orlan server entry that an older CLI wrote. Every other entry in the agent's settings stays. A second",
+            "connect for the same agent replaces its token. Then it makes one plain HTTP call to test the token.",
             "Only an admin of the organisation connects agents.",
             "",
             `For Claude Code it installs the Orlan plugin (${CLAUDE_PLUGIN}) from this package: the orlan command,`,
-            "a monitor that runs `orlan wait --follow` and wakes the session on each request, the hooks that",
-            "show the session's state on the board, the skills, and the MCP server. Then the MCP entry is not",
-            "needed. On a server other than https://orlan.app, the entry stays until you set ORLAN_SERVER.",
+            "the hooks that show the session's state on the board, and the skills.",
             "",
             "For Codex ($CODEX_HOME/hooks.json) and Cursor (~/.cursor/hooks.json) it writes the Orlan hooks: the",
             "session start gets the brief (`orlan hook start`), a turn that ends gets a waiting request",
@@ -575,125 +647,61 @@ export const commands = {
             "turn ends, it runs `orlan hook wait` and sends the request to the session as a new prompt, so the",
             "session wakes while OpenCode runs. The board shows the session's state.",
             "",
+            "For other it writes the skills in this project, in .agents/skills.",
+            "",
             AGENT_HELP,
             "--topic <id>   A topic the agent can use. Repeat it for more. Default: the topics you chose at sign-in.",
             "--role <role>  editor, commenter or viewer. Default: the role you chose at sign-in.",
-            "--no-plugin    Claude Code: add only the MCP entry, not the plugin.",
+            "--no-plugin    Claude Code: do not install the plugin. Write the skills to ~/.claude/skills.",
         ],
-        options: {
-            ...agentOption,
-            topic: { type: "string", multiple: true },
-            role: { type: "string" },
-            "no-plugin": { type: "boolean" },
-        },
+        options: CONNECT_OPTIONS,
         positionals: [0, 0],
-        run: async (values, _positionals, io) => {
-            const agent = namedAgent(values);
-            if (!agent)
-                throw new OrlanError(`Add --agent <id>: ${agentIds.join(", ")}.`);
-            const config = await readConfig();
-            const secret = await connect(config, agent, values, io);
-            const client = new McpClient(config.server, secret, io.version);
-            try {
-                const { topics } = await client.call("inbox", { brief: true });
-                io.out(`MCP test: ok. The agent can reach ${topics.map((topic) => quote(topic.name)).join(", ")}.`);
-            }
-            finally {
-                await client.close();
-            }
-            if (agent === "other") {
-                for (const line of mcpSettings(config.server, secret))
-                    io.out(line);
-                io.out("next_step: put the address and the header in your agent's MCP settings, then run orlan brief");
-            }
-            else {
-                io.out(`next_step: start a new ${agentLabels[agent]} session to load the Orlan MCP tools, then run orlan brief`);
-            }
-            return 0;
-        },
+        run: (values, _positionals, io) => connect(agentToConnect(values), values, io),
     },
-    "mcp print": {
-        usage: "orlan mcp print [--agent <id>]",
-        summary: "Print the MCP server address and the agent token, for an agent the CLI does not set up.",
-        details: [
-            "Uses the token of the agent (default: other). When that agent is not connected yet, it",
-            "connects it first. Put the address and the header in your agent's MCP settings.",
-            "The token is a secret: keep it out of chats, files you share, and repositories.",
-            "",
-            AGENT_HELP,
-        ],
+    disconnect: {
+        usage: "orlan disconnect [--agent <id>]",
+        summary: "Revoke the agent's token, and take out its Orlan plugin or hooks and any old Orlan server entry.",
+        details: ["The skills stay. `orlan connect` connects the agent again.", "", AGENT_HELP],
         options: agentOption,
         positionals: [0, 0],
-        run: async (values, _positionals, io) => {
-            const agent = typeof values.agent === "string" ? parseAgent(values.agent) : "other";
-            const config = await readConfig();
-            let secret = config.agents[agent] ? await getSecret(agentAccount(config, agent)) : undefined;
-            if (!secret)
-                secret = await connect(config, agent, values, io);
-            for (const line of mcpSettings(config.server, secret))
-                io.out(line);
-            io.out("next_step: put the address and the header in your agent's MCP settings");
-            return 0;
+        run: (values, _positionals, io) => disconnect(agentToConnect(values), io),
+    },
+    "mcp connect": {
+        usage: "orlan mcp connect [--agent <id>] [--topic <topic id>]... [--role editor|commenter|viewer] [--no-plugin]",
+        summary: "The old name of orlan connect. Use orlan connect: this name goes away in the next release.",
+        details: ["It does what `orlan connect` does. Orlan has no MCP entry for the agent now (D088)."],
+        options: CONNECT_OPTIONS,
+        positionals: [0, 0],
+        run: (values, _positionals, io) => {
+            oldName("Use orlan connect: orlan mcp connect goes away in the next release.");
+            return connect(agentToConnect(values), values, io);
         },
     },
-    "mcp headers": {
-        usage: "orlan mcp headers [--agent <id>]",
-        summary: "Print the MCP authorization header as JSON, for a headersHelper. The Claude Code plugin runs it.",
+    "mcp print": {
+        usage: "orlan mcp print [--agent <id>]",
+        summary: "The old way to connect another agent. Use orlan connect: this name goes away in the next release.",
         details: [
-            'Prints {"Authorization": "Bearer <agent token>"} with the token from the keychain, so the MCP',
-            "settings hold no secret and a new connect needs no new settings. When Claude Code gives the MCP",
-            "address (CLAUDE_CODE_MCP_SERVER_URL) and it is not the server you signed in to, it prints nothing",
-            "and exits with code 1.",
+            "Orlan has no MCP settings to print now (D088). It does what `orlan connect` does, for the agent",
+            "--agent names, else other: the token, and the skills in this project, in .agents/skills.",
             "",
-            AGENT_TOKEN_HELP,
+            AGENT_HELP,
         ],
         options: agentOption,
         positionals: [0, 0],
-        run: async (values, _positionals, io) => {
-            const config = await readConfig();
-            const asked = process.env.CLAUDE_CODE_MCP_SERVER_URL;
-            if (asked && serverOrigin(asked) !== config.server) {
-                throw new OrlanError(`The MCP server is ${serverOrigin(asked)}, but you signed in to ${config.server}. ` +
-                    `Set ORLAN_SERVER=${config.server} where you start Claude Code.`);
-            }
-            io.out(JSON.stringify({ Authorization: `Bearer ${await agentSecret(config, values)}` }));
-            return 0;
+        run: (values, _positionals, io) => {
+            oldName("Use orlan connect: orlan mcp print goes away in the next release.");
+            return connect(typeof values.agent === "string" ? parseAgent(values.agent) : "other", values, io);
         },
     },
     "mcp disconnect": {
         usage: "orlan mcp disconnect [--agent <id>]",
-        summary: "Revoke the agent's token and take the Orlan MCP server out of its settings.",
-        details: [AGENT_HELP],
+        summary: "The old name of orlan disconnect. Use orlan disconnect: this name goes away in the next release.",
+        details: ["It does what `orlan disconnect` does.", "", AGENT_HELP],
         options: agentOption,
         positionals: [0, 0],
-        run: async (values, _positionals, io) => {
-            const agent = namedAgent(values);
-            if (!agent)
-                throw new OrlanError(`Add --agent <id>: ${agentIds.join(", ")}.`);
-            const config = await readConfig();
-            const connected = config.agents[agent];
-            if (connected) {
-                await apiCall(config.server, `/api/cli/agents/${connected.tokenId}`, {
-                    token: await cliToken(config),
-                    method: "DELETE",
-                }).catch((error) => {
-                    if (!(error instanceof OrlanError) || error.code !== "not_found")
-                        throw error;
-                });
-            }
-            if (agent !== "other")
-                await removeMcp(agent);
-            if (agent === "codex" || agent === "cursor")
-                await setHooks(agent, false);
-            if (agent === "opencode")
-                await setOpencodePlugin(false);
-            await deleteSecret(agentAccount(config, agent));
-            delete config.agents[agent];
-            await writeConfig(config);
-            io.out(`Disconnected ${agentLabels[agent]}: its token is revoked and its Orlan MCP entry` +
-                `${agent === "codex" || agent === "cursor" ? " and hooks are" : agent === "opencode" ? " and plugin are" : " is"} gone.`);
-            io.out(`next_step: orlan mcp connect --agent ${agent} (to connect it again)`);
-            return 0;
+        run: (values, _positionals, io) => {
+            oldName("Use orlan disconnect: orlan mcp disconnect goes away in the next release.");
+            return disconnect(agentToConnect(values), io);
         },
     },
     "topics list": {
@@ -716,38 +724,59 @@ export const commands = {
         }),
     },
     "files list": {
-        usage: "orlan files list --topic <topic> [--agent <id>] [--json]",
+        usage: "orlan files list [--topic <topic>] [--agent <id>] [--json]",
         summary: "List the files of a topic with their current versions.",
-        details: ["--topic <topic>  The topic id or its name.", AGENT_TOKEN_HELP, JSON_HELP],
+        details: [
+            "--topic <topic>  The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
         options: { ...agentOption, ...jsonOption, topic: { type: "string" } },
         positionals: [0, 0],
         run: (values, _positionals, io) => withAgent(values, async (api) => {
-            if (typeof values.topic !== "string") {
-                throw new OrlanError("Add --topic <topic>.", undefined, "orlan topics list (the topics of the agent)");
-            }
-            const { files } = await api.call("read_board", { ...topicInput(values), view: "files" });
+            const topicId = await topicOrDefault(api, values);
+            const { files } = await api.call("read_board", { topicId, view: "files" });
             return finish(io, values, { files }, files.length === 0
                 ? ["No files."]
                 : files.map((file) => `${file.id}  ${quote(file.name)}  ${file.kind}  current v${file.current.number} (${file.current.status}), ` +
-                    `${file.versions} version${file.versions === 1 ? "" : "s"}`), files.length === 0
+                    `${file.versions} version${file.versions === 1 ? "" : "s"}` +
+                    (file.current.changed
+                        ? `, ${changedText(file.current.changed.pages)} from v${file.current.changed.from}`
+                        : "")), files.length === 0
                 ? "orlan files add <path> (a new file)"
                 : "orlan files pull <file> --edit --out <path> (the file id or its name)");
         }),
     },
     "files add": {
-        usage: "orlan files add <path> [--topic <topic>] [--agent <id>] [--json]",
+        usage: "orlan files add <path> [--at <x,y>] [--topic <topic>] [--agent <id>] [--json]",
         summary: "Post a local file as a new file on a topic, and put it on the board.",
         details: [
             "One request sends the file and places it on the board, right of the other items. The server",
             "renders its pages. A PowerPoint, PDF, PNG, JPG or HTML file, with the right extension.",
             "",
+            "--at <x,y>       Put it at this point of the board, in board coordinates, or at the nearest free",
+            "                 place. `orlan board` shows where the items are.",
             "--topic <topic>  The topic id or its name. Default: the topic the agent used last, else its only topic.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
-        options: { ...agentOption, ...jsonOption, topic: { type: "string" } },
+        options: { ...agentOption, ...jsonOption, topic: { type: "string" }, at: { type: "string" } },
         positionals: [1, 1],
         run: (values, [filePath], io) => withAgent(values, async (api) => {
+            const at = numbersOption(values, "at", 2);
+            if (at) {
+                // A place on the board: the file goes up first, then the post places it.
+                const topicId = await topicOrDefault(api, values);
+                const uploadId = await api.upload(await readFile(filePath), { topic: topicId });
+                const posted = await api.call("post", { topicId, name: path.basename(filePath), uploadId, position: { x: at[0], y: at[1] } });
+                return finish(io, values, {
+                    file: { id: posted.file.id, name: posted.file.name, version: posted.posted.number },
+                    boardItemId: posted.boardItemId,
+                }, [
+                    `Added ${quote(posted.file.name)} as file ${posted.file.id}, v${posted.posted.number}. It is on the ` +
+                        `board at ${at.join(",")}, or at the nearest free place; its pages render now.`,
+                ], "orlan wait (comments on the file come as requests)");
+            }
             const { nextStep, ...answer } = await api.postFile("/api/agent/files", { name: path.basename(filePath), topic: values.topic }, await readFile(filePath), "the new file");
             return finish(io, values, answer, [
                 `Added ${quote(answer.file.name)} to topic ${quote(answer.topic.name)} as file ` +
@@ -756,13 +785,20 @@ export const commands = {
         }),
     },
     "files pull": {
-        usage: "orlan files pull <file> [--version <n>] [--topic <topic>] [--out <path>] [--edit [--shared] [--ttl <time>]] [--agent <id>] [--json]",
-        summary: "Download a version of a file (the current one by default).",
+        usage: "orlan files pull <file> [--version <n>] [--pages <n,n> | --since <n>] [--topic <topic>] [--out <path>] [--edit [--shared] [--ttl <time>]] [--agent <id>] [--json]",
+        summary: "Download a version of a file (the current one by default), or images and text of its pages.",
         details: [
+            "With --pages or --since it gets pages, not the file: it saves the image of each page in the",
+            "--out folder as <name>-page-<n>.png, and prints the text of each page.",
+            "",
             "<file>         The file id, or its name where it is unique on the topic.",
             "--version <n>  A version number, for example 5 or v5. Default: the current version.",
+            "--pages <n,n>  The pages to get, from 1, for example 3 or 2,5.",
+            "--since <n>    The pages that changed since this older version, for example 4 or v4. With",
+            "               --pages, only those of the pages that changed.",
             "--topic <t>    The topic of a file name, when two topics have a file with that name.",
-            "--out <path>   Where to write it. Default: the file's own name, in the folder you are in.",
+            "--out <path>   Where to write it. Default: the file's own name, in the folder you are in. With",
+            "               --pages or --since: the folder of the page images. Default: the folder you are in.",
             "--edit         You pull it to edit it: this puts your claim on the file, which other agents and",
             "               people see. When another agent has a claim, you get it and no claim of your own.",
             "               A push or respond ends your claim, and it takes the pulled version as its base.",
@@ -775,6 +811,8 @@ export const commands = {
             ...agentOption,
             ...jsonOption,
             version: { type: "string" },
+            pages: { type: "string" },
+            since: { type: "string" },
             topic: { type: "string" },
             out: { type: "string" },
             edit: { type: "boolean" },
@@ -787,12 +825,17 @@ export const commands = {
                 throw new OrlanError("--shared and --ttl go with --edit.", undefined, "add --edit, or leave them out");
             }
             const version = versionNumber(values, "version");
-            // One call: the file, the version (v5), and the claim. Orlan finds a file by its name too.
+            const since = versionNumber(values, "since");
+            const pages = pageList(values);
+            const pageMode = pages !== undefined || since !== undefined;
+            // One call: the file, the version (v5), the pages, and the claim. Orlan finds a file by its name too.
             const answer = await api.call("get_file", {
                 artifactId: fileRef,
                 ...topicInput(values),
                 ...(version ? { versionId: `v${version}` } : {}),
-                pageImages: "none",
+                ...(pages ? { pages } : {}),
+                ...(since !== undefined ? { changedSince: since } : {}),
+                pageImages: pageMode ? "url" : "none",
                 ...(values.edit
                     ? {
                         edit: true,
@@ -801,6 +844,8 @@ export const commands = {
                     }
                     : {}),
             });
+            if (pageMode)
+                return pullPages(api, config, values, io, answer, since);
             const url = answer.originalUrl ?? answer.viewUrl;
             if (!url)
                 throw new OrlanError("Orlan gave no address for this file.", undefined, "run the command again");
@@ -815,15 +860,10 @@ export const commands = {
             }
             const target = typeof values.out === "string" ? values.out : path.basename(answer.file.name);
             await writeFile(target, Buffer.from(await response.arrayBuffer()));
-            const lines = [`Saved version ${answer.version.number} of ${quote(answer.file.name)} to ${quote(target)}.`];
-            if (answer.claim) {
-                lines.push(`Your${answer.claim.shared ? " shared" : ""} claim is on the file from v${answer.claim.baseVersion}.`);
-            }
-            for (const other of answer.claims ?? []) {
-                const minutes = Math.floor((Date.now() - new Date(other.since).getTime()) / 60_000);
-                lines.push(`${quote(other.agent)} is editing it from v${other.baseVersion}${other.shared ? " (shared claim)" : ""} - ` +
-                    `${minutes < 1 ? "under 1 min" : `${minutes} min`}.`);
-            }
+            const lines = [
+                `Saved version ${answer.version.number} of ${quote(answer.file.name)} to ${quote(target)}.`,
+                ...claimLines(answer),
+            ];
             return finish(io, values, {
                 file: { id: answer.file.id, name: answer.file.name },
                 version: answer.version.number,
@@ -879,6 +919,44 @@ export const commands = {
             ], "orlan wait (comments on the version come as requests)");
         }),
     },
+    "files rollback": {
+        usage: 'orlan files rollback <file> --version <n> [--changelog "<why>"] [--topic <topic>] [--agent <id>] [--json]',
+        summary: "Post an older version of a file again, as its newest version.",
+        details: [
+            "The new version is a copy of the older one. It waits for a person to make it current, as a push does.",
+            "",
+            "<file>              The file id, or its name where it is unique on the topic.",
+            "--version <n>       The older version to post again, for example 3 or v3. Required.",
+            "--changelog <text>  Why, for the people who review it.",
+            "--topic <topic>     The topic of a file name, when two topics have a file with that name.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: {
+            ...agentOption,
+            ...jsonOption,
+            version: { type: "string" },
+            changelog: { type: "string" },
+            topic: { type: "string" },
+        },
+        positionals: [1, 1],
+        run: (values, [fileRef], io) => withAgent(values, async (api) => {
+            const version = versionNumber(values, "version");
+            if (!version) {
+                throw new OrlanError("Add --version <n>.", undefined, "orlan files list shows the versions");
+            }
+            const posted = await api.call("post", {
+                artifactId: fileRef,
+                ...topicInput(values),
+                versionId: `v${version}`,
+                ...(typeof values.changelog === "string" ? { changelog: values.changelog } : {}),
+            });
+            return finish(io, values, { file: { id: posted.file.id, name: posted.file.name }, version: posted.posted.number, copyOf: version }, [
+                `Posted version ${posted.posted.number} of ${quote(posted.file.name)}, a copy of v${version}. ` +
+                    "It waits for a person to make it current.",
+            ], "orlan wait (comments on the version come as requests)");
+        }),
+    },
     "comments list": {
         usage: "orlan comments list [--topic <topic>] [--status open|resolved|all] [--file <file>] [--json]",
         summary: "List the comment threads, newest first.",
@@ -979,16 +1057,7 @@ export const commands = {
         },
         positionals: [1, 2],
         run: (values, positionals, io) => {
-            const numbers = (option, count) => {
-                const raw = values[option];
-                if (typeof raw !== "string")
-                    return undefined;
-                const parts = raw.split(",").map((part) => Number(part.trim()));
-                if (parts.length !== count || parts.some((part) => !Number.isFinite(part))) {
-                    throw new OrlanError(`--${option} takes ${count} numbers with commas.`, undefined, `run the command again with --${option} ${count === 2 ? "300,200" : "0.1,0.2,0.3,0.1"}`);
-                }
-                return parts;
-            };
+            const numbers = (option, count) => numbersOption(values, option, count);
             const [first, second] = positionals;
             const body = (second ?? first);
             const usage = "orlan comment --help (the three forms)";
@@ -1057,13 +1126,399 @@ export const commands = {
             return finish(io, values, { id: thread.thread, number: thread.number, status: "resolved" }, [`Resolved #${thread.number}.`], WAIT_STEP);
         }),
     },
+    board: {
+        usage: "orlan board [--topic <topic>] [--agent <id>] [--json]",
+        summary: "Print the board: its items with their ids and places, the timer, the votes and the open tasks.",
+        details: [
+            "Each item is one line: its id, its type, its place (x,y) and size (w x h) in board coordinates, and",
+            "its text. A file shows its name and pages, an arrow the items it links. People vote; an agent reads",
+            "the vote and its result, it does not vote.",
+            "",
+            "--topic <topic>  The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: { ...agentOption, ...jsonOption, topic: { type: "string" } },
+        positionals: [0, 0],
+        run: (values, _positionals, io) => withAgent(values, async (api) => {
+            const topicId = await topicOrDefault(api, values);
+            // Two requests at the same time: the board, and the names of its files.
+            const [board, { files }] = await Promise.all([
+                api.call("read_board", { topicId, view: "board" }),
+                api.call("read_board", { topicId, view: "files" }),
+            ]);
+            const names = new Map(files.map((file) => [file.id, file.name]));
+            const items = board.items.map((item) => item.type === "file" ? { ...item, name: names.get(item.artifactId ?? "") ?? "" } : item);
+            const { timer, vote, lastVote, tasks = [] } = board.session ?? {};
+            const lines = [
+                `Board of ${quote(board.topic.name)} (${board.topic.id}): ${items.length} item${items.length === 1 ? "" : "s"}.`,
+            ];
+            if (items.some((item) => item.text) || vote || tasks.length > 0)
+                lines.push(QUOTED_TEXT);
+            const round = (value) => Math.round(value);
+            for (const item of items) {
+                const place = `at ${round(item.x)},${round(item.y)}, ${round(item.w)}x${round(item.h)}`;
+                const end = (id, x, y) => id ?? `${round(x)},${round(y)}`;
+                lines.push(item.type === "arrow"
+                    ? `- ${item.id} arrow from ${end(item.from, item.x, item.y)} to ${end(item.to, item.x + item.w, item.y + item.h)}`
+                    : item.type === "file"
+                        ? `- ${item.id} file ${quote(item.name ?? "")} (${item.artifactId}) ${place}, ` +
+                            `${item.pages?.length ?? 0} page${item.pages?.length === 1 ? "" : "s"}`
+                        : `- ${item.id} ${item.type} ${place}${item.text === undefined ? "" : `: ${quote(item.text)}`}`);
+            }
+            if (timer) {
+                lines.push(`timer: ${timer.left}s left of ${timer.of}s${timer.paused ? ", paused" : ""}, by ${quote(timer.by)}` +
+                    (timer.for ? `, for ${quote(timer.for)}` : ""));
+            }
+            if (vote)
+                lines.push(`open vote: ${voteText(vote)} (people vote, you do not)`);
+            if (lastVote)
+                lines.push(`last vote: ${voteText(lastVote)}`);
+            lines.push(`open tasks: ${tasks.length === 0 ? "none" : tasks.length}`);
+            for (const task of tasks) {
+                lines.push(`- ${task.id} ${quote(task.text)}${task.to ? ` for ${quote(task.to)}` : ""}` +
+                    (task.thread !== undefined ? ` from #${task.thread}` : ""));
+            }
+            return finish(io, values, { topic: board.topic, items, ...(board.session ? { session: board.session } : {}) }, lines, 'orlan board add note "<text>" --at <x,y> (a note), orlan board change <item>, or orlan board delete <item>');
+        }),
+    },
+    "board add": {
+        usage: 'orlan board add note|text|frame ["<text>"] --at <x,y> [--size <w,h>] | arrow --from <item> --to <item> [--topic <topic>] [--agent <id>] [--json]',
+        summary: "Add a note, a text, a frame or an arrow to the board.",
+        details: [
+            "A note, a text or a frame goes at --at, with its text (a frame's text is its title). An arrow",
+            "links two items: --from and --to take their ids, from `orlan board`. People see it at once, and",
+            "a person can undo it. To add several items in one step, use `orlan board edit`.",
+            "",
+            "--at <x,y>        The top left corner, in board coordinates. A negative x goes with =: --at=-50,120.",
+            "--size <w,h>      The width and the height. Default: the size a person gets.",
+            "--from <item>     The item the arrow starts at.",
+            "--to <item>       The item the arrow points to.",
+            "--topic <topic>   The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: {
+            ...agentOption,
+            ...jsonOption,
+            at: { type: "string" },
+            size: { type: "string" },
+            from: { type: "string" },
+            to: { type: "string" },
+            topic: { type: "string" },
+        },
+        positionals: [1, 2],
+        run: (values, [type, text], io) => {
+            const usage = "orlan board add --help";
+            let edit;
+            if (type === "arrow") {
+                if (typeof values.from !== "string" || typeof values.to !== "string") {
+                    throw new OrlanError("An arrow needs --from <item> and --to <item>.", undefined, "orlan board (the item ids)");
+                }
+                if (text !== undefined)
+                    throw new OrlanError("An arrow has no text.", undefined, usage);
+                edit = { op: "create", type, from: values.from, to: values.to };
+            }
+            else if (type === "note" || type === "text" || type === "frame") {
+                const at = numbersOption(values, "at", 2);
+                if (!at)
+                    throw new OrlanError(`A ${type} needs --at <x,y>.`, undefined, "orlan board (where the items are)");
+                const size = numbersOption(values, "size", 2);
+                edit = {
+                    op: "create",
+                    type,
+                    x: at[0],
+                    y: at[1],
+                    ...(size ? { w: size[0], h: size[1] } : {}),
+                    ...(text !== undefined ? { text } : {}),
+                };
+            }
+            else {
+                throw new OrlanError("The item is a note, a text, a frame or an arrow.", undefined, usage);
+            }
+            return withAgent(values, async (api) => {
+                const { ids } = await editBoard(api, values, [edit]);
+                const where = type === "arrow" ? `from ${values.from} to ${values.to}` : `at ${edit.x},${edit.y}`;
+                return finish(io, values, { id: ids[0], type }, [`Added ${type} ${ids[0]} ${where}.`], type === "arrow"
+                    ? "orlan board (the board with the arrow)"
+                    : `orlan board add arrow --from ${ids[0]} --to <item> (to link it), or orlan board`);
+            });
+        },
+    },
+    "board change": {
+        usage: 'orlan board change <item> [--text "<text>"] [--at <x,y>] [--size <w,h>] [--from <item>|none] [--to <item>|none] [--topic <topic>] [--agent <id>] [--json]',
+        summary: "Change an item of the board: its text, place, size, or the ends of an arrow.",
+        details: [
+            "The changes are one step, which a person can undo. A file on the board only moves (--at).",
+            "",
+            "<item>            The item id, from `orlan board`.",
+            "--text <text>     The new text of a note or a text, or the title of a frame.",
+            "--at <x,y>        Move the item: its new top left corner, in board coordinates. A negative x goes",
+            "                  with =: --at=-50,120.",
+            "--size <w,h>      The new width and height.",
+            "--from <item>     The item the arrow starts at. none: the end stays where it is, on no item.",
+            "--to <item>       The item the arrow points to. none: the end stays where it is, on no item.",
+            "--topic <topic>   The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: {
+            ...agentOption,
+            ...jsonOption,
+            text: { type: "string" },
+            at: { type: "string" },
+            size: { type: "string" },
+            from: { type: "string" },
+            to: { type: "string" },
+            topic: { type: "string" },
+        },
+        positionals: [1, 1],
+        run: (values, [id], io) => {
+            const at = numbersOption(values, "at", 2);
+            const size = numbersOption(values, "size", 2);
+            const end = (option) => {
+                const value = values[option];
+                if (typeof value !== "string")
+                    return {};
+                return { [option]: value === "none" ? null : value };
+            };
+            const update = {
+                ...(typeof values.text === "string" ? { text: values.text } : {}),
+                ...(size ? { w: size[0], h: size[1] } : {}),
+                ...end("from"),
+                ...end("to"),
+            };
+            const edits = [
+                ...(at ? [{ op: "move", id, x: at[0], y: at[1] }] : []),
+                ...(Object.keys(update).length > 0 ? [{ op: "update", id, ...update }] : []),
+            ];
+            if (edits.length === 0) {
+                throw new OrlanError("Give --text, --at, --size, --from or --to.", undefined, `orlan board change ${id} --text "<text>"`);
+            }
+            return withAgent(values, async (api) => {
+                await editBoard(api, values, edits);
+                return finish(io, values, { id }, [`Changed ${id}.`], "orlan board (the board with the change)");
+            });
+        },
+    },
+    "board delete": {
+        usage: "orlan board delete <item>... [--topic <topic>] [--agent <id>] [--json]",
+        summary: "Delete items from the board: notes, texts, frames and arrows.",
+        details: [
+            "One step for all the items, which a person can undo. A file on the board is not deleted here: a",
+            "person does that.",
+            "",
+            "<item>           The item id, from `orlan board`. Give several to delete several.",
+            "--topic <topic>  The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: { ...agentOption, ...jsonOption, topic: { type: "string" } },
+        positionals: [1, 100],
+        run: (values, ids, io) => withAgent(values, async (api) => {
+            await editBoard(api, values, ids.map((id) => ({ op: "delete", id })));
+            return finish(io, values, { deleted: ids }, [`Deleted ${ids.length === 1 ? "1 item" : `${ids.length} items`}: ${ids.join(", ")}. A person can undo it.`], "orlan board (the board now)");
+        }),
+    },
+    "board edit": {
+        usage: "orlan board edit '<edits as JSON>' [--topic <topic>] [--agent <id>] [--json]",
+        summary: "Make several changes to the board in one step: all of them, or none.",
+        details: [
+            'The edits are a JSON list of at most 100. A person can undo the step. "#n" is the item that edit n',
+            "(from 0) made, so one step can add two notes and the arrow between them:",
+            '  [{"op":"create","type":"note","x":0,"y":0,"text":"Web"},',
+            '   {"op":"create","type":"note","x":400,"y":0,"text":"API"},',
+            '   {"op":"create","type":"arrow","from":"#0","to":"#1"}]',
+            "",
+            "create  type note, text or frame with x, y and text (and w, h); type arrow with from and to.",
+            "move    id, x, y.",
+            "update  id, and text, w, h, or from and to (null: on no item).",
+            "delete  id. A file on the board only moves.",
+            "",
+            "--topic <topic>  The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: { ...agentOption, ...jsonOption, topic: { type: "string" } },
+        positionals: [1, 1],
+        run: (values, [text], io) => {
+            let edits;
+            try {
+                edits = JSON.parse(text);
+            }
+            catch {
+                edits = undefined;
+            }
+            if (!Array.isArray(edits) || edits.length === 0) {
+                throw new OrlanError('The edits are a JSON list, for example [{"op":"delete","id":"<item>"}].', undefined, "orlan board edit --help");
+            }
+            return withAgent(values, async (api) => {
+                const { ids } = await editBoard(api, values, edits);
+                return finish(io, values, { ids }, [`Made ${ids.length} change${ids.length === 1 ? "" : "s"} in one step. The items: ${ids.join(", ")}.`], "orlan board (the board now)");
+            });
+        },
+    },
+    "tasks add": {
+        usage: 'orlan tasks add "<text>" [--assignee me|user:<id>|agent:<id>] [--thread <thread>] [--done] [--topic <topic>] [--agent <id>] [--json]',
+        summary: "Add a task to the topic's task list.",
+        details: [
+            "People see the task on the board at once. `orlan board` lists the open tasks.",
+            "",
+            "--assignee <who>  me (this agent), user:<id> or agent:<id>. Default: nobody.",
+            "--thread <t>      The comment thread the task comes from: #12 or the thread id.",
+            "--done            The task is done already.",
+            "--topic <topic>   The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: {
+            ...agentOption,
+            ...jsonOption,
+            assignee: { type: "string" },
+            thread: { type: "string" },
+            done: { type: "boolean" },
+            topic: { type: "string" },
+        },
+        positionals: [1, 1],
+        run: (values, [text], io) => withAgent(values, async (api, config) => {
+            const assignee = assigneeOption(config, values);
+            const task = await api.call("record", {
+                kind: "task",
+                topicId: await topicOrDefault(api, values),
+                text,
+                ...(assignee ? { assignee } : {}),
+                ...(typeof values.thread === "string" ? { sourceThreadId: values.thread } : {}),
+                ...(values.done ? { done: true } : {}),
+            });
+            return finish(io, values, { task }, [`Added task ${task.id}: ${taskText(task)}.`], `orlan tasks change ${task.id} --done (when it is done)`);
+        }),
+    },
+    "tasks change": {
+        usage: 'orlan tasks change <task id> [--text "<text>"] [--done | --open] [--assignee me|user:<id>|agent:<id>|none] [--agent <id>] [--json]',
+        summary: "Change a task: its text, done or open, or its assignee.",
+        details: [
+            "<task id>         The task id, from `orlan board` or `orlan brief`.",
+            "--text <text>     The new text.",
+            "--done            Mark it done.",
+            "--open            Mark it open again.",
+            "--assignee <who>  me (this agent), user:<id>, agent:<id>, or none.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: {
+            ...agentOption,
+            ...jsonOption,
+            text: { type: "string" },
+            done: { type: "boolean" },
+            open: { type: "boolean" },
+            assignee: { type: "string" },
+        },
+        positionals: [1, 1],
+        run: (values, [taskId], io) => withAgent(values, async (api, config) => {
+            if (values.done && values.open)
+                throw new OrlanError("Give --done or --open, not both.");
+            const assignee = assigneeOption(config, values);
+            const change = {
+                ...(typeof values.text === "string" ? { text: values.text } : {}),
+                ...(values.done ? { done: true } : values.open ? { done: false } : {}),
+                ...(assignee !== undefined ? { assignee } : {}),
+            };
+            if (Object.keys(change).length === 0) {
+                throw new OrlanError("Give --text, --done, --open or --assignee.", undefined, `orlan tasks change ${taskId} --done`);
+            }
+            const task = await api.call("record", { kind: "task", taskId, ...change });
+            return finish(io, values, { task }, [`Changed task ${task.id}: ${taskText(task)}.`], WAIT_STEP);
+        }),
+    },
+    "decisions add": {
+        usage: 'orlan decisions add "<title>" [--body "<text>"] [--thread <thread>] [--topic <topic>] [--agent <id>] [--json]',
+        summary: "Record a decision in the topic's decision log.",
+        details: [
+            "Record a decision the people made, so it is not lost in a thread. `orlan search` finds it later.",
+            "",
+            "--body <text>    The decision in full: what, and why.",
+            "--thread <t>     The comment thread the decision comes from: #12 or the thread id.",
+            "--topic <topic>  The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: {
+            ...agentOption,
+            ...jsonOption,
+            body: { type: "string" },
+            thread: { type: "string" },
+            topic: { type: "string" },
+        },
+        positionals: [1, 1],
+        run: (values, [title], io) => withAgent(values, async (api) => {
+            const decision = await api.call("record", {
+                kind: "decision",
+                topicId: await topicOrDefault(api, values),
+                title,
+                ...(typeof values.body === "string" ? { body: values.body } : {}),
+                ...(typeof values.thread === "string" ? { sourceThreadId: values.thread } : {}),
+            });
+            return finish(io, values, { decision }, [`Recorded decision ${decision.id}: ${quote(decision.title)}.`], WAIT_STEP);
+        }),
+    },
+    search: {
+        usage: 'orlan search "<words>" [--topic <topic>] [--limit <n>] [--agent <id>] [--json]',
+        summary: "Search the topics of the agent: topic and file names, page text, comments and decisions.",
+        details: [
+            "The matches are between « and », with some text around them. Orlan searches the current version",
+            "of each file, and the newest version that was sent.",
+            "",
+            "--topic <topic>  Only this topic: its id or its name. Default: every topic of the agent.",
+            "--limit <n>      At most this many results, from 1 to 100. Default: 20.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: { ...agentOption, ...jsonOption, topic: { type: "string" }, limit: { type: "string" } },
+        positionals: [1, 1],
+        run: (values, [words], io) => withAgent(values, async (api) => {
+            const limit = values.limit === undefined ? undefined : Number(values.limit);
+            if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 100)) {
+                throw new OrlanError("--limit takes a number from 1 to 100.", undefined, "run the command again with --limit 20");
+            }
+            const { results } = await api.call("search", {
+                q: words,
+                ...topicInput(values),
+                ...(limit ? { limit } : {}),
+            });
+            const on = (result) => `on ${quote(result.topic.name)}`;
+            const version = (result) => (result.version ? ` v${result.version.number}` : "");
+            const lines = results.length === 0 ? [`No match for ${quote(words)}.`] : [QUOTED_TEXT];
+            for (const result of results) {
+                const { ids } = result;
+                lines.push(result.kind === "topic"
+                    ? `- topic ${quote(result.title)} (${result.topic.id}): ${quote(result.snippet)}`
+                    : result.kind === "file"
+                        ? `- file ${quote(result.title)}${version(result)} (${ids.artifactId}) ${on(result)}: ${quote(result.snippet)}`
+                        : result.kind === "page"
+                            ? `- page ${ids.page} of ${quote(result.title)}${version(result)} (${ids.artifactId}) ${on(result)}: ${quote(result.snippet)}`
+                            : result.kind === "comment"
+                                ? `- comment in ${result.title} (thread ${ids.threadId}) ${on(result)}: ${quote(result.snippet)}`
+                                : `- decision ${quote(result.title)} (${ids.decisionId}) ${on(result)}: ${quote(result.snippet)}`);
+            }
+            const page = results.find((result) => result.kind === "page");
+            const comment = results.find((result) => result.kind === "comment");
+            return finish(io, values, { results }, lines, page
+                ? `orlan files pull ${page.ids.artifactId} --pages ${page.ids.page} (the page of a match)`
+                : comment
+                    ? `orlan comments list --topic ${comment.topic.id} --status all (the threads)`
+                    : results.length === 0
+                        ? "search again with other words"
+                        : "orlan brief (where the work stands)");
+        }),
+    },
     brief: {
         usage: "orlan brief [--topic <topic>] [--agent <id>] [--json]",
         summary: "Print where the work stands: the topic, the open requests, the files, and the next step.",
         details: [
-            "For the start of a session: one short answer, with no MCP session. The topic is the one the agent",
+            "For the start of a session: one short answer, in one plain HTTP call. The topic is the one the agent",
             "used last, else its only topic. It lists the open requests (`orlan inbox` prints them in full),",
-            "the files with their current versions, and one next_step line.",
+            "the files with their current versions, the open vote and the open tasks (one line each), and one",
+            "next_step line. People vote; an agent reads the vote, it does not vote.",
             "",
             "--topic <topic>  Another topic of the agent: its id or its name.",
             AGENT_TOKEN_HELP,
@@ -1311,9 +1766,9 @@ export const commands = {
         usage: "orlan hook start --agent codex|cursor",
         summary: "The session start hook of Codex and Cursor: report working and give the session the brief.",
         details: [
-            "`orlan mcp connect --agent codex|cursor` installs it. It prints `orlan brief` and how to answer a",
-            "request, in the JSON the harness adds to the session's context, and the board shows the session",
-            "as working. With the agent not connected, it prints nothing.",
+            "`orlan connect --agent codex|cursor` installs it. It prints `orlan brief`, what Orlan is and how",
+            "to answer a request, in the JSON the harness adds to the session's context, and the board shows",
+            "the session as working. With the agent not connected, it prints nothing.",
             "",
             "--agent <id>   codex or cursor.",
         ],
@@ -1330,16 +1785,15 @@ export const commands = {
                 apiCall(config.server, "/api/agent/brief?hook=true", { token }),
                 reportQuietly(config.server, token, "working", fields.session),
             ]);
-            const context = [
+            const lines = [
                 ...brief.lines,
+                await orlanIntro(),
                 `No monitor wakes this ${agentLabels[agent]} session. A new Orlan request comes to you when your turn ends, ` +
                     "from the Orlan stop hook. Do not run orlan wait yourself: it blocks your turn.",
                 "Answer a request with the orlan command in few steps: orlan files pull <file id> --edit --out <path> && cat <path>; " +
                     'edit the file; orlan respond <request id> --file <path> [--to <file id>] --message "<what changed>".',
-            ].join("\n");
-            io.out(JSON.stringify(agent === "codex"
-                ? { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context } }
-                : { additional_context: context }));
+            ];
+            io.out(sessionStartOutput(agent, lines));
             return 0;
         },
     },
@@ -1347,7 +1801,7 @@ export const commands = {
         usage: "orlan hook stop --agent codex|cursor",
         summary: "The stop hook of Codex and Cursor: give the session a waiting request, else report idle.",
         details: [
-            "`orlan mcp connect --agent codex|cursor` installs it. When the session's turn ends, it takes the",
+            "`orlan connect --agent codex|cursor` installs it. When the session's turn ends, it takes the",
             "new requests of the agent (as `orlan inbox --new` does) and gives them to the session, so it works",
             "on at once: Codex gets decision block with the requests, Cursor a followup_message. The board",
             "shows the session as working. With no request, it prints nothing and the board shows it idle.",
@@ -1401,7 +1855,7 @@ export const commands = {
         usage: "orlan hook wait --agent opencode",
         summary: "The wait of the OpenCode plugin: wait for a request and print it as the prompt of a new turn.",
         details: [
-            "`orlan mcp connect --agent opencode` installs the plugin that runs it when a session's turn ends.",
+            "`orlan connect --agent opencode` installs the plugin that runs it when a session's turn ends.",
             'It waits as `orlan wait` does, then prints one JSON line: {"prompt"} with the request, which the',
             'plugin sends to the session, or {"stopped"} when a person stopped the agent on the board. It ends',
             "when its standard input closes (OpenCode exited); a request it did not print stays in the inbox.",
@@ -1463,3 +1917,112 @@ export const commands = {
         },
     },
 };
+/** Runs edit_board on the topic of --topic, else the default topic: one step, all edits or none. */
+async function editBoard(api, values, edits) {
+    return api.call("edit_board", { topicId: await topicOrDefault(api, values), edits });
+}
+/** --assignee as the tool takes it: me (the token of this agent), user:<id>, agent:<id>, or none (null). */
+function assigneeOption(config, values) {
+    const raw = values.assignee;
+    if (typeof raw !== "string")
+        return undefined;
+    if (raw === "none")
+        return null;
+    if (raw === "me") {
+        return { kind: "agent", id: config.agents[pickAgent(config, values)]?.tokenId };
+    }
+    const match = /^(user|agent):(\S+)$/.exec(raw);
+    if (!match) {
+        throw new OrlanError("--assignee takes me, user:<id>, agent:<id> or none.", undefined, "run the command again with --assignee me");
+    }
+    return { kind: match[1], id: match[2] };
+}
+/** A task in one line: its text, its assignee, and done. */
+const taskText = (task) => `${quote(task.text)}${task.assignee ? ` for ${quote(task.assignee.name)}` : ""}${task.done ? ", done" : ", open"}`;
+/** A vote in one line, as the brief shows it, with its result when people can see it. */
+function voteText(vote) {
+    const result = vote.result
+        ?.map((entry) => "option" in entry
+        ? `${quote(entry.option)} ${entry.count}${entry.by ? ` (${entry.by.map(quote).join(", ")})` : ""}`
+        : `${entry.on} ${entry.count}`)
+        .join(", ");
+    return (`${vote.kind} ${quote(vote.question)}` +
+        (vote.options ? `, options ${vote.options.map(quote).join(", ")}` : `, ${vote.dots} dots each`) +
+        `, ${vote.voters} voted` +
+        (result ? `, result: ${result}` : ""));
+}
+/** --pages as page numbers: "3" or "2,5". */
+function pageList(values) {
+    if (typeof values.pages !== "string")
+        return undefined;
+    const pages = values.pages.split(",").map((part) => Number(part.trim()));
+    if (pages.length === 0 || pages.some((page) => !Number.isInteger(page) || page < 1)) {
+        throw new OrlanError("--pages takes page numbers from 1 with commas, for example 3 or 2,5.", undefined, "run the command again with --pages 1");
+    }
+    return pages;
+}
+/** The claim lines of a pull: the agent's own claim, and each other agent that edits the file. */
+function claimLines(answer) {
+    const lines = [];
+    if (answer.claim) {
+        lines.push(`Your${answer.claim.shared ? " shared" : ""} claim is on the file from v${answer.claim.baseVersion}.`);
+    }
+    for (const other of answer.claims ?? []) {
+        const minutes = Math.floor((Date.now() - new Date(other.since).getTime()) / 60_000);
+        lines.push(`${quote(other.agent)} is editing it from v${other.baseVersion}${other.shared ? " (shared claim)" : ""} - ` +
+            `${minutes < 1 ? "under 1 min" : `${minutes} min`}.`);
+    }
+    return lines;
+}
+/** The image types a page has, and the extension of each. */
+const PAGE_EXTENSIONS = { "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp" };
+/** `orlan files pull --pages|--since`: saves the image of each page and prints its text. */
+async function pullPages(api, config, values, io, answer, since) {
+    const folder = typeof values.out === "string" ? values.out : ".";
+    const stem = path.basename(answer.file.name, path.extname(answer.file.name));
+    const saved = [];
+    for (const page of answer.pages ?? []) {
+        const response = await fetch(page.imageUrl, {
+            headers: { authorization: `Bearer ${api.token}` },
+        }).catch((error) => {
+            throw unreachable(config.server, error);
+        });
+        if (!response.ok) {
+            throw new OrlanError(`The image of page ${page.index} from ${config.server} answered ${response.status}.`, undefined, "run the command again");
+        }
+        const type = response.headers.get("content-type")?.split(";")[0] ?? "";
+        const image = path.join(folder, `${stem}-page-${page.index}.${PAGE_EXTENSIONS[type] ?? "png"}`);
+        if (saved.length === 0)
+            await mkdir(folder, { recursive: true });
+        await writeFile(image, Buffer.from(await response.arrayBuffer()));
+        saved.push({ index: page.index, image, text: page.text ?? "" });
+    }
+    const { number, renderStatus } = answer.version;
+    const title = `Version ${number} of ${quote(answer.file.name)}`;
+    const lines = [
+        since !== undefined
+            ? `${title}: ${changedText(saved.map((page) => page.index))} since v${since}.`
+            : `${title}: ${saved.length} page${saved.length === 1 ? "" : "s"}.`,
+        ...(renderStatus !== "done" && saved.length === 0
+            ? [`The pages of v${number} are not rendered yet (${renderStatus}).`]
+            : []),
+        ...saved.map((page) => `Page ${page.index}: saved ${quote(page.image)}. Text: ${quote(page.text)}`),
+        ...claimLines(answer),
+    ];
+    const first = saved[0];
+    return finish(io, values, {
+        file: { id: answer.file.id, name: answer.file.name },
+        version: number,
+        ...(since !== undefined ? { changedSince: since } : {}),
+        pages: saved,
+        ...(answer.claim !== undefined ? { claim: answer.claim } : {}),
+        ...(answer.claims ? { claims: answer.claims } : {}),
+    }, lines, answer.nextStep ??
+        (first
+            ? `look at the images, then orlan comment --file ${answer.file.id} --page ${first.index} "<text>" (a comment on a page)`
+            : renderStatus !== "done"
+                ? "run the command again in a minute"
+                : `orlan files pull ${answer.file.id} (the whole file)`));
+}
+/** The changed pages of a version, as words: "pages 2, 5 changed", "no page changed". */
+const changedText = (pages) => pages.length === 0 ? "no page changed" : `page${pages.length === 1 ? "" : "s"} ${pages.join(", ")} changed`;