diff --git a/docs/about/installation.mdx b/docs/about/installation.mdx
index 256015947..3be2565b6 100644
--- a/docs/about/installation.mdx
+++ b/docs/about/installation.mdx
@@ -80,7 +80,7 @@ sudo loginctl enable-linger $USER
 Install the OpenShell snap from the Snap Store:
 
 ```shell
-sudo snap install openshell --classic
+sudo snap install openshell
 ```
 
 The snap defines two apps: the `openshell` CLI and the `openshell.gateway`
@@ -89,6 +89,12 @@ stores its database at `$SNAP_COMMON/gateway.db` (typically
 `/var/snap/openshell/common/gateway.db`). Create `$SNAP_COMMON/gateway.toml`
 when you need to override gateway settings.
 
+The snap CLI stores per-user config, data, and state under
+`$SNAP_USER_COMMON/xdg-*`, typically `~/snap/openshell/common/xdg-*`.
+Gateway registrations live under
+`$SNAP_USER_COMMON/xdg-config/openshell/gateways/` instead of
+`~/.config/openshell/gateways/`.
+
 ### Snap store installs
 
 When installing from the Snap Store, snapd automatically connects the `home`,
@@ -108,7 +114,7 @@ manually.
 When installing a locally built `.snap` file, no plugs are connected by default:
 
 ```shell
-sudo snap install ./openshell_*.snap --dangerous --classic
+sudo snap install ./openshell_*.snap --dangerous
 sudo snap connect openshell:home
 sudo snap connect openshell:network
 sudo snap connect openshell:network-bind
diff --git a/snapcraft.yaml b/snapcraft.yaml
index 01d90366e..151cb37bb 100644
--- a/snapcraft.yaml
+++ b/snapcraft.yaml
@@ -62,6 +62,10 @@ platforms:
 apps:
   openshell:
     command: bin/openshell
+    environment:
+      XDG_CONFIG_HOME: "$SNAP_USER_COMMON/xdg-config"
+      XDG_DATA_HOME: "$SNAP_USER_COMMON/xdg-data"
+      XDG_STATE_HOME: "$SNAP_USER_COMMON/xdg-state"
     plugs:
       - home
       - network
@@ -70,6 +74,10 @@ apps:
   term:
     command: bin/openshell term
     desktop: meta/gui/term.desktop
+    environment:
+      XDG_CONFIG_HOME: "$SNAP_USER_COMMON/xdg-config"
+      XDG_DATA_HOME: "$SNAP_USER_COMMON/xdg-data"
+      XDG_STATE_HOME: "$SNAP_USER_COMMON/xdg-state"
     plugs:
       - home
       - network
diff --git a/tasks/scripts/test-packaging-assets.sh b/tasks/scripts/test-packaging-assets.sh
index a03f60559..140d7777e 100755
--- a/tasks/scripts/test-packaging-assets.sh
+++ b/tasks/scripts/test-packaging-assets.sh
@@ -28,6 +28,21 @@ assert_not_contains() {
   fi
 }
 
+assert_occurrences() {
+  local file=$1
+  local expected=$2
+  local count=$3
+  local actual
+
+  actual=$(grep -F "$expected" "$file" | wc -l | tr -d '[:space:]')
+  if [[ "$actual" != "$count" ]]; then
+    echo "FAIL: ${file} expected ${count} occurrences of:" >&2
+    echo "  ${expected}" >&2
+    echo "found ${actual}" >&2
+    exit 1
+  fi
+}
+
 assert_file_exists() {
   local file=$1
 
@@ -39,9 +54,11 @@ assert_file_exists() {
 
 service="${ROOT}/deploy/deb/openshell-gateway.service"
 spec="${ROOT}/openshell.spec"
+snapcraft="${ROOT}/snapcraft.yaml"
 
 assert_file_exists "$service"
 assert_file_exists "$spec"
+assert_file_exists "$snapcraft"
 
 assert_contains \
   "$service" \
@@ -59,4 +76,9 @@ assert_contains \
   'ExecStartPre=/usr/bin/openshell-gateway generate-certs --output-dir ${OPENSHELL_LOCAL_TLS_DIR} --server-san host.openshell.internal'
 assert_not_contains "$spec" '%%S/openshell/tls'
 
+assert_contains "$snapcraft" 'confinement: strict'
+assert_occurrences "$snapcraft" 'XDG_CONFIG_HOME: "$SNAP_USER_COMMON/xdg-config"' 2
+assert_occurrences "$snapcraft" 'XDG_DATA_HOME: "$SNAP_USER_COMMON/xdg-data"' 2
+assert_occurrences "$snapcraft" 'XDG_STATE_HOME: "$SNAP_USER_COMMON/xdg-state"' 2
+
 echo "packaging asset tests passed"