docs: Revamp AGENTS.md with boundaries, skills index, and stack framing

Address #6638. Add the three high-value
sections the "great AGENTS.md" checklist calls for and that were missing:
a three-tier ✅/⚠️/🚫 Boundaries section, a Skills-load-on-demand index,
and a hybrid-SDK Stack framing that points at live version sources rather
than copying rot-prone version strings. Fix a drifted diagnostics example
(logger -> debug) and add a skill-precedence pointer in packages/core.

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

Author: antonis

AGENTS.md

@@ -1,11 +1,21 @@
 # AGENTS.md
 
-Sentry React Native SDK — monorepo using yarn workspaces with a single package at `packages/core`.
+Sentry React Native SDK — a **hybrid SDK**: a TypeScript/JS layer on top that wraps the native **sentry-cocoa** (iOS) and **sentry-android/java** SDKs through a JS↔native bridge. Monorepo using yarn workspaces; the SDK itself is the `packages/core` package.
+
+## Stack
+
+- **Published packages:** `@sentry/react-native` (`packages/core`, the SDK) + companion `@sentry/expo-upload-sourcemaps`; yarn 4 workspaces.
+- **Wraps native SDKs:** sentry-cocoa (iOS) + sentry-android/java (Android) through the JS↔native bridge.
+- **Hosts:** React Native on **both** the New (TurboModule/Fabric) and Old (bridge) Architecture, plus Expo and React.
+- **Exact versions** (don't copy them here — they rot): JS deps and host peer ranges in [`packages/core/package.json`](packages/core/package.json); the bundled native SDK versions per release in [`SDK-VERSIONS.md`](SDK-VERSIONS.md) (regenerated each release by `craft-pre-release.sh`).
+
+Changes to the wrapped native SDKs can ripple to them and to downstream hybrid SDKs (Flutter, .NET/MAUI, Unity) — see *Cross-Platform Dependencies*.
 
 ## Agent Responsibilities
 
-- **Continuous Learning**: Document new patterns in the appropriate nested `AGENTS.md` file.
-- **Context Management**: After compaction, re-read `AGENTS.md` files relevant to your current task.
+- **Reach for a skill first.** For anything beyond a trivial edit, load the matching skill (see *Skills*) — it carries the deep, current guidance this file only indexes.
+- **Continuous Learning:** when you discover a durable pattern, record it in the nearest nested `AGENTS.md` (or the relevant skill), not inline in a PR.
+- **Context Management:** after compaction, re-read the `AGENTS.md` for the surface you're touching before continuing.
 
 ## Setup
 
@@ -32,6 +42,26 @@ yarn build
 | ObjC/C++ lint | `yarn lint:clang` |
 | Swift lint | `yarn lint:swift` |
 
+## Boundaries
+
+**✅ Always**
+- Run `yarn lint`, `yarn test`, and `yarn circularDepCheck` before calling a change done; regenerate the API report (`yarn api-report`) when the public surface moved.
+- Make a change work on **both** architectures (New + Old) and **both** platforms (iOS + Android) — a fix that only covers one is not done.
+- Gate any user data placed in events/breadcrumbs/spans/logs on `options.sendDefaultPii`.
+- Catch native errors at the bridge boundary and degrade — reject/log, never let them propagate.
+
+**⚠️ Ask first**
+- Adding or changing any dependency, `.vscode` extension, GitHub Action, or native dependency — verify provenance first (load `code-guidelines` → *Adding dependencies*).
+- Changing the public API (`packages/core/src/js/index.ts` barrel, exported options) or a codegen/bridge spec (`NativeRNSentry.ts`, `*NativeComponent.ts`) — these are breaking and need a deprecation path.
+- Changing CI workflows, release config, or anything under `scripts/`.
+
+**🚫 Never**
+- Crash the host app — a native exception that reaches the app is the highest-severity failure this SDK can cause.
+- Break the public API or bridge ABI without a `@deprecated` migration path (an app can ship new JS against an older cached native binary).
+- Hand-edit generated files: `packages/core/etc/sentry-react-native.api.md` (regenerate it) or New-Architecture codegen output — regenerate, never edit by hand.
+- Add `CHANGELOG.md` noise for routine internal/CI/test/chore changes — the user-facing sections (`### Features`, `### Fixes`) are for user-visible changes. A genuinely notable internal change goes under the `### Internal` section instead, not among the user-facing entries.
+- Commit secrets, tokens, or DSNs.
+
 ## Commit Conventions
 
 Follow conventional commit format: `<type>(<scope>): <subject>`
@@ -99,6 +129,21 @@ Changes may impact downstream SDKs. Coordinate with other teams when modifying n
 - **Inline comments** for complex logic only
 - Update `CHANGELOG.md` for user-visible changes
 
+## Skills — load on demand
+
+The deep, task-specific guidance lives in `.agents/skills/` (registered in `agents.toml`) and is loaded when you need it — this file is the always-on operating manual, the skills are the specialists. Reach for one **before** doing the matching work:
+
+| Skill | Load it when |
+|-------|--------------|
+| `spec` | The *what* isn't pinned down yet — a fuzzy issue or idea to scope into acceptance criteria. Hands off to `design-first`. |
+| `design-first` | Starting a feature/integration, changing the public barrel, crossing the bridge, or changing a codegen spec — shape modules and seams before coding. |
+| `code-guidelines` | Implementing, refactoring, designing APIs, writing integrations, handling breaking changes, or adding dependencies. |
+| `test-guidelines` | Writing, modifying, or reviewing Jest tests, fixtures, and mocks. |
+| `review` | A three-axis (Standards / Spec / Correctness) pass on a branch or PR before opening or merging. |
+| `diagnosing-bugs` | A hard bug, flaky test, CI hang, native crash, or perf regression — builds a red-capable loop before hypothesizing. |
+
+Warden's automated PR review and `agents.toml` also pull **remote** specialists (`security-review`, `gha-security-review`, `span-convention-review`, and more) — invoke those for depth beyond the local pass.
+
 ## Nested AGENTS.md Files
 
 - [`packages/core/AGENTS.md`](packages/core/AGENTS.md) — TypeScript/JavaScript code style, testing, patterns

packages/core/AGENTS.md

@@ -1,5 +1,7 @@
 # packages/core — TypeScript/JavaScript SDK
 
+> **Depth lives in the skills.** The `code-guidelines` and `test-guidelines` skills (`.agents/skills/`) hold the authoritative, current guidance on code style, API/integration design, the bridge, and tests — load them before non-trivial work. This file covers the package's build/test commands, quick-reference conventions, and the **TurboModule subsystem**, which is documented nowhere else. Where a convention here overlaps a skill, the skill wins.
+
 ## Build & Test
 
 ```bash
@@ -95,14 +97,18 @@ describe('MyComponent', () => {
 
 ## Common Patterns
 
+> Diagnostics use **`debug`** from `@sentry/core`, not `logger` — `logger` is the Logs API and emits log *events* (and recurses in the bridge hot path). See *TurboModule Instrumentation* below.
+
 ### Error Handling
 
 ```typescript
+import { debug } from '@sentry/core';
+
 try {
   const result = await riskyOperation();
   return result;
 } catch (error) {
-  logger.error('Operation failed', error);
+  debug.error('Operation failed', error);
   // Don't throw - log and return fallback
   return fallbackValue;
 }
@@ -117,14 +123,14 @@ const { RNSentry } = NativeModules;
 
 export async function nativeOperation(param: string): Promise<boolean> {
   if (!RNSentry) {
-    logger.warn('Native module not available');
+    debug.warn('Native module not available');
     return false;
   }
 
   try {
     return await RNSentry.nativeOperation(param);
   } catch (error) {
-    logger.error('Native operation failed', error);
+    debug.error('Native operation failed', error);
     return false;
   }
 }