# Agent Guidance: Quickshell Project

## Core Architecture
- **Type**: Quickshell/QML based UI.
- **State Management**: Heavily reliant on QML Singletons for global state, configuration, and paths.
- **Main Entry**: `shell.qml`.

## Key Singletons
- `GlobalStates.qml`: Manages global UI visibility (e.g., `mediaControlsOpen`, `notificationPanelOpen`).
- `common/Config.qml`: Manages JSON configuration at `${XDG_CONFIG_HOME}/hydro-os/config.json` and watches for file changes.
- `common/Directories.qml`: Defines XDG and repository-specific file paths (e.g., `${XDG_CONFIG_HOME}/hydro-os/color.json`).
- `common/Appearance.qml`: Handles theme, colors, and transparency.

## Component Structure
- `bar/`: Top bar components.
- `osd/`: On-screen display components.
- `background/`: Background/Wallpaper components.
- `common/`: Shared utility and singleton components.
- `settings/`: Settings/Configuration components.
- `settings.qml`: Settings view entry point.

## Development Workflow
- **Logs**: Run `quickshell log` and read only after the last "INFO: Reloading configuration..."
- **Config**: Configuration files are located in `${XDG_CONFIG_HOME}/hydro-os/` and may be auto-created by the application.