R1

docs/troubleshooting.md

@@ -0,0 +1,46 @@
+# Troubleshooting
+
+## `gpu-doctor` reports no GPU
+
+Confirm the driver and Vulkan/CUDA runtime are installed, then run the doctor
+under the same graphical user session that will run `jarvisd`. A host command
+such as `vulkaninfo` is insufficient if QVAC itself reports no device. Jarvis
+will remain available for diagnostics but refuses inference until QVAC sees a
+GPU.
+
+## Voice doctor finds no wake engine
+
+Install a local openWakeWord or sherpa-onnx bridge and set
+`JARVIS_WAKE_COMMAND`. The bridge must read raw 16 kHz mono PCM from stdin and
+write detected phrases, one per line, to stdout. Push-to-talk remains useful
+for typed or manually triggered testing.
+
+## Portal consent succeeds but input is unavailable
+
+ScreenCast consent does not prove that RemoteDesktop/EIS injection is ready.
+Configure `JARVIS_LIBEI_BRIDGE`; the helper intentionally fails closed without
+it. Use observe-only mode until the injector reports ready. `ydotool` is an
+optional, explicitly enabled fallback.
+
+## The extension is missing
+
+Check that `metadata.json` has UUID `[email protected]`, copy the extension into
+`~/.local/share/gnome-shell/extensions/[email protected]`, then run:
+
+```bash
+gnome-extensions enable [email protected]
+journalctl --user -b | grep -i jarvis
+```
+
+## The daemon restarts
+
+Inspect `journalctl --user -u jarvisd.service`. Common causes are Node version,
+invalid QVAC config, missing session D-Bus, missing GPU visibility, or a stale
+portal grant. Run the three doctor commands before changing model settings.
+
+## Rolling release did not publish
+
+Check the Gitea Actions log and repository secret name. It must be exactly
+`RELEASE_TOKEN` with repository write permission. The workflow only publishes
+from `main`; pull requests and other branches run CI but do not replace the
+`rolling` prerelease.