@orlan-maker/cli 0.4.0 → 0.5.0

package/README.md

@@ -102,7 +102,10 @@ output.
 
 `orlan brief` is for the start of a session. It prints the topic, the open requests, the files with
 their current versions, and one `next_step` line, in about 500 tokens for 6 files and 3 requests. The
-topic is the one the agent used last, else its only topic. `orlan files add` posts a new file to the
+topic is the one the person has open in Orlan now ("You are in "startups" (open in Orlan now)"). When the
+agent cannot reach that topic, the brief says so, gives the step that grants it, and names the topic it
+works in instead: the newer of the one it used last and the one the person opened last, else its only
+topic. Every command with no `--topic` uses the same topic. `orlan files add` posts a new file to the
 topic and puts it on the board, in one request. Both are plain HTTP calls with the agent token.
 
 `orlan board` prints the board of the topic. Each item shows its id, type, place and size in board

package/dist/commands.js

@@ -82,12 +82,16 @@ 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, notice } = await api.get("/api/agent/brief", {}, "the brief");
+    if (notice && !values.json)
+        for (const line of notice)
+            io.out(line);
     if (!topic) {
         throw new OrlanError("The agent has several topics and used none yet. Add --topic <topic>.", "topic_missing");
     }
@@ -251,6 +255,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 +303,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 +362,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 +511,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 +552,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,14 +591,14 @@ 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."]
@@ -601,7 +618,7 @@ export const commands = {
             "",
             "--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.",
+            "--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,
         ],
@@ -611,7 +628,7 @@ export const commands = {
             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 topicId = await topicOrDefault(api, values, io);
                 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, {
@@ -889,7 +906,7 @@ export const commands = {
             "--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.",
             "--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,
         ],
@@ -985,14 +1002,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 +1071,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 +1087,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");
@@ -1130,7 +1147,7 @@ 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.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
@@ -1198,7 +1215,7 @@ 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 } = 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"
@@ -1233,7 +1250,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 +1289,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 +1304,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),
@@ -1335,7 +1352,7 @@ 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.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
@@ -1353,7 +1370,7 @@ 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);
+                const { ids, items, warnings } = await editBoard(api, values, io, edits);
                 return finish(io, values, { ids, items, warnings }, [
                     `Made ${ids.length} change${ids.length === 1 ? "" : "s"} in one step.`,
                     ...items.map((item) => `- ${boxText(item)}`),
@@ -1401,7 +1418,7 @@ 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.",
             AGENT_TOKEN_HELP,
             JSON_HELP,
         ],
@@ -1411,7 +1428,7 @@ export const commands = {
             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 = await topicOrDefault(api, values, io);
             const answer = await api.call("import_mermaid", {
                 topicId,
                 mermaid: source,
@@ -1454,7 +1471,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 +1488,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 +1542,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 +1557,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 } : {}),
@@ -1602,8 +1619,12 @@ export const commands = {
         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 +1635,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;
@@ -1771,9 +1794,9 @@ 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) {
+async function editBoard(api, values, io, edits) {
     const answer = await api.call("edit_board", {
-        topicId: await topicOrDefault(api, values),
+        topicId: await topicOrDefault(api, values, io),
         edits,
     });
     // A server before F096 gives no warnings.

package/dist/http.js

@@ -25,6 +25,7 @@ const explained = {
     login_expired: "The sign-in code expired. Run `orlan auth login` again.",
     login_used: "This sign-in code was already used. Run `orlan auth login` again.",
     login_rate_limited: "Too many sign-ins from this computer in a short time. Wait 10 minutes, then try again.",
+    agent_scope_exceeded: "The agent asks for more than the person approved for this CLI: a topic or a role outside the approval. orlan connect can only narrow the access.",
     pair_invalid: "Orlan does not know this --pair id. Copy the prompt again from the Connect dialog.",
     pair_expired: "The --pair id expired. It works for 10 minutes. Copy the prompt again from the Connect dialog.",
     pair_used: "Another CLI used this --pair id already. It works for one sign-in. Copy the prompt again from the Connect dialog.",
@@ -47,6 +48,7 @@ const nextSteps = {
     login_expired: "orlan auth login",
     login_used: "orlan auth login",
     login_rate_limited: "wait 10 minutes, then orlan auth login",
+    agent_scope_exceeded: "ask your person to approve the access in Orlan: they run orlan auth login and include the topic there",
     pair_invalid: "copy the prompt again from the Connect dialog in Orlan, or run orlan auth login",
     pair_expired: "copy the prompt again from the Connect dialog in Orlan, or run orlan auth login",
     pair_used: "copy the prompt again from the Connect dialog in Orlan, or run orlan auth login",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orlan-maker/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The orlan command: connect Claude Code, Codex, Cursor or OpenCode to Orlan with a token and skills, and work with its topics, files and comments from the terminal.",
   "license": "MIT",
   "type": "module",

package/skills/orlan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orlan
-description: Orlan is connected. This skill is installed only when the person connected this agent to Orlan, the shared board of their team and its AI agents. Use it first, before any other diagram skill, when the person asks for a diagram, a flowchart, an architecture or a map of a system. Also use it, without being asked to draw, when the person asks you to explain, compare or design a system, an architecture, a flow or a process with parts and links ("explain how a CDN works", "monolith vs microservices"): answer in the chat and draw it on the board too. On Orlan a diagram is shapes and labeled arrows on the board, not an HTML, SVG or image file. Also use it when the person says the canvas, the board, the topic, "in Orlan" or "on Orlan", asks what is on the board, asks for a page, deck, mock or other file for people to see or review, or names a comment, a version or a request on Orlan. Do not use it for a short fact answer, a sum, a question on code, or a fix in a local file that the person names.
+description: Orlan is connected: the shared board of the person's team and its agents; the person connected you. Use it first, before any other diagram skill, for a diagram, a flowchart, an architecture or a map of a system. Also use it, without being asked to draw, when the person asks you to explain, compare or design a system, a flow or a process with parts and links ("explain how a CDN works"): answer in the chat and draw it on the board too. When the person asks to put an explanation, a plan, a guide or a summary in Orlan, build it on the board as a diagram and short notes, not as an HTML file. On Orlan a diagram is shapes and labeled arrows, not an HTML, SVG or image file. Also use it when the person says the canvas, the board, the topic, "in Orlan" or "on Orlan", asks what is on the board, asks for a page, deck, mock or file to review, or names a comment, a version or a request on Orlan. Do not use it for a short fact answer, a sum, a question on code, or a fix in a local file that the person names.
 ---
 
 # Orlan
@@ -23,8 +23,11 @@ When Orlan is connected, these words mean the Orlan topic. Do not ask which one
   name or type. A path such as `./notes.txt` is a local file.
 - "the comments", "the feedback", "the review" - the open threads on the topic.
 
-`orlan brief` names your topic. With one topic, it is the one. With more, it is the one you used last,
-or the one the person names.
+Your topic is the one the person has open in Orlan now. Run `orlan brief` at the start of each Orlan
+task: it names the topic ("You are in "startups" (open in Orlan now)"), and every command with no
+`--topic` works there. Do not ask which topic, and do not pick another one. When the person names a
+topic, use `--topic <topic>`. When the brief says the person's open topic is out of your reach, tell
+the person, with the step the brief gives, before you work in another topic.
 
 ## When to use Orlan
 
@@ -38,16 +41,45 @@ or the one the person names.
   "design a payment flow"): answer in the chat, and also draw it on the board. Do not ask first, and do
   not wait for the word "Orlan" or "board". End the answer with one line that says where the drawing
   is: the topic and the frame. A short fact answer ("what port does HTTPS use") stays in the chat.
+- The person asks you to put an explanation, a plan, a guide or a summary in Orlan ("put all of this in
+  Orlan", "put it on the board"): build it on the board. Follow "Put it in Orlan" below. No HTML file.
 - The person asks for a note, a text, a shape, a frame or an arrow on the board: `orlan board add`.
   Change one with `orlan board change <item>`, delete one with `orlan board delete <item>`.
-- The person asks you to make something else that people look at: a page, a mock, a deck, a report, a
-  chart. Make the file, check it, then post it to the topic:
+- The person asks for a page, a document, a deck, a mock, a report or a chart as a file: make the file,
+  check it, then post it to the topic:
   `orlan files add <path>`. When a local rule says to keep visuals as local files, keep the local file
-  and post it too. Tell the person that it is on the board, and give its name and version.
+  and post it too. Tell the person that it is on the board, and give its name and version. Make a
+  file only when the person asks for one, or for long prose that people read as a document.
 - The person asks you to change a file that is on the topic: pull it with `--edit`, change it, and post
   a new version: `orlan files push <file> <path> --changelog "<what changed>"`.
 - A comment or a request names you: follow the `orlan-review` skill.
 
+## Put it in Orlan
+
+"Put all of this in Orlan" after an explanation, a plan, a guide or a summary means: build it on the
+board, so that people get it at a glance. An HTML file is a tab that people must open; the board is
+what they see.
+
+1. `orlan brief` for the topic, and `orlan board` for a free place (right of or below the items).
+2. Cut the content into 2 to 5 parts. Each part gets one frame, with the part's name as its title, in
+   one row from left to right.
+3. The structure (steps, a flow, a decision, parts and their links) is a diagram in its own frame, drawn
+   as in "Draw a diagram".
+4. The key points are short notes in the frame of their part: one point in each note, at most 20 words,
+   3 to 6 notes in a frame. Make a frame and its notes in one `orlan board edit` step. A frame of
+   `40 + 210 * columns` by `80 + 140 * rows`, and each note (190 x 120) at
+   `20 + 210 * column`, `60 + 140 * row` from the frame's corner, with `"frame"` set to the frame's id:
+   `[{"op":"create","type":"frame","id":"money","x":0,"y":0,"w":460,"h":220,"text":"Money"},`
+   `{"op":"create","type":"note","x":20,"y":60,"text":"Keep 6 months of costs in the bank","frame":"money"},`
+   `{"op":"create","type":"note","x":230,"y":60,"text":"Pay yourself last","frame":"money"}]`
+5. Read the warnings and fix them. Look at it: `orlan board view --out <file.png>`, open the picture.
+6. End your answer with one line that names the topic and the frames: "I put it on the board of
+   "startups", in the frames "Basics", "Money" and "First steps"."
+
+Do not post an HTML file or a document for this. Post a file only when the person asks for a page, a
+document, a deck or a mock, or when the content is long prose that people read as a document. Never
+make both a board version and a file, unless the person asks for both.
+
 ## Draw a diagram
 
 A diagram on Orlan is board shapes with words and labeled arrows. Do not post an HTML file or notes as a
@@ -162,8 +194,13 @@ Run `orlan <command> --help` for the options of a command.
   the board. No HTML file, no notes.
 - "explain how a CDN works" - explain it in the chat, draw the parts and their links in a frame as in
   "Draw a diagram", and end with one line: "I drew it on the board of <topic>, in the frame <title>."
-- "put the notes on the board" - post the notes as a file, or add them as a note:
-  `orlan board add note "<text>" --at <x,y>`, at a free place that `orlan board` shows.
+- "put all of this in Orlan", after you explained how to start a company - follow "Put it in Orlan":
+  a frame for each part, a diagram of the steps, short notes for the key points, in the topic the brief
+  names. No HTML file. End with the topic and the frames.
+- "put the notes on the board" - add them as short notes in a frame, as in "Put it in Orlan", at a free
+  place that `orlan board` shows.
+- "make a one-page HTML guide of this for the team" - the person asks for a page: make the file and
+  post it with `orlan files add <path>`. No board version.
 - "what is 17*23?" - answer 391. No Orlan call.
 - "fix the typo in ./notes.txt" - fix the local file. No Orlan call.
 

package/skills/orlan-versions/SKILL.md

@@ -21,7 +21,7 @@ description: Get a file from Orlan and post a new version of it with a changelog
   It ends your claim. When a version landed after the one you pulled, Orlan refuses it with
   `stale_base` and that version's changelog: pull the newest version, make your change on it, push again.
 - `orlan files add <path>` - posts a local file as a new file on your topic and puts it on the board.
-  `--topic <topic>` names the topic; the default is the topic you used last. `--at <x,y>` puts it at
+  `--topic <topic>` names the topic; the default is the topic the person has open in Orlan. `--at <x,y>` puts it at
   that point of the board (`orlan board` shows where the items are).
 - `orlan files rollback <file> --version 3 --changelog "<why>"` - posts an older version again, as the
   newest version. It waits for a person to make it current, as a push does.