docs: add tailscale private access guide

docs/deploy/local-development.md

@@ -48,12 +48,20 @@ pnpm dev --tailscale-auth
 
 This binds the server to `0.0.0.0` for private-network access.
 
+Alias:
+
+```sh
+pnpm dev --authenticated-private
+```
+
 Allow additional private hostnames:
 
 ```sh
 pnpm paperclipai allowed-hostname dotta-macbook-pro
 ```
 
+For full setup and troubleshooting, see [Tailscale Private Access](/deploy/tailscale-private-access).
+
 ## Health Checks
 
 ```sh

docs/deploy/tailscale-private-access.md

@@ -0,0 +1,77 @@
+---
+title: Tailscale Private Access
+summary: Run Paperclip with Tailscale-friendly host binding and connect from other devices
+---
+
+Use this when you want to access Paperclip over Tailscale (or a private LAN/VPN) instead of only `localhost`.
+
+## 1. Start Paperclip in private authenticated mode
+
+```sh
+pnpm dev --tailscale-auth
+```
+
+This configures:
+
+- `PAPERCLIP_DEPLOYMENT_MODE=authenticated`
+- `PAPERCLIP_DEPLOYMENT_EXPOSURE=private`
+- `PAPERCLIP_AUTH_BASE_URL_MODE=auto`
+- `HOST=0.0.0.0` (bind on all interfaces)
+
+Equivalent flag:
+
+```sh
+pnpm dev --authenticated-private
+```
+
+## 2. Find your reachable Tailscale address
+
+From the machine running Paperclip:
+
+```sh
+tailscale ip -4
+```
+
+You can also use your Tailscale MagicDNS hostname (for example `my-macbook.tailnet.ts.net`).
+
+## 3. Open Paperclip from another device
+
+Use the Tailscale IP or MagicDNS host with the Paperclip port:
+
+```txt
+http://<tailscale-host-or-ip>:3100
+```
+
+Example:
+
+```txt
+http://my-macbook.tailnet.ts.net:3100
+```
+
+## 4. Allow custom private hostnames when needed
+
+If you access Paperclip with a custom private hostname, add it to the allowlist:
+
+```sh
+pnpm paperclipai allowed-hostname my-macbook.tailnet.ts.net
+```
+
+## 5. Verify the server is reachable
+
+From a remote Tailscale-connected device:
+
+```sh
+curl http://<tailscale-host-or-ip>:3100/api/health
+```
+
+Expected result:
+
+```json
+{"status":"ok"}
+```
+
+## Troubleshooting
+
+- Login or redirect errors on a private hostname: add it with `paperclipai allowed-hostname`.
+- App only works on `localhost`: make sure you started with `--tailscale-auth` (or set `HOST=0.0.0.0` in private mode).
+- Can connect locally but not remotely: verify both devices are on the same Tailscale network and port `3100` is reachable.

docs/docs.json

@@ -73,6 +73,7 @@
             "pages": [
               "deploy/overview",
               "deploy/local-development",
+              "deploy/tailscale-private-access",
               "deploy/docker",
               "deploy/deployment-modes",
               "deploy/database",