docs(guide): mark USERGUIDE.md deprecated

It is too far out of date to be worth repairing. It describes identity keys
derived from a username and password, one `shared_dir` per group with an
`uploads/` quarantine, ChaCha20 as the content cipher, a hub that stores users'
public keys and the wrapped group keys, and a member wrapping that key for
another member — which is finding H3, in the section that explains why the hub
cannot read your files.

The banner lists each of those against what is actually true, so that no section
below it is mistaken for current, and points at MESHBAY_DESIGN.md and
MESHBAY_NODE_PROTOCOL.md instead. It also records what the document predates
entirely: encrypted chat, the sealed index and upload path, transfer leases,
device linking, the application framework.

Repairing it section by section is refused deliberately. Enough of it is wrong
that a reader cannot tell the sound parts from the stale ones, which is worse
than having no guide, and fixing one section leaves exactly that problem in
place. The previous commit — which translated two French passages and corrected
the errors immediately around them — is dropped for the same reason: it made a
small part of a misleading document accurate, which makes the whole harder to
distrust, not easier.

There is no replacement user guide today. That gap is real and is better stated
than papered over.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YVoHVCcfBqud6ZjG4db3y7

2 files changed, 30 insertions, 1 deletions

diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md
index 67f0bff..d34351b 100644
--- a/docs/MESHBAY_DESIGN.md
+++ b/docs/MESHBAY_DESIGN.md
@@ -33,7 +33,7 @@
 | `MESHBAY_NODE_PROTOCOL.md` | the MNP wire format, message by message |
 | `transfers-v1.md` | the transfer system's failure-mode analysis, kept because a synthesis cannot carry "every way a slot can be lost" |
 | `playlists.md` | the playlist design in full — decided, not built (§9.10) |
-| `USERGUIDE.md` | how to use and operate a deployment |
+| ~~`USERGUIDE.md`~~ | **deprecated** — a large majority of it predates per-node identity, named roots and the sealed wire, and is wrong. Kept for provenance; its own banner lists what is false |
 | `PACKAGING-GUIDE.md`, `QUICKSTART.md`, `HTTPS.md`, `MAIL-SERVER.md`, `windows-build.md` | installation and server operations |
 | `CLAUDE.md` | project conventions and the engineering lessons that govern how changes are made |
 | `old-draft.md` | historical archive of drafts v1–v4. Nothing there is authoritative |
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index 3c0e30c..c9febff 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -1,5 +1,34 @@
 # MeshBay User Guide
 
+> # ⚠️ DEPRECATED — do not rely on this document
+>
+> **A large majority of it is wrong.** It describes the system as it stood before
+> several of the changes that define it now, and it has not been maintained since.
+> It is kept for provenance only. **Read `MESHBAY_DESIGN.md` for the architecture
+> and the security model, and `MESHBAY_NODE_PROTOCOL.md` for the wire format.**
+>
+> What is known to be false here, so that nothing below is mistaken for current:
+>
+> | Section | What it claims | What is true |
+> |---|---|---|
+> | §2 Account Management | Identity keys are derived from username + password, or generated in the browser and stored on the hub as an encrypted bundle | Identity keys are **per node**, created at first contact with each node and left there. Registration generates nothing, and the hub stores no keypair bundle and no user public key |
+> | §4 Setting up a Node, §5 Sharing Files | A group has one `shared_dir`, and everything members send lands in `shared_dir/uploads/` | A group has **several named roots**, each read-only or read-write. The `uploads/` quarantine was removed on 2026-09-06 |
+> | §8 Security Model — ciphers | ChaCha20-Poly1305 is the principal cipher, AES-GCM an optional browser variant | **AES-256-GCM encrypts everything.** No production path constructs a ChaCha20 cipher |
+> | §8 Security Model — what the hub stores | The hub holds users' identity public keys and the wrapped group keys | It holds neither. Removing the key directory is what closed finding **H3**; the bundles moved to the node |
+> | §8 GEK wrapping | A member wraps the group key for another member, and the hub stores the bundle | **The node wraps it**, on every connection, for a key the joiner proved possession of. The described flow *is* finding H3 |
+> | §10 Troubleshooting | `GET /v1/groups/{id}/gek` returns 404 | That endpoint no longer exists |
+>
+> And it predates, so never mentions: encrypted chat, the sealed index and upload
+> path, transfer leases, device linking, and the group-application framework.
+>
+> Two passages are also still in French, and one code fence is unbalanced.
+>
+> **Do not repair this file section by section.** Enough of it is wrong that a
+> reader cannot tell the sound parts from the stale ones, which is worse than
+> having no guide — and a patch that fixes one section leaves that problem intact.
+> A user guide, when there is one again, starts from `MESHBAY_DESIGN.md`.
+
+
 This guide covers MeshBay in depth — architecture, configuration, security, and the full API. Read the [Quickstart](QUICKSTART.md) first if you have not set up a node yet.
 
 ---