# 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 and watches for file changes.
- `common/Directories.qml`: Defines XDG and repository-specific file paths.
- `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
- *TBD*: Check for build/lint/test commands (e.g., `npm`, `make`, or direct `quickshell` execution).