diff --git a/cloudflared-tunnel/README.md b/cloudflared-tunnel/README.md
index 662388d..6cf5a06 100644
--- a/cloudflared-tunnel/README.md
+++ b/cloudflared-tunnel/README.md
@@ -60,27 +60,8 @@ To check the upload, look at the owner's **Packages** tab in Gitea, or run
 
 ### 4. Install on each machine
 
-```bash
-sudo curl -fsSL https://git.dasfad.com/api/packages/mmainguy/debian/repository.key \
-  -o /etc/apt/keyrings/gitea-mmainguy.asc
-echo 'deb [signed-by=/etc/apt/keyrings/gitea-mmainguy.asc] https://git.dasfad.com/api/packages/mmainguy/debian bookworm main' \
-  | sudo tee /etc/apt/sources.list.d/gitea-mmainguy.list
-sudo apt update && sudo apt install cloudflared-tunnel
-
-sudo cloudflared-tunnel-setup --hostname app.example.com --port 3000
-#   or: --token <TUNNEL_TOKEN>    or: --quick
-```
-
-Installing the package doesn't start a tunnel. `cloudflared-tunnel-setup` does
-that, and it's safe to re-run to change the mode or port.
-
-If the Gitea owner is private, apt needs credentials. Keep them out of the
-world-readable sources file:
-
-```bash
-printf 'machine git.dasfad.com\nlogin mmainguy\npassword <read-only token>\n' \
-  | sudo install -m 0600 /dev/stdin /etc/apt/auth.conf.d/gitea.conf
-```
+See [Adding the Gitea repo to a Debian machine](#adding-the-gitea-repo-to-a-debian-machine)
+below for the client side.
 
 ### 5. Release an update
 
@@ -92,6 +73,112 @@ echo 1.0.1 > VERSION    # must change every release; Gitea won't overwrite a ver
 Machines pick it up with `apt upgrade`. If the tunnel is running, the upgrade
 restarts it.
 
+## Adding the Gitea repo to a Debian machine
+
+Do this once per machine that should install `cloudflared-tunnel` from Gitea.
+It works on Debian 11/12/13 and on Ubuntu. Substitute your own URL, owner and
+distribution wherever the examples say `git.dasfad.com`, `mmainguy` and
+`bookworm` — they must match `GITEA_URL`, `GITEA_OWNER` and `DIST` from
+`publish.env`.
+
+### 1. Prerequisites
+
+```bash
+sudo apt update
+sudo apt install -y curl ca-certificates
+sudo install -d -m 0755 /etc/apt/keyrings
+```
+
+`/etc/apt/keyrings` already exists on Debian 12 and newer; creating it is
+harmless and keeps the steps the same on older releases.
+
+### 2. Fetch the repository signing key
+
+Gitea serves it from the registry itself:
+
+```bash
+sudo curl -fsSL https://git.dasfad.com/api/packages/mmainguy/debian/repository.key \
+  -o /etc/apt/keyrings/gitea-mmainguy.asc
+sudo chmod 0644 /etc/apt/keyrings/gitea-mmainguy.asc
+```
+
+Confirm you got a key and not an HTML error page:
+
+```bash
+head -1 /etc/apt/keyrings/gitea-mmainguy.asc   # -----BEGIN PGP PUBLIC KEY BLOCK-----
+```
+
+### 3. Add the apt source
+
+```bash
+echo 'deb [signed-by=/etc/apt/keyrings/gitea-mmainguy.asc] https://git.dasfad.com/api/packages/mmainguy/debian bookworm main' \
+  | sudo tee /etc/apt/sources.list.d/gitea-mmainguy.list
+```
+
+Or, if you prefer the deb822 format, write
+`/etc/apt/sources.list.d/gitea-mmainguy.sources` instead — use one file or the
+other, not both:
+
+```
+Types: deb
+URIs: https://git.dasfad.com/api/packages/mmainguy/debian
+Suites: bookworm
+Components: main
+Signed-By: /etc/apt/keyrings/gitea-mmainguy.asc
+```
+
+### 4. Credentials, if the Gitea owner is private
+
+A public owner needs nothing here. Otherwise give apt a token with
+**package: Read** scope, kept out of the world-readable sources file:
+
+```bash
+printf 'machine git.dasfad.com\nlogin mmainguy\npassword <read-only token>\n' \
+  | sudo install -m 0600 /dev/stdin /etc/apt/auth.conf.d/gitea.conf
+```
+
+### 5. Install
+
+```bash
+sudo apt update
+apt-cache policy cloudflared-tunnel        # the candidate should come from git.dasfad.com
+sudo apt install cloudflared-tunnel
+```
+
+The package depends on `cloudflared`. If you mirrored it
+(`./publish.sh --cloudflared`), that dependency resolves from this same repo and
+the machine needs no Cloudflare apt source at all. If you did not, add
+Cloudflare's own repo before installing.
+
+Installing does not start a tunnel — `cloudflared-tunnel-setup` does:
+
+```bash
+sudo cloudflared-tunnel-setup --hostname app.example.com --port 3000
+#   or: --token <TUNNEL_TOKEN>    or: --quick
+```
+
+Later releases arrive with `sudo apt update && sudo apt upgrade`.
+
+### Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| `NO_PUBKEY` or `the following signatures couldn't be verified` | key missing or `signed-by=` path wrong — redo step 2 |
+| `404 Not Found` fetching `Release` | wrong owner or suite; check with `curl https://git.dasfad.com/api/packages/mmainguy/debian/dists/bookworm/Release` |
+| `401 Unauthorized` | private owner; add `/etc/apt/auth.conf.d/gitea.conf` (step 4) |
+| `Unable to locate package cloudflared-tunnel` | `apt update` not run since adding the source, or nothing published yet |
+| `cloudflared` has no installation candidate | the mirror is missing — run `./publish.sh --cloudflared` |
+| Installs fine but no tunnel | expected; run `cloudflared-tunnel-setup` |
+
+### Removing the repo
+
+```bash
+sudo rm -f /etc/apt/sources.list.d/gitea-mmainguy.list \
+           /etc/apt/keyrings/gitea-mmainguy.asc \
+           /etc/apt/auth.conf.d/gitea.conf
+sudo apt update
+```
+
 ## Changes from `setup-cloudflared.sh`
 
 - **The tunnel service is now `cloudflared-tunnel.service`.** This avoids a