@@ -78,6 +78,14 @@ test -d .venv || make setupPython
 
 This starts the mock Sentry server, starts the sample app (Spring Boot/Tomcat/CLI), runs tests via `./gradlew :sentry-samples:<sample-module>:systemTest`, and cleans up afterwards.
 
+To run **every** system test instead of one module, use the Makefile targets — they also create the
+venv for you:
+
+```bash
+make systemTest             # all system tests (--all)
+make systemTestInteractive  # pick the setups to run (--interactive)
+```
+
 ## Step 4: Report Results
 
 Summarize the test outcome:
 
@@ -34,7 +34,7 @@ Public API is tracked via `.api` files generated by the [Binary Compatibility Va
 - `SentryAndroidOptions` — Android-specific options
 - Integration modules may add their own (e.g. `SentrySpringProperties`)
 
-New features must be **opt-in by default** — add a getter/setter pair to the appropriate options class.
+See the `options` rule for how to add and wire up a new option.
 
 ### Internal Classes (Not Public API)
 
 
@@ -12,7 +12,9 @@ This document outlines the complete process for adding a new module to the sentr
 
 ### 1. Create the Module Structure
 
-1. Create the new module, conforming to the existing naming conventions and build scripts
+1. Create the new module, conforming to the existing naming conventions and build scripts.
+   Copy the `build.gradle.kts` of the closest existing integration rather than writing one from
+   scratch — `sentry-kafka` is a good JVM template, `sentry-android-timber` a good Android one.
 
 2. Add the module to the include list in `settings.gradle.kts`
 
@@ -27,9 +29,36 @@ ignoredProjects.addAll(
 )
 ```
 
-3. If adding a JVM sample, add E2E (system) tests, following the structure we have in the existing JVM examples.
+3. Add a `SENTRY_{MODULE}_SDK_NAME` constant to the `Config.Sentry` block in
+   `buildSrc/src/main/java/Config.kt`:
+
+```kotlin
+val SENTRY_FOO_SDK_NAME = "$SENTRY_JAVA_SDK_NAME.foo"
+```
+
+The module's `build.gradle.kts` consumes it in both `buildConfig` and the jar manifest
+(`Sentry-SDK-Name` / `Sentry-SDK-Package-Name`) — see `sentry-kafka/build.gradle.kts`.
+
+4. Add the instrumented library to `gradle/libs.versions.toml` and depend on it with
+   `compileOnly(libs.<lib>)`, so the integration does not force the dependency on users.
+
+5. Register the integration with the SDK so it is reported in the `sdk` payload. Every
+   integration does this — see `sentry-openfeature/.../SentryOpenFeatureHook.java`:
+
+```java
+static {
+  SentryIntegrationPackageStorage.getInstance()
+      .addPackage("maven:io.sentry:sentry-{module-name}", BuildConfig.VERSION_NAME);
+}
+// then, from the constructor:
+addIntegrationToSdkVersion("{IntegrationName}");
+```
+
+6. If adding a JVM sample, add E2E (system) tests, following the structure we have in the existing JVM examples.
    The test should then be added to `test/system-test-runner.py` and `.github/workflows/system-tests-backend.yml`.
 
+`sentry-bom` and the root `build.gradle.kts` need no change — they iterate over subprojects.
+
 ### 2. Create Module Documentation
 
 Create a `README.md` in the module directory with the following structure:
@@ -46,22 +75,29 @@ The following tasks are required only when adding a module that isn't a sample.
 
 ### 3. Update Main README.md
 
-Add the new module to the packages table in the main `README.md` with a placeholder link to the badge:
+Add the new module to the packages table in the main `README.md`. Copy the row of a neighbouring
+module and swap the name — Android modules carry a third column for the min API level, JVM modules
+do not:
 
 ```markdown
-| sentry-{module-name} | [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-{module-name}/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.sentry/sentry-{module-name}) | |
+| sentry-{module-name} | [![Maven Central Version](https://img.shields.io/maven-central/v/io.sentry/sentry-{module-name}?style=for-the-badge&logo=sentry&color=green)](https://central.sonatype.com/artifact/io.sentry/sentry-{module-name}) |
 ```
 
 Note that the badge will only work after the module is released to Maven Central.
 
-### 4. Add Documentation to docs.sentry.io
+### 4. Add the Module to the Issue Template
+
+Add `- sentry-{module-name}` to the integrations dropdown in
+`.github/ISSUE_TEMPLATE/bug_report_java.yml`, or `bug_report_android.yml` for an Android module.
+
+### 5. Add Documentation to docs.sentry.io
 
 Add the necessary documentation to [docs.sentry.io](https://docs.sentry.io):
 - For Java modules: Add to Java platform docs, usually in integrations section
 - For Android modules: Add to Android platform docs, usually in integrations section
 - Include installation instructions, configuration options, and usage examples
 
-### 5. Post release tasks
+### 6. Post release tasks
 
 Remind the user to perform the following tasks after the module is merged and released:
 
@@ -79,10 +115,3 @@ Remind the user to perform the following tasks after the module is merged and re
 - Use kebab-case for module names: `sentry-{module-name}`
 - Follow existing patterns: `sentry-okhttp`, `sentry-apollo-4`, `sentry-spring-boot`
 - For version-specific modules, include the version: `sentry-apollo-3`, `sentry-apollo-4`
-
-## Important Notes
-
-1. **API Files**: Do not modify `.api` files manually. Run `./gradlew apiDump` to regenerate them
-2. **Backwards Compatibility**: Ensure new features are opt-in by default
-3. **Testing**: Write comprehensive tests for all new functionality
-4. **Documentation**: Always include proper documentation and examples
 
@@ -40,7 +40,6 @@ The project uses **Gradle** with Kotlin DSL. Key build files:
 
 ## Essential Commands
 
-### Development Workflow
 ```bash
 # Format code and regenerate .api files (REQUIRED before committing)
 ./gradlew spotlessApply apiDump
@@ -50,36 +49,14 @@ The project uses **Gradle** with Kotlin DSL. Key build files:
 
 # Generate documentation
 ./gradlew aggregateJavadocs
-```
-
-### Testing
-```bash
-# Run unit tests for a specific file
-./gradlew ':<module>:testReleaseUnitTest' --tests="*<file name>*" --info
-
-# Run system tests (requires Python virtual env)
-make systemTest
-
-# Run specific test suites
-./gradlew :sentry-android-core:testReleaseUnitTest
-./gradlew :sentry:test
-```
-
-### Code Quality
-```bash
-# Check code formatting
-./gradlew spotlessJavaCheck spotlessKotlinCheck
-
-# Apply code formatting
-./gradlew spotlessApply
-
-# Update API dump files (after API changes)
-./gradlew apiDump
 
 # Dependency updates check
 ./gradlew dependencyUpdates -Drevision=release
 ```
 
+To run tests, use the `test` skill rather than composing the Gradle invocation by hand — it
+resolves the per-module test task and the unit-test vs system-test split for you.
+
 ### Android-Specific Commands
 ```bash
 # Assemble Android test APKs
@@ -102,11 +79,9 @@ make systemTest
 
 ## Repository Skills
 
-This repo ships task-specific skills (declared in `agents.toml`, sources under `.agents/skills`). Prefer them over performing the steps manually:
-- **`create-java-pr`**: Branch, format, `apiDump`, commit, push, open PR, and add the changelog entry (automates the PR workflow above)
-- **`test`**: Run unit or system tests for a module or a specific class
-- **`check-code-attribution`**: Verify third-party code attribution on the current branch (see Third-Party Code Attribution below)
-- **`btrace-perfetto`**: Capture and compare Perfetto traces for Android performance work
+This repo ships task-specific skills, declared in `agents.toml` with sources under
+`.agents/skills`. Your harness already lists them with their descriptions — prefer them over
+performing the steps manually.
 
 ## Module Architecture
 
@@ -150,8 +125,8 @@ The repository is organized into multiple modules:
 
 ### Code Style
 - **Languages**: Java 8+ and Kotlin
-- **Formatting**: Enforced via Spotless - always run `./gradlew spotlessApply` before committing
-- **API Compatibility**: Binary compatibility is enforced - run `./gradlew apiDump` after API changes
+- **Formatting**: Enforced via Spotless
+- **API Compatibility**: Binary compatibility is enforced. `.api` files are generated, never hand-edited
 
 ### Exception Handling
 
@@ -189,10 +164,9 @@ PR description why the broad catch is necessary.
 
 ### Contributing Guidelines
 1. Follow existing code style and language
-2. Do not modify API files (e.g. sentry.api) manually - run `./gradlew apiDump` to regenerate them
-3. Write comprehensive tests
-4. New features must be **opt-in by default** - extend `SentryOptions` or similar Option classes with getters/setters
-5. Consider backwards compatibility
+2. Write comprehensive tests
+3. New features must be **opt-in by default** - extend `SentryOptions` or similar Option classes with getters/setters
+4. Consider backwards compatibility
 
 ### Third-Party Code Attribution
 When adapting code from third-party libraries: