MangoTune — Agent Master Plan

Project Summary

MangoTune is a GTK4 + libadwaita desktop application written in Rust for Linux. It is a superior replacement for GOverlay — a GUI configurator for MangoHud, with first-class support for config conflict detection, strict validation, visual config-layer stacking (like CSS cascade), live preview via test launchers, and integrations with GameMode, Steam, Lutris, and Heroic Games Launcher.

Agent Instructions — READ FIRST

Read this file completely before doing anything.
Read docs/architecture.md for the full module map and dependency graph.
Read docs/mangohud_schema.md for the complete MangoHud option reference.
Read docs/design_system.md for all UI/UX rules and GTK4 widget patterns.
Read phases/phase_XX.md for the specific phase you are implementing.
Each module has its own spec file in modules/. Read the relevant spec before writing code.
Never modify files outside your assigned phase without noting it in a comment block.
After completing a phase, verify against the acceptance criteria in that phase file.

Directory Layout (this plan repo)

mangotune-plan/
├── README.md                  ← YOU ARE HERE — read first
├── docs/
│   ├── architecture.md        ← module map, crate deps, file tree
│   ├── mangohud_schema.md     ← every MangoHud config option, types, constraints
│   ├── config_resolution.md   ← how MangoHud config files are discovered & prioritized
│   ├── design_system.md       ← GTK4/libadwaita UI rules, widget patterns, UX decisions
│   └── integrations.md        ← GameMode, Steam, Lutris, Heroic specs
├── modules/
│   ├── config_parser.md       ← parser/writer module spec
│   ├── config_schema.md       ← schema/type system module spec
│   ├── config_validator.md    ← validation engine module spec
│   ├── config_resolver.md     ← multi-file conflict resolver module spec
│   ├── system_detect.md       ← system detection module spec
│   ├── launcher.md            ← test launcher module spec
│   └── ui_pages.md            ← all UI page/widget specs
├── phases/
│   ├── phase_01.md            ← Project scaffold, Cargo.toml, build system
│   ├── phase_02.md            ← Config parser + schema + validator (no UI)
│   ├── phase_03.md            ← Config resolver + system detection (no UI)
│   ├── phase_04.md            ← GTK4 app skeleton, main window, navigation
│   ├── phase_05.md            ← Performance & GPU/CPU pages (core UI)
│   ├── phase_06.md            ← Appearance, layout, colors, typography pages
│   ├── phase_07.md            ← Conflict resolver UI (cascade stack view)
│   ├── phase_08.md            ← Keybindings, logging, FPS limits pages
│   ├── phase_09.md            ← Test launcher (vkcube, glxgears, custom)
│   ├── phase_10.md            ← Integrations (GameMode, Steam, Lutris, Heroic)
│   └── phase_11.md            ← Polish, packaging, .desktop file, final QA
└── ui/
    ├── widget_toggle.md       ← toggle switch widget spec
    ├── widget_color.md        ← color picker widget spec
    ├── widget_hotkey.md       ← hotkey capture widget spec
    ├── widget_cascade.md      ← config cascade/layer stack widget spec
    └── widget_validation.md   ← inline validation error display spec

Target Source Tree (the actual Rust project)

mangotune/
├── Cargo.toml
├── Cargo.lock
├── build.rs
├── data/
│   ├── com.mangotune.MangoTune.gschema.xml
│   ├── com.mangotune.MangoTune.desktop
│   └── icons/
│       └── com.mangotune.MangoTune.svg
├── src/
│   ├── main.rs                ← entry point only — app init + run
│   ├── app.rs                 ← Application struct, GtkApplication setup
│   ├── window.rs              ← MainWindow: AdwApplicationWindow
│   ├── config/
│   │   ├── mod.rs
│   │   ├── parser.rs          ← read/write .conf files, preserve comments
│   │   ├── schema.rs          ← typed schema: all ~120 MangoHud options
│   │   ├── validator.rs       ← validation logic, dependency checks
│   │   ├── resolver.rs        ← discover all config files, build priority stack
│   │   └── types.rs           ← shared enums/structs (ConfigValue, OptionType, etc.)
│   ├── system/
│   │   ├── mod.rs
│   │   ├── detect.rs          ← detect MangoHud version, tools, GPU, display server
│   │   └── paths.rs           ← XDG path resolution, known config locations
│   ├── launcher/
│   │   ├── mod.rs
│   │   └── runner.rs          ← spawn vkcube/glxgears/custom with MANGOHUD=1
│   ├── integrations/
│   │   ├── mod.rs
│   │   ├── gamemode.rs
│   │   ├── steam.rs
│   │   ├── lutris.rs
│   │   └── heroic.rs
│   └── ui/
│       ├── mod.rs
│       ├── pages/
│       │   ├── mod.rs
│       │   ├── overview.rs
│       │   ├── performance.rs
│       │   ├── gpu.rs
│       │   ├── cpu.rs
│       │   ├── memory.rs
│       │   ├── io_network.rs
│       │   ├── media_player.rs
│       │   ├── battery.rs
│       │   ├── appearance.rs
│       │   ├── colors.rs
│       │   ├── typography.rs
│       │   ├── keybindings.rs
│       │   ├── fps_limits.rs
│       │   ├── logging.rs
│       │   ├── blacklist.rs
│       │   ├── opengl_quirks.rs
│       │   ├── raw_editor.rs
│       │   └── conflicts.rs
│       └── widgets/
│           ├── mod.rs
│           ├── toggle_row.rs
│           ├── color_row.rs
│           ├── hotkey_row.rs
│           ├── cascade_view.rs
│           ├── validation_label.rs
│           └── launch_bar.rs

Core Design Principles

Strict validation — the Save button is disabled if any field contains an invalid value. Inline error labels appear below each offending field. No config is written to disk in an invalid state under any circumstances.
Comment preservation — the parser round-trips existing files preserving all comments, whitespace, and ordering. Only changed lines are modified.
Dependency awareness — the schema encodes option dependencies (e.g. gpu_mem_clock requires vram=1). Enabling a dependent option auto-enables its parent and shows a notice.
Config cascade visibility — the conflict page shows all detected config files as a vertical stack ordered by MangoHud's actual priority (env > app-local > per-app XDG > global). Each option that is overridden shows which file wins and which files are shadowed.
No hardcoded paths — all paths resolve via XDG spec, $HOME, and runtime detection.
Graceful degradation — if MangoHud is not installed, the app opens but shows a clear install prompt. Missing optional tools (vkcube, glxgears, GameMode) are indicated per-feature, not as global errors.

Key Differentiators vs GOverlay

Feature	GOverlay	MangoTune
Config conflict detection	None	Visual cascade
Option dependency validation	None	Full schema
Comment preservation	Destroys them	Preserved
Multi-file editing	Global only	All layers
Strict type validation	None	Blocks save
Wayland support	Broken	Native GTK4
HiDPI	Buggy	GTK4 native
XDG compliance	Fixed in v1.7	From day one
Toolkit	Qt (AppImage)	GTK4/Adwaita
Live test launcher	vkcube only	vkcube+glx+custom