diff --git a/content/skills/jmix-verify-bootrun/SKILL.md b/content/skills/jmix-verify-bootrun/SKILL.md
index dbff5d1..8aba4ef 100644
--- a/content/skills/jmix-verify-bootrun/SKILL.md
+++ b/content/skills/jmix-verify-bootrun/SKILL.md
@@ -117,12 +117,28 @@ If you do have one, run the mechanical checks first, then:
    never becomes ready, tail the log, skip Gate 3, and shut the process down.
 3. With your browser/UI-automation tool, navigate to each view you created, click
    each button/action, fill each field, and confirm no error overlay or server
-   exception.
+   exception. A Jmix UI is a Vaadin web-component UI, so it does not respond to a
+   browser tool the way a plain HTML page does — see the next section.
 4. **Shut the background app down** when finished (`kill` the bootRun PID; if the
    port stays held, kill whatever holds it). Always leave the port free, and state
    in your report which database the walk ran against and what data it created
    there.
 
+### Driving a Jmix/Vaadin UI
+
+The page is built from `vaadin-*` custom elements, rendered by a client that keeps
+working after the HTTP response is done:
+
+- **Wait for the client to render before you look.** The first snapshot or
+  screenshot after navigation is routinely blank; retry until the expected content
+  is there instead of reporting a render failure.
+- **Refs go stale after every action.** Retake the snapshot immediately before each
+  interaction rather than reusing refs captured earlier in the walk.
+- **Role/name locators often miss `vaadin-*` components.** Prefer a ref from the
+  current snapshot, falling back to a DOM query on tag name and visible text.
+- **A disabled action is usually a precondition, not a defect.** Jmix actions enable
+  on state — find and satisfy what this one waits for before reporting it broken.
+
 ## Honest scope — Gate 3 is a render gate
 
 A browser walk catches the gross render exceptions a user would hit, but the