docs(user): Android app guide — LAN setup and the Android 16+ local-network permission

Android 16+ gates per-app access to local networks behind a runtime
permission; without it the app's LAN logins time out with zero packets
leaving the phone (browser works — it is not per-app-gated). The new
device guide covers the sideload install, first-run server URL, the
permission prompt (and manual re-grant path), and a triage table for
the login screen's error line. Per the user: overlay-VPN addresses are
not a consideration and stay undocumented.

docs/user/devices/android-app.md

@@ -0,0 +1,43 @@
+# Android App Setup Guide
+
+The Bookhoard Android app is the native mobile client: browse your libraries, read EPUBs, PDFs, comics and manga, and sync progress, highlights, bookmarks and notes with the server.
+
+## Prerequisites
+
+- ✅ A Bookhoard instance running and reachable from your phone's network
+- ✅ The Bookhoard APK installed on your phone (Android 8.0+ / API 26+)
+- ✅ Your phone connected to the same network as the server (for a self-hosted LAN setup)
+
+## Installing the app
+
+The app is distributed as a sideloaded APK:
+
+1. Copy the APK to your phone (USB, or any file-sync you trust)
+2. Tap the APK to install — approve the "install unknown apps" prompt for the app you installed from (file manager, browser, etc.)
+3. Upgrades install straight over the existing app and keep your data (login, downloads, reading state)
+
+## First run
+
+1. **Server URL** — enter your server's address. For a self-hosted LAN setup that is `http://<desktop-LAN-IP>:8765` (plain HTTP is expected here and fully supported; check the server machine's firewall allows port 8765 from your LAN)
+2. **Log in** with your Bookhoard account
+3. **Device registration** happens automatically — the app registers itself as a synced device so progress and annotations sync under your account
+
+## Android 16+: the local-network permission
+
+On Android 16 and newer, apps need explicit permission to talk to devices on your local network (and to non-HTTPS local addresses in general). **If the permission is missing, the app's logins to a LAN server time out with no visible cause** — the phone silently drops the traffic.
+
+- The app **asks for the permission by itself** during setup, as soon as you enter a local server address — grant it when prompted
+- If it was denied (or you missed the prompt): **Settings → Apps → Bookhoard → Permissions → "Access local network devices" → Allow**, then try again
+- Servers reached over the public internet (HTTPS) are not affected by this permission
+
+## Troubleshooting login failures
+
+The login screen prints the underlying error after "Could not reach server: …" — read it to narrow the cause:
+
+| Error | Meaning | What to check |
+|---|---|---|
+| `SocketTimeoutException` | The phone sent nothing that reached the server | On Android 16+ this is most often the **local-network permission** (above). Otherwise: wrong IP, phone on a different network/VLAN, or server down |
+| `ConnectException` (connection refused/blocked) | The phone reached the machine but nothing answered | Server container down, or a firewall rejecting port 8765 |
+| `UnknownHostException` | The hostname didn't resolve | Typo in the server URL, or a DNS/name issue (raw IPs avoid this) |
+
+To verify the server is reachable from the phone at all, open the same URL in the phone's browser — the browser is not subject to the per-app local-network permission, so if the browser works but the app times out on Android 16+, it is the permission.

docs/user/user-guide.md

@@ -6,6 +6,12 @@ Welcome to the Bookhoard user documentation. This section contains guides for us
 
 Learn how to configure your e-reader devices to sync with Bookhoard:
 
+- **[Android App Guide](devices/android-app.md)** - The native Android client
+  - Installing and upgrading the APK
+  - Connecting to a self-hosted server over LAN
+  - The Android 16+ local-network permission
+  - Troubleshooting login failures
+
 - **[KOReader Setup Guide](devices/koreader-setup.md)** - Complete guide for KOReader
   - Installation on Kindle/Kobo/PocketBook
   - Plugin setup with server-side device approval