# NovaVoice on macOS — install & first-run guide

> **Developer preview.** v0 macOS builds are **unsigned** and **not notarized**.
> macOS will warn you on first launch; the steps below show how to bypass
> Gatekeeper safely. Signing and notarization land before public beta.

## Requirements

- macOS 11 (Big Sur) or later, Apple Silicon or Intel
- ~250 MB free disk for the app + the Whisper model on first download
- A microphone

## Install

1. Download `NovaVoice-<version>.dmg` from the
   [Releases](https://github.com/novafabric/novavoice/releases) page.
2. Open the `.dmg`. Drag **NovaVoice.app** into the **Applications** folder shown
   in the Finder window.
3. Eject the `.dmg`.

## First launch — Gatekeeper bypass

Because v0 is unsigned, macOS shows
*"NovaVoice can’t be opened because Apple cannot check it for malicious software"*
the first time you double-click the app. To get past this:

1. Open Finder → Applications.
2. **Right-click** (or Control-click) **NovaVoice.app** → **Open**.
3. In the dialog that appears, click **Open** again.

You only need to do this once. After that, double-clicking works normally.

> If you prefer, do the same from a terminal:
> ```sh
> xattr -dr com.apple.quarantine /Applications/NovaVoice.app
> open /Applications/NovaVoice.app
> ```

## Grant Accessibility access

NovaVoice listens for the dictation key (Right Option by default) using the
macOS Accessibility API. The OS gates this with a privacy prompt:

1. On first launch, NovaVoice triggers macOS to show an **Accessibility** prompt.
   Click **Open System Settings**.
2. In **System Settings → Privacy & Security → Accessibility**, find
   **NovaVoice** and **enable the toggle**.
3. Quit and reopen NovaVoice (the daemon picks up the new permission on next
   launch).

If the prompt didn't appear, open the pane directly:

```sh
open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'
```

## Grant Microphone access

Hold the dictation key once. The first time, macOS prompts:
*"NovaVoice would like to access the microphone."* Click **OK**.

If you accidentally clicked **Don't Allow**, re-enable in
**System Settings → Privacy & Security → Microphone → NovaVoice**.

## Use it

By default, **hold Right Option** anywhere on the desktop, speak, then release.
The transcribed text appears in whatever app is focused.

The default hotkey is configurable in `~/Library/Application Support/novavoice/config.toml`:

```toml
[hotkey]
# "auto" → Right Option on macOS. Other options: "right_ctrl", "left_option",
# "space", "right_shift", ...
key = "auto"
hold_threshold_ms = 500

[stt]
model = "tiny.en"   # try "base.en" for better accuracy at the cost of CPU
```

The first transcription downloads the Whisper model (~80 MB for `tiny.en`)
into `~/Library/Caches/huggingface/hub/`. Subsequent dictations are fully offline.

## Verify with the CLI

The `.app` ships a CLI alongside the tray:

```sh
/Applications/NovaVoice.app/Contents/MacOS/NovaVoice --cli doctor
/Applications/NovaVoice.app/Contents/MacOS/NovaVoice --cli status
```

(For convenience, you can symlink it: `sudo ln -s /Applications/NovaVoice.app/Contents/MacOS/NovaVoice /usr/local/bin/novavoice` and then run `novavoice --cli doctor`.)

## Troubleshooting

**"NovaVoice keeps asking for Accessibility."** macOS treats unsigned apps as
new identities each time their hash changes. After every NovaVoice update you
may need to re-enable the toggle. Signing (planned) will fix this.

**"The hotkey doesn't fire."** Check Accessibility is granted. Also check
that no other tool is intercepting Right Option (e.g., Karabiner-Elements,
some IME apps). Try a different hotkey by editing `config.toml`.

**"Microphone is silent."** Confirm in
*System Settings → Privacy & Security → Microphone* that NovaVoice is enabled.
Run `--cli doctor` to see what NovaVoice is detecting.

**"Antivirus flags NovaVoice."** v0 is unsigned, which trips conservative AV
heuristics. Build from source (`scripts/build-macos.sh`) if you prefer.

## Uninstall

```sh
launchctl bootout gui/$(id -u)/com.novavoice.daemon 2>/dev/null || true
rm -rf /Applications/NovaVoice.app
rm -rf ~/Library/Application\ Support/novavoice
rm -rf ~/Library/Caches/novavoice
rm -rf ~/Library/Logs/novavoice
rm -f  ~/Library/LaunchAgents/com.novavoice.daemon.plist
```

Also remove the toggle entry in
*System Settings → Privacy & Security → Accessibility*.