docs: Add binary distribution guide and dylib troubleshooting

Author: skitsanos

README.md

@@ -116,6 +116,34 @@ DIARIZE_SEGMENTATION_MODEL=.cache/sherpa-onnx-pyannote-segmentation-3-0/model.on
 DIARIZE_EMBEDDING_MODEL=.cache/wespeaker_en_voxceleb_CAM++.onnx
 ```
 
+## Binary distribution
+
+Pre-built binaries can be deployed without Rust or build tools. The binary needs FFmpeg on PATH and the sherpa-onnx shared libraries alongside it:
+
+```
+transcribeit              # binary
+lib/                      # sherpa-onnx shared libraries
+  libsherpa-onnx-c-api.dylib
+  libonnxruntime.dylib
+```
+
+On first run, use `transcribeit setup` to download models and additional components. The binary looks for shared libraries in `lib/` relative to itself — no environment variables needed at runtime.
+
+To build a distributable binary:
+
+```bash
+cargo build --release
+# Copy binary + libs
+cp target/release/transcribeit dist/
+cp vendor/sherpa-onnx-*/lib/lib*.dylib dist/lib/
+```
+
+To build without sherpa-onnx (no shared library dependency):
+
+```bash
+cargo build --release --no-default-features
+```
+
 ## License
 
 This project is licensed under the [Business Source License 1.1](LICENSE).

docs/troubleshooting.md

@@ -213,3 +213,28 @@ Fix:
 SenseVoice models are capable of detecting emotions and audio events (laughter, applause, music, etc.), but the sherpa-onnx C API strips these tags from the output. Only the transcription text is available. This is a limitation of the sherpa-onnx C-level bindings, not of transcribeit.
 
 Additionally, the SenseVoice 2025 model is a quality regression compared to the 2024 version. Prefer using the 2024 SenseVoice model for best results.
+
+### Binary fails with "Library not loaded: libsherpa-onnx-c-api.dylib"
+
+Symptoms:
+- `dyld: Library not loaded: @rpath/libsherpa-onnx-c-api.dylib`
+- Binary crashes immediately on startup
+
+Fix: The binary expects sherpa-onnx shared libraries in a `lib/` directory next to itself:
+
+```
+transcribeit              # binary
+lib/                      # create this directory
+  libsherpa-onnx-c-api.dylib
+  libonnxruntime.dylib
+  libonnxruntime.1.23.2.dylib
+```
+
+Copy the dylibs from `vendor/sherpa-onnx-*/lib/` or download them with `transcribeit setup -c sherpa-libs`.
+
+If you see a hardcoded path from another machine (e.g., `/Users/someone/...`), the binary was built with an old `build.rs`. Rebuild with the latest code — the portable `@executable_path/lib` rpath is now used.
+
+To avoid this dependency entirely, build without sherpa-onnx:
+```bash
+cargo build --release --no-default-features
+```