# Contributing

Contributions that improve MIDI compatibility, chord recognition, command safety, accessibility, or Omarchy integration are welcome.

## Development setup

Chordarchy has no build step or third-party language packages. Clone it into Omarchy's user plugin directory and enable it:

```bash
git clone https://github.com/ctl0v0/chordarchy.git ~/.config/omarchy/plugins/io.github.ctl0v0.chordarchy
omarchy plugin enable io.github.ctl0v0.chordarchy
```

Restart the shell after changing QML that is already loaded:

```bash
omarchy restart shell
```

## Checks

Run every check before opening a pull request:

```bash
python3 -m unittest discover -s tests -p 'test_*.py'
node tests/test_music.js
omarchy plugin validate .
```

Open each affected Studio page and inspect the current shell process journal for QML errors. Also test command execution while armed, disarmed, in Practice, and during a demo preview when changing safety-sensitive behavior.

## Project structure

- `Service.qml` owns the backend process, snapshot, IPC, and detached Studio lifecycle.
- `backend/chordarchy_backend.py` owns MIDI, chord gestures, mappings, command execution, and synthesis.
- `Overlay.qml` provides Studio workflows.
- `Panel.qml` provides the compact performance panel.
- `MusicModel.js` and `StaffVisualizer.qml` provide staff and note presentation.

Keep changes scoped to this plugin. Do not require edits to Omarchy's files under `/usr/share/omarchy` or overwrite user Hyprland configuration.