@shardflux/cli 0.28.0 → 0.28.2

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## Unreleased
 
+- The Shardflux app 0.9.3 (0.28.2+): `shard` installs and updates `@shardflux/desktop-darwin-arm64` / `-x64` and
+  `@shardflux/desktop-linux-x64` / `-arm64` 0.9.3 (files open beside your work, pictures and videos picture in picture,
+  ⌘2 shows the agents your orchestrator starts, needs-you questions read whole).
+
+- Agent credentials (0.28.2+, SDK 0.30.2): environment credential questions can be answered with `shard needs-you answer acred_ID --credential --ask` (or stdin / `--from-file`), with scope chosen before the write. Scope flags preserve organization and thread identity; workspace-only permission flags are rejected for agent credentials.
+
+- Agent credential scopes (0.28.2+): `shard secrets create NAME --scope agents --org ORG --ask` adds a credential for all your agents; use `--scope project --project PROJECT` or `--scope conversation --conversation CONVERSATION` for a local override. Import, list, get, update, rotate, versions, access-log and delete accept the same scope. Values use the secure page, stdin, or `--from-file` and never command arguments.
+- Conversation origin (0.28.2+, SDK 0.30.2): conversation starts stay compatible with older APIs: send launching-conversation provenance only after `/v1/meta` advertises `capabilities.conversation_origin: true`; no create fallback retry.
+
+- Question explanations (0.28.2+, SDK 0.30.2): needs-you output prints each question and its optional `option_details` in full, including what each choice does and what follows it.
+
+- Launch attribution (0.28.2+, SDK 0.30.2): preserve the requesting orchestrator thread when `project_link` starts work in a laptop folder. API and guest title sources strip pasted-content/image transport markers, so `shard agents list` shows the request text. Tasks delete their workers and spawned descendants along with their computers.
+
+- The Shardflux app 0.9.2 (0.28.1+): `shard` installs and updates `@shardflux/desktop-darwin-arm64` / `-x64` and
+  `@shardflux/desktop-linux-x64` / `-arm64` 0.9.2 (Stop in ⌘1, organization choice at the first sign-in, Sign in after
+  signing out).
+
+- Return the coding-agent setup guide without loading the account command handlers.
+
+- Manual landing uses the result’s own ready computer or the persistent project reader, so deleting an unrelated thread does not interrupt it.
+
+- Check T3 presence directly during startup, avoiding unrelated desktop-app probes before every command.
+
+- Orchestrator inputs preserve long pastes, including their final instruction, without an application character cap. `shard orchestrator say` sends the full text to the API.
+
+- Land a finished conversation in its own repository's linked folder when a project holds several repositories.
+  Preserve the hub's default branch when it belongs to another repository.
+
+- Load only the selected command and skip optional setup modules when their local state is absent.
+
+
+- Load interactive command surfaces on demand, keeping help/version and simple commands fast while preserving command parsing, saved-work housekeeping, setup guards and install registration.
+
+- Codex Cloud admission (0.28.1+, SDK 0.30.1): a stopped startup/open reports its stored reason and recovery instruction immediately (`codex_admission_stopped`), instead of calling it pending or pointing only at connector status.
+
+- Stored-file recovery (0.28.1+): workspace views show when files are saved for recovery; resume restarts the workspace from those files.
+
 - `shard orchestrator say` (0.28.0+, SDK 0.30.0): every input waits its turn in order,
   however many wait (no more 429), and one of your orchestrator's threads hears each input at once, all in parallel: a
   follow-up reaches the thread of the request it is about (the input reads merged), the row you point at reaches the
@@ -17,22 +54,22 @@
 - Restore an orchestrator input (0.28.0+, SDK 0.30.0): `shard orchestrator restore <input-id>` brings an input you
   dismissed back into `shard orchestrator list` on every device and prints `Restored: <your words>` (`--json`:
   `{input}`). Restoring an input that is not dismissed changes nothing.
-- Orchestrator answer media (0.27.0+, SDK 0.29.0): `shard orchestrator say --wait` prints a line for each picture,
+- Orchestrator answer media (0.28.0+, SDK 0.29.0): `shard orchestrator say --wait` prints a line for each picture,
   video or file the answer shows, after its points: `  media: loss-curve.png (image, 1200×800, 84.0 KB)` (the size in
   pixels once measured). `--json` adds the answer's `media`; `shard drive get <file.path> --sha256 <file.sha256>` reads
   one.
 
-- Orchestrator report cards (0.27.0+, SDK 0.29.0): `shard orchestrator say --wait` prints an answer the orchestrator
+- Orchestrator report cards (0.28.0+, SDK 0.29.0): `shard orchestrator say --wait` prints an answer the orchestrator
   wrote as a report as its verdict, then its points under their group headings, one line each:
   `- Loss is down to 1.84: from 2.31 at step 5,000 (14:02)`, the time short and in this computer's local time; a point
   written without a lead prints its words. Every point, source and follow-up prints whole, however long. An answer
   written as facts prints its facts as before. `--json` adds the answer's `points`.
 
-- Board content at any length (0.27.0+, SDK 0.29.0): `shard task show` prints a task's title, its plan steps and each
+- Board content at any length (0.28.0+, SDK 0.29.0): `shard task show` prints a task's title, its plan steps and each
   report's title and outcome whole, however long the agent wrote them (the terminal wraps them); `shard task edit
   --title` takes a title of any length.
 
-- Your brain (0.27.0+, SDK 0.29.0): `shard brain ls [prefix]` lists your brain's files (size, saved time, type and
+- Your brain (0.28.0+, SDK 0.29.0): `shard brain ls [prefix]` lists your brain's files (size, saved time, type and
   path; `--all`, `--limit`, `--cursor`; `--json` adds `next_cursor` and the brain's `version`) and `shard brain get
   <path>` writes a file's bytes to standard output, to a file with `-o`, or as `--json` (`--sha256` reads exactly that
   version). Your brain is your archive in an organization, kept by your orchestrator: its published answers as
@@ -58,18 +95,18 @@
   the one that branch holds, or two of its workers were), with what to do instead; nothing moves on the project hub or
   in your folder. It was a Git error ("refusing to merge unrelated histories") that read as if trying again could help.
 
-- Auto land switch (0.27.0+): `shard settings --auto-land on|off` turns automatic landing on or off for every project
+- Auto land switch (0.28.0+): `shard settings --auto-land on|off` turns automatic landing on or off for every project
   on this computer (on by default). Off, the live twin lands no conversation and new conversations start from your
   HEAD; `shard task land` and `shard conversations land` still land on request. `shard settings` shows it and `--json`
   adds `auto_land`. The Shardflux app reads the same switch to land finished board tasks with no click.
 
-- Message delivery (0.27.0+, SDK 0.29.0): `shard conversations send` reaches a working agent in its running turn
+- Message delivery (0.28.0+, SDK 0.29.0): `shard conversations send` reaches a working agent in its running turn
   (Claude Code, Codex and Codex Cloud) and starts an idle one's next turn; its help says so instead of "next turn".
   `--wait` waits up to 60 s and prints what happened: `Steered into the running turn.`, `Started the next turn.` or
   `Not delivered yet.` (`Delivery not confirmed yet: …` when Codex Cloud has not confirmed it); `--json` adds
   `delivery`. Without `--wait` the output stays `Message sent (<seq>).`
 
-- One Shardflux app (0.27.0+): `shard` installs and updates the one desktop app (menu bar or tray, onboarding,
+- One Shardflux app (0.28.0+): `shard` installs and updates the one desktop app (menu bar or tray, onboarding,
   launcher, conversations with their computers, device approvals, one Settings window) from
   `@shardflux/desktop-darwin-arm64` / `-x64` 0.9.0 on macOS (replacing `@shardflux/menubar-darwin`) and from
   `@shardflux/desktop-linux-x64` / `-arm64` 0.9.0 on Linux (replacing the GTK tray app), at the same places as before
@@ -84,31 +121,31 @@
   executable behind the app's launcher and names each library the computer is missing.
 - 0.27.0 includes the changes prepared as 0.26.0 (not released on its own): the entries marked 0.27.0 below.
 
-- Device registration (0.27.0+): isolate each project, back off transient failures and stop after eight attempts with
+- Device registration (0.28.0+): isolate each project, back off transient failures and stop after eight attempts with
   an actionable needs-attention message. A device id another sign-in registered (the API key `shard setup` replaced,
   or another account) is replaced by a new one (at most once every 10 minutes), with one line in the helper's log, and every project
   registers again at once, so your agents reach this computer without a restart. The old id is kept in
   `device-id-history.json`.
-- Your agents on this computer (0.27.0+): `shard device approvals auto|read|ask` chooses how this computer answers
+- Your agents on this computer (0.28.0+): `shard device approvals auto|read|ask` chooses how this computer answers
   your own agents: `auto` runs everything they ask without asking, `read` runs folder listings and files copied to a
   conversation and asks before anything else (commands, files saved here, ports, linking a folder), `ask` asks every
   time. The first request asks for the choice (the Shardflux app's prompt; without the app, `shard` prints the two
   commands once) and runs under the mode chosen. A teammate's request always asks. What ran without asking is listed
   by `shard device approvals` (`--json`: `recent`) and the app's Settings. Approvals carry `choose_mode: true` while
   nothing is chosen.
-- First prompts (0.27.0+): a Codex Cloud start queues its initial prompt while the executor prepares. Resuming an accepted start uses the same prompt key; an unconfirmed send keeps its created conversation.
+- First prompts (0.28.0+): a Codex Cloud start queues its initial prompt while the executor prepares. Resuming an accepted start uses the same prompt key; an unconfirmed send keeps its created conversation.
 
-- Device helper (0.27.0+): a command your orchestrator asks your computer to run (a home conversation, so no folder of
+- Device helper (0.28.0+): a command your orchestrator asks your computer to run (a home conversation, so no folder of
   it on this computer) asks you once with the exact command and folder ("Run on your Mac: sh -c tail -n 5 train.log ·
   in ~/code/lm-train"), Allow once or Deny, and runs in your home folder or the ~/ folder it names. A request whose
   conversation has no folder on this computer is refused with the reason instead of staying pending.
-- Filesystem recovery (0.27.0+): resume JSON/timing keeps `cold_boot_reason: guest_filesystem`; the existing note reports restarted processes. Ships with SDK 0.29.0.
+- Filesystem recovery (0.28.0+): resume JSON/timing keeps `cold_boot_reason: guest_filesystem`; the existing note reports restarted processes. Ships with SDK 0.29.0.
 
-- Admission queue waits (0.27.0+, SDK 0.29.0): workspace opens retry `429 admission_queued` within the admission timeout with the same body/key, honor full `Retry-After`, and display `queued for admission; retrying in 2 s` while waiting.
+- Admission queue waits (0.28.0+, SDK 0.29.0): workspace opens retry `429 admission_queued` within the admission timeout with the same body/key, honor full `Retry-After`, and display `queued for admission; retrying in 2 s` while waiting.
 - 0.27.0: workspace disk caps report the admitted and acknowledged size. Completed disk grows refresh the disk grant; resize results retain the original request.
 
 
-- `shard orchestrator` (0.27.0+, SDK 0.29.0): your orchestrator agent from a terminal. `shard orchestrator say <words>`
+- `shard orchestrator` (0.28.0+, SDK 0.29.0): your orchestrator agent from a terminal. `shard orchestrator say <words>`
   sends your exact words (`--task`, `--report`, `--needs-you`, `--input`, `--conversation` point at a row) and prints
   the input id and its place in line; every input is handled in parallel by its own thread. `--wait` follows it until
   it is done, merged, failed or waiting and prints its curated result: the answer's headline and facts with their
@@ -118,13 +155,13 @@
   <input-id>` sends a failed one again and `shard orchestrator dismiss <input-id>` takes one out of the list. Signed in
   they reach your orchestrator; with `SHARDFLUX_API_KEY`, the orchestrator of the person who created the key. `--json`
   prints `{input}` / `{inputs, cursor}`.
-- `shard needs-you` (0.27.0+, SDK 0.29.0) lists your orchestrator's questions (`oq_…`, answered with `--text`) and what
+- `shard needs-you` (0.28.0+, SDK 0.29.0) lists your orchestrator's questions (`oq_…`, answered with `--text`) and what
   it asked your computer while it was offline (`dev_…`, "Waiting for your computer: list ~/code"; `shard needs-you
   answer dev_… cancel` drops it).
 - Deprecated (0.27.0): `shard route` (POST /v1/router) and `shard ask` (POST /v1/questions); use the orchestrator
   instead (`shard orchestrator say`). Each prints a one-line notice on stderr.
 
-- `shard agents models` (0.27.0+): the models each active account can use, as Claude and ChatGPT list them for that
+- `shard agents models` (0.28.0+): the models each active account can use, as Claude and ChatGPT list them for that
   account (asked server side the way Claude Code and Codex fill their pickers; never starts a computer): effort levels
   with the default starred, the default model, and unavailable models with the provider's reason. `--account <ref>`,
   `--provider`, `--all`, `--refresh`; `--json` prints the API answer. `--model` on `shard agents new` (and `shard ./`)
@@ -140,7 +177,7 @@
 - `shard transcribe <file>` (0.25.0+, SDK 0.28.0) prints what a recording says (WebM/Opus or PCM WAV from the file;
   raw PCM with `--format pcm16 --sample-rate`); `--words` adds each word's start and end, `--json` prints the
   transcript. Where cloud transcription is not on for the organization it says so in one line
-  (`cloud_transcription_off`) and exits 1 (0.27.0+, SDK 0.29.0).
+  (`cloud_transcription_off`) and exits 1 (0.28.0+, SDK 0.29.0).
 - Faster conversation starts (0.24.1): the project's dependency fingerprint is read from Git's own file list instead of walking the whole folder, so ignored and untracked trees beside the project (agent worktrees, build output) no longer hold a start on **Getting your project…**. A folder with 1.2 million such files took 32 s per start; it now takes 0.3 s, with the same fingerprint.
 - A folder without Git that `shard` makes a repository of (a first chat, `shard projects link`) starts with its files as
   the first commit (0.25.0+; `.gitignore` respected, large media stay untracked), so a conversation starts from the

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.
@@ -32,6 +34,12 @@ an explicit selection keeps the default credentials and target status. An approv
 
 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.
 
+## Agent credentials (0.28.2+)
+
+Answer a credential question with `shard needs-you answer acred_ID --credential --ask --scope project`. The value goes to the write-only answer field and the asking agent receives an availability message.
+
+`shard secrets create NAME --scope agents --org ORG --ask` adds a credential for all your agents; use `--scope project --project PROJECT` or `--scope conversation --conversation CONVERSATION` for a local override. Import, list, get, update, rotate, versions, access-log and delete accept the same scope. Values use the secure page, stdin, or `--from-file` and never command arguments.
+
 ## Support and bug reports
 
 [Report a bug](https://github.com/shardfluxdev/community/issues/new?template=bug_report.yml) or
@@ -127,8 +135,8 @@ 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+).
@@ -305,6 +313,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.
 
@@ -735,8 +748,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). |
-| `orchestrator say [--wait [--timeout D]] [--task ID\|--report ID\|--needs-you ID\|--input ID\|--conversation ID] <words...>`, `orchestrator list [--all]`, `orchestrator retry\|dismiss <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-0270). |
+| `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+). |
@@ -1626,6 +1641,8 @@ hour), and `--json` prints the API's answer. Pass an id to `shard agents new --m
 
 ## Conversations
 
+When an orchestrator starts work through a device project link (0.28.2+), the new conversation carries its requesting thread through to the API. `shard agents list --json` retains the orchestrator conversation and known input IDs.
+
 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.
 
 Watch an agent work: `shard conversations watch <id>` shows the conversation's terminal live, read-only. It starts
@@ -1671,6 +1688,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
@@ -1684,6 +1719,8 @@ shard c delete conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --yes
 
 ### 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
@@ -1691,25 +1728,33 @@ 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, step 7,300 of 10,000
-#   - Loss 1.84, down from 2.31 at step 5,000
-#   - About 2 h 10 min left at this pace
-#   - Last checkpoint at step 7,000
+# 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, step 7,300 of 10,000
+# in_7wcx227ovjpei4u6i47llu7w4i	done	Lets check on our language model training progress	Training is 73% done, on pace to finish at 16:40
 ```
 
-`--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 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`). Signed in, they reach your orchestrator (`--org <id|slug>` when you belong
+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}`).
 
@@ -1870,7 +1915,7 @@ shard board --follow                               # each change as it happens,
 changes the words (`--text`, and the task's master hears it), the title (`--title`), the bucket (`--now`, `--next`,
 `--later`) and the order (`--first`, `--after`), keeps an agent's suggestion as your own (`--keep`) or clears the task
 (`--clear`; `--no-clear` brings it back). `shard task steer <id> <words...>` sends steering words to the task's master,
-`shard task rm <id>` deletes the task, and `shard task clear-done` clears every finished one. `shard task show <id>`
+`shard task rm <id>` deletes the task, every nested follow-up, and their owned conversation trees and computers; masters shared by other tasks stay. `shard task clear-done` clears every finished one. `shard task show <id>`
 prints the task, its plan and each report: milestone, outcome and evidence (`tests 12/12 (pnpm test)`).
 `shard task land <id>` lands a finished task: its result (the branch `shard/<task id>`, where its master merged its
 workers' branches) goes into the project's default branch and into your folder on this computer the way finished
@@ -1977,6 +2022,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
@@ -2021,3 +2092,11 @@ 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.
+
+### Question explanations (0.28.2+)
+
+Needs-you output prints each question and its optional `option_details` in full, including what each choice does and what follows it. The first suggested answer is the agent’s recommendation. Secret values go through the project’s secure setup, never a question or its ordinary answer.
+
+Conversation creation (0.28.2+) includes the optional launching conversation only when `/v1/meta` advertises `capabilities.conversation_origin: true`. Older APIs receive the existing create body; no rejected create is replayed with different fields.

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/agent-git-commands.d.ts

@@ -6,5 +6,4 @@ export declare function rememberGitAgent(ctx: Ctx, ws: Workspace, folder: string
 export declare const AGENT_GIT_HANDLERS: Record<string, Handler>;
 /** No Git or network work when no records are due. Active passes are bounded and never infer deletion from an error. */
 export declare function housekeeping(ctx: HousekeepingCtx, now?: () => number, budgetMs?: number): Promise<void>;
-/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
-export declare function startupHousekeeping(ctx: Pick<Ctx, 'io' | 'store' | 'signal'>): Promise<void>;
+export { startupHousekeeping } from './startup-housekeeping.js';

package/dist/agent-git-commands.js

@@ -1,9 +1,8 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { Shardflux, ShardfluxApiError } from '@shardflux/sdk';
+import { ShardfluxApiError } from '@shardflux/sdk';
 import { out, resolveWorkspace, str } from "./commands.js";
 import { AgentStateStore } from "./agent-state.js";
-import { resolveApiUrl } from "./args.js";
 import { AgentGit, agentName } from "./agent-git.js";
 import { shardRemote } from "./git-remote.js";
 import { projectIdentity } from "./project-identity.js";
@@ -274,22 +273,4 @@ export async function housekeeping(ctx, now = Date.now, budgetMs = 1500) {
         clearTimeout(timer);
     }
 }
-/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
-export async function startupHousekeeping(ctx) {
-    try {
-        const state = new AgentStateStore(ctx.store.dir).read();
-        if (!state.git_repositories || !Object.keys(state.git_repositories).length)
-            return;
-        const apiUrl = resolveApiUrl(undefined, ctx.io.env.SHARDFLUX_API_URL ?? ctx.io.env.SHARDFLUX_BASE_URL);
-        let cloud;
-        await housekeeping({ ...ctx, apiUrl, cloud: () => {
-                const key = ctx.io.env.SHARDFLUX_API_KEY?.trim() || ctx.store.profile(apiUrl).api_key?.token;
-                if (!key)
-                    throw new UsageError('saved agents need a project key for housekeeping; run shard setup');
-                return cloud ??= new Shardflux({ apiKey: key, baseUrl: apiUrl, versionCheck: false });
-            } });
-    }
-    catch (error) {
-        ctx.io.stderr.write(`shard housekeeping: ${error instanceof Error ? error.message : String(error)}\n`);
-    }
-}
+export { startupHousekeeping } from "./startup-housekeeping.js";

package/dist/agent-setup.d.ts

@@ -1,10 +1,10 @@
+import type { Ctx } from './commands.js';
 /**
  * Set in a coding agent's shell: Claude Code (CLAUDECODE), Codex (CODEX_SANDBOX, CODEX_THREAD_ID), Cursor's agent
  * (CURSOR_AGENT) and Gemini CLI (GEMINI_CLI). Such a shell may have a terminal (Cursor and Codex can run commands in a
  * PTY), but nobody types into it: a full-screen view or a prompt there waits forever.
  */
-export declare const AGENT_SHELL_VARIABLES: readonly ["CLAUDECODE", "CODEX_SANDBOX", "CODEX_THREAD_ID", "CURSOR_AGENT", "GEMINI_CLI"];
-export declare function codingAgentShell(env: Record<string, string | undefined>): boolean;
+export { AGENT_SHELL_VARIABLES, codingAgentShell } from './agent-shell.js';
 /**
  * How the agent runs the setup (0.20.1+): it does the work, the person only decides. Onboarding testers (2026-10-12)
  * found agents handing them commands, links and codes, writing paragraphs and asking open questions.
@@ -46,4 +46,6 @@ export interface GuideState {
     apiKey: boolean;
 }
 export declare function setupGuide(state: GuideState): SetupGuide;
+/** 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 function setupGuideText(g: SetupGuide): string;

package/dist/agent-setup.js

@@ -18,10 +18,7 @@ import { legalFields } from "./legal.js";
  * (CURSOR_AGENT) and Gemini CLI (GEMINI_CLI). Such a shell may have a terminal (Cursor and Codex can run commands in a
  * PTY), but nobody types into it: a full-screen view or a prompt there waits forever.
  */
-export const AGENT_SHELL_VARIABLES = ['CLAUDECODE', 'CODEX_SANDBOX', 'CODEX_THREAD_ID', 'CURSOR_AGENT', 'GEMINI_CLI'];
-export function codingAgentShell(env) {
-    return AGENT_SHELL_VARIABLES.some((name) => (env[name]?.trim() ?? '') !== '');
-}
+export { AGENT_SHELL_VARIABLES, codingAgentShell } from "./agent-shell.js";
 /**
  * How the agent runs the setup (0.20.1+): it does the work, the person only decides. Onboarding testers (2026-10-12)
  * found agents handing them commands, links and codes, writing paragraphs and asking open questions.
@@ -137,6 +134,11 @@ function stepText(n, s) {
         ...(s.note ? [`     ${wrap(s.note, '     ', 96)}`] : []),
     ].join('\n');
 }
+/** 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()) });
+}
 export function setupGuideText(g) {
     return [
         'Set up Shardflux for your user. How:',

package/dist/agent-shell.d.ts

@@ -0,0 +1,2 @@
+export declare const AGENT_SHELL_VARIABLES: readonly ["CLAUDECODE", "CODEX_SANDBOX", "CODEX_THREAD_ID", "CURSOR_AGENT", "GEMINI_CLI"];
+export declare function codingAgentShell(env: Record<string, string | undefined>): boolean;

package/dist/agent-shell.js

@@ -0,0 +1,5 @@
+// Identify an agent shell before loading onboarding or command handlers.
+export const AGENT_SHELL_VARIABLES = ['CLAUDECODE', 'CODEX_SANDBOX', 'CODEX_THREAD_ID', 'CURSOR_AGENT', 'GEMINI_CLI'];
+export function codingAgentShell(env) {
+    return AGENT_SHELL_VARIABLES.some((name) => (env[name]?.trim() ?? '') !== '');
+}

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.28.0";
+export declare const CLI_VERSION = "0.28.2";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -15,7 +15,7 @@ import { BOARD_COMMANDS } from "./board-args.js";
 import { ORCHESTRATOR_COMMANDS } from "./orchestrator-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.28.0';
+export const CLI_VERSION = '0.28.2';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -127,6 +127,9 @@ const LIFETIME_FILTER = {
 };
 const SECRET_REF = { name: 'id|name', required: true };
 const SECRET_SCOPE = {
+    scope: { type: 'string', value: '<agents|project|conversation>', description: 'Agent credential scope: all your agents, this project, or one thread. Omit for workspace-bound secrets.' },
+    project: { type: 'string', value: '<project-id>', description: 'Project for a local agent credential (default: the key’s project).' },
+    conversation: { type: 'string', value: '<conversation-id>', description: 'Thread for --scope conversation.' },
     org: { type: 'string', value: '<organization-id>', description: 'Organization-wide secrets of this organization (owners/admins; project API keys get 403). Default: the API key’s project.' },
 };
 const SECRET_VALUE = {
@@ -993,6 +996,7 @@ const KEY_COMMANDS = [
         summary: 'Import named items from your vault as encrypted project secrets',
         positionals: [{ name: 'name', required: true, variadic: true }],
         options: {
+            ...SECRET_SCOPE,
             from: { type: 'string', value: '<hsec|1password|bitwarden|keychain>', description: 'Vault to read; values go straight into the encrypted secrets request.' },
             as: { type: 'string', value: '<secret-name>', description: 'Secret name for a single imported item.' },
             keychain: { type: 'string', value: '<path>', description: 'Read from this Keychain (keychain source only).' },

package/dist/board-args.js

@@ -123,6 +123,12 @@ export const BOARD_COMMANDS = [
         summary: 'Answer something that waits on you (0.25.0+)',
         positionals: [{ name: 'id', required: true }, { name: 'decision' }],
         options: {
+            credential: { type: 'boolean', description: 'Provide an environment credential through the secure value input; never through --text.' },
+            scope: { type: 'string', value: '<agents|project|conversation>', description: 'Credential storage scope (default: what the request suggests).' },
+            org: { type: 'string', value: '<organization-id>', description: 'The organization for a signed-in credential answer.' },
+            ask: { type: 'boolean', description: 'Open the secure page for the credential value.' },
+            'from-file': { type: 'string', value: '<file>', description: 'Read the credential value from this file; never from an argument.' },
+            timeout: { type: 'string', value: '<duration>', description: 'How long the secure page waits (default 10m).' },
             everywhere: { type: 'boolean', description: 'With always: the rule covers every project.' },
             text: { type: 'string', value: '<answer>', description: 'Your answer to an agent’s question.' },
             pick: { type: 'string', multiple: true, value: '<option|question=option>', description: 'The option you pick for an agent’s question in a permission request (repeatable for a multi-select question; "<question>=<option>" when it asks several).' },
@@ -136,6 +142,7 @@ export const BOARD_COMMANDS = [
             '  ask_…     --text <answer>: the task’s master gets it',
             '  oq_…      --text <answer>: the orchestrator thread that asked gets it (0.27.0+)',
             '  cred_…    deny (the value goes through the credential request, sealed for its computer)',
+            '  acred_…   --credential --ask: provide an environment value securely, or deny to decline it',
             '  land_…    land (as shard task land: the result into your folder and the default branch), keep (the',
             '            branch stays) or discard',
             '  prune_…   --keep <task-id> for each task to keep, keep for all of them, or discard to clear them',

package/dist/board-commands.d.ts

@@ -44,7 +44,7 @@ export declare function feedJson(u: BoardUpdate): Record<string, unknown>;
 /** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. Every
  *  title, step and outcome prints whole (0.27.0+), however long the agent wrote it; the terminal wraps it. */
 export declare function taskDetailText(d: TaskDetail): string;
-/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, land_, prune_, dev_); undefined for another id. */
+/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, acred_, land_, prune_, dev_); undefined for another id. */
 export declare function itemKind(id: string): NeedsYouItem['kind'] | undefined;
 export interface AnswerInput {
     word?: string | undefined;