From 94902949e1f4d8475e80550a88a345cc8df63e9e Mon Sep 17 00:00:00 2001 From: arios4k Date: Sun, 15 Nov 2026 10:12:12 -0800 Subject: [PATCH] Docs: a Snap Store version page, and clearer snap notes in Install and READMEs Documentation only, no app changes and no release. - New manual page "Snap Store version": why there is a snap (visibility), which version to choose, what works in each of the 18 tools, the permissions to connect and what each is for, what works only with apt or Fedora and why (a limitation of snaps, not of Voltkit), how the app shows it, installing only one version and switching between them without losing settings, updates and removal, and troubleshooting. - Install: links to it, says most of Voltkit works in the snap, lists what is left out, and tells you to remove the other version first. - FAQ and Troubleshooting: entries for the snap and for having two copies. - READMEs (five languages): why a snap, most features work, and removing the other version first. Co-Authored-By: Claude Opus 5.5 --- README.de.md | 8 + README.es.md | 8 + README.fr.md | 8 + README.md | 8 + README.zh-CN.md | 8 + docs/manual/pages/_order.txt | 1 + docs/manual/pages/faq.md | 6 +- docs/manual/pages/install.md | 41 +++-- docs/manual/pages/snap.md | 223 +++++++++++++++++++++++++++ docs/manual/pages/troubleshooting.md | 2 + 10 files changed, 298 insertions(+), 15 deletions(-) create mode 100644 docs/manual/pages/snap.md diff --git a/README.de.md b/README.de.md index 9bd4839..f4376bf 100644 --- a/README.de.md +++ b/README.de.md @@ -93,6 +93,8 @@ echo "deb [signed-by=/usr/share/keyrings/voltkit-archive-keyring.gpg] https://ar sudo apt update && sudo apt install voltkit ``` +**Vorher den Snap installiert?** Entfernen Sie ihn zuerst (`sudo snap remove voltkit`), sonst ist Voltkit doppelt installiert, und zwei Hintergrunddienste streiten um dieselben Tastenkürzel. + apt installiert die benötigten Werkzeuge (Tesseract, wl-clipboard, das Desktop-Portal) zusammen mit Voltkit, und Aktualisierungen kommen mit `sudo apt upgrade`. @@ -107,15 +109,21 @@ sudo dnf copr enable arios/voltkit sudo dnf install voltkit ``` +**Vorher den Snap installiert?** Entfernen Sie ihn zuerst (`sudo snap remove voltkit`), sonst ist Voltkit doppelt installiert, und zwei Hintergrunddienste streiten um dieselben Tastenkürzel. + Öffnen Sie Voltkit dann aus Ihren Apps; es richtet sich genauso ein. Aktualisierungen kommen mit `sudo dnf upgrade`. ## Installation (Snap Store) +Den Snap gibt es vor allem, damit man Voltkit findet: Der Snap Store ist auf jeder Linux-Distribution verfügbar, die Snaps unterstützt. Die meisten Funktionen arbeiten im Snap genauso; für die wenigen, die ein Snap nicht darf, installieren Sie mit apt oder Fedora. + ```bash sudo snap install voltkit ``` +**Vorher mit apt oder Fedora installiert?** Entfernen Sie diese Version zuerst (`sudo apt remove voltkit` oder `sudo dnf remove voltkit`), damit Voltkit nicht doppelt installiert ist. + Der Snap läuft in einer Sandbox. Deshalb funktionieren GPU-Tuning, Hosts & Umgebung, App-Berechtigungen, Kürzel beim Tippen und einige weitere Funktionen nur mit apt oder Fedora, und manche Werkzeuge brauchen eine Berechtigung, die einmal mit `sudo snap connect` verbunden wird. Jede betroffene Seite weist darauf hin; die Befehle stehen unter [Nach der Installation des Snaps](https://arios4k.github.io/voltkit/manual/install.html#snap-store) (auf Englisch). ## Installation (aus dem Quellcode) diff --git a/README.es.md b/README.es.md index b9fb242..2a945b3 100644 --- a/README.es.md +++ b/README.es.md @@ -92,6 +92,8 @@ echo "deb [signed-by=/usr/share/keyrings/voltkit-archive-keyring.gpg] https://ar sudo apt update && sudo apt install voltkit ``` +**¿Instalaste el snap antes?** Quítalo primero (`sudo snap remove voltkit`), o Voltkit quedará instalado dos veces, con dos servicios en segundo plano compitiendo por los mismos atajos. + apt instala las herramientas necesarias (Tesseract, wl-clipboard, el portal del escritorio) junto con Voltkit, y las actualizaciones llegan con `sudo apt upgrade`. @@ -106,15 +108,21 @@ sudo dnf copr enable arios/voltkit sudo dnf install voltkit ``` +**¿Instalaste el snap antes?** Quítalo primero (`sudo snap remove voltkit`), o Voltkit quedará instalado dos veces, con dos servicios en segundo plano compitiendo por los mismos atajos. + Luego abre Voltkit desde tus apps; se configura solo de la misma forma. Las actualizaciones llegan con `sudo dnf upgrade`. ## Instalación (Snap Store) +El snap existe sobre todo para que la gente encuentre Voltkit: la Snap Store está disponible en todas las distribuciones Linux que admiten snaps. La mayoría de las funciones son iguales en el snap; para las pocas que un snap no tiene permitidas, instálalo con apt o Fedora. + ```bash sudo snap install voltkit ``` +**¿Lo instalaste antes con apt o Fedora?** Quita esa versión primero (`sudo apt remove voltkit` o `sudo dnf remove voltkit`), para que Voltkit no quede instalado dos veces. + El snap funciona en un entorno aislado, así que el ajuste de GPU, Hosts y entorno, Permisos de apps, los disparadores al escribir y algunas otras funciones solo funcionan con apt o Fedora, y algunas herramientas necesitan un permiso que se conecta una vez con `sudo snap connect`. Cada página afectada lo indica; consulta [después de instalar el snap](https://arios4k.github.io/voltkit/manual/install.html#snap-store) (en inglés) para ver los comandos. ## Instalación (desde el código fuente) diff --git a/README.fr.md b/README.fr.md index 0ed29fc..8f1c146 100644 --- a/README.fr.md +++ b/README.fr.md @@ -97,6 +97,8 @@ echo "deb [signed-by=/usr/share/keyrings/voltkit-archive-keyring.gpg] https://ar sudo apt update && sudo apt install voltkit ``` +**Vous aviez installé le snap ?** Supprimez-le d’abord (`sudo snap remove voltkit`), sinon Voltkit sera installé deux fois, avec deux services en arrière-plan qui se disputent les mêmes raccourcis. + apt installe les outils nécessaires (Tesseract, wl-clipboard, le portail du bureau) avec Voltkit, et les mises à jour arrivent avec `sudo apt upgrade`. @@ -113,15 +115,21 @@ sudo dnf copr enable arios/voltkit sudo dnf install voltkit ``` +**Vous aviez installé le snap ?** Supprimez-le d’abord (`sudo snap remove voltkit`), sinon Voltkit sera installé deux fois, avec deux services en arrière-plan qui se disputent les mêmes raccourcis. + Ouvrez ensuite Voltkit depuis vos applications ; il se configure de la même façon. Les mises à jour arrivent avec `sudo dnf upgrade`. ## Installation (Snap Store) +Le snap existe surtout pour qu’on trouve Voltkit : le Snap Store est disponible sur toutes les distributions Linux qui prennent en charge les snaps. La plupart des fonctions marchent de la même façon dans le snap ; pour les rares qu’un snap n’a pas le droit d’utiliser, installez-le avec apt ou Fedora. + ```bash sudo snap install voltkit ``` +**Vous l’aviez installé avec apt ou Fedora ?** Supprimez d’abord cette version (`sudo apt remove voltkit` ou `sudo dnf remove voltkit`), pour que Voltkit ne soit pas installé deux fois. + Le snap s’exécute dans un bac à sable : le réglage du GPU, Hôtes et environnement, les autorisations des applications, les déclencheurs saisis et quelques autres fonctions ne marchent qu’avec apt ou Fedora, et certains outils ont besoin d’une autorisation à connecter une fois avec `sudo snap connect`. Chaque page concernée le signale ; les commandes sont dans [Après l’installation du snap](https://arios4k.github.io/voltkit/manual/install.html#snap-store) (en anglais). ## Installation (depuis les sources) diff --git a/README.md b/README.md index 29728d8..ac95645 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,8 @@ echo "deb [signed-by=/usr/share/keyrings/voltkit-archive-keyring.gpg] https://ar sudo apt update && sudo apt install voltkit ``` +**Installed the snap before?** Remove it first (`sudo snap remove voltkit`), or Voltkit ends up installed twice, with two background services fighting over the same shortcuts. + apt installs the required tools (Tesseract, wl-clipboard, the desktop portal) along with Voltkit, and updates arrive with `sudo apt upgrade`. @@ -103,15 +105,21 @@ sudo dnf copr enable arios/voltkit sudo dnf install voltkit ``` +**Installed the snap before?** Remove it first (`sudo snap remove voltkit`), so Voltkit isn't installed twice. + Then open Voltkit from your apps; it sets itself up the same way. Updates arrive with `sudo dnf upgrade`. ## Install (Snap Store) +The snap is here mostly so people can find Voltkit: the Snap Store is available on every Linux distribution that supports snaps. Most features work the same in the snap; for the few that a snap isn't allowed, install with apt or Fedora. + ```bash sudo snap install voltkit ``` +**Installed with apt or Fedora before?** Remove that version first (`sudo apt remove voltkit` or `sudo dnf remove voltkit`), so Voltkit isn't installed twice. + The snap runs in a sandbox, so GPU tuning, Hosts & Environment, App Permissions, typed triggers and a few other features work only with apt or Fedora, and some tools need a permission connected once with `sudo snap connect`. Each affected page says so; see [after installing the snap](https://arios4k.github.io/voltkit/manual/install.html#snap-store) for the commands. ## Install (from source) diff --git a/README.zh-CN.md b/README.zh-CN.md index cf0b1ca..ae775f3 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -91,6 +91,8 @@ echo "deb [signed-by=/usr/share/keyrings/voltkit-archive-keyring.gpg] https://ar sudo apt update && sudo apt install voltkit ``` +**之前安装过 snap 版?** 请先移除它(`sudo snap remove voltkit`),否则 Voltkit 会被安装两次,两个后台服务会争抢同一组快捷键。 + apt 会在安装 Voltkit 的同时安装所需工具(Tesseract、wl-clipboard、桌面门户),之后的更新通过 `sudo apt upgrade` 获得。 然后从应用列表中打开 Voltkit:它会自动设置后台服务和键盘快捷键。接下来该做什么,请参阅手册中的 [Install](https://arios4k.github.io/voltkit/manual/install.html) 和 [A tour of the app](https://arios4k.github.io/voltkit/manual/tour.html)。 @@ -106,14 +108,20 @@ sudo dnf copr enable arios/voltkit sudo dnf install voltkit ``` +**之前安装过 snap 版?** 请先移除它(`sudo snap remove voltkit`),否则 Voltkit 会被安装两次,两个后台服务会争抢同一组快捷键。 + 然后从应用列表中打开 Voltkit;它会以同样的方式完成自身设置。更新通过 `sudo dnf upgrade` 获得。 ## 安装(Snap Store) +提供 snap 版主要是为了让更多人发现 Voltkit:所有支持 snap 的 Linux 发行版都可以使用 Snap Store。大多数功能在 snap 版中完全相同;少数 snap 不被允许的功能,请通过 apt 或 Fedora 安装使用。 + ```bash sudo snap install voltkit ``` +**之前用 apt 或 Fedora 安装过?** 请先移除该版本(`sudo apt remove voltkit` 或 `sudo dnf remove voltkit`),以免 Voltkit 被安装两次。 + Snap 版运行在沙盒中,因此 GPU 调节、Hosts 与环境变量、应用权限、键入触发词等少数功能只能在 apt 或 Fedora 版中使用,部分工具还需要用 `sudo snap connect` 连接一次权限。受影响的页面都会提示;命令见[安装 snap 之后](https://arios4k.github.io/voltkit/manual/install.html#snap-store)(英文)。 ## 安装(从源码) diff --git a/docs/manual/pages/_order.txt b/docs/manual/pages/_order.txt index 444d134..6872e66 100644 --- a/docs/manual/pages/_order.txt +++ b/docs/manual/pages/_order.txt @@ -1,6 +1,7 @@ # file-stem | Title | Group index | Voltkit Manual | Start here install | Install | Start here +snap | Snap Store version | Start here tour | A tour of the app | Start here permissions | App Permissions | Tools compress | Asset Compressor | Tools diff --git a/docs/manual/pages/faq.md b/docs/manual/pages/faq.md index 11bdd1e..dbc3b3a 100644 --- a/docs/manual/pages/faq.md +++ b/docs/manual/pages/faq.md @@ -30,6 +30,10 @@ **How do I change the language?** Voltkit follows your session language (English, Spanish, German, French and Simplified Chinese). To test another: `LANGUAGE=de voltkit`. This manual is in English. -**How do I uninstall it?** `sudo apt remove voltkit` or `sudo dnf remove voltkit`. Your settings stay in `~/.config/voltkit/` until you delete them. If you turned on typed triggers, run `voltkit expander remove-access` first. +**Why is there a snap version, and is it the same?** It's there so more people can find Voltkit: the Snap Store is on every Linux distribution that supports snaps. Most of Voltkit works the same in it, but a few features need apt or Fedora because of the snap sandbox. See [Snap Store version](snap). + +**Can I install both the snap and the apt or Fedora version?** Don't: you'd get two Voltkit entries in your apps and two background services fighting over the same shortcuts. See [Installing only one version](snap#installing-only-one-version). + +**How do I uninstall it?** `sudo apt remove voltkit`, `sudo dnf remove voltkit` or `sudo snap remove voltkit`. Your settings stay in `~/.config/voltkit/` until you delete them. If you turned on typed triggers, run `voltkit expander remove-access` first. **Is it free?** Yes. Voltkit is open source under the MIT license: [github.com/arios4k/voltkit](https://github.com/arios4k/voltkit). If you find it useful, you can [support the author on PayPal](https://paypal.me/AlexisRios). diff --git a/docs/manual/pages/install.md b/docs/manual/pages/install.md index 33f94b8..09f0d68 100644 --- a/docs/manual/pages/install.md +++ b/docs/manual/pages/install.md @@ -14,6 +14,12 @@ echo "deb [signed-by=/usr/share/keyrings/voltkit-archive-keyring.gpg] https://ar sudo apt update && sudo apt install voltkit ``` +> [!IMPORTANT] **Installed the snap before?** Remove it first, or Voltkit is installed twice: two Voltkit entries in your apps, and two background services fighting over the same keyboard shortcuts. + +```bash +sudo snap remove voltkit +``` + The repository is signed with a GPG key, and apt installs the tools Voltkit needs (Tesseract, wl-clipboard, the desktop portal) together with it. Updates arrive with `sudo apt upgrade`. ## Fedora @@ -27,9 +33,19 @@ sudo dnf install voltkit Updates arrive with `sudo dnf upgrade`. +> [!IMPORTANT] **Installed the snap before?** Remove it first, or Voltkit is installed twice: two Voltkit entries in your apps, and two background services fighting over the same keyboard shortcuts. + +```bash +sudo snap remove voltkit +``` + ## Snap Store -Voltkit is also in the Snap Store, so you can find it in Ubuntu's App Center: +For everything about the snap (what works, permissions, limits and switching versions), see [Snap Store version](snap). + +**Why a snap?** Mostly so people can find Voltkit. The Snap Store is available on every Linux distribution that supports snaps, and it shows up in app stores such as Ubuntu's App Center, so more people can discover the tool and install it in one step. **Most of Voltkit works the same in the snap:** 16 of its 18 tools work there, most of them fully. For the few features a snap isn't allowed (see [What works only with apt or Fedora](#what-works-only-with-apt-or-fedora)), apt or Fedora is the way to install it. + +Install it from Ubuntu's App Center, or with: ```bash sudo snap install voltkit @@ -37,6 +53,8 @@ sudo snap install voltkit Snap updates arrive automatically. +> [!IMPORTANT] **Installed Voltkit with apt or Fedora before?** Remove that version first, or Voltkit is installed twice: two Voltkit entries in your apps, and two background services fighting over the same keyboard shortcuts. Use `sudo apt remove voltkit` (Ubuntu, Debian) or `sudo dnf remove voltkit` (Fedora). + > [!IMPORTANT] Apps from the Snap Store run in a sandbox that can't ask for your administrator password, change system files or read the desktop's permission store. Some features need one of them, so they work only when Voltkit is installed with apt (Ubuntu, Debian) or DNF (Fedora). Each tool affected shows a banner at the top of its page that says what is missing and why. ### After installing the snap @@ -79,21 +97,16 @@ Its *Snap Store version* section lists each permission and whether it is connect ### What works only with apt or Fedora -| Tool | What the snap can't do | -|---|---| -| [GPU Tuner](gpu) | Changing settings (power limit, fans, clocks, voltage) and applying profiles at startup. Monitoring works. | -| [Hosts & Environment](system) | The whole tool: editing `/etc/hosts` and your session's environment variables. | -| [App Permissions](permissions) | The whole tool: the sandbox can't read the desktop's permission store. | -| [Text Expansion](snippets) | Typed triggers such as `;date`. The snippet picker (Super+Shift+E) works. | -| [System Report](sysreport) | Drive health, memory slots and firmware update checks. | -| [What's Using This?](using) | Seeing and closing apps that belong to other users or to the system. | -| [Why Didn't It Sleep?](sleep) | Stopping a USB device from waking the computer. | +A few features need the administrator password, system files or desktop services that a snap isn't allowed to use. **This is a limitation of snaps, not of Voltkit**, and most of Voltkit works the same in the snap. Left out: -These need the administrator password (Voltkit asks through `pkexec`), write system files or read the desktop's permission store, and a snap is allowed none of them. To use them, remove the snap and install with [apt](#ubuntu-debian-and-derivatives) or [Fedora](#fedora) instead: +- [GPU Tuner](gpu): changing settings (monitoring works); +- [Hosts & Environment](system) and [App Permissions](permissions): the whole tools; +- [Text Expansion](snippets): typed triggers (the snippet picker works); +- [System Report](sysreport): drive health, memory slots and firmware checks; +- [What's Using This?](using): other users' and the system's apps; +- [Why Didn't It Sleep?](sleep): stopping a USB device from waking the computer. -```bash -sudo snap remove voltkit -``` +[Snap Store version](snap#what-works-only-with-apt-or-fedora) explains why each one can't work in a snap, what works in every tool, and how to switch to apt or Fedora without losing your snippets. ## From source diff --git a/docs/manual/pages/snap.md b/docs/manual/pages/snap.md new file mode 100644 index 0000000..eb63baa --- /dev/null +++ b/docs/manual/pages/snap.md @@ -0,0 +1,223 @@ +# Snap Store version + +Voltkit is available in three ways: from its own **apt** repository (Ubuntu, Debian and derivatives), from **Fedora** COPR, and from the **Snap Store**. This page explains what is different about the snap: why it exists, what works in it, what to do after installing it, what it can't do and why, and how to switch between versions. + +## Why there is a snap version + +Mostly **so people can find Voltkit**. The Snap Store is available on every Linux distribution that supports snaps, and it is built into app stores such as Ubuntu's App Center, where people browse and install apps without a terminal. Publishing there makes the tool easier to discover and to install in one step. + +**Most of Voltkit works the same in the snap.** 16 of its 18 tools work there, most of them fully, and only a handful of features are left out. Those are limits of the snap sandbox, explained below, not of Voltkit. If you need them, install with apt or Fedora instead: that version has every feature. + +## Which version should I install? + +| | apt (Ubuntu, Debian…) | Fedora (COPR) | Snap Store | +|---|---|---|---| +| Where | Ubuntu 24.04+, Debian 13+, Mint 22, Zorin OS 18, Pop!_OS 24.04 and derivatives | Fedora 43+ | Any distribution with snapd, and Ubuntu's App Center | +| Features | All | All | All except those listed in [What works only with apt or Fedora](#what-works-only-with-apt-or-fedora) | +| Updates | `sudo apt upgrade` | `sudo dnf upgrade` | Automatic | +| Setup after installing | None | None | Connect a few permissions once ([below](#connect-the-permissions)) | +| Runs in a sandbox | No | No | Yes (strict confinement) | + +**Install only one of them.** See [Installing only one version](#installing-only-one-version). + +## What works in the snap + +| Tool | In the snap | +|---|---| +| [Text Extractor](ocr) | Works fully (English text recognition is included) | +| [Color Picker](color) | Works fully | +| [QR Code](qr) | Works fully | +| [Screen Ruler](ruler) | Works fully | +| [Zoom & Annotate](zoom) | Works fully | +| [Smart Paste](smartpaste) | Works fully | +| [Keep Awake](awake) | Works fully | +| [Shortcut Detective](shortcuts) | Works fully | +| [Asset Compressor](compress) | Works fully for files in your home folder; USB drives after connecting `removable-media` | +| [Batch Rename](rename) | Same as the compressor | +| [Image Resizer](resize) | Same as the compressor | +| [Text Expansion](snippets) | The snippet picker works; **typed triggers don't** | +| [What's Using This?](using) | Your own apps, after connecting `system-observe`, `mount-observe` and `process-control`; **not other users' or the system's apps** | +| [Why Didn't It Sleep?](sleep) | After connecting `log-observe` and `login-session-observe`; **can't stop a USB device from waking the computer** | +| [System Report](sysreport) | After connecting `hardware-observe`, `system-observe` and `mount-observe`; **no drive health, memory slots or firmware checks** | +| [GPU Tuner](gpu) | **Monitoring only**, after connecting `hardware-observe`; can't change settings | +| [Hosts & Environment](system) | **Not available** (shown read-only) | +| [App Permissions](permissions) | **Not available** (shown read-only) | + +## After installing the snap + +### Open Voltkit once + +Open **Voltkit** from your apps. It starts its background service, sets it to start at every login, and adds its keyboard shortcuts. The shortcuts run the snap's command, `/snap/bin/voltkit`. + +### Connect the permissions + +Snaps get access to the system one permission (*interface*) at a time. The ones that are safe for every app are connected automatically: the desktop, the screen, sound, your home folder, settings and the desktop's portals for screenshots, the eyedropper and pasting. The ones below give access to system information, so Snap leaves them for you to allow. Copy these commands into a terminal and press Enter (they ask for your password once): + +```bash +sudo snap connect voltkit:removable-media +sudo snap connect voltkit:system-observe +sudo snap connect voltkit:mount-observe +sudo snap connect voltkit:process-control +sudo snap connect voltkit:log-observe +sudo snap connect voltkit:login-session-observe +sudo snap connect voltkit:hardware-observe +``` + +If your app store shows a **Permissions** section for Voltkit (GNOME Software does), you can switch them on there instead. You only need the ones for the tools you use: + +| Permission | Lets Voltkit | Used by | +|---|---|---| +| `removable-media` | use files on USB drives and other external disks | Asset Compressor, Batch Rename, Image Resizer | +| `system-observe` | see which apps have files and ports open, and read drivers and the system's state | What's Using This?, System Report | +| `mount-observe` | list the drives that are connected | What's Using This?, System Report | +| `process-control` | close the apps that keep something busy | What's Using This? | +| `log-observe` | read the sleep history from the system log | Why Didn't It Sleep? | +| `login-session-observe` | see what is keeping the computer awake | Why Didn't It Sleep? | +| `hardware-observe` | read hardware details, temperatures and fans | System Report, GPU Tuner | + +### Check + +```bash +voltkit doctor +``` + +Its *Snap Store version* section lists every permission with ✓ (connected) or – (not connected) and the command for each one that is missing, followed by the features that need apt or Fedora. You can also list the connections with: + +```bash +snap connections voltkit +``` + +To take a permission back, disconnect it, for example: + +```bash +sudo snap disconnect voltkit:process-control +``` + +## What works only with apt or Fedora + +**This is a limitation of snaps, not of Voltkit.** Every app from the Snap Store runs in a sandbox (*strict confinement*) that keeps it away from the rest of the system. A snap: + +- **can't ask for your administrator password.** Voltkit uses `pkexec` for the few things only the administrator may do; inside a snap it isn't allowed; +- **can't change system files**, such as `/etc/hosts` or the files in `/sys` that control devices; +- **can't write to your hidden settings folders** (`~/.config` and the like): it gets its own private copy instead; +- **can only talk to the system services Snap allows**, which leaves out the desktop's permission store and the disk service; +- **can't get access to the keyboard** unless the Snap Store reviews the app by hand. + +That protects you from apps you haven't checked, but a few Voltkit features need exactly those things: + +| Tool | What the snap can't do | Why | +|---|---|---| +| [GPU Tuner](gpu) | Change settings (power limit, fans, clocks, voltage) and apply profiles at startup. **Monitoring works.** | Settings are written to the graphics driver by a helper that runs as administrator after asking for your password (`pkexec`). A snap can't ask for it, and applying a profile at startup needs a system service, which a snap can't install. | +| [Hosts & Environment](system) | The whole tool. | `/etc/hosts` is a system file only the administrator can change. Environment variables are saved in your hidden settings folder (`~/.config/environment.d`), which a snap can't write to: it only sees its own private copy, so changes would have no effect. | +| [App Permissions](permissions) | The whole tool. | The answers you gave apps are kept by the desktop's permission store (`xdg-permission-store`), a service snaps aren't allowed to talk to. | +| [Text Expansion](snippets) | Typed triggers such as `;date`. **The snippet picker** (Super+Shift+E) **works.** | Typed triggers read the keyboard and type for you, which needs a one-time setup by the administrator (a rule in `/etc/udev`). A snap can't make that change, and the Snap Store reserves keyboard access for apps it reviews by hand. | +| [System Report](sysreport) | Drive health, memory slots and firmware update checks. **Everything else works** once its permissions are connected. | Drive health comes from the system's disk service (UDisks), which snaps aren't allowed to query; memory slot details are in a table (SMBIOS) only the administrator can read; firmware checks use the `fwupdmgr` tool, which isn't inside the snap. | +| [What's Using This?](using) | See and close apps that belong to other users or to the system. **Your own apps work** once its permissions are connected. | Other users' and the system's apps are visible only to the administrator, and closing them needs your password. | +| [Why Didn't It Sleep?](sleep) | Stop a USB device from waking the computer. **Everything else works** once its permissions are connected. | Which devices may wake the computer is a system setting; changing it, and keeping it after a restart, needs the administrator password. | + +None of this can be fixed with `snap connect`: the Snap Store doesn't offer these permissions to apps like Voltkit. If you need them, [switch to apt or Fedora](#from-the-snap-to-apt-or-fedora). + +## How the app tells you + +In the snap, every affected tool says so at the top of its page, so you know right away: + +- **"Connect 2 permissions to use everything here"** (or similar): some permissions above aren't connected yet. **Details** lists what each one is for and the exact `sudo snap connect` commands, with a **Copy Commands** button. The banner disappears once they are connected (it checks again whenever you open the page). +- **"Part of this tool works only in the APT and Fedora versions"**: the tool works, but one feature is left out. **Details** says which, and why. +- **"This tool works only in the APT and Fedora versions of Voltkit"**: the whole tool is unavailable. Its page is shown read-only so nothing is saved to the wrong place. + +**Details** also has **How to Install the Full Version**, which opens the [Install](install) page. + +## Installing only one version + +Install Voltkit **one way only**. With both the snap and the apt or Fedora package installed: + +- your apps show **two Voltkit entries**; +- **two background services** start at login, but only one can own the keyboard shortcuts, so shortcuts may run the wrong copy or seem to do nothing; +- each copy keeps **its own settings and snippets**, so changes in one don't show in the other. + +### From the snap to apt or Fedora + +**1.** Optional: keep your snippets and settings. The snap keeps them in its own folder; copy them to where the apt or Fedora version looks: + +```bash +mkdir -p ~/.config/voltkit && cp ~/snap/voltkit/current/.config/voltkit/config.toml ~/.config/voltkit/ +``` + +**2.** Remove the snap: + +```bash +sudo snap remove voltkit +``` + +**3.** Install with [apt](install#ubuntu-debian-and-derivatives) or [Fedora](install#fedora) and open Voltkit once. It sets its shortcuts to the new copy. + +### From apt or Fedora to the snap + +**1.** Optional: keep your snippets and settings. Save a copy where you can find it: + +```bash +cp ~/.config/voltkit/config.toml ~/voltkit-config-backup.toml +``` + +**2.** If you used typed triggers, remove their keyboard access while the apt or Fedora version is still installed: + +```bash +voltkit expander remove-access +``` + +**3.** Remove the apt or Fedora version. On Ubuntu and Debian: + +```bash +sudo apt remove voltkit +``` + +On Fedora: + +```bash +sudo dnf remove voltkit +``` + +**4.** Install the snap and open Voltkit once, so its shortcuts and start-at-login are set up: + +```bash +sudo snap install voltkit +``` + +**5.** If you saved your settings in step 1, put them where the snap looks, then reload them: + +```bash +mkdir -p ~/snap/voltkit/current/.config/voltkit && cp ~/voltkit-config-backup.toml ~/snap/voltkit/current/.config/voltkit/config.toml && voltkit daemon reload +``` + +**6.** [Connect the permissions](#connect-the-permissions). + +## Updates and removal + +Snaps update themselves in the background, usually within a few hours of a release. To update now, or to see the installed and published versions: + +```bash +sudo snap refresh voltkit +``` + +```bash +snap info voltkit +``` + +To remove the snap: + +```bash +sudo snap remove voltkit +``` + +This also removes the snap's settings and snippets (Snap keeps a snapshot for a while, see `snap saved`). Copy `~/snap/voltkit/current/.config/voltkit/config.toml` first if you want to keep them. + +## Troubleshooting the snap + +| Problem | What to do | +|---|---| +| A banner says to connect permissions, but I did | Open another tool and come back: the page checks again when it is shown. `snap connections voltkit` shows what is really connected; check the command was typed as `voltkit:` followed by the permission name. | +| Keyboard shortcuts do nothing or open the wrong copy | Check that only one Voltkit is installed (`snap list voltkit` and `apt list --installed voltkit`). If both are, remove one as in [Installing only one version](#installing-only-one-version), then open the remaining one once. | +| `voltkit doctor` says the background service isn't running | Open Voltkit once, or log out and in again: the snap starts the service at login. | +| A tool's page is greyed out | That tool needs apt or Fedora: see [What works only with apt or Fedora](#what-works-only-with-apt-or-fedora). | +| Files on a USB drive can't be opened | Connect `removable-media` (`sudo snap connect voltkit:removable-media`). | +| Text Extractor doesn't read my language | The snap includes English only. For other languages, install with apt or Fedora and add the Tesseract language packs. | diff --git a/docs/manual/pages/troubleshooting.md b/docs/manual/pages/troubleshooting.md index a43c9c9..936405b 100644 --- a/docs/manual/pages/troubleshooting.md +++ b/docs/manual/pages/troubleshooting.md @@ -52,6 +52,8 @@ The same findings appear in the app as the **N features need attention** banner, | Typed triggers do nothing | `voltkit expander status` says why. | | The clipboard is not set from a shortcut | Install `wl-clipboard` (Wayland) or `xclip` (X11). The result still appears in a notification. | | A GPU control is greyed out | Open the GPU Tuner's Monitor tab: *What this card supports* gives the reason. | +| Running the snap: a page shows a banner or is greyed out | That tool needs a permission connected, or works only with apt or Fedora. Click **Details**, or see [Snap Store version](snap). | +| Shortcuts run the wrong copy, or Voltkit appears twice in your apps | Both the snap and the apt or Fedora version are installed. Keep one: see [Installing only one version](snap#installing-only-one-version). | | Voltkit does not follow my language | Start it with `LANGUAGE=es voltkit` to test; set your session language otherwise. | ## Reporting a problem