diff --git a/docs/about/installation.mdx b/docs/about/installation.mdx
index 256015947..87c8a8363 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,11 @@ 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`,
+typically `~/snap/openshell/common`. Gateway registrations live under
+`$SNAP_USER_COMMON/.config/openshell/gateways/` instead of
+`~/.config/openshell/gateways/`.
+
 ### Snap store installs
 
 When installing from the Snap Store, snapd automatically connects the `home`,
@@ -108,7 +113,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..f7354aa01 100644
--- a/snapcraft.yaml
+++ b/snapcraft.yaml
@@ -62,6 +62,10 @@ platforms:
 apps:
   openshell:
     command: bin/openshell
+    environment:
+      XDG_CONFIG_HOME: "$SNAP_USER_COMMON/.config"
+      XDG_DATA_HOME: "$SNAP_USER_COMMON/.local/share"
+      XDG_STATE_HOME: "$SNAP_USER_COMMON/.local/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/.config"
+      XDG_DATA_HOME: "$SNAP_USER_COMMON/.local/share"
+      XDG_STATE_HOME: "$SNAP_USER_COMMON/.local/state"
     plugs:
       - home
       - network