Context

Issue #349 added a Browser Use guide section for a real upstream failure shape:

• External case: Bug: uploading an html file causes the agent to try to navigate to a web page browser-use/browser-use#4794
• BrowserTrace guide anchor: https://aaronlab.github.io/browsertrace/browser-use-debugging.html#debug-local-html-upload-navigation

The high-level failure-patterns page still does not mention this case, so people landing on the broader page may miss that BrowserTrace can help reason about local attachment metadata being misread as a navigation action.

Scope

Please make a small docs-only update:

1. Add one focused pattern to docs/browser-agent-failure-patterns.html for Browser Use local HTML upload navigation mistakes.
2. Link it to the existing Browser Use guide anchor above and the upstream community case.
3. Mention the useful trace evidence briefly:
   • task prompt and model-visible file or attachment context before step 0
   • local filename, extension, and MIME type when safe to log
   • raw model action before validation
   • parsed action type and bad URL or upload target
   • security/watchdog block reason and allowed-domains state
4. Add a small tests/test_metadata.py assertion so the failure-patterns page keeps this pattern and link.

Out of scope

• No Browser Use adapter code changes.
• No runtime behavior changes.
• No private prompt, file-content, screenshot, or page-content examples.
• No README rewrite.
• No star/upvote/repost requests.

Suggested verification

Run:

rg -n "local HTML|debug-local-html-upload-navigation|browser-use/browser-use/issues/4794" docs/browser-agent-failure-patterns.html docs/browser-use-debugging.html
uv run --python 3.11 --extra dev pytest tests/test_metadata.py -q
git diff --check

First PR Recipe

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