feat(cli): stream — a film or a song played in a media player

`meshbay-cli stream PATH` serves one video or sound file over HTTP on
127.0.0.1 for VLC, mpv or any player that reads HTTP; `--player PROGRAM`
starts the player, and closing it stops the stream, as Ctrl+C does.

The file goes as the node stores it: no remux, no transcode, no stream
slot on the node. Byte ranges are answered from leaseless file_req chunks
decrypted in memory, eight ahead and the last 24 kept. Loopback only, a
random token in the address, a foreign Host refused (DNS rebinding), an
audio or video type with nosniff. The connection is pinged and reopened
when it dies; a refusal by the node stops the stream (exit 5).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2 files changed, 21 insertions, 4 deletions

diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md
index 28763af..ea1dab0 100644
--- a/docs/MESHBAY_DESIGN.md
+++ b/docs/MESHBAY_DESIGN.md
@@ -3025,11 +3025,11 @@ MSE string) fed to a source buffer, with the node holding one slot per viewer.
 
 `meshbay-cli` (`packages/meshbay-cli`) is a member's groups and files from a
 terminal: `login`, `logout`, `groups`, `invitations`, `join`, `decline`,
-`leave`, `ls`, `search`, `get`, `put`, `rm`, `chat`, `devices`, `trust`,
+`leave`, `ls`, `search`, `get`, `stream`, `put`, `rm`, `chat`, `devices`, `trust`,
 `browser-access`, `help` (what `--help` prints), and with no argument an interactive two-pane view (Textual)
 over the same library. It is not an operator tool — a node is administered
-through `meshbay-node` and its loopback API (§6.7) — and it does not stream or
-play: those belong to an engine with a player and a page. English only.
+through `meshbay-node` and its loopback API (§6.7) — and it plays nothing
+itself: `stream` hands a file to a media player. English only.
 
 **The same protocol as the other clients, end to end.** The hub signs it in,
 issues the per-node token (E10) and relays the WebRTC offer and answer; from the
@@ -3086,6 +3086,19 @@ message naming it; `/get NAME` saves a file of that folder into the current
 directory. The chat's folder follows the page's rule: the operator's choice
 while its root is writable and present, else the first such root.
 
+**Streaming** (`stream`) serves one video or sound file over HTTP on
+127.0.0.1 to a media player (VLC, mpv; `--player` starts one), as the node
+stores it: the player decodes it, so the node runs no ffmpeg and holds no
+stream slot (§8.5 is the browser's path). Each byte range the player asks for
+is answered from `file_req` chunks decrypted in memory, read without a lease as
+the application's players read, eight chunks ahead and the last twenty-four
+kept. Decrypted content on a local port is what is guarded: loopback only, a
+random token in the address, a request whose `Host` is not that address
+refused (DNS rebinding), an audio or video type with `nosniff`. The connection
+to the node is pinged every half minute and opened again when it dies; a
+refusal by the node stops the stream (exit 5); Ctrl+C, or closing the player
+`--player` started, ends it, and the address with it.
+
 **Deleting** (`rm`) is `file_delete` signed with the machine's key on the node
 (§5.4): the node accepts the uploading account's devices and the operator's.
 The client checks the same rule against the index first (`uploader_id`, and the
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index 5b6f77a..93205d3 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -245,6 +245,7 @@ meshbay-cli chat Family -m "On my way"  # post one (-m - reads it from stdin)
 meshbay-cli chat Family --follow        # then each new message, until Ctrl+C
 meshbay-cli chat                        # interactive: pick a group, talk, Esc to leave
 meshbay-cli get -R Family/photos/2024   # download, here; -o elsewhere
+meshbay-cli stream --player vlc 'Family/films/Night Drive.mkv'   # play it; Ctrl+C stops
 meshbay-cli put -R ~/scans Family/documents
 meshbay-cli rm Family/documents/old-draft.odt   # asks first; --yes in a script
 meshbay-cli logout
@@ -254,7 +255,10 @@ A group is named as the GROUP column of `meshbay-cli groups` prints it; add
 `@owner` only when two of your groups share a name. Quote wildcards
 (`'Family/music/*.flac'`): they are matched against the group, not against
 your disk. An interrupted download resumes where it stopped the next time you
-run the same `get`. `rm` deletes what you uploaded, from any of your devices;
+run the same `get`. `stream` plays a film or a song without downloading it:
+it prints an address to open in VLC or mpv (or starts the player with
+`--player`), which works on this computer only and until you press Ctrl+C or
+close the player; skipping ahead in the player works. `rm` deletes what you uploaded, from any of your devices;
 the node's operator can delete anything. Run `meshbay-cli` with nothing after it for a two-pane
 view: this computer on the left, your groups on the right, F5 to copy the
 selection across, Delete to delete it from the group (what `rm` may delete).