# Repository Guidelines

## Project Structure & Module Organization
- `src/`: C# application code; organize by feature (e.g., `Audio`, `Services`, `Cli`) and keep platform interop isolated.
- `python/`: optional local model services (e.g., Whisper/Piper/XTTS runners) with `requirements.txt` and service entrypoints.
- `tests/`: unit/integration tests mirroring `src/` namespaces; add `fixtures/` for audio samples.
- `assets/models/`: downloaded or quantized STT/TTS models; keep README.md noting source, license, and hash.
- `docs/`: architecture notes, API contracts, and runbooks.

## Build, Test, and Development Commands
- `dotnet restore` / `dotnet build`: restore dependencies and compile the C# projects.
- `dotnet run --project src/App/App.csproj`: run the desktop app locally.
- `dotnet test`: execute test suite; add `/p:CollectCoverage=true` when coverage is required.
- `python -m venv .venv && .venv\\Scripts\\Activate.ps1 && pip install -r python/requirements.txt`: set up Python services.
- `python python/server.py`: start local model server (Whisper/Piper/XTTS) for offline STT/TTS.

## Coding Style & Naming Conventions
- C#: 4-space indent; `PascalCase` for public types/members, `camelCase` for locals/parameters, `_camelCase` for private fields; prefer expression-bodied members for brevity.
- Python: format with `black` (88 cols) and `isort`; snake_case for functions/variables, PascalCase for classes.
- Keep async flows explicit (`async`/`await`); avoid blocking audio threads. Add XML-docs on public APIs and service endpoints.

## Testing Guidelines
- Framework: xUnit for C#; `pytest` for Python helpers/services.
- Naming: mirror source namespace/module and suffix with `Tests` (e.g., `AudioCaptureTests.cs`, `test_transcriber.py`).
- Include fixtures for short WAV/PCM clips; verify latency and word-error-rate thresholds where applicable.
- Run `dotnet test` (and `pytest` if using Python services) before PRs; capture coverage when touching core audio pipelines.

## Commit & Pull Request Guidelines
- Commits: imperative, present tense (e.g., "Add streaming whisper adapter"); group related changes, avoid noisy vendor/model blobs.
- PRs: concise description, linked issue, test results, and notes on model/version changes or licensing. Include screenshots/CLI logs for UX changes.
- Document config changes (`appsettings.*`, `.env`, model paths) and update `docs/` if interfaces or endpoints change.