docs: add Python examples for the hub, a node and its control API

examples/ holds small scripts that talk to MeshBay the way the application
does, with the values to change as variables at the top of each one:

- meshbay_session.py: hub sign-in, WebRTC to a node serving the group, and
  the handshake (identity bundle, group key, proofs both ways)
- list_groups.py: the user's groups, up or down
- download.py: one file, decrypted chunk by chunk under a transfer lease
- upload.py: one file, sealed in 48 KiB chunks into a group folder
- create_group.py: creates a group on the hub and hosts it on the local node
  through its loopback control API

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

1 files changed, 38 insertions, 0 deletions

diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..f13e37a
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,38 @@
+# Examples
+
+Small programs that talk to MeshBay the way the application does, without the
+application. The values to change are variables at the top of each script.
+
+| File | What it does |
+|---|---|
+| `meshbay_session.py` | The shared part: signs in to the hub, connects to a node serving the group over WebRTC, and completes the handshake. Used by the scripts below |
+| `list_groups.py` | Lists your groups, `up` when a node serving the group is connected to the hub, `down` otherwise |
+| `create_group.py` | Creates a group on the hub and hosts it on the node running on this machine, through the node's control API on 127.0.0.1 |
+| `download.py` | Downloads one file from a group and saves it decrypted |
+| `upload.py` | Uploads one file into a folder of a group |
+
+```bash
+# From the root of the repository
+python3 -m venv .venv
+.venv/bin/pip install -e packages/meshbay-common aiortc httpx argon2-cffi
+
+# Edit the variables at the top of the script, then
+cd examples
+../.venv/bin/python download.py
+```
+
+The hub is `https://meshbay.org` by default. Paths in a group start with the
+root's name, then the folders, as in the group's file browser: `FILE_PATH =
+"shared/2024/beach.jpg"`, `DEST_DIR = "shared/2024"`. An upload needs a root the
+operator made writable, and never replaces a file: on a name clash the node
+picks a free name and says which.
+
+Why not curl: files never pass through the hub. They travel over a WebRTC
+DataChannel, straight between you and the node, encrypted under the group key.
+Signing in, the handshake with the node and the encryption all happen in the
+scripts.
+
+They need the node to keep a copy of your identity keys, sealed so that only
+your passphrase and your hub account can open it. That is the case when
+*Browser access* is on in the application's settings, or once you have opened
+the group in a browser.