mangotune/docs/plan/README.md

# 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

1. Read this file completely before doing anything.
2. Read `docs/architecture.md` for the full module map and dependency graph.
3. Read `docs/mangohud_schema.md` for the complete MangoHud option reference.
4. Read `docs/design_system.md` for all UI/UX rules and GTK4 widget patterns.
5. Read `phases/phase_XX.md` for the specific phase you are implementing.
6. Each module has its own spec file in `modules/`. Read the relevant spec before writing code.
7. Never modify files outside your assigned phase without noting it in a comment block.
8. 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 |