# Repository Guidelines

## Project Structure & Module Organization

- `src/aman.py` is the thin console/module entrypoint shim.
- `src/aman_cli.py` owns the main end-user CLI parser and dispatch.
- `src/aman_run.py` owns foreground runtime startup, tray wiring, and settings flow.
- `src/aman_runtime.py` owns the daemon lifecycle and runtime state machine.
- `src/aman_benchmarks.py` owns `bench`, `eval-models`, and heuristic dataset tooling.
- `src/aman_model_sync.py` and `src/aman_maint.py` own maintainer-only model promotion flows.
- `src/recorder.py` handles audio capture using PortAudio via `sounddevice`.
- `src/aman_processing.py` owns shared Whisper/editor pipeline helpers.
- `src/aiprocess.py` runs the in-process Llama-3.2-3B cleanup.
- `src/desktop_x11.py` encapsulates X11 hotkeys, tray, and injection.

## Build, Test, and Development Commands

- Install deps (X11): `python3 -m venv --system-site-packages .venv && . .venv/bin/activate && uv sync --active`.
- Run daemon: `uv run aman run --config ~/.config/aman/config.json`.

System packages (example names):

- Core: `portaudio`/`libportaudio2`.
- GTK/X11 Python bindings: distro packages such as `python3-gi` / `python3-xlib`.
- X11 tray: `libayatana-appindicator3`.

## Coding Style & Naming Conventions

- Shell scripts use Bash with `set -euo pipefail`.
- Indentation is two spaces; prefer lowercase variable names for locals and uppercase for environment-configured values.
- Keep functions small and focused; add comments only where the intent is not obvious.

## Testing Guidelines

- Automated tests live in `tests/` and run with `python3 -m unittest discover -s tests -p 'test_*.py'`.

## Commit & Pull Request Guidelines

- Commit history is minimal and does not establish a convention; use short, imperative messages (e.g., "Add device override").
- PRs should include a concise description, repro steps, and any environment variables or dependencies added.

## Configuration Tips

- Audio input is configured via the `recording.input` field in `config.json`.
- STT model and device are configured via the `stt` section in `config.json`.
- LLM model settings are locked; model downloads to `~/.cache/aman/models/`.
- `-v/--verbose` enables verbose logs (including llama.cpp) with `llama::` prefix.
- Press `Esc` while recording to cancel without processing.