refactor!: update dependency scope in extensions and improve documentation

- Changed Hadoop, Kafka, Avro, Schema Registry, and serialization libraries from `api` to `implementation` in `extensions` to limit their exposure to consuming projects.
- Updated `CONTRIBUTING.md` and user guide with guidelines for managing heavy client dependencies and clarifying compile/runtime usage implications.

Author: CoderYellow

CONTRIBUTING.md

@@ -34,6 +34,8 @@ Subprojects should declare Testcontainers modules without repeating the BOM. Ext
 
 When adding dependencies, keep them in the narrowest module that needs them. For example, Hadoop credential provider helpers belong in `extensions`, not `core`.
 
+Heavy client dependencies in `extensions`, such as Hadoop, Kafka, Avro, Schema Registry, and serialization libraries, should stay as `implementation` unless their types intentionally become part of the public API. This avoids pushing those libraries onto a user's compile classpath. Do not switch them to `api` just because an internal extension implementation imports them.
+
 ## Configuration Model
 
 Startup-time service configuration belongs to `@BigDataTest` and its TOML files. Examples include:

doc/user-guide.adoc

@@ -69,6 +69,10 @@ External consumers should import the same BOM in their own dependency-management
 * `org.testcontainers:testcontainers-junit-jupiter`
 * `org.testcontainers:testcontainers-postgresql`
 
+The `extensions` module keeps Hadoop, Kafka, Avro, Schema Registry, and serialization libraries as implementation dependencies. They are required at runtime for the built-in extensions, but they are not part of the extension module's compile API. This reduces compile-classpath conflicts for user applications that already use their own Hadoop or Kafka client versions.
+
+If an application needs to force its own runtime versions, use normal Gradle dependency constraints, platforms, or exclusions in the consuming build. Future extension modules can split these integrations further by feature so users can depend only on the extension families they need.
+
 == Programmatic Usage
 
 Use `BigDataTestKit.builder()` when you want direct lifecycle control.

extensions/build.gradle.kts

@@ -7,11 +7,11 @@ description = "Config-driven bigdata-test extensions for Hadoop credential provi
 
 dependencies {
     api(project(":junit5"))
-    api(libs.hadoopClientApi)
-    api(libs.hadoopClientRuntime)
-    api(libs.kafkaAvroSerializer)
-    api(libs.avro)
-    api(libs.kotlinxSerialization)
 
+    implementation(libs.hadoopClientApi)
+    implementation(libs.hadoopClientRuntime)
+    implementation(libs.kafkaAvroSerializer)
     implementation(libs.kafkaSchemaRegistryClient)
+    implementation(libs.avro)
+    implementation(libs.kotlinxSerialization)
 }