# Repository Guidelines

## Project Structure & Modules
- Solution: `v2rayN/v2rayN.sln` (C#/.NET 8)
- Apps: `v2rayN/v2rayN` (Windows WPF), `v2rayN/v2rayN.Desktop` (Avalonia cross‑platform)
- Core library: `v2rayN/ServiceLib` (models, services, `Resx` resources)
- Hotkeys: `v2rayN/GlobalHotKeys` (library + examples); tests in `GlobalHotKeys.Test`
- Artifacts: `v2rayN/Release/`, `v2rayN/publish/`, `build-output/`
- Packaging scripts (root): `package-*.sh`

## Build, Test, and Development
- Build all: `dotnet build v2rayN/v2rayN.sln -c Release`
- Run (Linux/macOS): `dotnet run --project v2rayN/v2rayN.Desktop -c Debug`
- Run (Windows): `dotnet run --project v2rayN/v2rayN -c Debug`
- Publish (examples):
  - Linux x64: `dotnet publish v2rayN/v2rayN.Desktop/v2rayN.Desktop.csproj -c Release -r linux-x64 --self-contained true -o v2rayN/Release/linux-64`
  - Windows x64: `dotnet publish v2rayN/v2rayN/v2rayN.csproj -c Release -r win-x64 -p:EnableWindowsTargeting=true -o v2rayN/Release/windows-64`
- Tests (NUnit): `dotnet test v2rayN/GlobalHotKeys/src/GlobalHotKeys.Test -c Release --collect:"XPlat Code Coverage"`

## Coding Style & Naming
- Formatting from `.editorconfig`: UTF-8, CRLF, spaces=4.
- C#: file‑scoped namespaces; System usings first; braces required; prefer `var` when type is apparent; PascalCase for types/members; fields/private locals use camelCase.
- Lint/format: `dotnet format` before pushing.
- XAML/Avalonia: keep views thin; move logic to ViewModels in `ServiceLib`/`*ViewModels`.

## Testing Guidelines
- Framework: NUnit with `GlobalHotKeys.Test`.
- Conventions: classes `*Tests`, methods `[Test]` with Arrange/Act/Assert; keep tests isolated and deterministic.
- Run locally with `dotnet test` and ensure coverage for hotkey registration/ID reuse.

## Commit & Pull Requests
- Commits: short imperative subject (e.g., "Fix…", "Update…"), optional scope, reference issues/PRs (e.g., `(#8123)`).
- PRs must include: problem summary, rationale, user impact, steps to verify, screenshots for UI, target OS/runtime.
- CI parity: changes must pass `dotnet build` and `dotnet test` locally; do not commit artifacts under `Release/` or `publish/`.

## Security & Configuration
- Do not commit secrets or downloaded core binaries; rely on packaging scripts/CI.
- Submodules: clone/update with `--recursive` when needed.
- Keep platform‑specific code isolated (Windows WPF vs Avalonia) to avoid regressions.

## Agent Notes
- Follow this file’s scope for style and layout; keep patches minimal and targeted.
- Prefer simplifying data flow over adding conditionals; avoid deep nesting.