docs(skills): quote the doctor the binary actually prints

This commit is contained in:
pj committed 2026-08-16 01:07:49 +05:30
1 parent 46aba1654f
commit 9172d1c378
1 file changed
+23 -21
+23 -21
View File
@@ -10,10 +10,9 @@ believe. Two things decide that, and both are usually treated as chores: the
handles the app exposes, and the state the app starts in. Everything else here handles the app exposes, and the state the app starts in. Everything else here
is plumbing. is plumbing.
Every flag below is one the binary accepts. `sanderling test -h` is the Every flag below is one the binary accepts, checked against `sanderling test -h`
authority, not this file and not the manual: the manual currently documents on this revision. That command is the authority, not this file and not the
`--launcher-activity`, which the binary answers with `flag provided but not manual. Check before you use a flag you have not seen work.
defined`. Check before you use a flag you have not seen work.
## 1. Install, then check the host ## 1. Install, then check the host
@@ -28,31 +27,34 @@ Both come from the same release tag and the CLI bundles the package's TypeScript
when it evaluates your spec, so they move together. when it evaluates your spec, so they move together.
`sanderling doctor` reports the host's readiness per platform and exits non-zero `sanderling doctor` reports the host's readiness per platform and exits non-zero
if anything is missing. On a Mac with no Android SDK it says: if anything is missing. Each line names the check and, on a failure, what to do
about it. On a Mac with the Android SDK installed but a CLI built by a plain
`go build`, `sanderling doctor --platform android` says:
``` ```
OK adb on PATH OK adb on PATH or under the Android SDK
FAIL emulator on PATH or under ANDROID_HOME: not on PATH and ANDROID_HOME is unset OK emulator on PATH or under the Android SDK
OK java 17+ on PATH OK java 17+ on PATH
FAIL sidecar JAR is real (not placeholder): placeholder JAR embedded; run `make sidecar && make sanderling` to embed the real fat JAR FAIL sidecar JAR is real (not placeholder): placeholder JAR embedded; run `make sidecar && make sanderling` to embed the real fat JAR
error: 2 check(s) failed error: 1 check(s) failed
``` ```
Scope it with `--platform web|android|ios|ios-device|all` (default `all`). Web Scope it with `--platform web|android|ios|ios-device|all` (default `all`). Web
needs a Chromium that launches headless. Android needs `adb`, an emulator on needs a Chromium that launches headless. Android needs `adb`, an emulator, Java
PATH or under `ANDROID_HOME`, Java 17 or newer, and the embedded sidecar JAR. 17 or newer, and the embedded sidecar JAR. iOS needs `xcrun` and `simctl`;
iOS needs `xcrun` and `simctl`; `ios-device` adds `devicectl`, the macOS usbmuxd `ios-device` adds `devicectl`, the macOS usbmuxd socket, a connected paired
socket, a connected paired device, and App Store Connect signing credentials. device, and App Store Connect signing credentials.
Read the doctor's Android result as advisory rather than final: its emulator The `adb` and `emulator` checks resolve through the same helpers a run uses, so
check today looks only at PATH, `ANDROID_HOME` and `ANDROID_SDK_ROOT`, while a they search PATH, then `ANDROID_HOME` and `ANDROID_SDK_ROOT`, then
run also searches `~/Library/Android/sdk`, `~/Android/Sdk` and the Homebrew `~/Library/Android/sdk`, `~/Android/Sdk` and the Homebrew command-line-tools
command-line-tools paths. The run's own error names every location it tried, so paths. A host the doctor passes is a host a run can drive, and a failure names
that is the one to trust. In the other direction, a missing SDK can surface every location it tried. What the doctor cannot tell you is the reverse: a
during a run as `sidecar health check: context deadline exceeded` about thirty missing SDK can also surface during a run as `sidecar health check: context
seconds in, which names the symptom and not the cause (issue #69). If you see deadline exceeded` about thirty seconds in, which names the symptom and not the
it, go back to `sanderling doctor --platform android` before believing anything cause (issue #69). If you see it, go back to
about the sidecar. `sanderling doctor --platform android` before believing anything about the
sidecar.
Two traps if you build from source rather than installing a release. A plain Two traps if you build from source rather than installing a release. A plain
`go build ./cmd/sanderling` embeds a placeholder sidecar JAR, so every Android `go build ./cmd/sanderling` embeds a placeholder sidecar JAR, so every Android