feat(settings): choose between Save As and saving into a folder

Downloading a selection of twenty files meant twenty Save As dialogs,
which is the wrong answer for the feature that had just been built.
Settings → Downloads now offers saving automatically, and that is the
default; asking every time stays available for people who want it.

The correction worth recording: a web page cannot be given a filesystem
path and cannot read one either. There is no ~/Downloads to configure and
nothing to type, on any operating system — which is also why none of this
will need changing on Windows. What a browser grants is a handle to a
folder the user picked in a dialog, so that is what the setting keeps:
picked once, stored in IndexedDB, re-confirmed once a session because the
grant comes back as a claim rather than a permission. Where no folder has
been granted, and in Firefox and Safari where none can be, files go to
the browser's own download folder — which on most machines is the folder
that was meant all along.

Automatic saving has one risk a dialog does not: it can silently replace
a file. It does not — a taken name gets a suffix before the extension,
`clip (2).mp4`, so a download folder does not fill up with files the
system no longer recognises. That, and the default, are what
test_downloads.py pins.

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

1 files changed, 18 insertions, 0 deletions

diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index eec61d9..1bc3045 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -540,6 +540,24 @@ context menu at a time was the thing that made it awkward.
 Selection is remembered as you walk into folders, so you can tick something in
 one and something else in another before choosing an action.
 
+**Where downloads are written** is a setting, under Settings → Downloads:
+
+- **Save automatically** (the default) writes into a folder you pick once, with
+  no dialog. Downloading twenty files puts twenty files there. A name already in
+  use gets a suffix — `clip (2).mp4` — rather than replacing what is there.
+- **Ask every time** opens a Save As dialog per file, which is right for one file
+  and wrong for a selection of twenty.
+
+A web page cannot be given a filesystem path, and cannot read one either: there
+is no `~/Downloads` to configure, on any operating system, and nothing changes
+here on Windows for the same reason. What a browser grants is access to a folder
+the user picked in a dialog, and MeshBay only ever writes inside it. That grant
+is remembered, but the browser may ask you to confirm it once per session.
+
+Firefox and Safari have no File System Access API, so no folder can be granted:
+downloads go to the browser's own download folder, and Settings says so instead
+of offering a choice that would do nothing.
+
 **Transfers run outside the page.** They are listed in the widget next to the
 bell, with a progress bar, the current rate, and a cancel button each: