docs: add connectivity guide

README.md

@@ -80,6 +80,7 @@ Paseo starts locally, then asks whether to enable the end-to-end encrypted relay
 For full setup and configuration, see:
 
 - [Docs](https://paseo.sh/docs)
+- [Connectivity guide](https://paseo.sh/docs/connectivity)
 - [Configuration reference](https://paseo.sh/docs/configuration)
 
 ### Docker

packages/website/src/styles.css

@@ -307,9 +307,11 @@
 
 .docs-prose h2 {
   color: var(--color-foreground);
-  font-size: 1.25rem;
+  font-size: 1.375rem;
   line-height: 1.4;
   font-weight: 500;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid var(--color-border);
   margin-top: 2rem;
   margin-bottom: 1rem;
 }

public-docs/configuration.md

@@ -189,7 +189,7 @@ In the mobile app, enter the password in the direct connection setup screen.
 
 ## Relay
 
-New homes write `daemon.relay.enabled: false`. Paseo asks before enabling relay when you pair a device; existing homes keep their saved value. See [Security](/docs/security) for relay encryption and direct connection alternatives.
+New homes write `daemon.relay.enabled: false`. Paseo asks before enabling relay when you pair a device; existing homes keep their saved value. See [Connectivity](/docs/connectivity) to choose and configure a connection method, and [Security](/docs/security) for the relay encryption model.
 
 Set the persisted value in `config.json`:
 

public-docs/connectivity.md

@@ -0,0 +1,92 @@
+---
+title: Connectivity
+description: Connect a Paseo client to your daemon through the relay or Tailscale.
+nav: Connectivity
+order: 4
+category: Getting started
+---
+
+# Connectivity
+
+Your Paseo app connects to the daemon running on your computer or server. You can connect through the Paseo relay or directly with Tailscale.
+
+- [Paseo relay](#paseo-relay)
+- [Tailscale](#tailscale)
+
+## Paseo relay
+
+The relay works without Tailscale, port forwarding, or network configuration. Traffic is end-to-end encrypted.
+
+Relay is disabled until you enable it.
+
+### Enable relay from Paseo Desktop
+
+1. Open **Settings → your host → Pair a device**.
+2. Select **Enable relay**.
+3. Scan the QR code with Paseo on your phone, or copy the pairing link and paste it into the phone app.
+
+### Enable relay from the CLI
+
+Run:
+
+```bash
+paseo daemon pair
+```
+
+Confirm when prompted. Paseo prints a QR code and pairing link. Scan the QR code with Paseo on your phone, or choose **Paste pairing link** in the phone app.
+
+## Tailscale
+
+Install [Tailscale](https://tailscale.com/download) on the daemon machine and your phone. Sign in to the same tailnet on both devices.
+
+### 1. Find the daemon machine's Tailscale IP
+
+Run this on the daemon machine:
+
+```bash
+tailscale ip -4
+```
+
+Copy the address it prints. The example below uses `100.101.102.103`.
+
+### 2. Configure the daemon
+
+Open `~/.paseo/config.json` and set `daemon.listen` to the Tailscale IP:
+
+```json
+{
+  "$schema": "https://paseo.sh/schemas/paseo.config.v1.json",
+  "version": 1,
+  "daemon": {
+    "listen": "100.101.102.103:6767"
+  }
+}
+```
+
+Keep the other settings already in the file. If it has a `daemon` object, add `listen` inside that object.
+
+To restrict access with a password, see [Password authentication](/docs/configuration#password-authentication).
+
+Restart the daemon:
+
+```bash
+paseo daemon restart
+```
+
+If Paseo Desktop manages the daemon, use **Settings → your host → Overview → Restart daemon**.
+
+### 3. Connect the phone app
+
+1. Connect Tailscale on your phone.
+2. Open Paseo and go to **Settings → Add host → Direct connection**.
+3. Enter the Tailscale IP in **Host**.
+4. Enter `6767` in **Port**.
+5. Leave **Use SSL** off and select **Connect**.
+
+If the host was already paired through the relay, Paseo adds the direct connection to the same host.
+
+## Troubleshooting
+
+- **Connection timed out:** Check that Tailscale is connected on both devices and that you used the daemon machine's Tailscale IP.
+- **Connection refused:** Run `paseo daemon status` and confirm the daemon is running on the configured IP and port.
+- **Config change has no effect:** Restart the daemon after editing `config.json`.

public-docs/index.md

@@ -50,6 +50,7 @@ The image runs the daemon and serves the bundled web UI. It does not bundle agen
 
 ## Where next
 
+- [Connectivity](/docs/connectivity), connect through the relay or Tailscale.
 - [Docker](/docs/docker), run the daemon and bundled web UI in a container.
 - [Workspaces](/docs/workspaces), the project, workspace, and session model Paseo is built around.
 - [Providers](/docs/providers), what a provider is and how Paseo wraps existing CLIs.

public-docs/security.md

@@ -2,7 +2,7 @@
 title: Security
 description: "Security model for Paseo: architecture overview, connection methods, relay encryption, and best practices."
 nav: Security
-order: 4
+order: 5
 category: Getting started
 ---
 
@@ -58,20 +58,15 @@ If you believe a pairing offer has been compromised, restart the daemon to gener
 
 By default, the daemon listens on `127.0.0.1:6767` (localhost only). This is safe for local CLI usage but not reachable from your phone or other devices.
 
+For relay and Tailscale setup instructions, see [Connectivity](/docs/connectivity).
+
 ### Socket file (CLI only)
 
 For maximum isolation, you can configure the daemon to listen on a Unix socket file instead of a TCP port. This prevents any network access entirely, only processes on the same machine can connect. The CLI supports this mode, but the mobile app and web interface require a network connection.
 
 ### VPN access
 
-If you prefer direct connections over the relay, you can use a VPN like [Tailscale](https://tailscale.com). Tailscale creates a private network between your devices, so you can access your daemon without exposing it to the public internet.
+Use a VPN such as [Tailscale](https://tailscale.com) when you want a direct connection outside your local network. The VPN encrypts the traffic and keeps the daemon off the public internet. Bind the daemon to its VPN address, set a Paseo password, then add that address as a direct connection in the client.
-
-To set this up:
-
-1. Install Tailscale on your machine and phone and join them to the same [tailnet](https://tailscale.com/kb/1136/tailnet)
-2. Configure the daemon to listen on your Tailscale IP (e.g., `100.x.y.z:6767`)
-3. Add your Tailscale hostname to `hostnames` and `cors.allowedOrigins`
-4. Add the daemon as a direct connection in the Paseo app using the Tailscale address
 
 ### Binding to 0.0.0.0
 

public-docs/web-ui.md

@@ -63,7 +63,7 @@ The same HTTP server keeps serving the API (`/api/*`), MCP (`/mcp/*`), service-p
 Three common ways to run it, in order of exposure:
 
 - **Same machine.** Daemon and browser on one box. Open `http://localhost:6767/`. Nothing else to configure.
-- **Private network (LAN or VPN).** Reach the daemon from other devices on a network you trust, a home LAN or a [Tailscale](https://tailscale.com) tailnet. Bind the daemon to that interface and connect to it by address.
+- **Private network (LAN or VPN).** Reach the daemon from other devices on a network you trust, a home LAN or a [Tailscale](https://tailscale.com) tailnet. Follow the [Connectivity guide](/docs/connectivity#tailscale) for the complete direct setup.
 - **Public reverse proxy or tunnel.** Expose the UI on a domain over HTTPS, terminating TLS at a reverse proxy or a tunnel. This is the full self-hosted setup.
 
 The rest of this page builds from local to public. **Verify a direct connection works before you add a proxy in front of it**, it isolates daemon problems from proxy problems.