docs: document LavaMoat popover positioning issue

Root cause identified in commit ed02ac2
which updated lavamoat-core and modified policies, blocking @popperjs/core
DOM access needed for popover positioning in production builds.

Affects ALL popover components in GitHub Actions builds while working
correctly in local development and 13.5.0 branch builds.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: georgewrmarshall

LAVAMOAT_POPOVER_ISSUE.md

@@ -0,0 +1,46 @@
+# LavaMoat Popover Positioning Issue
+
+## Problem Description
+
+All popover components in the MetaMask extension fail to anchor properly to their reference elements in production builds from GitHub Actions, but work correctly in local development and 13.5.0 release builds.
+
+## Root Cause Analysis
+
+**Issue identified in commit:** `ed02ac23e86fc3a20336901a2bef52365cdd6bb1` ("fix: lavamoat patch")
+
+This commit:
+- Updated lavamoat-core from 16.2.2 to 16.7.1
+- Modified LavaMoat build-system policies
+- Is NOT present in 13.5.0 branch (explaining why it works)
+- IS present in main branch (explaining why it fails)
+
+## Technical Details
+
+### Console Error Evidence
+Production builds show "TypeError: e is not a function" in ui-14.js, indicating @popperjs/core functions are being blocked by LavaMoat policies.
+
+### Build System Impact
+- **Local webpack builds:** Work correctly (LavaMoat policies may be applied differently)
+- **GitHub Actions Gulp builds:** Fail due to stricter LavaMoat enforcement
+- **13.5.0 branch CI builds:** Work correctly (don't contain the problematic commit)
+
+### Affected Components
+ALL popover components are affected, including:
+- Global menu popover
+- Account menu popover
+- Network selector popover
+- Any component using @popperjs/core for positioning
+
+## Proposed Solution
+
+Review and update LavaMoat policies to allow @popperjs/core the necessary DOM access for:
+- `getBoundingClientRect()` calls
+- DOM positioning calculations
+- Element measurement operations
+
+The policies should maintain security while allowing legitimate positioning functionality.
+
+## Timeline
+- Issue started ~5 days ago from main branch
+- Commit ed02ac2 introduced the breaking change
+- 13.5.0 branch remains unaffected