@shardflux/cli 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,13 +1,55 @@
 # Changelog
 
-## 0.9.0 — 2026-10-04 (not yet published)
-
-- `shard ws hint <workspace>` explicitly stages a parked workspace ahead of a VM tool call, without waiting for restore or resuming a suspended workspace.
-
 Every command and option the README shows is available from the version named here. Breaking changes ship in minor
 releases and are marked **Breaking**.
 
-## 0.9.0 (not yet published)
+## 0.11.0 (not yet published)
+
+- Add opt-in persistent workspace idle deletion retention, workspace/project setters and projected deletion times.
+
+- Accelerate reverse tunnels with a bounded, acknowledged binary WebSocket stream, 64 KiB frames and batched credits. Select `auto`, `pty` or `exec` transport; reconnect preserves byte offsets. Opt-in binary PTY output accepts larger blocks for file transfers.
+
+- Add opt-in resize controls to grow named resources only and return the held server answer without polling a pending operation.
+
+- `shard ws computer stream` reuses a private cached link by API/workspace/credential and kind with more than 60 seconds left. `--fresh` remints; `--stop` clears cached links.
+- `SHARDFLUX_BASE_URL` aliases `SHARDFLUX_API_URL` (the latter wins). Canceled exec results exit 130; timeout, normal exit and signal statuses follow the shared POSIX status helper.
+- Shared SDK proxy support, missing-file classification and computer batch screenshot deduplication.
+- Embed live desktop viewers and port previews in a web app with an explicit HTTPS origin allowlist and partitioned browser sessions.
+
+- Add foreground `shard ws tunnel <key> --remote <port> --to <host:port> [--bind 127.0.0.1|0.0.0.0]`. Ctrl-C closes the reverse tunnel and its guest process.
+
+- Add `shard ws upgrade <key> [--at next-resume]` with operation waiting and JSON output.
+
+## 0.10.0 — 2026-10-04
+
+Needs `@shardflux/sdk` 0.15.0 or later.
+
+### One command per workspace
+
+Additive (contracts §46), with `@shardflux/sdk` 0.15.0.
+
+- `shard exec <key> --template <slug> -- <cmd>`: `--template` on `ws exec` and `ws exec-start` opens the key first,
+  so the workspace is created on first use (stderr: `created workspace <key> (template <slug>)`) and resumed if it is
+  suspended. Without `--template` the key must have a workspace, as before.
+- `shard exec` is a shortcut for `shard workspaces exec`.
+- `--template default` opens the platform default template (`python-node-browser`).
+
+### Computer use
+
+- `shard ws computer status|screenshot|act|start|stop|stream <key>`: the workspace desktop (contracts §45).
+  `screenshot --out F` writes the image; `act <json|->` runs a batch of computer toolset actions, prints one line per
+  action and exits 1 when one failed (`--screenshot F` saves the screen after it; `--json` prints the full result);
+  `stream [--interactive] [--ttl D]` prints a private link to watch it, `stream --stop` ends every view.
+- One command per mouse and keyboard action: `shard ws computer click [x y] [--button] [--count 2|3] [--mods]`,
+  `type <text|->`, `key <keys> [--repeat]`, `scroll <dir> [x y] [--amount]`, `move`, `drag`, `mouse-down`, `mouse-up`,
+  `hold-key`, `zoom <x0 y0 x1 y1> [--out F]`, `cursor`, `wait`. Every input command and `act` take `--screenshot F`,
+  `--settle MS` and `--format jpeg --quality N`; `screenshot` takes `--quality`.
+- `shard ws computer enable|disable|inherit <key>` and `shard ws open --computer-use on|off|inherit`: the workspace's
+  computer use switch; `shard templates computer-use <slug> on|off`: the switch for every workspace of a template.
+
+## 0.9.0 — 2026-10-04
+
+- `shard ws hint <workspace>` explicitly stages a parked workspace ahead of a VM tool call, without waiting for restore or resuming a suspended workspace.
 
 Needs `@shardflux/sdk` 0.14.0 or later.
 
@@ -88,7 +130,7 @@ workspace.
   API decides (with elastic-by-default enabled for the organization a new workspace is elastic; otherwise
   `requires_elastic`). With `--allocation-mode fixed` it stays a usage error.
 
-## 0.8.1 (not yet published)
+## 0.8.1 — 2026-10-03
 
 Needs `@shardflux/sdk` 0.13.1 or later.
 
@@ -106,7 +148,7 @@ When the machine a workspace runs on fails, the workspace is suspended, and the
   `--timing` prints the SDK's `restored checkpoint <id> (host_lost; state as of <time>)`.
 - `hostLostNotice()` is exported next to `coldBootNotice()`.
 
-## 0.8.0
+## 0.8.0 — 2026-10-02
 
 Needs `@shardflux/sdk` 0.13.0 or later.
 
@@ -179,7 +221,7 @@ newest published version.
 - **Breaking:** `--json` output no longer carries `update_policy`: the API removed the update policy (it was always
   `pinned`).
 
-## 0.6.2
+## 0.6.2 — 2026-09-30
 
 Needs `@shardflux/sdk` 0.11.1 or later.
 
@@ -214,14 +256,12 @@ New organizations can start on a trial: 60 days at Developer limits, no card. Th
 - An interrupted file-first `ws exec` says `(an execution runs to completion)`; `mode_not_available` drops "yet";
   `--open` no longer says "best effort"; `templates init --help` no longer names an internal document.
 
-## 0.7.0 (release candidate)
+## 0.7.0 — 2026-09-30
 
 Completed exec output streams are drained before releasing their HTTP connections, with a bounded cleanup if a peer does not close.
 
 Uses SDK 0.12.0 and its pooled transport. Adds --labels/--idle-policy to open, --labels to list, ws labels, ws idle, ws exec-start --stdin-open and ws exec-input --offset. Protocol-error JSON includes source. Resume recovers failed workspaces; completed deletion permits key reuse.
 
-Requires the QM integration backend release for labels, failed recovery, key reuse and pipe stdin. No production deployment has occurred from this branch.
-
 ### Instant suspend: durable storage
 
 - `shard ws suspend --wait` still returns when the suspend succeeds (sealed on its host); a finished suspend or fork
@@ -237,7 +277,7 @@ Requires the QM integration backend release for labels, failed recovery, key reu
 - A suspend-when-idle canceled `workspace_active` says the workspace was in use and keeps running.
 - The `ws suspend` summary no longer says "durable checkpoint".
 
-## 0.6.1
+## 0.6.1 — 2026-09-30
 
 Needs `@shardflux/sdk` 0.11.0 or later.
 
@@ -249,7 +289,7 @@ flush grace after its last work), and a running command, an attached stream or a
 it ends. The human output says `is suspended as soon as it is idle`, and `ws get` shows `as soon as idle`. Out of
 range is still exit 2 before any request: `--when-idle must be between 0s and 1h`.
 
-## 0.6.0
+## 0.6.0 — 2026-09-29
 
 Needs `@shardflux/sdk` 0.11.0 or later.
 
@@ -269,17 +309,17 @@ suspend; every process was restarted.
   processes restarted (runtime_changed)` (the SDK's `formatTiming()`).
 - `coldBootNotice()` is exported next to `TimingRecorder`, which records the call as `coldBoot`.
 
-## 0.5.3
+## 0.5.3 — 2026-09-29
 
 Fix: `shard --version`, the User-Agent and the update check reports 0.5.3. 0.5.2 was published reporting 0.5.1, its previous version; the build now
 fails when `CLI_VERSION` differs from package.json.
 
-## 0.5.2
+## 0.5.2 — 2026-09-29
 
 Public support: package metadata and the README now link to the [shared bug tracker](https://github.com/shardfluxdev/community/issues),
 feature requests, and private support/security reporting.
 
-## 0.5.1
+## 0.5.1 — 2026-09-29
 
 ### A command that could not start is never a silent exit
 
@@ -329,7 +369,7 @@ cell had ended the session `failed_to_start` (`working directory "app" is not a
   `--cancel-when-idle` cancels it. `--json` prints `{workspace, operation, suspend_request}`.
 - `shard workspaces get` shows a pending request (`suspend when idle  after N s idle, not before ...`).
 
-## 0.5.0
+## 0.5.0 — 2026-09-29
 
 Needs `@shardflux/sdk` 0.9.0 or later.
 
@@ -502,13 +542,12 @@ unchanged and still stores nothing.
   edit that does not match, a mode the workspace lacks, a reused execution id), and `shard feedback` itself.
 - The positional usage of `shard feedback` is shown as `<message...>`; `--agent-label` also names the reporting agent.
 
-
-## 0.4.1 (2026-09-28)
+## 0.4.1 — 2026-09-28
 
 Needs `@shardflux/sdk` 0.8.0 or later. No command changes: the SDK's 0.8.0 is a types-only release (its provider tool
 exports type-check without casts), and the CLI moves to it so `shardflux` installs one copy of the SDK.
 
-## 0.4.0 (2026-09-28)
+## 0.4.0 — 2026-09-28
 
 Needs `@shardflux/sdk` 0.7.0 or later. New dependency: `yaml` (template.yaml).
 
@@ -536,7 +575,7 @@ Needs `@shardflux/sdk` 0.7.0 or later. New dependency: `yaml` (template.yaml).
 - `buildText` names a recipe v2 build's recipe sha256, its build network and denied hosts, and points at
   `shard templates builds get`.
 
-## 0.3.1 (2026-09-28)
+## 0.3.1 — 2026-09-28
 
 Needs `@shardflux/sdk` 0.6.2 or later.
 
@@ -553,7 +592,7 @@ stays suspended).
 - `shard workspaces get` names the origin of a template version test instance (`template <id> version <n>`, contracts
   §24.6) instead of reading it as a draft state.
 
-## 0.3.0 (2026-09-28)
+## 0.3.0 — 2026-09-28
 
 Needs `@shardflux/sdk` 0.6.0 or later.
 
@@ -582,13 +621,13 @@ Needs `@shardflux/sdk` 0.6.0 or later.
 - Ctrl-C ends a held open at once (exit 130); the open continues server side, and opening the key again keeps
   waiting.
 
-## 0.2.0 (2026-09-28)
+## 0.2.0 — 2026-09-28
 
 Secrets (`secrets ...`, `workspaces open --secret`, `workspaces secrets`), session workspaces (`--lifetime session`,
 `workspaces close`), layered workspaces (`workspaces reset|save-as-template|changes`), templates
 (`templates list|files|diff|draft ...`), and waking suspended workspaces on use (`--no-wake`, `--wake-timeout`).
 
-## 0.1.0 (2026-09-26)
+## 0.1.0 — 2026-09-26
 
 First release: `login`, `whoami`, `usage`, `workspaces open|list|get|exec|suspend|resume|fork|delete|sessions`,
 `files read|write|ls`, `operations list|get|wait`, `--json`, and documented exit codes.

package/README.md

@@ -1,6 +1,6 @@
 # @shardflux/cli: `shard`
 
-The command line for [Shardflux](https://shardflux.dev): cloud computers for AI agents. Open a
+The command line for [Shardflux](https://shardflux.dev): serverless VMs for AI agents. Open a
 persistent workspace by key, run commands in it, move files in and out, and suspend, resume, fork
 or delete it. From 0.5.0 it also does everything the web app does: create an account, sign in
 (with two-factor authentication), set up an organization, project and API key, manage members,
@@ -24,6 +24,20 @@ For usage, account, billing, or private support, email [shardflux@heliosone.fi](
 Report vulnerabilities through [private security reporting](https://github.com/shardfluxdev/community/security/advisories/new).
 See the [support guide](https://github.com/shardfluxdev/community/blob/main/SUPPORT.md) for all reporting options.
 
+## Reverse tunnels (0.11.0+)
+
+Run a foreground TCP tunnel from a workspace to a service on this machine:
+
+```sh
+shard ws tunnel customer-42/main --remote 8081 --to localhost:8081
+```
+
+Commands in the workspace can then call `http://127.0.0.1:8081`. The target is dialed on the machine running
+`shard`. Ctrl-C closes the sockets and guest process. `--bind 0.0.0.0` selects all guest interfaces; loopback is the
+default. An open tunnel keeps the workspace awake, and persistent workspaces preserve it across explicit suspend/resume.
+
+The tunnel selects a streaming transport automatically when `pty` permission is granted. Choose `transport: 'pty'` or `transport: 'exec'` in the SDK, or `--transport pty|exec` in the CLI, to select it explicitly. The handle reports `transport`.
+
 ## Install
 
 ```sh
@@ -42,8 +56,7 @@ password. With the Codex CLI signed in with ChatGPT on this machine, your email
 
 ```sh
 shard signup                                  # or: shard signup --email you@example.com
-shard workspaces open acme/demo --template python-node-browser
-shard ws exec acme/demo -- python3 -c 'print(40 + 2)'
+shard exec acme/demo --template default -- python3 -c 'print(40 + 2)'   # created on first use
 shard files write acme/demo /home/user/notes.txt --from notes.txt
 shard files read acme/demo /home/user/notes.txt
 shard ws suspend acme/demo --wait
@@ -116,8 +129,9 @@ terminal, `--json` on every command, secrets only on standard input, and documen
 2. **Verify the email** (an `--email` signup, to start the trial): `shard verify --json` emails a
    6-digit code; ask the person for it, then `shard verify <code>`. Nothing is signed out.
 3. **Set up again any time:** `shard setup --json` is idempotent.
-4. **Work:** `shard ws open <key> --template <slug> --json`, `shard ws exec <key> -- <cmd>`,
-   `shard files ...` use the saved key.
+4. **Work:** `shard exec <key> --template default -- <cmd>` creates the workspace on first use and runs the command
+   (0.10.0+); later commands reuse it. `shard ws open <key> --template <slug> --json`, `shard files ...` use the saved
+   key too.
 5. **A paid plan:** `shard billing plans`, then `shard billing upgrade <plan> --json` prints the Stripe
    Checkout URL; give it to the person, then `shard billing upgrade <plan> --wait` (or
    `shard billing status`) until it is active. The API activates a plan only when Stripe confirms the
@@ -385,8 +399,8 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `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+). |
 | `workspaces get <id\|key>` | One workspace (deleted ones included), with the startup of its template's start commands and services (0.4.0+): a failed step shows its exit code, reason and output tail. Its mode, and a file-first workspace's tree revision (0.5.0+). Its memory (0.8.0+): `fixed 4096 MiB`, or `elastic: promised …, held …, plugged +… MiB`. The template version whose [immutable paths](#immutable-paths-080) it has mounted (0.8.0+): `immutable paths  v3 (mounted read-only)`. |
 | `workspaces inputs <id\|key>` | The workspace's text inputs (0.4.0+). |
-| `workspaces exec <id\|key> [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] [-v] [--execution-id ID] [--output-limit N] [--resource-hint auto\|light\|heavy] [--burst [--burst-vcpus N] [--burst-memory MIB]] -- <cmd> [args...]` | Runs argv with no shell. Output is streamed (in the start request itself, 0.8.0+) and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. `-v` (0.5.0+) then prints the session id and exit status on stderr, and the memory grow the command waited for on an elastic workspace (0.8.0+; `--json`: `memory_grow`). `--cwd` is an absolute path (default `/home/user`); a relative one is refused (`invalid_cwd`, exit 2). A command that could not start (a `--cwd` that is not a directory, a program not on `PATH`) exits 6 with the workspace's reason and a hint (0.5.1+; before, it exited 1 with no output). On a file-first workspace (0.5.0+) the command runs as an execution instead: see [File-first workspaces](#file-first-workspaces). `--burst` (0.8.0+): [burst execution](#burst-execution-080). `--resource-hint` (0.9.0+): [elastic memory](#elastic-memory-080). |
-| `workspaces exec-start <id\|key> [--session-id ID] [--cwd D] [--timeout T] [--stdin-open] [--resource-hint auto\|light\|heavy] -- <cmd> [args...]`, `workspaces exec-read <id\|key> <session-id> [--follow]`, `workspaces exec-cancel <id\|key> <session-id> [--grace D]` | Background commands (0.8.0+): start a command and return at once, read its output and state (`--follow` streams it to its exit and exits with its code; while it runs `exec-read` exits 5), stop it. See [Background commands](#background-commands-080). |
+| `workspaces exec <id\|key> [--template S] [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] [-v] [--execution-id ID] [--output-limit N] [--resource-hint auto\|light\|heavy] [--burst [--burst-vcpus N] [--burst-memory MIB]] -- <cmd> [args...]` | Runs argv with no shell. `shard exec` is the same command (0.10.0+). `--template <slug>` (0.10.0+) opens the key first: the workspace is created on first use (stderr says so) and resumed if suspended; without it the key must have a workspace. Output is streamed (in the start request itself, 0.8.0+) and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. `-v` (0.5.0+) then prints the session id and exit status on stderr, and the memory grow the command waited for on an elastic workspace (0.8.0+; `--json`: `memory_grow`). `--cwd` is an absolute path (default `/home/user`); a relative one is refused (`invalid_cwd`, exit 2). A command that could not start (a `--cwd` that is not a directory, a program not on `PATH`) exits 6 with the workspace's reason and a hint (0.5.1+; before, it exited 1 with no output). On a file-first workspace (0.5.0+) the command runs as an execution instead: see [File-first workspaces](#file-first-workspaces). `--burst` (0.8.0+): [burst execution](#burst-execution-080). `--resource-hint` (0.9.0+): [elastic memory](#elastic-memory-080). |
+| `workspaces exec-start <id\|key> [--template S] [--session-id ID] [--cwd D] [--timeout T] [--stdin-open] [--resource-hint auto\|light\|heavy] -- <cmd> [args...]`, `workspaces exec-read <id\|key> <session-id> [--follow]`, `workspaces exec-cancel <id\|key> <session-id> [--grace D]` | Background commands (0.8.0+): start a command and return at once, read its output and state (`--follow` streams it to its exit and exits with its code; while it runs `exec-read` exits 5), stop it. See [Background commands](#background-commands-080). |
 | `executions get <id\|key> <execution-id> [--wait D]` | The result of a file-first workspace's execution (0.5.0+): its output, then what ran. Exits with the command's code, 6 if the execution failed or was lost, 5 while it still runs. |
 | `files read <id\|key> <path> [--out F]` | Raw bytes to stdout, or to a local file. |
 | `files write <id\|key> <path> [--from F\|-] [--append] [--no-parents] [--if-revision N]` | Atomic write. The default source is stdin. `--if-revision` (0.5.0+): file-first workspaces only, see [Tree revisions](#tree-revisions). |
@@ -408,6 +422,7 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `workspaces secrets <id\|key> [--set NAME]... [--clear]` | Show the secret names bound to the workspace and their status, or replace them. |
 | `workspaces port expose <id\|key> <port>`, `workspaces port ls <id\|key>`, `workspaces port close <id\|key> <port>` | Serve a port of the workspace at its own private HTTPS URL, list the exposed ports, close one (0.9.0+; see [Inbound ports](#inbound-ports-090)). |
 | `workspaces port token <id\|key> <port> [--ttl D]`, `workspaces port link <id\|key> <port> [--ttl D] [--path P]`, `workspaces port callback <id\|key> <port> [--revoke]` | A port token (printed alone), a link that opens the port in a browser, the port's callback URL for webhooks and OAuth redirects (0.9.0+). |
+| `workspaces computer status\|screenshot\|act\|start\|stop\|stream <id\|key>`, `workspaces computer click\|type\|key\|scroll\|move\|drag\|mouse-down\|mouse-up\|hold-key\|zoom\|cursor\|wait <id\|key> ...`, `workspaces computer enable\|disable\|inherit <id\|key>`, `templates computer-use <slug> on\|off` | The workspace desktop for computer use: its state, a screenshot (`--out F`), one command per mouse and keyboard action, a batch of actions (a JSON array), a private link to watch or use it (`stream [--interactive] [--ttl D]`, `--stop`), and the switch for a workspace or every workspace of a template (0.10.0+; see [Computer use](#computer-use-0100)). |
 | `secrets create <NAME> [--from-file F] [--description T] [--tool T]... [--allow-workspace ID]... [--org ID [--allow-project ID]... [--all-projects]]` | Create a secret. The value comes from standard input or `--from-file`, never from an argument. |
 | `secrets list [--org ID] [--include-deleted] [--all]`, `secrets get <id\|NAME>` | Secret metadata. Values are never shown. |
 | `secrets update <id\|NAME> [--description T] [--tool T]... [--allow-workspace ID]... [--any-workspace] [--allow-project ID]... [--all-projects] [--clear-projects]` | Change the description or usage permissions. |
@@ -751,6 +766,46 @@ shard ws port close acme/demo 3000
   again replaces the URL; `--revoke` removes it.
 - `close` stops the port's tokens, links and callback URL at once.
 
+## Computer use (0.10.0+)
+
+A desktop in the workspace for agents that operate GUI software: a screen, a mouse and a keyboard. Switch it on for a
+workspace (or every workspace of your template); the platform starts the desktop on the first computer command.
+
+```sh
+shard ws open acme/demo --template python-node-browser --computer-use on
+shard ws exec-start acme/demo -- chromium https://example.com     # opens on the desktop
+shard ws computer screenshot acme/demo --out desktop.png
+shard ws computer click acme/demo 640 400
+shard ws computer type acme/demo "hello" --screenshot after.png
+shard ws computer key acme/demo ctrl+s
+open "$(shard ws computer stream acme/demo)"                      # watch it live
+```
+
+| Command | Action |
+| --- | --- |
+| `click <ws> [x y] [--button left\|right\|middle] [--count 2\|3] [--mods keys]` | A click, double or triple click at a point or at the pointer |
+| `type <ws> <text\|->` | Types text (Unicode; `-` reads standard input) |
+| `key <ws> <keys> [--repeat n]` | Keys and combinations: `Return`, `ctrl+s`, `alt+Tab`, several separated by spaces |
+| `scroll <ws> up\|down\|left\|right [x y] [--amount n] [--mods keys]` | Wheel clicks (default 3) |
+| `move <ws> <x> <y>`, `drag <ws> <x1> <y1> <x2> <y2>` | Moves the pointer; drags with the left button |
+| `mouse-down <ws>`, `mouse-up <ws>`, `hold-key <ws> <keys> <seconds>` | Holds the left button or keys |
+| `zoom <ws> <x0> <y0> <x1> <y1> [--out F]` | Saves an enlarged view of a region |
+| `cursor <ws>`, `wait <ws> <seconds>` | Prints the pointer position; waits |
+| `act <ws> <json\|->` | Any of these in one batch: a JSON array of actions |
+
+Every input command takes `--screenshot F` (a screenshot after it, written to `F`), `--settle MS` (the wait before
+that screenshot, default 250) and `--format jpeg --quality N` for smaller images; `screenshot` and `zoom` take
+`--format` and `--quality` too.
+
+- The actions are Claude's computer toolset members with their parameters (`screenshot`, `zoom`, `left_click`,
+  `right_click`, `middle_click`, `double_click`, `triple_click`, `left_click_drag`, `mouse_move`, `left_mouse_down`,
+  `left_mouse_up`, `cursor_position`, `scroll`, `type`, `key`, `hold_key`, `wait`). Each command above and `act` print
+  one line per action and exit 1 when one failed (in a batch the rest are skipped).
+- `stream` prints a link to the viewer (view only unless `--interactive`; `--ttl` 1m to 7d, default 24h); anyone with
+  it can watch until it expires. `stream --stop` ends every view.
+- `ws computer enable|disable|inherit` sets the workspace's own switch (`inherit` follows the template);
+  `templates computer-use <slug> on|off` sets it for every workspace of one of your templates.
+
 ## Start deadlines
 
 A queued open, resume or fork (`capacity_pending`) has a deadline 15 minutes after it was created.
@@ -981,3 +1036,44 @@ Use the byte offset in each acknowledgement, including partial writes. `ws resum
 ### Prepare an imminent command (0.9.0+)
 
 Call `shard ws hint <workspace>` ahead of a tool call to stage a parked workspace while the input is prepared. It returns without waiting for restore. Resume a suspended workspace first. The hint is explicit; ordinary commands add no early hint.
+
+Resize controls (0.11.0+): `shard ws resize <workspace> --memory 6144 --disk 2 --at-least --no-wait` grows only
+resources that need more capacity and returns the held server answer with the operation. The normal command waits
+for completion. Fixed memory without `--memory-mib` uses the template default.
+
+## New in 0.11.0
+
+`shard ws computer stream <workspace>` reuses a private viewer link with more than 60 seconds left across CLI invocations. `--fresh` mints a new link, and `--stop` clears it. Canceled exec commands exit 130, timeouts exit 124, and signal exits use 128 + signal. `SHARDFLUX_BASE_URL` aliases `SHARDFLUX_API_URL`; the latter and `--api-url` take precedence. The SDK transport honors environment HTTP(S)_PROXY and NO_PROXY.
+
+## Embed a live viewer (0.11.0+)
+
+Watch the desktop or a port preview inside your web app. Choose 1–10 distinct HTTPS origins, then use the returned URL as the iframe source.
+
+```bash
+shard ws computer stream acme/demo --embed-origin https://app.example.com
+shard ws port link acme/demo 3000 --embed-origin https://app.example.com --embed-origin https://admin.example.com
+```
+
+```html
+<iframe src="RETURNED_LINK_URL" title="Watch the agent" style="width:100%;height:600px;border:0"></iframe>
+```
+
+The browser session is partitioned by the top-level site. Each origin is exactly a scheme and host with an optional port, such as `https://app.example.com:8443`. The viewer permits framing by those origins; interactive viewing uses the same allowlist.
+
+## Idle deletion retention (0.11.0+)
+
+```sh
+shard ws open chat/42 --template python-node-browser --delete-after-idle 14d
+shard ws retention chat/42 30d
+shard projects retention PROJECT_ID 14d --labels '{"app":"chat"}'
+shard projects retention PROJECT_ID
+shard ws retention chat/42 off
+```
+
+Use 1d through 3650d with persistent workspaces. `off` removes the workspace's own policy and follows its
+project default; `shard projects retention PROJECT_ID off` clears that default. All selector labels match
+exactly, and a workspace's own setting wins. With no policy, workspaces stay until you delete them.
+
+## Workspace upgrade (0.11.0+)
+
+`shard ws upgrade <key>` keeps files and installed package files through one cold start. Memory and processes end. Use `--at next-resume` to schedule it without stopping the VM; `--json` returns the operation and its applied/scheduled result.

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.9.0";
+export declare const CLI_VERSION = "0.11.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;
@@ -29,7 +29,6 @@ export interface CommandSpec {
 export declare const GLOBAL_OPTIONS: Record<string, OptionSpec>;
 /** Every command: the account plane first (sign in, set up), then the project-key commands. */
 export declare const COMMANDS: CommandSpec[];
-/** Canonical command words: aliases resolved, `workspaces files|operations|executions` folded to the top-level group. */
 export declare function normalizeWords(words: string[]): string[];
 export declare function findCommand(words: string[]): CommandSpec | undefined;
 /** "90s", "5m", "1.5h", "250ms"; a bare number is seconds. */