1 files changed, 81 insertions, 2 deletions
diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md
index 189dbc5..3672da2 100644
--- a/docs/MESHBAY_DESIGN.md
+++ b/docs/MESHBAY_DESIGN.md
@@ -152,7 +152,86 @@ document uses:
 | **Registered hub user with no membership** | Reach every hub endpoint that does not check membership |
 | **Federated peer hub** | Push directory rows and revocations over MHP |
 
-### 2.2 Security claims
+### 2.2 Security claims — and how to read them
+
+Every collaboration product carries the structural limits this section lists.
+Most never write them down. What follows states ours plainly and separates three
+things a single ❌ usually hides — a **definition**, a **guarantee** and an
+**accepted risk** — and says, where it matters, how a comparable product fares on
+the same point. Read it with one rule: **where you see a limit here, assume the
+mainstream closed product has it too and does not tell you.**
+
+The verdict first. Against anyone *outside* your group — the hub, the network,
+another group's operator — your content is unreadable. *Inside* your group, your
+operator and fellow members read it, because that is what a group is. The one
+place the protocol cannot protect a browser is **T3** (below); the native client
+turns that from an invisible attack into a publicly verifiable one.
+
+#### What a group inherently means
+
+These are not defeats of the design; they are what *a shared, hosted group* is.
+Each would read as ❌ in any honest table, for any product in this class:
+
+- Your **operator and fellow members read the group's content** — files, index
+  and chat. You chose them when you joined; they are your trust boundary, not the
+  hub's.
+- Your **operator hosts the files, so they can alter what they host.** Authority
+  over a node's content is the operator's by design (§2.4, §7).
+- **Leaving clears you hub-side; copies on a node you were hosted on stay** with
+  that operator (§7.7).
+
+On the one point every product in this class shares — who can read your content —
+stated the way an honest table would:
+
+| Who can read your content | MeshBay | A mainstream E2EE messenger | A mainstream cloud suite |
+|---|---|---|---|
+| The people in your group | Yes — operator + members | Yes — every member | Yes — members + workspace admin |
+| The server / host itself | No (native) · T3 (browser) | No — but a web build has the same client-code exposure, unstated | Yes, routinely |
+| Is this limit written down for you? | Here, explicitly | Rarely | Almost never |
+
+#### What MeshBay guarantees
+
+Stated as guarantees, not as the absence of failure, against the adversaries in
+§2.1:
+
+- Your **content never transits the hub** — the hub relays, it does not hold your
+  plaintext (§5).
+- **No party outside your group reads your files, index or chat**: not the hub,
+  not the network, not the operator of any *other* group (§3.2, §4).
+- The **hub holds no user key and cannot countersign**: it cannot add a device to
+  your account, become *you*, or obtain your group key — except where you ask it
+  to (open-join, mailed invitations; §7.3, §3.4).
+- A **node cannot be impersonated**, and content one node holds cannot be forged
+  into another's (§5).
+- Your **identity keys are per-node**: a bundle that leaks opens that one node's
+  bundle and no other (§3, §2.4).
+- **Chat is unreadable from a copy of a node's storage** that lacks its unlock
+  key (§4.5).
+
+#### Residual risks, and how they are checked
+
+Two risks are real, named and accepted — each with the control that bounds it:
+
+- **T3 — a compromised hub and the browser.** The hub serves the browser SPA, so
+  an active hub can ship modified code to a browser user and lift their keys. No
+  protocol prevents this; it is accepted for browsers (§2.3). The **native client
+  removes it**: its code ships in the package, not from the hub, so a malicious
+  hub cannot alter it **without the change being publicly verifiable** — anyone
+  can rebuild from source and compare hashes (reproducible builds). The attack
+  moves from invisible-and-per-user to an artifact the whole community can check.
+  This is *verifiable*, not merely *detectable*: integrity someone actively
+  confirms, not something a victim might happen to notice.
+- **C4 — keypair bundles.** For an account with browser access, each node holds
+  the bundle, sealed under the passphrase *and* a pepper the hub alone holds: no
+  operator can search it offline, only an active hub can — which is T3's adversary
+  already. For an account the desktop app keeps (browser access off, §3.7),
+  nothing of it sits on any node. An account is only as strong as its weakest
+  client.
+
+#### The full claim matrix
+
+For auditors: the complete claim-by-adversary matrix. The sections above are the
+reading; this is the reference.
 
 | Claim | Passive hub | Active hub | Malicious node operator | Malicious member | Network attacker |
 |---|---|---|---|---|---|
@@ -163,7 +242,7 @@ document uses:
 | Chat is unreadable **from a copy of the node's storage that lacks its unlock key** — not from a whole disk by default (§4.5) | ✅ | ✅ | — the operator holds the unlock key | ✅ | ✅ |
 | Content cannot be modified | ✅ | ✅ | ❌ by design | ✅ | ✅ |
 | The node cannot be impersonated | ✅ | ✅ | — | ✅ | ✅ |
-| Client code integrity | ❌ **T3, accepted** (browser) · ✅ ships in the package (native) | ❌ T3 · ⚠️ native: **detectable, not prevented** | ✅ | ✅ | ✅ |
+| Client code integrity | ❌ **T3, accepted** (browser) · ✅ ships in the package (native) | ❌ T3 · ⚠️ native: **publicly verifiable, not prevented** | ✅ | ✅ | ✅ |
 | The hub cannot obtain the group key | ✅ | ✅ **except** in an open-join group, where it can join legitimately (§7.3), and for an invitation the inviter asked the hub to mail, whose code it then holds (§3.4) | — | — | ✅ |
 | Node content authority | ✅ | ✅ | ✅ sovereign | ✅ | ✅ |
 | Devices cannot be added by the hub | ✅ | ✅ — the hub holds no user key and cannot countersign | ⚠️ a node adds a device only to itself, where it already reads everything | ✅ | ✅ |