docs: make KDE custom desktop setup safe and explicit

gh-pages/blog/2025-07-30-kde-support.md

@@ -4,24 +4,36 @@ authors: teddy
 tags: [for-user, kde, plasma, desktop-environment, wayland, x11]
 ---
 
-We're excited to announce that our experiments with **KDE Plasma** have yielded positive results, both the X11 session via XWayland and the Wayland session.
+:::caution Current guidance
+This post records early KDE experiments. Use the maintained [custom desktop environment guide](/docs/user/custom-de#kde-plasma) for current instructions. A TOML table may contain only one `try_launch` key, and native Wayland does not start reliably on every device.
+:::
+
+Our initial experiments with **KDE Plasma** produced working X11 sessions through Xwayland and working native Wayland sessions on the tested setup.
 
 ![KDE Plasma on Local Desktop](/img/kde.webp)
 
 ## How to
 
-Please visit [this document](/docs/user/custom-de) for detailed instructions.
-In simpler terms, just add the following configuration to your `localdesktop.toml` file:
+Create or edit `/etc/localdesktop/localdesktop.toml`, then choose **one** session template.
+
+### X11 via Xwayland
 
 ```toml title="/etc/localdesktop/localdesktop.toml"
 [command]
 try_check = "pacman -Qg plasma"
 try_install = "stdbuf -oL pacman -Syu plasma --noconfirm --noprogressbar"
-# X11 session via Xwayland
 try_launch = "XDG_RUNTIME_DIR=/tmp Xwayland -hidpi :1 2>&1 & while [ ! -e /tmp/.X11-unix/X1 ]; do sleep 0.1; done; XDG_SESSION_TYPE=x11 DISPLAY=:1 dbus-launch startplasma-x11 2>&1"
-# Wayland session
+```
+
+### Native Wayland
+
+```toml title="/etc/localdesktop/localdesktop.toml"
+[command]
+try_check = "pacman -Qg plasma"
+try_install = "stdbuf -oL pacman -Syu plasma --noconfirm --noprogressbar"
 try_launch = "XDG_RUNTIME_DIR=/tmp WAYLAND_DISPLAY=wayland-0 /usr/lib/plasma-dbus-run-session-if-needed startplasma-wayland 2>&1"
 ```
 
+Do not paste both `try_launch` alternatives into the same table. If native Wayland produces a black or purple screen, restart Local Desktop and test the X11 template. When a template succeeds, remove the `try_` prefix from all three settings to keep it for later launches.
 
-The outcome has been so promising that we're considering setting KDE Plasma as the default desktop environment in Local Desktop. This aligns with our long-term goal: replacing XWayland with a native Wayland session for better performance. We'd love to hear your thoughts on our [GitHub repository](https://github.com/localdesktop/localdesktop.github.io), and toss us a ⭐️ to help keep us motivated to improve KDE Plasma compatibility!
+Local Desktop currently defaults to Xfce; KDE remains an advanced custom configuration. Compatibility details and non-root user instructions are maintained in the [user guide](/docs/user/custom-de#kde-plasma).

gh-pages/docs/user/2-creating-a-non-root-user.md

@@ -2,87 +2,90 @@
 title: Creating a Non-root User
 ---
 
-For a simple setup process, Local Desktop won't prompt for a user registration form, that's why **it is login as root by default**.
+For a simple setup process, Local Desktop does not prompt for user registration and logs in as root by default.
 
-However, some applications are **recommended** or **required** to run as a normal user. For example:
+Some applications are recommended or required to run as a normal user. For example:
 
-- Chrome and Electron-based applications like VS Code **work better or are safer** without root.
-- AUR helpers like Paru or Yay require a non-root user and **won't work as root**.
+- Chrome and Electron-based applications such as VS Code work better or are safer without root.
+- AUR helpers such as Paru or Yay require a non-root user and do not run as root.
 
 :::info
-
-Please follow the instructions below carefully, or you can continue to use XFCE with root if you prefer.
-
+Follow the instructions below carefully. You can continue to use Xfce as root when a separate user is not required.
 :::
 
 ## Create your user
 
-Open a terminal and run the following command:
-
-_(Replace `teddy` with your preferred username)_
+Open a terminal and create an account. Replace `teddy` with your preferred username:
 
 ```bash
 useradd -m teddy
 ```
 
-The `-m` flag creates a home directory for the user.
+The `-m` flag creates the user's home directory.
 
 ## Create your password
 
-Set a password for your new user (you'll need this for `sudo`):
+Set a password for the new user. It will be required by `sudo`:
 
 ```bash
 passwd teddy
 ```
 
 ## Set up `sudo`
 
-Once you have logged in as a non-root user, you **must** use `sudo` to run commands with root privileges. If you skip this step, you **won't** be able to install new packages.
+After logging in as a non-root user, use `sudo` for commands that require root privileges. Without this step, the account cannot install new packages interactively.
 
 Install `sudo`:
 
 ```bash
 pacman -S sudo
 ```
 
-Allow your user to use `sudo` by editing the sudoers file:
+Edit the sudoers file safely:
 
 ```bash
 EDITOR=nano visudo
 ```
 
-Append a new line:
+Append a line for the account:
 
-```
+```text
 teddy ALL=(ALL) ALL
 ```
 
-_(Replace `teddy` with the username you created [previously](#create-your-user))_
-
-Save and exit.
+Replace `teddy` with the username you created, then save and exit.
 
-You can test if your new user can use `sudo` by temporarily logging in:
+Test the configuration by temporarily logging in:
 
 ```bash
-su teddy # Change to your username
-sudo ls /root # Make sure it does not output something like: "teddy is not in the sudoers file"
+su teddy
+sudo ls /root
 ```
 
-## [Important] Tell Local Desktop
+The second command must not report that the user is absent from the sudoers file.
 
-You must tell Local Desktop who to log in as, or it will log in as root. To (create and) edit the config file:
+## Tell Local Desktop which user to launch
 
-```
+Local Desktop must be told which account should own the desktop session. Create or edit the configuration file:
+
+```bash
+mkdir -p /etc/localdesktop
 nano /etc/localdesktop/localdesktop.toml
 ```
 
-Add the following content:
+Add:
 
 ```toml title="/etc/localdesktop/localdesktop.toml"
 [user]
 username = "teddy"
 ```
 
-_(Replace `teddy` with the username you created [previously](#create-your-user))_
+Replace `teddy` with the account you created. The change takes effect on the next launch.
+
+:::note What this setting changes
+The `[user].username` setting controls the account used for the desktop `launch` command. Local Desktop still runs dependency `check` and `install` commands as root, so desktop packages are installed system-wide while application settings and files belong to the selected user.
+:::
+
+For a custom desktop such as KDE Plasma, keep this `[user]` table and add exactly one tested `[command]` template from [Using other Desktop Environments](/docs/user/custom-de#kde-plasma).
 
-The changes will take effect the next time you launch Local Desktop. If something goes wrong, you can always delete this config file and restart as root.
+If the account or configuration is incorrect, remove or fix `/etc/localdesktop/localdesktop.toml` and restart Local Desktop to return to the built-in root default.

gh-pages/docs/user/3-custom-de.md

@@ -3,88 +3,161 @@ title: Using other Desktop Environments
 ---
 
 :::warning
-This is an advanced topic. Proceed with your own risk.
+This is an advanced topic. A desktop environment that fails to start can leave you on a black or solid-colour screen for that launch. Test changes with the `try_*` settings described below so that Local Desktop can recover on the next restart.
 :::
 
-## The `[command]` configs
+:::info Project scope
+Local Desktop targets desktop-style use on Android with a sufficiently large display and a physical keyboard. Mobile shells such as Phosh and Plasma Mobile are not currently supported or planned as defaults. We intentionally do not publish unverified installation or launch commands; confirmed community configurations are welcome.
+:::
+
+## Before you begin
+
+Local Desktop reads custom settings from:
+
+```text
+/etc/localdesktop/localdesktop.toml
+```
+
+The file is optional and might not exist on a fresh installation. From the default root session, create it when needed:
+
+```bash
+mkdir -p /etc/localdesktop
+touch /etc/localdesktop/localdesktop.toml
+```
+
+Each setting must fit on one line. A TOML key may appear only once in a table, so a configuration must contain **exactly one** `launch` or `try_launch` entry. Do not paste the X11 and Wayland alternatives into the same `[command]` table.
 
-Local Desktop uses 3 commands to set up your desktop environment:
+## The `[command]` settings
+
+Local Desktop uses three commands to set up a desktop environment:
 
 ```toml title="/etc/localdesktop/localdesktop.toml"
 [command]
-check="pacman -Q noto-fonts && pacman -Q xfce4-session && pacman -Q xfce4-panel && pacman -Q xfce4-settings && pacman -Q xfce4-terminal && pacman -Q thunar && pacman -Q xfdesktop && pacman -Q xfconf && pacman -Q labwc && pacman -Q wlr-randr && pacman -Q xorg-xwayland && pacman -Q xdg-desktop-portal && pacman -Q xdg-desktop-portal-gtk && pacman -Q onboard"
-install="stdbuf -oL pacman -Syu --needed --noconfirm --noprogressbar noto-fonts xfce4 labwc wlr-randr xorg-xwayland xdg-desktop-portal xdg-desktop-portal-gtk onboard"
-launch="XDG_RUNTIME_DIR=/tmp WAYLAND_DISPLAY=wayland-0 XDG_SESSION_TYPE=wayland XDG_CURRENT_DESKTOP=XFCE /usr/local/bin/startxfce4-localdesktop 2>&1"
+check = "pacman -Q noto-fonts && pacman -Q xfce4-session && pacman -Q xfce4-panel && pacman -Q xfce4-settings && pacman -Q xfce4-terminal && pacman -Q thunar && pacman -Q xfdesktop && pacman -Q xfconf && pacman -Q labwc && pacman -Q wlr-randr && pacman -Q xorg-xwayland && pacman -Q xdg-desktop-portal && pacman -Q xdg-desktop-portal-gtk && pacman -Q onboard"
+install = "stdbuf -oL pacman -Syu --needed --noconfirm --noprogressbar noto-fonts xfce4 labwc wlr-randr xorg-xwayland xdg-desktop-portal xdg-desktop-portal-gtk onboard"
+launch = "XDG_RUNTIME_DIR=/tmp WAYLAND_DISPLAY=wayland-0 XDG_SESSION_TYPE=wayland XDG_CURRENT_DESKTOP=XFCE /usr/local/bin/startxfce4-localdesktop 2>&1"
 ```
 
-You can change these 3 commands to install and launch your custom desktop environment. Please share your successful setups with us and we can put them here to help others.
+You can replace these commands to install and launch another desktop environment.
 
-:::success Tips
-The `try_check`, `try_install`, `try_launch` configs are very handy to try different config values **without breaking anything**. Check out the [Configurations](/docs/user/configurations#special-try_-configs) documentation for more details about `try_*`.
+:::success Test safely with `try_*`
+Use `try_check`, `try_install`, and `try_launch` while testing. Each `try_*` entry overrides its normal counterpart for one launch and is then commented out automatically. See [Configurations](/docs/user/configurations#special-try_-configs) for the complete behavior.
 :::
 
-### check
+### `check`
+
+The `check` command verifies that all required packages are installed. Local Desktop has two operating modes:
 
-The `check` command is used to verify if the required packages are installed and Local Desktop is ready to boot in Wayland mode. In case you are wondering, there are 2 modes in Local Desktop:
-- Webview mode (the mode with the official website for documentation on top of a progress bar during installation)
-- Wayland mode
+- **Webview mode**, which shows installation documentation and progress.
+- **Wayland mode**, which hosts the desktop session.
 
-If the command in `check` returns success, Local Desktop will boot in Wayland mode. Otherwise, it will enter Webview mode and proceed with the `install` command.
+If `check` succeeds, Local Desktop starts in Wayland mode. Otherwise, it enters Webview mode and runs `install`.
 
 :::info Recipe
-You can use `pacman -Q package` to check for a package and `pacman -Qg package-group` to check for a group. Use the `&&` operator to combine multiple checks.
+Use `pacman -Q package` to check an individual package and `pacman -Qg package-group` to check a package group. Join independent checks with `&&` so that any missing requirement causes the command to fail.
 :::
 
-### install
+### `install`
+
+When `check` fails, Local Desktop runs `install` as root. Important requirements:
 
-When `check` fails, this command will be executed next. This is exactly the command that Local Desktop runs during the installation process. Some important notes:
-- Always put `stdbuf -oL ` in front of the command. [Why?](/docs/developer/bug-cheat-sheet/pacman-progress)
-- Always include the `--noconfirm` flag, otherwise, it will get stuck because it is waiting for a confirmation that never comes.
-- For a clear output, include `--noprogressbar`.
+- Prefix the command with `stdbuf -oL `. [Why?](/docs/developer/bug-cheat-sheet/pacman-progress)
+- Include `--noconfirm`; there is no interactive prompt available during setup.
+- Include `--noprogressbar` for readable installation output.
 
 :::info Recipe
-Just keep all the syntax and put all the packages/groups between `pacman -Syu` and the first `--`. For example: `pacman -Syu package-1 package-group-2 package-3 --noconfirm`.
+Keep the command syntax and place all packages or groups between `pacman -Syu` and the first option. For example: `pacman -Syu package-1 package-group-2 package-3 --noconfirm --noprogressbar`.
 :::
 
-### launch
+### `launch`
 
-When `check` returns success, this command will be executed next. This is exactly the command that Local Desktop runs to launch the desktop environment.
+When `check` succeeds, Local Desktop runs `launch` as the user configured under `[user]`.
 
-This is the most important command to set up your preferred desktop environment. It is also the most complicated command, as it requires a good understanding of display server components. Some important notes:
-- When things go wrong, you must check the [logcat](/docs/developer/how-to-logcat) to view the logs.
-- If you don't see any error logs, try appending `2>&1` to redirect stderr to stdout.
-- The default session is **Xfce on Wayland**. The built-in compositor listens on `/tmp/wayland-0`; the guest runs `startxfce4 --wayland`, which starts labwc as a nested compositor and connects to that socket. Setup also installs `/usr/local/bin/startxfce4-localdesktop` as a thin wrapper around `startxfce4 --wayland`.
+This is the most important and most environment-sensitive command. Important notes:
+
+- Check [logcat](/docs/developer/how-to-logcat) when a session does not start.
+- Append `2>&1` when necessary so stderr is included in the captured output.
+- The default session is **Xfce on Wayland**. The built-in compositor listens on `/tmp/wayland-0`; the guest runs `startxfce4 --wayland`, which starts labwc as a nested compositor and connects to that socket. Setup installs `/usr/local/bin/startxfce4-localdesktop` as a thin wrapper around `startxfce4 --wayland`.
 
 :::info Recipe
-Put important environment variables at the beginning of the command, for example `XDG_RUNTIME_DIR=/tmp WAYLAND_DISPLAY=wayland-0 XDG_SESSION_TYPE=wayland XDG_CURRENT_DESKTOP=XFCE ...`, then start a Wayland session such as `/usr/local/bin/startxfce4-localdesktop` or `startplasma-wayland`.
+For a native Wayland session, set variables such as `XDG_RUNTIME_DIR=/tmp`, `WAYLAND_DISPLAY=wayland-0`, and `XDG_SESSION_TYPE=wayland`, then start the desktop's Wayland session.
 
-For a legacy **X11 session via Xwayland**, start Xwayland first and point the desktop at `DISPLAY=:1`, for example: `Xwayland -hidpi :1 2>&1 & while [ ! -e /tmp/.X11-unix/X1 ]; do sleep 0.1; done; XDG_SESSION_TYPE=x11 DISPLAY=:1 dbus-launch startxfce4 2>&1`.
+For a legacy X11 session, start Xwayland, wait for its socket, and point the desktop at `DISPLAY=:1`.
 :::
 
-## Config templates
+## KDE Plasma
+
+Choose **one** of the following templates. Do not combine their `try_launch` entries.
 
-### KDE Plasma
+### X11 session via Xwayland
+
+Use this as the fallback when the native Wayland session does not start on a device:
 
 ```toml title="/etc/localdesktop/localdesktop.toml"
 [command]
 try_check = "pacman -Qg plasma"
 try_install = "stdbuf -oL pacman -Syu plasma --noconfirm --noprogressbar"
-# X11 session via Xwayland
 try_launch = "XDG_RUNTIME_DIR=/tmp Xwayland -hidpi :1 2>&1 & while [ ! -e /tmp/.X11-unix/X1 ]; do sleep 0.1; done; XDG_SESSION_TYPE=x11 DISPLAY=:1 dbus-launch startplasma-x11 2>&1"
-# Wayland session
+```
+
+### Native Wayland session
+
+Native Wayland can provide better performance, but compatibility is not uniform. Some users have reported black or purple screens. Test it with the one-shot settings below; after a failed launch, restart Local Desktop and use the X11 template instead.
+
+```toml title="/etc/localdesktop/localdesktop.toml"
+[command]
+try_check = "pacman -Qg plasma"
+try_install = "stdbuf -oL pacman -Syu plasma --noconfirm --noprogressbar"
 try_launch = "XDG_RUNTIME_DIR=/tmp WAYLAND_DISPLAY=wayland-0 /usr/lib/plasma-dbus-run-session-if-needed startplasma-wayland 2>&1"
 ```
 
 ![KDE Plasma on Local Desktop](/img/kde.webp)
 
-Feedback:
+### Keep a successful configuration
 
-- The time zone is not set; however, it is simple to set one with KDE's UI.
-- "Could not enter folder tags:." error popups.
-- The Wayland session offers notably better performance than the X11 session or PRoot Distro + Termux:X11, but some features (e.g., Spectacle screenshots) may not work. With KDE 7 dropping X11 support, improving Wayland compatibility and being less dependent on Xwayland will be a bigger priority.
+The `try_*` settings are deliberately one-shot. When a template works, remove the `try_` prefix from **all three** settings:
 
-### Others
+- `try_check` → `check`
+- `try_install` → `install`
+- `try_launch` → `launch`
+
+If you do not make that change, the test entries are commented out after use and Local Desktop returns to its normal desktop configuration on the next launch.
+
+### Run Plasma as a non-root user
+
+Create and configure the account first by following [Creating a Non-root User](/docs/user/creating-a-non-root-user). Then add the user setting alongside one KDE template:
 
 ```toml title="/etc/localdesktop/localdesktop.toml"
-Feel free to contribute your configs by using the "Edit this page" link below
+[user]
+username = "teddy"
+
+[command]
+# Add exactly one KDE check/install/launch template here.
 ```
+
+Replace `teddy` with the account you created. Local Desktop runs `check` and `install` as root, so KDE packages are installed system-wide. It runs only `launch` as the configured user, so the Plasma session and its per-user settings belong to that account. Do not add `sudo` to the `install` command.
+
+### Known limitations
+
+- The time zone is not set automatically; it can be configured through KDE's settings.
+- A `Could not enter folder tags:.` error can appear.
+- Native Wayland features are still incomplete on some devices. For example, Spectacle screenshots might not work.
+
+## Troubleshooting
+
+| Symptom | Action |
+| --- | --- |
+| Black or purple screen after changing KDE settings | Restart Local Desktop. The one-shot `try_*` values will already be disabled. Then test the X11 template or inspect logcat. |
+| KDE works once, then Local Desktop returns to its default desktop | Remove the `try_` prefix from all three successful settings. |
+| Local Desktop ignores the custom file | Check for malformed TOML, duplicate keys, multi-line values, or incorrect capitalization. |
+| The config file is missing | Create `/etc/localdesktop` and `localdesktop.toml` as shown above. |
+| Plasma starts as root | Create a non-root account and set `[user].username` to that exact account name. |
+
+## Other desktop environments
+
+Please contribute only configurations that you have verified on the current Local Desktop release. A useful contribution includes:
+
+- The complete `check`, `install`, and `launch` commands.
+- Whether the session uses native Wayland or Xwayland.
+- The Local Desktop version and device architecture tested.
+- Known limitations and a recovery path when launch fails.