Context

A recent Browser Use bug report shows a useful failure shape for BrowserTrace docs:

• External thread: bu-2-0 emits {input_text: {index: true}} (boolean) instead of integer on auth0-style login pages (✨) browser-use/browser-use#4796
• Raw model action can contain an invalid target-bearing field, e.g. input_text.index: true where an integer element index is expected.
• Python validation may silently coerce true to 1, while stricter validators reject the same action.
• Once coercion happens, a trace can hide the important evidence: the executed element index came from schema normalization, not from a valid model action.

BrowserTrace does not need to claim first-class support for this yet. This issue is only to document the debugging boundary that a trace should preserve.

Scope

Please make a small docs-only update:

1. Update docs/browser-use-debugging.html with a short section or paragraph about action schema/validation boundaries.
2. Mention the useful evidence fields:
   • raw model action
   • validated/normalized action
   • schema or normalization warning
   • selected element metadata for the final executed target
3. Keep the wording careful: this is a debugging pattern and future adapter direction, not a claim that BrowserTrace already captures every Browser Use internal field.
4. Add focused metadata coverage in tests/test_metadata.py so the guide keeps this boundary documented.

Out of scope

• No Browser Use adapter code changes.
• No claims about BrowserTrace being an OWASP AOS compliance tool.
• No broad README rewrite.
• No star/upvote/repost requests.

Verification

Run:

uv run --python 3.11 --extra dev pytest tests/test_metadata.py -q
git diff --check

First PR recipe

Keep the PR tiny: one docs section plus one focused metadata test is enough.
See the First PR Recipe:
https://github.com/aaronlab/browsertrace/blob/main/CONTRIBUTING.md#first-pr-recipe