# Repository Guidelines

## Project Structure & Module Organization
- `main.py` wires the GTK `Application` and guards headless runs; UI widgets live in `sidebar_window.py` and `message_widget.py`.
- `ollama_client.py` wraps streaming calls and threading helpers so GTK stays responsive.
- Conversation state persists through `conversation_manager.py` and JSON files under `data/conversations/`; keep writes atomic.
- Shared settings belong in `config.py`, styles in `styles.css`, and tooling defaults in `pyproject.toml`; prefer adding focused modules over bloating these.
- Tests mirror the source tree under `tests/`, with fixtures in `tests/fixtures/` for reusable transcripts and metadata.

## Build, Test, and Development Commands
- `python -m venv .venv && source .venv/bin/activate` — creates and activates the project’s virtual environment.
- `pip install -r requirements.txt` — installs GTK, Ollama, and tooling dependencies.
- `python main.py` — launches the sidebar; requires a Wayland/X11 session.
- `AI_SIDEBAR_HEADLESS=1 python main.py` — skips GTK startup for CI smoke checks.
- `AI_SIDEBAR_HEADLESS=1 pytest` — runs the full test suite; combine with `-k "conversation"` for targeted checks.

## Coding Style & Naming Conventions
- Use 4-space indentation and format with `black .`; avoid tab characters.
- Lint via `ruff check .` and fix violations instead of adding ignores.
- Files stay snake_case; classes use PascalCase; callbacks adopt verb-based snake_case (e.g., `handle_stream_chunk`).
- Keep GTK signal handlers thin and delegate behavior to helpers or managers.

## Testing Guidelines
- Prefer `pytest` parameterized cases for conversation flows; store golden transcripts in `tests/fixtures/responses/`.
- Name tests `test_<module>_<behavior>` (e.g., `test_conversation_manager_persists_history`).
- Cover threading boundaries by mocking Ollama responses and asserting GTK updates via `GLib.idle_add`.
- Use `AI_SIDEBAR_HEADLESS=1` when exercising tests or scripts in non-GUI environments.
- Run `pytest --maxfail=1` before commits to catch regressions early.

## Commit & Pull Request Guidelines
- Follow the Conventional Commit pattern (`feat:`, `fix:`, `refactor:`) to keep the changelog clean.
- Keep commits scoped to a single concern and include tests or fixtures when changing behavior.
- Pull requests should summarize user-facing changes, list manual test steps, and attach screenshots or recordings for UI tweaks.
- Reference related issues with `Closes #ID` and call out follow-up tasks to keep planning clear.

## Agent Workflow Tips
- When prototyping new UI flows, add exploratory scripts under `experiments/` and clean them up before merging.
- Document new configuration toggles in `config.py` docstrings and echo them in the README so users can discover them easily.