@orlan-maker/cli 0.3.0 → 0.5.0

package/README.md

@@ -17,20 +17,21 @@ orlan connect --agent claude-code
 ```
 
 - `orlan auth login` shows a code and opens the approval page in your browser. Sign in, check the
-  code, choose the organisation, and the topics and role your agents get. The command waits for the
+  code, choose the organisation, and what your agents get: one topic, or all topics of the organisation
+  (also the topics made later). Details has a checkbox for each topic and the agent role. The command waits for the
   approval (codes work for 10 minutes). The CLI token goes to the OS keychain (macOS keychain, or the
   Secret Service on Linux), else to `credentials.json` in the config folder, readable by you only.
   `--server <url>` signs in to another Orlan server; `--no-browser` only prints the address.
 - `orlan auth login --pair <id>` is the sign-in that the prompt of the Connect dialog in the Orlan web
   app runs. It shows the code and opens no page: the code waits in the Connect dialog. Check that the
-  dialog shows the same code, choose the topics and role your agents get, then approve it there. A
+  dialog shows the same code, choose this topic or all topics for your agents, then approve it there. A
   `--pair` id works for one sign-in, for 10 minutes. A second CLI with the same id stops with
   `pair_used`, and the dialog warns. A denied sign-in stops the CLI with `login_denied`.
 - `orlan connect` makes an agent token and keeps it in the keychain. The agent then works on Orlan
   with the `orlan` command. Only an admin of the organisation connects agents. The command writes the
   skills where the agent reads skills (table below), and tests the token with one plain HTTP call.
   It writes nothing else: no plugin, no hook, no MCP entry, and no instruction file such as
-  `CLAUDE.md` or `AGENTS.md`. `--topic` and `--role` change the topics and the role of the agent.
+  `CLAUDE.md` or `AGENTS.md`. `--topic` limits the agent to the named topics, and `--role` changes its role.
 - The skills are `orlan`, `orlan-review` and `orlan-versions`. `orlan` tells the agent what Orlan is:
   "the canvas", "the board" and "the topic" mean the Orlan topic, and a file the person asks for goes
   on the topic. A diagram is board shapes with labeled arrows, never an HTML file or notes: the agent
@@ -73,8 +74,8 @@ orlan comment <thread> "<text>" | --file <file> --page <n> [--region <x,y,w,h>]
 orlan comments resolve <thread> [--topic <topic>]
 orlan board [--topic <topic>]
 orlan board view --out <file.png> [--frame <frame>] [--topic <topic>]
-orlan board add note|text|frame|shape ["<text>"] --at <x,y> [--size <w,h>] [--kind <kind>] [--color <color>] [--frame <frame>|none] | arrow --from <item> --to <item> [--text "<label>"] [--id <id>]
-orlan board change <item> [--text "<text>"] [--at <x,y>] [--size <w,h>] [--kind <kind>] [--color <color>] [--from <item>|none] [--to <item>|none] [--frame <frame>|none]
+orlan board add note|text|frame|shape ["<text>"] --at <x,y> [--size <w,h>] [--text-color <color>] [--kind <kind>] [--color <color>] [--frame <frame>|none] | arrow --from <item> --to <item> [--text "<label>"] [--id <id>]
+orlan board change <item> [--text "<text>"] [--at <x,y>] [--size <w,h>] [--text-color <color>] [--kind <kind>] [--color <color>] [--from <item>|none] [--to <item>|none] [--frame <frame>|none]
 orlan board delete <item>...
 orlan board edit '<edits as JSON>'
 orlan board mermaid <file.mmd> [--frame <frame>] [--topic <topic>]
@@ -101,12 +102,15 @@ 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
-coordinates, and its text. A note, a text and a shape also show a text size other than M, a shape its kind and
-color, a file its name and pages, and an arrow the items it links and its label. An item in a frame
+coordinates, and its text. A note, a text and a shape also show a text size other than M and a text color other
+than ink (`text color red`), a shape its kind and color, a file its name and pages, and an arrow the items it links and its label. An item in a frame
 shows `in frame <id>`. Then come the timer, the open vote and the last vote with its result, and the
 open tasks. People vote; an agent reads the vote, it does not vote. `orlan board add` adds a note, a
 text, a shape, a frame or an arrow, `orlan board change` changes an item's text, place, size, a shape's
@@ -119,7 +123,10 @@ command is one step that a person can undo on the board. `orlan board edit` take
 and makes them in one step, all or none. A create can give its item an id of its own (`"id":"api"`, also
 `orlan board add --id api`), so the arrow of the same step, and a later command, name it. Without
 `--size <w,h>` or `w`, `h`, a note is 190x120, a text 320x40, a shape 160x100 and a frame 480x320. A note, a
-text and a shape take a text size: `--size S`, `M`, `L` or `XL` (`"size"` in the JSON; default M). Their
+text and a shape take a text size: `--size S`, `M`, `L` or `XL` (`"size"` in the JSON; default M), and a
+text color for their words: `--text-color` ink (default), white, gray, blue, teal, green, yellow, orange or
+red (`"textColor"` in the JSON). The names are the shape colors; the words draw in a strong shade of each
+that reads on a note, a shape and the board (white reads only on a dark background). Their
 box grows to fit their words, so no word is cut and no word spills out: a note and a shape grow in
 height, and a text is as high as its lines. With no width, a text is as wide as its words (at most 20
 em), and a shape grows wider for its words (at most twice its default width, 320). `orlan board add`, `orlan board
@@ -143,13 +150,17 @@ rounded, `A((text))` an ellipse, `A{text}` a diamond, `A[(text)]` a cylinder and
 `A[[text]]`, `A>text]`, `A{{text}}`, `A[\text\]` and `A(((text)))` take the nearest of these. A label goes as
 `A -->|label| B` or `A -- label --> B`; `-->`, `---`, `-.->` and `==>` all become arrows, and `A & B --> C` and
 chains work. `subgraph id [title] ... end` is a frame, also in another frame. A fill from `style`, `classDef`,
-`class` or `:::` takes the nearest shape color. `linkStyle`, `click` and a `direction` in a subgraph are left
+`class` or `:::` takes the nearest shape color. `A ~~~ B` places B after A and draws no arrow. A `direction` in a
+subgraph, and a link to a subgraph id, work when no link goes out of that subgraph, as in Mermaid. `linkStyle`,
+`click` and a `direction` in a subgraph that a link goes out of are left
 out, and the answer says so. The layout is in layers (dagre), each box as large as its words need, with no
 overlap and no arrow across a box for the usual diagrams; the answer lists drawing warnings when it could not
-avoid one. The diagram goes in free space right of the items on the board, and nothing on the board moves.
+avoid one. Subgraphs that are stacked or side by side line up (one left edge and width, or one top and height)
+with even gaps, and subgraphs that no link joins keep the order of the file. The diagram goes in free space right of the items on the board, and nothing on the board moves.
 Each node and subgraph keeps its Mermaid id as its item id, so `orlan board change <id>` changes it later; an
 id that is on the board already gets a prefix (`m2-`, `m3-`), and the answer gives it. With
-`--frame <frame>`, the diagram goes in that frame, which grows to hold it, and it replaces the items this agent
+`--frame <frame>`, the diagram goes in that frame, which then fits it with 24 px of room (it grows and shrinks;
+a person's items in it stay in it), and it replaces the items this agent
 drew in that frame before: run it again after a change to the file, and the diagram changes in place, at the
 same place and with the same ids. A person's items in the frame stay where they are. Another Mermaid diagram (`sequenceDiagram`,
 `classDiagram` and others) is refused with `mermaid_unsupported`, and a syntax error with `mermaid_invalid` and

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");
     }
@@ -107,6 +111,8 @@ export const SHAPE_KINDS_HELP = "rectangle, rounded, ellipse, diamond, cylinder,
 export const SHAPE_COLORS_HELP = "white, gray, blue, teal, green, yellow, orange, red";
 /** The text sizes of a note, a text and a shape (F095): textSizes of @orlan/board. A test keeps them equal. */
 export const TEXT_SIZES_HELP = "S, M, L, XL";
+/** The text colors of a note, a text and a shape (F112): textColorNames of @orlan/board. A test keeps them equal. */
+export const TEXT_COLORS_HELP = "ink, white, gray, blue, teal, green, yellow, orange, red";
 /** How the boxes grow (F095), as applyEdits of @orlan/board makes them. */
 const GROW_HELP = [
     "A note, a text and a shape grow to fit their words, so no word is cut: a note and a shape grow in",
@@ -118,8 +124,10 @@ const GROW_HELP = [
 const WARNINGS_HELP = [
     "After each change, the answer lists warnings about the items it made or changed: two items overlap,",
     "an item lies partly or all outside the frame it is in, an arrow crosses an item that is not one of",
-    "its ends, an end of an arrow points at no item, an arrow label covers an item, or a frame title is",
-    "wider than its frame. Each",
+    "its ends, an end of an arrow points at no item, an arrow label covers an item, two arrows draw on",
+    "one line or their labels cover each other, a frame title is wider than its frame, frames are almost",
+    "but not quite lined up, stacked frames have uneven gaps, a frame is much larger than the items in it,",
+    "or a text has words much larger than the words of the shapes in its frame. Each",
     "warning names the items and says what to change. A warning never stops a change. With --json they",
     'are "warnings": [{"kind","ids","text"}], and [] when the drawing is clean.',
 ];
@@ -194,6 +202,28 @@ function numbersOption(values, option, count) {
     }
     return parts;
 }
+/**
+ * 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.
+ */
+function arrowEndOption(values, option) {
+    const raw = values[option];
+    if (typeof raw !== "string")
+        return {};
+    if (raw === "none")
+        return { [option]: null };
+    const at = raw.lastIndexOf("@");
+    if (at < 0)
+        return { [option]: raw };
+    const parts = raw
+        .slice(at + 1)
+        .split(",")
+        .map((part) => (part.trim() === "" ? Number.NaN : Number(part)));
+    if (parts.length !== 2 || parts.some((part) => !Number.isFinite(part) || part < 0 || part > 1)) {
+        throw new OrlanError(`--${option} takes <item> or <item>@x,y: x and y are from 0 to 1 of the item's box, 0,0 its top left corner.`, undefined, `run the command again with --${option} ${raw.slice(0, at) || "<item>"}@0.5,0.5`);
+    }
+    return { [option]: raw.slice(0, at), [`${option}At`]: { x: parts[0], y: parts[1] } };
+}
 const baseOption = (values) => {
     const number = versionNumber(values, "base");
     return number === undefined ? {} : { baseVersion: number };
@@ -225,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)
@@ -259,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.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.
@@ -317,8 +361,10 @@ export const commands = {
         summary: "Sign in to Orlan (approve in the Connect dialog with --pair, else in the browser) and keep a CLI token.",
         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 the topics and role your agents get. The CLI token goes",
-            "to the OS keychain, or to a file only you can read when there is no keychain.",
+            "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 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.",
             "",
             "With --pair, the code waits in the Connect dialog of the Orlan web app, and no page opens.",
             "Check the code there, then approve it. The prompt that the dialog copies has the --pair id.",
@@ -465,7 +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.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) {
@@ -505,8 +551,10 @@ export const commands = {
             "  other        .agents/skills in the folder you are in",
             "",
             AGENT_HELP,
-            "--topic <id>   A topic the agent can use. Repeat it for more. Default: the topics you chose at sign-in.",
-            "--role <role>  editor, commenter or viewer. Default: the role you chose at sign-in.",
+            "--topic <id>   A topic the agent can use. Repeat it for more. The agent then gets only these topics.",
+            "               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],
@@ -543,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."]
@@ -570,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,
         ],
@@ -580,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, {
@@ -858,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,
         ],
@@ -947,19 +995,21 @@ export const commands = {
         summary: "Print the board: its items with their ids and places, the timer, the votes and the open tasks.",
         details: [
             "Each item is one line: its id, its type, its place (x,y) and size (w x h) in board coordinates, and",
-            "its text. A note, a text and a shape also show a text size other than M, and a shape its kind and color, a",
-            "file its name and pages, an arrow the items it links and its label. An item in a frame shows",
+            "its text. A note, a text and a shape also show a text size other than M and a text color other than ink,",
+            "and a shape its kind and color, a",
+            "file its name and pages, an arrow the items it links and its label. An arrow end at an exact spot of",
+            "its item shows <item>@x,y: x and y are from 0 to 1 of the item's box, 0,0 its top left corner. An item in a frame shows",
             '"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" }),
@@ -969,7 +1019,7 @@ export const commands = {
             const items = board.items.map((item) => item.type === "file" ? { ...item, name: names.get(item.artifactId ?? "") ?? "" } : item);
             const { timer, vote, lastVote, tasks = [] } = board.session ?? {};
             const lines = [
-                `Board of ${quote(board.topic.name)} ${board.topic.id}: ${items.length} item${items.length === 1 ? "" : "s"}, text size M unless named.`,
+                `Board of ${quote(board.topic.name)} ${board.topic.id}: ${items.length} item${items.length === 1 ? "" : "s"}, text size M and text color ink unless named.`,
             ];
             if (items.some((item) => item.text) || vote || tasks.length > 0)
                 lines.push(QUOTED_TEXT);
@@ -977,14 +1027,15 @@ export const commands = {
             for (const item of items) {
                 const place = `at ${round(item.x)},${round(item.y)}, ${round(item.w)}x${round(item.h)}` +
                     (item.frame ? ` in frame ${item.frame}` : "");
-                const end = (id, x, y) => id ?? `${round(x)},${round(y)}`;
+                const end = (id, at, x, y) => (id ? (at ? `${id}@${at.x},${at.y}` : id) : `${round(x)},${round(y)}`);
                 const words = item.text === undefined ? "" : `: ${quote(item.text)}`;
-                // The text size M is the default: only another size shows.
-                const size = item.size && item.size !== "M" ? ` size ${item.size}` : "";
+                // The text size M and the text color ink are the defaults: only another one shows.
+                const size = (item.size && item.size !== "M" ? ` size ${item.size}` : "") +
+                    (item.textColor && item.textColor !== "ink" ? ` text color ${item.textColor}` : "");
                 lines.push(item.type === "shape"
                     ? `- ${item.id} shape ${item.kind} ${item.color}${size} ${place}${words}`
                     : item.type === "arrow"
-                        ? `- ${item.id} arrow from ${end(item.from, item.x, item.y)} to ${end(item.to, item.x + item.w, item.y + item.h)}${item.text ? words : ""}`
+                        ? `- ${item.id} arrow from ${end(item.from, item.fromAt, item.x, item.y)} to ${end(item.to, item.toAt, item.x + item.w, item.y + item.h)}${item.text ? words : ""}`
                         : item.type === "file"
                             ? `- ${item.id} file ${quote(item.name ?? "")} (${item.artifactId}) ${place}, ` +
                                 `${item.pages?.length ?? 0} page${item.pages?.length === 1 ? "" : "s"}`
@@ -1020,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,
         ],
@@ -1036,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");
@@ -1065,7 +1116,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>] [--kind <kind>] [--color <color>] [--frame <frame>|none] | arrow --from <item> --to <item> [--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>] [--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",
@@ -1083,16 +1134,20 @@ export const commands = {
             `--size <size>     The text size of a note, a text or a shape: ${TEXT_SIZES_HELP}. Default: M. Or the`,
             "                  width and the height as w,h. Default: the default size above, the size a person",
             "                  gets.",
+            `--text-color <color>  The color of the words of a note, a text or a shape: ${TEXT_COLORS_HELP}.`,
+            "                  Default: ink.",
             `--kind <kind>     A shape's kind: ${SHAPE_KINDS_HELP}. Default: rectangle.`,
             `--color <color>   A shape's color: ${SHAPE_COLORS_HELP}. Default: white.`,
             '--id <id>         The id of the new item, for example "api": 1 to 64 letters, digits, - or _. It',
             "                  must be new on the board. Default: a new uuid.",
-            "--from <item>     The item the arrow starts at.",
-            "--to <item>       The item the arrow points to.",
+            "--from <item>     The item the arrow starts at, on its edge. <item>@x,y: at that exact spot of the",
+            "                  item, x and y from 0 to 1 of its box, for example slide@0.25,0.6 for a spot on a",
+            "                  slide or an image. On a shape the end sits on its outline, on the line to the spot.",
+            "--to <item>       The item the arrow points to, as --from: <item> or <item>@x,y.",
             "--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,
         ],
@@ -1102,6 +1157,7 @@ export const commands = {
             text: { type: "string" },
             at: { type: "string" },
             size: { type: "string" },
+            "text-color": { type: "string" },
             kind: { type: "string" },
             color: { type: "string" },
             from: { type: "string" },
@@ -1122,7 +1178,13 @@ export const commands = {
                 if (typeof values.from !== "string" || typeof values.to !== "string") {
                     throw new OrlanError("An arrow needs --from <item> and --to <item>.", undefined, "orlan board (the item ids)");
                 }
-                edit = { op: "create", type, from: values.from, to: values.to, ...(text !== undefined ? { text } : {}) };
+                edit = {
+                    op: "create",
+                    type,
+                    ...arrowEndOption(values, "from"),
+                    ...arrowEndOption(values, "to"),
+                    ...(text !== undefined ? { text } : {}),
+                };
             }
             else if (type === "note" || type === "text" || type === "frame" || type === "shape") {
                 const at = numbersOption(values, "at", 2);
@@ -1140,7 +1202,10 @@ export const commands = {
             else {
                 throw new OrlanError("The item is a note, a text, a shape, a frame or an arrow.", undefined, usage);
             }
-            // The server refuses a kind or a color on an item that is not a shape, and says why.
+            // The server refuses a kind or a color on an item that is not a shape, and a text color on an item
+            // with no text color, and says why.
+            if (typeof values["text-color"] === "string")
+                edit.textColor = values["text-color"];
             if (typeof values.kind === "string")
                 edit.kind = values.kind;
             if (typeof values.color === "string")
@@ -1150,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"
@@ -1160,8 +1225,8 @@ export const commands = {
         },
     },
     "board change": {
-        usage: 'orlan board change <item> [--text "<text>"] [--at <x,y>] [--size <S|M|L|XL|w,h>] [--kind <kind>] [--color <color>] [--from <item>|none] [--to <item>|none] [--frame <frame>|none] [--topic <topic>] [--agent <id>] [--json]',
-        summary: "Change an item of the board: its text, place, size, frame, a shape's kind and color, or the ends of an arrow.",
+        usage: 'orlan board change <item> [--text "<text>"] [--at <x,y>] [--size <S|M|L|XL|w,h>] [--text-color <color>] [--kind <kind>] [--color <color>] [--from <item>[@x,y]|none] [--to <item>[@x,y]|none] [--frame <frame>|none] [--topic <topic>] [--agent <id>] [--json]',
+        summary: "Change an item of the board: its text, place, size, text color, frame, a shape's kind and color, or the ends of an arrow.",
         details: [
             "The changes are one step, which a person can undo. A file on the board only moves (--at) and goes",
             "in a frame or out of it (--frame). A note, a text and a shape grow to fit their new words or size.",
@@ -1176,13 +1241,16 @@ export const commands = {
             "                  with =: --at=-50,120.",
             `--size <size>     The new text size of a note, a text or a shape: ${TEXT_SIZES_HELP}. Or the new width`,
             "                  and height as w,h.",
+            `--text-color <color>  The new color of the words of a note, a text or a shape: ${TEXT_COLORS_HELP}.`,
             `--kind <kind>     A shape's new kind: ${SHAPE_KINDS_HELP}.`,
             `--color <color>   A shape's new color: ${SHAPE_COLORS_HELP}.`,
-            "--from <item>     The item the arrow starts at. none: the end stays where it is, on no item.",
-            "--to <item>       The item the arrow points to. none: the end stays where it is, on no item.",
+            "--from <item>     The item the arrow starts at, on its edge. <item>@x,y: at that exact spot of the",
+            "                  item, x and y from 0 to 1 of its box (on a shape: on its outline, on the line to the",
+            "                  spot). none: the end stays where it is, on no item.",
+            "--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,
         ],
@@ -1192,6 +1260,7 @@ export const commands = {
             text: { type: "string" },
             at: { type: "string" },
             size: { type: "string" },
+            "text-color": { type: "string" },
             kind: { type: "string" },
             color: { type: "string" },
             from: { type: "string" },
@@ -1202,19 +1271,14 @@ export const commands = {
         positionals: [1, 1],
         run: (values, [id], io) => {
             const at = numbersOption(values, "at", 2);
-            const end = (option) => {
-                const value = values[option];
-                if (typeof value !== "string")
-                    return {};
-                return { [option]: value === "none" ? null : value };
-            };
             const update = {
                 ...(typeof values.text === "string" ? { text: values.text } : {}),
                 ...sizeOption(values),
+                ...(typeof values["text-color"] === "string" ? { textColor: values["text-color"] } : {}),
                 ...(typeof values.kind === "string" ? { kind: values.kind } : {}),
                 ...(typeof values.color === "string" ? { color: values.color } : {}),
-                ...end("from"),
-                ...end("to"),
+                ...arrowEndOption(values, "from"),
+                ...arrowEndOption(values, "to"),
                 ...frameOption(values),
             };
             const edits = [
@@ -1222,10 +1286,10 @@ export const commands = {
                 ...(Object.keys(update).length > 0 ? [{ op: "update", id, ...update }] : []),
             ];
             if (edits.length === 0) {
-                throw new OrlanError("Give --text, --at, --size, --kind, --color, --from, --to or --frame.", undefined, `orlan board change ${id} --text "<text>"`);
+                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)"));
             });
@@ -1240,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),
@@ -1266,12 +1330,13 @@ export const commands = {
             '   {"op":"create","type":"arrow","from":"web","to":"api","text":"calls"}]',
             "",
             "create  type note, text, shape or frame with x, y and text (and w, h, frame); a note, a text and a",
-            `        shape also size (${TEXT_SIZES_HELP}; default M); a shape also kind and color; type arrow with`,
-            "        from and to, and text (its label). id: 1 to 64 letters, digits, - or _, new on the board.",
+            `        shape also size (${TEXT_SIZES_HELP}; default M) and textColor (default ink); a shape also`,
+            "        kind and color; type arrow with from and to, and text (its label). id: 1 to 64 letters,",
+            "        digits, - or _, new on the board.",
             "        Default: a new uuid.",
             "move    id, x, y. A frame moves with its items.",
-            "update  id, and text (an arrow: its label), w, h, size (a note, a text, a shape), kind, color (a",
-            "        shape), from and to (null: on no item), or frame (null: in no frame).",
+            "update  id, and text (an arrow: its label), w, h, size, textColor (a note, a text, a shape), kind,",
+            "        color (a shape), from and to (null: on no item), or frame (null: in no frame).",
             "delete  id. A file on the board only moves, and takes a frame.",
             "",
             BOARD_SIZES_HELP,
@@ -1279,13 +1344,15 @@ export const commands = {
             ...FRAMES_HELP,
             `Shape kinds: ${SHAPE_KINDS_HELP}. Default: rectangle.`,
             `Shape colors: ${SHAPE_COLORS_HELP}. Default: white.`,
+            `Text colors: ${TEXT_COLORS_HELP}. Default: ink. The same names as the shape colors, in a strong`,
+            "shade that reads on a note, on a shape and on the board. White reads only on a dark background.",
             "An arrow goes from the middle of one item to the middle of the other, and cannot end on an arrow.",
             "Its text is its label, on the middle of the arrow.",
             "An unknown key, or a key the item cannot use (x on an arrow), is refused: nothing changes, and",
             "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,
         ],
@@ -1303,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)}`),
@@ -1323,10 +1390,13 @@ export const commands = {
             "Each node and subgraph keeps its Mermaid id as its item id, so `orlan board change <id>` changes it",
             "later. An id that is on the board already gets a prefix, m2-, m3-, and so on; the other ids stay as",
             "they are. The answer gives each id.",
-            "With --frame, the diagram goes in that frame, which grows when it needs more room. It replaces the",
-            "items your agent drew in that frame before, and the arrows to them, so a second import of a changed",
-            "file changes the diagram in place: it starts at the same place and keeps its ids. A person's items",
-            "in the frame stay, and do not move.",
+            "With --frame, the diagram goes in that frame, and the frame fits it: it grows or shrinks to hold",
+            "the diagram and the other items in it, with 24 px of room round them. It replaces the items your",
+            "agent drew in that frame before, and the arrows to them, so a second import of a changed file",
+            "changes the diagram in place and keeps its ids. A person's items in the frame stay, and do not move.",
+            "Subgraphs that are stacked or side by side line up: one left edge and one width for a stack, one",
+            "top and one height for a row, with even gaps. Subgraphs that no link joins go in the order of the",
+            "file: so variants to compare (2-tier, 3-tier, 4-tier) are one file, one subgraph each.",
             "",
             "What works: the first line is flowchart or graph with TD, TB, BT, LR or RL.",
             "  A[text] rectangle, A(text) and A([text]) rounded, A((text)) ellipse, A{text} diamond,",
@@ -1334,17 +1404,21 @@ export const commands = {
             '  and A(((text))) take the nearest of these. "text" in quotes can hold brackets; <br> is a new line.',
             "  A --> B, A --- B, A -.-> B, A ==> B, with a label as A -->|label| B or A -- label --> B.",
             "  A --> B --> C and A & B --> C. Every link is an arrow from the first node to the second.",
-            "  subgraph id [title] ... end: a frame. Subgraphs can be in subgraphs.",
+            "  A ~~~ B: a hidden link. It places B after A, and draws no arrow.",
+            "  subgraph id [title] ... end: a frame. Subgraphs can be in subgraphs. direction LR (or TB, BT,",
+            "  RL) in a subgraph lays it out that way when no link goes out of it, as in Mermaid. A link to a",
+            "  subgraph id (A --> id, id ~~~ other) is a link to its frame, when no link goes out of it.",
             "  classDef name fill:#f9f, class A name, A:::name and style A fill:#f9f: the nearest shape color",
             `  (${SHAPE_COLORS_HELP}).`,
-            "  linkStyle, click, and direction in a subgraph are left out, and the answer says so.",
+            "  linkStyle, click, a direction in a subgraph a link goes out of, and the dots of -.-> (it draws",
+            "  solid) are left out, and the answer says so.",
             "Another Mermaid diagram (sequenceDiagram, classDiagram and others) is refused, and so is a syntax",
             "error, with its line. Nothing changes then.",
             ...WARNINGS_HELP,
             "",
             "<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,
         ],
@@ -1354,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,
@@ -1397,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,
         ],
@@ -1414,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 } : {}),
@@ -1468,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,
         ],
@@ -1483,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 } : {}),
@@ -1545,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.",
             "",
@@ -1557,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;
@@ -1714,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.3.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, a chart of a flow, an architecture or a map of a system. 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. Each Orlan topic has one board (people call it the canvas) with files, notes, comments, tasks and votes. Do not use it for work that has no link to the board, such as 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
 
@@ -33,16 +36,50 @@ or the one the person names.
   (`orlan files pull <file> --out <path>`), and answer from them.
 - The person asks for a diagram, a chart of a flow, a map of a system or a sketch: draw it on the board
   with shapes and labeled arrows. Follow "Draw a diagram" below.
+- The person asks you to explain, compare or design a system, an architecture, a flow or a process, and
+  the answer has parts and links between them ("explain how a CDN works", "monolith vs microservices",
+  "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
@@ -54,40 +91,46 @@ diagram, do not use notes as boxes, and do not use another diagram skill or tool
    make a frame at a free place (right of or below the items `orlan board` shows), and draw it in the frame:
    `orlan board add frame "<title>" --id <frame> --at <x,y>`, then
    `orlan board mermaid <file.mmd> --frame <frame>`. Use `subgraph` for the groups, a diamond `{...}`
-   for a decision, a cylinder `[(...)]` for data. To change it, change the file and run the same
-   command again: it replaces your old version in the frame.
-3. Another diagram (a grid, a layout, a timeline): `orlan board edit '<JSON>'` with the shapes, the
+   for a decision, a cylinder `[(...)]` for data. The frame fits the diagram.
+3. One picture is ONE Mermaid file and one import, also when it has several parts (a comparison,
+   variants, before and after, layers): one `subgraph` for each part, with no links between the parts.
+   `flowchart LR` stacks the parts as rows, `flowchart TB` puts them side by side; Orlan lines them up
+   in the order of the file. A key or a compare box is shapes in a subgraph of its own (`a ~~~ b` puts
+   two boxes side by side with no arrow), not a text item. All words keep one size.
+   A login, a payment or another exchange of messages between parties: one box for each step, in
+   order, that says who does what ("App sends the code to the auth server"), with a subgraph for each
+   phase. Do not draw each party once with arrows back and forth: the lines cross and the order is lost.
+4. Do not move, resize or add items by hand after the import. To change the picture, change the file
+   and run the same command again: it replaces your old version and fits the frame again.
+5. Another diagram (a grid, a layout, a timeline): `orlan board edit '<JSON>'` with the shapes, the
    arrows and their labels in one step, each with an id of your own.
-4. Read the warnings in the answer. Fix each one (move an item, change `LR` to `TD`, make the boxes
+6. Read the warnings in the answer. Fix each one in the file (change `LR` to `TB`, make the boxes
    fewer) and draw again, until the answer has no warning.
-5. Look at it: `orlan board view --out <file.png> --frame <frame>`, open the picture, and fix words that
+7. Look at it: `orlan board view --out <file.png> --frame <frame>`, open the picture, and fix words that
    are cut, boxes that touch and arrows that are hard to follow.
-6. Tell the person what is on the board: the frame, its groups and main steps, and that they can move
-   or change each shape.
+8. Tell the person what is on the board (the topic, the frame) in one line after your answer.
 
-Example for "create a diagram showing how to make a full stack app", in `app.mmd`:
+Example for "monolith vs microservices", in `compare.mmd`:
 
 ```
 flowchart LR
-  subgraph plan [Plan]
-    idea[Idea and users] -->|write| spec[Requirements]
+  subgraph mono [Monolith]
+    u1[Users] -->|HTTPS| app1[One app] -->|SQL| db1[(One database)]
+  end
+  subgraph micro [Microservices]
+    u2[Users] -->|HTTPS| gw[API gateway] -->|REST| orders[Order service] -->|SQL| db2[(Orders DB)]
   end
-  subgraph build [Build]
-    db[(Database)] -->|data| api[Backend API]
-    api -->|JSON| ui[Frontend UI]
+  subgraph key [Compare]
+    k1[Monolith: simple to run] ~~~ k2[Microservices: scale each part]
   end
-  spec -->|design schema| db
-  ui -->|run| test{Tests pass?}
-  test -->|no| api
-  test -->|yes| deploy[Deploy and monitor]
 ```
 
-Then `orlan board add frame "How to make a full stack app" --id app --at <x,y>`,
-`orlan board mermaid app.mmd --frame app` and `orlan board view --out app.png --frame app`.
+Then `orlan board add frame "Monolith vs microservices" --id compare --at <x,y>`,
+`orlan board mermaid compare.mmd --frame compare` and `orlan board view --out compare.png --frame compare`.
 
 ## When not to use Orlan
 
-Do not call Orlan for work that has no link to the board: a sum, a general question, a question on
+Do not call Orlan for work that has no link to the board: a sum, a short fact answer, a question on
 code, a fix in a local file the person names, a test run. Do the work and answer. Do not post a file
 the person did not ask for.
 
@@ -118,13 +161,20 @@ show it, and every other command fails with `agent_stopped`. When you see it:
 - `orlan board add note|text|frame "<text>" --at <x,y>`,
   `orlan board add shape "<text>" --kind <kind> --color <color> --at <x,y>`,
   `orlan board add arrow --from <item> --to <item> --text "<label>"`, `orlan board change <item>`,
-  `orlan board delete <item>` - change the board. A person can undo each change. `orlan board edit '<JSON>'` makes several changes in one step; give each new item an
+  `orlan board delete <item>` - change the board. A person can undo each change, or accept it: that takes your name label off its items, and the items still say you made them. Only a person accepts. `orlan board edit '<JSON>'` makes several changes in one step; give each new item an
   `"id"` of your own (`"api"`) and let the arrows of the same step use it. A note, a text and a shape
-  take a text size, `--size S|M|L|XL` (`"size"` in the JSON; default M). Their box grows to fit their
+  take a text size, `--size S|M|L|XL` (`"size"` in the JSON; default M), and a text color for their
+  words, `--text-color <color>` (`"textColor"`): ink (default) or a shape color name - white, gray,
+  blue, teal, green, yellow, orange, red. A color that a person cannot read on its fill in their theme
+  (white on a light note) draws in the ink of that theme. Their box grows to fit their
   words, so the answer gives the final box: place the next item from that box, not from the size you asked.
   A frame holds the items in it and moves with them: draw the frame, then put items in it
   (`--frame <frame>`, `"frame"` in the JSON), and move the frame to move the group. `--frame none`
   takes an item out.
+  An arrow ends on the edge of its item. To point at an exact spot of a slide, an image or a shape,
+  give `--to <item>@x,y` (or `--from`), x and y from 0 to 1 of the item's box (`"toAt": {"x", "y"}` in
+  the JSON). The spot moves with the item. On a shape the end sits on the outline, where the line to
+  the spot enters the shape, so arrows to different spots of one shape stay apart.
 - `orlan board mermaid <file.mmd> [--frame <frame>]` - draws a Mermaid flowchart as shapes, labeled
   arrows and frames.
 - `orlan board view --out <file.png> [--frame <frame>]` - a PNG picture of the board as people see it.
@@ -142,8 +192,15 @@ Run `orlan <command> --help` for the options of a command.
 - "create a diagram showing how to make a full stack app" - draw it in a frame with
   `orlan board mermaid`, as in "Draw a diagram", check the warnings and the picture, and say what is on
   the board. No HTML file, no notes.
-- "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.
+- "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 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.