Context

docs/browser-agent-failure-patterns.html is the broad page we can share when someone asks which AI browser-agent failures BrowserTrace helps debug. The stack-specific guides already have stable anchors such as:

• browser-use-debugging.html#debug-remote-cdp-hangs
• stagehand-debugging.html#debug-semantic-verification-boundaries
• skyvern-debugging.html#debug-vnc-and-cdp-evidence-together
• playwright-llm-debugging.html#keep-browser-artifacts-out-of-long-term-model-context

The high-level failure-patterns page still has plain <h2> headings. That means external replies, launch notes, and directory maintainers can only link to the whole page instead of the exact pattern.

Scope

Please make a small docs-only update:

1. Add stable id anchors to each failure pattern heading in docs/browser-agent-failure-patterns.html.
2. Use short, descriptive ids that match the existing guide anchor style where possible, for example:
   • debug-icon-only-click-targets
   • debug-remote-cdp-hangs
   • debug-stagehand-semantic-verification-boundary
   • debug-skyvern-vnc-cdp-integration
3. Add a small tests/test_metadata.py assertion that checks at least a few representative anchors exist.
4. Do not change the page copy unless needed for the anchors.

Out of scope

• No runtime code changes.
• No homepage redesign.
• No new failure-pattern content.
• No external posting or asking anyone for stars/upvotes.

Suggested verification

Run:

rg -n "<h2 id=\"debug-" docs/browser-agent-failure-patterns.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 HTML file plus one focused metadata test is enough.
See the First PR Recipe:
https://github.com/aaronlab/browsertrace/blob/main/CONTRIBUTING.md#first-pr-recipe