Desktop Rollback And Safety

Status: current Last reviewed: 2026-06-20 Superseded by: none

CachyOS desktop mutation must be explicit, backed up, and reversible. The active KDE safety baseline is Breeze Dark, captured from a manually restored user-level reference snapshot and applied through repo-owned helper commands.

The normal docs build, chezmoi apply, package upgrade path, and asset refresh path must not apply or re-apply visible desktop settings.

Safety Rules

1. status, plan, diff-breeze-reference, and audit-upstream style commands are read-only.
2. capture-breeze-reference writes only local user-state reference snapshots; it does not change live KDE settings.
3. Live reset, panel restore, full reference restore, rollback, and backup-restore commands refuse to run without a backup manifest.
4. Appearance reset and panel reset are separate scopes; panel reset requires --reset-panels.
5. SDDM/login theming is a later optional phase, not part of the Breeze safety baseline.
6. Plymouth/boot splash is out of scope for KDE reset and rollback.
7. WSL and Windows lanes must remain unaffected.

Backup Location

Before reset-breeze, apply-theme, apply-layout, rollback, or reference file restore writes user config, run:

dotfiles-cachyos-theme backup

The command creates a timestamped backup under:

~/.local/state/dotfiles/plasma-backups/YYYYMMDD-HHMMSS/

Candidate files to back up before mutation:

~/.config/kdeglobals
~/.config/kwinrc
~/.config/plasmarc
~/.config/plasmashellrc
~/.config/plasma-org.kde.plasma.desktop-appletsrc
~/.config/kcminputrc
~/.config/ksplashrc
~/.config/Kvantum/kvantum.kvconfig
~/.config/gtk-3.0/settings.ini
~/.config/gtk-4.0/settings.ini
~/.config/mimeapps.list

The backup command records which files existed, which were copied, and which were absent in manifest.tsv. Absence is normal, not an error. Use:

dotfiles-cachyos-theme backup --dry-run

The backup command does not apply a theme, change panels, write Flatpak overrides, touch SDDM, or touch boot/session infrastructure.

Breeze Reference

Capture the manually restored Breeze Dark reference:

dotfiles-cachyos-theme capture-breeze-reference --dry-run
dotfiles-cachyos-theme capture-breeze-reference

Snapshots are written under:

~/.local/state/dotfiles/kde-reference/snapshots/

~/.local/state/dotfiles/kde-reference/current points to the active reference. Use --force only if a non-symlink current path must be replaced.

Inspect drift:

dotfiles-cachyos-theme diff-breeze-reference
dotfiles-cachyos-theme diff-breeze-reference --reference latest
dotfiles-cachyos-theme diff-breeze-reference --reference /path/to/reference

The diff command reports stable key drift and file-level same/different/missing summaries. It does not print full config file contents.

Breeze Reset

Default Breeze Dark reset:

dotfiles-cachyos-theme reset-breeze --appearance dark --dry-run
dotfiles-cachyos-theme reset-breeze --appearance dark --backup latest

Reference-derived reset:

dotfiles-cachyos-theme reset-breeze --appearance dark --from-reference latest --dry-run
dotfiles-cachyos-theme reset-breeze --appearance dark --from-reference latest --backup latest

The appearance reset uses KDE commands and selected key writes for the user session. It sets Breeze Dark colour, Plasma desktop theme, KDE widget style, GTK settings, icons, cursor, KWin decoration, and right-side KWin buttons. It does not use Kvantum as the Breeze widget style.

Wallpaper, fonts, and display scaling remain manual unless a later decision adds a safe user-level scope.

Panel Reset

Panel reset is opt-in because broken panel state has a larger recovery cost than appearance settings.

dotfiles-cachyos-theme reset-breeze --appearance dark --from-reference latest --reset-panels --dry-run
dotfiles-cachyos-theme reset-breeze --appearance dark --from-reference latest --reset-panels --backup latest

The command restores captured plasmashellrc and plasma-org.kde.plasma.desktop-appletsrc from the reference snapshot after a backup exists. It does not synthesize a new panel layout, use Latte Dock, run the old MacTahoe/macOS-like layout, or restart Plasma automatically.

After a live panel restore, logout/login or manually restart Plasma if the session does not pick up panel changes. Do not restart SDDM automatically.

Full Reference File Restore

Full reference file restore is not the default. Use it only when the exact captured reference files are the desired recovery target:

dotfiles-cachyos-theme reset-breeze --appearance dark --from-reference latest --restore-reference-files --dry-run
dotfiles-cachyos-theme reset-breeze --appearance dark --from-reference latest --restore-reference-files --backup latest

This restores only the captured allowlist under the user config directory. It does not touch SDDM/login, Plymouth/boot splash, root-owned files, package state, wallpaper, fonts, display scaling, or Flatpak overrides.

Backup Restore

Return to the exact pre-reset backup:

dotfiles-cachyos-theme restore-backup latest --dry-run
dotfiles-cachyos-theme restore-backup latest

Or restore a named timestamp:

dotfiles-cachyos-theme restore-backup YYYYMMDD-HHMMSS --dry-run
dotfiles-cachyos-theme restore-backup YYYYMMDD-HHMMSS

restore-backup restores files recorded by the backup manifest under $HOME only. It does not restart Plasma, change SDDM/login, or touch system boot or session configuration.

SDDM And Boot Boundary

Login theming has a higher recovery cost and usually requires root-owned files. It stays out of the normal KDE safety baseline.

A later SDDM phase needs its own:

• Read-only plan output.
• Privilege model.
• Backup command.
• Rollback command.
• Manual logout/login validation.
• TTY recovery note.

It must not change display-manager service state, autologin, GPU/session configuration, Plymouth, boot splash, GRUB, kernel, driver, PRIME, or initramfs settings.

Manual Validation For Later Applies

After a future live reset, validate the touched phase directly:

• Confirm Breeze Dark is selected for KDE appearance.
• Open a common KDE app, a GTK app, and a browser or Electron-style app.
• Confirm KWin decoration and right-side window buttons.
• Confirm cursor theme.
• Confirm KRunner, System Settings, terminal access, and app launching.
• Confirm panels only after an explicit --reset-panels command.
• Logout/login after desktop theme or panel changes and confirm the session is still usable.
• Confirm WSL and Windows renders remain unchanged.