Skip to content

armgit / Handy

Public Imported from GitHub
0

A free, open source, and extensible speech-to-text application that works completely offline.

docs: explain macOS Accessibility after local rebuilds (#1889)

Dave Goobong Jeong8758dccb04ea
diff --git a/BUILD.md b/BUILD.md
index 5b7fe16f..d98e0dae 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -146,6 +146,38 @@ Resources only need re-copying if they change upstream (new icons, sounds, model
## Troubleshooting
+### macOS Accessibility remains enabled after a local rebuild
+
+Local builds use the ad-hoc `signingIdentity: "-"`. A rebuild can have a new macOS code
+identity while the old **System Settings > Privacy & Security > Accessibility** entry
+remains visibly enabled, leaving Handy on `Waiting...`.
+
+After installing the final bundle at `/Applications/Handy.app`, quit Handy, clear only its
+stale Accessibility record, then reopen it:
+
+```bash
+osascript -e 'tell application id "com.pais.handy" to quit' || true
+tccutil reset Accessibility com.pais.handy
+open /Applications/Handy.app
+```
+
+Grant Accessibility again when prompted. This does not reset Microphone or other TCC
+services, and official releases normally do not need it.
+
+For optional diagnosis, compare the designated requirements of the previous and rebuilt
+bundles:
+
+```bash
+codesign -dr - /path/to/previous/Handy.app 2>&1
+codesign -dr - /Applications/Handy.app 2>&1
+```
+
+An ad-hoc requirement contains a `cdhash`; a changed requirement confirms the rebuild is
+not covered by the old grant. The reset procedure does not require this check.
+
+See [issue #1618](https://github.com/cjpais/Handy/issues/1618) for the related onboarding
+and stale-permission report.
+
### AppImage build fails on Arch / rolling-release distros
`linuxdeploy` bundles its own `strip` binary which is too old to process system libraries built with newer toolchains on rolling-release distros (Arch, CachyOS, Manjaro, EndeavourOS).