docs: cover browser use action schema validation

Author: aaronlab

LAUNCH.md

@@ -117,7 +117,7 @@ Current latest audit:
 
 | Captured at | Stars | To 1001 | Forks | Watchers | Issues | PRs | Release downloads | Note |
 |---|---:|---:|---:|---:|---:|---:|---:|---|
-| 2026-05-12T11:46:42+00:00 | 3 | 998 | 20 | 0 | 11 | 0 | 40 | current monitor pass after good-first issue #352 opened for local HTML upload failure-patterns coverage; traffic views 354/132 unique, clones 16382/2819 unique |
+| 2026-05-12T11:53:28+00:00 | 3 | 998 | 20 | 0 | 11 | 0 | 40 | current monitor pass after Browser Use action schema validation docs coverage for #345; traffic views 354/132 unique, clones 16382/2819 unique |
 
 The active objective is incomplete until `stargazerCount > 1000`.
 

docs/browser-use-debugging.html

@@ -355,6 +355,19 @@ <h2 id="debug-local-html-upload-navigation">Debug local HTML upload navigation m
       <p>Related community case: <a href="https://github.com/browser-use/browser-use/issues/4794">browser-use/browser-use#4794</a>.</p>
     </section>
 
+    <section>
+      <h2 id="debug-action-schema-validation">Debug action schema validation boundaries</h2>
+      <p>Action schema coercion can hide why a Browser Use step targeted the wrong element. For example, a raw model action may put a boolean in an element-index field, then one validation path coerces it while another rejects it. After normalization, the final executed target can look deliberate unless the trace preserves both sides of the boundary.</p>
+      <p>Treat this as a schema validation and future adapter boundary. It does not mean BrowserTrace already captures every internal Browser Use field.</p>
+      <ul>
+        <li>Keep the raw model action before validation.</li>
+        <li>Record the validated or normalized action that Browser Use actually executed.</li>
+        <li>Capture any schema or normalization warning, validation error, or coercion note.</li>
+        <li>Preserve selected element metadata for the final executed target, including index, role, text, selector, and URL when available.</li>
+      </ul>
+      <p>Related community case: <a href="https://github.com/browser-use/browser-use/issues/4796">browser-use/browser-use#4796</a>.</p>
+    </section>
+
     <section>
       <h2 id="debug-empty-model-responses">Debug empty model responses</h2>
       <p>A failing parser exception might occur when the model provider returns an empty response (e.g., <code>input_value=''</code>) before Browser Use validation runs. This suggests the parser received no assistant JSON content at all, rather than malformed JSON.</p>

docs/launch/metrics-log.md

@@ -1033,3 +1033,4 @@ uv run --python 3.11 python scripts/launch_metrics.py --json
 | 2026-05-12T11:39:24+00:00 | 3 | 998 | 20 | 0 | 11 | 0 | 40 | current monitor pass after README mentions Browser Use remote CDP hangs for #350; traffic views 354/132 unique, clones 16382/2819 unique |
 | 2026-05-12T11:42:02+00:00 | 3 | 998 | 20 | 0 | 10 | 0 | 40 | current monitor pass after #350 closed with README remote CDP docs coverage; traffic views 354/132 unique, clones 16382/2819 unique |
 | 2026-05-12T11:46:42+00:00 | 3 | 998 | 20 | 0 | 11 | 0 | 40 | current monitor pass after good-first issue #352 opened for local HTML upload failure-patterns coverage; traffic views 354/132 unique, clones 16382/2819 unique |
+| 2026-05-12T11:53:28+00:00 | 3 | 998 | 20 | 0 | 11 | 0 | 40 | current monitor pass after Browser Use action schema validation docs coverage for #345; traffic views 354/132 unique, clones 16382/2819 unique |

tests/test_metadata.py

@@ -601,6 +601,36 @@ def test_browser_use_guide_covers_local_html_upload_navigation_boundary():
     assert "reposts" not in section.lower()
 
 
+def test_browser_use_guide_covers_action_schema_validation_boundary():
+    project_root = Path(__file__).resolve().parents[1]
+    guide = (project_root / "docs" / "browser-use-debugging.html").read_text()
+
+    assert 'id="debug-action-schema-validation"' in guide
+    assert "action schema" in guide
+    assert "schema coercion" in guide
+    assert "browser-use/browser-use/issues/4796" in guide
+
+    section = guide.split('id="debug-action-schema-validation"', 1)[1].split(
+        "</section>",
+        1,
+    )[0]
+
+    for expected in [
+        "raw model action",
+        "validated or normalized action",
+        "schema or normalization warning",
+        "selected element metadata",
+        "final executed target",
+    ]:
+        assert expected in section
+
+    assert "future adapter boundary" in section
+    assert "does not mean BrowserTrace already captures every internal Browser Use field" in section
+    assert "stars" not in section.lower()
+    assert "upvotes" not in section.lower()
+    assert "reposts" not in section.lower()
+
+
 def test_stagehand_guide_links_first_pr_recipe_for_small_contributions():
     project_root = Path(__file__).resolve().parents[1]
     guide = (project_root / "docs" / "stagehand-debugging.html").read_text()