# Repository Guidelines

## Project Structure & Module Organization

`HarmonyWinUI/` contains the unpackaged WinUI 3 application targeting .NET 8. Application startup and the main shell live in `App.xaml*` and `MainWindow.xaml*`. Put navigable views and their code-behind in `HarmonyWinUI/Pages/`, domain and service classes in `HarmonyWinUI/Models/`, and packaged images in `HarmonyWinUI/Assets/`. Publish settings are under `HarmonyWinUI/Properties/PublishProfiles/`. The root `vendor/` directory holds external tools such as `yt-dlp` and FFmpeg; treat downloaded media and temporary files there as local artifacts. Generated `bin/`, `obj/`, and `.vs/` content must not be edited or committed.

## Build, Test, and Development Commands

Run commands from the repository root:

```powershell
dotnet restore HarmonyWinUI/HarmonyWinUI.slnx
dotnet build HarmonyWinUI/HarmonyWinUI.csproj -c Debug -p:Platform=x64
dotnet run --project HarmonyWinUI/HarmonyWinUI.csproj -c Debug -r win-x64
dotnet publish HarmonyWinUI/HarmonyWinUI.csproj -c Release -r win-x64
```

Restore downloads NuGet dependencies; build compiles C# and XAML; run launches the unpackaged x64 app; publish creates the self-contained release output. ARM64 is also supported by replacing `x64`/`win-x64` with `ARM64`/`win-arm64`.

## Coding Style & Naming Conventions

Follow `HarmonyWinUI/.editorconfig`: tabs with width 4, LF endings, braces for blocks, nullable reference types, and `using` directives outside namespaces. Use PascalCase for types, properties, events, and methods; prefix interfaces with `I`. Keep UI concerns in `Pages` or XAML and network/process logic in `Models`. Never edit generated `*.g.cs` or `*.g.i.cs` files.

## Testing Guidelines

No automated test project currently exists. Every change must at least pass the x64 Debug build. Manually verify affected navigation, MusicBrainz search and Retry/Cancel behavior, playlist resizing, and vendor executable discovery as applicable. Add future tests in a separate `HarmonyWinUI.Tests` project and name cases `Method_Scenario_ExpectedResult`.

## Commit & Pull Request Guidelines

History favors short, single-purpose messages such as `added play list into right column` and `implemented search artists in MusicBrainz`. Keep commits focused and use a concise imperative summary. Pull requests should explain behavior changes, list build/manual-test results, link relevant issues, and include before/after screenshots for UI changes. Do not include `.user` files, downloaded media, FFmpeg archives, credentials, or machine-specific publish settings.