chore: bootstrap project scaffold

AGENTS.md

@@ -0,0 +1,36 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `main.py` wires the GTK `Application`; 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` and styles in `styles.css`; 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 in development mode; pass `--mock-ollama` when iterating without a local model.
+- `pytest` — runs the full test suite; combine with `pytest -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`.
+- 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.