implement real gateway path.

docs/desktop-client.md

@@ -0,0 +1,78 @@
+# Desktop Client
+
+It can:
+
+- Check whether Linux TUN support exists.
+- Find `adb`.
+- Check whether the Android VPN Share app is installed.
+- Check whether the Android gateway foreground service is running.
+- Bring the Android app to the foreground.
+- Start the Android gateway and create `adb forward tcp:10808 tcp:10808`.
+- Provide a local `socks5h://127.0.0.1:10808` proxy endpoint.
+- On Linux, create a `vpnshare0` TUN device and route OS traffic through the
+  phone using `tun2socks`.
+- Forward DNS/UDP through the Android gateway using SOCKS5 UDP-over-TCP.
+
+It cannot yet pair with the phone over VSHP or provide native Windows/macOS TUN
+drivers.
+
+## Build
+
+```bash
+cargo build -p vpnshare-desktop
+```
+
+## Run
+
+```bash
+./target/debug/vpnshare-desktop status
+./target/debug/vpnshare-desktop connect
+sudo ./target/debug/vpnshare-desktop system-gateway
+./target/debug/vpnshare-desktop android-launch
+```
+
+If `adb` is not on `PATH`, point the CLI to it:
+
+```bash
+VPN_SHARE_ADB=/path/to/adb ./target/debug/vpnshare-desktop status
+```
+
+After `connect`, use the local SOCKS5 proxy with apps that support SOCKS:
+
+```bash
+ALL_PROXY=socks5h://127.0.0.1:10808 curl https://ifconfig.me
+chromium --proxy-server=socks5h://127.0.0.1:10808
+```
+
+The `socks5h` form is important because DNS names are resolved through the
+phone-side gateway instead of the desktop.
+
+## Linux System Gateway
+
+For normal OS/app routing on Linux:
+
+1. Connect the phone with USB debugging enabled.
+2. Start the Android VPN app you want to share.
+3. Run `./target/debug/vpnshare-desktop connect`.
+4. Run `sudo ./target/debug/vpnshare-desktop system-gateway`.
+5. Keep the `system-gateway` process open while sharing.
+
+`system-gateway` creates `vpnshare0`, starts `tun2socks`, installs split-default
+routes (`0.0.0.0/1` and `128.0.0.0/1`), and configures systemd-resolved DNS on
+`vpnshare0` when `resolvectl` is available.
+
+Cleanup command:
+
+```bash
+sudo ./target/debug/vpnshare-desktop cleanup
+```
+
+## Next Implementation Step
+
+The next milestone is replacing the interim SOCKS transport with the full VSHP
+packet tunnel:
+
+1. Connect to the Android gateway over USB/WiFi/hotspot transports.
+2. Pair using VSHP.
+3. Encrypt IP packet frames end to end.
+4. Add Windows/macOS packet adapters.