docs: state the pepper, MBK3, the desktop keyring and browser access as they are

Design §2.2-§3.7, §4, §5.6, §7.7, §8, §9.10 and the registers; protocol §7,
§7.1, §7.1a and §13; the user guide; CLAUDE.md's parity rule.

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

1 files changed, 35 insertions, 8 deletions

diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index 7eeafbf..eb9452e 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -185,6 +185,10 @@ identity: it asks for your passphrase, unlocks the copy of your keys kept
 there, and you are in. No second code, nobody to ask — which is another reason
 the passphrase is worth choosing well.
 
+That copy exists only if your account allows browsers. An account created in the
+desktop application does not until you say so (below): a browser then cannot
+open your groups with the passphrase alone, and tells you why.
+
 ### The desktop application
 
 Worth installing if you use MeshBay more than occasionally:
@@ -193,7 +197,7 @@ Worth installing if you use MeshBay more than occasionally:
 |---|---|---|
 | Install | none | a package |
 | Interface comes from | the hub, on every visit | inside the package, from disk |
-| Keys | in the browser, plus a copy on each node | in the OS keyring, never bundled anywhere |
+| Keys | in the browser, plus a copy on each node | kept by the application in the OS keyring; a copy on each node only if you allow browsers |
 | Downloads | to disk where the browser allows it | native, streamed, no size limit |
 | Casting to a TV | — | yes |
 
@@ -203,10 +207,20 @@ any. So the application is the one to prefer for anything you care about. The
 browser stays, and is a perfectly reasonable way to use MeshBay — being able to
 open a group on someone else's laptop with nothing installed is worth having.
 
+**Browser access** (Profile → Browser access, in the application) decides whether
+a browser can open your groups with your passphrase. With it off — the default for
+an account created in the application — your keys stay on this computer and
+nothing of them is left on anybody's node. With it on, the application leaves a
+locked copy on each node, as a browser would. The change reaches each group the
+next time it opens. A browser can also be approved from the application for
+itself, group by group: the browser shows a linking code (*Get a linking code*),
+and you enter it in the application under *Your devices on this node*. That gives
+the browser keys of its own without turning browser access on.
+
 The application asks in a small window of its own, not in the page, before it
 hosts a group on this computer, shares a folder you did not pick in its folder
-dialog, replaces a group's key, clears the denylist, or points the node at
-another account. A folder you pick in the folder dialog is not asked about
+dialog, replaces a group's key, clears the denylist, turns browser access on, or
+points the node at another account. A folder you pick in the folder dialog is not asked about
 twice. That window belongs to the application, so nothing displayed in the page
 — which shows content from other people's nodes — can answer it for you.
 
@@ -745,9 +759,12 @@ deciding what belongs in a group and what is better kept elsewhere.
   browser downloads its code from the hub every time you open it; the
   application carries its own and never asks the hub for any. For anything you
   would rather not stake on the hub behaving, prefer the application.
-- **Your passphrase is what guards your keys.** A copy of them, locked with it,
-  sits on each machine you have joined. A long one puts that out of reach; a
-  guessable one does not. This is the single thing most worth getting right.
+- **Your passphrase is what guards your keys.** When your account allows
+  browsers, a copy of them sits on each machine you have joined, locked with your
+  passphrase and a second secret your hub keeps, so the people running those
+  machines cannot sit and guess at it. Whoever runs the hub holds that second
+  secret, though, and for them a guessable passphrase is still a weak one. A long
+  one puts it out of reach. This is the single thing most worth getting right.
 - **An open group is open.** Anybody can walk into one, which is what open
   means. Invite-only is the default, and is what you want for anything personal.
 - **The hub sees who is in which group, and when.** Never what was said or
@@ -792,8 +809,18 @@ namespace, so a volume mounted after it started is invisible to it.
 The browser is not paired. `meshbay-node operator pair`, then enter the code in
 the Members tab.
 
-**A member changed their passphrase while the node was down.**
-`meshbay-node member unpin <user>`, then a fresh invitation code.
+**A member changed their passphrase in a browser while the node was down.**
+`meshbay-node member unpin <user>`, then a fresh invitation code. The desktop
+application catches up by itself the next time it reaches the node.
+
+**"This node holds your identity in a format this version no longer reads."**
+The member's keys on that node were locked the way versions before 0.17 did it,
+which this version refuses. `meshbay-node member unpin <user>` on the node, then a
+fresh invitation code.
+
+**"Browser access is off for this account."**
+The account keeps its keys in the desktop application. Turn browser access on
+there (Profile), or approve this browser from it.
 
 **Video says the codec is not supported.**
 The source codec has no decoder in that browser and transcoding is off, or