@orlan-maker/cli 0.4.0 → 0.11.0

package/dist/commands.js

@@ -2,13 +2,14 @@
  * Every orlan command: its usage, its help, its options, and what it does. main.ts parses the
  * arguments and runs one of them.
  */
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { openAsBlob } from "node:fs";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { hostname } from "node:os";
 import path from "node:path";
 import { agentIds, agentLabels, detectAgent, parseAgent, planOldInstall, skillsDir, } from "./agents.js";
 import { openBrowser } from "./browser.js";
 import { readConfig, serverOrigin, writeConfig } from "./config.js";
-import { AgentApi, apiCall, OrlanError, sessionHeader, unreachable } from "./http.js";
+import { AgentApi, apiCall, apiError, OrlanError, sessionHeader, unreachable } from "./http.js";
 import { account, deleteSecret, getSecret, setSecret } from "./secrets.js";
 import { removeSkills, writeSkills } from "./skills.js";
 const agentOption = { agent: { type: "string" } };
@@ -64,6 +65,26 @@ async function withAgent(values, work) {
     const config = await readConfig();
     return work(new AgentApi(config.server, await agentSecret(config, values)), config);
 }
+/** The steps of a studio skill, in order (F143). */
+const STUDIO_STEPS = ["brief", "script", "build", "render", "review"];
+const skillLine = ({ steps, scripts }) => `${steps.join(", ")} (${scripts.length} helper script${scripts.length === 1 ? "" : "s"})`;
+/**
+ * withAgent for the studio commands (F143): the steps come only from Orlan, so an agent with no connection,
+ * or with a token Orlan does not accept, gets one sign-in message.
+ */
+async function withStudio(values, work) {
+    const signIn = () => new OrlanError("Sign in to Orlan to get the studio steps: they come only from Orlan, for a signed-in agent.", "not_signed_in", "orlan auth login, then orlan connect --agent <id>");
+    if (Object.keys((await readConfig()).agents).length === 0)
+        throw signIn();
+    try {
+        return await withAgent(values, work);
+    }
+    catch (error) {
+        if (error instanceof OrlanError && error.code === "not_signed_in")
+            throw signIn();
+        throw error;
+    }
+}
 /** Prints small JSON on one line (F038). */
 const printJson = (io, data) => io.out(JSON.stringify(data));
 /**
@@ -82,17 +103,68 @@ function finish(io, values, data, lines, next) {
 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).
+ * one the person has open in Orlan now, else the one the agent used last, else its only topic). When the
+ * person's open topic is out of the agent's reach, the command says so first (F123), not with --json.
  */
-async function topicOrDefault(api, values) {
+async function topicOrDefault(api, values, io) {
     if (typeof values.topic === "string")
         return values.topic;
-    const { topic } = await api.get("/api/agent/brief", {}, "the brief");
+    const { topic } = await briefTopic(api, values, io);
     if (!topic) {
         throw new OrlanError("The agent has several topics and used none yet. Add --topic <topic>.", "topic_missing");
     }
     return topic.id;
 }
+/** The topic the brief names, after its notice (F123). */
+async function briefTopic(api, values, io) {
+    const brief = await api.get("/api/agent/brief", {}, "the brief");
+    if (brief.notice && !values.json)
+        for (const line of brief.notice)
+            io.out(line);
+    return brief;
+}
+/** --new-topic: the name of the topic a command that writes makes when there is no topic (F131). */
+const NEW_TOPIC_HELP = [
+    "--new-topic <name>  With no --topic and no topic open in Orlan (or used in the last minutes): make a new",
+    "                  topic with this short name of the subject, and work there. Only for an agent with all",
+    "                  topics, within the person's role and plan.",
+];
+/** The help of --shots, its text from `column` on, as the other options of the command. */
+const shotsHelp = (column) => [
+    "For a video: its shot list, a JSON file of the scenes in order, for example",
+    '[{ "name": "Hook", "start": 0, "end": 4.5 }], in seconds. The review shows the scene list.',
+    "Orlan refuses a bad list with shots_invalid, and names the problem.",
+].map((line, index) => (index === 0 ? "--shots <file>" : "").padEnd(column) + line);
+/** The help of --scores (F139), its text from `column` on. */
+const scoresHelp = (column) => [
+    "The critic scorecard of the version: a JSON file of 1 to 20 scores, for example",
+    '[{ "name": "Hook", "score": 8, "note": "lands at 0:02" }], each score from 0 to 10. People see',
+    "it read only in the review and in Compare. Orlan refuses a bad scorecard with scores_invalid.",
+].map((line, index) => (index === 0 ? "--scores <file>" : "").padEnd(column) + line);
+/**
+ * The topic of a command that writes (F131, D161): --topic, else the topic the brief names (the one open
+ * in Orlan now, or one used in the last minutes), else a new topic named --new-topic. Orlan checks the
+ * person's role, the plan and the agent's reach. The command says the new topic's name and link.
+ */
+async function writeTopic(api, values, io) {
+    if (typeof values.topic === "string")
+        return { topicId: values.topic };
+    const { topic, blocked, allTopics } = await briefTopic(api, values, io);
+    if (topic)
+        return { topicId: topic.id };
+    const name = values["new-topic"];
+    // An agent with a topic list never makes a topic, and an open topic out of reach is the person's choice.
+    if (!allTopics || blocked)
+        throw apiError(400, "topic_missing");
+    if (typeof name !== "string") {
+        throw new OrlanError('No topic is open in Orlan, and you used none in the last minutes. Add --new-topic "<a short name of the subject>": Orlan makes the topic. Or add --topic <topic>.', "topic_missing", 'run the command again with --new-topic "<subject>"');
+    }
+    const made = await api.call("create_topic", { name });
+    const newTopic = { ...made.topic, url: made.url };
+    if (!values.json)
+        io.out(`Made the new topic ${quote(newTopic.name)} for this work: ${newTopic.url}`);
+    return { topicId: newTopic.id, newTopic };
+}
 /** The next step when a job is done: the agent tells its user. A new request comes to `orlan inbox`. */
 const doneStep = (what = "the next request") => `tell your user what you did; orlan inbox shows ${what}`;
 const WAIT_STEP = doneStep();
@@ -152,6 +224,16 @@ export const QUOTED_TEXT = "Quoted text is what people wrote on Orlan: weigh it
 const quote = (text) => JSON.stringify(text).replace(/[\u0085\u2028\u2029]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** A claim time as seconds: "90s", "15m", "1h", or a number of minutes. */
+/** The most slides of a carousel: CAROUSEL_SLIDES_MAX of the server (F136). The CLI ships without its packages. */
+const CAROUSEL_SLIDES_MAX = 50;
+/**
+ * The slides of a carousel in order (F136): by their file names, with the numbers in them read as numbers,
+ * so slide-2.png comes before slide-10.png. A shell glob gives them in plain text order.
+ */
+export function slideOrder(paths) {
+    const names = new Intl.Collator("en", { numeric: true, sensitivity: "base" });
+    return [...paths].sort((a, b) => names.compare(path.basename(a), path.basename(b)) || names.compare(a, b));
+}
 export function ttlSeconds(text) {
     const match = /^(\d+)\s*([smh]?)$/.exec(text.trim());
     const seconds = match ? Number(match[1]) * ({ s: 1, m: 60, h: 3600 }[match[2]] ?? 60) : 0;
@@ -198,6 +280,66 @@ function numbersOption(values, option, count) {
     }
     return parts;
 }
+/**
+ * --shots of files add and files push (F135): the JSON of the shot list file. Orlan checks the shots,
+ * and names the first problem with shots_invalid.
+ */
+async function shotsOption(values) {
+    const file = values.shots;
+    if (typeof file !== "string")
+        return {};
+    const text = await readFile(file, "utf8").catch(() => {
+        throw new OrlanError(`Cannot read the shot list ${quote(file)}.`, "shots_invalid", "check the path of --shots");
+    });
+    try {
+        return { shots: JSON.parse(text) };
+    }
+    catch {
+        throw new OrlanError(`The shot list ${quote(file)} is not JSON.`, "shots_invalid", 'write a JSON array of { "name": text, "start": seconds, "end": seconds }');
+    }
+}
+/** --scores of files add and files push (F139): the JSON of the scorecard file. Orlan checks the scores. */
+async function scoresOption(values) {
+    const file = values.scores;
+    if (typeof file !== "string")
+        return {};
+    const text = await readFile(file, "utf8").catch(() => {
+        throw new OrlanError(`Cannot read the scorecard ${quote(file)}.`, "scores_invalid", "check the path of --scores");
+    });
+    try {
+        return { scores: JSON.parse(text) };
+    }
+    catch {
+        throw new OrlanError(`The scorecard ${quote(file)} is not JSON.`, "scores_invalid", 'write a JSON array of { "name": text, "score": 0 to 10, "note": text }');
+    }
+}
+/** --answers of files push (F139): the comment numbers the version answers, "3,5" or "#3,#5". */
+function answersOption(values) {
+    if (typeof values.answers !== "string")
+        return {};
+    const answers = values.answers.split(",").map((part) => Number(part.trim().replace(/^#/, "")));
+    if (answers.length === 0 || answers.some((number) => !Number.isInteger(number) || number < 1)) {
+        throw new OrlanError("--answers takes comment numbers with commas, for example 3,5 or #3,#5.", "answers_invalid", "orlan comments list --file <file> shows the numbers");
+    }
+    return { answers };
+}
+/** One time of --time: seconds or m:ss, for example 42, 42.5, 0:42 or 1:02:03. NaN when it is not a time. */
+function secondsOf(text) {
+    if (!/^\d+(:\d{1,2}){0,2}(\.\d+)?$/.test(text.trim()))
+        return Number.NaN;
+    return text
+        .trim()
+        .split(":")
+        .reduce((sum, part) => sum * 60 + Number(part), 0);
+}
+/** --time of a comment on a video (F134): a time, or a range with a dash, for example 0:40-0:48. */
+function timeOption(raw) {
+    const [at, end, ...rest] = raw.split("-").map(secondsOf);
+    if (at === undefined || Number.isNaN(at) || (end !== undefined && Number.isNaN(end)) || rest.length > 0) {
+        throw new OrlanError("--time takes seconds or m:ss, for example 42 or 0:42, or a range with a dash, for example 0:40-0:48.", undefined, "run the command again with --time 0:42");
+    }
+    return end === undefined ? { at } : { at, end };
+}
 /**
  * An arrow end of --from or --to: <item>, or <item>@x,y for an exact spot on the item (F111), x and y
  * from 0 to 1 of its box. "none" (board change) is no item.
@@ -251,6 +393,20 @@ async function confirmPrinted(server, token, io, deliveries) {
         }
     }
 }
+/**
+ * "all topics", the restricted topics it also reaches and the ones it leaves out (B058), or the topic
+ * names. An older server sends no leftOut.
+ */
+const reachText = (scope, all) => {
+    if (!scope.allTopics)
+        return scope.topics.map((topic) => quote(topic.name)).join(", ");
+    const named = (topics) => topics.map((topic) => `${quote(topic.name)} (restricted)`).join(", ");
+    const included = scope.topics.filter((topic) => topic.restricted);
+    const leftOut = scope.leftOut ?? [];
+    return (all +
+        (included.length > 0 ? `, and ${named(included)}` : "") +
+        (leftOut.length > 0 ? `, except ${named(leftOut)}` : ""));
+};
 /** Prints what planOldInstall removed, on one line, and the commands that remove the rest by hand. */
 function printRemoved(io, { removed, byHand }) {
     if (removed.length > 0)
@@ -285,7 +441,7 @@ async function connect(agent, values, io) {
     await writeConfig(config);
     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.allTopics ? "all topics" : made.token.topics.map((topic) => quote(topic.name)).join(", ")}. It is in the ${where === "keychain" ? "keychain" : "credentials file"}.`);
+        `${reachText(made.token, "all topics")}. It is in the ${where === "keychain" ? "keychain" : "credentials file"}.`);
     await writeSkills(agent);
     io.out(`Installed the Orlan skills orlan, orlan-review and orlan-versions in ${skillsDir(agent)}.`);
     // The test is the person's, not a call of the agent: it names no agent session.
@@ -344,7 +500,7 @@ export const commands = {
         details: [
             "Shows a code and opens the Orlan page that approves it. Sign in there, check that the code is",
             "the same, choose the organisation, and what your agents get: one topic, or all topics of the",
-            "organisation (also the topics made later; restricted topics only when you tick them in Details).",
+            "organisation (also the topics made later; restricted topics only when you include them there).",
             "Details also has the agent role. The CLI token goes to the OS keychain, or to a file only you can",
             "read when there is no keychain.",
             "",
@@ -493,9 +649,7 @@ export const commands = {
             io.out(`Server:       ${config.server}`);
             io.out(`Signed in as: ${quote(status.user.name)} (${status.user.email ?? "guest account"})`);
             io.out(`Organisation: ${quote(status.org.name)} (${status.org.role})`);
-            io.out(`New agents get: ${status.agentDefaults.role} on ${status.agentDefaults.allTopics
-                ? "all topics, also new ones"
-                : status.agentDefaults.topics.map((topic) => quote(topic.name)).join(", ") || "no topics (use --topic)"}`);
+            io.out(`New agents get: ${status.agentDefaults.role} on ${reachText(status.agentDefaults, "all topics, also new ones") || "no topics (use --topic)"}`);
             if (agents.length === 0)
                 io.out("Agents:       none connected.");
             for (const { agent, token: local, role, check } of agents) {
@@ -536,8 +690,9 @@ export const commands = {
             "",
             AGENT_HELP,
             "--topic <id>   A topic the agent can use. Repeat it for more. The agent then gets only these topics.",
-            "               Default: what you chose at sign-in (one topic, the ticked topics, or all topics).",
-            "--role <role>  editor, commenter or viewer. Default: the role you chose at sign-in.",
+            "               Each must be in what you approved at sign-in: a restricted topic only when you",
+            "               included it. Default: what you chose at sign-in (one topic, the ticked topics, or all topics).",
+            "--role <role>  editor, commenter or viewer, not above the role you approved. Default: that role.",
         ],
         options: CONNECT_OPTIONS,
         positionals: [0, 0],
@@ -574,56 +729,140 @@ export const commands = {
         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. Default: the topic the agent used last, else its only topic.",
+            "--topic <topic>  The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
             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);
+            const topicId = await topicOrDefault(api, values, io);
             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} v${file.current.number} current (${file.current.status}), ` +
+                : files.map((file) => `${file.id} ${quote(file.name)} ${file.kind}` +
+                    // A video says its length (F133).
+                    (file.current.durationMs !== undefined ? ` ${Math.round(file.current.durationMs / 1000)} s` : "") +
+                    // The scenes of its shot list (F135).
+                    (file.current.scenes ? ` ${file.current.scenes} scene${file.current.scenes === 1 ? "" : "s"}` : "") +
+                    // The slides of a carousel (F136).
+                    (file.current.slides ? ` ${file.current.slides} slide${file.current.slides === 1 ? "" : "s"}` : "") +
+                    ` v${file.current.number} current (${file.current.status}), ` +
                     `${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 final version a person picked, with its formats (F137).
+                    (file.final ? `, final v${file.final.version} (${file.final.formats.join(", ")})` : "") +
+                    // The critic scorecard of the newest scored version (F139).
+                    (file.scores ? `, critic v${file.scores.version} ${scoreTotal(file.scores.scores)}` : "")), files.length === 0 ? "orlan files add <path> (a new file)" : "orlan files pull <file> --edit --out <path>");
         }),
     },
     "files add": {
-        usage: "orlan files add <path> [--at <x,y>] [--topic <topic>] [--agent <id>] [--json]",
+        usage: "orlan files add <path>... [--carousel [--name <name>]] [--at <x,y>] [--shots <shots.json>] [--scores <scores.json>] [--topic <topic> | --new-topic <name>] [--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.",
+            "renders its pages. A PowerPoint, Word, Excel, PDF, PNG, JPG or HTML file, or an MP4 or WebM video,",
+            "with the right extension. The file streams from the disk, so a large video works too.",
             "",
+            "--carousel       The paths are the PNG or JPG slides of one carousel: one file on the board.",
+            "                 The slides go in the order of the numbers in their names: slide-2 before slide-10.",
+            "--name <name>    With --carousel: the name of the carousel. Default: the name of its first slide.",
             "--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.",
+            ...shotsHelp(17),
+            ...scoresHelp(17),
+            "--topic <topic>  The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
+            ...NEW_TOPIC_HELP,
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
-        options: { ...agentOption, ...jsonOption, topic: { type: "string" }, at: { type: "string" } },
-        positionals: [1, 1],
-        run: (values, [filePath], io) => withAgent(values, async (api) => {
+        options: {
+            ...agentOption,
+            ...jsonOption,
+            topic: { type: "string" },
+            "new-topic": { type: "string" },
+            at: { type: "string" },
+            shots: { type: "string" },
+            scores: { type: "string" },
+            carousel: { type: "boolean" },
+            name: { type: "string" },
+        },
+        positionals: [1, CAROUSEL_SLIDES_MAX],
+        run: (values, paths, io) => withAgent(values, async (api) => {
+            const [filePath] = paths;
+            if (!values.carousel && (paths.length > 1 || values.name !== undefined)) {
+                throw new OrlanError(paths.length > 1
+                    ? "Give one file, or add --carousel for the slides of one carousel."
+                    : "--name goes with --carousel.", undefined, `orlan files add ${paths.join(" ")} --carousel`);
+            }
             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] } });
+            const shots = await shotsOption(values);
+            const scores = await scoresOption(values);
+            if (values.carousel && shots.shots !== undefined) {
+                throw new OrlanError("--shots goes with a video, not with --carousel.", "shots_invalid", "leave out --shots");
+            }
+            const { topicId, newTopic } = await writeTopic(api, values, io);
+            const madeTopic = newTopic ? { newTopic } : {};
+            if (values.carousel) {
+                // Each slide goes up first, in order; the post makes them one carousel (F136).
+                const slides = slideOrder(paths);
+                const uploadIds = [];
+                for (const slide of slides) {
+                    uploadIds.push(await api.upload(await openAsBlob(slide), { topic: topicId, name: path.basename(slide) }));
+                }
+                const name = typeof values.name === "string" && values.name.trim()
+                    ? values.name.trim()
+                    : path.parse(slides[0]).name;
+                const posted = await api.call("post", {
+                    topicId,
+                    name,
+                    slides: uploadIds,
+                    ...(at ? { position: { x: at[0], y: at[1] } } : {}),
+                    ...scores,
+                });
+                return finish(io, values, {
+                    file: {
+                        id: posted.file.id,
+                        name: posted.file.name,
+                        version: posted.posted.number,
+                        slides: slides.length,
+                    },
+                    boardItemId: posted.boardItemId,
+                    ...madeTopic,
+                }, [
+                    `Added the carousel ${quote(posted.file.name)} as file ${posted.file.id}, v${posted.posted.number}, ` +
+                        `${slides.length} slide${slides.length === 1 ? "" : "s"} in this order: ` +
+                        `${slides.map((slide) => path.basename(slide)).join(", ")}. It is on the board.`,
+                ], doneStep("comments on the file"));
+            }
+            if (at || shots.shots !== undefined || scores.scores !== undefined) {
+                // A place on the board, a shot list or a scorecard: the file goes up first, then the post places it.
+                const uploadId = await api.upload(await openAsBlob(filePath), {
+                    topic: topicId,
+                    name: path.basename(filePath),
+                });
+                const posted = await api.call("post", {
+                    topicId,
+                    name: path.basename(filePath),
+                    uploadId,
+                    ...(at ? { position: { x: at[0], y: at[1] } } : {}),
+                    ...shots,
+                    ...scores,
+                });
                 return finish(io, values, {
                     file: { id: posted.file.id, name: posted.file.name, version: posted.posted.number },
                     boardItemId: posted.boardItemId,
+                    ...madeTopic,
                 }, [
                     `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.`,
+                        `board${at ? ` at ${at.join(",")}, or at the nearest free place` : ""}; its pages render now.`,
+                    ...(shots.shots !== undefined ? ["Its shot list shows as the scene list of the video."] : []),
                 ], doneStep("comments on the file"));
             }
-            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, [
+            const { nextStep, ...answer } = await api.postFile("/api/agent/files", { name: path.basename(filePath), topic: topicId }, await openAsBlob(filePath), "the new file");
+            return finish(io, values, { ...answer, ...madeTopic }, [
                 `Added ${quote(answer.file.name)} to topic ${quote(answer.topic.name)} as file ` +
                     `${answer.file.id}, v${answer.file.version}. It is on the board; its pages render now.`,
             ], nextStep);
@@ -703,7 +942,10 @@ export const commands = {
             if (!response.ok) {
                 throw new OrlanError(`The download from ${config.server} answered ${response.status}.`, undefined, "run the command again");
             }
-            const target = typeof values.out === "string" ? values.out : path.basename(answer.file.name);
+            // A carousel's original is the zip of its slides (F136).
+            const target = typeof values.out === "string"
+                ? values.out
+                : `${path.basename(answer.file.name)}${answer.file.kind === "carousel" ? ".zip" : ""}`;
             await writeFile(target, Buffer.from(await response.arrayBuffer()));
             const lines = [
                 `Saved version ${answer.version.number} of ${quote(answer.file.name)} to ${quote(target)}.`,
@@ -720,16 +962,22 @@ export const commands = {
         }),
     },
     "files push": {
-        usage: 'orlan files push <file> <path> --changelog "<what changed>" [--base <n>] [--topic <topic>] [--agent <id>] [--json]',
+        usage: 'orlan files push <file> <path>... --changelog "<what changed>" [--answers <n,n>] [--base <n>] [--shots <shots.json>] [--scores <scores.json>] [--topic <topic>] [--agent <id>] [--json]',
         summary: "Post a local file as a new version of a file.",
         details: [
             "Two requests: one sends the file, one posts it with the changelog. It must be the same type of",
             "file. The version waits for a person to make it current. It ends your claim. When a version",
             "landed after your base, Orlan refuses the push with stale_base and its changelog.",
+            "For a carousel, give each PNG or JPG slide. They go in the order of the numbers in their names.",
             "",
             "<file>              The file id, or its name where it is unique on the topic.",
             "--changelog <text>  What changed, for the people who review it. Required.",
+            "--answers <n,n>     The comments this version answers, by number: 3,5 or #3,#5. Each shows",
+            '                    "answered in v<n>". A "#3" in the changelog counts too. A number that is no',
+            "                    comment on the file is refused with answers_invalid.",
             "--base <n>          The version you edited, for example 4 or v4. Default: the version your `pull --edit` got.",
+            ...shotsHelp(20),
+            ...scoresHelp(20),
             "--topic <topic>     The topic of a file name, when two topics have a file with that name.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
@@ -740,24 +988,37 @@ export const commands = {
             changelog: { type: "string" },
             base: { type: "string" },
             topic: { type: "string" },
+            shots: { type: "string" },
+            scores: { type: "string" },
+            answers: { type: "string" },
         },
-        positionals: [2, 2],
-        run: (values, [fileRef, filePath], io) => withAgent(values, async (api) => {
+        positionals: [2, CAROUSEL_SLIDES_MAX + 1],
+        run: (values, [fileRef, ...filePaths], io) => withAgent(values, async (api) => {
             const changelog = typeof values.changelog === "string" ? values.changelog.trim() : "";
             if (!changelog) {
-                throw new OrlanError("Add --changelog.", undefined, `orlan files push ${fileRef} ${filePath} --changelog "<what changed>"`);
+                throw new OrlanError("Add --changelog.", undefined, `orlan files push ${fileRef} ${filePaths.join(" ")} --changelog "<what changed>"`);
             }
             const base = baseOption(values);
-            const uploadId = await api.upload(await readFile(filePath), {
-                file: fileRef,
-                topic: values.topic,
-            });
+            const shots = await shotsOption(values);
+            const scores = await scoresOption(values);
+            const answers = answersOption(values);
+            // Several paths are the slides of a new carousel version (F136), in the order of their names.
+            const uploadIds = [];
+            for (const filePath of filePaths.length > 1 ? slideOrder(filePaths) : filePaths) {
+                uploadIds.push(await api.upload(await openAsBlob(filePath), {
+                    file: fileRef,
+                    topic: values.topic,
+                }));
+            }
             const posted = await api.call("post", {
                 artifactId: fileRef,
                 ...topicInput(values),
-                uploadId,
+                ...(uploadIds.length > 1 ? { slides: uploadIds } : { uploadId: uploadIds[0] }),
                 changelog,
                 ...base,
+                ...shots,
+                ...scores,
+                ...answers,
             });
             return finish(io, values, { file: { id: posted.file.id, name: posted.file.name }, version: posted.posted.number }, [
                 `Posted version ${posted.posted.number} of ${quote(posted.file.name)}. It waits for a person to make it current.`,
@@ -859,7 +1120,10 @@ export const commands = {
                     lines.push(`file ${quote(file.name)}:`);
                     for (const thread of file.threads) {
                         const place = `${thread.at}${thread.region ? `, region ${thread.region.join(",")}` : ""}` +
-                            (thread.element ? `, element ${quote(thread.element)}` : "");
+                            (thread.element ? `, element ${quote(thread.element)}` : "") +
+                            (thread.box ? `, box ${thread.box.join(",")}` : "") +
+                            (thread.scene ? `, scene ${thread.scene.index} ${quote(thread.scene.name)}` : "") +
+                            (thread.answeredIn ? `, answered in ${thread.answeredIn}` : "");
                         lines.push(...threadLines(thread, place));
                     }
                 }
@@ -877,19 +1141,23 @@ export const commands = {
         }),
     },
     comment: {
-        usage: 'orlan comment <thread> "<text>" | --file <file> --page <n> [--region <x,y,w,h>] "<text>" | --at <x,y> "<text>" [--topic <topic>] [--agent <id>] [--json]',
-        summary: "Reply in a thread, or open a new thread on a page or on the board.",
+        usage: 'orlan comment <thread> "<text>" | --file <file> --page <n> [--region <x,y,w,h>] "<text>" | --file <video> --time <t> [--box <x,y,w,h>] "<text>" | --file <video> --scene <n> "<text>" | --at <x,y> "<text>" [--topic <topic>] [--agent <id>] [--json]',
+        summary: "Reply in a thread, or open a new thread on a page, on a video or on the board.",
         details: [
-            "With a thread (#12 or its id), it replies in that thread. With --file and --page, or with --at, it",
-            "opens a new thread there: to ask a person, or to point at a problem. People see it on the board at once.",
+            "With a thread (#12 or its id), it replies in that thread. With --file and --page, --time or --scene, or",
+            "with --at, it opens a new thread there: to ask a person, or to point at a problem. People see it at once.",
             "Write @ and a name to mention a person or an agent of the topic: they are told like any mention.",
             "A question waits for the answer: leave the thread open, the answer comes to your inbox.",
             "",
             "--file <file>        The file of a new thread on a page: its id, or its name.",
             "--page <n>           The page, from 1.",
             "--region <x,y,w,h>   The rectangle on the page, as fractions (0 to 1). Default: the whole page.",
+            "--time <t>           A time of the video: seconds or m:ss, for example 42 or 0:42. A range has a",
+            "                     dash, for example 0:40-0:48.",
+            "--box <x,y,w,h>      With one --time: a rectangle on the frame at that time, as fractions (0 to 1).",
+            "--scene <n>          A scene of the video's shot list, from 1: the thread takes the scene's range.",
             "--at <x,y>           A new thread on this point of the board, in board coordinates.",
-            "--topic <topic>      The topic of --at, of a #12 or of a file name. Default: the topic you used last.",
+            "--topic <topic>      The topic of --at, of a #12 or of a file name. Default: the topic open in Orlan now, else the one used last.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
@@ -899,6 +1167,9 @@ export const commands = {
             file: { type: "string" },
             page: { type: "string" },
             region: { type: "string" },
+            time: { type: "string" },
+            box: { type: "string" },
+            scene: { type: "string" },
             at: { type: "string" },
             topic: { type: "string" },
         },
@@ -907,7 +1178,7 @@ export const commands = {
             const numbers = (option, count) => numbersOption(values, option, count);
             const [first, second] = positionals;
             const body = (second ?? first);
-            const usage = "orlan comment --help (the three forms)";
+            const usage = "orlan comment --help (the forms)";
             let target;
             if (second !== undefined) {
                 if (values.file !== undefined || values.at !== undefined) {
@@ -915,6 +1186,27 @@ export const commands = {
                 }
                 target = { threadId: first };
             }
+            else if (typeof values.file === "string" && (values.time !== undefined || values.scene !== undefined)) {
+                // A time, a range, a box on a frame or a scene of a video (F134, F135).
+                if ((values.time === undefined) === (values.scene === undefined) || values.page !== undefined) {
+                    throw new OrlanError("A comment on a video takes --time or --scene: one of them.", undefined, usage);
+                }
+                const box = numbers("box", 4);
+                const scene = Number(values.scene);
+                if (values.scene !== undefined && (!Number.isInteger(scene) || scene < 1)) {
+                    throw new OrlanError("--scene takes the number of a scene, from 1.", undefined, "add --scene 1");
+                }
+                if (box && (typeof values.time !== "string" || values.time.includes("-"))) {
+                    throw new OrlanError("--box goes with one --time, not a range.", undefined, "add --time 0:42");
+                }
+                target = {
+                    video: {
+                        artifactId: values.file,
+                        ...(typeof values.time === "string" ? timeOption(values.time) : { scene }),
+                        ...(box ? { box: { x: box[0], y: box[1], w: box[2], h: box[3] } } : {}),
+                    },
+                };
+            }
             else if (typeof values.file === "string") {
                 const page = Number(values.page);
                 if (!Number.isInteger(page) || page < 1) {
@@ -985,14 +1277,14 @@ export const commands = {
             '"in frame <id>". Each box is the box after it grew to fit its words. 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.",
+            "--topic <topic>  The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
             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);
+            const topicId = await topicOrDefault(api, values, io);
             // 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" }),
@@ -1054,7 +1346,7 @@ export const commands = {
             "",
             "--out <file.png>  Where to save the picture. A file that is there is replaced.",
             "--frame <frame>   Only this frame: its id, from `orlan board`.",
-            "--topic <topic>   The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            "--topic <topic>   The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
@@ -1070,7 +1362,7 @@ export const commands = {
             if (typeof values.out !== "string" || !values.out) {
                 throw new OrlanError("Add --out <file.png>: where to save the picture.", undefined, "orlan board view --out board.png");
             }
-            const topicId = await topicOrDefault(api, values);
+            const topicId = await topicOrDefault(api, values, io);
             const answer = await api.call("view_board", { topicId, ...(typeof values.frame === "string" ? { frameId: values.frame } : {}) });
             const saved = path.resolve(values.out);
             const png = Buffer.from(answer.png, "base64");
@@ -1099,7 +1391,7 @@ export const commands = {
         }),
     },
     "board add": {
-        usage: 'orlan board add note|text|frame|shape ["<text>"] --at <x,y> [--size <S|M|L|XL|w,h>] [--text-color <color>] [--kind <kind>] [--color <color>] [--frame <frame>|none] | arrow --from <item>[@x,y] --to <item>[@x,y] [--text "<label>"] [--id <id>] [--topic <topic>] [--agent <id>] [--json]',
+        usage: 'orlan board add note|text|frame|shape ["<text>"] --at <x,y> [--size <S|M|L|XL|w,h>] [--text-color <color>] [--kind <kind>] [--color <color>] [--frame <frame>|none] | arrow --from <item>[@x,y] --to <item>[@x,y] [--text "<label>"] [--id <id>] [--topic <topic> | --new-topic <name>] [--agent <id>] [--json]',
         summary: "Add a note, a text, a shape, a frame or an arrow to the board.",
         details: [
             "A note, a text, a shape or a frame goes at --at, with its text (a frame's text is its title, a",
@@ -1130,7 +1422,8 @@ export const commands = {
             "--frame <frame>   The frame the item goes in, by its id. none: in no frame. Default: the frame that",
             "                  holds more than half of it.",
             '--text <text>     The text, as the "<text>" word gives it. For an arrow: its label, for example "yes".',
-            "--topic <topic>   The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            "--topic <topic>   The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
+            ...NEW_TOPIC_HELP,
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
@@ -1148,6 +1441,7 @@ export const commands = {
             id: { type: "string" },
             frame: { type: "string" },
             topic: { type: "string" },
+            "new-topic": { type: "string" },
         },
         positionals: [1, 2],
         run: (values, [type, word], io) => {
@@ -1198,10 +1492,10 @@ export const commands = {
             // The server refuses a frame on an arrow, and says why.
             Object.assign(edit, frameOption(values));
             return withAgent(values, async (api) => {
-                const { items, warnings } = await editBoard(api, values, [edit]);
+                const { items, warnings, newTopic } = await editBoard(api, values, io, [edit]);
                 const item = items[0];
                 const where = type === "arrow" ? `, from ${values.from} to ${values.to}` : "";
-                return finish(io, values, { ...item, warnings }, [`Added ${boxText(item)}${where}.`, ...warningLines(warnings)], afterWarnings(warnings, type === "arrow"
+                return finish(io, values, { ...item, warnings, ...(newTopic ? { newTopic } : {}) }, [`Added ${boxText(item)}${where}.`, ...warningLines(warnings)], afterWarnings(warnings, type === "arrow"
                     ? "orlan board (the board with the arrow)"
                     : `orlan board add arrow --from ${item.id} --to <item> (to link it), or orlan board`));
             });
@@ -1233,7 +1527,7 @@ export const commands = {
             "--to <item>       The item the arrow points to, as --from.",
             "--frame <frame>   Put the item in this frame, by its id. none: take it out of its frame. The item",
             "                  stays where it is. With --at and no --frame, the item goes in the frame it lands in.",
-            "--topic <topic>   The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            "--topic <topic>   The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
@@ -1272,7 +1566,7 @@ export const commands = {
                 throw new OrlanError("Give --text, --at, --size, --text-color, --kind, --color, --from, --to or --frame.", undefined, `orlan board change ${id} --text "<text>"`);
             }
             return withAgent(values, async (api) => {
-                const { items, warnings } = await editBoard(api, values, edits);
+                const { items, warnings } = await editBoard(api, values, io, edits);
                 const item = items.find((each) => each.id === id);
                 return finish(io, values, { ...(item ?? { id }), warnings }, [item ? `Changed ${boxText(item)}.` : `Changed ${id}.`, ...warningLines(warnings)], afterWarnings(warnings, "orlan board (the board with the change)"));
             });
@@ -1287,14 +1581,14 @@ export const commands = {
             "of a deleted frame stay on the board, in the frame that frame was in.",
             "",
             "<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.",
+            "--topic <topic>  The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
         options: { ...agentOption, ...jsonOption, topic: { type: "string" } },
         positionals: [1, 100],
         run: (values, ids, io) => withAgent(values, async (api) => {
-            const { warnings } = await editBoard(api, values, ids.map((id) => ({ op: "delete", id })));
+            const { warnings } = await editBoard(api, values, io, ids.map((id) => ({ op: "delete", id })));
             return finish(io, values, { deleted: ids, warnings }, [
                 `Deleted ${ids.length === 1 ? "1 item" : `${ids.length} items`}: ${ids.join(", ")}. A person can undo it.`,
                 ...warningLines(warnings),
@@ -1302,7 +1596,7 @@ export const commands = {
         }),
     },
     "board edit": {
-        usage: "orlan board edit '<edits as JSON>' [--topic <topic>] [--agent <id>] [--json]",
+        usage: "orlan board edit '<edits as JSON>' [--topic <topic> | --new-topic <name>] [--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. A create can give its item",
@@ -1335,11 +1629,12 @@ export const commands = {
             "the error says what to change. The answer gives each item's id and its final place and size.",
             ...WARNINGS_HELP,
             "",
-            "--topic <topic>  The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            "--topic <topic>  The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
+            ...NEW_TOPIC_HELP,
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
-        options: { ...agentOption, ...jsonOption, topic: { type: "string" } },
+        options: { ...agentOption, ...jsonOption, topic: { type: "string" }, "new-topic": { type: "string" } },
         positionals: [1, 1],
         run: (values, [text], io) => {
             let edits;
@@ -1353,8 +1648,8 @@ export const commands = {
                 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, items, warnings } = await editBoard(api, values, edits);
-                return finish(io, values, { ids, items, warnings }, [
+                const { ids, items, warnings, newTopic } = await editBoard(api, values, io, edits);
+                return finish(io, values, { ids, items, warnings, ...(newTopic ? { newTopic } : {}) }, [
                     `Made ${ids.length} change${ids.length === 1 ? "" : "s"} in one step.`,
                     ...items.map((item) => `- ${boxText(item)}`),
                     ...warningLines(warnings),
@@ -1363,7 +1658,7 @@ export const commands = {
         },
     },
     "board mermaid": {
-        usage: "orlan board mermaid <file.mmd> [--frame <frame>] [--topic <topic>] [--agent <id>] [--json]",
+        usage: "orlan board mermaid <file.mmd> [--frame <frame>] [--topic <topic> | --new-topic <name>] [--agent <id>] [--json]",
         summary: "Draw a Mermaid flowchart on the board as real shapes, labeled arrows and frames.",
         details: [
             "Orlan reads the flowchart and draws it in one step, which a person can undo: a shape for each",
@@ -1401,17 +1696,24 @@ export const commands = {
             "",
             "<file.mmd>        The Mermaid file.",
             "--frame <frame>   Draw the diagram in this frame, by its id, from `orlan board`.",
-            "--topic <topic>   The topic id or its name. Default: the topic the agent used last, else its only topic.",
+            "--topic <topic>   The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
+            ...NEW_TOPIC_HELP,
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
-        options: { ...agentOption, ...jsonOption, topic: { type: "string" }, frame: { type: "string" } },
+        options: {
+            ...agentOption,
+            ...jsonOption,
+            topic: { type: "string" },
+            "new-topic": { type: "string" },
+            frame: { type: "string" },
+        },
         positionals: [1, 1],
         run: (values, [file], io) => withAgent(values, async (api) => {
             const source = await readFile(file, "utf8").catch((error) => {
                 throw new OrlanError(`Orlan cannot read ${quote(file)}: ${error.code ?? error.message}.`, undefined, "give the path of a Mermaid file, for example orlan board mermaid flow.mmd");
             });
-            const topicId = await topicOrDefault(api, values);
+            const { topicId, newTopic } = await writeTopic(api, values, io);
             const answer = await api.call("import_mermaid", {
                 topicId,
                 mermaid: source,
@@ -1427,7 +1729,7 @@ export const commands = {
             const made = [...count("shape", "shape"), ...count("arrow", "arrow"), ...count("frame", "frame")].join(", ");
             const prefixed = Object.entries(ids).filter(([from, to]) => from !== to);
             const where = typeof values.frame === "string" ? ` in frame ${values.frame}` : "";
-            return finish(io, values, { ids, items, warnings, replaced, ignored }, [
+            return finish(io, values, { ids, items, warnings, replaced, ignored, ...(newTopic ? { newTopic } : {}) }, [
                 `Drew ${quote(path.basename(file))}${where} in one step: ${made || "no items"}. A person can undo it.`,
                 ...(replaced.length > 0
                     ? [
@@ -1454,7 +1756,7 @@ export const commands = {
             "--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.",
+            "--topic <topic>   The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
@@ -1471,7 +1773,7 @@ export const commands = {
             const assignee = assigneeOption(config, values);
             const task = await api.call("record", {
                 kind: "task",
-                topicId: await topicOrDefault(api, values),
+                topicId: await topicOrDefault(api, values, io),
                 text,
                 ...(assignee ? { assignee } : {}),
                 ...(typeof values.thread === "string" ? { sourceThreadId: values.thread } : {}),
@@ -1525,7 +1827,7 @@ export const commands = {
             "",
             "--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.",
+            "--topic <topic>  The topic id or its name. Default: the topic open in Orlan now, else the one used last.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
@@ -1540,7 +1842,7 @@ export const commands = {
         run: (values, [title], io) => withAgent(values, async (api) => {
             const decision = await api.call("record", {
                 kind: "decision",
-                topicId: await topicOrDefault(api, values),
+                topicId: await topicOrDefault(api, values, io),
                 title,
                 ...(typeof values.body === "string" ? { body: values.body } : {}),
                 ...(typeof values.thread === "string" ? { sourceThreadId: values.thread } : {}),
@@ -1598,12 +1900,249 @@ export const commands = {
                         : "orlan brief (where the work stands)");
         }),
     },
+    brand: {
+        usage: "orlan brand [--save <folder>] [--agent <id>] [--json]",
+        summary: "Print the accepted brand kit of the organisation: colors, fonts, logos, tone, rules, formats.",
+        details: [
+            "Use it before you make a deck, a video, a carousel or a page, so the work is on brand with no brand",
+            "words in the prompt. Orlan gives only the sections people accepted. A section that waits for review",
+            "is named under draft, without its content: do not guess it. The references are work people like,",
+            "each with a note.",
+            "",
+            "--save <folder>  Also save the logo and font files of the kit in this folder.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: { ...agentOption, ...jsonOption, save: { type: "string" } },
+        positionals: [0, 0],
+        run: (values, _positionals, io) => withAgent(values, async (api, config) => {
+            const kit = await api.call("brand", {});
+            const saved = [];
+            if (typeof values.save === "string" && kit.files.length > 0) {
+                await mkdir(values.save, { recursive: true });
+                for (const file of kit.files) {
+                    const response = await fetch(file.url, {
+                        headers: { authorization: `Bearer ${api.token}`, ...sessionHeader() },
+                    }).catch((error) => {
+                        throw unreachable(config.server, error);
+                    });
+                    if (!response.ok) {
+                        throw new OrlanError(`The download of ${quote(file.name)} answered ${response.status}.`, undefined, "run the command again");
+                    }
+                    // Two files with one name (a light and a dark logo.png) are both kept.
+                    const name = saved.includes(path.join(values.save, file.name)) ? `${file.id}-${file.name}` : file.name;
+                    const target = path.join(values.save, path.basename(name));
+                    await writeFile(target, Buffer.from(await response.arrayBuffer()));
+                    saved.push(target);
+                }
+            }
+            const { sections } = kit;
+            const lines = [`Brand kit v${kit.version}. Only the accepted sections are here.`];
+            if (sections.colors) {
+                lines.push(`colors: ${sections.colors.items.map((color) => `${color.name} ${color.hex}${color.use ? ` (${color.use})` : ""}`).join(", ") || "none"}`);
+            }
+            if (sections.fonts) {
+                const font = (role) => sections.fonts?.[role].family || "not set";
+                lines.push(`fonts: heading ${font("heading")}, body ${font("body")}`);
+            }
+            for (const file of kit.files)
+                lines.push(`- ${file.role}: ${quote(file.name)} (${file.mime})`);
+            if (sections.tone)
+                lines.push(`tone: ${sections.tone.text || "not set"}`);
+            if (sections.rules) {
+                for (const rule of sections.rules.items)
+                    lines.push(`${rule.kind === "do" ? "do" : "do not"}: ${rule.text}`);
+            }
+            if (sections.formats) {
+                const { video, deck, carousel } = sections.formats;
+                lines.push(`formats: video ${video.join(", ") || "-"}; deck ${deck.join(", ") || "-"}; carousel ${carousel.join(", ") || "-"}`);
+            }
+            if (kit.draft.length)
+                lines.push(`draft (waits for review, not for use): ${kit.draft.join(", ")}`);
+            for (const ref of kit.references) {
+                lines.push(`reference ${ref.kind}: ${ref.url ?? quote(ref.file?.name ?? "")} - ${quote(ref.note)}`);
+            }
+            for (const target of saved)
+                lines.push(`Saved ${quote(target)}.`);
+            // What people asked this agent to change (F141): each request ends with its own next_step line.
+            const requests = kit.requests ?? [];
+            for (const request of requests)
+                lines.push("", ...brandRequestLines(request));
+            return finish(io, values, { ...kit, ...(typeof values.save === "string" ? { saved } : {}) }, lines, requests.length > 0
+                ? "answer each request above with orlan brand draft"
+                : kit.files.length > 0 && typeof values.save !== "string"
+                    ? "orlan brand --save brand (the logo and font files)"
+                    : "make the work with this kit");
+        }),
+    },
+    "brand draft": {
+        usage: 'orlan brand draft <section> (--file <path> | --data <json>) [--note "<text>"] [--request <id>] [--agent <id>] [--json]',
+        summary: "Write one section of the brand kit as a draft for people to review and accept.",
+        details: [
+            "Draft the kit from the website, the logo and font files and the files people give you: one call for",
+            "each section. Each section waits as a draft until a person accepts it on the Brand kit page; an agent",
+            "never accepts one. A draft answers your open requests on that section (orlan brand lists them).",
+            "",
+            "<section>  colors, fonts, logos, tone, rules or formats. The content of each, as JSON:",
+            '  colors   {"items": [{"name": "Vivid Blue", "hex": "#0679FF", "use": "Buttons"}]}',
+            '  fonts    {"heading": {"family": "Avenir Next", "fileIds": []}, "body": {"family": "Inter", "fileIds": []}}',
+            '  logos    {"light": "<file id>", "dark": null, "mark": null}',
+            '  tone     {"text": "Short sentences. Say what the customer gets."}',
+            '  rules    {"items": [{"kind": "do", "text": "Captions on every video."}, {"kind": "dont", "text": "..."}]}',
+            '  formats  {"video": ["16:9", "9:16"], "deck": ["16:9"], "carousel": ["4:5"]}',
+            "  A file id comes from orlan brand upload.",
+            "",
+            "--file <path>    The content in a JSON file.",
+            "--data <json>    The content as JSON text.",
+            "--note <text>    Where you took it from, or what you changed. People read it in the kit versions.",
+            "--request <id>   The request you answer, for example brand_12. Default: your open requests on the section.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: {
+            ...agentOption,
+            ...jsonOption,
+            file: { type: "string" },
+            data: { type: "string" },
+            note: { type: "string" },
+            request: { type: "string" },
+        },
+        positionals: [1, 1],
+        run: async (values, [section], io) => {
+            const file = typeof values.file === "string" ? values.file : undefined;
+            const data = typeof values.data === "string" ? values.data : undefined;
+            if ((file === undefined) === (data === undefined)) {
+                throw new OrlanError("Give the content with --file or --data, one of them.", undefined, `orlan brand draft ${section} --file <path to the JSON content>`);
+            }
+            const text = file === undefined ? data : await readFile(file, "utf8");
+            let content;
+            try {
+                content = JSON.parse(text);
+            }
+            catch {
+                throw new OrlanError(`The content is not JSON${file ? ` in ${quote(file)}` : ""}.`, undefined, "orlan brand draft --help shows the content of each section");
+            }
+            return withAgent(values, async (api) => {
+                const answer = await api.call("brand_draft", {
+                    section,
+                    content,
+                    ...(typeof values.note === "string" ? { note: values.note } : {}),
+                    ...(typeof values.request === "string" ? { requestId: values.request } : {}),
+                });
+                const { nextStep, ...rest } = answer;
+                return finish(io, values, rest, [
+                    `Wrote ${answer.section} as a draft in brand kit v${answer.version}. It waits for a person to accept it.` +
+                        (answer.answered ? ` Answered ${answer.answered.join(", ")}.` : ""),
+                ], nextStep);
+            });
+        },
+    },
+    "brand upload": {
+        usage: "orlan brand upload <path> --kind logo|font [--agent <id>] [--json]",
+        summary: "Upload a logo or a font file for the brand kit, and print its file id.",
+        details: [
+            "A logo is a PNG or a JPEG file; a font is an .otf, .ttf, .woff or .woff2 file. Name the file id in",
+            "the logos or the fonts section with orlan brand draft.",
+            "",
+            "--kind <kind>  logo or font. Required.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: { ...agentOption, ...jsonOption, kind: { type: "string" } },
+        positionals: [1, 1],
+        run: async (values, [filePath], io) => {
+            const kind = values.kind;
+            if (kind !== "logo" && kind !== "font") {
+                throw new OrlanError("Add --kind logo or --kind font.", undefined, `orlan brand upload ${filePath} --kind logo`);
+            }
+            const form = new FormData();
+            form.set("file", await openAsBlob(filePath), path.basename(filePath));
+            return withAgent(values, async (api) => {
+                const uploaded = await api.postForm("/api/agent/brand/files", { kind }, form, "the upload");
+                return finish(io, values, uploaded, [`Uploaded ${quote(uploaded.name)} as ${uploaded.kind} file ${uploaded.id}.`], `name ${uploaded.id} in the ${kind === "logo" ? "logos" : "fonts"} section with orlan brand draft`);
+            });
+        },
+    },
+    studio: {
+        usage: "orlan studio [<skill> [<step>]] [--agent <id>] [--json]",
+        summary: "Print one step of a studio skill (video, deck, carousel, walkthrough): the steps come from Orlan.",
+        details: [
+            "A studio skill makes a piece of work on this computer in five steps: brief, script, build, render,",
+            "review. Orlan gives the steps only to a signed-in agent, one step at a time: read each step when you",
+            "come to it, and follow it. Read the brand kit first (orlan brand).",
+            "",
+            "orlan studio                  The skills, with their steps and helper scripts.",
+            "orlan studio <skill>          The steps and the helper scripts of one skill.",
+            "orlan studio <skill> <step>   The text of one step.",
+            "",
+            "Get the helper scripts of a skill with orlan studio pull <skill>.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: { ...agentOption, ...jsonOption },
+        positionals: [0, 2],
+        run: (values, [skill, step], io) => withStudio(values, async (api) => {
+            if (!skill) {
+                const { skills } = await api.call("studio", {});
+                const lines = skills.length
+                    ? skills.map((each) => `${each.skill}: ${skillLine(each)}`)
+                    : ["Orlan has no studio skills yet."];
+                return finish(io, values, { skills }, lines, "orlan studio <skill> brief");
+            }
+            if (!step) {
+                const found = await api.call("studio", { skill });
+                const next = `${found.scripts.length ? `orlan studio pull ${skill}, then ` : ""}orlan studio ${skill} brief`;
+                return finish(io, values, { ...found }, [`${skill}: ${skillLine(found)}`], next);
+            }
+            const answer = await api.call("studio", { skill, step });
+            const after = STUDIO_STEPS[STUDIO_STEPS.indexOf(step) + 1];
+            return finish(io, values, answer, [answer.text.trimEnd()], after
+                ? `orlan studio ${skill} ${after}`
+                : "post the work: orlan files add <file>, or orlan files push for a new version");
+        }),
+    },
+    "studio pull": {
+        usage: "orlan studio pull <skill> [--to <folder>] [--agent <id>] [--json]",
+        summary: "Write the helper scripts of a studio skill into the project, from Orlan.",
+        details: [
+            "The steps of the skill name these scripts. Pull them again for the newest copy: each file is written",
+            "again, and files that you added stay.",
+            "",
+            "--to <folder>  The folder to write the scripts in. Default: .orlan/studio/<skill> in this folder.",
+            AGENT_TOKEN_HELP,
+            JSON_HELP,
+        ],
+        options: { ...agentOption, ...jsonOption, to: { type: "string" } },
+        positionals: [1, 1],
+        run: (values, [skill], io) => withStudio(values, async (api) => {
+            const { files } = await api.call("studio", { skill, scripts: true });
+            const folder = path.resolve(typeof values.to === "string" ? values.to : path.join(".orlan", "studio", `${skill}`));
+            for (const file of files) {
+                const target = path.resolve(folder, file.path);
+                // A path from the server stays in the folder.
+                if (!target.startsWith(`${folder}${path.sep}`)) {
+                    throw new OrlanError(`Orlan named a script path outside the folder: ${quote(file.path)}.`, "internal_error");
+                }
+                await mkdir(path.dirname(target), { recursive: true });
+                await writeFile(target, Buffer.from(file.contentBase64, "base64"));
+                await chmod(target, file.executable ? 0o755 : 0o644);
+            }
+            return finish(io, values, { skill, folder, files: files.map((file) => file.path) }, [
+                `Pulled ${files.length} helper scripts of ${skill} into ${folder}.`,
+                ...files.map((file) => `- ${file.path}`),
+            ], `orlan studio ${skill} brief`);
+        }),
+    },
     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, 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),",
+            "For the start of a task: one short answer, in one plain HTTP call. The topic is the one the person",
+            "has open in Orlan now, and the first lines say so. When the agent cannot reach that topic, they say",
+            "so, give the step that grants it, and name the topic the agent works in instead: the newer of the",
+            "one it used last and the one the person opened last, else its only topic. Other commands with no",
+            "--topic use the same topic; in one session they keep the topic of the last call for 5 minutes.",
+            "It lists the open requests (`orlan inbox` prints them in full),",
             "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.",
             "",
@@ -1614,7 +2153,9 @@ export const commands = {
         options: { ...agentOption, ...jsonOption, topic: { type: "string" } },
         positionals: [0, 0],
         run: (values, _positionals, io) => withAgent(values, async (api) => {
-            const { lines, nextStep, ...answer } = await api.get("/api/agent/brief", { topic: values.topic }, "the brief");
+            const { lines, nextStep, ...answer } = await api.get("/api/agent/brief", 
+            // The start of a task: Orlan takes the topic the person has open now again (F123).
+            { topic: values.topic, start: "true" }, "the brief");
             // The lines end with Orlan's next_step line.
             io.out(values.json ? JSON.stringify({ ...answer, next_step: nextStep }) : lines.join("\n"));
             return 0;
@@ -1632,7 +2173,7 @@ export const commands = {
         options: { ...agentOption, ...jsonOption, new: { type: "boolean" } },
         positionals: [0, 0],
         run: (values, _positionals, io) => withAgent(values, async (api) => {
-            const { requests, stopped } = await api.get("/api/inbox", { new: values.new ? "true" : undefined }, "the inbox");
+            const { requests, stopped, brand = [], } = await api.get("/api/inbox", { new: values.new ? "true" : undefined }, "the inbox");
             // A person stopped this session on the board (D109): the stop, also with --new.
             if (stopped) {
                 const [line = "", step = ""] = stopped.lines;
@@ -1644,20 +2185,23 @@ export const commands = {
                 return 0;
             }
             // --new with no request prints nothing.
+            // The brand kit requests (F141) come after the topic requests, each with its own next_step line.
+            const all = [...requests, ...brand];
             if (values.json) {
-                if (requests.length > 0 || !values.new) {
-                    const last = requests.at(-1);
+                if (all.length > 0 || !values.new) {
+                    const last = all.at(-1);
                     printJson(io, {
                         requests: requests.map((each) => each.request),
+                        ...(brand.length > 0 ? { brand: brand.map((each) => each.request) } : {}),
                         next_step: last ? deliveryStep(last) : NOTHING_STEP,
                     });
                 }
             }
             else {
-                if (requests.length === 0 && !values.new)
+                if (all.length === 0 && !values.new)
                     io.out(`No open requests.\nnext_step: ${NOTHING_STEP}`);
                 // Each request ends with its own next_step line. The line on quoted text comes once.
-                for (const [index, delivery] of requests.entries()) {
+                for (const [index, delivery] of all.entries()) {
                     if (index > 0)
                         io.out("");
                     const [first = "", ...rest] = delivery.lines;
@@ -1723,7 +2267,7 @@ export const commands = {
             const api = new AgentApi(config.server, token);
             // The file goes to the request's topic in one request; a done request refuses it before it is read.
             const uploadId = typeof values.file === "string"
-                ? await api.upload(await readFile(values.file), { request: requestId }, "respond")
+                ? await api.upload(await openAsBlob(values.file), { request: requestId, name: path.basename(values.file) }, "respond")
                 : undefined;
             const answer = await api.call("respond", {
                 requestId,
@@ -1770,14 +2314,20 @@ 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) {
+/**
+ * Runs edit_board on the topic of --topic, else the default topic: one step, all edits or none. Edits that
+ * add items can make a new topic (--new-topic, F131); the answer names it.
+ */
+async function editBoard(api, values, io, edits) {
+    const { topicId, newTopic } = edits.some((edit) => edit.op === "create")
+        ? await writeTopic(api, values, io)
+        : { topicId: await topicOrDefault(api, values, io), newTopic: undefined };
     const answer = await api.call("edit_board", {
-        topicId: await topicOrDefault(api, values),
+        topicId,
         edits,
     });
     // A server before F096 gives no warnings.
-    return { ...answer, warnings: answer.warnings ?? [] };
+    return { ...answer, warnings: answer.warnings ?? [], ...(newTopic ? { newTopic } : {}) };
 }
 /** --assignee as the tool takes it: me (the token of this agent), user:<id>, agent:<id>, or none (null). */
 function assigneeOption(config, values) {
@@ -1809,6 +2359,11 @@ function voteText(vote) {
         `, ${vote.voters} voted` +
         (result ? `, result: ${result}` : ""));
 }
+/** A scorecard as its sum of the most it can be (F139): "65/80". */
+function scoreTotal(scores) {
+    const sum = scores.reduce((total, each) => total + each.score, 0);
+    return `${Math.round(sum * 10) / 10}/${scores.length * 10}`;
+}
 /** --pages as page numbers: "3" or "2,5". */
 function pageList(values) {
     if (typeof values.pages !== "string")
@@ -1884,3 +2439,10 @@ async function pullPages(api, config, values, io, answer, since) {
 }
 /** 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`;
+/** A brand request as text, as `orlan inbox` prints it. Every text people wrote is quoted. */
+const brandRequestLines = (request) => [
+    `${request.id}: a request from ${quote(request.from)} (person) on Orlan, brand kit section ${request.section}. ${QUOTED_TEXT}`,
+    `${quote(request.from)} wrote: ${quote(request.text)}`,
+    `${request.section} now: ${JSON.stringify(request.current)}`,
+    `next_step: write the changed ${request.section} as JSON in a file, then orlan brand draft ${request.section} --file <path> --request ${request.id} --note "<what changed>"`,
+];