docs: settle the desktop client, and draft v6

A design discussion on 2026-08-17 settled Phase 13 and, in doing so, changed
four things the spec states. v6 restates only those; v5 stays authoritative for
everything it does not touch, per the convention v5 itself used with v4.

What changed:

  * The native shell is **Electron**, not pywebview — structural decision 18
    reversed. The SPA depends on Chromium-class APIs (WebRTC, WebCrypto
    X25519/Ed25519, MSE, Service Workers), so keeping Chromium keeps
    transport.js, crypto.js, keyderive.js, downloads.js and sw.js *as the
    client*. A system webview meant reimplementing ~2500-3000 lines. The old
    "69 % reused" figure was measured against an app.js of ~2600 lines; it is
    4586.

  * A group's content is **several named roots**, not one directory, because
    the planned video and audio libraries will not live in one folder on one
    disk.

  * **Device linking**: one person may hold several devices on a node,
    admitted by a key the node already pinned and bound by a one-time code the
    new device generates. Without it a native client is refused where a browser
    is not, and an account created natively could never be opened in a browser.

  * **Authorship is authenticated, not asserted** — chat senders sign, uploads
    have a provable owner, and delete authorization moves from the uploading
    key to the account.

And one rule v5 assumed without writing down: **group-related server state
lives on the node.** Verified for multi-root — SwarmSource carries hashes and
endpoints, no paths.

Also here: the Caddy configuration, which was a snippet in the roadmap that
would have broken the SPA (it predates /a/<hash>/ asset versioning and would
have 404ed /sw.js, silently killing streamed downloads on Firefox and Safari);
and downloads.html, which becomes a security page once a release key exists.

Phase 15 was re-read against device linking and is wrong as written: a sender
key must be per **device**, never per person, or two devices sharing a chain
produce key and nonce reuse — C1 again, one level down. senderkeys.py already
fails this silently.

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

1 files changed, 21 insertions, 3 deletions

diff --git a/tmp-decisions.md b/tmp-decisions.md
index 347d771..76d33d2 100644
--- a/tmp-decisions.md
+++ b/tmp-decisions.md
@@ -11,10 +11,14 @@
 | # | Decision | State |
 |---|---|---|
 | D1 | Does the hub keep serving the web UI? | ✅ **DECIDED 2026-08-13 — yes** |
-| D2 | Browser extension, native desktop client, or both? | ✅ **DECIDED 2026-08-13 — native client, offered alongside the hub-served SPA** |
-| D3 | Transport: aiortc primary, QUIC at parity, TCP+HTTP removed | ✅ Decided 2026-08-13 |
+| D2 | Browser extension, native desktop client, or both? | ✅ **DECIDED 2026-08-13 — native client, offered alongside the hub-served SPA.** Shell revised 2026-08-17: **Electron**, see `docs/desktop-client-v1.md` |
+| D3 | Transport: aiortc primary, QUIC at parity, TCP+HTTP removed | ✅ Decided 2026-08-13. Unchanged for the **node**; the desktop client uses Chromium's WebRTC rather than aiortc, and QUIC via a Python sidecar |
 | D4 | Hub minimization (old Phase 12) | ⏸️ **Deferred, may be dropped** |
 
+> **2026-08-17 — the browser-extension options are no longer live.** 12.2 (signed digest
+> of the served bundle) is what Option A needed, and it remains scheduled; nothing else
+> from A or B is planned. The desktop client is the answer to T3 for users who want one.
+
 **What was decided.** The hub keeps serving the web UI — that is the zero-install path
 and it stays. A native desktop client is offered *in addition*, not as a replacement.
 Hub minimization is off the critical path and may be dropped entirely.
@@ -103,10 +107,24 @@ hub operator does not control**. Manifest V3 forbids remote code, which works in
 the structure enforces exactly what we want. Keys live in extension storage, isolated from
 page JS. Moderate effort.
 
-**Option C — Native desktop client (pywebview + aiortc)** ← **CHOSEN**
+**Option C — Native desktop client** ← **CHOSEN**
 Phase 13. Full control, durable keys in an OS keystore, QUIC, hub-less access, best UX.
 Highest effort, and the security argument depends on 18.7.
 
+> **Shell revised 2026-08-17: Electron, not pywebview** (+ an optional Python sidecar for
+> `group://` over QUIC). See `docs/desktop-client-v1.md` §2. The comparison table below
+> was written against pywebview and **two of its rows are wrong for the chosen shell**:
+>
+> - *Browser sandbox* — Electron with `sandbox` and `contextIsolation` **keeps** the
+>   Chromium renderer sandbox. The row reads "❌ None (partial under Flatpak)"; that was
+>   WebKitGTK's property, not native's.
+> - *Crypto available* — the client keeps WebCrypto **and** gains local Argon2id/ChaCha20
+>   in the main process; the row implied WebCrypto is lost with the browser engine.
+>
+> The row that gets *worse*: **patch velocity**. "You own it" is more true of Chromium
+> than of a distro-maintained WebKitGTK, and the renderer parses attacker-controlled
+> content from nodes. That is the real cost and it is accepted deliberately.
+
 ### Comparison
 
 | | Hub-served SPA (today) | A: extension verifies | B: extension ships UI | C: native desktop |