chore: update version gated feature flag docs

[asalsys]

Description

Version-gated remote feature flags are evaluated in many places across the codebase, but guidance was scattered across team-specific docs and there was no single canonical pattern for agents and contributors to follow.

This PR centralizes that guidance:

1. New canonical guide — docs/readme/version-gated-feature-flags.md documents the SSOT (app/util/remoteFeatureFlag), the required selector pattern using validatedVersionGatedFeatureFlag, non-standard flag shapes, and forbidden duplicate helpers.
2. Cursor agent rule — .cursor/rules/version-gated-feature-flags.mdc enforces the same patterns for AI-assisted edits under app/**/*.{ts,tsx}.
3. Cross-doc updates — Perps, Predict, mUSD, and Compliance docs now link to the canonical guide and show correct import/usage examples instead of implying ad-hoc version checks.
4. Repo hygiene — .gitignore is updated to track *.mdc Cursor rules (matching the existing carve-out pattern for other IDE config), and AGENTS.md references the new guide in the development guidelines table and quick reference.

No runtime or selector code changes — documentation and agent guidance only.

Changelog

CHANGELOG entry: null

Related issues

Refs: fixes: MCWP-653

Manual testing steps

N/A — documentation-only change. Verified by reading rendered markdown links and confirming .cursor/rules/version-gated-feature-flags.mdc is tracked after the .gitignore carve-out.

Screenshots/Recordings

N/A — no UI changes.

Before

N/A

After

N/A

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

---

Note

Low Risk
Docs and agent guidance only; no runtime, selector, or feature-flag behavior changes.

Overview
Adds a canonical guide at docs/readme/version-gated-feature-flags.md and a matching Cursor rule (.cursor/rules/version-gated-feature-flags.mdc) so contributors and agents use validatedVersionGatedFeatureFlag from app/util/remoteFeatureFlag in selectors instead of duplicating version checks.

Cross-links and examples in Perps, Predict, mUSD, and Compliance docs now point at that guide and show the shared import pattern. AGENTS.md adds the guide to the dev guidelines table and quick reference.

.gitignore is adjusted so tracked *.mdc rules under .cursor/rules/ can be committed (carve-out for IDE config). No app or selector code changes.

^{Reviewed by Cursor Bugbot for commit 0388626. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[metamask-ci]

PR template — items to address before "Ready for review"

Warnings — informational, address before merging:

• Pre-merge author checklist has unchecked items (e.g. "I've tested on Android"). Every box must be consciously checked — see docs/readme/ready-for-review.md.

See docs/readme/ready-for-review.md for the full Definition of Ready for Review.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: None (no tests recommended)
• Selected Performance tags: None (no tests recommended)
• Risk Level: low
• AI Confidence: 99%

click to see 🤖 AI reasoning details

E2E Test Selection:
All 9 changed files are purely documentation and developer tooling configuration:

1. .gitignore - Minor pattern update to allow .cursor/rules/*.mdc files to be tracked (no functional impact)
2. AGENTS.md - Documentation update adding a reference to version-gated feature flags guide
3. .cursor/rules/version-gated-feature-flags.mdc - Cursor IDE rules file (developer tooling only)
4. docs/compliance.md, docs/musd/musd-convert-list.md, docs/perps/perps-feature-flags.md, docs/predict/live-nfl-architecture.md, docs/predict/tasks/00-feature-flag-and-types.md, docs/readme/version-gated-feature-flags.md - All documentation files

None of these changes touch application code, test infrastructure, controllers, UI components, navigation, or any functional behavior. No E2E tests are needed.

Performance Test Selection:
All changes are documentation and developer tooling configuration files. No application code was modified, so there is no performance impact whatsoever. No performance tests are needed.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud