feat: update Snap metadata and installation docs #1674

Problem Statement

OpenShell has Snap packaging in the repo, but the user-facing Snap path is not complete. The current snapcraft.yaml has only a short Store description, the installation docs do not mention Snap, and install.sh does not prefer Snap on Linux systems where snapd is already available.

Maintainer discussion identified several Snap-specific gaps:

• Put basic usage instructions in the Snap description text in snapcraft.yaml so the Store page updates from the repo metadata.
• Verify whether the current Snap Store declaration allows the required connections for the current strict snap.
• Move Store-managed visual metadata into the repo, including a logo/icon under meta/gui/ when Snapcraft conventions allow it.
• Add a desktop launcher that can be searched from desktop environments and runs the OpenShell terminal UI, likely openshell term, through the platform terminal.
• Update the published installation docs at docs/about/installation.mdx with Snap instructions.
• Consider updating install.sh to install through Snap when snapd is available, while preserving native package fallbacks.

Proposed Design

Update the Snap packaging and docs as one user-facing installation path:

1. Update snapcraft.yaml description text with concise basic usage instructions for Snap users, including Docker snap setup, interface connection commands, gateway creation or verification commands, and links back to the docs.
2. Audit the current strict-confinement plugs and Store declaration behavior for docker, network, network-bind, log-observe, ssh-keys, system-observe, and any other required interface. Document which connections are automatic and which require manual snap connect commands.
3. Add repo-managed Snap GUI metadata under meta/gui/, including the OpenShell logo/icon. If appropriate, add a .desktop launcher that starts the OpenShell terminal UI in the default platform terminal so OpenShell is discoverable from Linux desktop search.
4. Update docs/about/installation.mdx with a Snap section covering install, required Docker setup/connections, gateway status checks, and when users should choose Snap versus native DEB/RPM packages.
5. Update install.sh so Linux systems with snapd available can use the Snap path by default, with clear fallback behavior for unsupported systems, version-pinned installs, or users who need native packages.
6. Coordinate with existing Snap packaging issues chore(build): Update snap packaging to use prebuilt binaries #1610 and chore: Remove the early hand-assmbled snap packing from deploy/snap #1611 so build assembly changes do not conflict with the metadata/docs work.

Alternatives Considered

Store-only metadata updates were considered, but keeping description and visual metadata in snapcraft.yaml/meta/gui/ makes Store updates reproducible and versioned with the package.

Leaving install.sh on DEB/RPM only was considered, but Snap can provide a simpler install path on snap-enabled Linux systems. Native packages should remain available as fallbacks and for distributions or workflows where Snap is not appropriate.

Splitting this into separate docs and packaging issues was considered. A single issue is useful because the Store description, interface guidance, desktop metadata, docs page, and installer selection all describe the same Snap installation experience.

Agent Investigation

• Loaded the create-github-issue skill and followed the repo feature-request format.
• Reviewed .github/ISSUE_TEMPLATE/feature_request.yml and confirmed feature requests require Problem Statement, Proposed Design, Alternatives Considered, and optional Agent Investigation.
• Reviewed snapcraft.yaml; it currently defines the openshell and gateway apps, strict confinement, and plugs including docker, network, network-bind, log-observe, ssh-keys, and system-observe, but the description is a short product summary.
• Reviewed docs/about/installation.mdx; it documents curl/native package installation, macOS Homebrew, Linux DEB/RPM packages, and Kubernetes, but not Snap.
• Searched for Snap references and found docs/reference/gateway-config.mdx mentions Snap gateway config path, but installation docs and install.sh do not currently expose Snap as an install path.
• Found related open issues chore(build): Update snap packaging to use prebuilt binaries #1610 and chore: Remove the early hand-assmbled snap packing from deploy/snap #1611 for Snap build assembly/removing old packaging. Those do not cover Store metadata, desktop integration, installation docs, or installer Snap preference.

Checklist

• I have reviewed existing issues and the architecture docs
• This is a design proposal, not a please build this request