fix(snap): isolate CLI XDG paths from host environment

The Ubuntu Snap release canary is failing because GitHub-hosted runners set
`XDG_CONFIG_HOME=/home/runner/.config`, and the strict OpenShell snap currently
honors that host path. As a result, `openshell gateway add` tries to persist
gateway metadata under `/home/runner/.config/openshell/...` instead of the
snap-owned user directory, and strict snap confinement blocks the write.

The snap should set its user-facing app XDG paths explicitly to snap-owned
locations under `$SNAP_USER_COMMON`, so host-defined `XDG_*` variables cannot
redirect CLI or TUI state outside the snap sandbox.

The docs update also removes stale `--classic` Snap install examples, since the
OpenShell snap is strict-confined rather than classic-confined.

Signed-off-by: Kris Hicks <khicks@nvidia.com>

Author: krishicks

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

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

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"