fix examples toggle first-run and hotkey docs

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- `examples/vpaste-toggle.sh` no longer exits on first run under `/bin/sh` with `set -e` when the PID file is absent.
+
+### Changed
+
+- Example docs now include explicit macOS permission steps (Microphone, Accessibility, Automation), hotkey conflict guidance, and troubleshooting notes for `vpaste.sh`/`vpaste-toggle.sh`.
+- Toggle hotkey docs now describe editing script flags directly instead of using undocumented `VOXCLIP_MODEL` environment configuration.
+
 ## [1.1.0] - 2026-03-24
 
 ### Added

examples/README.md

@@ -56,7 +56,20 @@ The recording happens silently — no terminal window opens, no prompts appear.
 
 1. Open **Shortcuts.app** and create a new shortcut named "Voice Prompt".
 2. Add the action **Run Shell Script**, set shell to `/bin/zsh`, and paste the contents of `vpaste.sh`.
-3. Go to **System Settings > Keyboard > Keyboard Shortcuts > Services** (or App Shortcuts) and assign a key combination (e.g. `Ctrl+Shift+V`) to the "Voice Prompt" shortcut.
+3. Go to **System Settings > Keyboard > Keyboard Shortcuts > Services** (or App Shortcuts) and assign a key combination (for example `Ctrl+Alt+Cmd+V`).
+
+Avoid `Ctrl+Shift+V` and `Cmd+Shift+V` on macOS where editors and terminals often intercept those combos.
+
+### macOS permissions (required for both hotkey scripts)
+
+`vpaste.sh` and `vpaste-toggle.sh` rely on macOS privacy permissions for recording and simulated paste.
+
+1. Run the shortcut once from **Shortcuts.app** (click the Play button) to trigger permission prompts.
+2. Allow **Microphone** access for Shortcuts.
+3. Enable **Accessibility** for Shortcuts so `osascript` can send `Cmd+V`.
+4. Enable **Automation** for Shortcuts to control **System Events**.
+
+If you test from Terminal/iTerm instead of Shortcuts, grant the same permissions to that terminal app.
 
 ### Linux setup (GNOME)
 
@@ -78,7 +91,7 @@ The recording happens silently — no terminal window opens, no prompts appear.
 
 ### Requirements
 
-- **macOS:** nothing extra — `osascript` is built-in and voxclip copies to clipboard via `pbcopy`.
+- **macOS:** `osascript` is built-in and voxclip copies via `pbcopy`; grant Microphone + Accessibility + Automation permissions as described above.
 - **Linux X11:** `xclip` for clipboard writes and `xdotool` for simulating the paste keystroke (`apt install xclip xdotool` / `dnf install xclip xdotool`).
 - **Linux Wayland:** `wl-copy` for clipboard writes and `wtype` for simulating the paste keystroke (`apt install wl-clipboard wtype`).
 
@@ -123,18 +136,36 @@ Then bind `~/.local/bin/vpaste-toggle` to a global hotkey:
 - **KDE:** System Settings > Shortcuts > Custom Shortcuts
 - **macOS:** Shortcuts.app > Run Shell Script (set shell to `/bin/zsh`)
 
-### Configuration
-
-Set `VOXCLIP_MODEL` to change the model (default: `small`):
+Before binding a silent hotkey, pre-download the model once so first use does not block on background download:
 
 ```bash
-export VOXCLIP_MODEL=tiny
+voxclip setup --model tiny
 ```
 
+### Configuration
+
+Edit your local `vpaste-toggle` copy and adjust the `voxclip` flags directly (for example `--model`, `--language`, or `--input`).
+
 ### Requirements
 
 Same as `vpaste.sh` — see the [requirements section](#requirements) above.
 
+### Troubleshooting hotkey scripts
+
+Run from Terminal to surface hidden errors while iterating:
+
+```bash
+~/.local/bin/vpaste
+~/.local/bin/vpaste-toggle
+```
+
+Common failure modes:
+
+- `System Events got an error ... not allowed to send keystrokes (1002)` -> enable macOS Accessibility permission.
+- Transcript copies but does not paste on Linux -> install `xdotool` (X11) or `wtype` (Wayland).
+- Wrong microphone -> run `voxclip devices` and pass `--input` in your local script copy.
+- Toggle script appears stuck after interrupted run -> remove stale PID file: `rm -f /tmp/voxclip-toggle.pid`.
+
 ## One-shot invocation (non-interactive)
 
 ### `vprompt` — command substitution (fixed duration)

examples/vpaste-toggle.sh

@@ -17,7 +17,7 @@ export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
 PID_FILE="${XDG_RUNTIME_DIR:-/tmp}/voxclip-toggle.pid"
 
 # If a recording is already running, stop it and exit.
-pid=$(cat "$PID_FILE" 2>/dev/null)
+pid=$(cat "$PID_FILE" 2>/dev/null || true)
 if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
   kill -USR1 "$pid"
   exit 0

website/content/docs/examples.md

@@ -74,7 +74,7 @@ Record your voice for a fixed duration, transcribe locally, and simulate a paste
 {{< tab >}}
 1. Open **Shortcuts.app** and create a new shortcut named "Voice Prompt".
 2. Add the action **Run Shell Script**, set shell to `/bin/zsh`, and paste the contents of `vpaste.sh`.
-3. Go to **System Settings > Keyboard > Keyboard Shortcuts > Services** and assign a key combination (e.g. `Ctrl+Shift+V`).
+3. Go to **System Settings > Keyboard > Keyboard Shortcuts > Services** and assign a key combination (for example `Ctrl+Alt+Cmd+V`).
 {{< /tab >}}
 
 {{< tab >}}
@@ -101,14 +101,27 @@ Record your voice for a fixed duration, transcribe locally, and simulate a paste
 
 {{< /tabs >}}
 
+Avoid `Ctrl+Shift+V` and `Cmd+Shift+V` on macOS where editors and terminals often intercept those combos.
+
+### macOS permissions (required for both hotkey scripts)
+
+`vpaste.sh` and `vpaste-toggle.sh` rely on macOS privacy permissions for recording and simulated paste.
+
+1. Run the shortcut once from **Shortcuts.app** (click the Play button) to trigger permission prompts.
+2. Allow **Microphone** access for Shortcuts.
+3. Enable **Accessibility** for Shortcuts so `osascript` can send `Cmd+V`.
+4. Enable **Automation** for Shortcuts to control **System Events**.
+
+If you test from Terminal/iTerm instead of Shortcuts, grant the same permissions to that terminal app.
+
 **Configuration:**
 
 ```bash
 export VPROMPT_DURATION=12s
 ```
 
 **Requirements:**
-- **macOS:** nothing extra — `osascript` is built-in and voxclip copies to clipboard via `pbcopy`.
+- **macOS:** `osascript` is built-in and voxclip copies via `pbcopy`; grant Microphone + Accessibility + Automation permissions as described above.
 - **Linux X11:** `xclip` for clipboard writes and `xdotool` for simulating the paste keystroke (`apt install xclip xdotool` / `dnf install xclip xdotool`).
 - **Linux Wayland:** `wl-copy` for clipboard writes and `wtype` for simulating the paste keystroke (`apt install wl-clipboard wtype`).
 
@@ -150,14 +163,34 @@ Then bind `~/.local/bin/vpaste-toggle` to a global hotkey:
 
 {{< /tabs >}}
 
-**Configuration:**
+Before binding a silent hotkey, pre-download the model once so first use does not block on background download:
 
 ```bash
-export VOXCLIP_MODEL=tiny
+voxclip setup --model tiny
 ```
 
+**Configuration:**
+
+Edit your local `vpaste-toggle` copy and adjust the `voxclip` flags directly (for example `--model`, `--language`, or `--input`).
+
 **Requirements:** same as `vpaste.sh` above.
 
+### Troubleshooting hotkey scripts
+
+Run from Terminal to surface hidden errors while iterating:
+
+```bash
+~/.local/bin/vpaste
+~/.local/bin/vpaste-toggle
+```
+
+Common failure modes:
+
+- `System Events got an error ... not allowed to send keystrokes (1002)` -> enable macOS Accessibility permission.
+- Transcript copies but does not paste on Linux -> install `xdotool` (X11) or `wtype` (Wayland).
+- Wrong microphone -> run `voxclip devices` and pass `--input` in your local script copy.
+- Toggle script appears stuck after interrupted run -> remove stale PID file: `rm -f /tmp/voxclip-toggle.pid`.
+
 ### Voice notes (`vnote.sh`)
 
 Append timestamped transcriptions to a file: