From 5211edf26469e4031b98bb9a034e5786f4ba746b Mon Sep 17 00:00:00 2001
From: John O'Keefe <git@linuxhg.com>
Date: Mon, 2 Nov 2026 16:11:31 -0500
Subject: [PATCH] docs(user): pairing-code flow for device setup guides
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The setup guides walked the retired broadcast-list approve ("your device
appears under Pending Device Registrations — click Approve"), which no
longer exists. Both now describe the pairing-code flow: the e-reader
displays a 6-digit code, you type it into Pair a Device on your own
account, and only whoever holds the device can read the code — the
family-server gap that motivated the change. Adds a Pairing Code Not
Accepted troubleshooting case, refreshes the security practices
(claim only codes you can see on a device you are holding), and aligns
the remaining approval/pending wording throughout.
---
 docs/user/devices/koreader-setup.md | 63 +++++++++++++++++++----------
 docs/user/sync-guide.md             | 17 +++++---
 2 files changed, 52 insertions(+), 28 deletions(-)

diff --git a/docs/user/devices/koreader-setup.md b/docs/user/devices/koreader-setup.md
index 9eb8afde..28065928 100644
--- a/docs/user/devices/koreader-setup.md
+++ b/docs/user/devices/koreader-setup.md
@@ -1,4 +1,4 @@
-<!-- Ground truth: bookhoard.koplugin main.lua (menu tree, defaults, approval
+<!-- Ground truth: bookhoard.koplugin main.lua (menu tree, defaults, pairing
      flow) + the server-side koreader endpoints. Re-verify against the plugin
      source when the plugin changes. KOReader ITSELF is out of scope: this
      guide supports the plugin only, and installation is delegated to the
@@ -31,7 +31,7 @@ It also runs on Android tablets and phones — though on Android the dedicated
 Before you begin, make sure you have:
 
 - ✅ A Bookhoard instance running and accessible on your network
-- ✅ A web browser logged in to your Bookhoard account (for device approval)
+- ✅ A web browser logged in to your Bookhoard account (to enter the pairing code)
 - ✅ KOReader installed and running on your e-reader (see next section)
 - ✅ Your device connected to the same Wi-Fi network as your Bookhoard instance
 
@@ -55,8 +55,9 @@ whatever device you're on.
 
 ## Connecting KOReader to Bookhoard
 
-Setup is done **on the server**: you approve the device from the Bookhoard
-web interface — no usernames, passwords, or tokens to type on the device.
+Setup is done **on the server**: your e-reader shows a pairing code, and you
+type it into your own account's Devices page — no usernames, passwords, or
+tokens to type on the device.
 
 ### Step 1: Install the Bookhoard Plugin
 
@@ -88,23 +89,27 @@ Then restart KOReader.
 ### Step 3: Register the Device
 
 1. In the same **Bookhoard sync** menu, tap **Register device**
-2. On your computer or phone, open Bookhoard and go to the **Devices** page
-   (sidebar navigation)
-3. Your device appears under **Pending Device Registrations** — click
-   **Approve** to connect it
+2. Your e-reader displays a **6-digit pairing code**
+3. On your computer or phone, open Bookhoard — logged into **your** account —
+   and go to the **Devices** page (sidebar navigation)
+4. Type the code into the **Pair a Device** field and click **Find device**,
+   then confirm on the card that appears
 
-The plugin waits on the device and finishes by itself the moment you
-approve. Once approved, its credentials are stored automatically, sync
-events are armed, and Bookhoard's OPDS catalog is added to your KOReader —
-no further configuration is needed.
+The code is the only way to claim the registration, and only someone holding
+the device can read it — so the device always lands in the account of the
+person who registered it. The plugin waits on the device and finishes by
+itself the moment you confirm. Once paired, its credentials are stored
+automatically, sync events are armed, and Bookhoard's OPDS catalog is added to
+your KOReader — no further configuration is needed.
 
-> **Note:** Pending registrations expire after 5 minutes. If yours expires
-> ("Registration expired"), just tap **Register device** again and approve.
+> **Note:** Pairing codes expire after 5 minutes. If yours expires
+> ("Registration expired"), just tap **Register device** again for a fresh
+> one. Dismissing the waiting dialog on the device cancels the attempt.
 
 ### Auth Token (Advanced)
 
 The Devices page shows each KOReader device's **Auth Token**. You normally
-never need it (the plugin receives it automatically during approval), but it
+never need it (the plugin receives it automatically during pairing), but it
 can be re-entered manually in the plugin settings if you're moving a setup
 between devices or debugging.
 
@@ -116,7 +121,7 @@ sync**. The menu changes shape depending on whether you are connected.
 ### Before you're connected
 
 - **Server URL** — your server's address
-- **Register device** — starts the approval flow above
+- **Register device** — starts the pairing flow above
 
 ### Once connected — one-tap actions
 
@@ -132,7 +137,7 @@ sync**. The menu changes shape depending on whether you are connected.
 ### Automatically push progress
 
 This toggle is the on/off switch for background sync — **it starts off**, so
-after approval, turn it on to get automatic syncing. With it on, progress
+after pairing, turn it on to get automatic syncing. With it on, progress
 pushes as you read and on close/suspend; the plugin may prompt about turning
 Wi-Fi on at those moments depending on your device.
 
@@ -216,14 +221,26 @@ their progress syncs from the first page.
 
 ### Pending Registration Never Appears
 
-**Problem**: You entered the Server URL, but no pending registration shows in Bookhoard
+**Problem**: You entered the Server URL, but no pairing code shows on the device
 
 **Solutions**:
 
 1. Verify the Server URL is correct (no trailing path — just the base address)
 2. Make sure KOReader is connected to Wi-Fi
 3. Check the Bookhoard server is reachable from the device's network
-4. Registrations expire after 5 minutes — tap **Register device** again and approve quickly
+4. Registrations expire after 5 minutes — tap **Register device** again
+
+### Pairing Code Not Accepted
+
+**Problem**: The Devices page says "No waiting device matches that code"
+
+**Solutions**:
+
+1. Re-read the code on the device — it refreshes on every **Register device** tap
+2. Check you typed all 6 digits (spacing doesn't matter)
+3. Codes expire after 5 minutes — register again on the device and type the new code
+4. "Pairing code already used" means the device already paired (check the device list); otherwise register again
+5. Too many attempts lock new tries for a minute — wait and retry
 
 ### Connection Refused
 
@@ -236,9 +253,9 @@ their progress syncs from the first page.
 - Ensure the device is on the same Wi-Fi network as the server
 - Use the server's LAN IP instead of `localhost`
 
-### Sync Not Working After Approval
+### Sync Not Working After Pairing
 
-**Problem**: Device shows as approved but changes don't appear in Bookhoard
+**Problem**: Device shows as paired but changes don't appear in Bookhoard
 
 **Solutions**:
 
@@ -271,7 +288,9 @@ For day-to-day control of the same question on the device itself, use the
 
 1. **Use HTTPS**: If exposing Bookhoard beyond your LAN, configure SSL/TLS
 2. **Network Security**: Ensure your Wi-Fi network is secure (WPA2/WPA3)
-3. **Device Authorization**: Only approve pending registrations you initiated
+3. **Claim only codes you can see**: a pairing code is readable only on the
+   registering device's screen — never claim a code someone merely told you
+   if you can't see the device showing it
 4. **Revoke lost devices**: Remove devices you no longer use from the Devices page
 
 ## Additional Resources
diff --git a/docs/user/sync-guide.md b/docs/user/sync-guide.md
index 9566a4eb..caff519c 100644
--- a/docs/user/sync-guide.md
+++ b/docs/user/sync-guide.md
@@ -17,9 +17,14 @@ notes — and every registered device pushes and pulls against it.
 ## Getting a device into the circle
 
 1. Connect the device to your server (each guide above walks its own path)
-2. Approve the pending registration on the **Devices** page — the Android
-   app registers itself on first login; KOReader asks from its plugin
-3. Done. Sync starts as soon as a device is approved
+2. Pair it on the **Devices** page — the Android app registers itself on
+   first login; KOReader shows a 6-digit pairing code that you type into
+   **Pair a Device** on the page
+3. Done. Sync starts as soon as a device is paired
+
+Only the person holding the device can read its pairing code, so a device
+always lands in the account of whoever registered it — even on a family
+server where more than one person is logged in.
 
 The **Devices** page is mission control: see every registered device and
 when it was last seen, remove a device (revoking its access instantly), and
@@ -61,7 +66,7 @@ phone lands in the right place on an e-reader with different pagination.
 **Bookmarks** — location, title, and when you made them.
 
 Everything above is per-user and private: your devices see your data
-because you approved them, other users see theirs, and revoking a device
+because you paired them, other users see theirs, and revoking a device
 ends its access on the spot.
 
 ## Conflicts
@@ -98,13 +103,13 @@ alone.
 ## Troubleshooting
 
 **Progress not updating**
-Check the device is still on the **Devices** page and was approved; check
+Check the device is still on the **Devices** page and was paired; check
 the server URL in the device's settings; confirm the device can reach the
 server (open the server URL in the device's browser as a test).
 
 **"Device not found"**
 The device was removed or its token revoked — register it again and
-approve it.
+enter the fresh pairing code.
 
 **A conflict keeps coming back**
 Two devices are genuinely fighting over the same book. Decide which device