AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization
- `navipy.py` boots the PySide6 desktop client, wires logging, and discovers modules under `src/`.
- `src/api/` holds the Subsonic client, auth helpers, and data models that talk to your Navidrome server.
- `src/accessibility/` and `src/widgets/` contain custom Qt widgets and dialogs with accessibility metadata; `src/main_window.py` composes them.
- `src/config/settings.py` manages XDG-compliant config/data/cache dirs and persists `settings.json` and `servers.json`.
- `sounds/` ships UI audio assets; runtime logs land in `~/.local/share/navipy/navipy.log`.

## Build, Test, and Development Commands
- `python3 -m venv .venv && source .venv/bin/activate` — set up an isolated environment.
- `pip install -r requirements.txt` — install PySide6 and other runtime deps.
- `python3 navipy.py` — launch the app with logging to the data dir; exit cleanly with Ctrl+C.
- `pytest -q` — run the automated test suite; run this after major code changes.

## Coding Style & Naming Conventions
- Follow PEP 8: 4-space indentation, snake_case modules/functions, and descriptive class names for Qt widgets/actions.
- Keep accessibility in mind: set `setAccessibleName` on interactive widgets, and keep shortcuts consistent with existing ones in `MainWindow`.
- Prefer type hints for public APIs in `api/` and configuration helpers; keep JSON keys predictable and lowercase.

## Testing Guidelines
- Automated `pytest` suite lives under `tests/`; keep new tests named `test_<feature>.py` and prefer fixtures/fakes over live Navidrome.
- Run `pytest -q` after major code changes; set `QT_QPA_PLATFORM=offscreen` if adding Qt-dependent tests.
- Manual checks still matter: verify keyboard-only navigation, high-DPI rendering, and that logs/config are written under the XDG directories.

## Commit & Pull Request Guidelines
- Write imperative, scoped commit subjects (e.g., "Add server dialog validation"), keep to ~72 chars, and describe user-facing impact in the body when needed.
- PRs should list the change summary, test results or manual checks, linked issues, and UI screenshots/GIFs for visible tweaks.
- Call out accessibility-affecting changes, config migrations, or new dependencies so reviewers can double-check regressions.

## Security & Configuration Tips
- Never log server credentials; `servers.json` under `~/.config/navipy/` stores secrets—treat it as sensitive and avoid committing it.
- Respect `XDG_*` overrides in tests and scripts to avoid polluting real user data; prefer temporary dirs when experimenting.
- Keep error messages informative but redacted; sanitize Navidrome responses before logging.
Initial commit 2025-12-15 04:09:55 -05:00			`# Repository Guidelines`

			`## Project Structure & Module Organization`
			- `navipy.py` boots the PySide6 desktop client, wires logging, and discovers modules under `src/`.
			- `src/api/` holds the Subsonic client, auth helpers, and data models that talk to your Navidrome server.
			- `src/accessibility/` and `src/widgets/` contain custom Qt widgets and dialogs with accessibility metadata; `src/main_window.py` composes them.
			- `src/config/settings.py` manages XDG-compliant config/data/cache dirs and persists `settings.json` and `servers.json`.
			- `sounds/` ships UI audio assets; runtime logs land in `~/.local/share/navipy/navipy.log`.

			`## Build, Test, and Development Commands`
			- `python3 -m venv .venv && source .venv/bin/activate` — set up an isolated environment.
			- `pip install -r requirements.txt` — install PySide6 and other runtime deps.
			- `python3 navipy.py` — launch the app with logging to the data dir; exit cleanly with Ctrl+C.
Cache system added using sqlite. Should be nicer to the server. 2025-12-16 22:47:43 -05:00			- `pytest -q` — run the automated test suite; run this after major code changes.
Initial commit 2025-12-15 04:09:55 -05:00
			`## Coding Style & Naming Conventions`
			`- Follow PEP 8: 4-space indentation, snake_case modules/functions, and descriptive class names for Qt widgets/actions.`
			- Keep accessibility in mind: set `setAccessibleName` on interactive widgets, and keep shortcuts consistent with existing ones in `MainWindow`.
			- Prefer type hints for public APIs in `api/` and configuration helpers; keep JSON keys predictable and lowercase.

			`## Testing Guidelines`
Cache system added using sqlite. Should be nicer to the server. 2025-12-16 22:47:43 -05:00			- Automated `pytest` suite lives under `tests/`; keep new tests named `test_<feature>.py` and prefer fixtures/fakes over live Navidrome.
			- Run `pytest -q` after major code changes; set `QT_QPA_PLATFORM=offscreen` if adding Qt-dependent tests.
Initial commit 2025-12-15 04:09:55 -05:00			`- Manual checks still matter: verify keyboard-only navigation, high-DPI rendering, and that logs/config are written under the XDG directories.`

			`## Commit & Pull Request Guidelines`
			`- Write imperative, scoped commit subjects (e.g., "Add server dialog validation"), keep to ~72 chars, and describe user-facing impact in the body when needed.`
			`- PRs should list the change summary, test results or manual checks, linked issues, and UI screenshots/GIFs for visible tweaks.`
			`- Call out accessibility-affecting changes, config migrations, or new dependencies so reviewers can double-check regressions.`

			`## Security & Configuration Tips`
			- Never log server credentials; `servers.json` under `~/.config/navipy/` stores secrets—treat it as sensitive and avoid committing it.
			- Respect `XDG_*` overrides in tests and scripts to avoid polluting real user data; prefer temporary dirs when experimenting.
			`- Keep error messages informative but redacted; sanitize Navidrome responses before logging.`