docs: sync usage() and man page with actual CLI surface

party

@@ -30,16 +30,19 @@ Usage: party <subcommand> [args]
 Hosting:
   host [name] [--group <g>]
                           Start a party on a dedicated tmux server.
-  close                   Tear down the party you host.
+                          Names: letters, digits, '_', '-' (max 63).
+  close [name]            Tear down the party you host (name it when
+                          you host several).
 
 Joining:
   join [name] [--passive] Join a party. Without name: auto-pick or numbered prompt.
                           --passive lands in the host's session (mirrored view).
+                          Read-only invitees always join passive.
   leave                   Detach from the party you joined.
   role [active|passive|switch]
                           Flip your clients between guest session and host session.
 
-Moderation (host only):
+Moderation (host only; --party <name> disambiguates multiple parties):
   invite <user> [-r]      Add user to allowlist (read/write; -r for read-only).
   voice <user>            Promote user to read/write (alias: rw).
   mute <user>             Demote user to read-only (alias: ro).
@@ -48,7 +51,8 @@ Moderation (host only):
 
 Info:
   list                    List discoverable parties on this host.
-  who [--short]           Show invited and attached users for the active party.
+  who [--short] [--party <name>]
+                          Show invited and attached users for a party.
   status                  Show the caller's own party state.
   --help                  This message.
   --version               Print version.
@@ -113,8 +117,10 @@ user_in_party_group() {
 }
 
 # Soft assertion: caller is in TMUX_PARTY_GROUP. Fails loudly with
-# remediation instructions when not. Used by every subcommand that
-# touches the roster or socket.
+# remediation instructions when not. Called by cmd_host before any
+# filesystem work; the other subcommands don't need it — non-members
+# are stopped by the FS perimeter itself (EACCES at the per-party dir)
+# and get the friendlier group-gate message in cmd_join.
 require_caller_in_group() {
     if ! user_in_party_group "$USER"; then
         cat >&2 <<EOF
@@ -903,6 +909,9 @@ Usage: party join [name] [--passive]
              rather than your own guest session. Switch later with
              `party role` (note: role changes are session-level, not a
              read-only boundary, see `party role --help`).
+             Invitees added with `party invite -r` are read-only and
+             always join passive (tmux refuses session creation from
+             read-only clients).
 EOF
                 exit 0 ;;
             -*) echo "party join: unknown flag '$1'" >&2; exit 2 ;;