@meistrari/remy-cli 1.26.0-rc.0 → 1.26.0-rc.2

package/README.md

@@ -50,7 +50,7 @@ Help, version, sign-in/out, direct session commands, and redirected/noninteracti
 
 ## Your everyday workflow
 
-The dashboard is the starting point for all interactive work. It refreshes the visible session page every 10 seconds, so new sessions and status changes appear while you keep it open. If an update fails, Remy keeps showing the last successful list and retries on the next interval.
+The dashboard is the starting point for all interactive work. It refreshes the visible session page every 10 seconds, so new sessions and status changes appear while you keep it open. If an update fails, Remy keeps showing the last successful list and retries on the next interval. Each session shows its creator and where it started, such as `Slack #team-channel`, `Linear ENG-123`, or `CLI`.
 
 ### Start work
 
@@ -70,7 +70,7 @@ The new-session request and conversation composers share path completion and att
 
 Terminal follow-ups default to **Steer**, targeting the work currently in progress. Press `Ctrl+Enter` to queue a message as **Next**, which waits for current work to finish. Plain `Enter` continues to send as Steer. Failed submissions retain their mode, attachments, settings, and idempotency key when retried with `Ctrl+R`. Remy can replay sessions containing queued-message dispatch, withdrawal, and failure events. Messages withdrawn or failed before reaching Remy show an activity notice; an active submission ends as cancelled or failed instead of waiting for a turn that never started.
 
-Use Up/Down to select a session in the dashboard, Left/Right to load the adjacent page, and `Enter` to open it. Remy shows the session header and composer immediately after session details load, while retained conversation history loads in the background. You can start drafting immediately; sending is paused until history finishes, and your draft stays intact. New activity then streams as it arrives. Press `s` to fuzzy-search all accessible sessions through the API by author, repository, branch name, pull request title/number, or session number/ID/title; `Enter` applies immediately and keeps the search active; `Esc` clears it. Typing refreshes results after a short pause. Matching ignores case and query whitespace and finds characters in order within a field (for example, `grch` matches `Grace Hopper`); numbers also accept `#`. Search combines with your other filters and stays active across pages. Session rows and compact cards show the repository and session work branch (`Branch pending` when unassigned). Press `f` to filter sessions by lifecycle status, `a` by author, or `r` by repository. These pickers use checkboxes: Up/Down or `j`/`k` moves, `Space` toggles, Right/`l` checks, Left/`h` clears, `G` and `gg` jump to the last and first option, and `Enter` applies every checked value. An empty picker means all values. Press `s` inside a picker to fuzzy-search its options; `Enter` keeps the matching list and `Esc` cancels the search. Press `Esc` outside search to discard staged checkbox changes. Press `b` to filter by a case-insensitive part of a branch name; Enter applies it, an empty value clears it, and Esc discards edits. Repository and branch filters must match the same repository in a session. Filters apply to the complete remote result set and reset pagination to its first page. After the dashboard list or repository-review list has focus, Vim keys work too: `j`/`k` move, `h`/`l` go to the previous/next dashboard page (or clear/mark a repository), `G` goes to the last row, and `gg` goes to the first row. Press `Shift+L` in the dashboard to start a logout confirmation. In any message composer, plain `Enter` and `Shift+Enter` submit; `Option+Enter` on macOS (`Alt+Enter` elsewhere) inserts a newline. `Ctrl+J` also inserts a newline for terminals that do not report the Option/Alt modifier. `Cmd+Left`/`Cmd+Right` move to the start or end of the current line, as do `Home`/`End`, which many macOS terminals send for those keys; `Ctrl+D` deletes the character after the cursor. In the session view, `Ctrl+C` first clears a non-empty draft; press it again with an empty composer to exit. The conversation header keeps the numbered session title on its first line and repository, pull request, work state, elapsed time, connection state, and the agent's current `Harness · Model · Effort` on its second line. The header also keeps the last provider-reported context observation across reconnects, such as `Context 50% left · 62,000 used`; when the provider does not report a context window, it shows only used tokens. This is an observation, not a live occupancy guarantee or billing total.
+Use Up/Down to select a session in the dashboard, Left/Right to load the adjacent page, and `Enter` to open it. Remy shows the session header and composer immediately after session details load, while retained conversation history loads in the background. You can start drafting immediately; sending is paused until history finishes, and your draft stays intact. New activity then streams as it arrives. Press `s` to fuzzy-search all accessible sessions through the API by author, repository, branch name, pull request title/number, or session number/ID/title; `Enter` applies immediately and keeps the search active; `Esc` clears it. Typing refreshes results after a short pause. Matching ignores case and query whitespace and finds characters in order within a field (for example, `grch` matches `Grace Hopper`); numbers also accept `#`. Search combines with your other filters and stays active across pages. Session rows and compact cards show the repository and session work branch (`Branch pending` when unassigned). Press `f` to filter sessions by lifecycle status, `a` by author, or `r` by repository. These pickers use checkboxes: Up/Down or `j`/`k` moves, `Space` toggles, Right/`l` checks, Left/`h` clears, `G` and `gg` jump to the last and first option, and `Enter` applies every checked value. An empty picker means all values. Press `s` inside a picker to fuzzy-search its options; `Enter` keeps the matching list and `Esc` cancels the search. Press `Esc` outside search to discard staged checkbox changes. Press `b` to filter by a case-insensitive part of a branch name; Enter applies it, an empty value clears it, and Esc discards edits. Repository and branch filters must match the same repository in a session. Filters apply to the complete remote result set and reset pagination to its first page. After the dashboard list or repository-review list has focus, Vim keys work too: `j`/`k` move, `h`/`l` go to the previous/next dashboard page (or clear/mark a repository), `G` goes to the last row, and `gg` goes to the first row. Press `Shift+L` in the dashboard to start a logout confirmation. In any message composer, plain `Enter` and `Shift+Enter` submit; `Option+Enter` on macOS (`Alt+Enter` elsewhere) inserts a newline. `Ctrl+J` also inserts a newline for terminals that do not report the Option/Alt modifier. `Cmd+Left`/`Cmd+Right` move to the start or end of the current line, as do `Home`/`End`, which many macOS terminals send for those keys; `Ctrl+D` deletes the character after the cursor. In the session view, `Ctrl+C` first clears a non-empty draft; press it again with an empty composer to exit. The conversation header keeps the numbered session title on its first line and repository, pull request, work state, elapsed time, connection state, and the agent's current `Harness · Model · Effort` on its second line. A session connected to a Linear issue also shows that connection and its status there, such as `Connected to Linear · ENG-123 (Connected)`; the status is `Connecting` while Remy links the session to the issue and `Closed` after the session ends. The connection label links to the issue in terminals that support hyperlinks, and `/links` lists the issue URL. The header also keeps the last provider-reported context observation across reconnects, such as `Context 50% left · 62,000 used`; when the provider does not report a context window, it shows only used tokens. This is an observation, not a live occupancy guarantee or billing total.
 
 If a connected session loses its activity stream, Remy retries for up to two minutes and resumes from the last received event. After the live stream stays connected for at least 30 seconds, the next disconnect starts a fresh retry window. Connections that drop sooner share the existing window and backoff. While a submitted message is still awaiting its outcome, retries continue beyond that window.
 
@@ -82,9 +82,9 @@ Published files and Tela Pages appear in the timeline. File artifacts include th
 
 Your messages and Remy's render as Markdown: headings, bold, italic, strikethrough, inline and fenced code, lists and task lists, quotes, tables, and links show formatted, with their syntax markers hidden. A Markdown link shows its label; a target that is not a plain HTTP or HTTPS URL stays visible as the original source text. The live assistant preview shows raw text until the finished message arrives, and a message with expanded workspace context shows its original text.
 
-**Open links:** Ctrl+click an HTTP or HTTPS link in the conversation, including Markdown links and expanded activity links. Ordinary clicks and drag-to-copy keep their existing behavior. Terminals may reserve that gesture or use their own modifier for hyperlinks; `/links` or `Ctrl+L` provides a keyboard alternative. Select with arrows or `j`/`k`, press `Enter` to open the browser, or `c` to copy the complete URL. Browser opening uses the machine running Remy.
+**Open links:** Ctrl+click an HTTP or HTTPS link in the conversation, including Markdown links and expanded activity links. Ordinary clicks and drag-to-copy keep their existing behavior. Terminals may reserve that gesture or use their own modifier for hyperlinks; `/links` or `Ctrl+L` provides a keyboard alternative; for a session connected to a Linear issue, the issue comes first. Select with arrows or `j`/`k`, press `Enter` to open the browser, or `c` to copy the complete URL. Browser opening uses the machine running Remy.
 
-**Download files:** `/files` or `Ctrl+F` opens a session file picker, newest first, containing Remy’s published artifacts and attachments sent by everyone in that session, with author/source labels. Repeated updates to an artifact appear once, using its newest title and URL. Select with arrows or `j`/`k`; `Enter` (or `d`) downloads to `~/Downloads`, creating that directory if needed. Remy shows progress and the full saved path. Existing files are preserved: another `report.txt` becomes `report (1).txt`. Press `o` for the Web preview or `c` to copy its URL; previews use your browser sign-in. Tela Pages open their canonical URL instead of downloading. The picker also works in closed sessions. `Esc` cancels an unfinished download and returns to the conversation with your draft intact, without stopping Remy. Errors stay visible for an explicit retry, which requests fresh download authorization. Files are saved without executing or extracting them. This picker covers published files and message attachments; embedded tool-output media remains available through **View event in Web**.
+**Download files:** `/files` or `Ctrl+F` opens a session file picker, newest first, containing Remy’s published artifacts and attachments sent by everyone in that session, with author/source labels. Repeated updates to an artifact appear once, using its newest title and URL. Select with arrows or `j`/`k`; `Enter` (or `d`) downloads to `~/Downloads`, creating that directory if needed. Remy shows progress and the full saved path. Existing files are preserved: another `report.txt` becomes `report (1).txt`. Press `v` to open the selected item in Remy Viewer. Press `o` for the Web preview or `c` to copy its URL; previews use your browser sign-in. Tela Pages open their canonical URL instead of downloading. The picker also works in closed sessions. `Esc` cancels an unfinished download and returns to the conversation with your draft intact, without stopping Remy. Errors stay visible for an explicit retry, which requests fresh download authorization. Files are saved without executing or extracting them. This picker covers published files and message attachments; embedded tool-output media remains available through **View event in Web**.
 
 System observations appear as **system notifications** with the system actor, source, and a generic JSON data view. Remy preserves unknown actor IDs and notification formats rather than treating them as user messages or commands. Once the runtime accepts a notification, retained history can associate it with the known Remy turn that it started or joined without adding a synthetic prompt. The retained timeline keeps a turn-starting observation before that turn's start and a joined observation after the active turn's start, at the observation's original event position. Delivery is at-least-once, so an uncertain retry can produce additional distinct turns or repeat effects in an active turn; Remy preserves every observed turn rather than presenting the association as proof of exactly-once execution. The CLI has no control for creating notifications.
 
@@ -114,7 +114,9 @@ Drag to select visible text in any Remy view; Remy copies it to the local clipbo
 | `/sessions` | Return to the dashboard. |
 | `/new` | Start another new-session flow. |
 | `/logout` | Sign out of Remy after confirmation. |
-| `/files` / `Ctrl+F` | Browse and download session artifacts and everyone’s attachments. |
+| `/files` / `Ctrl+F` | Browse and download session artifacts and everyone’s attachments; `v` opens the selection in Remy Viewer. |
+| `/viewer` | Open the current session artifact list in Remy Viewer. |
+| `/desktop` | Select Desktop in Remy Viewer; connecting remains explicit. |
 | `/changes` / `/workspace` | Browse read-only workspace changes or repository files and diffs. |
 | `/context` | Review or remove staged workspace context before sending. |
 | `/mcps` | Inspect session MCP attachments and available offerings; add or toggle optional attachments on open sessions. |
@@ -135,6 +137,27 @@ Drag to select visible text in any Remy view; Remy copies it to the local clipbo
 
 </details>
 
+## Visual companion
+
+Remy Viewer is a separate app for macOS 13+ on Apple Silicon. It shows published artifacts, message attachments, Tela Pages, and Desktop beside your terminal; the conversation stays in Remy. Native/signing acceptance is required before a release is distributed. Use the signed arm64 DMG or ZIP from a validated viewer release, read its minimum compatible CLI version, and copy **Remy Viewer.app** to `~/Applications` or `/Applications`. The viewer bundles its runtime; Bun remains a CLI requirement only.
+
+```bash
+remy viewer <session-id>
+remy viewer <session-id> --artifact <artifact-id>
+remy viewer <session-id> --attachment <attachment-id>
+remy viewer <session-id> --desktop
+```
+
+Selection flags are mutually exclusive. `--json` emits one `{ "viewer": ... }` acknowledgment/failure result and exits; it does not turn the viewer into an unattended API or bypass a graphical session. `/viewer`, `/desktop`, and `v` in `/files` provide the same handoff from an attached session. An explicit launch focuses the window; later publications update the list without changing your selection. Closing the launching CLI leaves the viewer usable. Closing viewer tabs/windows or quitting never stops, cancels, or completes the remote session.
+
+Run `remy login` first when requested; browser-based identity approval remains necessary. The viewer shares coordinated CLI credentials without a second token store. Quit it before switching configuration/token path contexts. Logout or account/configuration changes clear its content and streams; local logout is not remote token revocation.
+
+Desktop needs an explicit **Connect** and uses direct WebRTC, with no TURN relay. Restricted networks may prevent connection; selecting Desktop does not wake a paused sandbox. Embedded tool-output media and repository Changes/Files remain in their existing terminal/Web surfaces.
+
+If the app is missing or cannot be verified, install a trusted release and compatible CLI. For version errors, update both; for `context-conflict`, quit the viewer; for `login-required`, sign in again. Timeout or invalid-reply errors ask for an explicit retry. Launch failure preserves your terminal draft/session and never silently installs software or opens a browser.
+
+Viewer updates are manual: **Cmd+Q**, replace the app with the new signed release, then relaunch. `remy update` updates the CLI only. Replacing a running viewer is unsupported, and upgrades do not migrate shared token files. To uninstall, quit and remove the app; downloads and CLI credentials remain separate.
+
 ## Commands for direct or scripted use
 
 The interactive dashboard is the recommended path. Use these commands when a script needs Remy, or when you already know exactly what to open or create.
@@ -255,6 +278,7 @@ remy whoami
 remy update
 remy --version | -v
 remy dashboard
+remy viewer <session-id> [--artifact <artifact-id> | --attachment <attachment-id> | --desktop] [--json]
 remy new [--repository <owner/name> ... --installation <id> --model <name> --reasoning-effort <low|medium|high|xhigh> --attach <path> ... --mcp <offering-id> ... --no-tui --json] <prompt>
 remy --session <session-id> [--queue --model <name> --reasoning-effort <low|medium|high|xhigh> --no-tui --json] [prompt]
 remy session open <session-id>