@orlan-maker/cli 0.2.2 → 0.3.0

package/README.md

@@ -21,66 +21,38 @@ orlan connect --agent claude-code
   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
+  `--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 installs
-  the skills, and the plugin or the hooks of the agent (table below). Then it tests the token with one
-  plain HTTP call. `--topic` and `--role` change the topics and the role of the agent.
+  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.
 - 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, never an HTML file or notes. `orlan skills add` writes the
-  skills again without a new token.
-- An older CLI wrote an Orlan server entry in the agent's settings. `orlan connect` removes that
-  entry, and keeps every other entry.
+  on the topic. A diagram is board shapes with labeled arrows, never an HTML file or notes: the agent
+  draws a flow with `orlan board mermaid` in a frame, fixes the warnings and looks at
+  `orlan board view`. A second `orlan connect` writes the skills again.
+- An older CLI (0.1 and 0.2) installed more: the Claude Code plugin `orlan@orlan` and its local
+  marketplace, hooks for Codex and Cursor, an OpenCode plugin, and an Orlan MCP entry. `orlan connect`
+  and `orlan disconnect` remove them, and keep every other entry the person has.
 - `orlan status` shows who you are, the server, and each connected agent, and tests each agent's
   connection with one plain HTTP call. It ends with exit code 1 when a check fails.
 
 Agents: `claude-code`, `codex`, `cursor`, `opencode`, `other`.
 
-| Agent | Skills | Also installs |
-| --- | --- | --- |
-| claude-code | in the plugin | the Claude Code plugin (below) |
-| codex | `~/.agents/skills` | the hooks in `$CODEX_HOME/hooks.json` |
-| cursor | `~/.cursor/skills` | the hooks in `~/.cursor/hooks.json` |
-| opencode | `~/.config/opencode/skills` | the plugin in `~/.config/opencode/plugins/orlan.js` |
-| other | `.agents/skills` in the folder you are in | - |
+| Agent | Skills |
+| --- | --- |
+| claude-code | `~/.claude/skills` (`$CLAUDE_CONFIG_DIR/skills` when it is set) |
+| codex | `~/.agents/skills` |
+| cursor | `~/.cursor/skills` |
+| opencode | `~/.config/opencode/skills` |
+| other | `.agents/skills` in the folder you are in |
 
-With `--no-plugin`, Claude Code gets no plugin, and the skills go to `~/.claude/skills`. Without
-`--agent`, the CLI finds the agent that runs it from its environment.
-
-## The Claude Code plugin
-
-This package is also the Claude Code plugin `orlan@orlan`. Its public marketplace is
-https://github.com/AliProgrammin/orlan-plugin (MIT). Install it in two lines:
-
-```
-claude plugin marketplace add AliProgrammin/orlan-plugin
-claude plugin install orlan@orlan
-```
-
-`orlan connect --agent claude-code` installs it too; from a checkout,
-`claude plugin marketplace add ./packages/cli` and `claude plugin install orlan@orlan` do the same. One install gives the session:
-
-- `orlan` on the PATH of Claude Code's shell.
-- Hooks that show the session on the board: working (session start, a prompt, each tool), waiting for
-  input (a permission prompt or a question in the terminal), idle (the turn ended), done (the session
-  ended). At the session start, `orlan brief` goes into the session's context, with one line that says
-  what Orlan is: "the canvas", "the board" and "the topic" mean the Orlan topic, and a diagram, a page,
-  a deck or a mock starts with the `orlan` skill. Codex, Cursor and OpenCode get the same line, from
-  `hooks/orlan-intro.txt`.
-- The skills `orlan`, `orlan-review` and `orlan-versions`.
-
-The session works on Orlan with the `orlan` command. A new request comes to the session when the agent
-runs `orlan brief`, `orlan inbox` or `orlan wait`.
-
-## The OpenCode plugin
-
-`orlan connect --agent opencode` also writes the Orlan plugin to `~/.config/opencode/plugins/orlan.js`.
-When a session's turn ends, the plugin runs `orlan hook wait`. A mention of the agent on the board then goes
-to the session as a new prompt, and a new turn starts. The plugin also shows the session on the board:
-working, waiting for a permission prompt, idle, done. It adds the line that says what Orlan is to the
-system prompt of each session. A request wakes a session only while OpenCode runs
-(the TUI or `opencode serve`). Restart a running OpenCode to load the plugin. `orlan disconnect
---agent opencode` removes it.
+Without `--agent`, the CLI finds the agent that runs it from its environment.
 
 ## Daily commands
 
@@ -100,21 +72,20 @@ orlan comments list [--topic <topic>] [--status open|resolved|all] [--file <file
 orlan comment <thread> "<text>" | --file <file> --page <n> [--region <x,y,w,h>] "<text>" | --at <x,y> "<text>" [--topic <topic>]
 orlan comments resolve <thread> [--topic <topic>]
 orlan board [--topic <topic>]
-orlan board add note|text|frame ["<text>"] --at <x,y> [--size <w,h>] | arrow --from <item> --to <item>
-orlan board change <item> [--text "<text>"] [--at <x,y>] [--size <w,h>] [--from <item>|none] [--to <item>|none]
+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 delete <item>...
 orlan board edit '<edits as JSON>'
+orlan board mermaid <file.mmd> [--frame <frame>] [--topic <topic>]
 orlan tasks add "<text>" [--assignee me|user:<id>|agent:<id>] [--thread <thread>] [--done]
 orlan tasks change <task id> [--text "<text>"] [--done | --open] [--assignee me|user:<id>|agent:<id>|none]
 orlan decisions add "<title>" [--body "<text>"] [--thread <thread>]
 orlan search "<words>" [--topic <topic>] [--limit <n>]
 orlan open [<topic id>] [--file <file id>]
-orlan wait [--follow]
 orlan inbox [--new]
 orlan inbox done <request id>
-orlan respond <request id> --message "<text>" [--file <path>] [--to <file>] [--changelog "<text>"] [--base <n>] [--wait]
-orlan hook <working|needs-input|idle|done>
-orlan hook start|stop --agent codex|cursor
+orlan respond <request id> --message "<text>" [--file <path>] [--to <file>] [--changelog "<text>"] [--base <n>]
 ```
 
 The ids people see work as input: a topic by its name, a file by its name, a thread as `#12`, and a
@@ -124,8 +95,9 @@ its id and topic: give the id, or add `--topic`.
 
 Every output ends with a `next_step` line, and every error says what to do next in a `next_step` line.
 With `--json`, a command prints small JSON on one line with a `next_step` field; an error is JSON too:
-`{"error": "<code>", "message": "...", "next_step": "..."}`. The hook commands
-print only what their harness reads, and `orlan inbox --new` prints nothing when there is no request.
+`{"error": "<code>", "message": "...", "next_step": "..."}`. `orlan inbox --new` prints nothing when
+there is no request. A text people wrote is always quoted, and the line that says so comes once in an
+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
@@ -133,14 +105,67 @@ topic is the one the agent used last, else its only topic. `orlan files add` pos
 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 file shows its name and pages, and an arrow the items it links. 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 frame or an arrow, `orlan board
-change` changes an item's text, place, size or arrow ends, and `orlan board delete` deletes items. Each
+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
+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
+kind and color, or an arrow's ends and label, and `orlan board delete` deletes items. A shape has a kind (`--kind`:
+rectangle, rounded, ellipse, diamond, cylinder or parallelogram; default rectangle), a named color
+(`--color`: white, gray, blue, teal, green, yellow, orange or red; default white), and its words in its
+middle. An arrow can end on a shape. An arrow's text is its label (`--text "yes"`), drawn on a pill on
+the middle of the arrow that moves with it; `--text ""` takes it away. Each
 command is one step that a person can undo on the board. `orlan board edit` takes a JSON list of edits
-and makes them in one step, all or none; `"#0"` names the item that the first edit made. A file on the
-board only moves. A negative coordinate goes with `=`: `--at=-50,120`. The CLI cannot draw shapes yet,
-so a diagram is not made with these commands.
+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
+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
+change` and `orlan board edit` print each item with its final place and size, after it grew. An unknown key, a key the item cannot use, or an arrow that ends on an arrow is
+refused, nothing changes, and the error says what to change. A file on the board only moves, and goes in a frame or out of it. A negative coordinate goes with `=`: `--at=-50,120`.
+A frame holds items: a move of the frame moves its items, and the items of the frames in it. An item goes in the
+smallest frame that holds more than half of it when it is made or moved, and a new frame takes the items it is
+drawn around. `--frame <id>` on `orlan board add` and `orlan board change` (`"frame"` in the JSON) puts an item
+in a frame, and `--frame none` (`"frame": null`) takes it out; the item stays where it is. An arrow is in no
+frame: its ends follow the items they are on. A deleted frame leaves its items on the board.
+After each change, `orlan board add`, `change`, `delete` and `edit` print drawing warnings about the items the change
+made or changed, one `warning:` line each, after the result: two items overlap (`shape api overlaps shape db by 40
+px: move one of them.`), 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 warning
+names the items and says what to change; the first id is the item to change. A warning never stops a change. With
+`--json` the answer has `"warnings": [{"kind","ids","text"}]`, and `[]` when the drawing is clean.
+
+`orlan board mermaid <file.mmd>` draws a Mermaid flowchart on the board as real items, in one step that a person
+can undo: a shape for each node, an arrow with its label for each link, and a frame for each subgraph. The first
+line is `flowchart` or `graph` with TD, TB, BT, LR or RL. `A[text]` is a rectangle, `A(text)` and `A([text])`
+rounded, `A((text))` an ellipse, `A{text}` a diamond, `A[(text)]` a cylinder and `A[/text/]` a parallelogram;
+`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
+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.
+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
+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
+its line; both list what works, and nothing changes. With `--json`: `{ ids, items, warnings, replaced,
+ignored }`.
+
+`orlan board view --out <file.png>` saves a PNG picture of the board as people see it, so an agent can look
+at what it drew. Orlan draws it with the same board canvas people use, without cursors, made-by marks and
+tools. The picture fits all the items, or one frame with `--frame <frame>`. It shows them at 100% when they
+fit in 1600 pixels, else smaller to fit, but not below 20%. A board too large for that shows its middle
+part, and the answer says so (`"cut": true`): then look at one frame at a time. A picture is at most 4000 x
+4000 pixels. The command prints where it saved the picture, its size in pixels and KB, its zoom, and the
+board point of its top left pixel. With `--json`: `{ saved, topicId, frameId, width, height, bytes, zoom,
+at: { x, y }, cut }`, where `saved` is the absolute path. The picture holds only the board and the files of
+that topic: a topic the token does not reach is refused. Errors: `frame_not_found`, `render_unavailable`,
+`render_timeout`, `render_failed`.
 
 `orlan tasks add` adds a task to the topic, `orlan tasks change` changes its text, marks it done or open,
 or sets its assignee (`--assignee me` is the agent). `orlan decisions add` records a decision in the
@@ -158,13 +183,13 @@ on the board at once. "@" and a name mentions a person or an agent of the topic.
 agent makes no request when that agent still has an open request from you in the thread, or after 5 asks
 this hour: the command prints "Not asked: <name>".
 
-`orlan wait` waits for the next request to the agent: a person, a guest or an agent mentions it in a
-comment. It prints the request with each comment, its file, version, page, region, the text under the
-region and a crop link, and exits. Running it again after a lost connection is safe: the request comes
-once. The wait confirms each request after it printed it; when the wait stops before that, the request
-goes back to the inbox within 20 seconds. `--follow` stays open and prints one line per request. `orlan inbox` prints the open requests;
-`--new` takes the new ones and prints nothing when there are none, for a stop hook. `orlan inbox done`
-closes a request when its work is finished.
+A request comes when a person, a guest or an agent mentions the agent in a comment, or answers in a
+thread the agent asked in. `orlan inbox` prints the open requests, each with its comments, file,
+version, page, region, the text under the region and a crop link, and exits at once. `--new` takes
+only the new ones and prints nothing when there are none. The CLI confirms each request after it
+printed it; when it stops before that, the request goes back to the inbox within 20 seconds.
+`orlan inbox done` closes a request when its work is finished. Nothing wakes the agent when a request
+comes: it runs `orlan brief` or `orlan inbox` when the person asks, or at the start of a task.
 
 `orlan files pull --pages 2,5` gets pages, not the file: it saves the image of each page as
 `<name>-page-<n>.png` in the `--out` folder, and prints the text of each page. `--since 4` gets the
@@ -185,38 +210,29 @@ When a newer version landed first, Orlan refuses it with `stale_base`, the newer
 `orlan respond` closes a review round in one command. With `--file`, it posts the file as a new version
 of the file the request is about, with the version the comments were on as its base (`--to <file id>`
 when the request names no file or several). Then it replies with the message in each thread of the
-request, resolves the threads, and marks the request done. `--wait` then waits for the next request, as
-`orlan wait` does. A request that is done already gives a refusal and a `next_step` line. To ask a
+request, resolves the threads, and marks the request done. A request that is done already gives a refusal and a `next_step` line. To ask a
 person a question, reply with `orlan comment` and leave the thread open: the answer comes to the
 inbox as a request. A request that stays taken for 10 minutes with no done goes back to the inbox.
 
-`orlan hook` is for harness hooks, not for the model: it tells the board that the agent works, waits
-in the terminal (for example on a permission prompt), is idle or is done. It reads the hook's JSON on
-standard input, makes one request, prints nothing and makes no model call. Orlan never answers the
-terminal prompt; the board tells people to go to the terminal. With no agent connected, it does nothing.
-
-`orlan hook start` and `orlan hook stop` are the session start and stop hooks of Codex and Cursor, and
-`orlan connect --agent codex|cursor` installs them. Codex and Cursor sessions do not wake when idle:
-the start hook puts the brief and the line that says what Orlan is in the session, and when a turn ends the stop hook gives the session the
-new requests, so it works on at once. After 5 requests in a row it lets the session stop. Codex runs a
-hook only after you trust it once with `/hooks`.
-
-Each command shows on the board as a step of the agent's hook session: a page it reads moves its cursor
-there. The command finds its session from the harness: `CLAUDE_CODE_SESSION_ID` in Claude Code,
-`CODEX_THREAD_ID` in Codex, and in OpenCode `ORLAN_SESSION` (the plugin sets it) or
-`OPENCODE_SESSION_ID`. Cursor gives no session id to the shell: Orlan then takes the hook session of the
-agent that reported last.
+Each command shows on the board as a step of the agent's session: the agent works while it calls, and
+a page it reads moves its cursor there (F102). There is no hook. The command finds its session from
+the harness: `CLAUDE_CODE_SESSION_ID` in Claude Code, `CODEX_THREAD_ID` in Codex and
+`OPENCODE_SESSION_ID` in OpenCode (`ORLAN_SESSION` wins over them). Cursor and a plain shell give
+none: the CLI then makes one for its shell, so each command of that shell lands on one session.
 
-While a wait of the agent is open, the `next_step` lines do not say `--wait`:
-the open wait gets the next request.
+A person on the board can press Stop on the agent (D109). Each next command of each of its sessions
+on that topic then prints who stopped it, the topic and what to do now: `orlan inbox` and `orlan brief`
+show the stop, and every other command fails with `agent_stopped`, so the agent changes nothing more.
+The stop stays on that session. A new session of the agent (a new session id, for example a new
+conversation in the harness) is not stopped.
 
 A version the agent posts waits for a person to make it current. When several agents are connected,
 add `--agent <id>`.
 
 ## Stop
 
-- `orlan disconnect --agent <id>` revokes the agent's token, and removes its plugin or hooks and an old
-  Orlan server entry. The skills stay.
+- `orlan disconnect --agent <id>` revokes the agent's token, and removes its Orlan skills and what an
+  older CLI installed.
 - `orlan auth logout` revokes the CLI token. You can also revoke it in Orlan: Profile, Orlan CLI sign-ins.
 
 Run `orlan help` for every command, and `orlan <command> --help` for its options.