diff --git a/deploy/snap/README.md b/deploy/snap/README.md
index 419aacaa4..2af7c5073 100644
--- a/deploy/snap/README.md
+++ b/deploy/snap/README.md
@@ -93,8 +93,14 @@ It also defines a system service with packaged Docker driver settings.
 - `openshell.gateway`
 
 The gateway service uses `refresh-mode: endure` so snap refreshes do not restart
-it while sandboxes are active. Restart the service manually when you are ready
-to move the gateway to the refreshed snap revision.
+it automatically. This avoids disconnecting active sandbox sessions, but means
+you must restart the gateway manually after a refresh to pick up the new revision:
+
+```shell
+sudo snap restart openshell.gateway
+```
+
+Note that restarting the gateway will interrupt active sandbox sessions.
 
 `openshell-sandbox` is staged next to `openshell-gateway` as the Docker
 supervisor binary. The gateway app starts through a small wrapper that sets
@@ -135,9 +141,10 @@ sudo snap connect openshell:ssh-keys
 
 The gateway uses Docker's default Unix socket location. The Docker snap exposes
 that socket through the connected `docker` interface, so no `DOCKER_HOST`
-override is required. The OpenShell snap still requires the Docker snap because
-it relies on the `docker:docker-daemon` slot; it does not work with Docker
-installed from a Debian package or Docker's upstream packages.
+override is required. The OpenShell snap requires the Docker snap because it
+relies on the `docker:docker-daemon` slot; it does not work with Docker
+installed from a Debian package or Docker's upstream packages. Support for
+system-installed Docker is coming in snapd 2.76.
 
 The service runs the gateway with Snap-specific environment defaults:
 
diff --git a/snapcraft.yaml b/snapcraft.yaml
index 136f1a78c..31b7d91a0 100644
--- a/snapcraft.yaml
+++ b/snapcraft.yaml
@@ -11,6 +11,38 @@ description: |
   policy-enforced egress routing, credential proxying, and privacy-aware
   LLM inference routing.
 
+  The OpenShell snap ships a CLI (`openshell`), a terminal UI
+  (`openshell.term`), and a managed gateway daemon (`openshell.gateway`).
+
+  **Setup instructions**
+
+    1. Install the Docker snap:
+
+         sudo snap install docker
+
+       Support for system-installed Docker is coming in snapd 2.76.
+
+    2. Connect the required interfaces and start the gateway:
+
+         sudo snap connect openshell:docker docker:docker-daemon
+         sudo snap connect openshell:log-observe
+         sudo snap connect openshell:system-observe
+         sudo snap connect openshell:ssh-keys
+         sudo snap start openshell.gateway
+
+    3. Verify the gateway and register it locally:
+
+         snap services openshell.gateway
+         openshell status
+         openshell gateway add http://127.0.0.1:17670 --local --name openshell-gateway
+
+    After a snap refresh, restart the gateway to pick up the new revision:
+
+         sudo snap restart openshell.gateway
+
+    Restarting the gateway will interrupt active sandbox sessions. The gateway
+    is not restarted automatically to avoid disconnecting running sandboxes.
+
 base: core24
 grade: stable
 confinement: strict