docs: record which download paths have actually been run

The download-to-disk story is three mechanisms — File System Access in
Chrome, a service worker streaming a response in Firefox and Safari, a
blob as the floor — and no test in this repository exercises any of them.
test_downloads.py pins their contracts by reading the source; whether a
browser really writes to disk needs a person with a large file.

One now has: Firefox, 180 MB, written to disk rather than assembled in
the tab. That is the path worth confirming, since it is the only one
Firefox has and it was written blind. It is also not the scale it exists
for, and the guide says which rows of that table are measured and which
are still only designed.

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

2 files changed, 23 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index ad215d5..6701d7d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -254,6 +254,14 @@ keypair bundle, or anything that looks like a user's public key.
   `deploy-hub.sh` runs `alembic upgrade head` before restarting the service; a schema
   change that skips a migration file will still pass every test you have
 
+- **Some paths only exist in a browser, and only one browser has them.** The
+  download-to-disk story is three different mechanisms — File System Access
+  (Chrome/Edge), a service worker streaming a response (Firefox/Safari), and a
+  blob as the floor — and no test in this repo exercises any of them.
+  `test_downloads.py` pins the contracts by reading the source; the behaviour
+  needs a person with a large file. Confirmed by the operator on 2026-08-15:
+  Firefox, 180 MB, written to disk. Nothing multi-gigabyte has been measured
+
 **Corrections to remember:**
 - `punch_nat()` is **not** a NAT traversal stack — one UDP probe, no STUN, no candidate
   gathering, one ISP validated. **ICE/STUN (WebRTC) is the traversal path**, for native
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index 8a55928..d6ce327 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -556,6 +556,21 @@ from a page. If even that is unavailable, a download under 512 MB is collected i
 memory and handed over; a larger one asks where to put it, because a tab does not
 survive a multi-gigabyte blob.
 
+**What has been exercised**, as of 2026-08-15, so the next person knows which of
+this is measured and which is designed:
+
+| Path | Browser | State |
+|---|---|---|
+| Streamed into a granted folder | Chrome | works |
+| Streamed by the service worker | Firefox | works — 180 MB, written to disk |
+| Collected in memory (no folder, no worker) | any | works, bounded at 512 MB |
+| Save As for a download over 512 MB | Chrome | works |
+| Multi-gigabyte download, any path | — | designed for, not yet measured |
+
+The 180 MB run is the one that matters most, because the service worker is the
+only way Firefox writes a download to disk rather than building it in a tab. It
+has not been tried at the scale it exists for.
+
 A finished download offers **Open** in the transfers widget when it went into a
 folder you granted: the file is handed to a new tab and the browser decides what
 to do with it. That is the whole of what a web page can do here — it cannot start