Context

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

• External thread: Bug: uploading an html file causes the agent to try to navigate to a web page browser-use/browser-use#4794
• A local .html file upload can be misread as a navigation target before the intended upload action runs.
• The security watchdog can correctly block the bad URL, but the useful debugging boundary is earlier: why did the first model/planner action become navigate at all?

This is different from a low-level file upload failure. It is a planner/action boundary where local attachment metadata, filename text, or model-visible context may leak into a URL-like action proposal.

Scope

Please make a small docs-only update:

1. Update docs/browser-use-debugging.html with a short section or paragraph about local HTML upload filenames or attachment observations being mistaken for navigation targets.
2. Mention useful evidence fields:
   • task prompt and model-visible file/attachment context before step 0
   • local filename, extension, and MIME type when safe to log
   • raw model action before validation/security
   • parsed action type and URL or upload target
   • whether the bad URL was derived from the local filename or file contents
   • security/watchdog block reason and allowed-domains state
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 provider-specific logging implementation.
• No private prompt, credential, file-content, screenshot, or page-content examples.
• 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