Add more AI rules

.cursor/rules/deduplication.mdc

@@ -0,0 +1,13 @@
+---
+alwaysApply: false
+description: Java SDK Event deduplication
+---
+
+# Java SDK Event deduplication
+
+To avoid sending the same error multiple times, there is deduplication logic in place in the SDK.
+Duplicate captures can happen due to multiple integrations capturing the exception as well as additional manual calls to `Sentry.captureException`.
+
+Deduplication is performed in `DuplicateEventDetectionEventProcessor` which returns `null` when it detects a duplicate event causing it to be dropped.
+
+The `enableDeduplication` option can be used to opt out of deduplication. It is enabled by default.

.cursor/rules/e2e_tests.mdc

@@ -0,0 +1,28 @@
+---
+alwaysApply: false
+description: Java SDK End to End Tests
+---
+
+# Java SDK End to End Tests (System Tests)
+
+The samples in the `sentry-samples` directory are used to run end to end tests against them.
+
+There is a python script (`system-test-runner.py`) that can be used to run one (using `--module SAMPLE_NAME`) or all (using `--all`) system tests.
+
+The script has an interactive mode (`-i`) which allows selection of test setups to execute, whether to run the tests or just prepare infrastructure for testing from IDE.
+
+The tests run a mock Sentry server via `system-test-sentry-server.py`. Any system under test will then have a DSN set that reflects this local mock server like `http://502f25099c204a2fbf4cb16edc5975d1@localhost:8000/0`.
+By using this local DSN, the system under test sends events to the local mock server.
+The tests can then use `TestHelper` to assert envelopes that were received by the mock server.
+`TestHelper` uses HTTP requests to retrieve the JSON payload of the received events and deserialize them back to objects for easier assertion.
+Tests can then assert events, transactions, logs etc. similar to how they would appear in `beforeSend` and similar callbacks.
+
+`TestHelper` has a lot of helper methods for asserting, e.g. by span name, log body etc.
+
+The end to end tests either expect the system under test to either be running on a server or call `java -jar` to execute a CLI system under test.
+
+For Spring Boot, we spin up the Spring Boot server. The tests then send requests to that server and assert what is sent to Sentry.
+
+End to end tests are also executed on CI using a matrix build, as defined in `.github/workflows/system-tests-backend.yml`.
+
+Some of the samples are tested in multiple ways, e.g. with OpenTelemetry Agent auto init turned on and off.

.cursor/rules/overview_dev.mdc

@@ -0,0 +1,62 @@
+---
+alwaysApply: true
+description: Sentry Java SDK - Development Rules Overview
+---
+
+# Sentry Java SDK Development Rules
+
+## Always Applied Rules
+
+These rules are automatically included in every conversation:
+- **coding.mdc**: General contributing guidelines, build commands, and workflow rules
+
+## Domain-Specific Rules (Fetch Only When Needed)
+
+Use the `fetch_rules` tool to include these rules when working on specific areas:
+
+### Core SDK Functionality
+- **`scopes`**: Use when working with:
+  - Hub/Scope management, forking, or lifecycle
+  - `Sentry.getCurrentScopes()`, `pushScope()`, `withScope()` 
+  - `ScopeType` (GLOBAL, ISOLATION, CURRENT)
+  - Thread-local storage, scope bleeding issues
+  - Migration from Hub API (v7 → v8)
+
+- **`deduplication`**: Use when working with:
+  - Duplicate event detection/prevention
+  - `DuplicateEventDetectionEventProcessor`
+  - `enableDeduplication` option
+
+- **`offline`**: Use when working with:
+  - Caching, envelope storage/retrieval
+  - Network failure handling, retry logic
+  - `AsyncHttpTransport`, `EnvelopeCache`
+  - Rate limiting, cache rotation
+  - Android vs JVM caching differences
+
+### Integration & Infrastructure
+- **`opentelemetry`**: Use when working with:
+  - OpenTelemetry modules (`sentry-opentelemetry-*`)
+  - Agent vs agentless configurations
+  - Span processing, sampling, context propagation
+  - `OtelSpanFactory`, `SentrySpanExporter`
+  - Tracing, distributed tracing
+
+### Testing
+- **`e2e_tests`**: Use when working with:
+  - System tests, sample applications
+  - `system-test-runner.py`, mock Sentry server
+  - End-to-end test infrastructure
+  - CI system test workflows
+
+## Usage Guidelines
+
+1. **Start minimal**: Only include `coding.mdc` (auto-applied) for general tasks
+2. **Fetch on-demand**: Use `fetch_rules ["rule_name"]` when you identify specific domain work
+3. **Multiple rules**: Fetch multiple rules if task spans domains (e.g., `["scopes", "opentelemetry"]` for tracing scope issues)
+4. **Context clues**: Look for these keywords in requests to determine relevant rules:
+   - Scope/Hub/forking → `scopes`
+   - Duplicate/dedup → `deduplication` 
+   - OpenTelemetry/tracing/spans → `opentelemetry`
+   - Cache/offline/network → `offline`
+   - System test/e2e/sample → `e2e_tests`

.cursor/rules/scopes.mdc

@@ -0,0 +1,112 @@
+---
+alwaysApply: false
+description: Java SDK Hubs and Scopes
+---
+# Java SDK Hubs and Scopes
+
+## `Scopes`
+
+`Scopes` implements `IScopes` and manages three `Scope` instances, `global`, `isolation` and `current` scope.
+For some data, all three `Scope` instances are combined, for others, a certain one is used exclusively and for some we look at each scope in a certain order and use the data of the first scope that has the data set. This logic is contained in `CombinedScopeView`.
+Data itself is stored on `Scope` instances.
+`Scopes` also has a `parent` field, linking the `Scopes` it was forked off of and a `creator` String, explaining why it was forked.
+
+## `Hub`
+
+Up until major version 7 of the Java SDK the `IHub` interface was a central part of the SDK.
+In major version 8 we replaced the `IHub` interface with `IScopes`. `IHub` has been deprecated.
+While there is some bridging code in place to allow for easier migration, we are planning to remove it in an upcoming major.
+
+## Scope Types
+
+We have introduced some new Scope types in the SDK, allowing for better control over what data is attached where.
+Previously there was a stack of scopes that was pushed and popped.
+Instead we now fork scopes for a given lifecycle and then restore the previous scopes.
+Since Hub is gone, it is also never cloned anymore.
+Separation of data now happens through the different scope types while making it easier to manipulate exactly what you need without having to attach data at the right time to have it apply where wanted.
+
+### Global Scope
+
+Global scope is attached to all events created by the SDK.
+It can also be modified before Sentry.init has been called.
+It can be manipulated using `Sentry.configureScope(ScopeType.GLOBAL, (scope) -> { ... })`.
+
+Global scope can be retrieved from `Scopes` via `getGlobalScope`. It can also be retrieved directly via `Sentry.getGlobalScope`.
+
+### Isolation Scope
+
+Isolation scope can be used e.g. to attach data to all events that come up while handling an incoming request.
+It can also be used for other isolation purposes.
+It can be manipulated using `Sentry.configureScope(ScopeType.ISOLATION, (scope) -> { ... })`.
+The SDK automatically forks isolation scope in certain cases like incoming requests, CRON jobs, Spring `@Async` and more.
+
+Isolation scope can be retrieved from `Scopes` via `getIsolationScope`.
+
+### Current scope
+
+Current scope is forked often and data added to it is only added to events that are created while this scope is active.
+Data is also passed on to newly forked child scopes but not to parents.
+
+Current scope can be retrieved from `Scopes` via `getScope`.
+
+## Storage of `Scopes`
+
+`Scopes` are stored in a `ThreadLocal` by default (NOTE: this is different for OpenTelemetry, see opentelemetry.mdc).
+This happens through `Sentry.scopesStorage` and `DefaultScopesStorage`.
+
+The lifetime of `Scopes` in the thread local is managed by `ISentryLifecycleToken`.
+When the scopes are forked, they are stored into the `ThreadLocal` and a `ISentryLifecycleToken` is returned.
+When the `Scopes` are no longer needed, e.g. because a request is finished, `ISentryLifecycleToken.close` can be called to restore the previous state of the `ThreadLocal`.
+
+## Old versions of the Java SDK
+
+There were several implementations of the `IHub` interface:
+- `Hub` managed a stack of `Scope` instances, which were pushed and popped.
+- A `Hub` could be cloned, meaning there could be multiple stacks of scopes active, e.g. for two separate requests being handled in a server application.
+
+### Migrating to major version 8 of the SDK
+
+`IHub` has been replaced by `IScopes`
+`HubAdapter` has been replaced by `ScopesAdapter`
+`Hub.clone` should be replaced by using `pushScope` or `pushIsolationScope`
+`Sentry.getCurrentHub` has been replaced by `Sentry.getCurrentScopes`
+`Sentry.popScope` has been deprecated. Instead `close` should be called on the `ISentryLifecycleToken` returned e.g. by `pushScope`. This can also be done in a `try-with-resource` block.
+
+## `globalHubMode`
+The SDK has a `globalHubMode` option which affects forking behaviour of the SDK.
+
+Android has `globalHubMode` enabled by default.
+For JVM Desktop applications, `globalHubMode` can be used.
+For JVM Backend applications (servers) we discourage enabling `globalHubMode` since it will cause scopes to bleed into each other. This can e.g. mean that state from request A leaks into request B and events sent to Sentry contain a mix of both request A and B potentially rendering the data useless.
+
+### Enabled
+
+If `globalHubMode` is enabled, the SDK avoids forking scopes.
+
+This means, retrieving current scopes on a thread where specific scopes do not exist yet for the thread, the root scopes are not forked but returned directly.
+The SDK also doesn't fork scopes when `Sentry.pushScope`, `Sentry.pushIsolation`, `Sentry.withScope` or `Sentry.withIsolationScope` are executed.
+
+The suppression of forking via `globalHubMode` only applies when using `Sentry` static API or `ScopesAdapter`.
+In case the `Scopes` instance is accessed directly, forking will happen as if `globalHubMode` is disabled.
+However, while it's possible to use `Sentry.setCurrentScopes` it does not have any effect due to `Sentry.getCurrentScopes` directly returning `rootScopes` if `globalHubMode` is enabled.
+This means the forked scopes have to be managed manually, e.g. by keeping a reference and accessing Sentry API via the reference instead of using static API.
+
+`ScopesAdapter` makes use of the static `Sentry` API internally. It allows us to access the correct scopes for the current context without passing it along explicitly. It also makes testing easier.
+
+### Disabled
+
+If `globalHubMode` is disabled, the SDK forks scopes freely, e.g. when:
+- `Sentry.getCurrentScopes()` is executed on a Thread where no specific scopes for that thread have been stored yet. In this case the SDK will fork `rootScopes` (stored in a `Sentry` static property).
+- `withScope` or `withIsolationScope` are executed
+- `pushScope` or `pushIsolationScope` are executed
+
+## `defaultScopeType`
+
+The `defaultScopeType` controls which `Scope` instance is being used for writing to and reading from as a default value.
+When using API like `Sentry.setTag` the SDK adds that tag to the default `Scope`.
+
+This also ensures, customers who migrate to the latest SDK version and already have `Sentry.configureScope` invocations in place, will now write to the default `Scope` instance that was chosen.
+
+The default value for `defaultScopeType` is `ISOLATION` scope for JVM and `CURRENT` scope for Android.
+
+Which fields are written/read from/to `defaultScopeType` is controlled in `CombinedScopeView`.