@shardflux/cli 0.25.0 → 0.28.1

package/README.md

@@ -1,5 +1,7 @@
 # @shardflux/cli: `shard`
 
+Use `shard --help` or `shard <command> --help` to explore commands before signing in.
+
 For error codes, retry timing, and plan recovery, see the [error reference](https://docs.shardflux.dev/reference/errors).
 
 Historical template file lists: reads queue checksum-verified reconstruction when a cold list is absent from the SQL cache. TypeScript SDK 0.27.0+ / Python 0.23.0+ wait full Retry-After for retryable API 409 file_list_indexing on GET/HEAD within the admission timeout. Template objects and version history stay available.
@@ -30,6 +32,8 @@ T3 Connect (0.22.0+): `shard setup --inspect --t3-connect --org <id|slug>` signs
 project. Status and Connect use the same person and organization, including a saved session without an API key;
 an explicit selection keeps the default credentials and target status. An approved T3 sign-in is reused.
 
+Filesystem recovery timing (0.28.0+): cold resume output identifies `guest_filesystem` in JSON and the restart notice. See the [workspace lifecycle](https://docs.shardflux.dev/concepts/lifecycle) for retained files and process restart semantics.
+
 ## Support and bug reports
 
 [Report a bug](https://github.com/shardfluxdev/community/issues/new?template=bug_report.yml) or
@@ -51,6 +55,8 @@ Both the task and project are required, and the task becomes the first user-auth
 
 ## Reverse tunnels (0.11.0+)
 
+Reverse listener recovery (0.24.1+): the foreground tunnel replaces its helper automatically after replay is lost and accepts fresh connections. Keep the command running for callbacks; Ctrl-C closes it.
+
 Run a foreground TCP tunnel from a workspace to a service on this machine:
 
 ```sh
@@ -74,18 +80,24 @@ Linux (Ubuntu 24.04, x64 and arm64) and macOS are supported. On Linux, run `shar
 connect Claude, Codex or both (0.17.0+), then run `shard ./` in your project to attach Claude Code or Codex in place. Sign-in opens your browser;
 on a headless terminal, follow the displayed URL and device code. `--accept-terms` accepts the terms notice.
 
-In a desktop session, `shard` opens the Shardflux app for this (0.18.0+): guided sign-in, a top-bar panel for your
-conversations, a launcher on Alt+Shift+Space and Settings. It installs with the CLI (the optional
-`@shardflux/desktop-linux-x64` or `-arm64` package), appears in the app grid and starts at login;
-`shard menubar start|stop|status` and `--login on|off` manage it as on macOS.
+In a desktop session, `shard` opens the Shardflux app (0.18.0+): guided sign-in, your conversations with their
+computers, approvals for this computer, a launcher on Alt+Shift+Space and one Settings window. It lives in the tray
+and the app grid and starts at login; `shard menubar start|stop|status` and `--login on|off` manage it as on macOS.
+
+The Shardflux app (0.28.0+) is one desktop app on macOS and Linux: the menu bar or tray, onboarding, the launcher,
+conversations with their computers, device approvals and one Settings window. `shard` installs it from the optional
+`@shardflux/desktop-darwin-arm64` / `-x64` package on macOS (at `~/Applications/Shardflux.app`, in place of the menu
+bar app, keeping its login item and privacy grants) and from `@shardflux/desktop-linux-x64` / `-arm64` on Linux (at
+`~/.local/share/shardflux/desktop`), and `shard update` keeps it current.
 
 The Linux helper starts automatically after setup as `~/.config/systemd/user/shardflux-helper.service`
 and restarts after a CLI update. It keeps the live twin, `~/Shardflux` files and conversation history in sync.
-Use `shard device requests`, `shard device approve <id>` or `shard device deny <id>` for local approvals;
+Use `shard device requests`, `shard device approve <id>` or `shard device deny <id>` for local approvals, and
+`shard device approvals auto|read|ask` to choose whether your agents ask first (0.28.0+);
 desktop notifications point to pending requests. On systems without a systemd user session, the helper runs
 while your `shard` commands are open. `shard agents open` opens a terminal when launched outside one, using
-`$TERMINAL`, `x-terminal-emulator` or `gnome-terminal`, or prints the attach command. The Mac app adds a menu
-bar, launcher and Settings window.
+`$TERMINAL`, `x-terminal-emulator` or `gnome-terminal`, or prints the attach command. On macOS the same app lives in
+the menu bar.
 
 ```sh
 npm i -g shardflux
@@ -109,7 +121,7 @@ shard ./
 
 Choose Claude Code or Codex. Claude asks for one cloud sign-in per Shardflux account; Codex uses your copied login.
 Each `shard ./` starts its own conversation VM and opens your agent’s native terminal. Later turns stay in that
-VM; `shard ./ --resume` selects a saved project conversation. Native terminal and ACP sessions receive the conversation tools for their own conversation, so the agent can fork, ask for a review, and report to its parent (0.14.0+). You can open conversations in separate terminals at the same time; each stays in the project's local history. On macOS, `shard` opens the optional command center. On macOS the menu bar starts automatically the first
+VM; `shard ./ --resume` selects a saved project conversation. Native terminal and ACP sessions receive the conversation tools for their own conversation, so the agent can fork, ask for a review, and report to its parent (0.14.0+). You can open conversations in separate terminals at the same time; each stays in the project's local history. On macOS, `shard` opens the optional command center. The Shardflux app starts automatically the first
 time `shard` runs, with launch at login enabled; `shard menubar stop` turns it off. See [Cloud agents](https://docs.shardflux.dev/guides/cloud-agents).
 
 T3 Code uses one **Shardflux** provider; choose a Claude Code or Codex model to start that agent in the cloud.
@@ -117,14 +129,14 @@ Model choices come from your cloud agent's session and use the same coding tools
 Project files synchronize before each message and before its completion (0.22.0+): review remote edits in T3’s
 Changes panel and checkpoints, and send local edits to the next turn. Conflicting versions are retained with
 a `.shard-conflict-<agent>` suffix. Sync runs between turns; an idle T3 thread needs no file watcher.
-The provider is registered automatically when T3 Code is installed, on macOS and on Linux from its .deb or AppImage
-(0.17.0+). Choose **Sign in** on its card in T3's provider settings: T3 runs `shard acp --login` in its own terminal,
+At command startup, Shardflux checks for T3 Code and registers the provider automatically on macOS and on Linux
+from its .deb or AppImage (0.17.0+). Choose **Sign in** on its card in T3's provider settings: T3 runs `shard acp --login` in its own terminal,
 which creates or signs in to your account (with this computer's Codex login, or your email) and connects Claude Code
 and Codex, skipping every step that is already done (0.15.0+). Editors that launch agents from the ACP registry
 run the same sign-in as `shard --login` (0.22.0+).
 With T3 Code 0.0.45, `shard agents new --in t3` adds the project as an SSH environment instead.
 
-ACP journal read reattachment uses bounded backoff through temporary lifecycle interruptions (0.23.0+). It keeps the saved sequence and never resubmits an uncertain turn.
+ACP journal read reattachment uses bounded backoff through temporary lifecycle interruptions (0.23.0+). It keeps the saved sequence and never resubmits an uncertain turn. ACP input reattachment (0.25.0+) retains the native request identity and running turn while reconnecting.
 
 In CLI 0.22.0+, `shard setup --inspect` shows a stopped T3 Connect workspace link and its remedy without restarting
 the link or replacing your approved sign-in. `shard agents open t3` brings T3 Code up once the workspace is linked
@@ -155,12 +167,24 @@ shard conversations start --home --title "Plan the billing work"
 shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Here is the failing run" --file ci.log
 ```
 
-`--repo` and `--branch` choose the repository and the branch it starts from (default: the project's most recently
-active repository, from `main`, then `master`); `--app`, `--model` and `--effort` work as for `shard ./`. It prints the
+`--repo` and `--branch` choose the repository and the branch it starts from (default: the project's only
+repository, from `main`, then `master`; a project with several asks you to name one with `--repo`); `--app`, `--model` and `--effort` work as for `shard ./`. It prints the
 conversation's id, key and state; `shard agents open <id>` opens it. `--file` (repeatable, up to 20 files of 64 MiB
 each) puts each file in the conversation's computer before the message and prints where it landed; `--json` returns
 the stored paths.
 
+A message reaches the agent at once: a working agent takes it into its running turn (Claude Code, Codex and Codex
+Cloud), and an idle one starts its next turn with it. `--wait` (0.28.0+) says which:
+
+```sh
+$ shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Use the staging database instead" --wait
+Message sent (12).
+Steered into the running turn.
+```
+
+It prints `Started the next turn.` when the agent was idle; `--json` adds `delivery` (`state`, `delivered_at`,
+`steered`).
+
 Choose the model and reasoning effort a new thread starts with (0.17.0+):
 
 ```sh
@@ -202,14 +226,14 @@ resolution before preserve-all can upload; a registration whose folder is gone h
 With CLI 0.24.0+, a move during a reply stops the local turn and continues the same reply in the cloud automatically, redoing the interrupted step. An agent calling `move_to_cloud` inside its own turn waits for that turn to finish. Uncommitted edits come along, and your working tree, index and branch stay as
 they are. The cloud work comes back to your checkout by itself, and typing in the local Claude Code copy shows one line
 that it continues in the cloud. Sessions from Claude Desktop's Code tab and the Codex app move the same way; in the
-macOS menu bar, a project's recent sessions have **Move to cloud** in their ⋯ menu, and with the Shardflux MCP server
+Shardflux app's menu, a project's recent sessions under **On this Mac** (**On this computer** on Ubuntu) have
+**Move to cloud**, and with the Shardflux MCP server
 you can ask the agent itself to continue in the cloud. A session is listed under every repository it worked in, also
 one that began in another folder such as Claude Desktop's scratch folder, and `--path <repository>` moves it from
 anywhere (0.22.0+).
 
-With menu bar 0.8.5+, a failed move stays at its session’s row with its reason on hover and **Retry move to cloud**
-in **⋯**. Retry or Refresh clears the previous failure. CLI 0.23.0+ records a matching stable Node.js path on macOS,
-and menu bar 0.8.5+ recovers Node.js after an upgrade removes the recorded binary.
+In the Shardflux app, a failed move stays at its session’s row as **Couldn’t move**, with its reason on hover:
+choose it to try again (**Retry move to cloud** in the row's menu). CLI 0.23.0+ records a matching stable Node.js path on macOS.
 
 Start a thread in T3 Code from the command line (0.17.0+):
 
@@ -229,6 +253,11 @@ conversation with `shard conversations send <id> "<answer>"` (0.23.0+ names it w
 with in claude.ai and the Claude app (default `☁`: "☁ Fix login bug · todo-app"); `shard settings` shows it with where
 conversations open.
 
+Finished cloud work lands in your folder by itself: a conversation's commits come into the branch it started from, a
+board task's result into your linked folder and the project's default branch. `shard settings --auto-land off`
+(0.28.0+) keeps it in the cloud on this computer (`shard task land` and `shard conversations land` still land on
+request); `--auto-land on` turns it back on. The Shardflux app's Settings → Projects changes the same switch.
+
 Terminal conversations open in the terminal you choose (0.22.0+):
 
 ```sh
@@ -251,7 +280,7 @@ shard conversations try <conversation>
 
 Your branch opens in `.shard/worktrees/<name>`, syncs both ways, and its dev servers appear at localhost.
 Ctrl-C stops local sync. Your main checkout stays available for your own work.
-Device tools ask for approval on your computer before preparing the conversation’s local worktree. With CLI 0.15.0 and menu bar 0.3.0, Review shows the exact command, file direction, paths or port mapping; access outside the conversation folder only offers Allow once. Live transcripts stay in
+Device tools ask for approval on your computer before preparing the conversation’s local worktree. With CLI 0.15.0+, Review shows the exact command, file direction, paths or port mapping; access outside the conversation folder only offers Allow once. Live transcripts stay in
 
 From 0.25.0, an agent can also list a folder on your computer, make one of your projects from it, and move a file to or from anywhere on it by an absolute or `~/` path. Each asks first: **Allow once**, or **Always for this folder**, which covers that kind of request for that folder and everything inside it. `shard projects link <path> [--prompt <text>]` does the same from a terminal: the folder is prepared in the background, kept as this computer’s live copy, and `--prompt` starts a conversation there.
 `~/.config/shardflux/conversations/`; ended sessions enter Claude Code’s or Codex’s native history. Transcript files up to 64 MiB are supported (0.14.0+).
@@ -259,14 +288,14 @@ From 0.14.3, transcript copying runs independently of device approvals. Unknown
 
 Every conversation's committed files are on your computer too (with the helper running; macOS 0.16.0+, Linux 0.17.0+):
 `~/Shardflux/<repository>/<base branch>/<conversation>/` holds what each conversation changed or added, read-only,
-and updates when its branch moves. Large files are listed as `<file>.placeholder.txt`; download one with the menu
-bar's **Download** or:
+and updates when its branch moves. Large files are listed as `<file>.placeholder.txt`; open one from the
+conversation's computer in the Shardflux app and choose **Save to Downloads**, or:
 
 ```sh
 shard files pull hype-video out/hype.mp4
 ```
 
-Finished conversations land in your checkout by themselves (0.16.0+, with the menu bar app running). When a
+Finished conversations land in your checkout by themselves (0.16.0+, with the Shardflux app running). When a
 conversation's turn ends with its work committed, the branch it started from moves to its commits and the changed
 files are written in place, next to your own uncommitted edits, which stay as they are (where both touched the same
 lines, your text is kept). `git status` keeps showing only your edits. A conversation started from a checkout with
@@ -278,6 +307,11 @@ shard conversations landing            # auto (default), pr or off for this proj
 shard conversations landing backups    # then: shard conversations landing restore <backup>
 ```
 
+To land a finished conversation manually, run `shard conversations land <id> merge`. In a project with several
+repositories it chooses a linked folder of that conversation's repository; the hub's default branch for another
+repository stays where it is. `--path <folder>` chooses the destination explicitly. From 0.28.1, manual landing
+uses the result’s own ready computer or the project reader, so deleting an unrelated thread does not interrupt it.
+
 For application workspace commands, `shard signup` creates an account and saves a project key, or set
 `SHARDFLUX_API_KEY` to a key from the console and run `shard login`. `shard --help` lists every command.
 
@@ -379,7 +413,7 @@ answer) or their product (it runs VMs for its customers through the API, SDK or
 Commands that wait for your user in the browser (sign-ins, `--ask`) take up to 10 minutes: run them with a long timeout
 or in the background.
 
-**Their product** (no agent sign-ins, menu bar or machine):
+**Their product** (no agent sign-ins, Shardflux app or machine):
 
 2. `eval "$(shard env)"` exports `SHARDFLUX_API_KEY` for the SDKs, the MCP server and your product's server. Keep it in
    server-side secrets.
@@ -649,9 +683,11 @@ and the session renewals of step-up and password changes).
 ## Update
 
 `shard update` **(0.13.5+)** brings everything Shardflux installed on this computer up to date: shard itself
-(the `shardflux` package or `@shardflux/cli`), its SDK, the macOS menu bar app and a globally installed
+(the `shardflux` package or `@shardflux/cli`), its SDK, the Shardflux app and a globally installed
 `@shardflux/mcp`. It runs one install of the latest versions with the package manager that installed shard (npm,
-pnpm, bun or Volta) and restarts the menu bar on its new app. The menu bar's **Update** button runs the same command.
+pnpm, bun or Volta) and restarts the app on its new version; **Update now** in the app's Settings → Updates runs the
+same command. After `npm i -g shardflux` the app moves to the new version by itself once no window is open and no
+approval or move is in progress.
 
 ```sh
 shard update --check   # what is behind, without installing
@@ -706,7 +742,10 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `version [--check]` | Print the CLI and SDK versions and the update status (`--check` asks the API now). |
 | `usage [--org <id>] [--estimate \| --series \| --workspace <id\|key>] [--from T] [--to T] [--granularity hour\|day] [--meter M]` | Usage summary for the current period: plan, meters and allowances. `--estimate`: the bill so far and projected allowance use; `--series`: usage over time; `--workspace`: one workspace's usage over time (0.5.0+). The summary includes the [overage](#usage-and-overage) block (0.5.1+). |
 | `feedback [--yes] [--category C] [--workspace W] [--request-id ID] [--error-code CODE] [--command TEXT] [--from-file F\|-] <message...>` | Preview feedback; `--yes` sends after explicit user authorization (0.22.0+). See [Feedback](#feedback-preview-and-user-approval). |
-| `route [--task ID] [--org O] [--project P] <text...>`, `ask [--task ID] [--org O] [--project P] <question...>` | The board's input bar (0.25.0+): where a line of input goes (its project or your home; a task, a question or a steer, split per task), and a quick question about your work, answered as it is written. |
+| `orchestrator say [--wait [--timeout D]] [--task ID\|--report ID\|--needs-you ID\|--input ID\|--conversation ID] <words...>`, `orchestrator list [--all]`, `orchestrator retry\|dismiss\|restore <input-id>` | Your orchestrator (0.28.0+): say something and every input is handled at once by its own thread; `--wait` prints its curated result. See [Your orchestrator](#your-orchestrator-0280). |
+| `brain ls [prefix] [--org O] [--all] [--limit N] [--cursor C]`, `brain get <path> [--org O] [--sha256 HEX] [-o FILE]` | Your brain (0.28.0+): your orchestrator's answers, reports and notes, read from any device. See [Your brain](#your-brain-0280). |
+| `route [--task ID] [--org O] [--project P] <text...>`, `ask [--task ID] [--org O] [--project P] <question...>` | Deprecated; use `shard orchestrator say`. The board's input bar (0.25.0+): where a line of input goes, and a quick question about your work. |
+| `conversations archive\|unarchive\|seen <id...>` (`c archive`) | Your inbox, the same on every device (0.28.0+): archive conversations, bring them back, or mark them seen. `--json` prints `{data, skipped}`. See [Conversations](#conversations). |
 | `conversations delete <id> --yes` (`c delete`) | Delete a conversation everywhere at once (0.25.0+): its agent stops, its computer is deleted, and its messages, transcript and branch go with it. `--json` prints `{id, deleted, deleted_at, operation}`. See [Conversations](#conversations). |
 | `workspaces open <key> --template <slug> [--secret NAME]... [--input NAME=value]... [--input-file F] [--lifetime persistent\|session] [--mode processful\|file-first] [--cpu-millis N --memory-mib N --disk-gib N] [--allocation-mode fixed\|elastic] [--memory-held N] [--no-wait] [--timeout 5m] [--timing]` | Open by key. Creates the workspace on first use and reconnects or resumes it afterwards, never resetting it. Waits until it is ready (the template's start commands and services included) unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--input` (0.4.0+) passes the template's text inputs (replacing those of an existing workspace); `--input-file` reads `NAME=value` lines or a JSON object. `--lifetime session`: the workspace is discarded when the session ends (`workspaces close` or the idle timeout), and the key then opens a new workspace. `--mode file-first` (0.5.0+) opens a [file-first workspace](#file-first-workspaces); the default is processful for a new key and the stored mode for an existing one. `--allocation-mode elastic` (0.8.0+): [elastic memory](#elastic-memory-080). |
 | `workspaces list [--state S] [--prefix P] [--lifetime persistent\|session\|any] [--purpose standard\|template_draft\|template_test\|any] [--include-deleted] [--all] [--limit N] [--cursor C]` | One page, or every page with `--all`. The next cursor is printed on stderr. By default only persistent standard workspaces are listed. A file-first workspace's state reads `running (file-first)` (0.5.0+). |
@@ -941,6 +980,7 @@ without waking it (the state at suspension); `files search` then notes it on std
   is still queued after 120000 ms`). The operation continues server side:
   `shard operations wait <id>` keeps waiting. Without either (0.16.0+), a resume queued for capacity is waited for
   until its deadline, its place shown on stderr (see [Start deadlines](#start-deadlines)).
+- Admission queues (0.28.0+, SDK 0.29.0): an open keeps its body and Idempotency-Key while waiting, and stderr says `queued for admission; retrying in 2 s`. Each wait honors `Retry-After` within the SDK admission timeout (default 2 minutes).
 - A call refused while the workspace's host makes room to wake it (503 `host_capacity`) or while every workspace the
   plan lets work at once is busy (429 `quota_exceeded`) did not run: `shard` sends it again after each `Retry-After`,
   for up to 2 minutes (0.16.0+), and stderr says `waiting for room on the workspace's host (position 2)` once.
@@ -1024,7 +1064,8 @@ $ shard ws resize acme/demo --elastic --held 1024    # switch modes live
 Memory changes live, and disks grow online. A suspended workspace gets its new size when it resumes, before its first
 call. CPU changes live within the vCPUs the workspace booted with; a larger CPU size applies at the next start. Each
 resource says when it applies (`now`, `on resume` or `next start`), and the new caps are stored, so every later start
-uses them. `--json` prints the result with `applies_at` per resource and the stored `caps`.
+uses them. `--json` prints the result with `applies_at` per resource and `caps`. A non-null `caps.disk_gib` is bounded
+by the admitted plan and template ceiling and the acknowledged disk size. `disk.requested_gib` retains the resize request.
 
 ## Burst execution (0.8.0+)
 
@@ -1506,8 +1547,8 @@ machine on its next use (0.20.0+).
 Skills, commands, agents, output styles, memories and `CLAUDE.md` / `AGENTS.md` lines that Claude or Codex saves in a
 cloud conversation come back to this computer by themselves, seconds after the turn ends, and into your saved
 machine too (0.20.0+). A file you changed here at the same time keeps your version, with the cloud's next to it
-(`CLAUDE.cloud.md`); a deleted one goes to the Trash. Project memory follows the project both ways. The menu bar says
-what arrived in one line, and `agent-config-return.jsonl` in the config directory lists every change.
+(`CLAUDE.cloud.md`); a deleted one goes to the Trash. Project memory follows the project both ways. The Shardflux app
+says what arrived in one line, and `agent-config-return.jsonl` in the config directory lists every change.
 `shard machine save --wait` and `shard template save --wait` return once the new version is ready (0.13.3+).
 A version larger than the plan's workspace disk names its size and the disk, with `retryable: false` and a hint: delete
 what the VM does not need, then save again, or move to a plan with a larger disk (`shard billing plans`); `--json`
@@ -1524,7 +1565,7 @@ see the [settings and billing reference](https://docs.shardflux.dev/limits#cloud
 Claude needs one cloud sign-in per account; Codex uses your copied login.
 
 Import project secrets from hsec, 1Password, Bitwarden or Keychain. Approve browser fills from the attached CLI or
-menu bar; remember a selected login for unattended work with automatic relay renewal. Bound secret values are
+the Shardflux app; remember a selected login for unattended work with automatic relay renewal. Bound secret values are
 redacted from command output and saved logs.
 
 Imported secrets: stored encrypted with AWS KMS; only this project's workspaces can load it, and every load is logged.
@@ -1576,6 +1617,22 @@ Another member's personal account can be made active only by that member.
 another account in a cloud VM and `shard agents accounts remove claude:2` removes one. To remove someone else's active
 account, make another one active first; your own you can always remove. `--json` prints the API's account list.
 
+From 0.28.0, `shard agents models` shows the models each active account can use, as Claude and ChatGPT list them
+for that account (the same lists Claude Code and Codex fill their pickers with): effort levels with the default
+starred, the default model, and what the plan does not include.
+
+```text
+Claude · marc@example.com (active)
+  claude-opus-5-5            Opus 5.5    low medium* high xhigh max  (default)
+  claude-fable-5-1           Fable 5.1   low medium high* xhigh max
+  claude-sonnet-5-5          Sonnet 5.5  low medium* high xhigh max
+  More models
+  claude-haiku-4-5-20251001  Haiku 4.5   no effort levels
+```
+
+`--account claude:2` shows another account, `--all` every account, `--refresh` asks again (lists are kept for an
+hour), and `--json` prints the API's answer. Pass an id to `shard agents new --model` (with `--effort`).
+
 ## Conversations
 
 From 0.14.0, `shard conversations list|get|send|wait|land|move` manages project conversations. `shard c` is the short form. Conversations retain their branch and transcript as their VM binding changes.
@@ -1623,6 +1680,24 @@ Conversation JSON includes `join_mode` and the worktree used by reviewers and wo
 
 `shard conversations resume <id>` continues a saved conversation in a fresh VM under the same identity (0.14.0+). `shard ./ --resume` uses this same path. `shard conversations reader <project-id>` opens a small read-only workspace for saved branches and transcripts; the Mac transcript mirror opens it automatically when no project VM is live. Adaptive idle reclaims the reader.
 
+Your inbox is the same on every device (0.28.0+): `shard conversations archive <id...>` archives conversations from
+your own inbox, `shard conversations unarchive <id...>` brings them back, and `shard conversations seen <id...>` records
+that you opened them now, so a result that finished before then is no longer new to you in the Shardflux app or any
+other client. Name one conversation or many in one command. Only your view changes: the conversations, their agents
+and computers carry on, and everyone else keeps their own inbox. `--json` prints the API's answer, `{data, skipped}`:
+the conversations with your `seen_at` and `dismissed_at`, and the ids not found. `shard c get --json` and
+`shard c list --json` carry the same two fields.
+
+```sh
+shard c archive conv_k3m5q7s2u4w6y3b5d7f2h4j6ln conv_a7k2m4q6s3t5v7x2z4b6d3f5h7
+# Archived conv_k3m5q7s2u4w6y3b5d7f2h4j6ln  Fix login
+# Archived conv_a7k2m4q6s3t5v7x2z4b6d3f5h7  Upgrade the test runner
+shard c unarchive conv_a7k2m4q6s3t5v7x2z4b6d3f5h7
+# Unarchived conv_a7k2m4q6s3t5v7x2z4b6d3f5h7  Upgrade the test runner
+shard c seen conv_k3m5q7s2u4w6y3b5d7f2h4j6ln
+# Marked seen conv_k3m5q7s2u4w6y3b5d7f2h4j6ln  Fix login
+```
+
 `shard conversations delete <id> --yes` (0.25.0+) deletes a conversation everywhere at once: its agent stops, its
 computer is deleted (a computer other conversations share stays for them), and its messages, transcript and branch go
 with it, on every device. From then on it leaves every list and reads not found; `shard c feed` shows it once as
@@ -1634,8 +1709,73 @@ shard c delete conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --yes
 # Deleted: conv_k3m5q7s2u4w6y3b5d7f2h4j6ln
 ```
 
+### Your orchestrator (0.28.0+)
+
+`shard orchestrator say` passes your words to the API as one input, without cutting the final instruction.
+
+Your orchestrator is your own agent on top of every project, on its own Shardflux computer and the same on every
+device. `shard orchestrator say` sends it your exact words and answers at once with the input and its place in line;
+every input is handled in parallel by its own thread, which answers it, puts tasks on the board, asks you something or
+adds it to an input in flight. `--wait` follows it and prints what it became:
+
+```sh
+shard orchestrator say --wait Lets check on our language model training progress
+# Training is 73% done, on pace to finish at 16:40
+#   Moved
+#   - Loss is down to 1.84: from 2.31 at step 5,000 (14:02)
+#   - Checkpoint saved: at step 7,000
+#   Still open
+#   - Eval has not run: it starts after the last checkpoint
+#   media: loss-curve.png (image, 1200×800, 84.0 KB)
+#   Sources: train.log (~/code/lm-train/train.log), wandb.ai (https://wandb.ai/acme/lm)
+#   Follow-ups: Check again in an hour
+shard orchestrator say --task task_h7g4d7tqyv2pz3a2npyo4rpgzq use postgres instead
+# in_q3vd5k2xbnwjm7e4rtyhcu6aio	queued (1 in line)
+shard orchestrator list
+# in_q3vd5k2xbnwjm7e4rtyhcu6aio	working	use postgres instead
+# in_7wcx227ovjpei4u6i47llu7w4i	done	Lets check on our language model training progress	Training is 73% done, on pace to finish at 16:40
+```
+
+The answer card is the verdict, then its points under the headings the orchestrator chose (a point's time in your
+local time; an answer written as plain facts prints its facts), then a media line for each picture, video or file it
+shows (an image with its width×height once measured). Each is a file on the project drive: `--json` has its
+`file.path` and `file.sha256`, and `shard drive get <path> --sha256 <sha256> -o <file>` saves it. `--task`, `--report`, `--needs-you`, `--input`
+and `--conversation` point at the row your words are about. `--wait` stops when the input is done (its answer card and
+the tasks it created), merged (the input it was added to), waiting
+(the line it waits on; a question names the `shard needs-you answer oq_… --text <answer>` that answers it) or failed
+(exit 6; `shard orchestrator retry <input-id>` sends it again); `--timeout` (default 10m) stops following with exit 5
+while the input goes on. `shard orchestrator list` shows your recent inputs newest first (`--all` adds the ones you
+dismissed with `shard orchestrator dismiss`); `shard orchestrator restore <input-id>` (0.28.0+) brings one back on every
+device. Signed in, they reach your orchestrator (`--org <id|slug>` when you belong
+to several); with `SHARDFLUX_API_KEY` set, the orchestrator of the person who created that key. `--json` prints the
+API's objects (`{input}`, `{inputs, cursor}`).
+
+Device helper recovery (0.28.0+): projects register independently and report when a sign-in needs attention. A new
+sign-in on this computer (a new API key from `shard setup`, another account) gets this computer a new device id by
+itself and registers again at once. See the [error reference](https://docs.shardflux.dev/reference/errors) for recovery.
+
+When your orchestrator needs your computer (the tail of `~/code/lm-train/train.log`, say), the device helper asks you
+first with the exact command and folder, **Allow once** or **Deny**, and runs it in your home folder or the `~/`
+folder it names (0.28.0+). Each of these commands asks; none runs under an Always grant, unless you let your agents
+run things without asking.
+
+**Your agents on this computer (0.28.0+).** Choose once how this computer answers your own agents:
+
+| `shard device approvals` | Your agents |
+|---|---|
+| `auto` | Allow everything: commands, files, ports and folders run without asking |
+| `read` | Allow reading: folder listings and files copied to a conversation run; anything that changes this computer asks |
+| `ask` | Ask every time |
+
+The first request asks which you want (the Shardflux app's prompt, or one line from `shard` with both commands) and
+runs under your choice; the app's Settings and `shard device approvals` change it any time. A teammate's request
+always asks. `shard device approvals` lists what ran without asking (`--json` for `recent`).
+
 ### Route input and ask about your work (0.25.0+)
 
+`shard route` and `shard ask` are deprecated (0.28.0); use `shard orchestrator say` (each prints a one-line notice on
+stderr).
+
 `shard route` reads a line of input the way the board's input bar does: which project it belongs to (or your home),
 whether it is a new task, a question or a steer for an open task, and each task in your own words when it asks for
 several. `shard ask` answers a quick question about your work from the board, printing the answer as it is written.
@@ -1711,14 +1851,20 @@ shard projects sync list                # selected projects and their state
 shard projects sync pause ~/code/web    # stop preparing it (remove: forget it)
 ```
 
-The device helper (started by the menu bar or the Linux app) prepares each selected project in a short-lived VM: it
+The device helper (started by the Shardflux app, and on Linux by its systemd service) prepares each selected project
+in a short-lived VM: it
 puts the project's current state in the project cache, and when its dependency files change, installs them and saves
 the project template. Conversations then start without sending the project, with dependencies installed. Only the
-projects you add are prepared; onboarding and Settings → Projects in both desktop apps choose them too.
+projects you add are prepared; onboarding (**Sync projects**) and Settings → Projects in the Shardflux app choose them
+too.
 
-### Menu bar conversation shortcut (0.15.0+)
+### Launcher (0.15.0+)
 
-The macOS menu bar's **New conversation** action (menu bar 0.3.0+) opens the same launcher as **Option-Shift-Space**. It requires a task and project, remembers Claude/Codex, and invokes the commands below. Configure the hotkey in the macOS Settings window (⌘,), with conflict detection and a fallback.
+**New conversation** in the Shardflux app's menu opens the same launcher as **⌥⇧Space** (**Alt+Shift+Space** on
+Ubuntu; a GNOME keybinding on Wayland), in the project open in the app in front (app 0.9.0+). It starts the
+conversation where your conversations open (Settings → Agents → **Open conversations in**), with a card near the top
+of the screen that follows each start (**Show all N launches**); change the shortcut, **Detect my project** and the
+panel's position in Settings → Launcher. From a terminal:
 
 ```sh
 shard agents new --app claude --path ./ --prompt "Review the billing changes" --json
@@ -1772,7 +1918,9 @@ branch: `Landed in ~/code/best-todo · 3f2a1c9`.
 Later tasks to keep, oldest first. `shard needs-you answer <id>` answers any of them: `allow`, `always` (also adds the
 always-allow rule for the project; `--everywhere` for every project) or `deny` for a permission request, `--pick` for an
 agent's question in one, `--text` for a question, `land` (as `shard task land`), `keep` or `discard` for finished work, and `--keep <task-id>`
-(or `keep`, `discard`) for Later tasks. The agent goes on as soon as you answer.
+(or `keep`, `discard`) for Later tasks. The agent goes on as soon as you answer. Your orchestrator's questions are
+`oq_…` items (`--text`), and what it asked your computer while it was offline waits as a `dev_…` item ("Waiting for
+your computer: list ~/code"): it runs when your computer is back, and `cancel` drops it (0.28.0+).
 
 **Approvals.** The approval mode answers your agents' permission requests before they reach you: `ask` sends every one
 to you, `routine` (the default) approves tests, builds, reads and installs, `trusted` approves everything except
@@ -1795,7 +1943,7 @@ Explicit `agents new --in terminal`, `--in t3`, and `--like` launches keep their
 
 Save progress (0.22.0+): Machine and template saves show source size and an estimated duration, then queued/build state and phase updates immediately. With `--json`, progress events go to stderr and the final stdout document includes `preflight` and `phases`. Failure and timeout output retain the latest counters and `details.last_progress`, with the build id and recovery action. If an older API cannot expose the build, JSON stderr emits `save_started` with the version/build id and leaves the phase unknown. Missing final host reports preserve the last observed progress.
 
-Desktop launch cards (0.22.0+): the bundled desktop apps clear and close the launcher on submission, then show each pending start in a layered card stack near the top of the display. **Show all launches** expands individual statuses and recovery.
+Desktop launch cards (0.22.0+): the Shardflux app clears and closes the launcher on submission, then shows each pending start as a card near the top of the display. **Show all N launches** expands their statuses and recovery.
 
 
 ### Pending execution cancellation (0.23.0+)
@@ -1829,7 +1977,7 @@ shard c list --org acme --state needs_you
 shard c feed --org acme --json
 ```
 
-`shard conversations list --all` reads every page, keeping the selected project, state and parent filters. `--json` returns `data` and `nextCursor`. Linux desktop 0.1.11+ reads all conversation and computer pages and shows the selected project key’s organization, usage, spend and connector status in Settings.
+`shard conversations list --all` reads every page, keeping the selected project, state and parent filters. `--json` returns `data` and `nextCursor`.
 
 ## Project drive (0.25.0+)
 
@@ -1866,6 +2014,32 @@ shard drive rm tasks/t_ab12/notes.md
 - The drive is the API key's project, or `--project <id>`. Signed in (`shard auth login`), `--project` takes any of
   your projects by id or slug, and without an API key the drive is your default project's.
 
+## Your brain (0.28.0+)
+
+`shard brain` reads your brain: your archive in an organization, kept by your orchestrator. Every answer it publishes is
+filed as `reports/<YYYY-MM-DD>/<folder>/report.md` with the answer's media next to it (image thumbnails under
+`.thumbs/`), with its own notes and files and an `index.md` of everything, newest first. Your orchestrator writes it;
+you read it from any device, with every computer asleep. Paths are relative to the brain's root, the names `~/brain`
+shows on your orchestrator's computer.
+
+```sh
+shard brain get index.md
+shard brain ls reports/2026-10-17/
+# SIZE      SAVED                 TYPE           PATH
+# 195.3 KB  2026-10-17 09:12:40Z  image/png      reports/2026-10-17/training-progress-ab12cd34/loss.png
+# 1.2 KB    2026-10-17 09:12:41Z  text/markdown  reports/2026-10-17/training-progress-ab12cd34/report.md
+shard brain get reports/2026-10-17/training-progress-ab12cd34/report.md
+shard brain get reports/2026-10-17/training-progress-ab12cd34/loss.png -o loss.png
+```
+
+- `ls [prefix]` lists the current files by path, 200 to a page (`--limit` up to 1000, `--cursor`, `--all`); `--json`
+  returns `data` (each file with its `sha256`), `next_cursor` and the brain's `version`, which moves whenever anything
+  in it changes.
+- `get` writes the bytes to standard output, or to a file with `-o`, once they match their SHA-256; `--sha256` reads
+  exactly that version, and `--json` returns `content_base64` with `sha256`, `size` and `content_type`.
+- Signed in, it is your brain in your saved organization (`shard orgs use`), else your only one, or `--org <id|slug>`;
+  with `SHARDFLUX_API_KEY` set, the brain of the person who created that key.
+
 ## Model template (0.25.0+)
 
 `shard models` shows which harness, model and effort each role of a task runs with, from the Claude and Codex accounts
@@ -1910,3 +2084,5 @@ shard volumes detach --machine datasets
 ```
 
 Defaults mount in new and running conversations. Removal waits for current work to finish and preserves manual attachments. Add `--json` to read propagation results.
+
+Bare `shard` in a coding-agent shell or without a TTY returns its setup guide using locally saved sign-in and API-key state.

package/dist/account-commands.d.ts

@@ -1,5 +1,5 @@
-import { setupGuide } from './agent-setup.js';
-import type { Ctx, Handler } from './commands.js';
+export { agentSetupGuide } from './agent-setup.js';
+import type { Handler } from './commands.js';
 export declare const DEFAULT_API_URL = "https://api.shardflux.dev";
 /** What `shard setup` gave a key before 0.15.1: every tool but `computer`. Such a saved key is replaced with a full one. */
 export declare function outdatedDefaultKey(permissions: readonly string[]): boolean;
@@ -18,6 +18,4 @@ export declare function exportLine(shell: ShellKind, name: string, value: string
 export declare function parseTime(text: string, option: string, now?: number): string;
 /** A spend cap in dollars ("9", "9.5", "9.50", "$9") as minor units (cents); at most two decimals. */
 export declare function dollarsToMinor(text: string, what: string): number;
-/** The setup guide for this computer: whether a session and an API key are saved (no network call). */
-export declare function agentSetupGuide(ctx: Ctx): ReturnType<typeof setupGuide>;
 export declare const ACCOUNT_HANDLERS: Record<string, Handler>;

package/dist/account-commands.js

@@ -21,7 +21,8 @@ import { API_KEY_TOOL_PERMISSIONS, CheckoutTimeoutError, Shardflux, ShardfluxAcc
 import { CLI_VERSION, UUID, parseDuration, parsePositiveInt } from "./args.js";
 import { openUrl } from "./browser.js";
 import { defaultClientName, startDeviceAuthorization, waitForDeviceSession } from "./browser-login.js";
-import { setupGuide, setupGuideText } from "./agent-setup.js";
+import { agentSetupGuide, setupGuideText } from "./agent-setup.js";
+export { agentSetupGuide } from "./agent-setup.js";
 import { allOrgs, allProjects, byRef, choices, findOrg, gone, keyOrganizationWarning, keyScope, resolveOrg, resolveProject, staleDefaultOrg } from "./account-scope.js";
 import { readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
@@ -768,11 +769,6 @@ function wantsBrowser(ctx, values) {
         return true;
     return ctx.input.interactive && !ctx.json;
 }
-/** The setup guide for this computer: whether a session and an API key are saved (no network call). */
-export function agentSetupGuide(ctx) {
-    const profile = ctx.store.profile(ctx.apiUrl);
-    return setupGuide({ signedIn: ctx.sessionSource() !== null, email: profile.session?.user?.email ?? null, apiKey: profile.api_key !== undefined || Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) });
-}
 /**
  * After `orgs use` / `projects use` (0.20.2+): the defaults moved, but workspace, agent and usage commands use the API
  * key, which may act in another organization. Says so; on a terminal offers to make a key for the new default (a

package/dist/account-pool.d.ts

@@ -6,7 +6,7 @@
  * With --json every write prints the updated `{accounts, pool}` block (the menu bar redraws from it), plus the account
  * it changed. Sign-ins run the provider's own login in a workspace, as `shard agents credentials login claude` does.
  */
-import type { AgentAccount, AgentAccountList, AgentAccountWindow } from '@shardflux/sdk';
+import type { AgentAccount, AgentAccountList, AgentAccountModels, AgentAccountWindow } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
 /**
  * Codex names its windows primary and secondary; their length says which is the 5-hour and which the weekly one (a
@@ -31,6 +31,16 @@ export declare function formatAccounts(list: AgentAccountList, now: number): str
 export declare function formatUsage(list: AgentAccountList, now: number): string;
 /** Codex's device sign-in page, as Codex 0.160.0 prints it (test/fixtures/cloud-agents/codex-login-device-auth-0.160.0.json). */
 export declare function codexLoginUrls(output: string): string[];
+/**
+ * `shard agents models` (0.27.0+): each account's models as its provider lists them for that account, the way Claude
+ * Code and Codex ask for their pickers. The default effort is starred; the harness's default model is marked.
+ */
+export declare function formatModels(entries: Array<AgentAccountModels & {
+    label?: string;
+    active?: boolean;
+}>, now: number): string;
+/** `shard agents models` (no `shard models` alias: that one is the model template). */
+export declare const AGENT_MODELS_HANDLERS: Record<string, Handler>;
 export declare const ACCOUNT_POOL_HANDLERS: Record<string, Handler>;
 /** The `accounts` block of `shard agents targets --json` (0.18.0+): the account list for the menu bar; null when it cannot be read. */
 export declare function targetsAccounts(ctx: Ctx): Promise<AgentAccountList | null>;

package/dist/account-pool.js

@@ -207,6 +207,54 @@ async function signIn(ctx, values, app) {
             await api.cancelSignIn(claim.sign_in_id).catch(() => undefined);
     }
 }
+const REASONS = { disabled: 'turned off for this account', not_entitled: 'not included for this account', not_in_plan: 'not in this plan' };
+/** "3m ago", "2h ago". */
+const ago = (at, now) => { const m = Math.max(0, Math.round((now - Date.parse(at)) / 60_000)); return m < 60 ? `${m}m ago` : `${Math.round(m / 60)}h ago`; };
+/**
+ * `shard agents models` (0.27.0+): each account's models as its provider lists them for that account, the way Claude
+ * Code and Codex ask for their pickers. The default effort is starred; the harness's default model is marked.
+ */
+export function formatModels(entries, now) {
+    if (!entries.length)
+        return 'No Claude or ChatGPT/Codex account is signed in. Add one with shard agents accounts add claude|codex.\n';
+    const lines = [];
+    for (const e of entries) {
+        const freshness = e.source === 'builtin' ? 'the harness’s own list until the provider answers' : e.stale && e.fetched_at ? `as of ${ago(e.fetched_at, now)}` : '';
+        lines.push(`${PROVIDERS[e.provider]}${e.label ? ` · ${e.label}` : ''}${e.active ? ' (active)' : ''}${freshness ? ` · ${freshness}` : ''}`);
+        const width = Math.max(...e.models.map(m => m.id.length), 8) + 2, nameWidth = Math.max(...e.models.map(m => m.name.length), 4) + 2;
+        const row = (m) => `  ${m.id.padEnd(width)}${m.name.padEnd(nameWidth)}${m.available
+            ? `${m.efforts.map(x => x === m.default_effort ? `${x}*` : x).join(' ') || 'no effort levels'}${m.id === e.default_model ? '  (default)' : ''}`
+            : `unavailable: ${m.reason_text ?? (m.reason ? REASONS[m.reason] : 'not offered')}`}`;
+        const main = e.models.filter(m => m.section === 'main'), more = e.models.filter(m => m.section === 'more');
+        lines.push(...main.map(row));
+        if (more.length)
+            lines.push('  More models', ...more.map(row));
+        lines.push('');
+    }
+    lines.push('Start with one: shard agents new <claude|codex> --model <id> --effort <level> (* the model’s default effort).');
+    return `${lines.join('\n')}\n`;
+}
+/** `shard agents models` (no `shard models` alias: that one is the model template). */
+export const AGENT_MODELS_HANDLERS = {
+    async 'agents models'(ctx, values) {
+        const api = ctx.cloud().agentAccounts;
+        const refresh = values.refresh === true;
+        if (values.account !== undefined) {
+            if (typeof values.account !== 'string' || !values.account.trim())
+                throw new UsageError('--account needs an account: its id, claude:<n>, codex:<n>, email or label.');
+            const account = findAccount(await api.list(), values.account.trim());
+            if (account.kind !== 'oauth')
+                throw new UsageError(`${name(account)} is an API key: it has no model list. Sign in with shard agents accounts add ${account.provider}.`);
+            const models = await api.models(account.id, { refresh });
+            out(ctx, formatModels([{ ...models, label: name(account), active: isActive(account) }], Date.now()), models);
+            return 0;
+        }
+        const all = await api.allModels({ provider: optionalProvider(values.provider), refresh });
+        const shown = values.all === true ? all.accounts : all.accounts.filter(a => a.active);
+        out(ctx, formatModels(shown, Date.now()), { accounts: shown });
+        return 0;
+    },
+};
 export const ACCOUNT_POOL_HANDLERS = {
     async 'agents accounts'(ctx, values) {
         const list = await ctx.cloud().agentAccounts.list({ provider: optionalProvider(values.provider) });