1. Product mission

Build a control plane for a user's existing Linux desktop. The application must not require the user to adopt a specific dotfile distribution, shell, bar, terminal, launcher, notification daemon, or theme system.

2. Non-negotiable product principles

3. Scope and product boundaries

V1 should solve the configuration problems most specific to modular Wayland desktops. Do not begin by rebuilding GNOME Settings.

4. UX expectations

• Use a desktop-settings information architecture: persistent sidebar, section detail view, search.
• Controls should map to semantic concepts, not configuration syntax.
• Use immediate preview only when safe; otherwise require Apply.
• Any destructive or session-impacting action must clearly explain impact before execution.
• Search should find both human terms (“rounded corners”) and underlying concepts (rounding).
• Unavailable settings must explain why they are unavailable instead of silently disappearing when that would confuse the user.

5. System architecture

┌──────────────────────────────────────────────────────┐
│                    Presentation                      │
│                                                      │
│        Desktop GUI                  CLI               │
└──────────────┬───────────────────────┬───────────────┘
               │                       │
               └───────────┬───────────┘
                           ▼
┌──────────────────────────────────────────────────────┐
│                  Settings Core                       │
│                                                      │
│ read · validate · diff · apply · snapshot · restore │
│ profiles · discovery · dependency graph · events    │
└──────────────┬───────────────────────┬───────────────┘
               │                       │
      ┌────────▼────────┐      ┌──────▼────────┐
      │ Desktop adapters│      │ App plugins   │
      │                 │      │               │
      │ Hyprland        │      │ Alacritty     │
      │ Hypridle        │      │ Yazi          │
      │ Hyprlock        │      │ Waybar        │
      │ Wallpaper       │      │ Quickshell    │
      └────────┬────────┘      └──────┬────────┘
               │                       │
               └───────────┬───────────┘
                           ▼
                   Files / IPC / DBus
                   system commands
                   runtime sockets

6. Canonical settings model

Internally, settings should be represented independently of any target application's file format.

{
  "path": "desktop.hyprland.general.gaps_out",
  "type": "integer",
  "value": 10,
  "default": 5,
  "constraints": { "min": 0, "max": 100 },
  "source": "hyprland",
  "restartPolicy": "reload",
  "managed": true,
  "dirty": false
}

Every setting definition should support, where applicable:

• Stable ID/path.
• Display label and description.
• Type: boolean, integer, float, string, enum, color, file, directory, command, keybinding, list, object.
• Default value and current resolved value.
• Validation constraints.
• Visibility conditions and dependency conditions.
• Restart/reload requirements.
• Source plugin/adapter.
• Whether the value is user-owned, generated, inherited or unmanaged.

7. Configuration safety model

This is the most important engineering requirement in the entire project.

Preferred strategy: generated override fragments

~/.config/hypr/hyprland.conf
  ├─ user's normal configuration
  └─ source = ~/.config/modular-settings/generated/hyprland.conf

~/.config/modular-settings/
  ├─ state/
  ├─ generated/
  │   ├─ hyprland.conf
  │   ├─ theme/
  │   └─ ...
  ├─ snapshots/
  ├─ profiles/
  └─ plugins/

Mutation transaction

1. Read current state.
2. Validate proposed state.
3. Generate output into a temporary file.
4. Validate generated configuration with the target adapter where possible.
5. Create snapshot of currently managed output.
6. Atomically replace generated file.
7. Request target reload.
8. Verify success.
9. If verification fails, restore snapshot automatically.
10. Return structured success/error information to GUI/CLI.

Required backup behavior

• Automatic snapshots before every write transaction.
• Retention policy configurable; reasonable default such as last 20 snapshots per component.
• Named manual snapshots.
• Full profile/export snapshots.
• One-click rollback from GUI and CLI.

8. Plugin system

The plugin framework is a first-class product feature, not an implementation detail. The core team should not need to hard-code every Linux application.

plugin/
├─ plugin.toml
├─ schema.json
├─ icon.svg
├─ adapter
│  └─ ...
├─ migrations/
└─ README.md

Example manifest

id = "alacritty"
name = "Alacritty"
version = "1.0.0"
api_version = 1

[detect]
binary = "alacritty"
config = "~/.config/alacritty/alacritty.toml"

[capabilities]
read = true
write = true
preview = false
reload = false

Example schema concept

{
  "groups": [
    {
      "id": "font",
      "label": "Font",
      "settings": [
        {
          "id": "font.size",
          "type": "number",
          "label": "Font Size",
          "min": 6,
          "max": 36,
          "step": 0.5
        }
      ]
    }
  ]
}

Plugin API requirements

• detect() — determine whether plugin is applicable.
• read() — resolve current values.
• validate() — validate requested changes.
• plan() — produce a human-readable mutation plan/diff.
• apply() — perform a transaction through core-provided safe filesystem primitives.
• reload() — reload target when possible.
• health() — provide diagnostic status.

9. Theme engine

Themes should use semantic tokens, then adapters map those tokens into target applications.

[meta]
name = "Everforest Dark"

[colors]
background = "#272e33"
surface = "#2e383c"
surface_alt = "#374145"
foreground = "#d3c6aa"
muted = "#859289"

accent = "#a7c080"
accent_alt = "#83c092"

red = "#e67e80"
orange = "#e69875"
yellow = "#dbbc7f"
green = "#a7c080"
blue = "#7fbbb3"
purple = "#d699b6"

Theme targets should be opt-in per application. A user must be able to apply a desktop theme without forcing their editor or terminal to change.

• Hyprland border/colors.
• GTK and Qt where safely supported.
• Terminal emulators.
• Waybar / Quickshell.
• Rofi / launchers.
• Mako / SwayNC.
• Hyprlock.
• Yazi.
• Optional adapters for Neovim and other developer tools.

10. Settings modules

11. CLI requirements

# inspection
mlsettings get desktop.hyprland.general.gaps_out
mlsettings list
mlsettings plugins list
mlsettings doctor

# writes
mlsettings set desktop.hyprland.general.gaps_out 10
mlsettings theme apply everforest
mlsettings wallpaper set ~/Pictures/wallpaper.png

# profiles
mlsettings profile list
mlsettings profile apply gaming

# safety
mlsettings diff
mlsettings snapshot create before-rice-change
mlsettings snapshot list
mlsettings snapshot restore <id>

# debugging
mlsettings config paths
mlsettings logs
mlsettings plugin inspect alacritty

The CLI should support machine-readable output, preferably --json, so shell scripts and external tools can integrate with the settings core.

12. Profiles

Profiles are named bundles of settings and optional runtime actions.

profiles/
├─ laptop.toml
├─ desk.toml
├─ gaming.toml
└─ presentation.toml

Profile application must itself be transactional: either all applicable changes succeed, or failed operations are reported and rollback occurs according to component safety policies.

13. Desktop discovery

First launch should inspect the system and construct a settings interface relevant to the current machine.

Desktop scan
────────────────────
Hyprland       detected
Hyprlock       detected
Hypridle       detected
Quickshell     detected
Alacritty      detected
Yazi           detected
Mako           not installed
Waybar         not installed
Matugen        not installed

Discovery should inspect:

• Available binaries in PATH.
• Known config locations.
• Hyprland runtime environment and IPC/socket availability.
• User services where relevant.
• Optional dependencies required by plugins.

Discovery results must be cached but refreshable. The application must tolerate software being installed or removed while it is running.

14. Recommended implementation stack

15. Repository layout

modular-linux-settings/
├─ Cargo.toml
├─ README.md
├─ LICENSE
├─ docs/
│  ├─ architecture.md
│  ├─ plugin-api.md
│  ├─ config-safety.md
│  └─ contributing.md
├─ crates/
│  ├─ core/
│  ├─ cli/
│  ├─ gui/
│  ├─ plugin-sdk/
│  ├─ config-io/
│  ├─ snapshots/
│  └─ diagnostics/
├─ adapters/
│  ├─ hyprland/
│  ├─ hypridle/
│  ├─ hyprlock/
│  └─ wallpaper/
├─ plugins/
│  ├─ alacritty/
│  ├─ yazi/
│  ├─ waybar/
│  └─ quickshell/
├─ themes/
│  ├─ everforest/
│  └─ example/
├─ fixtures/
│  ├─ hyprland/
│  ├─ alacritty/
│  └─ yazi/
├─ packaging/
│  ├─ arch/
│  └─ flatpak/   # optional later, assess permission constraints first
└─ scripts/

16. Implementation phases

17. Testing requirements

Unit tests

• Schema validation.
• Setting resolution.
• Theme token mapping.
• Conflict detection.
• Snapshot rotation.
• Path expansion and safe-path checks.

Fixture tests

Every adapter/plugin should include real-world configuration fixtures:

fixtures/hyprland/
├─ minimal.conf
├─ sourced-files.conf
├─ comments-heavy.conf
├─ unusual-formatting.conf
├─ duplicate-settings.conf
└─ invalid.conf

Transaction tests

• Write succeeds → reload succeeds.
• Write succeeds → reload fails → rollback occurs.
• Disk full / permission denied.
• Plugin crashes during plan/apply.
• Configuration changed externally between read and apply.

GUI tests

• Keyboard navigation.
• Search.
• Validation states.
• Apply/revert behavior.
• Unavailable dependency states.
• Dynamic plugin installation/removal.

18. Security and privilege rules

• Run entirely as the user by default.
• Never run the whole GUI as root.
• Use privilege escalation only for a narrowly scoped action that actually requires it.
• Never interpolate untrusted strings into shell commands.
• Prefer direct process execution with argument arrays instead of sh -c.
• Resolve and validate filesystem paths before writes.
• Plugins must declare capabilities.
• Third-party plugin code must be considered untrusted.
• Do not transmit configuration data off-device unless the user explicitly enables a future cloud feature.

19. MVP release criteria

The project is not ready for a public MVP until all of the following are true:

• Installs cleanly on a fresh Arch + Hyprland environment.
• Launches without requiring root.
• Detects Hyprland and relevant supported components.
• Can configure appearance, core Hyprland options, displays and keybindings.
• Supports at least three app/component plugins.
• All managed writes are atomic or transactional.
• Automatic snapshots and rollback work.
• Externally edited configs are detected instead of silently overwritten.
• GUI and CLI produce the same resulting state.
• Application remains usable if one plugin fails.
• Logs contain enough context to debug failures without exposing secrets.
• Documentation explains exactly which files the application owns.
• Uninstalling the program does not destroy the user's original configuration.

20. Instructions for the implementation agent

1. Work phase-by-phase. Do not start later modules before the current phase's exit criterion works.
2. Keep the project buildable. Every meaningful commit should compile and tests should pass.
3. Do not invent APIs silently. Document important domain interfaces and plugin contracts as they are introduced.
4. No destructive whole-file rewrites. Use generated overrides or verified lossless transformations.
5. Never modify unrelated settings. One requested change must produce the narrowest possible mutation.
6. Back up before writes. Every managed mutation participates in snapshot/transaction infrastructure.
7. Separate domain logic from UI. The GUI is a client of the Settings Core.
8. Prefer structured process execution. Avoid shell strings.
9. Do not introduce a background daemon unless required by a demonstrated feature.
10. Do not add cloud services, telemetry or accounts in MVP.
11. Do not bundle opinionated dotfiles. Example themes/plugins are acceptable; replacing the user's desktop is not.
12. Do not assume Waybar/Kitty/Rofi/etc. Detect components and populate UI dynamically.
13. Support external edits. Detect file changes and reconcile/refresh rather than overwriting stale state.
14. Return structured errors. The UI must be able to distinguish validation, permission, missing dependency, parse, reload and rollback failures.
15. Add tests with each adapter feature. A new config mutation without regression fixtures is incomplete.
16. Keep public plugin APIs versioned. Avoid breaking third-party plugins without an explicit migration/version strategy.
17. Document ownership. Every generated file must have a visible header where the target format permits comments.
18. Implement diagnostics early. Every adapter should expose detection and health information useful to doctor.
19. Design for future compositor adapters, but implement Hyprland first. Do not prematurely build abstractions that have no Hyprland use.
20. When uncertain, preserve the user's current working desktop. Safety is more important than applying a requested cosmetic change.

Required agent progress reporting

At the end of each implementation phase, produce:

• What was implemented.
• Files/modules added or changed.
• Tests added and their status.
• Known limitations.
• Manual verification steps.
• Whether the phase exit criterion is fully met.
• Any architecture decision that deviated from this specification and the reason.

21. Definition of long-term success

The project succeeds when an Arch/Hyprland user can adopt it without surrendering control of their desktop, and a plugin author can add support for another application without changing the core application.