fix(runner): warn on malformed screen snapshot (#13)

* fix(runner): warn on malformed screen snapshot

screenFromSnapshot swallowed json.Unmarshal errors, so a non-string
screen value silently became "" in the step log and trace while the
verifier still saw the raw JSON. Return the error and warn at the
call site, matching the hierarchy warning pattern.

* docs: clarify --avd is optional for uatu test

The CLI accepts --avd as an empty-string default (cmd/uatu/main.go:49)
and only requires it when no device is connected and multiple AVDs
exist (cmd/uatu/android_env.go:63). Docs and examples that showed it
as required or always-passed were misleading.

docs/manual/cli.md

@@ -18,7 +18,7 @@ Run a spec against an app for a fixed duration.
 | `--bundle-id` | required | Target app bundle ID (Android: applicationId). |
 | `--launcher-activity` | resolved | Optional `<pkg>/<activity>` to launch. Overrides default resolution. |
 | `--platform` | `android` | Target platform. Only `android` in the current alpha. |
-| `--avd` | required (android) | Android AVD name. |
+| `--avd` | optional (android) | Android AVD name to boot if no device is connected. Required only when no device is connected and multiple AVDs exist. |
 | `--duration` | `5m` | Total test duration (`30s`, `5m`, `2h`, `1d`). |
 | `--seed` | `0` | PRNG seed. `0` uses a random seed and records it in `meta.json`. |
 | `--output` | `./runs` | Output directory for traces. |

docs/manual/getting-started.md

@@ -59,10 +59,11 @@ uatu test \
   --spec spec.ts \
   --bundle-id dev.uatu.sample \
   --platform android \
-  --avd Pixel_7 \
   --duration 2m
 ```
 
+Pass `--avd <name>` only when no device is connected and you have multiple AVDs; otherwise uatu uses the connected device or boots the single AVD it finds.
+
 When the run ends, the trace lands in `runs/<timestamp>/`:
 
 ```

docs/manual/runs.md

@@ -11,7 +11,7 @@ A run is not analogous to a unit test. A closer framing is: boot a fuzzer for an
 ## Lifecycle
 
 ```
-uatu test --spec spec.ts --bundle-id com.example.app --avd Pixel_7 --duration 30m
+uatu test --spec spec.ts --bundle-id com.example.app --duration 30m
   │
   ├── uninstall and reinstall the app (clean slate, every run)
   ├── boot the sidecar, connect the agent socket