# Contributing to Jukebox

Thank you for helping make voice a first-class interface for agentic work.

Discuss material architecture or UX changes in an issue before implementation so capture reliability, privacy, and Omarchy shell stability remain coherent.

## Ground rules

- Never commit real recordings, transcripts, generated prompts with personal data, credentials, tokens, model files, or machine-specific state.
- Use synthetic fixtures designed specifically for tests.
- Do not add privileged commands or background network services without an explicit threat-model update.
- Do not start a second Quickshell process. Plugin UI belongs in the existing Omarchy shell.
- Preserve raw speech whenever a downstream stage fails.
- Do not silently change the user's selected model or destination.
- Keep W1 undefined until its product contract is decided separately.

## Required checks

```bash
./scripts/validate.sh
python -m unittest discover -s tests -v
```

UI changes must include narrow, typical, and large-width evidence plus hover, processing, keyboard, and resize validation. Backend changes must include state-transition and failure-recovery tests.

## Transformation adapters

Provider work must begin from one of the scoped adapter issues linked in the README. Keep provider authentication and invocation behind a narrow transformation interface; do not add provider logic to audio capture, transcription, focus restoration, or terminal delivery.

Every adapter pull request must demonstrate:

- explicit provider and model selection with no hidden downgrade;
- reuse of the provider CLI's own authenticated session, or documented keyring-backed secret storage when no CLI session exists;
- no credentials or transcript content in process arguments, logs, fixtures, screenshots, or permissive files;
- bounded timeout, cancellation, retry, malformed-output, unavailable-model, and nonzero-exit handling;
- preservation of the raw transcript on every downstream failure;
- synthetic Verbatim/Upskill corpus results and a disposable-home integration test;
- no regression in the current Codex adapter or origin-window delivery contract;
- updated architecture, threat model, dependencies, setup, disconnect/removal, and privacy documentation.

Never inspect or copy another CLI's credential database merely because it is accessible with the current user's permissions. Invoke the provider through its documented interface and let that provider own authentication refresh and logout behavior.

## Pull requests

Explain the user problem, implementation boundary, security/privacy impact, test evidence, screenshots when visual, and rollback behavior. Small, reviewable changes are preferred.