docs(skills): document reference images for act and assert

skills/android-automation/SKILL.md

@@ -180,7 +180,7 @@ npx -y @midscene/android@1 assert \
 
 ### Use a Reference Image for Precise Targeting
 
-When the user provides a screenshot, icon, logo, or reference image and wants an exact visual match, prefer `tap --locate` instead of a generic `act --prompt`. Pass `--locate` as JSON. The `prompt` describes the target, `images` supplies named reference images, and `convertHttpImage2Base64: true` is useful when the image URL may not be directly accessible to the model.
+When the user provides a screenshot, icon, logo, or reference image and wants an exact visual match, use `tap --locate` for a single tap on that target. Pass `--locate` as JSON. The `prompt` describes the target, `images` supplies named reference images, and `convertHttpImage2Base64: true` is useful when the image URL may not be directly accessible to the model.
 
 ```bash
 npx -y @midscene/android@1 tap --locate '{
@@ -197,6 +197,18 @@ npx -y @midscene/android@1 tap --locate '{
 
 The same `locate` JSON shape also works for other commands that accept a `locate` parameter.
 
+`act` and `assert` take reference images too, via repeatable `--image` / `--image-name` pairs. Use them when the task needs more than one step, or when the assertion itself compares against the image:
+
+```bash
+npx -y @midscene/android@1 act \
+  --prompt "tap the icon matching the reference image named 'target image', then confirm in the dialog" \
+  --image "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png" \
+  --image-name "target image" \
+  --convert-http-image2-base64 true
+```
+
+Every `--image` needs a matching `--image-name`, and the prompt should refer to the image by that name — that name is how the model connects your wording to the picture. A local file path or a base64 data URI works in `--image` as well.
+
 ### Disconnect
 
 ```bash
@@ -234,7 +246,7 @@ Since CLI commands are stateless between invocations, follow this pattern:
 6. **Use scrcpy when screenshot capture needs acceleration**: Add `--use-scrcpy` to each relevant command when normal Android screenshots are slow, flaky, or blocked by the environment.
 7. **Use `assert` for verification**: When the goal is to confirm that a screen state is true, use `assert --prompt "..."` instead of an `act` prompt. Keep assertions observable and specific, such as `"the permission dialog is visible"` or `"the Save button is disabled"`.
 8. **Always report results after completion**: After finishing the automation task, you MUST proactively present the results to the user without waiting for them to ask. This includes: (1) the answer to the user's original question or the outcome of the requested task, (2) key data extracted or observed during execution, (3) screenshots and other generated files with their paths, (4) a brief summary of steps taken. Do NOT silently finish after the last automation command — the user expects complete results in a single interaction.
-9. **Prefer `tap --locate` when a reference image is provided**: If the user shares a screenshot, icon, or logo and wants that exact visual target, use `tap --locate` with a multimodal `locate` JSON object such as `{ "prompt": "...", "images": [...] }` instead of relying only on `act --prompt`.
+9. **Use reference images when the user provides one**: For a single tap on that exact visual target, use `tap --locate` with a multimodal `locate` JSON object such as `{ "prompt": "...", "images": [...] }`. For a multi-step action or an assertion against the image, pass `--image` / `--image-name` to `act` or `assert` instead.
 
 **Example — Popup menu interaction:**
 

skills/browser/SKILL.md

@@ -252,7 +252,7 @@ npx -y @midscene/web@1 assert \
 
 ### Use a Reference Image for Precise Targeting
 
-When the user provides a screenshot, icon, logo, or reference image and wants an exact visual match, prefer `tap --locate` instead of a generic `act --prompt`. Pass `--locate` as JSON. The `prompt` describes the target, `images` supplies named reference images, and `convertHttpImage2Base64: true` is useful when the image URL may not be directly accessible to the model.
+When the user provides a screenshot, icon, logo, or reference image and wants an exact visual match, use `tap --locate` for a single tap on that target. Pass `--locate` as JSON. The `prompt` describes the target, `images` supplies named reference images, and `convertHttpImage2Base64: true` is useful when the image URL may not be directly accessible to the model.
 
 ```bash
 npx -y @midscene/web@1 tap --locate '{
@@ -269,6 +269,18 @@ npx -y @midscene/web@1 tap --locate '{
 
 The same `locate` JSON shape also works for other commands that accept a `locate` parameter.
 
+`act` and `assert` take reference images too, via repeatable `--image` / `--image-name` pairs. Use them when the task needs more than one step, or when the assertion itself compares against the image:
+
+```bash
+npx -y @midscene/web@1 act \
+  --prompt "click the icon matching the reference image named 'target image', then confirm in the dialog" \
+  --image "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png" \
+  --image-name "target image" \
+  --convert-http-image2-base64 true
+```
+
+Every `--image` needs a matching `--image-name`, and the prompt should refer to the image by that name — that name is how the model connects your wording to the picture. A local file path or a base64 data URI works in `--image` as well.
+
 ### Disconnect
 
 Disconnect from the page but keep the browser running:
@@ -314,7 +326,7 @@ The browser **persists across CLI calls** via a background Chrome process. Follo
 3. **Use natural, specific prompts**: Describe visible UI and desired outcomes, such as `"click the blue Submit button in the contact form"`, not selectors like `"#submit"`.
 4. **Batch related operations into a single `act` command**: For example, fill the email and password fields, then click Log In in one prompt. Use separate commands when you need to inspect the intermediate state.
 5. **Use `assert` for verification**: Check observable page state with `assert --prompt "..."`, such as `"the success toast is visible"` or `"the cart total is $42.00"`.
-6. **Prefer `tap --locate` when a reference image is provided**: If the user shares a screenshot, icon, or logo and wants that exact visual target, use `tap --locate` with a multimodal `locate` JSON object such as `{ "prompt": "...", "images": [...] }` instead of relying only on `act --prompt`.
+6. **Use reference images when the user provides one**: For a single click on that exact visual target, use `tap --locate` with a multimodal `locate` JSON object such as `{ "prompt": "...", "images": [...] }`. For a multi-step action or an assertion against the image, pass `--image` / `--image-name` to `act` or `assert` instead.
 
 **Example — Dropdown selection:**
 

skills/computer-automation/SKILL.md

@@ -202,7 +202,7 @@ npx -y @midscene/computer@1 assert \
 
 ### Use a Reference Image for Precise Targeting
 
-When the user provides a screenshot, icon, logo, or reference image and wants an exact visual match, prefer `tap --locate` instead of a generic `act --prompt`. Pass `--locate` as JSON. The `prompt` describes the target, `images` supplies named reference images, and `convertHttpImage2Base64: true` is useful when the image URL may not be directly accessible to the model.
+When the user provides a screenshot, icon, logo, or reference image and wants an exact visual match, use `tap --locate` for a single tap on that target. Pass `--locate` as JSON. The `prompt` describes the target, `images` supplies named reference images, and `convertHttpImage2Base64: true` is useful when the image URL may not be directly accessible to the model.
 
 ```bash
 npx -y @midscene/computer@1 tap --locate '{
@@ -219,6 +219,18 @@ npx -y @midscene/computer@1 tap --locate '{
 
 The same `locate` JSON shape also works for other commands that accept a `locate` parameter.
 
+`act` and `assert` take reference images too, via repeatable `--image` / `--image-name` pairs. Use them when the task needs more than one step, or when the assertion itself compares against the image:
+
+```bash
+npx -y @midscene/computer@1 act \
+  --prompt "click the icon matching the reference image named 'target image', then confirm in the dialog" \
+  --image "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png" \
+  --image-name "target image" \
+  --convert-http-image2-base64 true
+```
+
+Every `--image` needs a matching `--image-name`, and the prompt should refer to the image by that name — that name is how the model connects your wording to the picture. A local file path or a base64 data URI works in `--image` as well.
+
 ### Disconnect
 
 ```bash
@@ -263,7 +275,7 @@ Since CLI commands are stateless between invocations, follow this pattern:
    This prevents screenshot failures caused by missing system utilities.
 9. **Use `assert` for verification**: When the goal is to confirm that a screen state is true, use `assert --prompt "..."` instead of an `act` prompt. Keep assertions observable and specific, such as `"the Save dialog is open"` or `"the export completed message is visible"`.
 10. **Always report results after completion**: After finishing the automation task, you MUST proactively present the results to the user without waiting for them to ask. This includes: (1) the answer to the user's original question or the outcome of the requested task, (2) key data extracted or observed during execution, (3) screenshots and other generated files with their paths, (4) a brief summary of steps taken. Do NOT silently finish after the last automation command — the user expects complete results in a single interaction.
-11. **Prefer `tap --locate` when a reference image is provided**: If the user shares a screenshot, icon, or logo and wants that exact visual target, use `tap --locate` with a multimodal `locate` JSON object such as `{ "prompt": "...", "images": [...] }` instead of relying only on `act --prompt`.
+11. **Use reference images when the user provides one**: For a single click on that exact visual target, use `tap --locate` with a multimodal `locate` JSON object such as `{ "prompt": "...", "images": [...] }`. For a multi-step action or an assertion against the image, pass `--image` / `--image-name` to `act` or `assert` instead.
 
 **Example — Context menu interaction:**
 

skills/harmony-automation/SKILL.md

@@ -182,7 +182,7 @@ npx -y @midscene/harmony@1 assert \
 
 ### Use a Reference Image for Precise Targeting
 
-When the user provides a screenshot, icon, logo, or reference image and wants an exact visual match, prefer `tap --locate` instead of a generic `act --prompt`. Pass `--locate` as JSON. The `prompt` describes the target, `images` supplies named reference images, and `convertHttpImage2Base64: true` is useful when the image URL may not be directly accessible to the model.
+When the user provides a screenshot, icon, logo, or reference image and wants an exact visual match, use `tap --locate` for a single tap on that target. Pass `--locate` as JSON. The `prompt` describes the target, `images` supplies named reference images, and `convertHttpImage2Base64: true` is useful when the image URL may not be directly accessible to the model.
 
 ```bash
 npx -y @midscene/harmony@1 tap --locate '{
@@ -199,6 +199,18 @@ npx -y @midscene/harmony@1 tap --locate '{
 
 The same `locate` JSON shape also works for other commands that accept a `locate` parameter.
 
+`act` and `assert` take reference images too, via repeatable `--image` / `--image-name` pairs. Use them when the task needs more than one step, or when the assertion itself compares against the image:
+
+```bash
+npx -y @midscene/harmony@1 act \
+  --prompt "tap the icon matching the reference image named 'target image', then confirm in the dialog" \
+  --image "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png" \
+  --image-name "target image" \
+  --convert-http-image2-base64 true
+```
+
+Every `--image` needs a matching `--image-name`, and the prompt should refer to the image by that name — that name is how the model connects your wording to the picture. A local file path or a base64 data URI works in `--image` as well.
+
 ### Disconnect
 
 ```bash
@@ -234,7 +246,7 @@ Since CLI commands are stateless between invocations, follow this pattern:
 5. **Batch related operations into a single `act` command**: When performing consecutive operations within the same app, combine them into one `act` prompt instead of splitting them into separate commands. For example, "open Settings, tap Wi-Fi, and toggle it on" should be a single `act` call, not three. This reduces round-trips, avoids unnecessary screenshot-analyze cycles, and is significantly faster.
 6. **Use `assert` for verification**: When the goal is to confirm that a screen state is true, use `assert --prompt "..."` instead of an `act` prompt. Keep assertions observable and specific, such as `"the permission dialog is visible"` or `"the Save button is disabled"`.
 7. **Summarize report files after completion**: After finishing the automation task, collect and summarize all report files (screenshots, logs, output files, etc.) for the user. Present a clear summary of what was accomplished, what files were generated, and where they are located, making it easy for the user to review the results.
-8. **Prefer `tap --locate` when a reference image is provided**: If the user shares a screenshot, icon, or logo and wants that exact visual target, use `tap --locate` with a multimodal `locate` JSON object such as `{ "prompt": "...", "images": [...] }` instead of relying only on `act --prompt`.
+8. **Use reference images when the user provides one**: For a single tap on that exact visual target, use `tap --locate` with a multimodal `locate` JSON object such as `{ "prompt": "...", "images": [...] }`. For a multi-step action or an assertion against the image, pass `--image` / `--image-name` to `act` or `assert` instead.
 
 **Example — App launch and interaction:**
 

skills/ios-automation/SKILL.md

@@ -170,7 +170,7 @@ npx -y @midscene/ios@1 assert \
 
 ### Use a Reference Image for Precise Targeting
 
-When the user provides a screenshot, icon, logo, or reference image and wants an exact visual match, prefer `tap --locate` instead of a generic `act --prompt`. Pass `--locate` as JSON. The `prompt` describes the target, `images` supplies named reference images, and `convertHttpImage2Base64: true` is useful when the image URL may not be directly accessible to the model.
+When the user provides a screenshot, icon, logo, or reference image and wants an exact visual match, use `tap --locate` for a single tap on that target. Pass `--locate` as JSON. The `prompt` describes the target, `images` supplies named reference images, and `convertHttpImage2Base64: true` is useful when the image URL may not be directly accessible to the model.
 
 ```bash
 npx -y @midscene/ios@1 tap --locate '{
@@ -187,6 +187,18 @@ npx -y @midscene/ios@1 tap --locate '{
 
 The same `locate` JSON shape also works for other commands that accept a `locate` parameter.
 
+`act` and `assert` take reference images too, via repeatable `--image` / `--image-name` pairs. Use them when the task needs more than one step, or when the assertion itself compares against the image:
+
+```bash
+npx -y @midscene/ios@1 act \
+  --prompt "tap the icon matching the reference image named 'target image', then confirm in the dialog" \
+  --image "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png" \
+  --image-name "target image" \
+  --convert-http-image2-base64 true
+```
+
+Every `--image` needs a matching `--image-name`, and the prompt should refer to the image by that name — that name is how the model connects your wording to the picture. A local file path or a base64 data URI works in `--image` as well.
+
 ### Disconnect
 
 ```bash
@@ -222,7 +234,7 @@ Since CLI commands are stateless between invocations, follow this pattern:
 4. **Batch related operations into a single `act` command**: When performing consecutive operations within the same app, combine them into one `act` prompt instead of splitting them into separate commands. For example, "open Settings, tap Wi-Fi, and check the connected network" should be a single `act` call, not three. This reduces round-trips, avoids unnecessary screenshot-analyze cycles, and is significantly faster.
 5. **Use `assert` for verification**: When the goal is to confirm that a screen state is true, use `assert --prompt "..."` instead of an `act` prompt. Keep assertions observable and specific, such as `"the permission dialog is visible"` or `"the Save button is disabled"`.
 6. **Always report results after completion**: After finishing the automation task, you MUST proactively present the results to the user without waiting for them to ask. This includes: (1) the answer to the user's original question or the outcome of the requested task, (2) key data extracted or observed during execution, (3) screenshots and other generated files with their paths, (4) a brief summary of steps taken. Do NOT silently finish after the last automation command — the user expects complete results in a single interaction.
-7. **Prefer `tap --locate` when a reference image is provided**: If the user shares a screenshot, icon, or logo and wants that exact visual target, use `tap --locate` with a multimodal `locate` JSON object such as `{ "prompt": "...", "images": [...] }` instead of relying only on `act --prompt`.
+7. **Use reference images when the user provides one**: For a single tap on that exact visual target, use `tap --locate` with a multimodal `locate` JSON object such as `{ "prompt": "...", "images": [...] }`. For a multi-step action or an assertion against the image, pass `--image` / `--image-name` to `act` or `assert` instead.
 
 **Example — Alert dialog interaction:**