feat(cli): invitations, join, decline, leave, devices, browser access

join accepts an invitation or redeems a link pasted as sent, then has the
node admit a key pair made here, with the invitation's code (a link's code
goes only to the node it names; one for a node that is away is kept for the
next connection). decline, leave and devices revoke ask first, and refuse
without --yes where there is no terminal. devices approve countersigns the
one waiting request a code matches, none when several do. browser-access is
the application's setting, kept per machine and never enabled from the hub's
mirror: on leaves a copy sealed under M on each node, off withdraws it,
unset touches nothing. A key pair made for a first contact is now kept.

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

2 files changed, 59 insertions, 19 deletions

diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md
index a9502d8..c5a0847 100644
--- a/docs/MESHBAY_DESIGN.md
+++ b/docs/MESHBAY_DESIGN.md
@@ -3010,9 +3010,10 @@ MSE string) fed to a source buffer, with the node holding one slot per viewer.
 
 ### 8.6 The command-line client
 
-`meshbay-cli` (`packages/meshbay-cli`) is a member's files from a terminal:
-`login`, `logout`, `groups`, `ls`, `get`, `put`, `trust`, and with no argument
-an interactive two-pane view (Textual) over the same library. It is not an
+`meshbay-cli` (`packages/meshbay-cli`) is a member's groups and files from a
+terminal: `login`, `logout`, `groups`, `invitations`, `join`, `decline`,
+`leave`, `ls`, `get`, `put`, `devices`, `trust`, `browser-access`, 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, play or chat: those belong to an engine
 with a player and a page. English only.
@@ -3026,15 +3027,32 @@ data-related passes through the hub.
 **Identity on a node, in this order:** the identity this machine kept from an
 earlier run; the one waiting for a device approval; the bundle the node keeps
 for browsers, opened with the passphrase (§3.7) and then kept locally; failing
-all three, a new key pair filed as a device request (§3.3) — the code is
-printed, an already linked device approves it, and the client joins with its
-own keys. It never writes a bundle. That is the desktop client's position: an
-installed program, no hub-served code (T3 does not apply), so device linking
-is admitted for it as for the application.
+all three, a new key pair — admitted with an invitation's code by `join`, or
+filed as a device request (§3.3): the code is printed, an already linked device
+approves it, and the client joins with its own keys. That is the desktop
+client's position: an installed program, no hub-served code (T3 does not
+apply), so device linking is admitted for it as for the application, and it
+approves other devices as the application does (`devices approve`, exactly one
+waiting request per code).
 
-**What it keeps.** `state.json` (hub, account, pinned node keys) and
-`secrets.enc` (AES-GCM: the refresh token, the device hub key, the node
-identities) in the user's data directory (`$XDG_DATA_HOME/meshbay-cli`,
+**Joining and leaving** follow the application's two halves (§3.4): the hub
+makes the account a member (an invitation accepted, a link's ticket redeemed),
+then the node admits the key made here with the invitation's code; a link's
+code goes to the node the link names and to no other. `leave`, like
+`decline` and `devices revoke`, asks first on a terminal and refuses without
+`--yes` where there is none.
+
+**Browser access is the application's setting, kept per machine** (§3.7):
+`browser-access on` leaves a copy of the identity sealed under `M` on each node
+it opens a group on, when the node holds none or an outdated one; `off`
+withdraws it; never set, it writes and withdraws nothing. It is set on the
+command line and nowhere else: the hub's mirror, which anyone holding a session
+can write, is read only to tell a person joining that a browser will not open
+the group — never to upload a key.
+
+**What it keeps.** `state.json` (hub, account, pinned node keys, browser
+access) and `secrets.enc` (AES-GCM: the refresh token, the device hub key, the
+node identities, an invitation's code waiting for its node) in the user's data directory (`$XDG_DATA_HOME/meshbay-cli`,
 `%LOCALAPPDATA%\meshbay-cli`). The key that opens `secrets.enc` is in the OS
 key storage; where there is none, in a 0600 file, which `login` says once. The
 passphrase is never stored: a remembered session renews with the refresh
@@ -3060,9 +3078,10 @@ a `%` in a name, and a link copied from the application accepted as it is.
 group; a group whose node is away is reported without stopping the others
 (exit 4).
 
-**Exit codes** are a contract for scripts: 1 usage, 2 sign-in, 3 not found,
-4 partial, 5 node unreachable or waiting for device approval, 6 node key
-changed, 7 version, 8 refused before anything was sent, 130 interrupted.
+**Exit codes** are a contract for scripts: 1 usage (or a confirmation not
+given), 2 sign-in, 3 not found, 4 partial, 5 node unreachable, waiting for
+device approval, or asking for an invitation's code, 6 node key changed,
+7 version, 8 refused before anything was sent, 130 interrupted.
 
 **Packaging.** Its own `.deb`/`.rpm` (`meshbay-cli`, with the packages only it
 uses, on top of `meshbay-common`'s venv) and a man page generated from its
@@ -4562,8 +4581,9 @@ operator CLI and loopback control API, the desktop client through its identity
 and download stages, account recovery, the Windows port through packaging, and
 the Android client — the shell, native keys, downloads and uploads, casting,
 and notifications while it is closed, fetched or pushed (§11.3) — and the
-command-line client: groups, listing, downloads and uploads with resume,
-device linking, and an interactive two-pane view (§8.6).
+command-line client: groups, joining and leaving them, listing, downloads and
+uploads with resume, device linking and approval, browser access, and an
+interactive two-pane view (§8.6).
 
 The packages install: a machine has been taken from the built artefacts to a
 running hub and node on **Ubuntu 26.04 (`.deb`), Fedora 44 (`.rpm`) and
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index 09d264e..d66e757 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -230,8 +230,8 @@ twice. That window belongs to the application, so nothing displayed in the page
 
 ### The command-line client
 
-`meshbay-cli` reaches your groups' files from a terminal — a server, a script, a
-machine with no desktop. It is a package of its own on Linux (`meshbay-cli`,
+`meshbay-cli` reaches your groups and their files from a terminal — a server,
+a script, a machine with no desktop. It is a package of its own on Linux (`meshbay-cli`,
 with a manual page: `man meshbay-cli`), and comes with the desktop
 application's full installer on Windows (not with the light one).
 
@@ -261,7 +261,27 @@ can read, which `login` tells you.
 The first time it opens a group, the client may print a linking code instead
 of the files: the node holds no copy of your keys (Browser access is off), so
 this computer asks to be added as one of your devices. Enter the code in the
-application under *Your devices on this node*; the client goes on by itself.
+application under *Your devices on this node*, or run
+`meshbay-cli devices approve GROUP CODE` on a computer already linked; the
+client goes on by itself.
+
+Joining and leaving work as in the application (§4):
+
+```bash
+meshbay-cli invitations                       # what you were invited to
+meshbay-cli join Family@bob --code K7P2-9WQX  # accept, then give the node its code
+meshbay-cli join 'https://meshbay.org/#/invite?v=1&...'   # a link, pasted as sent
+meshbay-cli decline Club@carol
+meshbay-cli leave Club@carol                  # asks first; --yes in a script
+```
+
+`meshbay-cli devices list GROUP` shows your devices on the node serving a group;
+`devices approve` admits a new one by its code, `devices revoke` retires one.
+
+Like the application, the client keeps your keys to itself: a browser cannot
+open, with your passphrase alone, a group you joined from it. To allow that, as
+*Browser access* does in the application, run `meshbay-cli browser-access on`
+on that computer; `off` takes the copy back. It is that computer's setting.
 
 Managing a node is not the client's job: that is `meshbay-node` (§6).