docs: add agent best practices to AGENTS.md

[mattbodle]

Background

• Agent sessions in this repo were following a long architecture dump without the operating rules that actually constrain changes (public API/snippet contract, gitflow base branch, PII, bundle size, test integrity).
• Ported the high-signal conventions from Rokt WSDK AGENTS.md and adapted them to this codebase.

What Has Changed

• Added web-specific agent rules at the top of AGENTS.md: ranked principles (security, compatibility, performance, clarity), no-comments default, readability prefer/over table, opportunistic-refactor + test-integrity rules, third-party embedding hard rules, P0/P1 review bar.
• Documented contracts that were missing or stale: PRs target development, snippet.js / snippet.rokt.js must stay in sync, do not hand-commit dist/, noDeviceId implies noFunctional + noTargeting, APV state lives on window.__mpApv__.
• Refreshed the architecture map for the current tree (pageViewTracker.ts, vault.ts, events.ts, public-types.ts / internal-types.ts, reporting/).
• Left the common (cross-SDK) section intact aside from using it as product context.

Screenshots/Video

• N/A (docs only)

Checklist

• Self-review completed
• Tests added or updated
• Tested locally

[cursor]

PR Summary

Low Risk
Documentation-only change to AGENTS.md; no runtime or API behavior is modified.

Overview
Replaces the long AGENTS.md architecture and cross-SDK guide (~550 lines) with a short agent playbook (~50 lines) tuned for AI sessions on this repo.

The new doc states product constraints up front (third-party embed, security, public API compatibility, CI gzip size vs master) and tells agents to discover commands/paths from the tree instead of maintaining catalogs in the file.

Hard rules cover forbidden patterns (eval, stray window.*, console.log), TypeScript-only new code, no hand-committed dist//CHANGELOG/versions, and feature PRs targeting development (not master).

A “Contracts the code will not tell you” section documents non-obvious invariants: snippet.js / snippet.rokt.js / stub sync for pre-load calls, type file split (public-types.ts vs internal-types.ts), identity callback + queueIfNotInitialized, Rokt noDeviceId implications, window.__mpApv__ for APV, vault.ts for storage, and PII-safe logging.

Tests guidance is trimmed to Jest vs Karma roles and when to run the full suite.

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

[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

[crisryantan]

Love the bias for action here. 🙏